@indiegems/gem-web-sdk 16.1.0 → 16.3.0

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

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v16.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/function` v16.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/function` exports exactly the symbols on this page and nothing else.
 
@@ -3200,9 +3200,11 @@ readonly etag: string
 
 This save's version, which changes whenever the save does.
 
-NOT something to pass back on a write — a write pins the version it is
-replacing on its own. This is how a game holding a copy tells whether the
-stored save is still the one it has.
+NOT something to pass back on a write — the SDK remembers the version of
+each slot you last loaded or wrote and sends it for you, so a write that
+would replace a save you never saw is refused as `save_conflict`. This is
+how a game holding a copy tells whether the stored save is still the one
+it has.
 
 <a id="saverecord-metadata"></a>
 
@@ -3295,7 +3297,7 @@ has already agreed to the write. Re-read before assuming what is stored.
 ## GemSaveError.reason
 
 ```ts
-readonly reason: "upload_failed" | "download_failed" | "save_timeout" | "save_malformed"
+readonly reason: "upload_failed" | "download_failed" | "save_timeout" | "save_malformed" | "save_conflict" | "load_failed"
 ```
 
 Which part failed.
@@ -3305,15 +3307,31 @@ Which part failed.
 - `save_timeout` — a hop did not finish in the time the call allows.
 - `save_malformed` — the answer, or the stored payload, was not what it
   claims to be.
+- `save_conflict` — a write was refused because the stored save changed
+  since this game last loaded or wrote it: another device or tab saved
+  in between. Nothing was written.
+- `load_failed` — a write was refused before anything was sent, because
+  the last load of this slot failed, so what the write would replace is
+  unknown — it could be the player's real progress.
 
 `save_timeout`, and a one-off `upload_failed` or `download_failed`, are
 worth one retry. `save_malformed` is not: the same bytes will fail the
 same way.
 
+Neither is `save_conflict` or `load_failed`: resending the same write
+fails the same way. Load the slot again and decide what to write from
+what is stored — merge, or ask the player. Pass `overwrite: true` only to
+replace whatever is stored on purpose.
+
 An `upload_failed` that repeats on EVERY save, for every player, is not
 transient either — it is a platform-side misconfiguration, and retrying
 is a loop rather than a recovery. See the saves guide.
 
+A RATE LIMIT IS NOT ONE OF THESE. Refused for the rate on any leg — the
+platform, the upload, the download — a save or load rejects as
+`GemApiError` reason `rate_limited`, with `retryAfterSeconds` when a wait
+was named.
+
 <a id="putsaveoptions"></a>
 
 ## PutSaveOptions
@@ -3354,6 +3372,10 @@ Cancel the write.
 A save is several hops, so a cancelled write can land after the platform
 has already agreed to it. Re-read rather than assuming nothing was stored.
 
+A write that replaced earlier ones still waiting on its slot carries them,
+so cancelling it before it goes out cancels them too. Cancelling a write
+that a later one replaced rejects only this call; the later write goes on.
+
 <a id="putsaveoptions-timeoutms"></a>
 
 ## PutSaveOptions.timeoutMs
@@ -3376,6 +3398,68 @@ to do something about it.
 It does not make a save faster. Three round trips plus the payload is what
 a save costs; this only decides when to stop waiting.
 
+It counts from the call, so a write waiting for the one before it on the
+same slot spends it waiting. A rate limit whose wait it will not cover
+rejects at once as `GemApiError` reason `rate_limited`, not as
+`save_timeout`.
+
+It stays this call's when a later write replaces this one: running out
+rejects only this call, and the later write goes on. The write that is
+sent runs on the newest call's `timeoutMs`, and running out of that rejects
+every call it carries.
+
+<a id="putsaveoptions-teardown"></a>
+
+## PutSaveOptions.teardown
+
+```ts
+readonly teardown?: boolean
+```
+
+This is the last write before the page goes away: send it without waiting
+for the spacing between writes to one slot.
+
+Writes to one slot go out a few seconds apart, and a write made sooner
+waits its turn. Set this on the write you make from
+`GemTerminationNotice` or `pagehide`, with a `timeoutMs` inside the
+time you have.
+
+IT STILL WAITS FOR A WRITE ALREADY IN FLIGHT to the same slot, and it
+still honours a rate-limit hold: when the hold outlasts `timeoutMs` the
+write rejects at once as `rate_limited`, and nothing is sent. Not for
+ordinary saves — the spacing is what keeps a save loop from spending the
+rate limit.
+
+A later write that replaces this one while it waits keeps it: the write
+that goes out skips the spacing when any call it carries set `teardown`.
+Not across a player change: a call replaced after the signed-in player
+changed is refused as `save_conflict`, and its `teardown` goes with it.
+
+<a id="putsaveoptions-overwrite"></a>
+
+## PutSaveOptions.overwrite
+
+```ts
+readonly overwrite?: boolean
+```
+
+Write even if it replaces a save this game has not loaded.
+
+Without it, a write to a slot whose last load FAILED is refused as
+`load_failed`, and a write is refused as `save_conflict` when the stored
+save changed since you last loaded or wrote it. Both refusals protect the
+player's real progress from a game that started from defaults.
+
+Set it only when replacing whatever is stored is what you mean — a "new
+game" the player confirmed, or the player choosing this device's progress
+after a conflict. Never set it to get past a failed load.
+
+A later write that replaces this one while it waits keeps it: the write
+that goes out overwrites when any call it carries set `overwrite`. A call
+that gives up first (its `signal` or `timeoutMs`) takes it back, and so
+does one replaced after the signed-in player changed: it is refused as
+`save_conflict`, so one player's "new game" never overwrites the next's.
+
 <a id="putbytesoptions"></a>
 
 ## PutBytesOptions
