@hecks/client 3.1.3 → 3.2.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 +3 -2
- package/dist/client.d.ts +11 -1
- package/dist/client.js +20 -4
- package/dist/client.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -82,6 +82,7 @@ const repriced = await client.apply({
|
|
|
82
82
|
| `domain` | The domain's name as its bluebook declares it. Falls back to the `HECKS_DOMAIN` environment variable. Required. |
|
|
83
83
|
| `url` | Where the host listens. Trailing slashes are trimmed. Falls back to the `HECKS_SERVICE_URL` environment variable. Required. |
|
|
84
84
|
| `role` | The role sent with every command unless a call names its own. The host compares it as a plain string against the roles a command declares. When neither the client nor the call sets one, no role is sent and the host performs no role check. |
|
|
85
|
+
| `actorId` | The Governance identity id of the signed-in person, sent as `actor_id` with every command unless a call names its own. An identified caller should pass this and leave `role` unset, so Governance's role assignments decide. The host honors `actor_id` only on its internal protocol, from its own peers. |
|
|
85
86
|
| `timeoutMs` | How long one request may take before it counts as unreachable. Defaults to `8000`. |
|
|
86
87
|
| `fetch` | The `fetch` to send requests with, for tests or a custom agent. Defaults to the global `fetch`, looked up on each call. |
|
|
87
88
|
|
|
@@ -95,8 +96,8 @@ missing domain or URL throws a `TypeError`.
|
|
|
95
96
|
- `domain`, `url`: the resolved configuration.
|
|
96
97
|
- `qualify(name)`: places a bare name in the client's domain (`"Event"` becomes `"Shop::Event"`). A name that already contains `::` is returned unchanged.
|
|
97
98
|
- `read(): Promise<Answer>`: posts `{"read": true}` and returns everything the domain holds.
|
|
98
|
-
- `dispatch(verb, args = {}, to?, role?): Promise<Answer>`: posts one command and returns the raw answer. `verb` is `Aggregate.Verb` or fully qualified. `to` targets an existing instance and is omitted for a command that creates one.
|
|
99
|
-
- `apply<T>(command): Promise<T>`: dispatches `command.verb` with `command.with`, `command.to` and `command.
|
|
99
|
+
- `dispatch(verb, args = {}, to?, role?, actorId?): Promise<Answer>`: posts one command and returns the raw answer. `verb` is `Aggregate.Verb` or fully qualified. `to` targets an existing instance and is omitted for a command that creates one.
|
|
100
|
+
- `apply<T>(command): Promise<T>`: dispatches `command.verb` with `command.with`, `command.to`, `command.role` and `command.actorId`, reads the answer with `command.parse`, and returns the result when `command.confirm` accepts it. Otherwise it throws `DomainRefusal` built from the answer's last refusal.
|
|
100
101
|
- `instancesOf(answer, aggregate): [string, state][]`: the states of one aggregate, bare or qualified name.
|
|
101
102
|
|
|
102
103
|
Standalone readers, importable without a client:
|
package/dist/client.d.ts
CHANGED
|
@@ -12,6 +12,13 @@ export interface ClientOptions {
|
|
|
12
12
|
* no role check.
|
|
13
13
|
*/
|
|
14
14
|
role?: string;
|
|
15
|
+
/**
|
|
16
|
+
* The Governance identity id of the person on whose behalf commands run,
|
|
17
|
+
* sent as `actor_id` with every command unless a call names its own. Pass
|
|
18
|
+
* it for an identified caller and leave `role` unset, so Governance's role
|
|
19
|
+
* assignments decide. The host honors it only on its internal protocol.
|
|
20
|
+
*/
|
|
21
|
+
actorId?: string;
|
|
15
22
|
/** How long one request may take before it counts as unreachable. Defaults to 8000. */
|
|
16
23
|
timeoutMs?: number;
|
|
17
24
|
/** The fetch to send requests with. Defaults to the global `fetch`, looked up on each call. */
|
|
@@ -29,6 +36,8 @@ export interface Command<T> {
|
|
|
29
36
|
/** The target instance id; absent for a command that creates one. */
|
|
30
37
|
to?: string;
|
|
31
38
|
role?: string;
|
|
39
|
+
/** The Governance identity id of the caller; see `ClientOptions.actorId`. */
|
|
40
|
+
actorId?: string;
|
|
32
41
|
parse: (answer: Answer) => T;
|
|
33
42
|
confirm: (parsed: T) => boolean;
|
|
34
43
|
}
|
|
@@ -39,6 +48,7 @@ export declare class HostClient {
|
|
|
39
48
|
/** The host's base URL, without a trailing slash. */
|
|
40
49
|
readonly url: string;
|
|
41
50
|
private readonly role;
|
|
51
|
+
private readonly actorId;
|
|
42
52
|
private readonly timeoutMs;
|
|
43
53
|
private readonly fetchImpl;
|
|
44
54
|
constructor(options?: ClientOptions);
|
|
@@ -52,7 +62,7 @@ export declare class HostClient {
|
|
|
52
62
|
* Sends one command and returns the raw answer. Callers judge the outcome
|
|
53
63
|
* from the state in it and turn a miss into a refusal with `refusalOf`.
|
|
54
64
|
*/
|
|
55
|
-
dispatch(verb: string, args?: Record<string, unknown>, to?: string, role?: string): Promise<Answer>;
|
|
65
|
+
dispatch(verb: string, args?: Record<string, unknown>, to?: string, role?: string, actorId?: string): Promise<Answer>;
|
|
56
66
|
/**
|
|
57
67
|
* Runs one command and returns what `command.parse` reads from the answer.
|
|
58
68
|
* Throws `DomainRefusal` when that state does not show the change,
|
package/dist/client.js
CHANGED
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
//
|
|
4
4
|
// { "read": true }
|
|
5
5
|
// -> { instances: { "Domain::Aggregate#<id>": { ...state } }, refusals: [] }
|
|
6
|
-
// { "verb": "Domain::Aggregate.Verb", "to": "<id>", "with": { ... },
|
|
6
|
+
// { "verb": "Domain::Aggregate.Verb", "to": "<id>", "with": { ... },
|
|
7
|
+
// "role": "Role", "actor_id": "<id>" }
|
|
7
8
|
// -> the same shape after the command ran
|
|
8
9
|
//
|
|
9
10
|
// The host answers HTTP 200 whether or not the domain refused, and its
|
|
@@ -11,6 +12,12 @@
|
|
|
11
12
|
// judged by the state that comes back (see `HostClient#apply`), never by the
|
|
12
13
|
// list alone.
|
|
13
14
|
//
|
|
15
|
+
// An identified caller passes `actorId`, the Governance identity id of the
|
|
16
|
+
// signed-in person, and leaves `role` unset: the host then checks the roles
|
|
17
|
+
// Governance has assigned to that actor. A stated `role` is a label the
|
|
18
|
+
// caller writes, not a proof. The host honors `actor_id` only on its
|
|
19
|
+
// internal protocol, from its own peers.
|
|
20
|
+
//
|
|
14
21
|
// The protocol carries no authentication. It is meant for server-to-server
|
|
15
22
|
// calls on a private network, never for a browser.
|
|
16
23
|
import { refusalOf, DomainUnavailable } from "./errors.js";
|
|
@@ -27,6 +34,7 @@ export class HostClient {
|
|
|
27
34
|
/** The host's base URL, without a trailing slash. */
|
|
28
35
|
url;
|
|
29
36
|
role;
|
|
37
|
+
actorId;
|
|
30
38
|
timeoutMs;
|
|
31
39
|
fetchImpl;
|
|
32
40
|
constructor(options = {}) {
|
|
@@ -39,6 +47,7 @@ export class HostClient {
|
|
|
39
47
|
this.domain = domain;
|
|
40
48
|
this.url = url.replace(/\/+$/, "");
|
|
41
49
|
this.role = options.role;
|
|
50
|
+
this.actorId = options.actorId;
|
|
42
51
|
this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
43
52
|
this.fetchImpl = options.fetch;
|
|
44
53
|
}
|
|
@@ -58,9 +67,16 @@ export class HostClient {
|
|
|
58
67
|
* Sends one command and returns the raw answer. Callers judge the outcome
|
|
59
68
|
* from the state in it and turn a miss into a refusal with `refusalOf`.
|
|
60
69
|
*/
|
|
61
|
-
dispatch(verb, args = {}, to, role) {
|
|
70
|
+
dispatch(verb, args = {}, to, role, actorId) {
|
|
62
71
|
const asRole = role ?? this.role;
|
|
63
|
-
|
|
72
|
+
const asActor = actorId ?? this.actorId;
|
|
73
|
+
return this.post({
|
|
74
|
+
verb: this.qualify(verb),
|
|
75
|
+
...(to ? { to } : {}),
|
|
76
|
+
with: args,
|
|
77
|
+
...(asRole ? { role: asRole } : {}),
|
|
78
|
+
...(asActor ? { actor_id: asActor } : {}),
|
|
79
|
+
});
|
|
64
80
|
}
|
|
65
81
|
/**
|
|
66
82
|
* Runs one command and returns what `command.parse` reads from the answer.
|
|
@@ -68,7 +84,7 @@ export class HostClient {
|
|
|
68
84
|
* carrying the domain's own words for why.
|
|
69
85
|
*/
|
|
70
86
|
async apply(command) {
|
|
71
|
-
const answer = await this.dispatch(command.verb, command.with, command.to, command.role);
|
|
87
|
+
const answer = await this.dispatch(command.verb, command.with, command.to, command.role, command.actorId);
|
|
72
88
|
const parsed = command.parse(answer);
|
|
73
89
|
if (command.confirm(parsed))
|
|
74
90
|
return parsed;
|
package/dist/client.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,mDAAmD;AACnD,EAAE;AACF,qBAAqB;AACrB,iFAAiF;AACjF,
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED