@indiegems/gem-web-sdk 7.3.1 → 7.4.1

package/docs/api/api-reference-server.md

@@ -0,0 +1,4397 @@
+# The server surface — API reference
+
+Generated from `@indiegems/gem-web-sdk/sdk` v7.4.1. Every symbol below links to its page on the Gem Arcade developer site.
+
+`@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
+
+```js
+import { defineServer } from '@indiegems/gem-web-sdk/sdk';
+```
+
+One dependency covers both halves of a game, and it is written out in [getting-started](https://gemarcade.com/developer/docs/getting-started#3-add-the-sdk) — the only place it is written out, so there is one copy to keep current. It is a public download needing no account and no credential, it goes in `dependencies`, and nothing is built on install. If you followed that page, the server entry is already installed.
+
+## AnalyticsValue
+
+[AnalyticsValue](https://gemarcade.com/developer/api/server#analyticsvalue)
+
+```ts
+type AnalyticsValue = string | number
+```
+
+A value attached to an event.
+
+A **string** is a dimension and a **number** is a measure, and which one a
+key is was decided in your game config, not here. Dimensions are closed sets
+declared ahead of time — that is the whole reason there is no free-text
+property — and measures are the numbers the platform sums, averages and
+takes the min and max of.
+
+## AnalyticsRejection
+
+[AnalyticsRejection](https://gemarcade.com/developer/api/server#analyticsrejection)
+
+```ts
+interface AnalyticsRejection
+```
+
+One event the platform refused, inside an otherwise fine batch.
+
+## AnalyticsRejection.index
+
+[AnalyticsRejection.index](https://gemarcade.com/developer/api/server#analyticsrejection-index)
+
+```ts
+readonly index: number
+```
+
+Which event was refused, as an index into the batch that was sent.
+
+⚠️ NOT an index into anything you hold. The SDK batches on its own
+schedule, so this is only meaningful beside the code — which is the part
+worth acting on.
+
+## AnalyticsRejection.code
+
+[AnalyticsRejection.code](https://gemarcade.com/developer/api/server#analyticsrejection-code)
+
+```ts
+readonly code: string
+```
+
+A stable snake_case code. Read the code, never the prose.
+
+`analytics_not_declared` (this channel resolves no `analytics_events`
+section at all — promote a config that has one), `unknown_event` (the
+channel declares a set and this name is not in it), `unknown_dimension`,
+`missing_dimension`, `dimension_value_not_declared`, `unknown_measure`,
+`measure_wrong_type`, `source_not_permitted`.
+
+## AnalyticsFlushResult
+
+[AnalyticsFlushResult](https://gemarcade.com/developer/api/server#analyticsflushresult)
+
+```ts
+interface AnalyticsFlushResult
+```
+
+What `AnalyticsApi.flush` resolves with.
+
+## AnalyticsFlushResult.accepted
+
+[AnalyticsFlushResult.accepted](https://gemarcade.com/developer/api/server#analyticsflushresult-accepted)
+
+```ts
+readonly accepted: number
+```
+
+How many events the platform accepted and wrote.
+
+## AnalyticsFlushResult.rejected
+
+[AnalyticsFlushResult.rejected](https://gemarcade.com/developer/api/server#analyticsflushresult-rejected)
+
+```ts
+readonly rejected: readonly AnalyticsRejection[]
+```
+
+Every event the platform refused, by index into the batch that was sent.
+
+⚠️ REJECTIONS ARRIVE INSIDE A 200, never as a thrown error, and the
+accepted events in the same batch were still written. An empty array is
+the ordinary case.
+
+## AnalyticsFlushResult.dropped
+
+[AnalyticsFlushResult.dropped](https://gemarcade.com/developer/api/server#analyticsflushresult-dropped)
+
+```ts
+readonly dropped: number
+```
+
+How many events the local queue threw away since the last successful
+flush, because it was full. The oldest go first.
+
+A number worth alarming on: it is nonzero only when the game is producing
+events faster than the platform accepts them.
+
+## AnalyticsFlushResult.duplicate
+
+[AnalyticsFlushResult.duplicate](https://gemarcade.com/developer/api/server#analyticsflushresult-duplicate)
+
+```ts
+readonly duplicate: boolean
+```
+
+True when the platform had already seen this batch and wrote nothing.
+
+A retry that the first attempt had in fact delivered. Not an error — it is
+what stops a flush racing a `pagehide` from being counted twice — and
+`accepted` is 0 on one.
+
+## Base64String
+
+[Base64String](https://gemarcade.com/developer/api/server#base64string)
+
+```ts
+type Base64String = string & { __contentEncoding: "base64" }
+```
+
+A base64-encoded value — a `string`, but not one you can substitute an
+ordinary string for.
+
+Some platform fields carry BYTES inside a JSON string, encoded as base64. An
+entity setting's `value` is the one you are most likely to meet. Passing
+ordinary text there fails the whole request, and it fails at runtime, on the
+server, after you shipped.
+
+This type moves that failure to your build. `{ value: JSON.stringify(state) }`
+type-checks perfectly against `string` and is exactly the mistake being
+stopped.
+
+MAKE ONE WITH [toBase64](https://gemarcade.com/developer/api/server#tobase64). Writing `as Base64String` instead silences the
+error and puts the trap back.
+
+## toBase64
+
+[toBase64](https://gemarcade.com/developer/api/server#tobase64)
+
+```ts
+function toBase64(value: string | Uint8Array<ArrayBufferLike>): Base64String
+```
+
+Encode text or bytes for a field that wants base64.
+
+The only way to produce a [Base64String](https://gemarcade.com/developer/api/server#base64string), and the reason not to reach
+for `btoa` yourself: `btoa` takes a *binary* string and throws on any
+character above U+00FF, so `btoa(name)` works all through your testing and
+then fails on the first player whose display name is not Latin-1. This
+encodes a string as UTF-8 first.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `string \| Uint8Array<ArrayBufferLike>` | Text, or bytes you already have. |
+
+**Returns.** The encoded value, typed so the field will accept it.
+
+```js
+await gem.api.putEntityGameSetting('loadout', {
+  value: toBase64(JSON.stringify(loadout)),
+});
+```
+
+## GemErrorReason
+
+[GemErrorReason](https://gemarcade.com/developer/api/server#gemerrorreason)
+
+```ts
+type GemErrorReason = "invalid" | "forbidden" | "not_found" | "conflict" | "precondition_failed" | "not_modified" | "insufficient_funds" | "too_large" | "rate_limited" | "unavailable"
+```
+
+What went wrong, in terms you can act on.
+
+BRANCH ON THIS, not on the HTTP status — one status covers several distinct
+refusals, and the reason is what tells them apart. It is carried by
+[GemApiError.reason](https://gemarcade.com/developer/api/server#gemapierror-reason).
+
+## GemApiError
+
+[GemApiError](https://gemarcade.com/developer/api/server#gemapierror)
+
+```ts
+class GemApiError
+```
+
+A refusal from the Gem Arcade backend. Any call that reaches the platform can
+throw one.
+
+You catch this; you never construct it. Branch on [GemApiError.reason](https://gemarcade.com/developer/api/server#gemapierror-reason)
+for what went wrong and [GemApiError.retryable](https://gemarcade.com/developer/api/server#gemapierror-retryable) for whether another
+attempt could help — not on [GemApiError.status](https://gemarcade.com/developer/api/server#gemapierror-status), because one status
+covers several distinct refusals.
+
+```js
+try {
+  await somePlatformCall();
+} catch (err) {
+  if (err instanceof GemApiError && err.retryable) {
+    const wait = err.retryAfterSeconds ?? 1;
+    // try again after `wait` seconds
+  } else {
+    throw err;
+  }
+}
+```
+
+## GemApiError.reason
+
+[GemApiError.reason](https://gemarcade.com/developer/api/server#gemapierror-reason)
+
+```ts
+readonly reason: GemErrorReason
+```
+
+What went wrong, in terms you can act on — `invalid`, `forbidden`,
+`not_found`, `conflict`, `precondition_failed`, `not_modified`,
+`insufficient_funds`, `too_large`, `rate_limited` or `unavailable`.
+
+This is the field to branch on. Two refusals can share a status and mean
+different things; they do not share a reason.
+
+## GemApiError.status
+
+[GemApiError.status](https://gemarcade.com/developer/api/server#gemapierror-status)
+
+```ts
+readonly status: number
+```
+
+The HTTP status the server answered with.
+
+Carried for logs and bug reports. Prefer [GemApiError.reason](https://gemarcade.com/developer/api/server#gemapierror-reason) for
+decisions: several distinct refusals map onto one status, so branching
+here treats different problems as the same one.
+
+## GemApiError.detail
+
+[GemApiError.detail](https://gemarcade.com/developer/api/server#gemapierror-detail)
+
+```ts
+readonly detail: string
+```
+
+The server's own sentence, without the `reason (status):` prefix that
+`message` carries.
+
+Use this when you want to quote the platform — in a log line, or a bug
+report. It is not written for players, so do not put it on screen.
+
+## GemApiError.retryAfterSeconds
+
+[GemApiError.retryAfterSeconds](https://gemarcade.com/developer/api/server#gemapierror-retryafterseconds)
+
+```ts
+readonly retryAfterSeconds?: number
+```
+
+How long the server asked you to wait, in whole seconds.
+
+ABSENT MEANS "NO ESTIMATE GIVEN", NEVER "DO NOT RETRY" —
+[GemApiError.retryable](https://gemarcade.com/developer/api/server#gemapierror-retryable) is what answers that. A refusal can be
+worth repeating and still name no wait, so treat absence as "pick your
+own backoff" rather than as a stop signal. The platform estimates a wait
+for capacity and for rate limits, and sends none for the refusals it
+cannot put a number on.
+
+## GemApiError.code
+
+[GemApiError.code](https://gemarcade.com/developer/api/server#gemapierror-code)
+
+```ts
+readonly code?: string
+```
+
+The platform's own error code, when it sent one —
+`too_many_concurrent_matches`, `cluster_target_required`,
+`no_compatible_server`.
+
+Finer-grained than [GemApiError.reason](https://gemarcade.com/developer/api/server#gemapierror-reason), and the only way to tell
+apart two refusals that share both a reason and a status. Absent on most
+refusals, so treat it as extra information rather than something to
+depend on.
+
+ON A PURCHASE IT IS THE FIELD TO BRANCH ON. `gem.me.mutations.purchase`
+refusals carry the platform's purchase codes — `insufficient_funds`,
+`recipe_locked`, `price_mismatch`, `not_purchasable`, … — the same
+strings `gem.purchases.request` answers as its `reason`, so one `switch`
+on `err.code` covers both purchase paths.
+
+## GemApiError.retryable
+
+[GemApiError.retryable](https://gemarcade.com/developer/api/server#gemapierror-retryable)
+
+```ts
+get retryable(): boolean
+```
+
+Whether another attempt could plausibly succeed.
+
+True for `unavailable` and `rate_limited` and false for everything else —
+a `forbidden` or `not_found` will refuse identically however many times you
+send it. Check this before retrying, and wait
+[GemApiError.retryAfterSeconds](https://gemarcade.com/developer/api/server#gemapierror-retryafterseconds) if the server named one.
+
+## ClientOptions
+
+[ClientOptions](https://gemarcade.com/developer/api/server#clientoptions)
+
+```ts
+interface ClientOptions
+```
+
+How a [GemClient](https://gemarcade.com/developer/api/server#gemclient) is built.
+
+You rarely construct one yourself — [createGemServer](https://gemarcade.com/developer/api/server#creategemserver) does it — but the
+type has to be nameable to write a helper that takes one.
+
+## ClientOptions.transport
+
+[ClientOptions.transport](https://gemarcade.com/developer/api/server#clientoptions-transport)
+
+```ts
+readonly transport: Transport
+```
+
+How requests actually leave. Substitute one to test without a network — see
+[Transport](https://gemarcade.com/developer/api/server#transport).
+
+## ClientOptions.clock
+
+[ClientOptions.clock](https://gemarcade.com/developer/api/server#clientoptions-clock)
+
+```ts
+readonly clock: Clock
+```
+
+Where time comes from, for retry backoff. See [Clock](https://gemarcade.com/developer/api/server#clock).
+
+## ClientOptions.maxRetries
+
+[ClientOptions.maxRetries](https://gemarcade.com/developer/api/server#clientoptions-maxretries)
+
+```ts
+readonly maxRetries?: number
+```
+
+How many times to retry a read that failed. Defaults to 2 — three attempts
+in all.
+
+READS SPEND THIS BUDGET, and so does a write the caller has declared
+replayable with [RequestOptions.replaySafe](https://gemarcade.com/developer/api/server#requestoptions-replaysafe). Every other write gets
+one attempt whatever you set here: a write that timed out may already have
+been applied, and repeating it is how a client charges someone twice.
+Whether a given write is safe to repeat is something only its caller knows,
+so the SDK does not guess.
+
+## RequestOptions
+
+[RequestOptions](https://gemarcade.com/developer/api/server#requestoptions)
+
+```ts
+interface RequestOptions
+```
+
+Per-call options, for the occasional call that needs one.
+
+## RequestOptions.keepalive
+
+[RequestOptions.keepalive](https://gemarcade.com/developer/api/server#requestoptions-keepalive)
+
+```ts
+readonly keepalive?: boolean
+```
+
+Let the request finish even if the page goes away.
+
+For the last write before a player closes the tab. Browsers cap how much
+can be in flight this way, so use it for the write that matters, not for
+every write.
+
+## RequestOptions.ifMatch
+
+[RequestOptions.ifMatch](https://gemarcade.com/developer/api/server#requestoptions-ifmatch)
+
+```ts
+readonly ifMatch?: string
+```
+
+Only apply this write if nothing has changed since you read.
+
+Pass the version that came back with the read your write is based on. If
+someone else wrote in between, the call fails with `precondition_failed`
+instead of overwriting them — re-read, decide again against the new state,
+and write again.
+
+## RequestOptions.replaySafe
+
+[RequestOptions.replaySafe](https://gemarcade.com/developer/api/server#requestoptions-replaysafe)
+
+```ts
+readonly replaySafe?: boolean
+```
+
+Declare that sending this write twice is harmless, so a failure that never
+reached the server can be retried.
+
+OFF BY DEFAULT, and it stays off unless you set it. Writes are not retried
+because a write that timed out may already have been applied — but some
+writes commit nothing, and for those the rule costs a caller the request
+with nothing bought. Asking for a signed upload URL is the example: it
+checks and hands back a URL, and asking twice produces a second URL and no
+second effect.
+
+SET IT ONLY WHEN REPEATING THE CALL CANNOT CHANGE THE OUTCOME. A purchase,
+a transfer, a grant of currency and anything that appends are all the
+opposite: a retry the caller cannot see is how one purchase becomes two.
+If you are unsure, leave it alone and decide for yourself whether to
+repeat the call.
+
+It buys the same budget a read gets — see [ClientOptions.maxRetries](https://gemarcade.com/developer/api/server#clientoptions-maxretries)
+— and nothing else. A refusal the server made deliberately is still
+final: only the failures [GemApiError.retryable](https://gemarcade.com/developer/api/server#gemapierror-retryable) describes, and a
+connection that died with no answer, are attempted again.
+
+## VersionedGetOptions
+
+[VersionedGetOptions](https://gemarcade.com/developer/api/server#versionedgetoptions)
+
+```ts
+interface VersionedGetOptions
+```
+
+Options for a read that also wants the value's version back.
+
+## VersionedGetOptions.signal
+
+[VersionedGetOptions.signal](https://gemarcade.com/developer/api/server#versionedgetoptions-signal)
+
+```ts
+readonly signal?: AbortSignal
+```
+
+Cancel the read. An aborted call rejects rather than resolving.
+
+## VersionedGetOptions.ifNoneMatch
+
+[VersionedGetOptions.ifNoneMatch](https://gemarcade.com/developer/api/server#versionedgetoptions-ifnonematch)
+
+```ts
+readonly ifNoneMatch?: string
+```
+
+Ask "has this changed?" instead of "give me this".
+
+Pass the version from your last read. If nothing has changed you get back
+`{ modified: false }` and no body — cheaper for you and for the platform.
+
+## VersionedResponse
+
+[VersionedResponse](https://gemarcade.com/developer/api/server#versionedresponse)
+
+```ts
+type VersionedResponse<T> = { modified: true; body: T; etag?: string } | { modified: false; etag?: string }
+```
+
+What a versioned read answers: either the value and its version, or "nothing
+changed".
+
+CHECK `modified` FIRST. There is no `body` on the unchanged branch — not an
+empty one, none — so the type will not let you read it until you have asked.
+That is deliberate: an optional `body` would let an unhandled 304 through to
+production as `undefined`.
+
+```js
+const result = await gem.client.getWithEtag(path, { ifNoneMatch: lastEtag });
+if (result.modified) {
+  render(result.body);
+  lastEtag = result.etag;
+}
+```
+
+## BytesResponse
+
+[BytesResponse](https://gemarcade.com/developer/api/server#bytesresponse)
+
+```ts
+interface BytesResponse
+```
+
+What [GemClient.postBytes](https://gemarcade.com/developer/api/server#gemclient-postbytes) resolves: the answer's raw bytes, and the id
+the platform gave the invocation when there was one.
+
+## BytesResponse.bytes
+
+[BytesResponse.bytes](https://gemarcade.com/developer/api/server#bytesresponse-bytes)
+
+```ts
+readonly bytes: Uint8Array
+```
+
+Exactly the bytes that arrived — empty when the answer had no body.
+
+## BytesResponse.invocationId
+
+[BytesResponse.invocationId](https://gemarcade.com/developer/api/server#bytesresponse-invocationid)
+
+```ts
+readonly invocationId?: string
+```
+
+The platform's id for this invocation, when the answer named one and the
+runtime could read it. See [TransportResponse.invocationId](https://gemarcade.com/developer/api/server#transportresponse-invocationid).
+
+## GemClient
+
+[GemClient](https://gemarcade.com/developer/api/server#gemclient)
+
+```ts
+class GemClient
+```
+
+The HTTP client underneath the generated operations — for calls those do not
+cover.
+
+PREFER [ServerApi](https://gemarcade.com/developer/api/server#serverapi). Its methods are typed against the platform's own
+description, so a shape that changes becomes a build error in your bundle.
+This one takes a path and checks nothing you give it.
+
+What it does give you is everything around the call: the credential, retries
+on the requests that are safe to retry, and failures already classified into
+[GemApiError](https://gemarcade.com/developer/api/server#gemapierror) so you can branch on a reason instead of a status.
+
+READS ARE RETRIED; A WRITE IS NOT, unless its caller declares it replayable
+with [RequestOptions.replaySafe](https://gemarcade.com/developer/api/server#requestoptions-replaysafe). A write that timed out may well have
+been applied, and retrying it silently is how a client duplicates a purchase
+it cannot see — so the default is one attempt, and widening it is a decision
+made one call at a time by whoever knows what the call does.
+
+You reach one as `gem.client`; there is normally no reason to construct it.
+
+## GemClient.constructor
+
+[GemClient.constructor](https://gemarcade.com/developer/api/server#gemclient-constructor)
+
+```ts
+constructor(options: ClientOptions): GemClient
+```
+
+Build a client. You normally do not — `createGemServer` builds one and hands
+it to you as `gem.client`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `ClientOptions` | See [ClientOptions](https://gemarcade.com/developer/api/server#clientoptions). |
+
+## GemClient.get
+
+[GemClient.get](https://gemarcade.com/developer/api/server#gemclient-get)
+
+```ts
+get<T>(path: string, signal?: AbortSignal): Promise<T>
+```
+
+Read something.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | From the API root, e.g. `/v1/players/me/settings`. |
+| `signal` | `AbortSignal` | Cancels the read. |
+
+**Throws.** [GemApiError](https://gemarcade.com/developer/api/server#gemapierror) on a refusal — branch on `reason`.
+
+## GemClient.getWithEtag
+
+[GemClient.getWithEtag](https://gemarcade.com/developer/api/server#gemclient-getwithetag)
+
+```ts
+getWithEtag<T>(path: string, options?: VersionedGetOptions): Promise<VersionedResponse<T>>
+```
+
+Read something AND get its version back — or find out it has not changed.
+
+The read half of optimistic concurrency: keep the version this returns, pass
+it as `ifMatch` on your write, and the write is refused rather than
+overwriting somebody. Pass it as `ifNoneMatch` here and an unchanged
+resource comes back with no body at all.
+
+SEPARATE FROM [GemClient.get](https://gemarcade.com/developer/api/server#gemclient-get) on purpose — `get` answers with the value
+and nothing else, which is what most calls want.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | From the API root. |
+| `options` | `VersionedGetOptions` | See [VersionedGetOptions](https://gemarcade.com/developer/api/server#versionedgetoptions). |
+
+**Returns.** See [VersionedResponse](https://gemarcade.com/developer/api/server#versionedresponse) — check `modified` before reading a body.
+
+**Throws.** [GemApiError](https://gemarcade.com/developer/api/server#gemapierror) on a refusal.
+
+## GemClient.put
+
+[GemClient.put](https://gemarcade.com/developer/api/server#gemclient-put)
+
+```ts
+put<T>(path: string, body: unknown, signal?: AbortSignal, options?: RequestOptions): Promise<T>
+```
+
+Replace something.
+
+NOT RETRIED. A write that timed out may already have been applied — set
+[RequestOptions.replaySafe](https://gemarcade.com/developer/api/server#requestoptions-replaysafe) if repeating this one cannot change the
+outcome.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | From the API root. |
+| `body` | `unknown` | What to send. Encoded as JSON. |
+| `signal` | `AbortSignal` |  |
+| `options` | `RequestOptions` | See [RequestOptions](https://gemarcade.com/developer/api/server#requestoptions) — `ifMatch` is how you avoid
+  overwriting someone else's write. |
+
+**Throws.** [GemApiError](https://gemarcade.com/developer/api/server#gemapierror) on a refusal.
+
+## GemClient.post
+
+[GemClient.post](https://gemarcade.com/developer/api/server#gemclient-post)
+
+```ts
+post<T>(path: string, body: unknown, signal?: AbortSignal, options?: RequestOptions): Promise<T>
+```
+
+Create something, or perform an action.
+
+NOT RETRIED, for the same reason as [GemClient.put](https://gemarcade.com/developer/api/server#gemclient-put), and widened the
+same way.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | From the API root. |
+| `body` | `unknown` | What to send. Encoded as JSON. |
+| `signal` | `AbortSignal` |  |
+| `options` | `RequestOptions` | See [RequestOptions](https://gemarcade.com/developer/api/server#requestoptions). |
+
+**Throws.** [GemApiError](https://gemarcade.com/developer/api/server#gemapierror) on a refusal.
+
+## GemClient.postBytes
+
+[GemClient.postBytes](https://gemarcade.com/developer/api/server#gemclient-postbytes)
+
+```ts
+postBytes(path: string, bytes: Uint8Array, signal?: AbortSignal, options?: RequestOptions): Promise<BytesResponse>
+```
+
+Send raw bytes and get raw bytes back.
+
+For a route whose input and output are your own bytes rather than JSON.
+The body goes out as it is, labelled `application/octet-stream`, and a
+success comes back undecoded. A refusal is still a [GemApiError](https://gemarcade.com/developer/api/server#gemapierror).
+
+NOT RETRIED, for the same reason as [GemClient.put](https://gemarcade.com/developer/api/server#gemclient-put), and widened the
+same way.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | From the API root. |
+| `bytes` | `Uint8Array` | What to send, byte for byte. |
+| `signal` | `AbortSignal` |  |
+| `options` | `RequestOptions` | See [RequestOptions](https://gemarcade.com/developer/api/server#requestoptions). |
+
+**Throws.** [GemApiError](https://gemarcade.com/developer/api/server#gemapierror) on a refusal.
+
+## GemClient.patch
+
+[GemClient.patch](https://gemarcade.com/developer/api/server#gemclient-patch)
+
+```ts
+patch<T>(path: string, body: unknown, signal?: AbortSignal, options?: RequestOptions): Promise<T>
+```
+
+Change part of something.
+
+NOT RETRIED, for the same reason as [GemClient.put](https://gemarcade.com/developer/api/server#gemclient-put), and widened the
+same way.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | From the API root. |
+| `body` | `unknown` | The change. Encoded as JSON. |
+| `signal` | `AbortSignal` |  |
+| `options` | `RequestOptions` | See [RequestOptions](https://gemarcade.com/developer/api/server#requestoptions). |
+
+**Throws.** [GemApiError](https://gemarcade.com/developer/api/server#gemapierror) on a refusal.
+
+## GemClient.delete
+
+[GemClient.delete](https://gemarcade.com/developer/api/server#gemclient-delete)
+
+```ts
+delete<T>(path: string, signal?: AbortSignal, options?: RequestOptions): Promise<T>
+```
+
+Remove something.
+
+NOT RETRIED, for the same reason as [GemClient.put](https://gemarcade.com/developer/api/server#gemclient-put), and widened the
+same way.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | From the API root. |
+| `signal` | `AbortSignal` | Cancels the call. |
+| `options` | `RequestOptions` | See [RequestOptions](https://gemarcade.com/developer/api/server#requestoptions). |
+
+**Throws.** [GemApiError](https://gemarcade.com/developer/api/server#gemapierror) on a refusal.
+
+## AuthFailure
+
+[AuthFailure](https://gemarcade.com/developer/api/server#authfailure)
+
+```ts
+type AuthFailure = "chain_exhausted" | "unavailable" | "timeout" | "internal"
+```
+
+Why the session could not produce a usable token.
+
+THIS IS THE CAUSE, NOT A VERDICT. It deliberately never distinguishes a
+sign-out from a ban from a revocation, and it does not tell you whether to
+try again — [AuthState](https://gemarcade.com/developer/api/server#authstate) does that. A game that branches on the reason
+is guessing.
+
+- `chain_exhausted` — the token chain cannot be renewed any further.
+- `unavailable` — no token right now.
+- `timeout` — the arcade did not answer in time.
+- `internal` — something went wrong on this side.
+
+## AuthState
+
+[AuthState](https://gemarcade.com/developer/api/server#authstate)
+
+```ts
+type AuthState = "ready" | "pending" | "degraded" | "lost"
+```
+
+What the session can currently do, delivered to `GemOptions.onAuthStateChange`.
+
+THIS IS THE ONE TO BRANCH ON, and the only route to it: the token source
+itself is internal, so a game cannot read this state by asking for it. Watch
+the callback instead.
+
+- `ready` — a usable token is held.
+- `pending` — no token yet, or one is being fetched.
+- `degraded` — the last attempt failed but another may succeed. Keep playing;
+  a retry is worthwhile.
+- `lost` — terminal for this session. Signing back in is the only way
+  forward, and retrying will not produce one.
+
+## TokenGrant
+
+[TokenGrant](https://gemarcade.com/developer/api/server#tokengrant)
+
+```ts
+interface TokenGrant
+```
+
+A credential and the two deadlines on it.
+
+YOU DO NOT HANDLE ONE IN NORMAL USE. The SDK obtains it, refreshes it before
+it expires, and attaches it to every call. It is named here because the
+token-source signatures a bundle reads when wiring things up itself mention
+it.
+
+TWO DEADLINES, AND THEY MEAN DIFFERENT THINGS. `expiresAt` is when this
+credential stops working and a fresh one is fetched — routine, invisible.
+`chainEndsAt` is when fetching a fresh one stops being possible at all: past
+it the session is over and only signing in again helps.
+
+## TokenGrant.token
+
+[TokenGrant.token](https://gemarcade.com/developer/api/server#tokengrant-token)
+
+```ts
+readonly token: string
+```
+
+The credential itself.
+
+NEVER LOG IT AND NEVER FORWARD IT. Anything holding it can act as this
+session until it expires.
+
+## TokenGrant.expiresAt
+
+[TokenGrant.expiresAt](https://gemarcade.com/developer/api/server#tokengrant-expiresat)
+
+```ts
+readonly expiresAt: number
+```
+
+When this credential stops working, in seconds since the Unix epoch.
+
+Routine — the SDK renews before this, and you do not see it happen.
+
+## TokenGrant.chainEndsAt
+
+[TokenGrant.chainEndsAt](https://gemarcade.com/developer/api/server#tokengrant-chainendsat)
+
+```ts
+readonly chainEndsAt: number
+```
+
+When renewal stops being possible, in seconds since the Unix epoch.
+
+Past this the session cannot be extended by anything. Watch
+[AuthState](https://gemarcade.com/developer/api/server#authstate) rather than this number.
+
+## AuthError
+
+[AuthError](https://gemarcade.com/developer/api/server#autherror)
+
+```ts
+class AuthError
+```
+
+The session cannot produce a usable token.
+
+Thrown by any call that needs the player's session. You catch this; you never
+construct it.
+
+IT CARRIES NO `retryable` FIELD, and that is deliberate rather than an
+oversight — [AuthError.reason](https://gemarcade.com/developer/api/server#autherror-reason) is the cause, and the retry verdict
+lives on the session's state. Watch `GemOptions.onAuthStateChange` and treat
+[AuthState](https://gemarcade.com/developer/api/server#authstate) `degraded` as worth retrying and `lost` as terminal. A game
+that decides from the reason will retry a session that can never come back.
+
+## AuthError.reason
+
+[AuthError.reason](https://gemarcade.com/developer/api/server#autherror-reason)
+
+```ts
+readonly reason: AuthFailure
+```
+
+Why the token could not be produced. See [AuthFailure](https://gemarcade.com/developer/api/server#authfailure) — it is the
+cause, and not a signal about whether to try again.
+
+## AuthError.isAuthError
+
+[AuthError.isAuthError](https://gemarcade.com/developer/api/server#autherror-isautherror)
+
+```ts
+isAuthError(error: unknown): error is AuthError
+```
+
+Whether a caught value is an `AuthError`.
+
+Prefer this to `instanceof`. Two copies of the SDK can coexist on a page —
+the arcade vendors one build and games install another — and an error from
+one copy fails `instanceof` in the other. This check does not care which
+copy minted it.
+
+```js
+try {
+  await somePlatformCall();
+} catch (err) {
+  if (AuthError.isAuthError(err)) {
+    // the session is the problem; watch onAuthStateChange for whether it recovers
+  }
+}
+```
+
+The call is left unnamed on purpose: this error reaches a game and a server
+bundle alike, and the two have no call in common.
+
+| Parameter | Type |
+| --- | --- |
+| `error` | `unknown` |
+
+## TransportRefusal
+
+[TransportRefusal](https://gemarcade.com/developer/api/server#transportrefusal)
+
+```ts
+class TransportRefusal
+```
+
+The request was never sent, because sending it would have been wrong.
+
+ALWAYS YOUR BUG, never a transient fault, and never worth retrying — the same
+call will be refused identically every time. Seven things produce one: a path
+or base URL that will not parse, a path that changes the protocol or host, a
+path or base URL carrying credentials, a body that will not serialise to
+JSON, a raw body that is not bytes or is sent alongside a JSON body, a
+conditional-header value the wire cannot carry, and a retry count outside
+0..10.
+
+Nothing reached the platform, so there is no status and no response to read.
+Fix the call.
+
+## TransportRefusal.retryable
+
+[TransportRefusal.retryable](https://gemarcade.com/developer/api/server#transportrefusal-retryable)
+
+```ts
+readonly retryable: false
+```
+
+Always `false`.
+
+Present so that code branching on `retryable` across the errors this SDK
+throws reads a real `false` here rather than `undefined`. A refusal is
+deterministic; retrying cannot change it.
+
+## TransportRefusal.isRefusal
+
+[TransportRefusal.isRefusal](https://gemarcade.com/developer/api/server#transportrefusal-isrefusal)
+
+```ts
+isRefusal(error: unknown): error is TransportRefusal
+```
+
+Whether a caught value is a `TransportRefusal`.
+
+Prefer this to `instanceof`. Two copies of the SDK can coexist on a page —
+the arcade vendors one build and games install another — and an error from
+one copy fails `instanceof` in the other.
+
+| Parameter | Type |
+| --- | --- |
+| `error` | `unknown` |
+
+## CONDITIONAL_HEADERS
+
+[CONDITIONAL_HEADERS](https://gemarcade.com/developer/api/server#conditional_headers)
+
+```ts
+CONDITIONAL_HEADERS: readonly ["if-match", "if-none-match"]
+```
+
+The only request headers a call may set: `if-match` and `if-none-match`.
+
+A CLOSED SET, ON PURPOSE. Everything else — the credential, the content type,
+the client's identity — is the SDK's to send, and a call that could add its
+own headers could send headers the platform trusts.
+
+## ConditionalRequestHeaders
+
+[ConditionalRequestHeaders](https://gemarcade.com/developer/api/server#conditionalrequestheaders)
+
+```ts
+type ConditionalRequestHeaders = Partial<Record<unknown[number], string>>
+```
+
+The type of [TransportRequest.headers](https://gemarcade.com/developer/api/server#transportrequest-headers) — derived from
+[CONDITIONAL_HEADERS](https://gemarcade.com/developer/api/server#conditional_headers), so the two cannot disagree.
+
+## TransportRequest
+
+[TransportRequest](https://gemarcade.com/developer/api/server#transportrequest)
+
+```ts
+interface TransportRequest
+```
+
+One outgoing call, as a [Transport](https://gemarcade.com/developer/api/server#transport) receives it.
+
+You meet this when you write a transport — usually in a test, to assert what
+your code sends without a network.
+
+## TransportRequest.method
+
+[TransportRequest.method](https://gemarcade.com/developer/api/server#transportrequest-method)
+
+```ts
+readonly method: "GET" | "PUT" | "POST" | "PATCH" | "DELETE"
+```
+
+The HTTP method.
+
+## TransportRequest.path
+
+[TransportRequest.path](https://gemarcade.com/developer/api/server#transportrequest-path)
+
+```ts
+readonly path: string
+```
+
+The path, from the API root — `/v1/players/me/settings`. Never a full URL:
+where it is sent is not a call's decision.
+
+## TransportRequest.body
+
+[TransportRequest.body](https://gemarcade.com/developer/api/server#transportrequest-body)
+
+```ts
+readonly body?: unknown
+```
+
+The request body, if there is one. Encoded as JSON.
+
+## TransportRequest.bytes
+
+[TransportRequest.bytes](https://gemarcade.com/developer/api/server#transportrequest-bytes)
+
+```ts
+readonly bytes?: Uint8Array<ArrayBufferLike>
+```
+
+A raw request body, sent as it is and labelled `application/octet-stream`.
+
+For a route whose input is your own bytes rather than JSON. Set this or
+[TransportRequest.body](https://gemarcade.com/developer/api/server#transportrequest-body), never both: a request carrying both is
+refused rather than sent with one of them dropped.
+
+## TransportRequest.responseType
+
+[TransportRequest.responseType](https://gemarcade.com/developer/api/server#transportrequest-responsetype)
+
+```ts
+readonly responseType?: "json" | "bytes"
+```
+
+How to read a successful answer: as JSON (the default), or as the raw
+bytes that arrived.
+
+Only a success is read as bytes. A refusal is the platform's own JSON
+envelope whichever you ask for, so its code and message still reach the
+error you catch.
+
+## TransportRequest.headers
+
+[TransportRequest.headers](https://gemarcade.com/developer/api/server#transportrequest-headers)
+
+```ts
+readonly headers?: Partial<Record<"if-match" | "if-none-match", string>>
+```
+
+See [ConditionalRequestHeaders](https://gemarcade.com/developer/api/server#conditionalrequestheaders) — nothing else may be set.
+
+## TransportRequest.signal
+
+[TransportRequest.signal](https://gemarcade.com/developer/api/server#transportrequest-signal)
+
+```ts
+readonly signal?: AbortSignal
+```
+
+Cancels the request. Timeouts are the caller's policy, not the SDK's.
+
+## TransportRequest.keepalive
+
+[TransportRequest.keepalive](https://gemarcade.com/developer/api/server#transportrequest-keepalive)
+
+```ts
+readonly keepalive?: boolean
+```
+
+Let the request outlive the page.
+
+For the write fired as a player leaves. Without this, a request started
+while the page is unloading is simply cancelled — it looks like it was sent,
+and nothing arrives.
+
+NOT ON EVERYTHING, because browsers cap how much can be in flight this way
+(64 KB across all such requests). Use it for the write that matters.
+
+## TransportResponse
+
+[TransportResponse](https://gemarcade.com/developer/api/server#transportresponse)
+
+```ts
+interface TransportResponse
+```
+
+What a [Transport](https://gemarcade.com/developer/api/server#transport) answers with.
+
+THREE HEADERS ARE PARSED OUT and there is no header bag, because these are the
+only three anything above this point reads — which also keeps a stub in a test
+to a few fields.
+
+## TransportResponse.status
+
+[TransportResponse.status](https://gemarcade.com/developer/api/server#transportresponse-status)
+
+```ts
+readonly status: number
+```
+
+The HTTP status.
+
+## TransportResponse.body
+
+[TransportResponse.body](https://gemarcade.com/developer/api/server#transportresponse-body)
+
+```ts
+readonly body: unknown
+```
+
+The decoded response body — or, for a success when the request asked for
+`responseType: 'bytes'`, a `Uint8Array` of exactly what arrived.
+
+## TransportResponse.etag
+
+[TransportResponse.etag](https://gemarcade.com/developer/api/server#transportresponse-etag)
+
+```ts
+readonly etag?: string
+```
+
+The resource's version, parsed out of the response.
+
+Absent when the server sent none — not every resource is versioned. If you
+are writing a transport for a test, set it: leaving it out makes every
+conditional read look unversioned.
+
+## TransportResponse.retryAfterSeconds
+
+[TransportResponse.retryAfterSeconds](https://gemarcade.com/developer/api/server#transportresponse-retryafterseconds)
+
+```ts
+readonly retryAfterSeconds?: number
+```
+
+How long the server asked you to wait, in WHOLE SECONDS.
+
+Seconds, not milliseconds — do not divide it by anything.
+
+ABSENT MEANS "NO ESTIMATE", NEVER "DO NOT RETRY". Whether a refusal is
+worth repeating is [GemApiError.retryable](https://gemarcade.com/developer/api/server#gemapierror-retryable)'s answer, not this field's.
+
+## TransportResponse.invocationId
+
+[TransportResponse.invocationId](https://gemarcade.com/developer/api/server#transportresponse-invocationid)
+
+```ts
+readonly invocationId?: string
+```
+
+The platform's id for the invocation this call started, when it started
+one — a serverless function call is the one that does.
+
+Absent when the answer named none, and also when the runtime could not read
+the header: a browser only reads the response headers the platform exposes
+to it.
+
+## Transport
+
+[Transport](https://gemarcade.com/developer/api/server#transport)
+
+```ts
+interface Transport
+```
+
+How calls actually leave — the seam you replace to test without a network.
+
+The SDK builds a real one for you. Pass your own when you want to assert what
+your code sends, or to answer it without a server.
+
+```js
+const sent = [];
+const transport = {
+  async request(req) {
+    sent.push(req);
+    return { status: 200, body: { ok: true } };
+  },
+};
+```
+
+## Transport.request
+
+[Transport.request](https://gemarcade.com/developer/api/server#transport-request)
+
+```ts
+request(request: TransportRequest): Promise<TransportResponse>
+```
+
+Send one request and resolve with what came back.
+
+| Parameter | Type |
+| --- | --- |
+| `request` | `TransportRequest` |
+
+## ChallengeWindow
+
+[ChallengeWindow](https://gemarcade.com/developer/api/server#challengewindow)
+
+```ts
+type ChallengeWindow = "daily" | "weekly" | "monthly" | "cron" | string & object
+```
+
+How often a challenge resets.
+
+Open on purpose: the platform may add a window, and a game that pattern-
+matches on the three it knows should fall through rather than fail to
+compile against a newer SDK.
+
+## Challenge
+
+[Challenge](https://gemarcade.com/developer/api/server#challenge)
+
+```ts
+interface Challenge
+```
+
+One challenge, in one period.
+
+Everything here is a function of your game config, the calendar and the
+player's time zone. It says nothing about the player's progress or streak.
+
+⚠️ **Key a period on [Challenge.periodLocalDate](https://gemarcade.com/developer/api/server#challenge-periodlocaldate), or on
+[Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed) for a `cron` challenge — never on
+[Challenge.periodStartAt](https://gemarcade.com/developer/api/server#challenge-periodstartat).** Two players on the same date, and on the
+same board, see different start instants when their time zones differ.
+
+## Challenge.id
+
+[Challenge.id](https://gemarcade.com/developer/api/server#challenge-id)
+
+```ts
+readonly id: string
+```
+
+The challenge's permanent id — the progression's id from your game config.
+
+Stable across renames, and the thing your own content should be keyed on.
+A challenge's id means one thing forever — reusing it for a different
+challenge merges two histories into one; the daily-challenges guide, §7,
+is the page.
+
+## Challenge.slug
+
+[Challenge.slug](https://gemarcade.com/developer/api/server#challenge-slug)
+
+```ts
+readonly slug?: string
+```
+
+The slug from your game config, when you declared one.
+
+Absent means absent — the field is omitted, never `null` or `''`.
+
+## Challenge.window
+
+[Challenge.window](https://gemarcade.com/developer/api/server#challenge-window)
+
+```ts
+readonly window: ChallengeWindow
+```
+
+How often this challenge resets.
+
+## Challenge.periodStartAt
+
+[Challenge.periodStartAt](https://gemarcade.com/developer/api/server#challenge-periodstartat)
+
+```ts
+readonly periodStartAt: number
+```
+
+When this period began for this player, in Unix seconds.
+
+⚠️ **Informational: never key anything on it** — not content, not a cache,
+not a result you send your server. A `local` period begins at the player's
+own reset time, so the same date starts at a different instant in each
+time zone, and an earlier period (`periodsBack`) is computed in the zone
+the player has now. Key on [Challenge.periodLocalDate](https://gemarcade.com/developer/api/server#challenge-periodlocaldate), or on
+[Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed) for a `cron` challenge.
+
+## Challenge.periodEndsAt
+
+[Challenge.periodEndsAt](https://gemarcade.com/developer/api/server#challenge-periodendsat)
+
+```ts
+readonly periodEndsAt: number
+```
+
+When this period stops accepting progress, in Unix seconds.
+
+**This is the seed's expiry.** After this instant the challenge is in a new
+period with a different [Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed); read `gem.challenges.list`
+again rather than computing the next boundary.
+
+⚠️ **Comparing it against the device clock is the one place that clock
+still matters** — and the consequence of a wrong one is bounded: you read
+late and show yesterday's subject a while longer. It cannot put your
+progress in the wrong period, because the platform decides that from the
+instant the write arrives, not from anything your game sends.
+
+⚠️ **Clamp any timer you build from it.** This is `0` when the platform
+sent something this SDK could not read (see below), and
+`setTimeout(refresh, (periodEndsAt - now) * 1000)` on a negative delay
+fires immediately, every time — a tight poll with no backoff. A
+`Math.max(60_000, ...)` floor turns that into a slow retry.
+
+## Challenge.periodLocalDate
+
+[Challenge.periodLocalDate](https://gemarcade.com/developer/api/server#challenge-periodlocaldate)
+
+```ts
+readonly periodLocalDate?: string
+```
+
+The period's calendar date, `YYYY-MM-DD`: the day for a daily, the Monday
+for a weekly, the 1st for a monthly, in the calendar the challenge runs on.
+
+**This is the period's identity, and what to key on** — together with
+[Challenge.id](https://gemarcade.com/developer/api/server#challenge-id), for content, a cache, or a result your server checks.
+Every player on the same date shares the same [Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed) and
+the same stored content, whatever their time zone.
+
+Absent — never `''` or `null` — for a `cron` challenge, which has no
+calendar date, and when the platform sent no date this SDK would pass on;
+key on [Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed) then: `c.periodLocalDate ?? c.seed`.
+
+## Challenge.boundary
+
+[Challenge.boundary](https://gemarcade.com/developer/api/server#challenge-boundary)
+
+```ts
+readonly boundary: string
+```
+
+Where this challenge's calendar runs: `'local'` — the player's own time
+zone — or the zone your game config fixed for everybody, as an IANA name
+such as `'UTC'` or `'Asia/Tokyo'`. `'UTC'` for a `cron` challenge.
+
+A player with no time zone stored on the platform is on UTC, so a `local`
+challenge is on UTC for them.
+
+`''` when the platform sent something this SDK would not pass on.
+
+## Challenge.resetTime
+
+[Challenge.resetTime](https://gemarcade.com/developer/api/server#challenge-resettime)
+
+```ts
+readonly resetTime: string
+```
+
+The clock time, `HH:MM` in [Challenge.boundary](https://gemarcade.com/developer/api/server#challenge-boundary)'s zone, at which a
+new period begins. `'00:00'` unless your game config set one, and always
+`'00:00'` for a `cron` challenge, whose periods begin when its expression
+fires.
+
+`''` when the platform sent something this SDK would not pass on.
+
+## Challenge.seed
+
+[Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed)
+
+```ts
+readonly seed: string
+```
+
+The subject selector for this challenge in this period.
+
+Identical for every player in this game and period — **in every channel**,
+because the channel is not part of what the platform derives it from — and
+different in the next period. For a daily, weekly or monthly challenge the
+period is the [Challenge.periodLocalDate](https://gemarcade.com/developer/api/server#challenge-periodlocaldate), so players in different
+time zones share each board, each reaching it when their own period begins.
+
+Lowercase hex, and **a string on purpose**: JavaScript numbers are doubles,
+so a 64-bit seed parsed as a number loses its low bits and two clients
+rounding differently disagree about today's board. Use it as text, or parse
+only as much of it as your generator needs. **Treat the length as opaque**
+— take a prefix, never assume one.
+
+⚠️ **IT IS NOT A SECRET, and nothing may depend on it being one.** It is
+derived from public inputs and is entirely predictable: anyone can compute
+the next one, and every player's client already holds this one. Never
+authorize anything with it, never use it where a value must be
+unguessable, and if knowing the subject in advance would break your game,
+the subject has to come from your own server instead. Its job is
+agreement, not secrecy.
+
+⚠️ **`''` means the platform sent something this SDK would not pass on** —
+a value outside the lowercase-hex contract above. It is falsy, so
+`if (today.seed)` is the guard; do not start a seeded board without one.
+
+## Challenge.data
+
+[Challenge.data](https://gemarcade.com/developer/api/server#challenge-data)
+
+```ts
+readonly data?: string
+```
+
+The content your studio pre-generated for this challenge and period —
+usually JSON describing today's board — when it stored some.
+
+⚠️ **It may be absent, and your game must keep working when it is.** The
+field is omitted — never `''` — when nothing is stored for this period, and
+then you fall back to [Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed) or a pool bundled with your
+game. Content is written ahead of time by your studio's producer (a CI job,
+a cron job, an agent, or a developer with `gemctl challenges data push`),
+and a producer's runway can run out.
+
+It is opaque to the platform, which never parses it: parse it yourself, and
+treat a value you cannot parse the way you treat an absent one.
+
+⚠️ **It is not per channel.** Content is stored once for the challenge and
+period and served on every channel whose config displays that challenge —
+the same bytes on `dev` as on `release`. Content pushed to try out on `dev`
+reaches `release` players as soon as the `release` config displays the same
+challenge [Challenge.id](https://gemarcade.com/developer/api/server#challenge-id); to trial different content, give the trial
+challenge a different id. The player's progress on it stays per channel.
+
+⚠️ **It is not authority.** Every player in the period receives the same
+bytes, so it must never hold anything a verifier relies on being secret —
+a hidden solution stays on your server. And it must never hold personal
+data.
+
+A period's content becomes readable only once that period has begun.
+
+## Challenge.dataHash
+
+[Challenge.dataHash](https://gemarcade.com/developer/api/server#challenge-datahash)
+
+```ts
+readonly dataHash?: string
+```
+
+16 lowercase hex identifying [Challenge.data](https://gemarcade.com/developer/api/server#challenge-data) — present exactly when
+`data` is.
+
+**Send it with a result, together with [Challenge.periodLocalDate](https://gemarcade.com/developer/api/server#challenge-periodlocaldate)**
+— or [Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed) for a `cron` challenge, which has no date.
+A verifier reads the same period and compares hashes, which is how it
+proves the player played the content it is checking against. It changes
+only when your studio corrects a running period; clients may hold the old
+content for up to an hour afterwards, and the hash is how a verifier tells
+them apart.
+
+## FunctionInvokeOptions
+
+[FunctionInvokeOptions](https://gemarcade.com/developer/api/server#functioninvokeoptions)
+
+```ts
+interface FunctionInvokeOptions
+```
+
+What [FunctionsApi.invoke](https://gemarcade.com/developer/api/server#functionsapi-invoke) takes besides the input.
+
+## FunctionInvokeOptions.signal
+
+[FunctionInvokeOptions.signal](https://gemarcade.com/developer/api/server#functioninvokeoptions-signal)
+
+```ts
+readonly signal?: AbortSignal
+```
+
+Cancel the call. A call already cancelled sends nothing.
+
+## FunctionResult
+
+[FunctionResult](https://gemarcade.com/developer/api/server#functionresult)
+
+```ts
+interface FunctionResult
+```
+
+Your function's answer: its bytes, and ways to read them.
+
+```js
+const result = await gem.functions.invoke({ v: 2, runId, finishMs });
+const verdict = result.json();
+```
+
+## FunctionResult.bytes
+
+[FunctionResult.bytes](https://gemarcade.com/developer/api/server#functionresult-bytes)
+
+```ts
+readonly bytes: Uint8Array
+```
+
+Exactly the bytes your function returned in `Ok`. Empty when it returned none.
+
+## FunctionResult.invocationId
+
+[FunctionResult.invocationId](https://gemarcade.com/developer/api/server#functionresult-invocationid)
+
+```ts
+readonly invocationId?: string
+```
+
+The platform's id for this call — what to quote when you ask about one call.
+
+Absent when your code cannot read it: a server bundle can, and a game page
+can only once the platform lets a page read that response header.
+
+## FunctionResult.text
+
+[FunctionResult.text](https://gemarcade.com/developer/api/server#functionresult-text)
+
+```ts
+text(): string
+```
+
+The answer as UTF-8 text.
+
+**Throws.** `TypeError` when the bytes are not valid UTF-8, rather than
+  replacing what it cannot decode.
+
+## FunctionResult.json
+
+[FunctionResult.json](https://gemarcade.com/developer/api/server#functionresult-json)
+
+```ts
+json<T>(): T
+```
+
+The answer parsed as JSON.
+
+**Throws.** `SyntaxError` when the answer is not JSON — including an empty one.
+
+## FunctionFailure
+
+[FunctionFailure](https://gemarcade.com/developer/api/server#functionfailure)
+
+```ts
+type FunctionFailure = "trap" | "memory_exceeded" | "cpu_budget_exceeded" | "host_call_limit"
+```
+
+Why a call that reached your function did not finish — carried on
+[GemFunctionError.failure](https://gemarcade.com/developer/api/server#gemfunctionerror-failure).
+
+- `trap` — a panic, an `unreachable`, an out-of-bounds access or a stack
+  overflow. No stack trace comes back.
+- `memory_exceeded` — past the memory limit.
+- `cpu_budget_exceeded` — past the CPU budget.
+- `host_call_limit` — more platform API calls than one invocation may make.
+
+## GemFunctionError
+
+[GemFunctionError](https://gemarcade.com/developer/api/server#gemfunctionerror)
+
+```ts
+class GemFunctionError
+```
+
+A call to your serverless function was refused, or your function did not
+answer.
+
+Thrown by [FunctionsApi.invoke](https://gemarcade.com/developer/api/server#functionsapi-invoke) for every refusal the platform sends.
+It IS a [GemApiError](https://gemarcade.com/developer/api/server#gemapierror), so `reason`, `status`, `code`, `detail` and
+`retryAfterSeconds` mean what they mean there. Branch on `code` for what
+happened; `retryable` is decided by the code. You catch this; you never
+construct it.
+
+```js
+try {
+  show((await gem.functions.invoke(claim)).json());
+} catch (err) {
+  if (!(err instanceof GemFunctionError)) throw err;
+  if (err.code === 'function_error') reportBug(err.functionMessage, err.invocationId);
+  else if (err.retryable) retryLater(err.retryAfterSeconds ?? 5);
+  else reportBug(err.code, err.invocationId);
+}
+```
+
+## GemFunctionError.reason
+
+[GemFunctionError.reason](https://gemarcade.com/developer/api/server#gemfunctionerror-reason)
+
+```ts
+readonly reason: GemErrorReason
+```
+
+What went wrong, in terms you can act on — `invalid`, `forbidden`,
+`not_found`, `conflict`, `precondition_failed`, `not_modified`,
+`insufficient_funds`, `too_large`, `rate_limited` or `unavailable`.
+
+This is the field to branch on. Two refusals can share a status and mean
+different things; they do not share a reason.
+
+## GemFunctionError.status
+
+[GemFunctionError.status](https://gemarcade.com/developer/api/server#gemfunctionerror-status)
+
+```ts
+readonly status: number
+```
+
+The HTTP status the server answered with.
+
+Carried for logs and bug reports. Prefer [GemApiError.reason](https://gemarcade.com/developer/api/server#gemapierror-reason) for
+decisions: several distinct refusals map onto one status, so branching
+here treats different problems as the same one.
+
+## GemFunctionError.detail
+
+[GemFunctionError.detail](https://gemarcade.com/developer/api/server#gemfunctionerror-detail)
+
+```ts
+readonly detail: string
+```
+
+The server's own sentence, without the `reason (status):` prefix that
+`message` carries.
+
+Use this when you want to quote the platform — in a log line, or a bug
+report. It is not written for players, so do not put it on screen.
+
+## GemFunctionError.retryAfterSeconds
+
+[GemFunctionError.retryAfterSeconds](https://gemarcade.com/developer/api/server#gemfunctionerror-retryafterseconds)
+
+```ts
+readonly retryAfterSeconds?: number
+```
+
+How long the server asked you to wait, in whole seconds.
+
+ABSENT MEANS "NO ESTIMATE GIVEN", NEVER "DO NOT RETRY" —
+[GemApiError.retryable](https://gemarcade.com/developer/api/server#gemapierror-retryable) is what answers that. A refusal can be
+worth repeating and still name no wait, so treat absence as "pick your
+own backoff" rather than as a stop signal. The platform estimates a wait
+for capacity and for rate limits, and sends none for the refusals it
+cannot put a number on.
+
+## GemFunctionError.code
+
+[GemFunctionError.code](https://gemarcade.com/developer/api/server#gemfunctionerror-code)
+
+```ts
+readonly code?: string
+```
+
+The platform's own error code, when it sent one —
+`too_many_concurrent_matches`, `cluster_target_required`,
+`no_compatible_server`.
+
+Finer-grained than [GemApiError.reason](https://gemarcade.com/developer/api/server#gemapierror-reason), and the only way to tell
+apart two refusals that share both a reason and a status. Absent on most
+refusals, so treat it as extra information rather than something to
+depend on.
+
+ON A PURCHASE IT IS THE FIELD TO BRANCH ON. `gem.me.mutations.purchase`
+refusals carry the platform's purchase codes — `insufficient_funds`,
+`recipe_locked`, `price_mismatch`, `not_purchasable`, … — the same
+strings `gem.purchases.request` answers as its `reason`, so one `switch`
+on `err.code` covers both purchase paths.
+
+## GemFunctionError.invocationId
+
+[GemFunctionError.invocationId](https://gemarcade.com/developer/api/server#gemfunctionerror-invocationid)
+
+```ts
+readonly invocationId?: string
+```
+
+The platform's id for the invocation, when the call became one and your
+code can read the id. See [FunctionResult.invocationId](https://gemarcade.com/developer/api/server#functionresult-invocationid).
+
+## GemFunctionError.functionMessage
+
+[GemFunctionError.functionMessage](https://gemarcade.com/developer/api/server#gemfunctionerror-functionmessage)
+
+```ts
+readonly functionMessage?: string
+```
+
+The text your function returned in `Err`, on `code` `function_error`.
+
+Written by your function, which may have repeated what the caller sent, so
+treat it as untrusted: log it, never render it as markup.
+
+## GemFunctionError.failure
+
+[GemFunctionError.failure](https://gemarcade.com/developer/api/server#gemfunctionerror-failure)
+
+```ts
+readonly failure?: string & object | FunctionFailure
+```
+
+On `code` `function_failed`, which limit or fault ended the call. See
+[FunctionFailure](https://gemarcade.com/developer/api/server#functionfailure). A value this SDK does not know yet arrives as the
+platform sent it.
+
+## GemFunctionError.retryable
+
+[GemFunctionError.retryable](https://gemarcade.com/developer/api/server#gemfunctionerror-retryable)
+
+```ts
+get retryable(): boolean
+```
+
+Whether repeating the same call could plausibly get a different answer.
+
+Decided by `code`. True when the platform could not run the call: it was
+busy, could not reach the function, or was rate-limiting the caller. False
+when the function ran — `function_error`, `function_failed`,
+`function_timeout` — and when nothing will change until someone acts:
+nothing published, input too large, functions switched off. A lost
+connection is `retryable` too, but your function may have run.
+
+## FunctionsApi
+
+[FunctionsApi](https://gemarcade.com/developer/api/server#functionsapi)
+
+```ts
+class FunctionsApi
+```
+
+Your game's serverless function. Reached as `gem.functions`, in the browser
+and in a server bundle.
+
+## FunctionsApi.invoke
+
+[FunctionsApi.invoke](https://gemarcade.com/developer/api/server#functionsapi-invoke)
+
+```ts
+invoke(input: unknown, options?: FunctionInvokeOptions): Promise<FunctionResult>
+```
+
+Call the function published on your channel, and get its answer.
+
+The input is sent as your function's `input`, byte for byte. Pass a
+`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they
+are. Pass anything else and it is sent as its JSON text — a string too, so
+`'ping'` arrives as `"ping"` with its quotes.
+
+The call is made once. It is never repeated for you, because your function
+may have granted or written something: see [GemFunctionError.retryable](https://gemarcade.com/developer/api/server#gemfunctionerror-retryable)
+for whether repeating it could help.
+
+```js
+const result = await gem.functions.invoke({ v: 2, runId, finishMs });
+const { accepted, why } = result.json();
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `input` | `unknown` | Bytes, or a value to send as JSON. |
+| `options` | `FunctionInvokeOptions` |  |
+
+**Throws.** [GemFunctionError](https://gemarcade.com/developer/api/server#gemfunctionerror) for a refusal, including your function's
+  own `Err`. `TransportRefusal` for an input that is neither bytes nor
+  JSON, before anything is sent. `AuthError` if the token cannot be renewed.
+
+## Clock
+
+[Clock](https://gemarcade.com/developer/api/server#clock)
+
+```ts
+interface Clock
+```
+
+Where time comes from — so a test does not have to wait for it.
+
+Credential refresh, retry backoff and timeouts are all wall-clock behaviour.
+A test that has to wait ten real seconds to prove a timeout fires is a test
+nobody runs, so every SDK option that involves time takes one of these.
+
+Pass [systemClock](https://gemarcade.com/developer/api/server#systemclock) — or nothing, which means the same — to use real
+time. Pass your own to control it.
+
+```js
+let now = 0;
+const timers = [];
+const clock = {
+  now: () => now,
+  setTimeout: (fn, ms) => timers.push({ fn, at: now + ms }),
+  clearTimeout: () => {},
+};
+// advance time yourself, and run whatever is due
+```
+
+## Clock.now
+
+[Clock.now](https://gemarcade.com/developer/api/server#clock-now)
+
+```ts
+now(): number
+```
+
+The current time, in milliseconds — the same scale as `Date.now()`.
+
+## Clock.setTimeout
+
+[Clock.setTimeout](https://gemarcade.com/developer/api/server#clock-settimeout)
+
+```ts
+setTimeout(fn: () => void, ms: number): unknown
+```
+
+Run `fn` after `ms` milliseconds. Return whatever identifies it; the SDK
+only ever hands that value back to [Clock.clearTimeout](https://gemarcade.com/developer/api/server#clock-cleartimeout).
+
+| Parameter | Type |
+| --- | --- |
+| `fn` | `() => void` |
+| `ms` | `number` |
+
+## Clock.clearTimeout
+
+[Clock.clearTimeout](https://gemarcade.com/developer/api/server#clock-cleartimeout)
+
+```ts
+clearTimeout(handle: unknown): void
+```
+
+Cancel a timer created by [Clock.setTimeout](https://gemarcade.com/developer/api/server#clock-settimeout).
+
+| Parameter | Type |
+| --- | --- |
+| `handle` | `unknown` |
+
+## systemClock
+
+[systemClock](https://gemarcade.com/developer/api/server#systemclock)
+
+```ts
+systemClock: Clock
+```
+
+Real time — the [Clock](https://gemarcade.com/developer/api/server#clock) every SDK option defaults to.
+
+Name it when you want to be explicit, or wrap it when you want to watch what
+the SDK schedules without replacing the clock entirely.
+
+## defineServer
+
+[defineServer](https://gemarcade.com/developer/api/server#defineserver)
+
+```ts
+function defineServer(setup: (gem: GemMatchServer) => GemServerBundle, options?: GemServerOptions): GemServerFactory
+```
+
+Declare your dedicated server. Default-export the result.
+
+You pass a setup function; it receives a [GemMatchServer](https://gemarcade.com/developer/api/server#gemmatchserver) — the platform
+operations, your room, your players — and returns the handlers you want. The
+credential and its refresh are handled for you, and the SDK is disposed when
+the match ends.
+
+WHY A FUNCTION RATHER THAN A PLAIN OBJECT: your handlers need to share state.
+The closure the setup function creates is where your world lives, alongside
+`gem`, without threading either through five signatures.
+
+A THROWN ERROR IS NOT SWALLOWED. The platform logs it and keeps serving —
+except in `init`, where it fails the match. That is deliberate: a server with
+a broken handler quietly serving nobody is worse than one that stops.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `setup` | `(gem: GemMatchServer) => GemServerBundle` | Called once. Return the handlers you want from
+  [GemServerBundle](https://gemarcade.com/developer/api/server#gemserverbundle); omit the rest. |
+| `options` | `GemServerOptions` | Passed through to [createGemServer](https://gemarcade.com/developer/api/server#creategemserver). Normally omit it. |
+
+**Returns.** The value to default-export from your bundle's entry file.
+
+```js
+import { defineServer } from '@indiegems/gem-web-sdk/sdk';
+
+export default defineServer((gem) => {
+  let round = 0;
+  return {
+    async init() {
+      const room = await gem.room?.get();
+      gem.log(`room has ${room?.members.length ?? 0} player(s)`);
+    },
+    message(playerId, data, isText) {
+      if (isText && data === 'next') gem.broadcast(`round ${++round}`);
+    },
+    async shutdown(info) {
+      if (info?.reason !== 'signal') await gem.match.end();
+    },
+  };
+});
+```
+
+**Guides.** [server-bundles](https://gemarcade.com/developer/docs/server-bundles)
+
+## createMatchServer
+
+[createMatchServer](https://gemarcade.com/developer/api/server#creatematchserver)
+
+```ts
+function createMatchServer(host: GemServerHost, options?: GemServerOptions): GemMatchServer
+```
+
+Build the `gem` object yourself, when you are driving the lifecycle by hand.
+
+MOST BUNDLES WANT [defineServer](https://gemarcade.com/developer/api/server#defineserver), which calls this for you and wires up
+your handlers. Use this one if you are writing the lifecycle object directly.
+
+CALL IT FROM `init`, not at module scope — it needs the host, and it builds
+the platform connection immediately, which is what turns "this platform image
+is too old" into a startup failure rather than a surprise mid-match. Call
+`dispose()` from `shutdown`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `host` | `GemServerHost` | The object the runtime passed to `init`. |
+| `options` | `GemServerOptions` | Passed through to [createGemServer](https://gemarcade.com/developer/api/server#creategemserver). Normally omit it. |
+
+**Throws.** When the runtime named no API host, so no call could succeed.
+
+```js
+import { createMatchServer } from '@indiegems/gem-web-sdk/sdk';
+
+export default () => {
+  let gem;
+  return {
+    async init(host) { gem = createMatchServer(host); },
+    join(playerId) { gem.broadcast(`${playerId} joined`); },
+    async shutdown(info) { if (info?.reason !== 'signal') await gem.match.end(); gem.dispose(); },
+  };
+};
+```
+
+## createGemServer
+
+[createGemServer](https://gemarcade.com/developer/api/server#creategemserver)
+
+```ts
+function createGemServer(host: ServerBundleHost, options?: GemServerOptions): GemServer
+```
+
+Build your server's connection to the platform. Call it once, in `init(host)`.
+
+Pass the `host` object the runtime handed you and you get back a
+[GemServer](https://gemarcade.com/developer/api/server#gemserver): the platform operations, the room reads for your own room,
+and a way to end the match. The credential is taken from the host and kept
+fresh for you.
+
+MOST BUNDLES DO NOT CALL THIS. [defineServer](https://gemarcade.com/developer/api/server#defineserver) does it for you and hands
+you the result. Reach for it directly when you are managing the lifecycle
+yourself.
+
+IT THROWS AT STARTUP if the runtime did not name an API to call — an old
+platform image. That is deliberate: a server that silently cannot reach the
+platform is worse than one that refuses to start.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `host` | `ServerBundleHost` | The object the runtime passes to `init`. |
+| `options` | `GemServerOptions` | See [GemServerOptions](https://gemarcade.com/developer/api/server#gemserveroptions) — normally omit it. |
+
+**Throws.** When the runtime named no API host, so no call could succeed.
+
+```js
+import { createGemServer } from '@indiegems/gem-web-sdk/sdk';
+
+export async function init(host) {
+  const gem = createGemServer(host);
+  const room = await gem.room?.get();
+  host.log(`match ${gem.identity.matchId} with ${room?.members.length ?? 0}`);
+}
+```
+
+**Guides.** [server-bundles](https://gemarcade.com/developer/docs/server-bundles)
+
+## createHostTokenSource
+
+[createHostTokenSource](https://gemarcade.com/developer/api/server#createhosttokensource)
+
+```ts
+function createHostTokenSource(host: ServerBundleHost, options: HostTokenSourceOptions): HostTokenSource
+```
+
+Keep the platform credential fresh, without building the rest of the SDK.
+
+MOST BUNDLES NEVER CALL THIS. [createGemServer](https://gemarcade.com/developer/api/server#creategemserver) does it, and hands you a
+client that is already authenticated. Reach for it when you are assembling
+the pieces yourself.
+
+It subscribes to the host's credential pushes straight away. Call `dispose()`
+when you are done, or a pending refresh timer will keep your process alive
+after the match is over.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `host` | `ServerBundleHost` | The object the runtime passed to `init`. |
+| `options` | `HostTokenSourceOptions` | See [HostTokenSourceOptions](https://gemarcade.com/developer/api/server#hosttokensourceoptions) — `clock` is required. |
+
+**Returns.** Something you can stop. See [HostTokenSource](https://gemarcade.com/developer/api/server#hosttokensource).
+
+## achievementReceipts
+
+[achievementReceipts](https://gemarcade.com/developer/api/server#achievementreceipts)
+
+```ts
+function achievementReceipts(order: unknown): AchievementReceipt[]
+```
+
+The achievement receipts on an order result: one for each achievement
+threshold the order crossed — unlocked, already held, or suppressed and why
+— plus any achievement it unlocked because the value was already past the
+threshold. Empty when the order crossed none, which is almost every order.
+
+Pass the value a progression write or `createEntityOrder` returned; for a
+batch, call it once per entry of the result's `orders`. Anything that is not
+a well-formed achievement receipt is left out, so the call is safe on any
+order result.
+
+The receipts say what happened, once. They are not a trigger to pay a
+game-side reward on: a retried or replayed order reports nothing, because
+the threshold is already behind it. Put a game reward in the same
+threshold's `rewards`, which the platform pays on the crossing itself (and
+again after a reset, unlike the achievement).
+
+| Parameter | Type |
+| --- | --- |
+| `order` | `unknown` |
+
+```ts
+const order = await gem.api.addEntityProgression('players', playerId, 'boards_cleared', {
+  amount: 1,
+});
+for (const r of achievementReceipts(order)) {
+  if (r.outcome === 'unlocked') log(`unlocked ${r.achievementId} (+${r.points})`);
+}
+```
+
+**Guides.** [achievements](https://gemarcade.com/developer/docs/achievements)
+
+## AchievementReceipt
+
+[AchievementReceipt](https://gemarcade.com/developer/api/server#achievementreceipt)
+
+```ts
+interface AchievementReceipt
+```
+
+What became of one achievement an order reached.
+
+**Guides.** [achievements](https://gemarcade.com/developer/docs/achievements)
+
+## GemMatchServer
+
+[GemMatchServer](https://gemarcade.com/developer/api/server#gemmatchserver)
+
+```ts
+interface GemMatchServer
+```
+
+The `gem` your bundle holds — everything a dedicated server can do, on one
+object.
+
+This is what [defineServer](https://gemarcade.com/developer/api/server#defineserver) hands your setup function. It is a
+[GemServer](https://gemarcade.com/developer/api/server#gemserver) — the platform operations, your room, ending the match —
+with the match surface added: the players connected right now, and how to talk
+to them.
+
+The allocation is spelled ONE way. There is no `gem.matchId`; it is
+`gem.identity.matchId`.
+
+```js
+export default defineServer((gem) => ({
+  join(playerId) {
+    const who = gem.profile(playerId);
+    gem.broadcast(`${playerId} joined (seat ${gem.playerNumber(playerId)})`);
+    gem.log(`now ${gem.players().length} connected`);
+  },
+}));
+```
+
+## GemServerBundle
+
+[GemServerBundle](https://gemarcade.com/developer/api/server#gemserverbundle)
+
+```ts
+interface GemServerBundle
+```
+
+The five things that can happen to your server. Define the ones you care
+about; each may be `async` and is awaited before the next event arrives.
+
+This is what your setup function returns — see [defineServer](https://gemarcade.com/developer/api/server#defineserver). Events
+are delivered one at a time, in order, so you never handle two at once and do
+not need locking around your own state.
+
+```js
+export default defineServer((gem) => {
+  const scores = new Map();
+  return {
+    join(playerId) { scores.set(playerId, 0); },
+    leave(playerId) { scores.delete(playerId); },
+    message(playerId, data, isText) {
+      if (isText) scores.set(playerId, scores.get(playerId) + Number(data));
+    },
+    async shutdown(info) { if (info?.reason !== 'signal') await gem.match.end(); },
+  };
+});
+```
+
+## GemServerFactory
+
+[GemServerFactory](https://gemarcade.com/developer/api/server#gemserverfactory)
+
+```ts
+type GemServerFactory = () => GemServerLifecycle
+```
+
+The type of your bundle's default export — what [defineServer](https://gemarcade.com/developer/api/server#defineserver) returns.
+
+The platform calls it once, at the start of a match.
+
+## GemServerLifecycle
+
+[GemServerLifecycle](https://gemarcade.com/developer/api/server#gemserverlifecycle)
+
+```ts
+interface GemServerLifecycle
+```
+
+What the platform actually calls — a [GemServerBundle](https://gemarcade.com/developer/api/server#gemserverbundle) after the SDK has
+wrapped it.
+
+YOU DO NOT WRITE ONE. [defineServer](https://gemarcade.com/developer/api/server#defineserver) produces it from your bundle. It is
+named here so you can type a variable holding the result, and so the shape the
+platform drives is written down somewhere a reader can find it.
+
+`init` and `shutdown` are required here although both are optional on your
+bundle: the SDK always defines them, to receive the host and to release the
+credential subscription when the match is over.
+
+## RuntimeShutdownPayload
+
+[RuntimeShutdownPayload](https://gemarcade.com/developer/api/server#runtimeshutdownpayload)
+
+```ts
+interface RuntimeShutdownPayload
+```
+
+What the platform runtime hands `shutdown`, on images that say why.
+
+Either spelling of the platform reason is accepted: the runtime's wire
+name (`platform_reason`) and the SDK's (`endedReason`).
+
+## ServerShutdownInfo
+
+[ServerShutdownInfo](https://gemarcade.com/developer/api/server#servershutdowninfo)
+
+```ts
+interface ServerShutdownInfo
+```
+
+Why your server's `shutdown` is running.
+
+The reason is the platform runtime's own word, passed through unchanged:
+
+- `match_ended` — the platform ended the match (yours by `gem.match.end()`,
+  or its own: expired, everybody left, …). `endedReason` names which, in
+  the same vocabulary `matchEnded` uses on the client, when the runtime
+  passed it along.
+- `idle_timeout` — nobody was connected for the idle window. The platform
+  ends the match itself, so the room reopens; there is nothing to end.
+- `signal` — the platform is reclaiming the machine. A drain: your players
+  are still here and the match plays out. Do not end it.
+
+On a LISTEN HOST — the same bundle run in the hosting player's browser by
+`gem.match.serve()` — two more arrive: `host_migrated` (the platform moved
+the match to another host; this seat no longer speaks for it) and `stopped`
+(the hosting game called the deprecated `stop()`, which tells the platform
+nothing).
+
+OPEN: a later runtime may add a value. Treat one you do not recognise as
+"the match is over", which is the safe reading.
+
+## GemServerProfile
+
+[GemServerProfile](https://gemarcade.com/developer/api/server#gemserverprofile)
+
+```ts
+interface GemServerProfile
+```
+
+Who a player is, for display. Safe to hold; think before you relay it.
+
+Returned by [GemMatchServer.profile](https://gemarcade.com/developer/api/server#gemmatchserver-profile).
+
+RELAY THE ID, NOT THE NAME. Sending player ids to your clients and letting
+each one render the name it already has is better than broadcasting names
+through your server: it is less to send, and it keeps one player's text from
+reaching every other player's screen through you.
+
+## GemServer
+
+[GemServer](https://gemarcade.com/developer/api/server#gemserver)
+
+```ts
+interface GemServer
+```
+
+Your server's connection to the platform — what [createGemServer](https://gemarcade.com/developer/api/server#creategemserver)
+returns.
+
+Build one in `init(host)`, keep it, and call through it for the life of the
+match. It holds the credential and refreshes it for you; there is nothing to
+sign, renew or attach.
+
+```js
+import { defineServer } from '@indiegems/gem-web-sdk/sdk';
+
+export default defineServer((gem) => ({
+  async init() {
+    const room = await gem.room?.get();
+    gem.log(`starting with ${room?.members.length ?? 0} player(s)`);
+  },
+  async shutdown(info) {
+    if (info?.reason !== 'signal') await gem.match.end();
+  },
+}));
+```
+
+## GemServerIdentity
+
+[GemServerIdentity](https://gemarcade.com/developer/api/server#gemserveridentity)
+
+```ts
+interface GemServerIdentity
+```
+
+Which game, channel and match this server was started for.
+
+You never construct one. The platform decides all of it when it allocates the
+server, and [GemServer.identity](https://gemarcade.com/developer/api/server#gemserver-identity) is it restated in one place so you do
+not have to keep reaching back to the host object.
+
+These are also the ids bound into every call `api` makes, which is why a
+bundle never types a game id and cannot name another game's.
+
+## GemServerOptions
+
+[GemServerOptions](https://gemarcade.com/developer/api/server#gemserveroptions)
+
+```ts
+interface GemServerOptions
+```
+
+Options for [createGemServer](https://gemarcade.com/developer/api/server#creategemserver). Every one is optional, and a bundle
+running on the platform normally passes none.
+
+They exist for the two cases the platform does not cover: pointing a bundle at
+something other than the API the platform named, and running it in a test.
+
+## ServerApi
+
+[ServerApi](https://gemarcade.com/developer/api/server#serverapi)
+
+```ts
+type ServerApi = unknown
+```
+
+Every platform operation your server can call, already holding its credential.
+
+This is the surface you spend most of your time in: `gem.api.getGameRoomV2(id)`,
+`gem.api.createOrder(...)`, and the rest. Each method's arguments and return
+type come from the platform's own API description, so what you can pass and
+what you get back are the contract rather than someone's reading of it.
+
+`game_id` is never a parameter. It is filled in from the allocation — in the
+path and the query alike — so a bundle cannot address another game's data even
+by mistake.
+
+The operation list moves with the platform. An operation added to your game's
+API appears here without this package changing, and one that is withdrawn
+stops type-checking rather than failing at runtime.
+
+**Guides.** [server-bundles](https://gemarcade.com/developer/docs/server-bundles)
+
+## ServerBundleHost
+
+[ServerBundleHost](https://gemarcade.com/developer/api/server#serverbundlehost)
+
+```ts
+interface ServerBundleHost
+```
+
+The part of the host object that identifies the match and carries the
+credential.
+
+This is what [createGemServer](https://gemarcade.com/developer/api/server#creategemserver) needs, and nothing more — which is also
+what makes it easy to stand up in a test: four members instead of the whole
+host. [GemServerHost](https://gemarcade.com/developer/api/server#gemserverhost) is the same object at full width.
+
+## ServerTokenGrant
+
+[ServerTokenGrant](https://gemarcade.com/developer/api/server#servertokengrant)
+
+```ts
+interface ServerTokenGrant
+```
+
+A credential the platform handed your server, and when it stops working.
+
+You do not normally touch one. [createGemServer](https://gemarcade.com/developer/api/server#creategemserver) takes the credential
+from the host and refreshes it for you; this type is here for a bundle wiring
+the pieces up itself.
+
+## HostTokenSource
+
+[HostTokenSource](https://gemarcade.com/developer/api/server#hosttokensource)
+
+```ts
+interface HostTokenSource
+```
+
+A credential subscription — what [createHostTokenSource](https://gemarcade.com/developer/api/server#createhosttokensource) gives back.
+
+Deliberately narrow: the only thing you can do with it is stop it. The
+credential itself is not reachable, because nothing you can call takes one.
+
+## GemServerHost
+
+[GemServerHost](https://gemarcade.com/developer/api/server#gemserverhost)
+
+```ts
+interface GemServerHost
+```
+
+The whole `host` object, as the runtime passes it to your bundle.
+
+[ServerBundleHost](https://gemarcade.com/developer/api/server#serverbundlehost) is its credential half; everything added here is the
+match — who is connected, what they sent, and how to answer.
+
+SEVERAL MEMBERS ARE OPTIONAL BECAUSE THE PLATFORM IMAGE MAY BE OLDER than the
+member. There is no version to ask for; presence is the signal. Check before
+calling, and your bundle keeps running on every image rather than only the
+newest.
+
+A bundle written with [defineServer](https://gemarcade.com/developer/api/server#defineserver) usually reads [GemMatchServer](https://gemarcade.com/developer/api/server#gemmatchserver)
+instead, which wraps this.
+
+## GemServerHostProfile
+
+[GemServerHostProfile](https://gemarcade.com/developer/api/server#gemserverhostprofile)
+
+```ts
+interface GemServerHostProfile
+```
+
+A player's display identity, as the platform resolved it for your server.
+
+EVERY FIELD IS OPTIONAL. The platform may not have all of them for a given
+player, and that is not an error — fall back to something of your own.
+
+[GemMatchServer.profile](https://gemarcade.com/developer/api/server#gemmatchserver-profile) is the version you usually want: same
+information, with the name typed as [PlayerText](https://gemarcade.com/developer/api/server#playertext).
+
+## SendOptions
+
+[SendOptions](https://gemarcade.com/developer/api/server#sendoptions)
+
+```ts
+interface SendOptions
+```
+
+What delivery you are ASKING FOR when you send.
+
+A request, not a guarantee in either direction: a transport may deliver an
+unreliable message reliably anyway, and it never does the reverse. What you
+asked for is carried to the receiver either way, so they can tell the
+difference.
+
+## BroadcastOptions
+
+[BroadcastOptions](https://gemarcade.com/developer/api/server#broadcastoptions)
+
+```ts
+interface BroadcastOptions
+```
+
+The same delivery choices as [SendOptions](https://gemarcade.com/developer/api/server#sendoptions), plus who to skip.
+
+## HostTokenSourceOptions
+
+[HostTokenSourceOptions](https://gemarcade.com/developer/api/server#hosttokensourceoptions)
+
+```ts
+interface HostTokenSourceOptions
+```
+
+Options for [createHostTokenSource](https://gemarcade.com/developer/api/server#createhosttokensource).
+
+You need these only if you are wiring the credential up yourself.
+[createGemServer](https://gemarcade.com/developer/api/server#creategemserver) does it for you.
+
+## RoomArgValue
+
+[RoomArgValue](https://gemarcade.com/developer/api/server#roomargvalue)
+
+```ts
+type RoomArgValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[]
+```
+
+What a room setting can be: a string, a number, a boolean, or an array of one
+of those.
+
+FLAT. There is no nested-object arm, because a room's settings schema cannot
+declare one. What you get is what your game's published configuration said a
+room may be created with, already type-checked by the platform before the
+match was allocated — so a bundle reading settings does not need to validate
+them again.
+
+**Guides.** [rooms-and-matches](https://gemarcade.com/developer/docs/rooms-and-matches)
+
+## ServerAnalytics
+
+[ServerAnalytics](https://gemarcade.com/developer/api/server#serveranalytics)
+
+```ts
+interface ServerAnalytics
+```
+
+Your server's analytics — the events you declared in your game config,
+attributed to the player they are about.
+
+Reached as `gem.analytics`. [ServerAnalytics.track](https://gemarcade.com/developer/api/server#serveranalytics-track) is synchronous and
+never throws: it queues, and the queue goes out on a timer, at fifty events,
+and whenever you call [ServerAnalytics.flush](https://gemarcade.com/developer/api/server#serveranalytics-flush).
+
+⚠️ **Flush before your match ends.** A dedicated server is torn down when the
+match is over and nothing gets a last word in for it — there is no `pagehide`
+here. `await gem.analytics.flush()` in `shutdown` is the whole of it.
+
+```js
+export default defineServer((gem) => ({
+  async shutdown() {
+    gem.analytics.track(winner, 'match_result', { outcome: 'win', score: 3100 });
+    await gem.analytics.flush();
+  },
+}));
+```
+
+**Guides.** [analytics](https://gemarcade.com/developer/docs/analytics)
+
+## ServerAnalytics.track
+
+[ServerAnalytics.track](https://gemarcade.com/developer/api/server#serveranalytics-track)
+
+```ts
+track(playerId: string, name: string, props?: Readonly<Record<string, AnalyticsValue>>): void
+```
+
+Record an event about one player. Synchronous, and it never throws.
+
+String values become dimensions and numbers become measures, matched
+against your `analytics_events` declaration server-side — an undeclared
+name or key comes back as a rejection rather than being stored.
+
+⚠️ **The player id is required and is not guessed.** A game-server token
+names no player, so an event from here has to say who it is about; the
+platform will not infer it. Take the id from `join()` or `host.players()`.
+
+⚠️ `gem_` is reserved AND unavailable to a server: the platform's own
+events are client-sourced, so one emitted here would be refused
+`source_not_permitted`. It is refused locally instead.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | The player this event is about. |
+| `name` | `string` | A declared event id — an `id` from your `analytics_events`. |
+| `props` | `Readonly<Record<string, AnalyticsValue>>` | Dimensions (strings) and measures (numbers). |
+
+## ServerAnalytics.flush
+
+[ServerAnalytics.flush](https://gemarcade.com/developer/api/server#serveranalytics-flush)
+
+```ts
+flush(signal?: AbortSignal): Promise<AnalyticsFlushResult>
+```
+
+Send what is queued now, and find out what happened to it.
+
+Resolves with the platform's own answer, INCLUDING per-event rejections, which
+arrive inside a 200 rather than as an error. A refusal that could clear on
+its own — a 429, a 503 — keeps the queue and rejects; one that cannot
+discards the batch, because resending it can only fail the same way.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `signal` | `AbortSignal` | Cancels the call — not the queue. |
+
+## ServerAnalytics.pending
+
+[ServerAnalytics.pending](https://gemarcade.com/developer/api/server#serveranalytics-pending)
+
+```ts
+readonly pending: number
+```
+
+How many events are waiting to go out.
+
+## ServerListChallengesOptions
+
+[ServerListChallengesOptions](https://gemarcade.com/developer/api/server#serverlistchallengesoptions)
+
+```ts
+interface ServerListChallengesOptions
+```
+
+Options for [ServerChallenges.list](https://gemarcade.com/developer/api/server#serverchallenges-list).
+
+## ServerListChallengesOptions.playerId
+
+[ServerListChallengesOptions.playerId](https://gemarcade.com/developer/api/server#serverlistchallengesoptions-playerid)
+
+```ts
+readonly playerId: string
+```
+
+The player whose periods you are asking about. Required.
+
+Take it from `join()` or `gem.players()`, never from something a client
+sent you. The platform answers only for a player who plays your game or is
+in it now, and refuses anyone else with `not_found`.
+
+## ServerListChallengesOptions.periodsBack
+
+[ServerListChallengesOptions.periodsBack](https://gemarcade.com/developer/api/server#serverlistchallengesoptions-periodsback)
+
+```ts
+readonly periodsBack?: number
+```
+
+How many periods back to answer for. `0` — the default — is the period
+running now.
+
+⚠️ **Counted per window**, as in the browser: `1` is yesterday for a
+daily and last week for a weekly. `1` is also what accepts a result the
+player finished just before their day rolled over.
+
+An integer from 0 to 400. Anything else is a `TypeError` before the
+request is made.
+
+## ServerListChallengesOptions.signal
+
+[ServerListChallengesOptions.signal](https://gemarcade.com/developer/api/server#serverlistchallengesoptions-signal)
+
+```ts
+readonly signal?: AbortSignal
+```
+
+Abort the request.
+
+## ServerChallenges
+
+[ServerChallenges](https://gemarcade.com/developer/api/server#serverchallenges)
+
+```ts
+interface ServerChallenges
+```
+
+The challenges your game config declares, for one player, in one period —
+with the date, the seed and the stored content your server verifies a
+result against.
+
+Reached as `gem.challenges`. The browser's `gem.challenges.list()` answers
+for the player holding the token; a server holds no player, so this one
+takes the player's id. Everything else is the same read, and each entry is
+the same [Challenge](https://gemarcade.com/developer/api/server#challenge).
+
+```js
+export default defineServer((gem) => ({
+  async message(playerId, data, isText) {
+    if (!isText) return;
+    const result = JSON.parse(data);
+    const [now, before] = await Promise.all([
+      gem.challenges.list({ playerId }),
+      gem.challenges.list({ playerId, periodsBack: 1 }),
+    ]);
+    const played = [...now, ...before].find(
+      (c) =>
+        c.id === result.challengeId &&
+        (c.periodLocalDate ?? c.seed) === result.period &&
+        c.dataHash === result.dataHash,
+    );
+    if (!played) return gem.send(playerId, 'rejected');
+    // ...check the result against played.data
+  },
+}));
+```
+
+## ServerChallenges.list
+
+[ServerChallenges.list](https://gemarcade.com/developer/api/server#serverchallenges-list)
+
+```ts
+list(options: ServerListChallengesOptions): Promise<Challenge[]>
+```
+
+Every challenge your config declares, for one player, for one period.
+
+⚠️ **Verify against the player's period, never your own clock.** A
+player's day ends at their own midnight, so the date and the seed you hold
+for one player are not another player's, and "today" on the machine this
+runs on is neither. Ask per player, and match on
+[Challenge.periodLocalDate](https://gemarcade.com/developer/api/server#challenge-periodlocaldate) — or [Challenge.seed](https://gemarcade.com/developer/api/server#challenge-seed) for a
+`cron` challenge — never on [Challenge.periodStartAt](https://gemarcade.com/developer/api/server#challenge-periodstartat).
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `ServerListChallengesOptions` |
+
+**Throws.** `TypeError` when `playerId` is missing or empty, or `periodsBack`
+  is not an integer from 0 to 400 — refused before the request.
+
+`GemApiError` with `reason: 'not_found'` for a player who neither
+  plays your game nor is in it now, and for a channel with no config.
+
+## GameApi
+
+[GameApi](https://gemarcade.com/developer/api/server#gameapi)
+
+```ts
+interface GameApi
+```
+
+What a generated call needs in order to make itself: the client that sends
+it, and the game it belongs to.
+
+YOU DO NOT BUILD ONE. `createGemServer` does, and hands you the operations
+already holding it as `gem.api`. It is named here because it appears in the
+type of those operations, so a helper of your own that takes them has to be
+able to spell it.
+
+`gameId` is a call rather than a field because the game is not known until
+the platform has issued a credential, which happens after the client exists.
+It is never something a caller passes: a bundle cannot address another
+game's data because it never types a game id, in a path or in a query.
+
+## GameApi.client
+
+[GameApi.client](https://gemarcade.com/developer/api/server#gameapi-client)
+
+```ts
+readonly client: GemClient
+```
+
+The client every operation sends through.
+
+## GameApi.gameId
+
+[GameApi.gameId](https://gemarcade.com/developer/api/server#gameapi-gameid)
+
+```ts
+gameId(): string
+```
+
+The game this server is running — taken from its credential.
+
+## PlayerText
+
+[PlayerText](https://gemarcade.com/developer/api/server#playertext)
+
+```ts
+class PlayerText
+```
+
+A player-authored string, which your game must convert before rendering.
+
+Player names are chosen by players, and length limits are not content limits.
+If your game assigned one straight to `innerHTML`, whoever picked that name
+would be running code on your page — with your play token, which is the whole
+session. So the SDK does not hand you a string: it hands you this, and the
+unsafe thing does not compile.
+
+There is exactly one way out, and it belongs at your model boundary:
+
+```js
+import { text } from '@indiegems/gem-web-sdk/sdk';
+
+const name = text.toPlain(profile.displayName);
+label.textContent = name;
+```
+
+To sort names, use [text.compare](https://gemarcade.com/developer/api/server#text-compare) rather than converting first — it is
+locale-aware, which a plain `<` comparison is not.
+
+## PlayerText.toString
+
+[PlayerText.toString](https://gemarcade.com/developer/api/server#playertext-tostring)
+
+```ts
+toString(): string
+```
+
+A sentinel that names its own fix, never the player's text.
+
+If you see `[gem: use gem.text.toPlain()]` on screen, something rendered
+the wrapper instead of converting it. That is the gate working — the
+alternative was shipping an unescaped player name.
+
+⚠️ THE SENTINEL NAMES `gem.text`, WHICH DOES NOT EXIST. `text` is imported
+from the package — `import { text } from '@indiegems/gem-web-sdk/sdk';` —
+not reached from your `gem` instance. Follow that rather than the message.
+
+## PlayerText.toJSON
+
+[PlayerText.toJSON](https://gemarcade.com/developer/api/server#playertext-tojson)
+
+```ts
+toJSON(): string
+```
+
+The same sentinel, so putting a player name into a save blob or a telemetry
+payload cannot silently store unescaped text.
+
+Convert with [text.toPlain](https://gemarcade.com/developer/api/server#text-toplain) before serialising anything you intend to
+keep.
+
+## text
+
+[text](https://gemarcade.com/developer/api/server#text)
+
+```ts
+text: { toPlain: null; compare: null; equals: null }
+```
+
+The only ways out of [PlayerText](https://gemarcade.com/developer/api/server#playertext).
+
+Imported from the package rather than reached from `gem`:
+`import { text } from '@indiegems/gem-web-sdk/sdk';`
+
+Two calls:
+
+- `toPlain(value)` — the plain string, safe for `textContent`, canvas
+  `fillText` and interpolation. The one call you make, and it belongs at your
+  model boundary rather than scattered through render code.
+- `compare(a, b, locale?)` — locale-aware comparison for sorting rosters and
+  leaderboards. Use it instead of converting and comparing with `<`, which
+  sorts by code point and gets accented and non-Latin names wrong. It accepts
+  plain strings too, because real leaderboards mix player names with rows
+  your game authored, and it falls back rather than throwing on a bad locale
+  tag — a throw inside a comparator takes the whole sort down.
+
+```js
+import { text } from '@indiegems/gem-web-sdk/sdk';
+
+const name = text.toPlain(profile.displayName);
+players.sort((a, b) => text.compare(a.displayName, b.displayName, locale));
+```
+
+THERE IS DELIBERATELY NO `toHtml`. Escaping depends on where the value
+lands — safe in element text and quoted attributes, unsafe in URL, style and
+script contexts — and your framework already escapes. One unambiguous
+function beats two where one carries a caveat.
+
+## text.toPlain
+
+[text.toPlain](https://gemarcade.com/developer/api/server#text-toplain)
+
+```ts
+toPlain(t: PlayerText): string
+```
+
+The plain string, safe for `textContent`, canvas `fillText` and
+interpolation.
+
+The one call you make, and it belongs at your model boundary rather than
+scattered through your render code:
+
+```js
+const name = text.toPlain(profile.displayName);
+```
+
+Safe for text; NOT pre-escaped for HTML. Do not put the result into
+`innerHTML`, a URL, a style or a script — convert at the boundary and let
+your framework escape, which is what it already does.
+
+| Parameter | Type |
+| --- | --- |
+| `t` | `PlayerText` |
+
+## text.compare
+
+[text.compare](https://gemarcade.com/developer/api/server#text-compare)
+
+```ts
+compare(a: string | PlayerText, b: string | PlayerText, locale?: string): number
+```
+
+Locale-aware comparison, for sorting rosters and leaderboards.
+
+Use this rather than converting to strings and comparing with `<`, which
+sorts by code point and gets accented and non-Latin names wrong.
+
+```js
+players.sort((a, b) => text.compare(a.displayName, b.displayName, locale));
+```
+
+Accepts plain strings as well as player text, because real leaderboards mix
+player names with rows your game authored. Pass the player's locale from
+`GemPrefs.locale`; without one it uses the runtime's. A malformed
+locale tag falls back rather than throwing — this is a comparator, and a
+throw here would take the whole sort down with it.
+
+| Parameter | Type |
+| --- | --- |
+| `a` | `string \| PlayerText` |
+| `b` | `string \| PlayerText` |
+| `locale` | `string` |
+
+## text.equals
+
+[text.equals](https://gemarcade.com/developer/api/server#text-equals)
+
+```ts
+equals(a: string | PlayerText, b: string | PlayerText): boolean
+```
+
+Whether two names are the same name, without unwrapping either.
+
+Compares normalised forms, so two spellings of the same name — one
+composed, one decomposed — come out equal. That matters because a name may
+reach your game from somewhere other than the arcade.
+
+**KEY YOUR ROWS ON THE PLAYER'S ID, NEVER ON A NAME.** Names are not
+identifiers: two players can choose the same one, and a player can change
+theirs. Use this for display-level comparisons, not for identity.
+
+| Parameter | Type |
+| --- | --- |
+| `a` | `string \| PlayerText` |
+| `b` | `string \| PlayerText` |
+
+## AchievementReceipt.achievementId
+
+[AchievementReceipt.achievementId](https://gemarcade.com/developer/api/server#achievementreceipt-achievementid)
+
+```ts
+readonly achievementId: string
+```
+
+The achievement's id, as your game config declares it.
+
+## AchievementReceipt.progressionDefinitionId
+
+[AchievementReceipt.progressionDefinitionId](https://gemarcade.com/developer/api/server#achievementreceipt-progressiondefinitionid)
+
+```ts
+readonly progressionDefinitionId: string
+```
+
+The progression the achievement sits on.
+
+## AchievementReceipt.points
+
+[AchievementReceipt.points](https://gemarcade.com/developer/api/server#achievementreceipt-points)
+
+```ts
+readonly points: number
+```
+
+Achievement points the unlock credited. Zero unless `outcome` is
+`unlocked`, so summing it over receipts counts only what this order
+credited.
+
+## AchievementReceipt.outcome
+
+[AchievementReceipt.outcome](https://gemarcade.com/developer/api/server#achievementreceipt-outcome)
+
+```ts
+readonly outcome: "unlocked" | "already_unlocked" | "suppressed"
+```
+
+`unlocked`: this order unlocked it. `already_unlocked`: this order crossed
+the threshold again, after a reset, and the player already holds it.
+`suppressed`: it was not unlocked, and `reason` says why.
+
+The set may grow. A receipt with an outcome this SDK does not know is
+left out rather than reported as one of these, so a `switch` over these
+three needs no default for correctness — but write one anyway.
+
+## AchievementReceipt.reason
+
+[AchievementReceipt.reason](https://gemarcade.com/developer/api/server#achievementreceipt-reason)
+
+```ts
+readonly reason?: string
+```
+
+Why a `suppressed` achievement was not unlocked — for example
+`channel=dev`, `principal=developer-minted server token` (a server you
+started yourself rather than one the platform allocated),
+`achievements_disabled`, `written_by_config` (something in your config —
+a recipe, a loot table, a reward — can raise the progression, so a paying
+achievement on it never unlocks), or `achievements_unavailable`
+(transient; the next eligible write tries again). For your logs and your
+developer tools; not text to show a player.
+
+## GemServerOptions.baseUrl
+
+[GemServerOptions.baseUrl](https://gemarcade.com/developer/api/server#gemserveroptions-baseurl)
+
+```ts
+readonly baseUrl?: string
+```
+
+Where to send API calls, INSTEAD of where the platform said.
+
+The host already names it, and a bundle running for real should not
+second-guess that. This is for a rig — a tunnel, an API running on your own
+machine — not for choosing which environment you are in. Setting it in a
+shipped bundle means your server talks to somewhere the platform did not
+send it.
+
+## GemServerOptions.clock
+
+[GemServerOptions.clock](https://gemarcade.com/developer/api/server#gemserveroptions-clock)
+
+```ts
+readonly clock?: Clock
+```
+
+Where time comes from. Defaults to the real clock.
+
+Pass a [Clock](https://gemarcade.com/developer/api/server#clock) in a test so token refresh and retry backoff happen when
+you say rather than when a real second passes.
+
+## GemServerOptions.fetch
+
+[GemServerOptions.fetch](https://gemarcade.com/developer/api/server#gemserveroptions-fetch)
+
+```ts
+readonly fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+```
+
+The `fetch` used for every call. Defaults to the runtime's own.
+
+For tests: a stub here is how you assert what your bundle sends without a
+network.
+
+## GemServerOptions.onAuthStateChange
+
+[GemServerOptions.onAuthStateChange](https://gemarcade.com/developer/api/server#gemserveroptions-onauthstatechange)
+
+```ts
+readonly onAuthStateChange?: (state: AuthState, reason?: AuthFailure) => void
+```
+
+Called whenever the server's ability to make authenticated calls changes.
+
+The same signal the browser half delivers to a game, for the same reason:
+the token is refreshed for you, and this is how you find out when that stops
+working. See [AuthState](https://gemarcade.com/developer/api/server#authstate) for what to branch on and [AuthFailure](https://gemarcade.com/developer/api/server#authfailure)
+for the cause.
+
+## GemServerIdentity.gameId
+
+[GemServerIdentity.gameId](https://gemarcade.com/developer/api/server#gemserveridentity-gameid)
+
+```ts
+readonly gameId: string
+```
+
+The game this server belongs to.
+
+## GemServerIdentity.channel
+
+[GemServerIdentity.channel](https://gemarcade.com/developer/api/server#gemserveridentity-channel)
+
+```ts
+readonly channel: string
+```
+
+The channel it was allocated on — `dev`, `test` or `release`.
+
+## GemServerIdentity.matchId
+
+[GemServerIdentity.matchId](https://gemarcade.com/developer/api/server#gemserveridentity-matchid)
+
+```ts
+readonly matchId: string
+```
+
+The match it is running.
+
+## GemServerIdentity.gameRoomId
+
+[GemServerIdentity.gameRoomId](https://gemarcade.com/developer/api/server#gemserveridentity-gameroomid)
+
+```ts
+readonly gameRoomId?: string
+```
+
+The room this match came from, when there is one.
+
+CHECK IT BEFORE USING IT. It is absent on older platform images, which is
+also why [GemServer.room](https://gemarcade.com/developer/api/server#gemserver-room) can be absent — the two go together.
+
+## GemServer.identity
+
+[GemServer.identity](https://gemarcade.com/developer/api/server#gemserver-identity)
+
+```ts
+readonly identity: GemServerIdentity
+```
+
+Which game, channel and match this server is running.
+
+## GemServer.client
+
+[GemServer.client](https://gemarcade.com/developer/api/server#gemserver-client)
+
+```ts
+readonly client: GemClient
+```
+
+The HTTP client underneath [GemServer.api](https://gemarcade.com/developer/api/server#gemserver-api), for calls the generated
+surface does not cover.
+
+PREFER `api`. It is typed against the platform's description, so a shape
+that changes becomes a build error in your bundle. This one takes a path and
+checks nothing — reach for it when you genuinely need something `api` has
+no method for, and treat that as worth telling us about.
+
+## GemServer.api
+
+[GemServer.api](https://gemarcade.com/developer/api/server#gemserver-api)
+
+```ts
+readonly api: ServerApi
+```
+
+Every platform operation your server can call. This is the one you want.
+
+See [ServerApi](https://gemarcade.com/developer/api/server#serverapi).
+
+## GemServer.match
+
+[GemServer.match](https://gemarcade.com/developer/api/server#gemserver-match)
+
+```ts
+readonly match: { end: null }
+```
+
+Ending the match.
+
+`end()` is HOW A SERVER-AUTHORITATIVE GAME FINISHES. It tells the platform
+the match is over; the platform then tells the runtime, and your server
+winds down through its ordinary shutdown. You do not stop the process
+yourself.
+
+It always means THIS match — the id is already known, so there is nothing to
+pass and no way to end someone else's.
+
+The platform half makes the request, not your process: it holds the proof
+that this server is the one allocated to the match, which the platform
+requires. On a platform image too old to offer that, `end()` throws rather
+than sending a request without the proof.
+
+## GemServer.match.end
+
+[GemServer.match.end](https://gemarcade.com/developer/api/server#gemserver-match-end)
+
+```ts
+end(signal?: AbortSignal): Promise<void>
+```
+
+Tell the platform this match is finished.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `signal` | `AbortSignal` | Not used — the platform half bounds its own request. |
+
+**Throws.** When the platform image running this server predates
+  `host.endMatch`, so the match cannot be ended from here.
+
+## GemServer.analytics
+
+[GemServer.analytics](https://gemarcade.com/developer/api/server#gemserver-analytics)
+
+```ts
+readonly analytics: ServerAnalytics
+```
+
+Recording analytics events about the players in this match.
+
+THE AUTHORITATIVE HALF of the pair. The browser's `gem.analytics` records
+game-asserted browser facts, which feed a developer's own numbers and
+nothing the platform treats as true; a server holds a credential the player
+does not, so what it records about a run, a score or an outcome is the
+counterpart a game reaches for when the browser's word is not enough. A
+game may declare an event `sources: [server]` and shut the client out of it
+entirely.
+
+⚠️ **Every event names its player, and `gem_*` is unavailable here** — see
+[ServerAnalytics.track](https://gemarcade.com/developer/api/server#serveranalytics-track). And flush before the match ends: there is no
+page unload to get the tail out on.
+
+## GemServer.functions
+
+[GemServer.functions](https://gemarcade.com/developer/api/server#gemserver-functions)
+
+```ts
+readonly functions: FunctionsApi
+```
+
+Your game's serverless function — `gem.functions.invoke(input)`, the same
+call a game makes in the browser.
+
+The call arrives as this server, not as a player: your function's
+`get-context` says so, and a server's per-minute budget is its own. It runs
+the function promoted on the channel this match runs on.
+
+## GemServer.challenges
+
+[GemServer.challenges](https://gemarcade.com/developer/api/server#gemserver-challenges)
+
+```ts
+readonly challenges: ServerChallenges
+```
+
+A player's daily challenges — their period, its date, the seed, and any
+content your studio stored — so your server verifies a result against the
+board that player was actually given.
+
+A period is the PLAYER's, not the calendar's: it ends at their own
+midnight. That is why this takes a player id where the browser's
+`gem.challenges` takes none. See [ServerChallenges.list](https://gemarcade.com/developer/api/server#serverchallenges-list).
+
+## GemServer.room
+
+[GemServer.room](https://gemarcade.com/developer/api/server#gemserver-room)
+
+```ts
+readonly room?: { get: (options?: { ifNoneMatch?: string; signal?: AbortSignal }) => Promise<VersionedResponse<GameRoomResponseV2>>; args: (options?: { signal?: AbortSignal }) => Promise<RoomArgsResponse> }
+```
+
+Reading the room this match came from — the two calls almost every server
+makes at startup, already pointed at your own room.
+
+CHECK IT IS THERE. `room` is absent on older platform images, which is why
+the type says it might be. `gem.room?.get()` is the shape to write. When it
+is absent the same reads are still available through `api` if you know the
+room id from somewhere else.
+
+## GemServer.room.get
+
+[GemServer.room.get](https://gemarcade.com/developer/api/server#gemserver-room-get)
+
+```ts
+get: (options?: { ifNoneMatch?: string; signal?: AbortSignal }) => Promise<VersionedResponse<GameRoomResponseV2>>
+```
+
+The room, in full: the settings it was created with, the template those
+came from, and every member — with display name, role, ready state and
+avatar.
+
+This is what you want at `start()`, and it is a superset of what the older
+roster push carried.
+
+## GemServer.room.args
+
+[GemServer.room.args](https://gemarcade.com/developer/api/server#gemserver-room-args)
+
+```ts
+args: (options?: { signal?: AbortSignal }) => Promise<RoomArgsResponse>
+```
+
+Just the room's settings.
+
+A room whose template declares no settings answers 404
+`room_args_not_defined` rather than an empty object — "this room has no
+settings" and "this room's settings are empty" are different answers and
+the API keeps them apart.
+
+## GemServer.dispose
+
+[GemServer.dispose](https://gemarcade.com/developer/api/server#gemserver-dispose)
+
+```ts
+dispose(): void
+```
+
+Stop listening for credential updates.
+
+You rarely need it: a bundle built with [defineServer](https://gemarcade.com/developer/api/server#defineserver) is disposed for
+you when the match ends. Call it in a test, or if you built the server
+yourself and are tearing it down.
+
+## ServerTokenGrant.token
+
+[ServerTokenGrant.token](https://gemarcade.com/developer/api/server#servertokengrant-token)
+
+```ts
+readonly token: string
+```
+
+The credential to present. Never log it and never send it on.
+
+## ServerTokenGrant.expiresAt
+
+[ServerTokenGrant.expiresAt](https://gemarcade.com/developer/api/server#servertokengrant-expiresat)
+
+```ts
+readonly expiresAt: number
+```
+
+When it expires, in seconds since the Unix epoch.
+
+## ServerBundleHost.matchId
+
+[ServerBundleHost.matchId](https://gemarcade.com/developer/api/server#serverbundlehost-matchid)
+
+```ts
+readonly matchId: string
+```
+
+The match this server was allocated for.
+
+## ServerBundleHost.gameId
+
+[ServerBundleHost.gameId](https://gemarcade.com/developer/api/server#serverbundlehost-gameid)
+
+```ts
+readonly gameId: string
+```
+
+The game it belongs to.
+
+## ServerBundleHost.channel
+
+[ServerBundleHost.channel](https://gemarcade.com/developer/api/server#serverbundlehost-channel)
+
+```ts
+readonly channel: string
+```
+
+The channel it was allocated on — `dev`, `test` or `release`.
+
+## ServerBundleHost.gameRoomId
+
+[ServerBundleHost.gameRoomId](https://gemarcade.com/developer/api/server#serverbundlehost-gameroomid)
+
+```ts
+readonly gameRoomId?: string
+```
+
+The room this match came from. MAY BE ABSENT on older platform images, so
+check before using it — that absence is also why [GemServer.room](https://gemarcade.com/developer/api/server#gemserver-room) can
+be missing.
+
+## ServerBundleHost.apiBaseUrl
+
+[ServerBundleHost.apiBaseUrl](https://gemarcade.com/developer/api/server#serverbundlehost-apibaseurl)
+
+```ts
+readonly apiBaseUrl?: string
+```
+
+Where to send API calls. Absent on older platform images, which is the case
+[createGemServer](https://gemarcade.com/developer/api/server#creategemserver) refuses at startup.
+
+## ServerBundleHost.serverToken
+
+[ServerBundleHost.serverToken](https://gemarcade.com/developer/api/server#serverbundlehost-servertoken)
+
+```ts
+serverToken(): ServerTokenGrant | undefined
+```
+
+The credential held right now, if the platform delivered one.
+
+## ServerBundleHost.onServerToken
+
+[ServerBundleHost.onServerToken](https://gemarcade.com/developer/api/server#serverbundlehost-onservertoken)
+
+```ts
+onServerToken(listener: (grant: ServerTokenGrant) => void): () => void
+```
+
+Be told when the credential is replaced.
+
+Called straight away if one is already held, and again on every refresh.
+Returns a function that stops the notifications.
+
+You rarely call this. [createGemServer](https://gemarcade.com/developer/api/server#creategemserver) subscribes for you.
+
+| Parameter | Type |
+| --- | --- |
+| `listener` | `(grant: ServerTokenGrant) => void` |
+
+## SendOptions.reliable
+
+[SendOptions.reliable](https://gemarcade.com/developer/api/server#sendoptions-reliable)
+
+```ts
+readonly reliable?: boolean
+```
+
+Ask for the message to arrive. Defaults to true.
+
+`false` says you would rather it be dropped than delayed — position updates
+that a later one supersedes. A transport is free to deliver it reliably
+anyway; the receiver is still told what you asked for.
+
+## SendOptions.ordered
+
+[SendOptions.ordered](https://gemarcade.com/developer/api/server#sendoptions-ordered)
+
+```ts
+readonly ordered?: boolean
+```
+
+Ask for messages to arrive in the order you sent them. Defaults to true.
+
+## BroadcastOptions.reliable
+
+[BroadcastOptions.reliable](https://gemarcade.com/developer/api/server#broadcastoptions-reliable)
+
+```ts
+readonly reliable?: boolean
+```
+
+Ask for the message to arrive. Defaults to true.
+
+`false` says you would rather it be dropped than delayed — position updates
+that a later one supersedes. A transport is free to deliver it reliably
+anyway; the receiver is still told what you asked for.
+
+## BroadcastOptions.ordered
+
+[BroadcastOptions.ordered](https://gemarcade.com/developer/api/server#broadcastoptions-ordered)
+
+```ts
+readonly ordered?: boolean
+```
+
+Ask for messages to arrive in the order you sent them. Defaults to true.
+
+## BroadcastOptions.except
+
+[BroadcastOptions.except](https://gemarcade.com/developer/api/server#broadcastoptions-except)
+
+```ts
+readonly except?: string
+```
+
+A player to leave out — usually the one whose action caused the broadcast.
+
+## GemServerHostProfile.displayName
+
+[GemServerHostProfile.displayName](https://gemarcade.com/developer/api/server#gemserverhostprofile-displayname)
+
+```ts
+readonly displayName?: string
+```
+
+The player's chosen name, as a plain string.
+
+PREFER [GemMatchServer.profile](https://gemarcade.com/developer/api/server#gemmatchserver-profile), which gives you the same name as
+[PlayerText](https://gemarcade.com/developer/api/server#playertext) — a type that reminds you a stranger wrote it.
+
+## GemServerHostProfile.displayTag
+
+[GemServerHostProfile.displayTag](https://gemarcade.com/developer/api/server#gemserverhostprofile-displaytag)
+
+```ts
+readonly displayTag?: string
+```
+
+The precomposed `Name#0001`, as a plain string. It contains the name, so
+PREFER [GemMatchServer.profile](https://gemarcade.com/developer/api/server#gemmatchserver-profile), which gives it as [PlayerText](https://gemarcade.com/developer/api/server#playertext).
+
+## GemServerHostProfile.discriminator
+
+[GemServerHostProfile.discriminator](https://gemarcade.com/developer/api/server#gemserverhostprofile-discriminator)
+
+```ts
+readonly discriminator?: string
+```
+
+The disambiguating suffix, when the player has one.
+
+## GemServerHost.matchId
+
+[GemServerHost.matchId](https://gemarcade.com/developer/api/server#gemserverhost-matchid)
+
+```ts
+readonly matchId: string
+```
+
+The match this server was allocated for.
+
+## GemServerHost.gameId
+
+[GemServerHost.gameId](https://gemarcade.com/developer/api/server#gemserverhost-gameid)
+
+```ts
+readonly gameId: string
+```
+
+The game it belongs to.
+
+## GemServerHost.channel
+
+[GemServerHost.channel](https://gemarcade.com/developer/api/server#gemserverhost-channel)
+
+```ts
+readonly channel: string
+```
+
+The channel it was allocated on — `dev`, `test` or `release`.
+
+## GemServerHost.gameRoomId
+
+[GemServerHost.gameRoomId](https://gemarcade.com/developer/api/server#gemserverhost-gameroomid)
+
+```ts
+readonly gameRoomId?: string
+```
+
+The room this match came from. MAY BE ABSENT on older platform images, so
+check before using it — that absence is also why [GemServer.room](https://gemarcade.com/developer/api/server#gemserver-room) can
+be missing.
+
+## GemServerHost.apiBaseUrl
+
+[GemServerHost.apiBaseUrl](https://gemarcade.com/developer/api/server#gemserverhost-apibaseurl)
+
+```ts
+readonly apiBaseUrl?: string
+```
+
+Where to send API calls. Absent on older platform images, which is the case
+[createGemServer](https://gemarcade.com/developer/api/server#creategemserver) refuses at startup.
+
+## GemServerHost.serverToken
+
+[GemServerHost.serverToken](https://gemarcade.com/developer/api/server#gemserverhost-servertoken)
+
+```ts
+serverToken(): ServerTokenGrant | undefined
+```
+
+The credential held right now, if the platform delivered one.
+
+## GemServerHost.onServerToken
+
+[GemServerHost.onServerToken](https://gemarcade.com/developer/api/server#gemserverhost-onservertoken)
+
+```ts
+onServerToken(listener: (grant: ServerTokenGrant) => void): () => void
+```
+
+Be told when the credential is replaced.
+
+Called straight away if one is already held, and again on every refresh.
+Returns a function that stops the notifications.
+
+You rarely call this. [createGemServer](https://gemarcade.com/developer/api/server#creategemserver) subscribes for you.
+
+| Parameter | Type |
+| --- | --- |
+| `listener` | `(grant: ServerTokenGrant) => void` |
+
+## GemServerHost.sizeClass
+
+[GemServerHost.sizeClass](https://gemarcade.com/developer/api/server#gemserverhost-sizeclass)
+
+```ts
+readonly sizeClass: string
+```
+
+Which size of machine this server was allocated on.
+
+## GemServerHost.roomArgs
+
+[GemServerHost.roomArgs](https://gemarcade.com/developer/api/server#gemserverhost-roomargs)
+
+```ts
+readonly roomArgs?: Readonly<Record<string, RoomArgValue>>
+```
+
+**Deprecated.** Read `gem.room?.args()` instead — it gets the same settings from
+the platform and distinguishes "no settings are declared" from "they are
+declared and empty".
+
+Still delivered today. The member keeps compiling for the rest of `3.x`,
+and `4.0.0` is the earliest release that may take it off the type. Whether
+a server keeps sending a value is a separate question, decided where the
+dedicated-server image is built rather than by a package release — so check
+for the room read and keep this as the fallback. Both halves are in
+[the deprecation policy](https://gemarcade.com/developer/docs/deprecation-policy).
+
+The room's settings as they were at match start.
+
+`undefined` covers two cases you cannot tell apart and do not need to: the
+room type declares no settings, or the platform image is older than this
+member.
+
+## GemServerHost.roster
+
+[GemServerHost.roster](https://gemarcade.com/developer/api/server#gemserverhost-roster)
+
+```ts
+readonly roster: readonly string[]
+```
+
+**Deprecated.** Read `gem.room?.get()` instead — live membership, with names,
+roles and ready state.
+
+Still delivered today. The member keeps compiling for the rest of `3.x`,
+and `4.0.0` is the earliest release that may take it off the type. Whether
+a server keeps sending a value is a separate question, decided where the
+dedicated-server image is built rather than by a package release — so check
+for the room read and keep this as the fallback. Both halves are in
+[the deprecation policy](https://gemarcade.com/developer/docs/deprecation-policy).
+
+Who was in the room when this server was allocated.
+
+A SIZING HINT, NOT A GUEST LIST. It is never revised, and it does not decide
+who may connect — the platform admits players by credential. A player who
+joined after allocation holds a valid one and is not in here.
+
+## GemServerHost.players
+
+[GemServerHost.players](https://gemarcade.com/developer/api/server#gemserverhost-players)
+
+```ts
+players(): string[]
+```
+
+The player ids connected right now, as a fresh array each call.
+
+## GemServerHost.profile
+
+[GemServerHost.profile](https://gemarcade.com/developer/api/server#gemserverhost-profile)
+
+```ts
+profile(playerId: string): GemServerHostProfile | undefined
+```
+
+A player's display identity, if the platform resolved one.
+
+OPTIONAL TWICE OVER: the method itself may be absent on an older platform
+image, and it may answer `undefined` for a player it has nothing for.
+[GemMatchServer.profile](https://gemarcade.com/developer/api/server#gemmatchserver-profile) collapses both into one `null`.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+
+## GemServerHost.playerNumber
+
+[GemServerHost.playerNumber](https://gemarcade.com/developer/api/server#gemserverhost-playernumber)
+
+```ts
+playerNumber(playerId: string): number | undefined
+```
+
+The 1-based seat the platform gave a connected player.
+
+May be absent as a method on an older platform image, and answers
+`undefined` for an id it has not seated.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+
+## GemServerHost.send
+
+[GemServerHost.send](https://gemarcade.com/developer/api/server#gemserverhost-send)
+
+```ts
+send(playerId: string, data: string | Uint8Array<ArrayBufferLike>, options?: SendOptions): void
+```
+
+Send to one player. A string goes as text; bytes go as binary, and the
+receiver is told which.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` |  |
+| `data` | `string \| Uint8Array<ArrayBufferLike>` |  |
+| `options` | `SendOptions` | What delivery you are asking for — see [SendOptions](https://gemarcade.com/developer/api/server#sendoptions).
+  Pass them freely: an older platform image ignores them harmlessly. |
+
+## GemServerHost.broadcast
+
+[GemServerHost.broadcast](https://gemarcade.com/developer/api/server#gemserverhost-broadcast)
+
+```ts
+broadcast(data: string | Uint8Array<ArrayBufferLike>, options?: BroadcastOptions): void
+```
+
+Send to every connected player. See [BroadcastOptions](https://gemarcade.com/developer/api/server#broadcastoptions) for how, and
+for leaving one out.
+
+| Parameter | Type |
+| --- | --- |
+| `data` | `string \| Uint8Array<ArrayBufferLike>` |
+| `options` | `BroadcastOptions` |
+
+## GemServerHost.kick
+
+[GemServerHost.kick](https://gemarcade.com/developer/api/server#gemserverhost-kick)
+
+```ts
+kick(playerId: string, reason?: string): void
+```
+
+Disconnect a player. `reason` is shown to them and recorded in the logs.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+| `reason` | `string` |
+
+## GemServerHost.endMatch
+
+[GemServerHost.endMatch](https://gemarcade.com/developer/api/server#gemserverhost-endmatch)
+
+```ts
+endMatch(): Promise<"ok" | "already_ended" | "refused" | "failed" | string & object>
+```
+
+Ask the platform half to end this match, with the allocation's own proof.
+
+MAY BE ABSENT on older platform images. `gem.match.end()` is this call —
+the request carries the allocation nonce, which never enters the bundle
+process — and refuses on an image that does not offer it. You rarely call
+this yourself.
+
+Resolves with what the platform half did: `ok`, `already_ended` (this
+match was already over, or you asked twice), `refused` (the allocation was
+not ready yet) or `failed` (the platform could not be reached).
+
+## GemServerHost.log
+
+[GemServerHost.log](https://gemarcade.com/developer/api/server#gemserverhost-log)
+
+```ts
+log(message: string): void
+```
+
+Write a line to the match's logs.
+
+THE ONLY ROUTE. `console.log` writes to standard output, which is how the
+runtime talks to your server — a line written there arrives as a complaint
+about your bundle rather than as a log.
+
+| Parameter | Type |
+| --- | --- |
+| `message` | `string` |
+
+## GemServerHost.warn
+
+[GemServerHost.warn](https://gemarcade.com/developer/api/server#gemserverhost-warn)
+
+```ts
+warn(message: string): void
+```
+
+Like [GemServerHost.log](https://gemarcade.com/developer/api/server#gemserverhost-log), marked as a warning.
+
+| Parameter | Type |
+| --- | --- |
+| `message` | `string` |
+
+## HostTokenSourceOptions.clock
+
+[HostTokenSourceOptions.clock](https://gemarcade.com/developer/api/server#hosttokensourceoptions-clock)
+
+```ts
+readonly clock: Clock
+```
+
+Where time comes from — used for expiry and for the wait below. Pass a
+[Clock](https://gemarcade.com/developer/api/server#clock) in a test.
+
+## HostTokenSourceOptions.timeoutMs
+
+[HostTokenSourceOptions.timeoutMs](https://gemarcade.com/developer/api/server#hosttokensourceoptions-timeoutms)
+
+```ts
+readonly timeoutMs?: number
+```
+
+How long to wait for the platform to deliver a credential before giving up
+on a call. Defaults to 10 seconds.
+
+## HostTokenSourceOptions.onStateChange
+
+[HostTokenSourceOptions.onStateChange](https://gemarcade.com/developer/api/server#hosttokensourceoptions-onstatechange)
+
+```ts
+readonly onStateChange?: (state: AuthState, reason?: AuthFailure) => void
+```
+
+Called when the ability to make authenticated calls changes. See
+[AuthState](https://gemarcade.com/developer/api/server#authstate) for what to branch on.
+
+## HostTokenSource.dispose
+
+[HostTokenSource.dispose](https://gemarcade.com/developer/api/server#hosttokensource-dispose)
+
+```ts
+dispose(): void
+```
+
+Stop refreshing the credential.
+
+CALL IT AT SHUTDOWN. A pending refresh timer keeps the process alive, so a
+bundle that skips this looks like it has hung rather than exited.
+
+## GemServerBundle.init
+
+[GemServerBundle.init](https://gemarcade.com/developer/api/server#gemserverbundle-init)
+
+```ts
+init(): void | Promise<void>
+```
+
+Once, before any player arrives. Set your world up here.
+
+YOU HAVE 60 SECONDS. Throwing fails the match, so do not start anything here
+you are not prepared to have fail loudly.
+
+## GemServerBundle.join
+
+[GemServerBundle.join](https://gemarcade.com/developer/api/server#gemserverbundle-join)
+
+```ts
+join(playerId: string, meta?: { playerNumber?: number; transport?: string; rejoin?: boolean; superseded?: boolean }): void | Promise<void>
+```
+
+A player connected, and the platform has already verified who they are.
+
+They are ALREADY in `host.players()` by the time this runs.
+
+`meta.rejoin` marks a player the platform has already seen in this match,
+as against a first arrival — the cue to restore what you kept for them
+instead of seating them anew. `meta.playerNumber` is the number they
+already had, so state you keyed by it still applies.
+
+Read `rejoin` as a FLOOR, not a decision procedure. It is absent, not
+`false`, when unset, and an older platform image sets it only for the
+narrow case where the player's previous connection was still open when the
+new one landed — a reconnect it had already reaped arrives unmarked there.
+So an absent `rejoin` means "not known to be a reconnect", never
+"certainly a new player", and `playerNumber` is what to key state by
+either way.
+
+`meta.superseded` narrows a rejoin further: the player's EARLIER
+connection was still attached when this one landed, so they never really
+left — the `leave` you heard a moment ago (its `cause` is `superseded`)
+was synthetic, and the pair is one reconnect rather than a departure and
+a return. Without it a bundle could not tell that pair from a genuine
+drop-and-rejoin, and so could not decide whether to hold a team, a slot
+or a score for a player. Present on the
+dedicated runtime and on a listen host alike; absent, not `false`, when
+nothing was superseded, and on platform images that predate it.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | Who joined. Take ids from here rather than from anything a
+  client sent you. |
+| `meta` | `{ playerNumber?: number; transport?: string; rejoin?: boolean; superseded?: boolean }` | What the platform knows about the arrival — the seat it gave
+  them, which transport carried them, whether this is a player coming
+  back, and whether they replaced a connection that was still up. MAY BE
+  ABSENT on older platform images, so default before use. |
+
+## GemServerBundle.leave
+
+[GemServerBundle.leave](https://gemarcade.com/developer/api/server#gemserverbundle-leave)
+
+```ts
+leave(playerId: string, meta?: { cause?: string }): void | Promise<void>
+```
+
+A player's connection closed. They are ALREADY gone from `host.players()`.
+
+A player whose link dropped and who is reconnecting arrives here first and
+in `join` again, with `meta.rejoin` set on platform images that report it.
+Nothing is replayed between the two.
+
+Two shapes reach here, and `meta.cause` tells them apart. A redial that
+lands while the dead connection is still attached supersedes it: the cause
+is `superseded`, this `leave` is synthetic, and the `join` follows
+immediately. A connection the platform gave up on first ends with its own
+cause, and the player's redial may be seconds behind or may never come.
+Either way the `join`, if it comes, is the same player and carries the
+same `playerNumber` — so do not tear down what you are holding for them
+on the strength of the cause alone.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | Who left. |
+| `meta` | `{ cause?: string }` | Why, when the platform knows. May be absent. |
+
+## GemServerBundle.message
+
+[GemServerBundle.message](https://gemarcade.com/developer/api/server#gemserverbundle-message)
+
+```ts
+message(playerId: string, data: string | Uint8Array<ArrayBufferLike>, isText: boolean, meta?: { reliable?: boolean; ordered?: boolean; sessionId?: number; playerNumber?: number }): void | Promise<void>
+```
+
+A player sent you something.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | Who sent it. |
+| `data` | `string \| Uint8Array<ArrayBufferLike>` | The message: a string when `isText`, bytes otherwise. |
+| `isText` | `boolean` | Which of the two `data` is. CHECK IT rather than guessing —
+  treating bytes as text corrupts them. |
+| `meta` | `{ reliable?: boolean; ordered?: boolean; sessionId?: number; playerNumber?: number }` | What the sender ASKED FOR — `reliable` and `ordered` — carried
+  across whatever the transport actually did. May be absent. |
+
+## GemServerBundle.shutdown
+
+[GemServerBundle.shutdown](https://gemarcade.com/developer/api/server#gemserverbundle-shutdown)
+
+```ts
+shutdown(info?: ServerShutdownInfo): void | Promise<void>
+```
+
+The match is ending, or the platform is reclaiming the machine. Save what
+just happened.
+
+YOU HAVE LONGER THAN YOU THINK, and how much depends on which of the two it
+is. When the match ends: 10 minutes before the process goes — deliberately
+generous, because writing results is what servers do here. When the platform
+is reclaiming the machine: up to 2 hours, so a match with players still in it
+plays out rather than dying mid-game.
+
+`info.reason` says which, on platform images that report it — see
+[ServerShutdownInfo](https://gemarcade.com/developer/api/server#servershutdowninfo). On a reclaim (`signal`) do NOT end the match:
+the players are still in it, and ending it here drops every one of them.
+
+```js
+async shutdown(info) {
+  await saveResults();
+  if (info?.reason !== 'signal') await gem.match.end();
+}
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `info` | `ServerShutdownInfo` | Why, when the platform says. ABSENT on older platform images,
+  so default before use. |
+
+**Guides.** [server-bundles](https://gemarcade.com/developer/docs/server-bundles#how-long-your-server-lives)
+
+## ServerShutdownInfo.reason
+
+[ServerShutdownInfo.reason](https://gemarcade.com/developer/api/server#servershutdowninfo-reason)
+
+```ts
+readonly reason: string & object | "match_ended" | "idle_timeout" | "signal"
+```
+
+Which of the above.
+
+## ServerShutdownInfo.endedReason
+
+[ServerShutdownInfo.endedReason](https://gemarcade.com/developer/api/server#servershutdowninfo-endedreason)
+
+```ts
+readonly endedReason?: string
+```
+
+On `match_ended`: why, in the client's `matchEnded` vocabulary (`explicit`,
+`expired`, `all_left`, …), or `unknown` when the runtime passed a word this
+SDK does not know. Absent when the runtime passed nothing.
+
+## GemServerLifecycle.init
+
+[GemServerLifecycle.init](https://gemarcade.com/developer/api/server#gemserverlifecycle-init)
+
+```ts
+init(host: GemServerHost): Promise<void>
+```
+
+Called first, handing over the host object. This is where the SDK takes it
+and where your own `init` runs.
+
+| Parameter | Type |
+| --- | --- |
+| `host` | `GemServerHost` |
+
+## GemServerLifecycle.join
+
+[GemServerLifecycle.join](https://gemarcade.com/developer/api/server#gemserverlifecycle-join)
+
+```ts
+join(playerId: string, meta?: { playerNumber?: number; transport?: string; rejoin?: boolean; superseded?: boolean }): void | Promise<void>
+```
+
+Forwarded from your bundle, when you defined a `join`.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+| `meta` | `{ playerNumber?: number; transport?: string; rejoin?: boolean; superseded?: boolean }` |
+
+## GemServerLifecycle.leave
+
+[GemServerLifecycle.leave](https://gemarcade.com/developer/api/server#gemserverlifecycle-leave)
+
+```ts
+leave(playerId: string, meta?: { cause?: string }): void | Promise<void>
+```
+
+Forwarded from your bundle, when you defined a `leave`.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+| `meta` | `{ cause?: string }` |
+
+## GemServerLifecycle.message
+
+[GemServerLifecycle.message](https://gemarcade.com/developer/api/server#gemserverlifecycle-message)
+
+```ts
+message(playerId: string, data: string | Uint8Array<ArrayBufferLike>, isText: boolean, meta?: { reliable?: boolean; ordered?: boolean; sessionId?: number; playerNumber?: number }): void | Promise<void>
+```
+
+Forwarded from your bundle, when you defined a `message`.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+| `data` | `string \| Uint8Array<ArrayBufferLike>` |
+| `isText` | `boolean` |
+| `meta` | `{ reliable?: boolean; ordered?: boolean; sessionId?: number; playerNumber?: number }` |
+
+## GemServerLifecycle.shutdown
+
+[GemServerLifecycle.shutdown](https://gemarcade.com/developer/api/server#gemserverlifecycle-shutdown)
+
+```ts
+shutdown(info?: RuntimeShutdownPayload): Promise<void>
+```
+
+Always defined, even if your bundle has no `shutdown` — the SDK has teardown
+of its own to do, and it runs whether or not yours threw.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `info` | `RuntimeShutdownPayload` | What the runtime passed, when it passed anything: the raw
+  `{ reason, platform_reason }` of its shutdown frame, which the SDK
+  narrows into [ServerShutdownInfo](https://gemarcade.com/developer/api/server#servershutdowninfo) for your bundle. |
+
+## RuntimeShutdownPayload.reason
+
+[RuntimeShutdownPayload.reason](https://gemarcade.com/developer/api/server#runtimeshutdownpayload-reason)
+
+```ts
+readonly reason?: string
+```
+
+The runtime's cause: `match_ended`, `idle_timeout`, `signal`.
+
+## RuntimeShutdownPayload.platform_reason
+
+[RuntimeShutdownPayload.platform_reason](https://gemarcade.com/developer/api/server#runtimeshutdownpayload-platform_reason)
+
+```ts
+readonly platform_reason?: string
+```
+
+On `match_ended`, the platform's reason as the runtime's frame spells it.
+
+## RuntimeShutdownPayload.endedReason
+
+[RuntimeShutdownPayload.endedReason](https://gemarcade.com/developer/api/server#runtimeshutdownpayload-endedreason)
+
+```ts
+readonly endedReason?: string
+```
+
+The same, as the SDK spells it — for a lifecycle driven by hand.
+
+## GemServerProfile.displayName
+
+[GemServerProfile.displayName](https://gemarcade.com/developer/api/server#gemserverprofile-displayname)
+
+```ts
+readonly displayName: PlayerText
+```
+
+The name the player chose — so it is [PlayerText](https://gemarcade.com/developer/api/server#playertext), not a plain string.
+
+The type is the reminder: this is text a stranger wrote. `text.toPlain` is
+the one way to turn it into a string, and on a server the honest answer is
+usually that you never need to.
+
+## GemServerProfile.displayTag
+
+[GemServerProfile.displayTag](https://gemarcade.com/developer/api/server#gemserverprofile-displaytag)
+
+```ts
+readonly displayTag?: PlayerText
+```
+
+The precomposed `Name#0001`, when the platform has one. It contains the
+name, so it is [PlayerText](https://gemarcade.com/developer/api/server#playertext) too — the same type every other surface
+that shows a player gives it.
+
+## GemServerProfile.discriminator
+
+[GemServerProfile.discriminator](https://gemarcade.com/developer/api/server#gemserverprofile-discriminator)
+
+```ts
+readonly discriminator?: string
+```
+
+The disambiguating suffix, when the player has one.
+
+## GemMatchServer.identity
+
+[GemMatchServer.identity](https://gemarcade.com/developer/api/server#gemmatchserver-identity)
+
+```ts
+readonly identity: GemServerIdentity
+```
+
+Which game, channel and match this server is running.
+
+## GemMatchServer.client
+
+[GemMatchServer.client](https://gemarcade.com/developer/api/server#gemmatchserver-client)
+
+```ts
+readonly client: GemClient
+```
+
+The HTTP client underneath [GemServer.api](https://gemarcade.com/developer/api/server#gemserver-api), for calls the generated
+surface does not cover.
+
+PREFER `api`. It is typed against the platform's description, so a shape
+that changes becomes a build error in your bundle. This one takes a path and
+checks nothing — reach for it when you genuinely need something `api` has
+no method for, and treat that as worth telling us about.
+
+## GemMatchServer.api
+
+[GemMatchServer.api](https://gemarcade.com/developer/api/server#gemmatchserver-api)
+
+```ts
+readonly api: ServerApi
+```
+
+Every platform operation your server can call. This is the one you want.
+
+See [ServerApi](https://gemarcade.com/developer/api/server#serverapi).
+
+## GemMatchServer.match
+
+[GemMatchServer.match](https://gemarcade.com/developer/api/server#gemmatchserver-match)
+
+```ts
+readonly match: { end: null }
+```
+
+Ending the match.
+
+`end()` is HOW A SERVER-AUTHORITATIVE GAME FINISHES. It tells the platform
+the match is over; the platform then tells the runtime, and your server
+winds down through its ordinary shutdown. You do not stop the process
+yourself.
+
+It always means THIS match — the id is already known, so there is nothing to
+pass and no way to end someone else's.
+
+The platform half makes the request, not your process: it holds the proof
+that this server is the one allocated to the match, which the platform
+requires. On a platform image too old to offer that, `end()` throws rather
+than sending a request without the proof.
+
+## GemMatchServer.match.end
+
+[GemMatchServer.match.end](https://gemarcade.com/developer/api/server#gemmatchserver-match-end)
+
+```ts
+end(signal?: AbortSignal): Promise<void>
+```
+
+Tell the platform this match is finished.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `signal` | `AbortSignal` | Not used — the platform half bounds its own request. |
+
+**Throws.** When the platform image running this server predates
+  `host.endMatch`, so the match cannot be ended from here.
+
+## GemMatchServer.analytics
+
+[GemMatchServer.analytics](https://gemarcade.com/developer/api/server#gemmatchserver-analytics)
+
+```ts
+readonly analytics: ServerAnalytics
+```
+
+Recording analytics events about the players in this match.
+
+THE AUTHORITATIVE HALF of the pair. The browser's `gem.analytics` records
+game-asserted browser facts, which feed a developer's own numbers and
+nothing the platform treats as true; a server holds a credential the player
+does not, so what it records about a run, a score or an outcome is the
+counterpart a game reaches for when the browser's word is not enough. A
+game may declare an event `sources: [server]` and shut the client out of it
+entirely.
+
+⚠️ **Every event names its player, and `gem_*` is unavailable here** — see
+[ServerAnalytics.track](https://gemarcade.com/developer/api/server#serveranalytics-track). And flush before the match ends: there is no
+page unload to get the tail out on.
+
+## GemMatchServer.functions
+
+[GemMatchServer.functions](https://gemarcade.com/developer/api/server#gemmatchserver-functions)
+
+```ts
+readonly functions: FunctionsApi
+```
+
+Your game's serverless function — `gem.functions.invoke(input)`, the same
+call a game makes in the browser.
+
+The call arrives as this server, not as a player: your function's
+`get-context` says so, and a server's per-minute budget is its own. It runs
+the function promoted on the channel this match runs on.
+
+## GemMatchServer.challenges
+
+[GemMatchServer.challenges](https://gemarcade.com/developer/api/server#gemmatchserver-challenges)
+
+```ts
+readonly challenges: ServerChallenges
+```
+
+A player's daily challenges — their period, its date, the seed, and any
+content your studio stored — so your server verifies a result against the
+board that player was actually given.
+
+A period is the PLAYER's, not the calendar's: it ends at their own
+midnight. That is why this takes a player id where the browser's
+`gem.challenges` takes none. See [ServerChallenges.list](https://gemarcade.com/developer/api/server#serverchallenges-list).
+
+## GemMatchServer.room
+
+[GemMatchServer.room](https://gemarcade.com/developer/api/server#gemmatchserver-room)
+
+```ts
+readonly room?: { get: (options?: { ifNoneMatch?: string; signal?: AbortSignal }) => Promise<VersionedResponse<GameRoomResponseV2>>; args: (options?: { signal?: AbortSignal }) => Promise<RoomArgsResponse> }
+```
+
+Reading the room this match came from — the two calls almost every server
+makes at startup, already pointed at your own room.
+
+CHECK IT IS THERE. `room` is absent on older platform images, which is why
+the type says it might be. `gem.room?.get()` is the shape to write. When it
+is absent the same reads are still available through `api` if you know the
+room id from somewhere else.
+
+## GemMatchServer.room.get
+
+[GemMatchServer.room.get](https://gemarcade.com/developer/api/server#gemmatchserver-room-get)
+
+```ts
+get: (options?: { ifNoneMatch?: string; signal?: AbortSignal }) => Promise<VersionedResponse<GameRoomResponseV2>>
+```
+
+The room, in full: the settings it was created with, the template those
+came from, and every member — with display name, role, ready state and
+avatar.
+
+This is what you want at `start()`, and it is a superset of what the older
+roster push carried.
+
+## GemMatchServer.room.args
+
+[GemMatchServer.room.args](https://gemarcade.com/developer/api/server#gemmatchserver-room-args)
+
+```ts
+args: (options?: { signal?: AbortSignal }) => Promise<RoomArgsResponse>
+```
+
+Just the room's settings.
+
+A room whose template declares no settings answers 404
+`room_args_not_defined` rather than an empty object — "this room has no
+settings" and "this room's settings are empty" are different answers and
+the API keeps them apart.
+
+## GemMatchServer.dispose
+
+[GemMatchServer.dispose](https://gemarcade.com/developer/api/server#gemmatchserver-dispose)
+
+```ts
+dispose(): void
+```
+
+Stop listening for credential updates.
+
+You rarely need it: a bundle built with [defineServer](https://gemarcade.com/developer/api/server#defineserver) is disposed for
+you when the match ends. Call it in a test, or if you built the server
+yourself and are tearing it down.
+
+## GemMatchServer.sizeClass
+
+[GemMatchServer.sizeClass](https://gemarcade.com/developer/api/server#gemmatchserver-sizeclass)
+
+```ts
+readonly sizeClass: string
+```
+
+Which size of machine this server was allocated on.
+
+Useful if your game scales what it does to the hardware it got.
+
+## GemMatchServer.roomArgs
+
+[GemMatchServer.roomArgs](https://gemarcade.com/developer/api/server#gemmatchserver-roomargs)
+
+```ts
+readonly roomArgs: Readonly<Record<string, RoomArgValue>> | undefined
+```
+
+**Deprecated.** Use `gem.room?.args()` instead. It reads the same settings from
+the platform and can tell "this room type has no settings" apart from "it has
+settings and they are empty" — a difference this snapshot cannot express.
+
+Still delivered today. The member keeps compiling for the rest of `3.x`,
+and `4.0.0` is the earliest release that may take it off the type. Whether
+a server keeps sending a value is a separate question, decided where the
+dedicated-server image is built rather than by a package release — so check
+for the room read and keep this as the fallback. Both halves are in
+[the deprecation policy](https://gemarcade.com/developer/docs/deprecation-policy).
+
+The room's settings as they were at match start.
+
+## GemMatchServer.roster
+
+[GemMatchServer.roster](https://gemarcade.com/developer/api/server#gemmatchserver-roster)
+
+```ts
+readonly roster: readonly string[]
+```
+
+**Deprecated.** Use `gem.room?.get()` instead: live membership, with names, roles
+and ready state.
+
+Still delivered today. The member keeps compiling for the rest of `3.x`,
+and `4.0.0` is the earliest release that may take it off the type. Whether
+a server keeps sending a value is a separate question, decided where the
+dedicated-server image is built rather than by a package release — so check
+for the room read and keep this as the fallback. Both halves are in
+[the deprecation policy](https://gemarcade.com/developer/docs/deprecation-policy).
+
+Who was in the room when the server was allocated.
+
+A HINT FOR SIZING, NOT A GUEST LIST. It is never revised, and it is not what
+decides who may connect — the platform admits players by credential, not by
+this array.
+
+## GemMatchServer.players
+
+[GemMatchServer.players](https://gemarcade.com/developer/api/server#gemmatchserver-players)
+
+```ts
+players(): string[]
+```
+
+The players connected right now, as a fresh array each call.
+
+## GemMatchServer.profile
+
+[GemMatchServer.profile](https://gemarcade.com/developer/api/server#gemmatchserver-profile)
+
+```ts
+profile(playerId: string): GemServerProfile | null
+```
+
+A connected player's display identity, or `null` if the platform has none
+for them.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | Take this from `join()` or `players()`, never from something
+  a client sent you. |
+
+## GemMatchServer.playerNumber
+
+[GemMatchServer.playerNumber](https://gemarcade.com/developer/api/server#gemmatchserver-playernumber)
+
+```ts
+playerNumber(playerId: string): number | undefined
+```
+
+The seat number the platform gave a player — 1-based.
+
+`undefined` when there is no answer: an id that is not seated, or an older
+platform image that does not assign seats. You cannot tell those apart and
+do not need to — handle the absence.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+
+## GemMatchServer.send
+
+[GemMatchServer.send](https://gemarcade.com/developer/api/server#gemmatchserver-send)
+
+```ts
+send(playerId: string, data: string | Uint8Array<ArrayBufferLike>, options?: SendOptions): void
+```
+
+Send to one player.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | Who to send to. |
+| `data` | `string \| Uint8Array<ArrayBufferLike>` | A string or bytes. The receiver is told which. |
+| `options` | `SendOptions` | What delivery you are ASKING FOR — see [SendOptions](https://gemarcade.com/developer/api/server#sendoptions).
+  Both default to true. Pass them freely: an older platform image ignores
+  them harmlessly. |
+
+## GemMatchServer.broadcast
+
+[GemMatchServer.broadcast](https://gemarcade.com/developer/api/server#gemmatchserver-broadcast)
+
+```ts
+broadcast(data: string | Uint8Array<ArrayBufferLike>, options?: BroadcastOptions): void
+```
+
+Send to every connected player.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `data` | `string \| Uint8Array<ArrayBufferLike>` | A string or bytes. |
+| `options` | `BroadcastOptions` | See [BroadcastOptions](https://gemarcade.com/developer/api/server#broadcastoptions) — the same delivery choices as
+  [GemMatchServer.send](https://gemarcade.com/developer/api/server#gemmatchserver-send), plus who to leave out. |
+
+## GemMatchServer.kick
+
+[GemMatchServer.kick](https://gemarcade.com/developer/api/server#gemmatchserver-kick)
+
+```ts
+kick(playerId: string, reason?: string): void
+```
+
+Disconnect a player.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | Who to remove. |
+| `reason` | `string` | Shown to them, and recorded in the match's logs. |
+
+## GemMatchServer.log
+
+[GemMatchServer.log](https://gemarcade.com/developer/api/server#gemmatchserver-log)
+
+```ts
+log(message: string): void
+```
+
+Write a line to the match's logs.
+
+USE THIS, NEVER `console.log`. Standard output belongs to the platform — it
+is how the runtime talks to your server — and writing to it directly
+corrupts that conversation.
+
+| Parameter | Type |
+| --- | --- |
+| `message` | `string` |
+
+## GemMatchServer.warn
+
+[GemMatchServer.warn](https://gemarcade.com/developer/api/server#gemmatchserver-warn)
+
+```ts
+warn(message: string): void
+```
+
+Like [GemMatchServer.log](https://gemarcade.com/developer/api/server#gemmatchserver-log), marked as a warning.
+
+| Parameter | Type |
+| --- | --- |
+| `message` | `string` |