Buzz API

Sometimes in the Buzz API, you'll come across a user ID that may actually represent two values: one for the user performing the proxy (agent) and one for the proxied (student) user. This happens because the full ID is stored as a 64‑bit number. The trick is that if the number fits within 32 bits (i.e., it's less than 4,294,967,296), then it represents a single user ID. But if it’s 64‑bit (equal to or greater than 4,294,967,296), it’s actually a composite value with the top 32 bits holding the agents’s ID and the lower 32 bits holding the proxied user’s ID.

Why do we need to do this?
This conversion is important when you're working with proxied sessions or performing operations that depend on knowing both the agent (proxy) user and the proxied user. By splitting the 64‑bit number into two parts, you ensure that your application correctly identifies who performed the proxy action and on whose behalf.

How can you tell the difference and perform the conversion?
You can simply check whether the ID is less than 2³² (4,294,967,296). If it is, then it's a single user ID and no further conversion is necessary. Otherwise, if the ID is 64‑bit, you can use bitwise operations to extract the two IDs:

• Agent (proxy) user ID: Shift the number right by 32 bits.
• Proxied (student) user ID: Use a bitmask to retrieve the lower 32 bits.

Below is a JavaScript example using BigInt (to handle large numbers safely):

function processID(idInput) {
  // Convert input to BigInt to safely handle large numbers.
  let id = BigInt(idInput);
  const two32 = BigInt(4294967296); // 2^32

  if (id < two32) {
    // The value fits in 32 bits: it's a single user ID.
    return {
      type: 'single',
      userId: id.toString()
    };
  } else {
    // The value is 64-bit: it encodes two user IDs.
    // The agent (proxy) user ID is stored in the top 32 bits.
    const agentId = id >> BigInt(32);
    // The proxied user ID is stored in the bottom 32 bits.
    const userId = id & (two32 - BigInt(1));
    return {
      type: 'composite',
      agentId: agentId.toString(),
      userId: userId.toString()
    };
  }
}

// Example usage:
console.log(processID("46287217"));
// Output: { type: 'single', userId: '46287217' }

console.log(processID("308202919021450050"));
// Output: { type: 'composite', agentId: '71759084', userId: '50533186' }

This snippet first converts the input into a BigInt to handle numbers larger than 32 bits safely. It then checks if the value is less than 2³². If yes, it returns the number as is; if not, it extracts the agent and proxied user IDs using bitwise operations.

I hope this helps clarify the process and makes it easier for you to work with these user IDs!