@@ -3419,6 +3503,10 @@ Cancel the write.
 A save is several hops, so a cancelled write can land after the platform
 has already agreed to it. Re-read rather than assuming nothing was stored.
 
+A write that replaced earlier ones still waiting on its slot carries them,
+so cancelling it before it goes out cancels them too. Cancelling a write
+that a later one replaced rejects only this call; the later write goes on.
+
 <a id="putbytesoptions-timeoutms"></a>
 
 ## PutBytesOptions.timeoutMs
@@ -3441,6 +3529,68 @@ to do something about it.
 It does not make a save faster. Three round trips plus the payload is what
 a save costs; this only decides when to stop waiting.
 
+It counts from the call, so a write waiting for the one before it on the
+same slot spends it waiting. A rate limit whose wait it will not cover
+rejects at once as `GemApiError` reason `rate_limited`, not as
+`save_timeout`.
+
+It stays this call's when a later write replaces this one: running out
+rejects only this call, and the later write goes on. The write that is
+sent runs on the newest call's `timeoutMs`, and running out of that rejects
+every call it carries.
+
+<a id="putbytesoptions-teardown"></a>
+
+## PutBytesOptions.teardown
+
+```ts
+readonly teardown?: boolean
+```
+
+This is the last write before the page goes away: send it without waiting
+for the spacing between writes to one slot.
+
+Writes to one slot go out a few seconds apart, and a write made sooner
+waits its turn. Set this on the write you make from
+`GemTerminationNotice` or `pagehide`, with a `timeoutMs` inside the
+time you have.
+
+IT STILL WAITS FOR A WRITE ALREADY IN FLIGHT to the same slot, and it
+still honours a rate-limit hold: when the hold outlasts `timeoutMs` the
+write rejects at once as `rate_limited`, and nothing is sent. Not for
+ordinary saves — the spacing is what keeps a save loop from spending the
+rate limit.
+
+A later write that replaces this one while it waits keeps it: the write
+that goes out skips the spacing when any call it carries set `teardown`.
+Not across a player change: a call replaced after the signed-in player
+changed is refused as `save_conflict`, and its `teardown` goes with it.
+
+<a id="putbytesoptions-overwrite"></a>
+
+## PutBytesOptions.overwrite
+
+```ts
+readonly overwrite?: boolean
+```
+
+Write even if it replaces a save this game has not loaded.
+
+Without it, a write to a slot whose last load FAILED is refused as
+`load_failed`, and a write is refused as `save_conflict` when the stored
+save changed since you last loaded or wrote it. Both refusals protect the
+player's real progress from a game that started from defaults.
+
+Set it only when replacing whatever is stored is what you mean — a "new
+game" the player confirmed, or the player choosing this device's progress
+after a conflict. Never set it to get past a failed load.
+
+A later write that replaces this one while it waits keeps it: the write
+that goes out overwrites when any call it carries set `overwrite`. A call
+that gives up first (its `signal` or `timeoutMs`) takes it back, and so
+does one replaced after the signed-in player changed: it is refused as
+`save_conflict`, so one player's "new game" never overwrites the next's.
+
 <a id="putbytesoptions-contenttype"></a>
 
 ## PutBytesOptions.contentType
@@ -3483,6 +3633,20 @@ await gem.me.saves.put('slot1', { level: 7, checkpoint: 'bridge' });
 const state = await gem.me.saves.get('slot1');
 ```
 
+LOAD BEFORE YOU SAVE. Each write carries the version of the slot your last
+load or write found, so a write that would replace a save this game has not
+seen — another device's, or the player's real progress after a load that
+failed — is refused as `save_conflict` or `load_failed` rather than stored.
+After a failed load, play on without saving and load again later; pass
+`overwrite: true` only when the player chose to start over.
+
+ONE WRITE PER SLOT AT A TIME. A write made while another to the same slot is
+in flight waits for it, and a later one replaces it: the newest value is the
+one sent, and every caller it replaced resolves with it, keeping its own
+`signal`, `timeoutMs`, `teardown` and `overwrite`. Writes to one slot
+go out a few seconds apart (`teardown: true` skips that), and after a
+`rate_limited` answer none goes out until the wait it named is over.
+
 WHAT IS DELIBERATELY NOT HERE: no autosave timer, no save format, no
 migration. Those are your game's, and a platform that guessed at them would
 guess wrong.