@arcadible/server-sdk 0.4.0-next.0 → 0.5.0-next.0

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/README.md CHANGED
@@ -42,7 +42,7 @@ const ticket = await tickets.check(bearer, {
42
42
  - **`server`** is your server's own address, as your game's `arcadible.toml` lists it. A ticket for another server is refused.
43
43
  - **`game`** is your game's id. A ticket for another game is refused.
44
44
  - **`channel`** is the channel your server takes tickets from: `"production"`, `"staging"`, or both as a list. A production server passes `"production"`, so it never takes a staging build's tickets.
45
- - **`player`** is the player's id in your game, the same every time, or `null` for a guest.
45
+ - **`player`** is the player, as `{ id }`: their id in your game, the same every time. It's `null` for a guest. Pass it as it is to `players.read` and to a value's `scope`.
46
46
  - **`id`** is unique to the ticket. Keep it until `expiresAt` to refuse a ticket sent twice.
47
47
 
48
48
  It rejects with an `ArcadibleError`, whose `code` says what to do:
@@ -55,12 +55,12 @@ It rejects with an `ArcadibleError`, whose `code` says what to do:
55
55
 
56
56
  ## Players
57
57
 
58
- A ticket gives your server a player's id. With one of your game's keys, it can ask Arcadible for their name, and who has deleted their account.
58
+ A ticket gives your server a player, by their id in your game. With one of your game's keys, it can ask Arcadible for their name, and who has deleted their account.
59
59
 
60
60
  ```js
61
61
  import { players } from "@arcadible/server-sdk";
62
62
 
63
- const [sam, kim] = await players.read([ticket.player, other]);
63
+ const [sam, kim] = await players.read([ticket.player, { id: stored }]);
64
64
  // { id, name }, or null for a player who's gone, or a guest
65
65
 
66
66
  const gone = await players.deleted({ since: lastChecked });
@@ -68,10 +68,12 @@ const gone = await players.deleted({ since: lastChecked });
68
68
  ```
69
69
 
70
70
  - **The key** is read from `ARCADIBLE_KEY` in your server's environment, never passed in code. Make one in Arcadible Studio, or with `arc server key create`. It's for one game and one channel, and it's shown once.
71
- - **`players.read`** takes up to 50 ids. A name is the player's own, as they've set it on Arcadible; show it as text.
71
+ - **A player is an object,** in every call: `players.read` takes up to 50, each anything with a player's `id`, such as a ticket's `player`, an entry of `players.deleted`, or a `{ id }` your server kept. An id alone isn't taken. A missing player, `null`, as a guest's ticket has, comes back `null`.
72
+ - **A player may gain properties.** Arcadible may add to a player later, and every call that takes one reads only its `id`. Don't depend on a player's exact shape, such as by comparing whole objects or expecting the same properties back: compare and keep the `id`.
73
+ - **A name** is the player's own, as they've set it on Arcadible; show it as text.
72
74
  - **`players.deleted`** lists who deleted their account in the last 30 days. Read it on a schedule, and delete what your server keeps for each.
73
75
 
74
- Both reject with an `ArcadibleError`: `invalid` (no key, or one Arcadible doesn't take), `busy` (too many requests: slow down), or `unavailable` (try again).
76
+ Both reject with an `ArcadibleError`: `invalid` (no key, one Arcadible doesn't take, or an argument that isn't a list of players or a time), `too_many` (more than 50 players), `busy` (too many requests: slow down), or `unavailable` (try again).
75
77
 
76
78
  ## Values
77
79
 
@@ -94,10 +96,10 @@ await values.write([
94
96
  ]);
95
97
 
96
98
  // a logged-in player's own
97
- await values.write([{ scope: { id: ticket.player }, key: "progress", value: { level: 3 } }]);
99
+ await values.write([{ scope: ticket.player, key: "progress", value: { level: 3 } }]);
98
100
  ```
99
101
 
100
- - **`read`, `write`, and `remove`** take items, each naming its scope and key, up to 32, as one request across scopes: a read is one snapshot, and a write or a remove is all made or none.
102
+ - **`read`, `write`, and `remove`** take items, each naming its scope and key, up to 32, as one request across scopes: a read is one snapshot, and a write or a remove is all made or none. With no items, nothing is asked.
101
103
  - **A `revision`** makes a write, or a remove, only if the value is still that one (`0`: only if there's none); otherwise the whole call rejects with `conflict`, and your server reads again.
102
104
  - **`since`** on a read item, a revision you have: if the value is still at it, it comes back `{ scope, key, revision, unchanged: true }`, without its value.
103
105
  - **`list`** gives a scope's keys, with their sizes and times and no values, 50 at a time.
@@ -112,7 +114,7 @@ They reject with an `ArcadibleError`: `invalid`, `denied` (not allowed to a serv
112
114
  ARCADIBLE_SERVE=http://localhost:4100 node server.js
113
115
  ```
114
116
 
115
- With it set, your server takes `arc serve`'s tickets (their channel is `local`), and none of Arcadible's, and `players` asks `arc serve`, with no key. Set it only in development: it must name your own machine, and any other value makes every check fail.
117
+ With it set, your server takes `arc serve`'s tickets (their channel is `local`), and none of Arcadible's, and `players` and `values` ask `arc serve`, with no key. It differs from Arcadible in a few ways: `players.read` knows only the players its tickets named in this run, `players.deleted` is always empty, and the limits on how often you call aren't enforced. Set it only in development: it must name your own machine, and any other value makes every check fail.
116
118
 
117
119
  ## License
118
120
 
@@ -8,7 +8,7 @@ import { type Tickets } from "./tickets.js";
8
8
  */
9
9
  export declare const tickets: Tickets;
10
10
  /**
11
- * The game's players, by the ids its tickets name: their names, and who
11
+ * The game's players, as its tickets name them: their names, and who
12
12
  * deleted their account, asked of Arcadible with the game's key, from
13
13
  * `ARCADIBLE_KEY` in the process's environment.
14
14
  */
@@ -21,7 +21,7 @@ export const tickets = {
21
21
  },
22
22
  };
23
23
  /**
24
- * The game's players, by the ids its tickets name: their names, and who
24
+ * The game's players, as its tickets name them: their names, and who
25
25
  * deleted their account, asked of Arcadible with the game's key, from
26
26
  * `ARCADIBLE_KEY` in the process's environment.
27
27
  */
@@ -10,13 +10,21 @@ export type DeletedPlayer = {
10
10
  export interface Players {
11
11
  /**
12
12
  * Each player, in the order given: their id and name, or `null` for one
13
- * who's gone, never was, or is a guest. Up to 50 ids, each from a ticket.
13
+ * who's gone, never was, or is a guest. Up to 50 players, each anything
14
+ * with a player's `id`: a ticket's `player`, a `deleted` entry, or a
15
+ * `{ id }` the server kept. An id alone isn't taken. A missing player,
16
+ * `null`, as a guest's ticket has, is `null`, and isn't asked for.
17
+ * Rejects with `invalid` for what isn't a list of players, and
18
+ * `too_many` past 50.
14
19
  */
15
- read(ids: readonly string[]): Promise<(Player | null)[]>;
20
+ read(players: readonly ({
21
+ readonly id: string;
22
+ } | null | undefined)[]): Promise<(Player | null)[]>;
16
23
  /**
17
24
  * The players who deleted their accounts in the last 30 days, oldest
18
25
  * first, or those after `since`, an ISO time. Read it on a schedule, and
19
- * clear what the server holds against each.
26
+ * clear what the server holds against each. Rejects with `invalid` for
27
+ * a `since` that isn't a time.
20
28
  */
21
29
  deleted(options?: {
22
30
  since?: string;
@@ -1,5 +1,6 @@
1
1
  // Players, for a server of the developer's own: their names, and who
2
2
  // deleted their account, read on a schedule.
3
+ import { ArcadibleError, Codes } from "../shared/error.js";
3
4
  import { isObject, readPlayers, unreadable, } from "../shared/players.js";
4
5
  // [function]
5
6
  export function createPlayers(api) {
@@ -8,7 +9,7 @@ export function createPlayers(api) {
8
9
  async deleted(options = {}) {
9
10
  const since = options.since;
10
11
  if (since !== undefined && Number.isNaN(Date.parse(since))) {
11
- throw new TypeError("players.deleted's `since` is an ISO time, such as 2026-11-10T00:00:00Z.");
12
+ throw new ArcadibleError(Codes.Invalid, "players.deleted's `since` is an ISO time, such as 2026-11-10T00:00:00Z.");
12
13
  }
13
14
  const query = since === undefined ? "" : `?since=${encodeURIComponent(since)}`;
14
15
  const data = await api().request(`/deleted_players${query}`);
@@ -17,7 +18,9 @@ export function createPlayers(api) {
17
18
  return data.map((entry) => {
18
19
  if (!isObject(entry) ||
19
20
  typeof entry["id"] !== "string" ||
20
- typeof entry["deleted_at"] !== "string") {
21
+ typeof entry["deleted_at"] !== "string" ||
22
+ // a time that isn't one is an answer that can't be read
23
+ Number.isNaN(Date.parse(entry["deleted_at"]))) {
21
24
  throw unreadable();
22
25
  }
23
26
  return {
@@ -11,8 +11,13 @@ export type Ticket = {
11
11
  version: string;
12
12
  /** The build's channel. */
13
13
  channel: Channel;
14
- /** The player's id in this game, the same every time; `null` for a guest. */
15
- player: string | null;
14
+ /**
15
+ * The player, by their id in this game, the same every time; `null` for a
16
+ * guest. What `players.read` and a value's `scope` take.
17
+ */
18
+ player: {
19
+ id: string;
20
+ } | null;
16
21
  /** When it stops being good, as an ISO time. */
17
22
  expiresAt: string;
18
23
  };
@@ -153,7 +153,9 @@ export function createTickets(options = {}) {
153
153
  typeof jti !== "string" ||
154
154
  typeof site !== "string" ||
155
155
  typeof version !== "string" ||
156
- (sub !== undefined && typeof sub !== "string")) {
156
+ // a player is named by their id in the game, a UUID, as every
157
+ // call that takes one asks; no `sub` is a guest
158
+ (sub !== undefined && (typeof sub !== "string" || !UUID.test(sub)))) {
157
159
  throw invalid("it's missing what a ticket says");
158
160
  }
159
161
  const seconds = now() / 1000;
@@ -167,7 +169,7 @@ export function createTickets(options = {}) {
167
169
  expiresAt: new Date(exp * 1000).toISOString(),
168
170
  game: given.game,
169
171
  id: jti,
170
- player: sub ?? null,
172
+ player: sub === undefined ? null : { id: sub },
171
173
  site,
172
174
  version,
173
175
  };
@@ -13,6 +13,11 @@ export declare function isObject(value: unknown): value is Record<string, unknow
13
13
  export declare function unreadable(): ArcadibleError;
14
14
  /**
15
15
  * `players.read`: each player, in the order given, their id and name, or
16
- * `null` for one who's gone, never was, or is a guest. Up to 50 ids.
16
+ * `null` for one who's gone, never was, or is a guest. Up to 50 players,
17
+ * each anything with a player's `id`; an id alone isn't taken. A missing
18
+ * player, `null` or `undefined`, as a guest's ticket has, is `null`, and
19
+ * isn't asked for.
17
20
  */
18
- export declare function readPlayers(api: () => Api): (ids: readonly string[]) => Promise<(Player | null)[]>;
21
+ export declare function readPlayers(api: () => Api): (players: readonly ({
22
+ readonly id: string;
23
+ } | null | undefined)[]) => Promise<(Player | null)[]>;
@@ -1,8 +1,11 @@
1
1
  // Players: what a game's server, or its function, may ask Arcadible about
2
- // the players it knows by their ids: their names. Each package adds its own
3
- // (the server's `deleted`, the function's `primary`).
2
+ // the players it knows: their names. A player is an object, in and out: a
3
+ // call takes anything with a player's `id` (a ticket's `player`, the
4
+ // function's `primary`, a `read`'s or a `deleted`'s entry, a stored
5
+ // `{ id }`), never an id alone, and answers with objects. Each package adds
6
+ // its own (the server's `deleted`, the function's `primary`).
4
7
  import { ArcadibleError, Codes } from "./error.js";
5
- // The most ids one read takes.
8
+ // The most players one read takes.
6
9
  export const MAX_PLAYERS = 50;
7
10
  export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
8
11
  // [function]
@@ -17,19 +20,33 @@ export function unreadable() {
17
20
  // [function]
18
21
  /**
19
22
  * `players.read`: each player, in the order given, their id and name, or
20
- * `null` for one who's gone, never was, or is a guest. Up to 50 ids.
23
+ * `null` for one who's gone, never was, or is a guest. Up to 50 players,
24
+ * each anything with a player's `id`; an id alone isn't taken. A missing
25
+ * player, `null` or `undefined`, as a guest's ticket has, is `null`, and
26
+ * isn't asked for.
21
27
  */
22
28
  export function readPlayers(api) {
23
- return async (ids) => {
24
- if (!Array.isArray(ids) ||
25
- ids.length > MAX_PLAYERS ||
26
- !ids.every((id) => typeof id === "string" && UUID.test(id))) {
27
- throw new TypeError(`players.read takes up to ${MAX_PLAYERS} ids, each a player's id in the game.`);
29
+ return async (players) => {
30
+ if (!Array.isArray(players)) {
31
+ throw new ArcadibleError(Codes.Invalid, "players.read takes a list of players.");
28
32
  }
29
- if (ids.length === 0)
30
- return [];
33
+ if (players.length > MAX_PLAYERS) {
34
+ throw new ArcadibleError(Codes.TooMany, `players.read takes up to ${MAX_PLAYERS} players at once, not ${players.length}.`);
35
+ }
36
+ const ids = players.map((player, index) => {
37
+ if (player === null || player === undefined)
38
+ return null;
39
+ if (!isObject(player) ||
40
+ typeof player["id"] !== "string" ||
41
+ !UUID.test(player["id"])) {
42
+ throw new ArcadibleError(Codes.Invalid, `players.read takes players, each with their id in the game, as { id }: a ticket's player, players.primary(request), or one a server kept. Entry ${index} isn't one; an id alone isn't a player.`);
43
+ }
44
+ return player["id"];
45
+ });
31
46
  // each id once, then every place it was asked for
32
- const asked = [...new Set(ids)];
47
+ const asked = [...new Set(ids.filter((id) => id !== null))];
48
+ if (asked.length === 0)
49
+ return ids.map(() => null);
33
50
  const data = await api().request(`/players/${asked.join(",")}`);
34
51
  if (!Array.isArray(data) || data.length !== asked.length) {
35
52
  throw unreadable();
@@ -47,6 +64,6 @@ export function readPlayers(api) {
47
64
  name: typeof name === "string" && name !== "" ? name : null,
48
65
  });
49
66
  }
50
- return ids.map((id) => found.get(id) ?? null);
67
+ return ids.map((id) => (id === null ? null : (found.get(id) ?? null)));
51
68
  };
52
69
  }
@@ -2,13 +2,13 @@ import type { Api } from "./api.js";
2
2
  /**
3
3
  * Whose the values are: `"developer"`, what the developer publishes, to
4
4
  * read; `"game"`, what every player reads and only the game's server writes;
5
- * `"server"`, the server's alone; or a player, by their id in the game:
6
- * `{ id }`, as `players.primary(request)` or a ticket gives it.
5
+ * `"server"`, the server's alone; or a player: anything with their `id` in
6
+ * the game, as `players.primary(request)` or a ticket's `player` is.
7
7
  */
8
8
  export type Scope = "developer" | WritableScope;
9
9
  /** A scope a server writes: every one but the developer's. */
10
10
  export type WritableScope = "game" | "server" | {
11
- id: string;
11
+ readonly id: string;
12
12
  };
13
13
  /** A value, with the revision a write may name to replace it. */
14
14
  export type Value = {
@@ -74,7 +74,8 @@ export interface Values {
74
74
  /**
75
75
  * The values of the items, in their order, in one call and one snapshot,
76
76
  * across scopes: each with its revision, `Unchanged` for an item whose
77
- * `since` is still its revision, or `null` for a key with none. Up to 32.
77
+ * `since` is still its revision, or `null` for a key with none. Up to
78
+ * 32; with none, `[]`, and nothing is asked.
78
79
  */
79
80
  read(items: readonly ReadItem[]): Promise<(Value | Unchanged | null)[]>;
80
81
  /**
@@ -36,14 +36,13 @@ function scopeOf(scope) {
36
36
  throw invalid('A scope is "developer", "game", "server", or a player, as { id }.');
37
37
  }
38
38
  // [function]
39
- // a call's items: at least one, no more than a call takes, each an object
40
- // with a scope and a key, none named twice in a scope.
39
+ // a call's items: no more than a call takes, each an object with a scope
40
+ // and a key, none named twice in a scope. None at all is a call with
41
+ // nothing to ask, answered without a request.
41
42
  function itemsOf(items) {
42
43
  if (!Array.isArray(items) || !items.every(isObject)) {
43
44
  throw invalid("A call takes a list of items, each { scope, key }.");
44
45
  }
45
- if (items.length === 0)
46
- throw invalid("A call names at least one item.");
47
46
  if (items.length > MAX_KEYS) {
48
47
  throw new ArcadibleError(Codes.TooMany, `A call names up to ${MAX_KEYS} items.`);
49
48
  }
@@ -114,6 +113,8 @@ export function createValues(api) {
114
113
  key: item.key,
115
114
  ...(item.since === undefined ? {} : { since: revisionOf(item.since) }),
116
115
  }));
116
+ if (items.length === 0)
117
+ return [];
117
118
  const data = await api().request("/values/read", { items });
118
119
  if (!Array.isArray(data) || data.length !== items.length) {
119
120
  throw unreadable();
@@ -146,6 +147,8 @@ export function createValues(api) {
146
147
  ? {}
147
148
  : { revision: revisionOf(item.revision) }),
148
149
  }));
150
+ if (items.length === 0)
151
+ return [];
149
152
  const data = await api().request("/values/write", { items });
150
153
  if (!Array.isArray(data) || data.length !== items.length) {
151
154
  throw unreadable();
@@ -168,6 +171,8 @@ export function createValues(api) {
168
171
  ? {}
169
172
  : { revision: revisionOf(item.revision) }),
170
173
  }));
174
+ if (items.length === 0)
175
+ return;
171
176
  await api().request("/values/remove", { items });
172
177
  };
173
178
  const list = async function (scope, options = {}) {
package/package.json CHANGED
@@ -28,5 +28,5 @@
28
28
  },
29
29
  "type": "module",
30
30
  "types": "./dist/server/index.d.ts",
31
- "version": "0.4.0-next.0"
31
+ "version": "0.5.0-next.0"
32
32
  }