@axorum/client 0.0.0-stage → 1.0.0

package/dist/retry.js

@@ -0,0 +1,297 @@
+/**
+ * The transport retry policy: a mirror of `acton-service-client` 0.2's, which the Rust
+ * SDK uses, so both SDKs retry alike.
+ *
+ * Retries are **off** for a client's own calls unless it is built with a
+ * {@link RetryPolicy}. When one is, a request is sent again after a connection failure
+ * or a timeout, and after a `429`, `502` or `504` from something in front of the
+ * service (or a `423` that says when to come back), honouring `Retry-After`. A status
+ * the service documents as an answer (every `4xx` it sends, `421 not_primary`, `503
+ * commit_unavailable`) is not retried there: it reaches the caller after one send.
+ *
+ * `authorize` always retries, under its own policy ({@link AUTHORIZE_RETRY_POLICY}) and
+ * one deadline for the whole call ({@link AUTHORIZE_DEADLINE_MS}), and re-sends a `421`
+ * and a `503` too ({@link AUTHORIZE_RESENT_STATUSES}).
+ *
+ * Every function here is pure. `spec/fixtures/retry-v1.json` pins each one to the rows
+ * the Rust SDK pins `acton-service-client` itself to.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Three sends, 100 ms doubling, capped at 5 s, no jitter, no deadline:
+ * `acton-service-client`'s default.
+ *
+ * ```ts
+ * import { AxorumClient, DEFAULT_RETRY_POLICY } from "@axorum/client";
+ *
+ * const axorum = new AxorumClient({ baseUrl, retry: DEFAULT_RETRY_POLICY });
+ * ```
+ */
+export const DEFAULT_RETRY_POLICY = Object.freeze({
+    maxAttempts: 3,
+    baseDelayMs: 100,
+    maxDelayMs: 5_000,
+});
+/**
+ * The whole budget of one `authorize` call, in milliseconds: the window and pin reads,
+ * every submission, every attempt and every pause. The most `authorizeDeadlineMs`
+ * accepts, since the attestation minimum is sized for it.
+ */
+export const AUTHORIZE_DEADLINE_MS = 15_000;
+/**
+ * The response header on `GET /api/openapi.json` in which a clustered service advertises
+ * its commit wait (`[cluster] submit_timeout_ms`), in milliseconds: how long it holds a
+ * submission before answering `503 commit_unavailable`. A standalone service has no
+ * commit wait and sends none.
+ */
+export const SUBMIT_TIMEOUT_HEADER = "axorum-submit-timeout-ms";
+/**
+ * How much longer than the advertised commit wait an attempt waits, in milliseconds, so
+ * the service's own `503 commit_unavailable` arrives before the client gives up.
+ */
+export const COMMIT_WAIT_MARGIN_MS = 1_000;
+/**
+ * The most one attempt waits, in milliseconds, when the service advertises no commit
+ * wait: a standalone service, one older than the header, or an advertisement that could
+ * not be read. Also the bound on each of `authorize`'s reads.
+ */
+export const SUBMIT_ATTEMPT_FALLBACK_MS = 6_000;
+/**
+ * The most one submission attempt waits against a service whose advertised commit wait
+ * is `commitWaitMs`: that wait plus {@link COMMIT_WAIT_MARGIN_MS}, or
+ * {@link SUBMIT_ATTEMPT_FALLBACK_MS} when none is advertised. Pure.
+ *
+ * Under `authorize`'s deadline the attempt is further clamped to what is left of it. When
+ * that clamp cuts an attempt below the commit wait plus the margin, the service may still
+ * be deciding when the client stops waiting, so an attempt that ends that way is honestly
+ * `indeterminate`: re-drive the same payment to learn its answer.
+ *
+ * ```ts
+ * submitAttemptTimeout(undefined); // 6000
+ * submitAttemptTimeout(9_000); // 10000
+ * ```
+ */
+export function submitAttemptTimeout(commitWaitMs) {
+    return commitWaitMs === undefined ? SUBMIT_ATTEMPT_FALLBACK_MS : commitWaitMs + COMMIT_WAIT_MARGIN_MS;
+}
+/**
+ * The timeout a plain submission needs in place of the SDK's default `defaultMs` to
+ * outlast an advertised `commitWaitMs`: {@link submitAttemptTimeout} of it, when that is
+ * longer. Never shorter, and `undefined` when no wait is advertised. Pure.
+ */
+export function liftedSubmitTimeout(defaultMs, commitWaitMs) {
+    if (commitWaitMs === undefined) {
+        return undefined;
+    }
+    const needed = submitAttemptTimeout(commitWaitMs);
+    return needed > defaultMs ? needed : undefined;
+}
+/**
+ * The commit wait, in milliseconds, a {@link SUBMIT_TIMEOUT_HEADER} value states, or
+ * `undefined` when it states none: only 1 to 9 ASCII digits, not all zero, state a wait.
+ * Anything else (a sign, a space, an exponent, a tenth digit) is treated as no
+ * advertisement rather than guessed at, so this client reads the header as the Rust
+ * client does (`spec/fixtures/attempt-timeout-v1.json` pins both). Pure.
+ */
+export function advertisedCommitWait(value) {
+    if (value === null || value === undefined || !/^[0-9]{1,9}$/.test(value)) {
+        return undefined;
+    }
+    const millis = Number(value);
+    return millis === 0 ? undefined : millis;
+}
+/**
+ * The policy every `authorize` request is sent under: as many attempts as the deadline
+ * allows, full jitter floored at 100 ms, capped at 1.6 s. The deadline is not in it: it is
+ * an instant, set once per call and shared by all of its requests.
+ */
+export const AUTHORIZE_RETRY_POLICY = Object.freeze({
+    maxAttempts: 2 ** 32 - 1,
+    baseDelayMs: 100,
+    maxDelayMs: 1_600,
+    jitter: "full",
+});
+/**
+ * The status an `authorize` submission is re-sent on beyond the defaults: `421
+ * not_primary`, safe to re-send under the same transaction id. A `503` is not here: the
+ * transport re-sends on the status alone and reads no body, and only its body tells a
+ * `503 idempotency_unseeded`, which wrote nothing, from a `503 commit_unavailable`,
+ * which may have committed. So the call sends a `503` again itself, its body read.
+ */
+export const AUTHORIZE_RESENT_STATUSES = Object.freeze([421]);
+/** The largest double strictly below 1: the top of the clamped draw range. */
+const DRAW_MAX = 1 - Number.EPSILON / 2;
+/**
+ * The exponential ceiling for the pause after send number `attempt` (1-based):
+ * `baseDelayMs × 2^(attempt − 1)`, capped at `maxDelayMs`. An attempt below 1 is
+ * treated as 1; a huge one saturates to the cap. With no jitter it is the pause. Pure.
+ */
+export function backoffDelay(policy, attempt) {
+    const exponent = Math.min(Math.max(attempt - 1, 0), 63);
+    return Math.min(policy.baseDelayMs * 2 ** exponent, policy.maxDelayMs);
+}
+/**
+ * The pause after send number `attempt` (1-based), or `undefined` when it would reach the
+ * deadline. Pure.
+ *
+ * - `draw` is a uniform sample, clamped to `[0, 1)`; a `NaN` counts as 0. Ignored
+ *   without jitter.
+ * - `remainingMs` is the time left before the deadline, or `undefined` for none.
+ *
+ * With `ceiling = backoffDelay(policy, attempt)` and `floor = min(baseDelayMs, ceiling)`:
+ * no jitter pauses `ceiling`; full jitter pauses `floor + ⌊(ceiling − floor) × draw⌋`.
+ * Either is refused when `remainingMs` is set and the pause is at least it.
+ */
+export function pause(policy, attempt, draw, remainingMs) {
+    const ceiling = backoffDelay(policy, attempt);
+    let delay = ceiling;
+    if (policy.jitter === "full") {
+        const floor = Math.min(policy.baseDelayMs, ceiling);
+        delay = floor + spread(ceiling - floor, draw);
+    }
+    return fitsBefore(delay, remainingMs);
+}
+/** Whether another send is allowed after send number `attempt` (1-based). Pure. */
+export function shouldRetry(policy, attempt) {
+    return attempt < Math.max(policy.maxAttempts, 1);
+}
+/**
+ * The pause before the send after `attempt`, or `undefined` to stop: when `maxAttempts`
+ * is spent, or when the pause would reach the deadline. A server's `Retry-After`
+ * replaces the computed pause (unjittered, not capped by `maxDelayMs`) but is still
+ * refused if it would reach the deadline. Pure.
+ */
+export function nextPause(policy, attempt, draw, retryAfterMs, remainingMs) {
+    if (!shouldRetry(policy, attempt)) {
+        return undefined;
+    }
+    return retryAfterMs === undefined
+        ? pause(policy, attempt, draw, remainingMs)
+        : fitsBefore(retryAfterMs, remainingMs);
+}
+/**
+ * The timeout for one send, or `undefined` to leave the client's own. Pure.
+ *
+ * In order: the request's own, the client-wide attempt timeout, then (under a deadline
+ * only) the client's timeout, then the time remaining; under a deadline, whichever
+ * applies is clamped to what remains.
+ */
+export function attemptTimeout(requestMs, clientAttemptMs, clientMs, remainingMs) {
+    const configured = requestMs ?? clientAttemptMs;
+    if (remainingMs === undefined) {
+        return configured;
+    }
+    const own = configured ?? clientMs;
+    return own === undefined ? remainingMs : Math.min(own, remainingMs);
+}
+/**
+ * Whether a failing `status` asks for another send. A status listed in `retryOn` always
+ * does, checked first; otherwise an accepted (documented) status never does, and any
+ * other does when {@link isRetriableStatus} says so. Pure.
+ */
+export function wantsRetry(status, hasRetryAfter, accepted, retryOn) {
+    return retryOn.includes(status) || (!accepted && isRetriableStatus(status, hasRetryAfter));
+}
+/**
+ * Whether a failing status is worth another send: `429`, `502`, `503`, `504`, and `423`
+ * only when the server said when to come back. Pure.
+ */
+export function isRetriableStatus(status, hasRetryAfter) {
+    switch (status) {
+        case 429:
+        case 502:
+        case 503:
+        case 504:
+            return true;
+        case 423:
+            return hasRetryAfter;
+        default:
+            return false;
+    }
+}
+/** A reason's label, as the Rust SDK's `RetryReason::label` spells it: `"503"`, `"timeout"`. Pure. */
+export function retryLabel(reason) {
+    return reason.kind === "status" ? String(reason.status) : reason.kind;
+}
+/**
+ * The pause, if it ends strictly before the deadline `remainingMs` away, or `undefined`
+ * when it would reach it: `acton-service-client`'s rule, the boundary included. With no
+ * deadline every pause fits. Pure.
+ */
+export function fitsBefore(pauseMs, remainingMs) {
+    return remainingMs !== undefined && pauseMs >= remainingMs ? undefined : pauseMs;
+}
+/** The largest `Retry-After` the Rust SDK reads: an unsigned 64-bit second count. */
+const MAX_RETRY_AFTER_SECONDS = 2n ** 64n - 1n;
+/**
+ * A `Retry-After` header's delay in milliseconds, or `undefined`. Only the
+ * delta-seconds form is read, as Rust parses a `u64`: an optional `+`, then digits. An
+ * HTTP date, a fraction, a minus sign or an overflow is ignored. Pure.
+ */
+export function parseRetryAfter(header) {
+    if (header === null) {
+        return undefined;
+    }
+    const trimmed = header.trim();
+    if (!/^\+?\d+$/.test(trimmed)) {
+        return undefined;
+    }
+    const seconds = BigInt(trimmed.replace(/^\+/, ""));
+    return seconds > MAX_RETRY_AFTER_SECONDS ? undefined : Number(seconds) * 1_000;
+}
+/**
+ * Rejects a policy whose counts and delays are not non-negative whole numbers, whose
+ * deadline is not a positive whole number, or whose jitter is not one this SDK knows.
+ *
+ * @throws {RangeError} Naming the bad field.
+ */
+export function checkRetryPolicy(policy) {
+    for (const [name, value] of [
+        ["maxAttempts", policy.maxAttempts],
+        ["baseDelayMs", policy.baseDelayMs],
+        ["maxDelayMs", policy.maxDelayMs],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new RangeError(`${name} must be a non-negative whole number, not ${value}`);
+        }
+    }
+    if (policy.deadlineMs !== undefined &&
+        (!Number.isSafeInteger(policy.deadlineMs) || policy.deadlineMs <= 0)) {
+        throw new RangeError(`deadlineMs must be a positive whole number, not ${policy.deadlineMs}`);
+    }
+    if (policy.jitter !== undefined && policy.jitter !== "none" && policy.jitter !== "full") {
+        throw new RangeError(`jitter must be "none" or "full", not ${String(policy.jitter)}`);
+    }
+}
+/** Error codes Node's `fetch` (undici) and its resolver give a connection that never opened. */
+const CONNECT_FAILURE_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+/**
+ * Whether a `fetch` rejection is a connection that never opened: the counterpart of
+ * reqwest's `is_connect`, which is what `acton-service-client` retries (with timeouts).
+ * A connection that broke after the request went out is not one. Pure.
+ */
+export function isConnectFailure(error) {
+    let current = error;
+    for (let depth = 0; depth < 4 && current instanceof Error; depth += 1) {
+        const code = current.code;
+        if (typeof code === "string" && CONNECT_FAILURE_CODES.has(code)) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/** `⌊span × draw⌋` with `draw` clamped to `[0, 1)` (NaN as 0), never above `span`. */
+function spread(span, draw) {
+    const clamped = Number.isNaN(draw) ? 0 : Math.min(Math.max(draw, 0), DRAW_MAX);
+    return Math.min(Math.floor(span * clamped), span);
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAiCH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAgB,MAAM,CAAC,MAAM,CAAC;IAC7D,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,KAAK;CAClB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,0BAA0B,CAAC;AAEhE;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAE3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAgC;IACnE,OAAO,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,YAAY,GAAG,qBAAqB,CAAC;AACxG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,YAAgC;IACrF,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC;IAClD,OAAO,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAgC;IACnE,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAgB,MAAM,CAAC,MAAM,CAAC;IAC/D,WAAW,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;IACxB,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,MAAM;CACf,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAEjF,8EAA8E;AAC9E,MAAM,QAAQ,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAmB,EAAE,OAAe;IAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,GAAG,CAAC,IAAI,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CACnB,MAAmB,EACnB,OAAe,EACf,IAAY,EACZ,WAA+B;IAE/B,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,KAAK,GAAG,OAAO,CAAC;IACpB,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACpD,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;AACxC,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,MAAmB,EAAE,OAAe;IAC9D,OAAO,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,MAAmB,EACnB,OAAe,EACf,IAAY,EACZ,YAAgC,EAChC,WAA+B;IAE/B,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,YAAY,KAAK,SAAS;QAC/B,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC;QAC3C,CAAC,CAAC,UAAU,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,SAA6B,EAC7B,eAAmC,EACnC,QAA4B,EAC5B,WAA+B;IAE/B,MAAM,UAAU,GAAG,SAAS,IAAI,eAAe,CAAC;IAChD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,MAAM,GAAG,GAAG,UAAU,IAAI,QAAQ,CAAC;IACnC,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,aAAsB,EACtB,QAAiB,EACjB,OAA0B;IAE1B,OAAO,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,IAAI,iBAAiB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,aAAsB;IACtE,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,GAAG,CAAC;QACT,KAAK,GAAG,CAAC;QACT,KAAK,GAAG,CAAC;QACT,KAAK,GAAG;YACN,OAAO,IAAI,CAAC;QACd,KAAK,GAAG;YACN,OAAO,aAAa,CAAC;QACvB;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAWD,sGAAsG;AACtG,MAAM,UAAU,UAAU,CAAC,MAAmB;IAC5C,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,WAA+B;IACzE,OAAO,WAAW,KAAK,SAAS,IAAI,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACnF,CAAC;AAED,qFAAqF;AACrF,MAAM,uBAAuB,GAAG,EAAE,IAAI,GAAG,GAAG,EAAE,CAAC;AAE/C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACnD,OAAO,OAAO,GAAG,uBAAuB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;AACjF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAmB;IAClD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI;QAC1B,CAAC,aAAa,EAAE,MAAM,CAAC,WAAW,CAAC;QACnC,CAAC,aAAa,EAAE,MAAM,CAAC,WAAW,CAAC;QACnC,CAAC,YAAY,EAAE,MAAM,CAAC,UAAU,CAAC;KACzB,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,6CAA6C,KAAK,EAAE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IACD,IACE,MAAM,CAAC,UAAU,KAAK,SAAS;QAC/B,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC,EACpE,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,mDAAmD,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACxF,MAAM,IAAI,UAAU,CAAC,wCAAwC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED,gGAAgG;AAChG,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,cAAc;IACd,WAAW;IACX,WAAW;IACX,cAAc;IACd,aAAa;IACb,yBAAyB;CAC1B,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,IAAI,OAAO,YAAY,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,GAAI,OAA8B,CAAC,IAAI,CAAC;QAClD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAChE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sFAAsF;AACtF,SAAS,MAAM,CAAC,IAAY,EAAE,IAAY;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC/E,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;AACpD,CAAC"}

package/dist/typeid.d.ts

@@ -0,0 +1,64 @@
+/**
+ * TypeID encoding — how Axorum spells its identifiers on the wire.
+ *
+ * Every Axorum id is a {@link https://github.com/jetify-com/typeid | TypeID}: a fixed
+ * prefix, an underscore, and the 128 bits of a UUID in Crockford base32 —
+ * `txn_7w5b4trnc7b2ja027jyyb64395`. The client needs this for exactly one reason:
+ * it mints the transaction id, which is the substrate's idempotency key, and it has
+ * to spell it the way the ledger reads it.
+ *
+ * @packageDocumentation
+ */
+/** The TypeID prefix for a transaction id. */
+export declare const TRANSACTION_PREFIX = "txn";
+/**
+ * Encodes the 16 bytes of a UUID as a 26-character Crockford base32 TypeID suffix.
+ *
+ * A pure function of its input: the same UUID always spells the same suffix, which
+ * is what makes an id reconstructible rather than merely unique.
+ *
+ * @param uuid - A canonical UUID string, e.g. `01890a5d-ac96-774b-bcce-b302099a8057`.
+ * @returns The 26-character suffix, e.g. `01h455vb4pex5vsknk084sn02q`.
+ * @throws {TypeError} If `uuid` is not 32 hex digits with the usual dashes.
+ */
+export declare function encodeSuffix(uuid: string): string;
+/**
+ * The 128 bits a 26-character TypeID suffix encodes, or `undefined` when it is not one.
+ * The inverse of {@link encodeSuffix}. Pure.
+ *
+ * ```ts
+ * decodeSuffix(encodeSuffix("01890a5d-ac96-774b-bcce-b302099a8057")); // 0x01890a5d…n
+ * ```
+ */
+export declare function decodeSuffix(suffix: string): bigint | undefined;
+/**
+ * Mints a fresh transaction id: a UUID v7 minted at `nowMs`, spelled as a `txn_…`
+ * TypeID. The id carries its own mint time ({@link v7MintedAtMs}), which every envelope
+ * pinned from it sends as `minted_at_ms`.
+ *
+ * **Mint it once.** The transaction id is the substrate's idempotency key — every
+ * retry of a submission must carry the *same* id, so that an attempt which in fact
+ * landed replays its stored outcome instead of posting a second time. This is why
+ * {@link AxorumClient.submitPinned} mints the id before its first attempt and never
+ * again, and why you should hold on to the id you minted rather than mint another.
+ *
+ * @param nowMs - The minting time; `Date.now()` when omitted.
+ * @returns A new transaction id, e.g. `txn_01m3250v3ve008000000000000`.
+ */
+export declare function newTransactionId(nowMs?: number): string;
+/**
+ * RFC 9562 UUID version 7 from a millisecond timestamp and 16 random bytes (of which
+ * the first six are replaced by the timestamp). Pure.
+ */
+export declare function uuidV7(unixMs: number, random: Uint8Array): string;
+/**
+ * The mint time a UUID v7 transaction id carries: its 48-bit Unix millisecond
+ * timestamp. `undefined` for any other version or a malformed id. Pure; the same rule
+ * as the Rust SDK's.
+ *
+ * ```ts
+ * v7MintedAtMs(`txn_${encodeSuffix(uuidV7(1_790_000_000_000, new Uint8Array(16)))}`); // 1790000000000
+ * ```
+ */
+export declare function v7MintedAtMs(transaction: string): number | undefined;
+//# sourceMappingURL=typeid.d.ts.map

package/dist/typeid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeid.d.ts","sourceRoot":"","sources":["../src/typeid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBjD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,MAAmB,GAAG,MAAM,CAEnE;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAWjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUpE"}

package/dist/typeid.js

@@ -0,0 +1,119 @@
+/**
+ * TypeID encoding — how Axorum spells its identifiers on the wire.
+ *
+ * Every Axorum id is a {@link https://github.com/jetify-com/typeid | TypeID}: a fixed
+ * prefix, an underscore, and the 128 bits of a UUID in Crockford base32 —
+ * `txn_7w5b4trnc7b2ja027jyyb64395`. The client needs this for exactly one reason:
+ * it mints the transaction id, which is the substrate's idempotency key, and it has
+ * to spell it the way the ledger reads it.
+ *
+ * @packageDocumentation
+ */
+/** Crockford's base32 alphabet, lowercase: no `i`, `l`, `o`, or `u`. */
+const ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+/** The number of base32 characters 128 bits encodes to (26 × 5 = 130 ≥ 128). */
+const SUFFIX_LENGTH = 26;
+/** The TypeID prefix for a transaction id. */
+export const TRANSACTION_PREFIX = "txn";
+/**
+ * Encodes the 16 bytes of a UUID as a 26-character Crockford base32 TypeID suffix.
+ *
+ * A pure function of its input: the same UUID always spells the same suffix, which
+ * is what makes an id reconstructible rather than merely unique.
+ *
+ * @param uuid - A canonical UUID string, e.g. `01890a5d-ac96-774b-bcce-b302099a8057`.
+ * @returns The 26-character suffix, e.g. `01h455vb4pex5vsknk084sn02q`.
+ * @throws {TypeError} If `uuid` is not 32 hex digits with the usual dashes.
+ */
+export function encodeSuffix(uuid) {
+    const hex = uuid.replaceAll("-", "").toLowerCase();
+    if (hex.length !== 32 || !/^[0-9a-f]{32}$/.test(hex)) {
+        throw new TypeError(`'${uuid}' is not a UUID`);
+    }
+    // 128 bits as one integer, then 26 five-bit digits, most significant first. The
+    // two bits of headroom land in the leading digit, which is why a TypeID suffix
+    // always starts in `0`–`7`.
+    let value = BigInt(`0x${hex}`);
+    const digits = new Array(SUFFIX_LENGTH);
+    for (let index = SUFFIX_LENGTH - 1; index >= 0; index -= 1) {
+        digits[index] = ALPHABET[Number(value & 31n)];
+        value >>= 5n;
+    }
+    return digits.join("");
+}
+/**
+ * The 128 bits a 26-character TypeID suffix encodes, or `undefined` when it is not one.
+ * The inverse of {@link encodeSuffix}. Pure.
+ *
+ * ```ts
+ * decodeSuffix(encodeSuffix("01890a5d-ac96-774b-bcce-b302099a8057")); // 0x01890a5d…n
+ * ```
+ */
+export function decodeSuffix(suffix) {
+    if (suffix.length !== SUFFIX_LENGTH || suffix[0] === undefined || suffix[0] > "7") {
+        return undefined;
+    }
+    let value = 0n;
+    for (const digit of suffix) {
+        const index = ALPHABET.indexOf(digit);
+        if (index < 0) {
+            return undefined;
+        }
+        value = (value << 5n) | BigInt(index);
+    }
+    return value;
+}
+/**
+ * Mints a fresh transaction id: a UUID v7 minted at `nowMs`, spelled as a `txn_…`
+ * TypeID. The id carries its own mint time ({@link v7MintedAtMs}), which every envelope
+ * pinned from it sends as `minted_at_ms`.
+ *
+ * **Mint it once.** The transaction id is the substrate's idempotency key — every
+ * retry of a submission must carry the *same* id, so that an attempt which in fact
+ * landed replays its stored outcome instead of posting a second time. This is why
+ * {@link AxorumClient.submitPinned} mints the id before its first attempt and never
+ * again, and why you should hold on to the id you minted rather than mint another.
+ *
+ * @param nowMs - The minting time; `Date.now()` when omitted.
+ * @returns A new transaction id, e.g. `txn_01m3250v3ve008000000000000`.
+ */
+export function newTransactionId(nowMs = Date.now()) {
+    return `${TRANSACTION_PREFIX}_${encodeSuffix(uuidV7(nowMs, crypto.getRandomValues(new Uint8Array(16))))}`;
+}
+/**
+ * RFC 9562 UUID version 7 from a millisecond timestamp and 16 random bytes (of which
+ * the first six are replaced by the timestamp). Pure.
+ */
+export function uuidV7(unixMs, random) {
+    const bytes = Uint8Array.from(random.subarray(0, 16));
+    let time = BigInt(unixMs);
+    for (let index = 5; index >= 0; index -= 1) {
+        bytes[index] = Number(time & 0xffn);
+        time >>= 8n;
+    }
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * The mint time a UUID v7 transaction id carries: its 48-bit Unix millisecond
+ * timestamp. `undefined` for any other version or a malformed id. Pure; the same rule
+ * as the Rust SDK's.
+ *
+ * ```ts
+ * v7MintedAtMs(`txn_${encodeSuffix(uuidV7(1_790_000_000_000, new Uint8Array(16)))}`); // 1790000000000
+ * ```
+ */
+export function v7MintedAtMs(transaction) {
+    const prefix = `${TRANSACTION_PREFIX}_`;
+    if (!transaction.startsWith(prefix)) {
+        return undefined;
+    }
+    const bits = decodeSuffix(transaction.slice(prefix.length));
+    if (bits === undefined || ((bits >> 76n) & 0xfn) !== 7n) {
+        return undefined;
+    }
+    return Number(bits >> 80n);
+}
+//# sourceMappingURL=typeid.js.map

package/dist/typeid.js.map

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