ceejay.members

Every function takes the same last argument, options: signal, timeoutMs and maxRetries, for that one call. A write also takes idempotencyKey there. Every function can also raise the errors any request can raise, such as a bad key or the rate limit. Both are on Errors and retries.

ceejay.members.get

Gets one member: their profile, XP and level, currency and linked accounts, in one call.

GET /v1/members/{discordId} · requires members:read · API reference: Get a member

Retried by the SDK: Yes. It is a read

Takes

Returns the member, typed as Schemas['Member'].

Each linked account also carries playerId and playerName under their legacy names, platformUserId and platformUsername. They contain the same values and are still returned.

proof indicates how far a game's playerId can be trusted. It is 'verified' when the player was proven (by the game, or by your own server linking it), 'basic' when the member connected through Connect with a player ID the game only stated, and null for an account that is not a connection to a game. Anyone with the public key a game ships with can claim any ID, so do not grant a member rewards for a 'basic' connection.

Errors

An ID that is not a string of 17 to 20 digits never leaves your server: the SDK throws a TypeError before it sends anything.

Example

import { CeejayError } from '@communitystudios/ceejay'

try {
  const member = await ceejay.members.get('409876543210987654')
  console.log(member.displayName, member.xp, member.level)
  for (const account of member.connections) {
    console.log(account.platform, account.playerId, account.playerName)
  }
} catch (error) {
  if (error instanceof CeejayError && error.code === 'member_not_found') {
    console.log('CEEJAY has not seen this member yet')
  } else {
    throw error
  }
}

ceejay.members.link

Links a member's account in your game, or on another platform such as Twitch, Steam or Roblox, to their Discord ID. Activity on your platform can then be tied to the community member.

POST /v1/members/link · requires members:link · API reference: Link an account

Retried by the SDK: Only with idempotencyKey. Retrying it yourself is safe too: linking the same platform for the same member again updates the link

Takes one object, then options.

Options

The API also accepts playerId and playerName under their legacy names, platformUserId and platformUsername, from code that calls it without the SDK. The SDK sends the names in the table.

The member must be in your server. An ID CEEJAY has no profile for is looked up in Discord first. A member who has only just joined can take up to 15 seconds to be found: after a member_not_found for such a member, wait 15 seconds before you retry.

Returns the link, typed as Schemas['LinkedAccount'].

The response also carries the link under legacy names, which are still returned: id (the same as connectionId, as a number), server_id, user_id (the same as discordId), platform_user_id, platform_username, is_active and connected_at.

Errors

A platform that is a game. On an instance that offers Connect, a game that is set up for your community is a platform too: pass its slug as platform. The link is then a game connection at the verified level, because your server vouches for it, and the member is shown no page for it. To let the member confirm the link themselves, use the functions on Connect. For a game, the call can also fail with:

A connection the member made themselves through Connect is protected like a sign-in: a call that names another playerId is rejected with linked_by_sign_in.

Nothing is changed when a link is rejected. Errors about an idempotency key are described on Errors and retries.

Example

import { CeejayError } from '@communitystudios/ceejay'

try {
  const link = await ceejay.members.link(
    {
      discordId: '409876543210987654',
      platform: 'steam',
      playerId: '76561198012345678',
      playerName: 'nova',
    },
    { idempotencyKey: 'link-steam-76561198012345678' },
  )
  console.log(link.platform, link.playerId, link.connectedAt)
} catch (error) {
  if (error instanceof CeejayError && error.code === 'player_already_linked') {
    console.log('That Steam account belongs to another member')
  } else {
    throw error
  }
}