@splattervault/server 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,7 +4,36 @@ All notable changes to `@splattervault/server` are listed here. The format follo
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package uses [semantic versioning](https://semver.org/);
5
5
  while it is 0.x, a minor version may change the API.
6
6
 
7
- ## [0.1.0] - Unreleased (preview)
7
+ ## [0.1.1] - 2026-11-15
8
+
9
+ Follows the corrected Studio API description (API main c002ca7f, https://splattervault.com/docs/studio/swagger.json).
10
+
11
+ ### Added
12
+
13
+ - `poolClaimConflict(err)`: tells a `serverPools.claim` 409 apart by the API's message: `"no_warm_server"` (none idle:
14
+ start a session instead) or `"busy"` (the "— retry" messages: contention; trying the claim again shortly is safe;
15
+ nothing was claimed). The SDK still never retries a claim itself (it starts servers). The README and
16
+ `examples/match-server.ts` show the fallback.
17
+
18
+ ### Changed (types, from the API description)
19
+
20
+ - `CreditBalance`: `createdAt` and `updatedAt` are now `string | null` (an organization API key's answer has null
21
+ dates); new fields `availableBalance`, `graceExpiresAt` (`string | null`) and `user` (an object, or null; null for
22
+ an organization key). Code that assigned `createdAt` to a non-null `string` must now handle null. The SDK itself
23
+ never reads these fields.
24
+ - Every GET operation's parameters now list an optional `If-None-Match` header, and its answers `ETag`, `304` and
25
+ `x-request-id` headers (`components["headers"]["RequestId"]`); `serverPools.claim` lists its `409` answer. Request
26
+ and answer bodies are unchanged apart from `CreditBalance`.
27
+
28
+ ### Documentation
29
+
30
+ - The game-server session and billing routes never answer 429 (the API sets no rate limit on them): said so in the
31
+ README and on `Sessions` / `Billing`; only the studio routes answer `429 rate_limited`.
32
+ - Conditional requests: every GET documents ETags, but the SDK never sends `If-None-Match` itself, so it never meets
33
+ a 304; if you send one in `headers`, it adds `Cache-Control: max-age=0` and a 304 rejects with status 304 (as in
34
+ 0.1.0). The contract test now checks exactly that instead of "no operation documents ETags".
35
+
36
+ ## [0.1.0] - 2026-11-15 (preview)
8
37
 
9
38
  The first release: the Studio API's server operations (organization API key) for Node.js 18 and later.
10
39
 
package/README.md CHANGED
@@ -60,17 +60,24 @@ Claim a warm server from one of your pools (it is already running: seconds), or
60
60
  minute):
61
61
 
