@heyanon-arp/sdk 0.0.2 → 0.0.3

package/dist/index.js

@@ -645,6 +645,43 @@ function expiresAt(ttlSeconds, now = /* @__PURE__ */ new Date()) {
   return rfc3339(new Date(now.getTime() + ttlSeconds * 1e3));
 }
 
+// src/utils/poll.ts
+async function pollUntil(opts) {
+  const intervalMs = Math.max(100, opts.intervalMs ?? 3e3);
+  const timeoutMs = Math.max(intervalMs, opts.timeoutMs ?? 3e5);
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  if (opts.abortSignal?.aborted) return { kind: "aborted", last: void 0 };
+  for (; ; ) {
+    try {
+      last = await opts.fetch();
+      if (opts.predicate(last)) return { kind: "matched", value: last };
+    } catch (err) {
+      if (!opts.swallowFetchErrors) throw err;
+      opts.onFetchError?.(err);
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return { kind: "timeout", last };
+    const sleepMs = Math.min(intervalMs, remaining);
+    await sleepWithAbort(sleepMs, opts.abortSignal);
+    if (opts.abortSignal?.aborted) return { kind: "aborted", last };
+  }
+}
+function sleepWithAbort(ms, signal) {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 // src/types/body.ts
 var DECLINE_REASONS = ["missing_brief", "rate_too_low", "out_of_scope", "policy", "expired_proposal", "capacity", "unspecified", "other"];
 function isDeclineReason(v) {
@@ -830,6 +867,7 @@ exports.isDeclineReason = isDeclineReason;
 exports.isValidDid = isValidDid;
 exports.parseCaip19SolanaAssetId = parseCaip19SolanaAssetId;
 exports.parseDid = parseDid;
+exports.pollUntil = pollUntil;
 exports.resolveAsset = resolveAsset;
 exports.rfc3339 = rfc3339;
 exports.scryptPasswordProofSign = scryptPasswordProofSign;

package/dist/index.mjs

@@ -620,6 +620,43 @@ function expiresAt(ttlSeconds, now = /* @__PURE__ */ new Date()) {
   return rfc3339(new Date(now.getTime() + ttlSeconds * 1e3));
 }
 
+// src/utils/poll.ts
+async function pollUntil(opts) {
+  const intervalMs = Math.max(100, opts.intervalMs ?? 3e3);
+  const timeoutMs = Math.max(intervalMs, opts.timeoutMs ?? 3e5);
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  if (opts.abortSignal?.aborted) return { kind: "aborted", last: void 0 };
+  for (; ; ) {
+    try {
+      last = await opts.fetch();
+      if (opts.predicate(last)) return { kind: "matched", value: last };
+    } catch (err) {
+      if (!opts.swallowFetchErrors) throw err;
+      opts.onFetchError?.(err);
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return { kind: "timeout", last };
+    const sleepMs = Math.min(intervalMs, remaining);
+    await sleepWithAbort(sleepMs, opts.abortSignal);
+    if (opts.abortSignal?.aborted) return { kind: "aborted", last };
+  }
+}
+function sleepWithAbort(ms, signal) {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 // src/types/body.ts
 var DECLINE_REASONS = ["missing_brief", "rate_too_low", "out_of_scope", "policy", "expired_proposal", "capacity", "unspecified", "other"];
 function isDeclineReason(v) {
@@ -758,4 +795,4 @@ function computeCreateLockDiscriminator() {
   return h.slice(0, 8);
 }
 
-export { CAIP19_REGEX, COSIGNATURE_PURPOSES, CREATE_LOCK_DISCRIMINATOR, DECLINE_REASONS, PROTECTED_PURPOSES, PURPOSE_PARTIAL_RELEASE_STRING, PURPOSE_REFUND_STRING, PURPOSE_RELEASE_STRING, Purpose, REFUND_REASON_BYTES, SCRYPT_PARAMS, SETTLEMENT_PURPOSES, SLIP44_SOLANA, SOLANA_CLUSTER_IDS, SPL_TOKEN_PROGRAM_ID_BASE58, TOKEN_2022_PROGRAM_ID_BASE58, USDC_MINTS, WELL_KNOWN_ASSETS, WELL_KNOWN_ASSET_KEYS, base58btcDecode, base58btcEncode, buildCreateLockIxData, buildPartialReleaseDigest, buildRefundDigest, buildReleaseDigest, buildWebhookSignatureHeader, bytes16ToDelegationId, canonicalBytes, canonicalJson, canonicalSha256Hex, computeCreateLockDiscriminator, delegationIdToBytes16, deriveConditionHash, deriveLockId, deriveScryptKey, detectTokenProgramFromOwner, detectTokenProgramFromOwnerBytes, expiresAt, findFirstChainDivergence, formatDid, generateKeyPair, getPublicKey2 as getPublicKey, isAssetIdentifier, isDeclineReason, isValidDid, parseCaip19SolanaAssetId, parseDid, resolveAsset, rfc3339, scryptPasswordProofSign, scryptPasswordProofVerify, senderNonce, serverEventHash, sign2 as sign, signChallenge, signCosignature, signEnvelope, signKeyLinkAttestation, signKeyRotationAttestation, signedMessageHash, uuidV4, verify2 as verify, verifyChallenge, verifyCosignature, verifyEnvelope, verifyKeyLinkAttestation, verifyKeyRotationAttestation, verifyWebhookSignatureHeader };
+export { CAIP19_REGEX, COSIGNATURE_PURPOSES, CREATE_LOCK_DISCRIMINATOR, DECLINE_REASONS, PROTECTED_PURPOSES, PURPOSE_PARTIAL_RELEASE_STRING, PURPOSE_REFUND_STRING, PURPOSE_RELEASE_STRING, Purpose, REFUND_REASON_BYTES, SCRYPT_PARAMS, SETTLEMENT_PURPOSES, SLIP44_SOLANA, SOLANA_CLUSTER_IDS, SPL_TOKEN_PROGRAM_ID_BASE58, TOKEN_2022_PROGRAM_ID_BASE58, USDC_MINTS, WELL_KNOWN_ASSETS, WELL_KNOWN_ASSET_KEYS, base58btcDecode, base58btcEncode, buildCreateLockIxData, buildPartialReleaseDigest, buildRefundDigest, buildReleaseDigest, buildWebhookSignatureHeader, bytes16ToDelegationId, canonicalBytes, canonicalJson, canonicalSha256Hex, computeCreateLockDiscriminator, delegationIdToBytes16, deriveConditionHash, deriveLockId, deriveScryptKey, detectTokenProgramFromOwner, detectTokenProgramFromOwnerBytes, expiresAt, findFirstChainDivergence, formatDid, generateKeyPair, getPublicKey2 as getPublicKey, isAssetIdentifier, isDeclineReason, isValidDid, parseCaip19SolanaAssetId, parseDid, pollUntil, resolveAsset, rfc3339, scryptPasswordProofSign, scryptPasswordProofVerify, senderNonce, serverEventHash, sign2 as sign, signChallenge, signCosignature, signEnvelope, signKeyLinkAttestation, signKeyRotationAttestation, signedMessageHash, uuidV4, verify2 as verify, verifyChallenge, verifyCosignature, verifyEnvelope, verifyKeyLinkAttestation, verifyKeyRotationAttestation, verifyWebhookSignatureHeader };

package/dist/types/body.d.ts

@@ -238,11 +238,117 @@ export interface DisputeContent {
     evidence_refs?: string[];
     response_text?: string;
 }
+/**
+ * `settlement_signature` — payee's settlement-key signature on a
+ * release-digest, sent as a STAND-ALONE envelope AFTER the matching
+ * receipt-propose envelope is committed.
+ *
+ * Why a separate envelope (and not an attachment on receipt-propose)?
+ * The release digest (`buildReleaseDigest` / `buildPartialReleaseDigest`
+ * in `packages/sdk/src/settlement/settlement.ts`) takes `receiptEventHash`
+ * as one of its inputs. `receipt_event_hash` is the SERVER-ASSIGNED
+ * hash of the receipt envelope — it is computed only AFTER server-side
+ * validation completes (it includes server-assigned `prev_server_event_hash`
+ * + `server_timestamp` in its canonical input). The payee CANNOT
+ * compute the digest at receipt-propose time because the digest input
+ * does not yet exist. So the wire flow is necessarily two envelopes:
+ *
+ *   1. Payee sends `receipt` (propose) — server commits + returns
+ *      `IngestResultDto.serverEventHash`.
+ *   2. Payee reads `serverEventHash`, computes the release digest,
+ *      signs it, and sends THIS `settlement_signature` envelope.
+ *   3. Buyer reads the `settlement_signature` envelope from inbox SSE
+ *      (sender-recipient routing is standard), then assembles the
+ *      `attachments.settlement_signatures` block on the cosign envelope.
+ *
+ * This body type carries ONLY the payee side. The payer's settlement
+ * sig still lands on the cosign envelope's `attachments` block — that
+ * stays unchanged. The server's handler for `settlement_signature`
+ * also performs Ed25519 verification of the payee sig against the
+ * reconstructed digest as defence-in-depth: a bad sig fails loudly on
+ * the worker side instead of stranding the buyer's cosign later.
+ *
+ * Refund flow is NOT served by this body type — `buildRefundDigest`
+ * does NOT bind to `receipt_event_hash` (it binds to lock-derived
+ * fields only), so refund signatures can be computed independent of
+ * any envelope timing and ride their own dedicated paths. The
+ * `purpose` field below is intentionally narrowed to RELEASE +
+ * PARTIAL_RELEASE for the same reason — REFUND-v1 sigs do not belong
+ * on this envelope.
+ */
+export interface SettlementSignatureBody extends Body<SettlementSignatureContent> {
+    type: 'settlement_signature';
+}
+export interface SettlementSignatureContent {
+    /** The delegation whose receipt is being settlement-signed. */
+    delegation_id: string;
+    /**
+     * Server-assigned hash of the receipt-propose envelope this signature
+     * settles. Must match `Receipt.receiptEventHash` server-side; that is
+     * the value the server's cosign-validator feeds into the digest
+     * reconstruction as `receiptEventHash`.
+     */
+    receipt_event_hash: Sha256Hex;
+    /**
+     * Which digest the `sig` was computed over. Narrowed to RELEASE +
+     * PARTIAL_RELEASE: REFUND-v1 sigs ride other paths because the
+     * refund digest is independent of `receipt_event_hash` and never
+     * needs this envelope as a transport.
+     */
+    purpose: 'ARP-SOLANA-RELEASE-v1.5' | 'ARP-SOLANA-PARTIAL-RELEASE-v1.5';
+    /**
+     * Payee's settlement-key public key (base58, 32 bytes raw). The
+     * server cross-checks this against the registered settlement key on
+     * the payee's DID document before re-verifying the sig — a sig
+     * signed by an unregistered key is rejected even if it
+     * mathematically verifies.
+     */
+    payee_settlement_pubkey: string;
+    /**
+     * Ed25519 sig over the reconstructed release/partial-release digest,
+     * **raw base64 — NO `ed25519:` prefix.** Wire format intentionally
+     * mismatches the SDK's prefixed `Ed25519Sig` type because the buyer
+     * forwards this exact string verbatim into
+     * `attachments.settlement_signatures.payee.sig` at cosign time, and
+     * the server's `ReceiptCosignValidatorService.parseBase64Sig`
+     * (`apps/arp-server/src/escrow/services/receipt-cosign-validator.service.ts:557-565`)
+     * `Buffer.from(input, 'base64')` directly — no prefix stripping.
+     * Aligns with the CLI's `--payer-settlement-sig <base64>` /
+     * `--payee-settlement-sig <base64>` flags that consumers already
+     * wire to (see `packages/cli/src/commands/receipt.ts:670-673`).
+     *
+     * Server re-builds the same digest from lock + receipt + envelope
+     * content and verifies this sig as defence-in-depth at handler time
+     * — a malformed or wrong-digest sig is rejected pre-projection so
+     * the bad receipt sig never reaches the buyer's cosign attempt.
+     */
+    sig: string;
+    /**
+     * Unix seconds — the `expires_at` value the payee bound into the
+     * digest. Server re-uses it when reconstructing the digest and
+     * cross-checks against `expires_at > now` + `expires_at <=
+     * lock.expiry - DISPUTE_BUFFER_SECONDS` (ADR-12 §4). The payer
+     * echoes the SAME value on the cosign envelope's settlement_signatures
+     * block so both sides sign the same bytes.
+     */
+    expires_at: number;
+    /**
+     * Base-unit decimal-integer string — required when `purpose ===
+     * 'ARP-SOLANA-PARTIAL-RELEASE-v1.5'`, omitted (or undefined) for
+     * full RELEASE. The server cross-checks it against
+     * `receipt.usage.computed_amount` for usage_based contracts before
+     * verifying the digest (same invariant
+     * `ESC_USAGE_COMPUTED_AMOUNT_MISMATCH` already guards on the
+     * propose-time receipt body).
+     */
+    payee_amount?: string;
+    [extra: string]: unknown;
+}
 /**
  * Union over every standard body type. Consumers can narrow on
  * `body.type` via discriminated dispatch.
  */
-export type AnyBody = HandshakeBody | HandshakeResponseBody | ContractBody | DelegationBody | WorkRequestBody | WorkResponseBody | ReceiptBody | MemoryDeltaBody | DisputeBody;
+export type AnyBody = HandshakeBody | HandshakeResponseBody | ContractBody | DelegationBody | WorkRequestBody | WorkResponseBody | ReceiptBody | MemoryDeltaBody | DisputeBody | SettlementSignatureBody;
 /** Receipt co-signature payload — what gets `payload_hash`'d in `attachments.co_signature`. */
 export interface ReceiptCosignPayload {
     purpose: 'ARP-RECEIPT-v1';

package/dist/types/envelope.d.ts

@@ -97,7 +97,22 @@ export interface SettlementSignatures {
 }
 export interface SettlementParty {
     settlement_pubkey: string;
-    sig: Ed25519Sig;
+    /**
+     * Ed25519 signature, **raw base64 — NO `ed25519:` prefix.** Wire
+     * format intentionally mismatches the prefixed `Ed25519Sig` type
+     * because this block is consumed by the Solana Ed25519Program at
+     * release-tx-builder time, where prefixed strings would break. The
+     * server's `ReceiptCosignValidatorService.parseBase64Sig`
+     * (`apps/arp-server/src/escrow/services/receipt-cosign-validator.service.ts:557-565`)
+     * decodes 64 bytes directly via `Buffer.from(input, 'base64')`
+     * without any prefix stripping. The CLI's
+     * `heyarp wallet sign-settlement-release` already emits raw base64
+     * (`packages/cli/src/commands/wallet.ts:1718-1722`). Matches the
+     * raw-base64 shape of `SettlementSignatureContent.sig` — divergent
+     * types here would leave buyers unable to copy the value verbatim
+     * into the cosign attachment.
+     */
+    sig: string;
 }
 /** Top-level envelope as it appears on the wire. */
 export interface Envelope<TBody extends Body = Body> {

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 export type { Sha256Hex, Ed25519Sig, Did, ProtectedBlock, Body, Attachments, CoSignature, SettlementSignatures, SettlementParty, EscrowLockAttachment, Envelope, PersistedEvent, } from './envelope';
-export type { HandshakeBody, HandshakeContent, HandshakeResponseBody, HandshakeResponseContent, ContractBody, ContractContent, DelegationBody, DelegationContent, WorkRequestBody, WorkRequestContent, WorkResponseBody, WorkResponseContent, ReceiptBody, ReceiptContent, MemoryDeltaBody, MemoryDeltaContent, DisputeBody, DisputeContent, AnyBody, ReceiptCosignPayload, DisputeResponseCosignPayload, CosignPayload, DeclineReason, AssetIdentifier, } from './body';
+export type { HandshakeBody, HandshakeContent, HandshakeResponseBody, HandshakeResponseContent, ContractBody, ContractContent, DelegationBody, DelegationContent, WorkRequestBody, WorkRequestContent, WorkResponseBody, WorkResponseContent, ReceiptBody, ReceiptContent, MemoryDeltaBody, MemoryDeltaContent, DisputeBody, DisputeContent, SettlementSignatureBody, SettlementSignatureContent, AnyBody, ReceiptCosignPayload, DisputeResponseCosignPayload, CosignPayload, DeclineReason, AssetIdentifier, } from './body';
 export { DECLINE_REASONS, isDeclineReason } from './body';
 export type { OwnerSigningMethod, KeyLinkPayload, KeyRotationPayload, ScryptPasswordAttestation } from './identity';
 export { SCRYPT_PARAMS } from './identity';

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export { uuidV4 } from './uuid';
 export { senderNonce } from './nonce';
 export { rfc3339, expiresAt } from './timestamp';
+export { pollUntil, type PollUntilOptions, type PollUntilResult } from './poll';

package/dist/utils/poll.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Generic polling helper for SDK consumers that need to block until
+ * an FSM transition lands.
+ *
+ * The SDK is wire-format-only — it has no HTTP client and no
+ * awareness of the relationship/delegation/receipt state-machine
+ * strings. Callers bring their own `fetch` function (axios, native
+ * fetch, custom transport) and their own predicate; this helper
+ * supplies the polling discipline (interval, timeout, cancellable
+ * AbortSignal, exponential backoff on transient errors).
+ *
+ * Why this is useful enough to ship even without a state-machine
+ * type in the SDK: third-party bot authors today write the loop
+ * themselves and routinely get the discipline wrong — they tight-loop
+ * the RPC, ignore timeouts, swallow errors that should propagate, or
+ * miss state transitions that landed between polls. A 40-LOC
+ * primitive with documented behaviour is worth more than the
+ * duplicated `setTimeout` chains it replaces.
+ *
+ * Pairs with the CLI's `--wait-until <phase>` flag on FSM-advancing
+ * commands: same polling shape, same exit-on-predicate semantics,
+ * ported to the API-client layer for callers who don't shell out to
+ * `heyarp`. Either path can be skipped — `heyarp status <rel-id>
+ * --wait --until <phase>` remains the documented escape hatch.
+ */
+/**
+ * Outcome of a `pollUntil` call.
+ *
+ * - `{ kind: 'matched', value }` — predicate returned true; `value`
+ *   is the matched fetcher return.
+ * - `{ kind: 'timeout', last }` — wall-clock exceeded `timeoutMs`;
+ *   `last` is the most recent fetcher return (which DID NOT match the
+ *   predicate) for the caller's diagnostic / retry decision.
+ * - `{ kind: 'aborted', last }` — `abortSignal.aborted` became true;
+ *   `last` is the most recent fetcher return, or `undefined` if the
+ *   abort fired before the first fetch landed.
+ *
+ * Discriminated union (`kind` literal) so consumers can `switch`
+ * exhaustively. No exceptions are thrown for the timeout/abort
+ * outcomes — they're modelled as values so the caller's branching
+ * stays explicit. Fetcher errors are a different story: they bubble
+ * unless `swallowFetchErrors` is true.
+ */
+export type PollUntilResult<T> = {
+    kind: 'matched';
+    value: T;
+} | {
+    kind: 'timeout';
+    last: T | undefined;
+} | {
+    kind: 'aborted';
+    last: T | undefined;
+};
+export interface PollUntilOptions<T> {
+    /**
+     * Async fetcher invoked once per poll tick. Should return the
+     * domain object the predicate evaluates against. Implementations
+     * typically read the same row the CLI's `composeStatus` reads —
+     * a single signed-GET against the relationship's entities is
+     * common.
+     */
+    fetch: () => Promise<T>;
+    /**
+     * Returns `true` when `value` satisfies the wait condition. The
+     * helper exits with `{ kind: 'matched', value }` on the first
+     * `true`. Predicate exceptions bubble (treat as a fail-fast
+     * programmer error — the predicate shouldn't be side-effectful or
+     * I/O-bound).
+     */
+    predicate: (value: T) => boolean;
+    /** Milliseconds between fetches. Defaults to 3000 (matches CLI WAIT_DEFAULT_INTERVAL_SEC). Lower bound is 100ms to avoid tight-loop accidents. */
+    intervalMs?: number;
+    /** Wall-clock budget in milliseconds. Defaults to 300000 (5 min). On exceed, returns `{ kind: 'timeout', last }`. */
+    timeoutMs?: number;
+    /**
+     * If true, fetch errors are caught and logged via `onFetchError`
+     * (or silently swallowed when that's absent); the loop continues
+     * to the next tick. If false (default), the first fetch error
+     * rejects the returned promise — appropriate for "fail loud on
+     * the first network blip" scripts.
+     */
+    swallowFetchErrors?: boolean;
+    /**
+     * Called once per fetch error when `swallowFetchErrors` is true.
+     * Gets the raw error so the caller can log / sample / surface to
+     * an observability sink without coupling the polling primitive to
+     * any particular logger.
+     */
+    onFetchError?: (err: unknown) => void;
+    /**
+     * Cancellation signal — when its `aborted` flag flips, the
+     * helper resolves with `{ kind: 'aborted', last }` after the
+     * current sleep completes (or immediately if currently mid-sleep
+     * and the signal supports listener-driven abort). The fetcher
+     * itself is not abort-aware here; if it needs to be, the caller
+     * should pass the same signal into its own implementation.
+     */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Poll `fetch` until `predicate` returns true, the timeout fires, or
+ * the optional `abortSignal` aborts. Returns a discriminated outcome
+ * (no exceptions for the expected paths).
+ *
+ * Behaviour notes:
+ *   - The first fetch happens immediately (no leading sleep). If the
+ *     predicate matches on the first call, returns without any sleep
+ *     — useful when the caller already knows the state may have
+ *     transitioned in the background.
+ *   - Sleeps are clamped to the remaining budget; the final sleep
+ *     will be shorter than `intervalMs` when timeout is near.
+ *   - Lower-bound `intervalMs` to 100ms. Higher-frequency polling is
+ *     an accident; if you really need it, build your own loop with
+ *     direct `setTimeout` calls.
+ */
+export declare function pollUntil<T>(opts: PollUntilOptions<T>): Promise<PollUntilResult<T>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyanon-arp/sdk",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "TypeScript SDK for the Agent Relationship Protocol — canonical JSON, Ed25519 envelope sign/verify, did:arp identity, receipt co-signatures, scrypt key attestation, chain-audit helpers.",
   "license": "MIT",
   "keywords": [