@deliverd/sdk 0.9.0 → 0.10.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/src/messages.ts CHANGED
@@ -1,161 +1,161 @@
1
- /**
2
- * What a failure says.
3
- *
4
- * An error is part of the interface, and `ERR_POLICY_SUBJECT_RESOLUTION_FAILED`
5
- * is an interface that tells a developer to go and read something. These say
6
- * what happened, why, and the one thing to do next — because the person
7
- * reading it is stuck, at a keyboard, and does not want a search engine.
8
- *
9
- * Keyed on the codes the API actually returns. Anything unlisted keeps the
10
- * API's own message, which is written for a person too.
11
- */
12
-
13
- export interface Explanation {
14
- /** Replaces the API's message when we can say it better. */
15
- message?: string;
16
- /** The line under it: what to do. */
17
- hint: string;
18
- }
19
-
20
- export const EXPLANATIONS: Record<string, Explanation> = {
21
- no_api_key: {
22
- message: "No API key.",
23
- hint: "Set DELIVERD_API_KEY in your environment, or pass { apiKey } — or use { mode: \"development\" } to run without one.",
24
- },
25
- auth_error: {
26
- message: "That credential was not accepted.",
27
- /*
28
- * Both families, because both work: a `dlv_` key somebody created, or a
29
- * `dlvo_` access token from an OAuth connector. Naming only the first is
30
- * how a connector's token gets thrown away and replaced with a key
31
- * nobody needed to create.
32
- *
33
- * Credentials only. A missing scope is `insufficient_scope` below and has
34
- * been since `ApiScopeError` existed — the two shared this code before
35
- * that, which is how somebody whose key was perfectly good came to be told
36
- * to go and check their key.
37
- */
38
- hint: "Check DELIVERD_API_KEY. An API key starts with dlv_ and is created in Settings → API tokens; an OAuth access token starts with dlvo_ and needs no setup.",
39
- },
40
- insufficient_scope: {
41
- message: "That credential is valid and does not carry the scope this call needs.",
42
- hint: "Reissue the key with the scope named above, or re-consent the connector for it. A credential issued before a scope existed does not have it — nothing is wrong with the key itself, so replacing it with another of the same scopes will fail the same way.",
43
- },
44
- unknown_approver: {
45
- message: "No approver could be found for this request.",
46
- hint: "Everyone in `approvers` must be an active member of your organisation, named by email or user id. Invite them first, or leave `approvers` out and your owners and admins decide.",
47
- },
48
- self_approval: {
49
- message: "You cannot approve your own request.",
50
- hint: "Name somebody else in `approvers`, or leave it out so your organisation's owners and admins decide.",
51
- },
52
- not_approver: {
53
- hint: "Only the people named on the request can decide it.",
54
- },
55
- not_requester: {
56
- message: "Only the requester can answer a question on their own request.",
57
- hint: "Use the same key that created the approval.",
58
- },
59
- not_pending: {
60
- message: "That request was already decided.",
61
- hint: "Read its status rather than deciding again; a decision is final.",
62
- },
63
- expired: {
64
- message: "That request expired before anyone decided it.",
65
- hint: "Ask again, with a longer `expiresIn`, or chase the approver.",
66
- },
67
- rate_limited: {
68
- message: "Too many requests.",
69
- hint: "The SDK already retried and gave up. Reduce how often you poll, or wait with `approve()` rather than looping yourself.",
70
- },
71
- plan_limit: {
72
- hint: "Your organisation's plan does not include this. Billing → Plans.",
73
- },
74
- network_error: {
75
- hint: "Check the machine's network and `baseUrl`. Deliverd's status is at https://deliverd.dev.",
76
- },
77
- timeout: {
78
- hint: "You stopped waiting; the request is still open at the URL above until it expires. If an approver asked a question, answer it with an `onQuestion` handler — an unanswered question is the commonest reason a wait runs out.",
79
- },
80
- /*
81
- * The one code every namespace can return, and the only entry here that is
82
- * about what a status *means* rather than about a particular call.
83
- *
84
- * It had none until a policy id that does not exist stopped answering 500,
85
- * and the reason to write one is the half a reader does not expect: a 404
86
- * is also what this API says when the thing is there and not theirs. It is
87
- * one answer on purpose — telling the two apart would say whether the id
88
- * exists for somebody else — so "it was deleted" is a guess, and a retry
89
- * cannot turn it into anything else.
90
- *
91
- * No `message`: the server's own sentence names the resource, and this
92
- * table cannot, being shared by approvals, reports and policies alike.
93
- */
94
- not_found: {
95
- hint: "Nothing with that id, or nothing this key may see — the API does not say which, because saying would tell you whether it exists for somebody else. Check the id, and that the key belongs to the organisation that owns it. Retrying will not change the answer.",
96
- },
97
- /*
98
- * The 404s that name their own resource. Each is here for a fact the
99
- * server's sentence cannot carry, which is the only reason to add one —
100
- * repeating "not found" under a longer name would be noise.
101
- *
102
- * `report_not_found` is deliberately absent. Placing and releasing a legal
103
- * hold is web-only by design, so no route can send it and an entry would be
104
- * advice nobody receives; `sdk-parity.test.ts` holds that omission to the
105
- * reason the app already records, and fails if the code ever becomes
106
- * reachable.
107
- */
108
- agent_not_found: {
109
- message: "The agent identity this key acts as is not there any more.",
110
- hint: "Nothing is wrong with the credential — it still authenticates, and what is gone is the identity it speaks as. Recreate the agent under Admin → Agents, or issue a key bound to one that exists. Every call this key makes fails the same way until then.",
111
- },
112
- upload_not_found: {
113
- hint: "A publish consumes the bundle it reads, so this is what a *second* publish with the same `uploadId` gets — which means the first one may well have worked. Look at the report before uploading again, or you will publish it twice.",
114
- },
115
- question_not_found: {
116
- hint: "Question ids belong to one approval, so this is usually an id from a different one. Take it from that approval's own questions — an `onQuestion` handler is handed it — rather than from anywhere you cached it. A question already answered is `already_answered`, not this.",
117
- },
118
- quote_not_found: {
119
- hint: "The passage is not in the version the message names. A republish rewrites the text, so a quote taken before one stops matching: read the current version and quote what it says now. A quote that matches in several places is `quote_ambiguous` instead, and an empty one is `quote_empty`.",
120
- },
121
- /*
122
- * The gate and its policy, which had no entries at all until the codes were
123
- * told apart — the newest surface in the API and the one a reader is least
124
- * likely to recognise, falling through to the server's own message with no
125
- * next step.
126
- *
127
- * The first two are met through `deliverd.gate()`. The last three come from
128
- * authoring, which no namespace covers, so a caller reaches them through
129
- * `deliverd.http` — still the API's codes, still worth explaining, and the
130
- * reason this table is keyed on what the API returns rather than on which
131
- * namespace produced it.
132
- */
133
- unknown_action: {
134
- message: "No action by that name is registered.",
135
- hint: "Register it first — `deliverd actions push`, or POST /v1/actions — and use the same dotted id. A gate on an unregistered action is refused before any rule is read, so this is not a policy saying no.",
136
- },
137
- invalid_input: {
138
- message: "The arguments do not match the action's registered schema.",
139
- hint: "Read `details` for the field. The schema is the one your organisation registered for this action, so either the call is wrong or the registration is out of date.",
140
- },
141
- invalid_rules: {
142
- message: "Those rules cannot be stored as written.",
143
- hint: "Read `details` — it names each condition that could not be checked, usually a field no registered action declares. This is refused now rather than at evaluation, where the rule would match nothing and look like one that had simply not fired.",
144
- },
145
- duplicate: {
146
- hint: "Something with that name is already there. Add a version to it rather than creating a second one.",
147
- },
148
- superseded: {
149
- hint: "It was replaced while you were working. Read the current one and act on that; copy its contents into a new version rather than reviving the old, because a past decision points at what it said.",
150
- },
151
- invalid_signature: {
152
- hint: "Check the endpoint's signing secret, and that you passed the raw request body rather than a re-encoded object.",
153
- },
154
- };
155
-
156
- /** The message as a developer should read it: what happened, then what to do. */
157
- export function explain(code: string, apiMessage: string): { message: string; hint?: string } {
158
- const found = EXPLANATIONS[code];
159
- if (!found) return { message: apiMessage };
160
- return { message: `${found.message ?? apiMessage}\n${found.hint}`, hint: found.hint };
161
- }
1
+ /**
2
+ * What a failure says.
3
+ *
4
+ * An error is part of the interface, and `ERR_POLICY_SUBJECT_RESOLUTION_FAILED`
5
+ * is an interface that tells a developer to go and read something. These say
6
+ * what happened, why, and the one thing to do next — because the person
7
+ * reading it is stuck, at a keyboard, and does not want a search engine.
8
+ *
9
+ * Keyed on the codes the API actually returns. Anything unlisted keeps the
10
+ * API's own message, which is written for a person too.
11
+ */
12
+
13
+ export interface Explanation {
14
+ /** Replaces the API's message when we can say it better. */
15
+ message?: string;
16
+ /** The line under it: what to do. */
17
+ hint: string;
18
+ }
19
+
20
+ export const EXPLANATIONS: Record<string, Explanation> = {
21
+ no_api_key: {
22
+ message: "No API key.",
23
+ hint: "Set DELIVERD_API_KEY in your environment, or pass { apiKey } — or use { mode: \"development\" } to run without one.",
24
+ },
25
+ auth_error: {
26
+ message: "That credential was not accepted.",
27
+ /*
28
+ * Both families, because both work: a `dlv_` key somebody created, or a
29
+ * `dlvo_` access token from an OAuth connector. Naming only the first is
30
+ * how a connector's token gets thrown away and replaced with a key
31
+ * nobody needed to create.
32
+ *
33
+ * Credentials only. A missing scope is `insufficient_scope` below and has
34
+ * been since `ApiScopeError` existed — the two shared this code before
35
+ * that, which is how somebody whose key was perfectly good came to be told
36
+ * to go and check their key.
37
+ */
38
+ hint: "Check DELIVERD_API_KEY. An API key starts with dlv_ and is created in Settings → API tokens; an OAuth access token starts with dlvo_ and needs no setup.",
39
+ },
40
+ insufficient_scope: {
41
+ message: "That credential is valid and does not carry the scope this call needs.",
42
+ hint: "Reissue the key with the scope named above, or re-consent the connector for it. A credential issued before a scope existed does not have it — nothing is wrong with the key itself, so replacing it with another of the same scopes will fail the same way.",
43
+ },
44
+ unknown_approver: {
45
+ message: "No approver could be found for this request.",
46
+ hint: "Everyone in `approvers` must be an active member of your organisation, named by email or user id. Invite them first, or leave `approvers` out and your owners and admins decide.",
47
+ },
48
+ self_approval: {
49
+ message: "You cannot approve your own request.",
50
+ hint: "Name somebody else in `approvers`, or leave it out so your organisation's owners and admins decide.",
51
+ },
52
+ not_approver: {
53
+ hint: "Only the people named on the request can decide it.",
54
+ },
55
+ not_requester: {
56
+ message: "Only the requester can answer a question on their own request.",
57
+ hint: "Use the same key that created the approval.",
58
+ },
59
+ not_pending: {
60
+ message: "That request was already decided.",
61
+ hint: "Read its status rather than deciding again; a decision is final.",
62
+ },
63
+ expired: {
64
+ message: "That request expired before anyone decided it.",
65
+ hint: "Ask again, with a longer `expiresIn`, or chase the approver.",
66
+ },
67
+ rate_limited: {
68
+ message: "Too many requests.",
69
+ hint: "The SDK already retried and gave up. Reduce how often you poll, or wait with `approve()` rather than looping yourself.",
70
+ },
71
+ plan_limit: {
72
+ hint: "Your organisation's plan does not include this. Billing → Plans.",
73
+ },
74
+ network_error: {
75
+ hint: "Check the machine's network and `baseUrl`. Deliverd's status is at https://deliverd.dev.",
76
+ },
77
+ timeout: {
78
+ hint: "You stopped waiting; the request is still open at the URL above until it expires. If an approver asked a question, answer it with an `onQuestion` handler — an unanswered question is the commonest reason a wait runs out.",
79
+ },
80
+ /*
81
+ * The one code every namespace can return, and the only entry here that is
82
+ * about what a status *means* rather than about a particular call.
83
+ *
84
+ * It had none until a policy id that does not exist stopped answering 500,
85
+ * and the reason to write one is the half a reader does not expect: a 404
86
+ * is also what this API says when the thing is there and not theirs. It is
87
+ * one answer on purpose — telling the two apart would say whether the id
88
+ * exists for somebody else — so "it was deleted" is a guess, and a retry
89
+ * cannot turn it into anything else.
90
+ *
91
+ * No `message`: the server's own sentence names the resource, and this
92
+ * table cannot, being shared by approvals, reports and policies alike.
93
+ */
94
+ not_found: {
95
+ hint: "Nothing with that id, or nothing this key may see — the API does not say which, because saying would tell you whether it exists for somebody else. Check the id, and that the key belongs to the organisation that owns it. Retrying will not change the answer.",
96
+ },
97
+ /*
98
+ * The 404s that name their own resource. Each is here for a fact the
99
+ * server's sentence cannot carry, which is the only reason to add one —
100
+ * repeating "not found" under a longer name would be noise.
101
+ *
102
+ * `report_not_found` is deliberately absent. Placing and releasing a legal
103
+ * hold is web-only by design, so no route can send it and an entry would be
104
+ * advice nobody receives; `sdk-parity.test.ts` holds that omission to the
105
+ * reason the app already records, and fails if the code ever becomes
106
+ * reachable.
107
+ */
108
+ agent_not_found: {
109
+ message: "The agent identity this key acts as is not there any more.",
110
+ hint: "Nothing is wrong with the credential — it still authenticates, and what is gone is the identity it speaks as. Recreate the agent under Admin → Agents, or issue a key bound to one that exists. Every call this key makes fails the same way until then.",
111
+ },
112
+ upload_not_found: {
113
+ hint: "A publish consumes the bundle it reads, so this is what a *second* publish with the same `uploadId` gets — which means the first one may well have worked. Look at the report before uploading again, or you will publish it twice.",
114
+ },
115
+ question_not_found: {
116
+ hint: "Question ids belong to one approval, so this is usually an id from a different one. Take it from that approval's own questions — an `onQuestion` handler is handed it — rather than from anywhere you cached it. A question already answered is `already_answered`, not this.",
117
+ },
118
+ quote_not_found: {
119
+ hint: "The passage is not in the version the message names. A republish rewrites the text, so a quote taken before one stops matching: read the current version and quote what it says now. A quote that matches in several places is `quote_ambiguous` instead, and an empty one is `quote_empty`.",
120
+ },
121
+ /*
122
+ * The gate and its policy, which had no entries at all until the codes were
123
+ * told apart — the newest surface in the API and the one a reader is least
124
+ * likely to recognise, falling through to the server's own message with no
125
+ * next step.
126
+ *
127
+ * The first two are met through `deliverd.gate()`. The last three come from
128
+ * authoring, which no namespace covers, so a caller reaches them through
129
+ * `deliverd.http` — still the API's codes, still worth explaining, and the
130
+ * reason this table is keyed on what the API returns rather than on which
131
+ * namespace produced it.
132
+ */
133
+ unknown_action: {
134
+ message: "No action by that name is registered.",
135
+ hint: "Register it first — `deliverd actions push`, or POST /v1/actions — and use the same dotted id. A gate on an unregistered action is refused before any rule is read, so this is not a policy saying no.",
136
+ },
137
+ invalid_input: {
138
+ message: "The arguments do not match the action's registered schema.",
139
+ hint: "Read `details` for the field. The schema is the one your organisation registered for this action, so either the call is wrong or the registration is out of date.",
140
+ },
141
+ invalid_rules: {
142
+ message: "Those rules cannot be stored as written.",
143
+ hint: "Read `details` — it names each condition that could not be checked, usually a field no registered action declares. This is refused now rather than at evaluation, where the rule would match nothing and look like one that had simply not fired.",
144
+ },
145
+ duplicate: {
146
+ hint: "Something with that name is already there. Add a version to it rather than creating a second one.",
147
+ },
148
+ superseded: {
149
+ hint: "It was replaced while you were working. Read the current one and act on that; copy its contents into a new version rather than reviving the old, because a past decision points at what it said.",
150
+ },
151
+ invalid_signature: {
152
+ hint: "Check the endpoint's signing secret, and that you passed the raw request body rather than a re-encoded object.",
153
+ },
154
+ };
155
+
156
+ /** The message as a developer should read it: what happened, then what to do. */
157
+ export function explain(code: string, apiMessage: string): { message: string; hint?: string } {
158
+ const found = EXPLANATIONS[code];
159
+ if (!found) return { message: apiMessage };
160
+ return { message: `${found.message ?? apiMessage}\n${found.hint}`, hint: found.hint };
161
+ }
package/src/paging.ts CHANGED
@@ -1,64 +1,64 @@
1
- import type { HttpClient } from "./http.js";
2
-
3
- /**
4
- * What the SDK does about a list that does not fit in one answer.
5
- *
6
- * The API says where it stopped: a response carries `nextCursor`, null when
7
- * the page is the end of the list and a string to pass back when it is not.
8
- * That leaves the client one decision, and it is worth stating rather than
9
- * leaving to whoever reads the call:
10
- *
11
- * **`limit` set means one page of that size. `limit` unset means all of
12
- * them.** `list()` with no limit follows the cursor until the API stops
13
- * offering one, so `.length` is the real count rather than a page size that
14
- * happens to look like one. A caller who wants to page by hand asks for a
15
- * `limit`, or uses `listPage` and drives the cursor themselves.
16
- *
17
- * The alternative — return a page and let the caller notice — reads fine and
18
- * fails quietly, because a full page and a complete list are indistinguishable
19
- * until somebody counts.
20
- */
21
- export interface PageInput {
22
- limit?: number;
23
- cursor?: string;
24
- }
25
-
26
- export interface PageOf<T> {
27
- items: T[];
28
- nextCursor: string | null;
29
- }
30
-
31
- /**
32
- * Follow the cursor to the end, collecting as we go.
33
- *
34
- * `fetchPage` is whatever single request the caller's endpoint makes; this
35
- * only decides when to ask again. A page that comes back empty while still
36
- * offering a cursor ends the loop as well — a server that did that would
37
- * otherwise spin here for ever.
38
- */
39
- export async function collect<T>(
40
- fetchPage: (cursor: string | null) => Promise<PageOf<T>>
41
- ): Promise<T[]> {
42
- const all: T[] = [];
43
- let cursor: string | null = null;
44
- for (;;) {
45
- const page: PageOf<T> = await fetchPage(cursor);
46
- all.push(...page.items);
47
- if (!page.nextCursor || page.items.length === 0) return all;
48
- cursor = page.nextCursor;
49
- }
50
- }
51
-
52
- /** One page, or every page, depending on whether a limit was asked for. */
53
- export async function listOrCollect<T>(
54
- input: PageInput,
55
- fetchPage: (query: { limit?: number; cursor?: string }) => Promise<PageOf<T>>
56
- ): Promise<T[]> {
57
- if (input.limit !== undefined) {
58
- const page = await fetchPage({ limit: input.limit, cursor: input.cursor });
59
- return page.items;
60
- }
61
- return collect((cursor) => fetchPage({ cursor: cursor ?? undefined }));
62
- }
63
-
64
- export type { HttpClient };
1
+ import type { HttpClient } from "./http.js";
2
+
3
+ /**
4
+ * What the SDK does about a list that does not fit in one answer.
5
+ *
6
+ * The API says where it stopped: a response carries `nextCursor`, null when
7
+ * the page is the end of the list and a string to pass back when it is not.
8
+ * That leaves the client one decision, and it is worth stating rather than
9
+ * leaving to whoever reads the call:
10
+ *
11
+ * **`limit` set means one page of that size. `limit` unset means all of
12
+ * them.** `list()` with no limit follows the cursor until the API stops
13
+ * offering one, so `.length` is the real count rather than a page size that
14
+ * happens to look like one. A caller who wants to page by hand asks for a
15
+ * `limit`, or uses `listPage` and drives the cursor themselves.
16
+ *
17
+ * The alternative — return a page and let the caller notice — reads fine and
18
+ * fails quietly, because a full page and a complete list are indistinguishable
19
+ * until somebody counts.
20
+ */
21
+ export interface PageInput {
22
+ limit?: number;
23
+ cursor?: string;
24
+ }
25
+
26
+ export interface PageOf<T> {
27
+ items: T[];
28
+ nextCursor: string | null;
29
+ }
30
+
31
+ /**
32
+ * Follow the cursor to the end, collecting as we go.
33
+ *
34
+ * `fetchPage` is whatever single request the caller's endpoint makes; this
35
+ * only decides when to ask again. A page that comes back empty while still
36
+ * offering a cursor ends the loop as well — a server that did that would
37
+ * otherwise spin here for ever.
38
+ */
39
+ export async function collect<T>(
40
+ fetchPage: (cursor: string | null) => Promise<PageOf<T>>
41
+ ): Promise<T[]> {
42
+ const all: T[] = [];
43
+ let cursor: string | null = null;
44
+ for (;;) {
45
+ const page: PageOf<T> = await fetchPage(cursor);
46
+ all.push(...page.items);
47
+ if (!page.nextCursor || page.items.length === 0) return all;
48
+ cursor = page.nextCursor;
49
+ }
50
+ }
51
+
52
+ /** One page, or every page, depending on whether a limit was asked for. */
53
+ export async function listOrCollect<T>(
54
+ input: PageInput,
55
+ fetchPage: (query: { limit?: number; cursor?: string }) => Promise<PageOf<T>>
56
+ ): Promise<T[]> {
57
+ if (input.limit !== undefined) {
58
+ const page = await fetchPage({ limit: input.limit, cursor: input.cursor });
59
+ return page.items;
60
+ }
61
+ return collect((cursor) => fetchPage({ cursor: cursor ?? undefined }));
62
+ }
63
+
64
+ export type { HttpClient };