@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 +10 -8
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +1 -1
- package/dist/server/players.d.ts +11 -3
- package/dist/server/players.js +5 -2
- package/dist/server/tickets.d.ts +7 -2
- package/dist/server/tickets.js +4 -2
- package/dist/shared/players.d.ts +7 -2
- package/dist/shared/players.js +30 -13
- package/dist/shared/values.d.ts +5 -4
- package/dist/shared/values.js +9 -4
- package/package.json +1 -1
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
|
|
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
|
|
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,
|
|
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
|
-
-
|
|
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,
|
|
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:
|
|
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`
|
|
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
|
|
package/dist/server/index.d.ts
CHANGED
|
@@ -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,
|
|
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
|
*/
|
package/dist/server/index.js
CHANGED
|
@@ -21,7 +21,7 @@ export const tickets = {
|
|
|
21
21
|
},
|
|
22
22
|
};
|
|
23
23
|
/**
|
|
24
|
-
* The game's players,
|
|
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
|
*/
|
package/dist/server/players.d.ts
CHANGED
|
@@ -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
|
|
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(
|
|
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;
|
package/dist/server/players.js
CHANGED
|
@@ -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
|
|
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 {
|
package/dist/server/tickets.d.ts
CHANGED
|
@@ -11,8 +11,13 @@ export type Ticket = {
|
|
|
11
11
|
version: string;
|
|
12
12
|
/** The build's channel. */
|
|
13
13
|
channel: Channel;
|
|
14
|
-
/**
|
|
15
|
-
|
|
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
|
};
|
package/dist/server/tickets.js
CHANGED
|
@@ -153,7 +153,9 @@ export function createTickets(options = {}) {
|
|
|
153
153
|
typeof jti !== "string" ||
|
|
154
154
|
typeof site !== "string" ||
|
|
155
155
|
typeof version !== "string" ||
|
|
156
|
-
|
|
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
|
|
172
|
+
player: sub === undefined ? null : { id: sub },
|
|
171
173
|
site,
|
|
172
174
|
version,
|
|
173
175
|
};
|
package/dist/shared/players.d.ts
CHANGED
|
@@ -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
|
|
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): (
|
|
21
|
+
export declare function readPlayers(api: () => Api): (players: readonly ({
|
|
22
|
+
readonly id: string;
|
|
23
|
+
} | null | undefined)[]) => Promise<(Player | null)[]>;
|
package/dist/shared/players.js
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
// Players: what a game's server, or its function, may ask Arcadible about
|
|
2
|
-
// the players it knows
|
|
3
|
-
//
|
|
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
|
|
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
|
|
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 (
|
|
24
|
-
if (!Array.isArray(
|
|
25
|
-
|
|
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 (
|
|
30
|
-
|
|
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
|
}
|
package/dist/shared/values.d.ts
CHANGED
|
@@ -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
|
|
6
|
-
*
|
|
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
|
|
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
|
/**
|
package/dist/shared/values.js
CHANGED
|
@@ -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:
|
|
40
|
-
//
|
|
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