62
62
  ```ts
63
- import { SplatterVault, SplatterVaultError } from "@splattervault/server";
63
+ import { poolClaimConflict, SplatterVault } from "@splattervault/server";
64
64
 
65
65
  const sv = new SplatterVault();
66
66
 
67
67
  async function serverForMatch(matchId: string) {
68
- try {
69
- const claim = await sv.serverPools.claim(12, { friendlyName: `Match ${matchId}`, mode: "Ranked" });
70
- return claim; // { sessionId, serverInstanceId, connection: { host, primaryPort, code, ... } | null }
71
- } catch (err) {
72
- // 409: no warm server free right now: start a new one instead.
73
- if (!(err instanceof SplatterVaultError) || err.status !== 409) throw err;
68
+ for (let attempt = 1; attempt <= 2; attempt++) {
69
+ try {
70
+ const claim = await sv.serverPools.claim(12, { friendlyName: `Match ${matchId}`, mode: "Ranked" });
71
+ return claim; // { sessionId, serverInstanceId, connection: { host, primaryPort, code, ... } | null }
72
+ } catch (err) {
73
+ const conflict = poolClaimConflict(err); // a 409 claimed nothing; null for any other error
74
+ if (conflict === "busy" && attempt === 1) {
75
+ await new Promise((r) => setTimeout(r, 1000)); // contention: one more try shortly
76
+ continue;
77
+ }
78
+ if (conflict === null) throw err;
79
+ break; // "no_warm_server" (or still busy): start a new one instead
80
+ }
74
81
  }
75
82
  const session = await sv.sessions.create({
76
83
  gameTypeConfigKey: "my-game",
@@ -96,6 +103,11 @@ says it is ready (`ready: true`; a game with no ready signal is returned once it
96
103
  Creating a session, stopping one and claiming a pool server are **never retried by the SDK** (a repeat could start or
97
104
  claim a second server). After a network error, look for the session with `sv.sessions.list()` before trying again.
98
105
 
106
+ A claim's `409` claims nothing, and the API tells its kinds apart only by the message: `poolClaimConflict(err)`
107
+ answers `"no_warm_server"` ("No warm server available in this pool": start a session instead) or `"busy"` (the
108
+ messages ending in "— retry": another claim was running, or the idle server could not take the session; trying the
109
+ claim again shortly is safe), and null for any other error.
110
+
99
111
  ### Verify a player's token on your game server
100
112
 
101
113
  The game client sends its player token when it connects; your server checks it **offline** against SplatterVault's
@@ -239,6 +251,10 @@ try {
239
251
  `err.is("rate_limited")`, `err.isTransient` (408, 429, 500, 502, 503, 504 or no answer) and `err.isNetworkError` help too. Each
240
252
  operation's codes are listed in the [Studio API reference](https://splattervault.com/docs/studio).
241
253
 
254
+ Rate limits: the studio routes (player sign-in, player data, the store) answer `429 rate_limited` with `Retry-After`
255
+ when a key or a player sends too much. The game-server session and billing routes set no rate limit of their own:
256
+ they never answer 429 (their transient failures are 500, 502, 503, 504 or no answer).
257
+
242
258
  ## Retries, timeouts and cancellation
243
259
 
244
260
  The SDK sends a request again by itself only when that is **safe**, and only after a transient failure: no answer
@@ -311,7 +327,7 @@ claiming match's; `mode`, `serverName` and `friendlyName` are from when the pool
311
327
  | `sv.playerData` | `resolve`, `get`, `update`, `clear`, `getMany`, `writeMany`, `getGameData`, `updateGameData`, `import`, `listErasedPlayers`, `erasedPlayerPages` |
312
328
  | `sv.store` | `getCatalog`, `getPlayer`, `getHistory`, `historyPages`, `grant`, `consume`, `purchase`, `updateItem`, `reverse`, `syncMetaPurchases`, `importCatalog`, `importHoldings` |
313
329
  | `sv` | `verifyPlayerToken` |
314
- | functions | `verifyPlayerToken`, `createPlayerTokenVerifier`, `readSessionEnvironment`, `newIdempotencyKey` |
330
+ | functions | `verifyPlayerToken`, `createPlayerTokenVerifier`, `readSessionEnvironment`, `newIdempotencyKey`, `poolClaimConflict` |
315
331
 
316
332
  Each method's documentation names its API operation (`@see POST /store/studio/players/{player}/grants`). Request and
317
333
  answer types (`ServerSession`, `StoreTxnResult`, `DataOp`, …) are exported, generated from the API's OpenAPI
package/dist/index.cjs CHANGED
@@ -519,7 +519,7 @@ var HttpClient = class {
519
519
  };
520
520
 
521
521
  // src/version.ts
522
- var SDK_VERSION = "0.1.0";
522
+ var SDK_VERSION = "0.1.1";
523
523
  var KID_RE = /^[0-9a-f]{16}$/;
524
524
  var MIN_KEYS_LIFETIME_MS = 6e4;
525
525
  var MAX_KEYS_LIFETIME_MS = 36e5;
@@ -833,7 +833,7 @@ var Billing = class {
833
833
  http;
834
834
  /**
835
835
  * The credit balance: the organization's for an organization API key (split into subscription and purchased
836
- * credits).
836
+ * credits). For an organization key `id` is 0 and `createdAt`, `updatedAt` and `user` are null.
837
837
  * @see GET /credits (`billing.getCredits`)
838
838
  */
839
839
  getCredits(options) {
@@ -1274,6 +1274,12 @@ var Sessions = class {
1274
1274
  return this.http.call("sessions.cancelScheduledCredit", { path: { sessionId }, options });
1275
1275
  }
1276
1276
  };
1277
+ function poolClaimConflict(err) {
1278
+ if (!(err instanceof SplatterVaultError) || err.status !== 409 || err.operationId !== "serverPools.claim") return null;
1279
+ const body = err.body;
1280
+ const message = typeof body?.message === "string" ? body.message : "";
1281
+ return /\bretry\s*[.!]?\s*$/i.test(message) ? "busy" : "no_warm_server";
1282
+ }
1277
1283
  var ServerPools = class {
1278
1284
  /** @internal */
1279
1285
  constructor(http) {
@@ -1282,8 +1288,11 @@ var ServerPools = class {
1282
1288
  http;
1283
1289
  /**
1284
1290
  * Claims a warm server from pool `poolId` for a match: answers the new session's id, the pool instance and its
1285
- * `connection` (null until reachable). Needs a key holding org:manage_pools. Never retried by the SDK: a repeat
1286
- * would claim a second server.
1291
+ * `connection` (null until reachable). Needs a key holding org:manage_pools (with an organization API key).
1292
+ *
1293
+ * Never retried by the SDK: a repeat after a lost answer could claim a second server. A `409` claimed nothing:
1294
+ * {@link poolClaimConflict} says whether no server is idle (`"no_warm_server"`: start a session instead) or the
1295
+ * claim met contention (`"busy"`: you may try again shortly). Like every session route it never answers 429.
1287
1296
  * @see POST /server-pools/{id}/claim (`serverPools.claim`)
1288
1297
  */
1289
1298
  claim(poolId, body, options) {
@@ -1578,6 +1587,7 @@ exports.TRANSIENT_STATUSES = TRANSIENT_STATUSES;
1578
1587
  exports.createPlayerTokenVerifier = createPlayerTokenVerifier;
1579
1588
  exports.isBrowserLike = isBrowserLike;
1580
1589
  exports.newIdempotencyKey = newIdempotencyKey;
1590
+ exports.poolClaimConflict = poolClaimConflict;
1581
1591
  exports.readSessionEnvironment = readSessionEnvironment;
1582
1592
  exports.verifyPlayerToken = verifyPlayerToken;
1583
1593
  //# sourceMappingURL=index.cjs.map