ceejay.fieldMap

Read a game's field map, and propose to it.

A game sends values and events under its own names. The field map says which of those names the community has accepted, and what each one is: see Players for the requests that send them. A name is accepted by a person on the community's team. A key reads the map and proposes to it, and cannot approve its own map.

Every function takes the same last argument, options: signal, timeoutMs and maxRetries, for that one call. 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.

Before you start

• The game is set up for the community first, and gets a slug. Both functions take it as their first argument, game.
• The key needs players:read to read the map and players:write to propose to it. A key with every permission (*) has both.
• The rate limit is the key's own limit of requests per minute.
• No idempotency key. Neither takes one. ceejay.fieldMap.propose is not retried automatically by the SDK. Retrying it yourself is safe: a name that has already been proposed is matched to the existing entry, not duplicated.

ceejay.fieldMap.get

Reads the field map of a game: every field and event it sends, with the state of each. It contains no player data.

GET /v1/games/{game}/field-map · requires players:read · API reference: Get the field map

Retried by the SDK: Yes. It is a read

Takes the game, then options.

Returns the map, typed as Schemas['FieldMap'].

The state of an entry is proposed (waiting for the team), approved (values are written) or unused (the team marked it as unused). The type of a field is text, number, date, choice, yes_no or ordered, and never changes once the field is approved. The category is progress, purchases or location. A sensitive field is marked, and never returned with a player.

Errors

A paused game can still be read.

Example

const map = await ceejay.fieldMap.get('rugby_manager')

const waiting = map.fields.filter((field) => field.state === 'proposed')
console.log(waiting.map((field) => field.sourceKey), map.limits.ownFields, map.limits.events)

ceejay.fieldMap.propose

Tells CEEJAY which fields and events your game sends, before it sends them, so the community can approve them first.

POST /v1/games/{game}/field-map/propose · requires players:write · API reference: Propose to the field map

Retried by the SDK: No. Retrying it yourself is safe: a name that has already been proposed is matched to the existing entry

Takes the game, one object, then options.

Send at least one field or event. The proposal is made by fixed rules and no player value leaves CEEJAY: a name that is a known alias of a standard field becomes that field, true and false are yes or no, a number is a number, text that reads as a date is a date, and a name that ends in _cents proposes a scale of 0.01.

Returns the proposal, typed as Schemas['ProposeFieldMapResult'].

Errors

A request body that names no field and no event, or an entry that cannot be parsed, is a bad_request whose body names the offending field, such as fields.type.

Example

const proposal = await ceejay.fieldMap.propose('rugby_manager', {
  sample: {
    fields: { league_position: 3, club: 'Harbour Town', coins_spent_cents: 12900 },
    events: ['match_won', 'cup_entered'],
  },
  fields: [{ sourceKey: 'lvl', standard: 'std.level' }],
})

console.log(proposal.fields.map((field) => `${field.key}: ${field.state}`))
console.log(proposal.skipped.map((skip) => `${skip.sourceKey}: ${skip.reason}`))