@hecks/client 2.7.0

package/README.md

@@ -0,0 +1,310 @@
+# @hecks/client
+
+A small TypeScript client for the body-shaped dispatch protocol a Hecks host
+answers. It reads the state of a domain, dispatches commands to it, and turns
+the answers into typed values. It has no runtime dependencies and uses the
+platform `fetch`, so it needs Node 18 or newer.
+
+Beside the dispatch client it carries the other server-side pieces a site in
+front of a host tends to need: a JSON reader that survives a briefly
+unavailable upstream (`createResilientFetch`), a client for the host's
+payment-connection API (`PaymentsConnection`), and a verifier for the account
+token the host signs (`verifyAccountToken`). Each is described below.
+
+The host answers this protocol on any path but `/` when it runs with
+`HECKS_SERVE_MODE=1` (`rust/host`). The client posts to `<url>/dispatch`. The
+protocol has no authentication: use it server to server on a private network,
+never from a browser.
+
+## Install
+
+The package is versioned with the `hecks` gem and published under the `@hecks`
+npm scope:
+
+```sh
+npm install @hecks/client
+```
+
+The `hecks` organization exists on npm, but no version is published yet. Until
+the first publish, install from a release tag of the repository instead (the
+package lives in `packages/hecks-client`, so use a tool that can install from a
+subdirectory, or a tarball built with `npm pack`):
+
+```sh
+git clone --branch v<version> https://github.com/heckslabs/hecks.git
+cd hecks/packages/hecks-client && npm ci && npm pack
+npm install ./hecks-client-<version>.tgz
+```
+
+`<version>` is a release of the gem, such as `2.6.0`: the package carries the
+same version as the `hecks` gem it was released with, so pick the one matching
+the host you talk to.
+
+The package is ESM and ships its type declarations.
+
+## Use
+
+```ts
+import { HostClient, text, whole } from "@hecks/client";
+
+const client = new HostClient({
+  domain: "Shop",
+  url: "http://127.0.0.1:4322",
+  role: "Organizer",
+});
+
+// Everything the domain holds.
+const answer = await client.read();
+
+// One aggregate's states, as [id, state] pairs.
+const events = client.instancesOf(answer, "Event").map(([id, state]) => ({
+  id,
+  name: text(state.name), // {value: "Yoga"} -> "Yoga"
+  priceCents: whole(state.price, "cents"), // {cents: 10800} -> 10800
+}));
+
+// A command, judged by the state that comes back.
+const repriced = await client.apply({
+  verb: "Event.Reprice",
+  to: "yoga-1",
+  with: { price: { cents: 12000 } },
+  parse: (answer) => client.instancesOf(answer, "Event"),
+  confirm: (states) => states.find(([id]) => id === "yoga-1")?.[1].price?.cents === 12000,
+});
+```
+
+## Configuration
+
+`new HostClient(options)` (or `createClient(options)`) takes:
+
+| Option | Meaning |
+| --- | --- |
+| `domain` | The domain's name as its bluebook declares it. Falls back to the `HECKS_DOMAIN` environment variable. Required. |
+| `url` | Where the host listens. Trailing slashes are trimmed. Falls back to the `HECKS_SERVICE_URL` environment variable. Required. |
+| `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. |
+| `timeoutMs` | How long one request may take before it counts as unreachable. Defaults to `8000`. |
+| `fetch` | The `fetch` to send requests with, for tests or a custom agent. Defaults to the global `fetch`, looked up on each call. |
+
+The environment variables are read once, when the client is constructed. A
+missing domain or URL throws a `TypeError`.
+
+## API
+
+`HostClient`
+
+- `domain`, `url`: the resolved configuration.
+- `qualify(name)`: places a bare name in the client's domain (`"Event"` becomes `"Shop::Event"`). A name that already contains `::` is returned unchanged.
+- `read(): Promise<Answer>`: posts `{"read": true}` and returns everything the domain holds.
+- `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.
+- `apply<T>(command): Promise<T>`: dispatches `command.verb` with `command.with`, `command.to` and `command.role`, 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.
+- `instancesOf(answer, aggregate): [string, state][]`: the states of one aggregate, bare or qualified name.
+
+Standalone readers, importable without a client:
+
+- `instancesOf(answer, "Domain::Aggregate")`: the same lookup with the aggregate named in full.
+- `text(raw): string | null`: a string value object's text, `null` when absent or empty.
+- `whole(raw, key): number`: a numeric value object's number under `key` (`"value"`, `"cents"`), `0` when absent.
+- `optionalWhole(raw, key): number | null`: like `whole`, but `null` when the attribute was left unset.
+- `refusalOf(answer, verb): DomainRefusal`: the domain's own words for why a command changed nothing.
+
+Types and errors: `Answer` (`{ instances?, refusals?, error? }`), `Refusal`
+(`{ kind, error }`), `ClientOptions`, `Command<T>`, `DomainRefusal` (has
+`kind`), `DomainUnavailable`.
+
+The other exports, by the section that describes them: `createResilientFetch`,
+`ResilientFetchError` and the types `ResilientFetch`, `ResilientFetchConfig`,
+`ResilientRequest`; `PaymentsConnection`, `pastedKeys`, `savedMessage` and the
+types `PaymentConnectionState`, `PaymentMode`, `PaymentStatus`,
+`PaymentsConnectionOptions`, `PaymentsResult`, `FormFields`, `PastedKeys`;
+`verifyAccountToken`, `accountFromCookieHeader`, `cookieValue`,
+`accountToken`, `resolveAccountCookieName`, `DEFAULT_ACCOUNT_COOKIE` and the
+types `AccountClaims`, `Clock`, `CookieVerifyOptions`, `VerifyOptions`.
+
+### Why `apply` judges by state
+
+The host answers HTTP 200 whether or not the domain refused, and its
+`refusals` list can carry entries replayed from history. A command therefore
+counts as done when the state that comes back shows the change, never because
+the list is empty or non-empty.
+
+### Errors
+
+- `DomainUnavailable`: the host could not be reached, answered a non-2xx status, did not answer with JSON, or answered `{ "error": ... }`.
+- `DomainRefusal`: the domain understood a command and said no (`kind` is the failed rule, such as `GivenNotMet`, and `message` is the domain's wording).
+
+## Reading upstream JSON that may be down: `createResilientFetch`
+
+A site that renders from a service it does not own (a CMS, say) should not
+turn that service restarting into an error for every visitor.
+`createResilientFetch` reads JSON with two layers of protection: it retries
+network errors, timeouts and 502/503/504 with a short backoff, and when the
+upstream is still failing (a network error or any 5xx) it answers with the last
+good response for that exact URL, from this process's memory. A cold process
+has nothing remembered and still throws, so a broken deploy is never masked. A
+4xx is a real answer and is never retried or served stale.
+
+```ts
+import { createResilientFetch } from "@hecks/client";
+
+const upstream = createResilientFetch();
+const page = await upstream.json<Page>("http://cms.internal/api/pages/about", {
+  what: 'page "about"',
+  source: "the CMS",
+});
+```
+
+`createResilientFetch(config)` takes `fetch`, `sleep` and `warn` (all
+injectable, for tests), `retryDelaysMs` (default `[150, 500]`; its length is the
+number of retries), `attemptTimeoutMs` (default `10000`) and `maxRemembered`
+(default `200`, the least recently answered URL is dropped first). Each reader
+keeps its own memory; `clear()` forgets it.
+
+`json<T>(url, request): Promise<T | null>` takes:
+
+| Field | Meaning |
+| --- | --- |
+| `what`, `source` | Words for the error message: `Failed to fetch <what> from <source>: <failure>`, thrown as `ResilientFetchError` (its `failure` is the last attempt's reason). |
+| `allowStale` | Serve the remembered answer when the upstream is down. Defaults to `true`; turn it off where a stale answer would be acted on. |
+| `nullOn404` | Resolve to `null` on a 404 instead of throwing. |
+| `retryDelaysMs` | Replaces the configured delays for this call. |
+| `headers` | Extra request headers. |
+| `private` | The response is for one viewer (a draft read with their cookie): never remembered, and never answered from the remembered public copy of the same URL. |
+
+## Connecting a payment processor: `PaymentsConnection`
+
+A host that serves a domain with a `PaymentConnection` answers a JSON API under
+`/payments/connection` (`rust/host/src/payments.rs`). Every route acts as the
+person behind the host's account cookie, so each call forwards that person's own
+session and the host decides who may do what: an Owner connects and
+disconnects, only the platform operator turns real payments on or off.
+
+```ts
+import { PaymentsConnection, pastedKeys, savedMessage } from "@hecks/client";
+
+const payments = new PaymentsConnection({
+  url: "http://127.0.0.1:4322",
+  cookieName: "hecks_session", // the host's HECKS_SESSION_COOKIE; this is its default
+});
+
+// `session` is the value of the person's account cookie.
+const shown = await payments.show(session);
+if (shown.ok) console.log(shown.connection.status, shown.connection.can_manage);
+
+const pasted = pastedKeys(await request.formData()); // {keys} or {error}
+if ("keys" in pasted) {
+  const saved = await payments.saveKeys(session, pasted.keys);
+  if (saved.ok) console.log(savedMessage(saved.connection.display_name, saved.connection.mode));
+  else if (saved.status === 401) redirectToSignIn();
+  else console.error(saved.error);
+}
+```
+
+`new PaymentsConnection({ url, cookieName?, timeoutMs?, fetch? })`. Every method
+takes the session first and returns `Promise<PaymentsResult>`:
+
+| Method | Route | Who may |
+| --- | --- | --- |
+| `show(session)` | `GET /payments/connection` | an Owner or the operator |
+| `saveKeys(session, { secret_key, publishable_key })` | `POST .../direct` | an Owner |
+| `useOwnAccount(session, mode)` | `POST .../direct` with `{ mode }` | an Owner |
+| `disconnect(session)` | `POST .../disconnect` | an Owner |
+| `enable(session)`, `disable(session)` | `POST .../enable`, `.../disable` | the operator |
+
+`PaymentsResult` is `{ ok: true, status, connection }` or
+`{ ok: false, status, error }`. `connection` is a `PaymentConnectionState`
+(`status`, `processor`, `label`, `account_ref`, `mode`, `display_name`,
+`direct_modes`, `direct`, `can_save_keys`, `can_manage`, `can_enable`); it never
+carries a credential. `error` is the host's own sentence (`401` "not logged in",
+`403`, `409`, `422` for keys the host rejects) and is `undefined` when the host
+sent none, which is what an older host without these routes does by redirecting
+to an HTML login page. A host that cannot be reached throws `DomainUnavailable`.
+A `session` that is empty or not one cookie value throws `TypeError`.
+
+The host, not this package, decides whether a key is well formed: it checks the
+prefixes and that both keys are from the same mode, and answers `422` without
+quoting a key. `pastedKeys(form)` only trims the two fields (`secret_key`,
+`publishable_key`) of a `FormData` (or anything with `get(name)`) and says in
+plain words which one is missing; its errors never repeat a pasted value.
+`savedMessage(displayName, mode)` writes the confirmation sentence. Keys go to
+the host once and are never stored or logged.
+
+## Verifying the host's account token: `verifyAccountToken`
+
+After a sign-in the host mints a signed claim of who the person is and sets it
+as a cookie; `GET /accounts/sso-token` mints a 60-second copy as JSON so
+another service can start its own session for the same person. These functions
+are the receiving half. They are framework independent, do no I/O, and leave
+what to do with the person (find or create a user, start a session) to the
+caller.
+
+```ts
+import { accountFromCookieHeader, verifyAccountToken } from "@hecks/client";
+
+// A handoff token passed in a URL.
+const claims = verifyAccountToken(token, process.env.HOST_SESSION_SECRET!);
+if (!claims) return new Response("Invalid or expired token.", { status: 401 });
+signInAs(claims.email);
+
+// Or the cookie the host set, on a request to the same site.
+const who = accountFromCookieHeader(request.headers.get("cookie"), secret, { cookieName: "site_session" });
+```
+
+- `verifyAccountToken(token, secret, opts?): AccountClaims | null`, where `AccountClaims` is `{ email, exp }` (`exp` in Unix seconds). It returns `null`, and never throws, for a malformed token, a signature made with another secret, a missing email or expiry, or an expired token. `opts.now` is the clock (`() => milliseconds`, default `Date.now`). `opts.normalizeEmail` trims and lowercases the email and refuses one that is blank afterwards, for a receiver that stores addresses in that form; the default returns the email exactly as the host signed it. An empty `secret` throws `TypeError`.
+- `accountFromCookieHeader(header, secret, opts?)`: reads the account cookie out of a `Cookie` header (`opts.cookieName`, default `hecks_session`) and verifies it.
+- `cookieValue(header, name)`: one cookie's value in a `Cookie` header, or `null`.
+- `accountToken(secret, email, ttlSeconds, opts?)`: mints a token in the host's format, for tests and stand-in hosts.
+- `resolveAccountCookieName(configured?)` and `DEFAULT_ACCOUNT_COOKIE`: the cookie name the host uses for a value of `HECKS_SESSION_COOKIE` (unset or empty means `hecks_session`; an invalid name throws `TypeError`).
+
+The secret is the host's session secret; the receiver must hold the same value.
+The format is `rust/host/src/auth.rs`'s `account_token`:
+`<payload>.<signature>`, where the payload is the base64url (no padding) of
+the JSON `{"email": ..., "exp": <unix seconds>}` and the signature is the
+lowercase hex HMAC-SHA256 of the payload as sent. A token is expired once the
+current second is past `exp`. The tests pin a known-answer vector that the
+host's own unit test (`account_token_matches_the_known_answer_vector`) checks
+too.
+
+## Development
+
+```sh
+npm ci
+npm test              # builds, then runs the hermetic tests (no network)
+npm run typecheck
+```
+
+The hermetic tests run a protocol scenario against an in-process fake of the
+host. `npm run test:contract` runs the same scenario against a live host; see
+`test/contract.mjs`. The repository's `client-contract` workflow starts
+`rust/host` on the `spec/fixtures/rust_host/checkout_fixture` domain and runs
+it. To do the same locally, build that domain with `bin/project_wasm`, start
+`rust/host`'s `bootstrap` binary with `HECKS_SERVE_MODE=1`, `HECKS_DOMAIN`,
+`HECKS_WASM_PATH`, `HECKS_IR_PATH` and `DATABASE_URL` (a Postgres database), and
+run `HECKS_SERVICE_URL=http://127.0.0.1:<port> npm run test:contract`. Add
+`HECKS_CONTRACT_PAYMENTS=1` when that host also serves the payment-connection
+routes (it started with `HECKS_CHECKOUT_DOMAIN` naming its domain) to check the
+`PaymentsConnection` 401 as well; the workflow leaves it off.
+
+## Releasing
+
+The package version equals `Hecks::VERSION` and is released together with the
+gem; `spec/hecks_client_version_spec.rb` fails when they differ, and
+`bin/release_gem` refuses to push the gem while they do. When
+`lib/hecks/version.rb` changes, bump the package in the same change:
+
+```sh
+cd packages/hecks-client
+npm version <version> --no-git-tag-version   # also updates package-lock.json
+```
+
+`bin/release_gem` publishes the gem only. Publish the package from this
+directory once the gem is out (until the first publish, the tag install above is
+the way to consume it). npm is restricting tokens that bypass two-factor
+authentication, so publish from an account that can answer the prompt or set up
+trusted publishing, rather than relying on a long-lived token:
+
+```sh
+npm publish --access public   # `prepack` builds dist/ first
+```
+
+The steps as a whole are under "Releasing" in the repository's
+`CONTRIBUTING.md`.

package/dist/accountToken.d.ts

@@ -0,0 +1,56 @@
+/** The cookie name the account token travels in when a deploy names none. */
+export declare const DEFAULT_ACCOUNT_COOKIE = "hecks_session";
+/** The clock: the current time in milliseconds since the epoch, like `Date.now`. */
+export type Clock = () => number;
+/** What a verified token says. */
+export interface AccountClaims {
+    /** The person's email, as the host signed it unless `normalizeEmail` was set. */
+    email: string;
+    /** When the token stops being valid, in seconds since the epoch. */
+    exp: number;
+}
+/** Choices for `verifyAccountToken`. */
+export interface VerifyOptions {
+    /** The clock the expiry is judged by. Defaults to `Date.now`. */
+    now?: Clock;
+    /**
+     * Trim and lowercase the email, and refuse a token whose email is blank
+     * afterwards. For a receiver that stores addresses in that form: an address
+     * the host signed in mixed case must find the row stored for it.
+     */
+    normalizeEmail?: boolean;
+}
+/** Choices for `accountFromCookieHeader`. */
+export interface CookieVerifyOptions extends VerifyOptions {
+    /** The cookie the token is read from. Defaults to `hecks_session`. */
+    cookieName?: string;
+}
+/**
+ * Mints a token in the host's format, for tests and for a stand-in host.
+ * Expires `ttlSeconds` after `now` (by the injected clock).
+ */
+export declare function accountToken(secret: string, email: string, ttlSeconds: number, opts?: {
+    now?: Clock;
+}): string;
+/**
+ * Checks a token the host minted and returns who it names, or `null` when it
+ * is malformed, signed with another secret, carries no email or expiry, or
+ * has expired. Never throws for a bad token.
+ * @throws {TypeError} when `secret` is empty
+ */
+export declare function verifyAccountToken(token: string, secret: string, opts?: VerifyOptions): AccountClaims | null;
+/** The value of one cookie in a `Cookie` request header, or `null` when the header does not carry it. */
+export declare function cookieValue(header: string | null | undefined, name: string): string | null;
+/**
+ * Reads the account cookie out of a `Cookie` header and verifies it: who the
+ * request is from, or `null` when the cookie is absent or does not verify.
+ */
+export declare function accountFromCookieHeader(header: string | null | undefined, secret: string, opts?: CookieVerifyOptions): AccountClaims | null;
+/**
+ * The account cookie's name for a deploy that configures it (the host reads
+ * `HECKS_SESSION_COOKIE`): unset or empty means the default, anything else
+ * must be a valid cookie name because it is written into a `Set-Cookie`
+ * header.
+ * @throws {TypeError} when `configured` has characters other than letters, digits, `_`, `-` and `.`
+ */
+export declare function resolveAccountCookieName(configured?: string | null): string;

package/dist/accountToken.js

@@ -0,0 +1,112 @@
+// The host's account token, verified outside the host. After a sign-in the
+// host mints a short claim of who the person is, signs it, and sets it as a
+// cookie; `GET /accounts/sso-token` mints a shorter-lived copy as JSON for a
+// service that wants to start its own session for the same person. This is
+// the receiver's half: check the signature and the expiry, and read the
+// email. It is framework independent and does no I/O, so what a service then
+// does with the person (find or create a user, start a session) stays its own.
+//
+// The wire format is rust/host/src/auth.rs's `account_token`, byte for byte:
+//
+//   token     = <payload> "." <signature>
+//   payload   = base64url (no padding) of the UTF-8 JSON {"email": "...", "exp": <unix seconds>}
+//   signature = lowercase hex of HMAC-SHA256(secret, <payload as sent>)
+//
+// The host splits at the last ".", compares the signature as a plain string,
+// requires `exp` to be a non-negative integer, and treats the token as
+// expired once the current second is past `exp`. This module makes the same
+// decisions. The one deliberate difference is that the signature is compared
+// in constant time.
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** The cookie name the account token travels in when a deploy names none. */
+export const DEFAULT_ACCOUNT_COOKIE = "hecks_session";
+const encode = (text) => Buffer.from(text, "utf8").toString("base64url");
+const sign = (secret, payload) => createHmac("sha256", secret).update(payload).digest("hex");
+const nowSeconds = (now) => Math.floor(now() / 1000);
+function requireSecret(secret) {
+    // An empty key would verify tokens anyone can sign; a receiver with no
+    // secret configured is a misconfiguration, not an anonymous host.
+    if (typeof secret !== "string" || secret === "")
+        throw new TypeError("the account token secret must be a non-empty string");
+}
+/**
+ * Mints a token in the host's format, for tests and for a stand-in host.
+ * Expires `ttlSeconds` after `now` (by the injected clock).
+ */
+export function accountToken(secret, email, ttlSeconds, opts = {}) {
+    requireSecret(secret);
+    const payload = encode(JSON.stringify({ email, exp: nowSeconds(opts.now ?? Date.now) + ttlSeconds }));
+    return `${payload}.${sign(secret, payload)}`;
+}
+/**
+ * Checks a token the host minted and returns who it names, or `null` when it
+ * is malformed, signed with another secret, carries no email or expiry, or
+ * has expired. Never throws for a bad token.
+ * @throws {TypeError} when `secret` is empty
+ */
+export function verifyAccountToken(token, secret, opts = {}) {
+    requireSecret(secret);
+    if (typeof token !== "string")
+        return null;
+    const dot = token.lastIndexOf(".");
+    if (dot < 0)
+        return null;
+    const payload = token.slice(0, dot);
+    const signature = token.slice(dot + 1);
+    const expected = Buffer.from(sign(secret, payload));
+    const given = Buffer.from(signature);
+    if (expected.length !== given.length || !timingSafeEqual(expected, given))
+        return null;
+    let claims;
+    try {
+        claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!claims || typeof claims !== "object")
+        return null;
+    const { exp, email } = claims;
+    if (typeof exp !== "number" || !Number.isInteger(exp) || exp < 0)
+        return null;
+    if (nowSeconds(opts.now ?? Date.now) > exp)
+        return null;
+    if (typeof email !== "string")
+        return null;
+    if (!opts.normalizeEmail)
+        return { email, exp };
+    const normalized = email.toLowerCase().trim();
+    return normalized ? { email: normalized, exp } : null;
+}
+/** The value of one cookie in a `Cookie` request header, or `null` when the header does not carry it. */
+export function cookieValue(header, name) {
+    for (const part of (header ?? "").split(";")) {
+        const pair = part.trim();
+        if (pair.startsWith(`${name}=`))
+            return pair.slice(name.length + 1);
+    }
+    return null;
+}
+/**
+ * Reads the account cookie out of a `Cookie` header and verifies it: who the
+ * request is from, or `null` when the cookie is absent or does not verify.
+ */
+export function accountFromCookieHeader(header, secret, opts = {}) {
+    const token = cookieValue(header, opts.cookieName ?? DEFAULT_ACCOUNT_COOKIE);
+    return token ? verifyAccountToken(token, secret, opts) : null;
+}
+/**
+ * The account cookie's name for a deploy that configures it (the host reads
+ * `HECKS_SESSION_COOKIE`): unset or empty means the default, anything else
+ * must be a valid cookie name because it is written into a `Set-Cookie`
+ * header.
+ * @throws {TypeError} when `configured` has characters other than letters, digits, `_`, `-` and `.`
+ */
+export function resolveAccountCookieName(configured) {
+    if (!configured)
+        return DEFAULT_ACCOUNT_COOKIE;
+    if (/^[A-Za-z0-9_.-]+$/.test(configured))
+        return configured;
+    throw new TypeError(`${JSON.stringify(configured)} is not a valid cookie name (letters, digits, '_', '-' and '.' only)`);
+}
+//# sourceMappingURL=accountToken.js.map

package/dist/accountToken.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountToken.js","sourceRoot":"","sources":["../src/accountToken.ts"],"names":[],"mappings":"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"}

package/dist/answer.d.ts

@@ -0,0 +1,27 @@
+/** A refusal the host reported: the failed rule's kind and the domain's own words for it. */
+export interface Refusal {
+    kind: string;
+    error: string;
+}
+/**
+ * The body of every host answer: the state of the aggregates, keyed
+ * `Domain::Aggregate#id`, and the refusals the run reported. `error` is set
+ * when the host itself failed rather than the domain refusing.
+ */
+export interface Answer {
+    instances?: Record<string, Record<string, unknown>>;
+    refusals?: Refusal[];
+    error?: string;
+}
+/**
+ * The states of one aggregate in an answer, as `[id, state]` pairs. The
+ * aggregate is named in full (`Domain::Aggregate`), the way it appears in the
+ * answer's keys.
+ */
+export declare function instancesOf(answer: Answer, aggregate: string): [string, Record<string, unknown>][];
+/** A string value object's text, or null when it is absent or empty. */
+export declare const text: (raw: unknown) => string | null;
+/** A numeric value object's number under `key` ("value", "cents"), 0 when absent. */
+export declare const whole: (raw: unknown, key: string) => number;
+/** A numeric value object's number under `key`, or null when it is absent (an optional attribute left unset). */
+export declare const optionalWhole: (raw: unknown, key: string) => number | null;

package/dist/answer.js

@@ -0,0 +1,37 @@
+// The shapes a host answers with, and the readers that pull typed values out of
+// them. Nothing here performs I/O, so it can be imported anywhere, including
+// code that runs under a plain `node --test`.
+/**
+ * The states of one aggregate in an answer, as `[id, state]` pairs. The
+ * aggregate is named in full (`Domain::Aggregate`), the way it appears in the
+ * answer's keys.
+ */
+export function instancesOf(answer, aggregate) {
+    const prefix = `${aggregate}#`;
+    return Object.entries(answer.instances ?? {})
+        .filter(([key]) => key.startsWith(prefix))
+        .map(([key, state]) => [key.slice(prefix.length), state]);
+}
+// A value object arrives as {value: "x"} or {cents: 900}; a plain value passes
+// through, so a wrapped and a flattened answer read the same.
+function scalar(raw, key) {
+    if (raw && typeof raw === "object" && key in raw)
+        return raw[key];
+    return raw;
+}
+/** A string value object's text, or null when it is absent or empty. */
+export const text = (raw) => {
+    const v = scalar(raw, "value");
+    return typeof v === "string" && v !== "" ? v : null;
+};
+/** A numeric value object's number under `key` ("value", "cents"), 0 when absent. */
+export const whole = (raw, key) => {
+    const v = scalar(raw, key);
+    return typeof v === "number" ? v : Number(v ?? 0);
+};
+/** A numeric value object's number under `key`, or null when it is absent (an optional attribute left unset). */
+export const optionalWhole = (raw, key) => {
+    const v = scalar(raw, key);
+    return v === null || v === undefined || v === "" ? null : Number(v);
+};
+//# sourceMappingURL=answer.js.map

package/dist/answer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.js","sourceRoot":"","sources":["../src/answer.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,8CAA8C;AAmB9C;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,SAAiB;IAC3D,MAAM,MAAM,GAAG,GAAG,SAAS,GAAG,CAAC;IAC/B,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;SAC1C,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;SACzC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,+EAA+E;AAC/E,8DAA8D;AAC9D,SAAS,MAAM,CAAC,GAAY,EAAE,GAAW;IACvC,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,IAAI,GAAG;QAAE,OAAQ,GAA+B,CAAC,GAAG,CAAC,CAAC;IAC/F,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,GAAY,EAAiB,EAAE;IAClD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACtD,CAAC,CAAC;AAEF,qFAAqF;AACrF,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAE,GAAW,EAAU,EAAE;IACzD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC,CAAC;AAEF,iHAAiH;AACjH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAY,EAAE,GAAW,EAAiB,EAAE;IACxE,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC3B,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACtE,CAAC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,65 @@
+import type { Answer } from "./answer.js";
+/** What a `HostClient` needs to reach one domain. */
+export interface ClientOptions {
+    /** The domain's name as its bluebook declares it ("Shop"). Falls back to the `HECKS_DOMAIN` environment variable. */
+    domain?: string;
+    /** Where the host listens ("http://127.0.0.1:4322"). Falls back to the `HECKS_SERVICE_URL` environment variable. */
+    url?: string;
+    /**
+     * 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 this nor the call sets one, no role is sent and the host performs
+     * no role check.
+     */
+    role?: string;
+    /** How long one request may take before it counts as unreachable. Defaults to 8000. */
+    timeoutMs?: number;
+    /** The fetch to send requests with. Defaults to the global `fetch`, looked up on each call. */
+    fetch?: typeof fetch;
+}
+/**
+ * One command whose outcome is judged from the state that comes back.
+ * `parse` turns the answer into the caller's own shape and `confirm` says
+ * whether that shape shows the command took effect.
+ */
+export interface Command<T> {
+    /** The verb, `Aggregate.Verb` or fully qualified (`Domain::Aggregate.Verb`). */
+    verb: string;
+    with: Record<string, unknown>;
+    /** The target instance id; absent for a command that creates one. */
+    to?: string;
+    role?: string;
+    parse: (answer: Answer) => T;
+    confirm: (parsed: T) => boolean;
+}
+/** Talks to one domain on one host. */
+export declare class HostClient {
+    /** The domain's name, as configured. */
+    readonly domain: string;
+    /** The host's base URL, without a trailing slash. */
+    readonly url: string;
+    private readonly role;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    /** A name in full: one that already carries `::` is left alone, any other is placed in this client's domain. */
+    qualify(name: string): string;
+    /** The states of one aggregate in an answer, as `[id, state]` pairs. `aggregate` may be bare ("Event") or qualified. */
+    instancesOf(answer: Answer, aggregate: string): [string, Record<string, unknown>][];
+    /** Everything the domain holds, as the protocol answers it. */
+    read(): Promise<Answer>;
+    /**
+     * Sends one command and returns the raw answer. Callers judge the outcome
+     * from the state in it and turn a miss into a refusal with `refusalOf`.
+     */
+    dispatch(verb: string, args?: Record<string, unknown>, to?: string, role?: string): Promise<Answer>;
+    /**
+     * Runs one command and returns what `command.parse` reads from the answer.
+     * Throws `DomainRefusal` when that state does not show the change,
+     * carrying the domain's own words for why.
+     */
+    apply<T>(command: Command<T>): Promise<T>;
+    private post;
+}
+/** Shorthand for `new HostClient(options)`. */
+export declare const createClient: (options?: ClientOptions) => HostClient;