@provex/utils 1.11.0 → 2.0.0

package/dist/buy/submitStepDerivations.test.js

@@ -0,0 +1,305 @@
+/**
+ * Tests for the pure derivations extracted from SubmitStep.tsx.
+ *
+ * SubmitStep is a state machine plus JSX wired to wagmi, tx-flight, indexer,
+ * and toast contexts. The state-machine predicates and the fee display math
+ * are pure functions over the lifecycle status, so pinning them here lets a
+ * future SubmitStep refactor land without re-deriving the lifecycle contract.
+ *
+ * Bigint throughout: money values stay bigint until display.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { attestationStateFromResult, attestationFromResult, attestationErrorFromResult, isSubmissionErrorFromResult, isVerifiedOrLater, buttonLoadingTextFromState, isCompleteButtonLoading, isCompleteButtonDisabled, formatFeeTokenAmount, formatNetTokenAmount, } from './submitStepDerivations.js';
+/** Run one test per row, naming it by filling each `%s` in the title from the row. */
+const each = (rows) => (title, run) => {
+    for (const row of rows) {
+        let next = 0;
+        const name = title.replace(/%s/g, () => String(row[next++]));
+        it(name, () => run(row));
+    }
+};
+// Sentinel attestation payload — only the fields the helpers read
+// matter. typedDataValue.releaseAmount is the gross USDC the gate
+// authorized (a stringified bigint, NOT a JS number, because it
+// rides the JSON wire boundary).
+const makeAttestation = (releaseAmount) => ({
+    typedDataValue: { releaseAmount: releaseAmount.toString() },
+});
+// ---------------------------------------------------------------------------
+// Lifecycle status mappings
+// ---------------------------------------------------------------------------
+describe('attestationStateFromResult', () => {
+    // The 1:1 mapping is trivial in code but worth pinning so a refactor
+    // that introduces a new lifecycle status without wiring it through
+    // to AttestationState surfaces in a test rather than at render time.
+    each([
+        ['idle'],
+        ['requesting'],
+        ['verifying'],
+        ['verified'],
+        ['submitting'],
+        ['confirming'],
+        ['syncing'],
+        ['complete'],
+        ['error'],
+    ])('maps %s status to the matching AttestationState', ([status]) => {
+        const result = status === 'idle' || status === 'requesting'
+            ? { status }
+            : status === 'error'
+                ? { status, error: 'fail', isSubmissionError: false }
+                : { status, data: makeAttestation(100n) };
+        assert.equal(attestationStateFromResult(result), status);
+    });
+});
+describe('attestationFromResult', () => {
+    it('returns null for idle and requesting (no attestation yet)', () => {
+        assert.equal(attestationFromResult({ status: 'idle' }), null);
+        assert.equal(attestationFromResult({ status: 'requesting' }), null);
+    });
+    each([
+        ['verifying'],
+        ['verified'],
+        ['submitting'],
+        ['confirming'],
+        ['syncing'],
+        ['complete'],
+    ])('returns the attestation payload in %s', ([status]) => {
+        const att = makeAttestation(100n);
+        const result = { status, data: att };
+        assert.equal(attestationFromResult(result), att);
+    });
+    it('returns the attestation in error state when present (post-verification failure)', () => {
+        // A submission error after a successful verification — the user
+        // can still see what attestation was issued so the failure
+        // recap shows real numbers, not "unknown amount".
+        const att = makeAttestation(100n);
+        assert.equal(attestationFromResult({
+            status: 'error',
+            error: 'tx reverted',
+            isSubmissionError: true,
+            data: att,
+        }), att);
+    });
+    it('returns null in error state when no attestation (pre-verification failure)', () => {
+        assert.equal(attestationFromResult({
+            status: 'error',
+            error: 'attestation service down',
+            isSubmissionError: false,
+        }), null);
+    });
+});
+describe('attestationErrorFromResult', () => {
+    it('returns the error string only in error state', () => {
+        assert.equal(attestationErrorFromResult({
+            status: 'error',
+            error: 'nullifier already used',
+            isSubmissionError: false,
+        }), 'nullifier already used');
+    });
+    each([
+        ['idle'],
+        ['verifying'],
+        ['complete'],
+    ])('returns null in %s state', ([status]) => {
+        const result = status === 'idle'
+            ? { status }
+            : { status, data: makeAttestation(100n) };
+        assert.equal(attestationErrorFromResult(result), null);
+    });
+});
+describe('isSubmissionErrorFromResult', () => {
+    it('returns true only when error AND isSubmissionError flag is set', () => {
+        // The two error sub-categories drive different retry-button copy
+        // ("retry submission" vs "retry verification"). Pinning the
+        // discriminant so a refactor can't accidentally collapse them.
+        assert.equal(isSubmissionErrorFromResult({
+            status: 'error',
+            error: 'tx reverted',
+            isSubmissionError: true,
+        }), true);
+        assert.equal(isSubmissionErrorFromResult({
+            status: 'error',
+            error: 'attestation declined',
+            isSubmissionError: false,
+        }), false);
+    });
+    it('returns false in non-error states', () => {
+        assert.equal(isSubmissionErrorFromResult({ status: 'complete', data: makeAttestation(100n) }), false);
+    });
+});
+describe('isVerifiedOrLater', () => {
+    // The "after verification" predicate gates the receive-first card's
+    // "verified" recap row vs the in-progress spinner. Locking the set
+    // explicitly so a new lifecycle state added later (e.g. 'retrying')
+    // surfaces here as a missing branch.
+    each([
+        ['verified', true],
+        ['submitting', true],
+        ['confirming', true],
+        ['syncing', true],
+        ['complete', true],
+        ['idle', false],
+        ['requesting', false],
+        ['verifying', false],
+        ['error', false],
+    ])('returns %s for %s state', ([state, expected]) => {
+        assert.equal(isVerifiedOrLater(state), expected);
+    });
+});
+// ---------------------------------------------------------------------------
+// Button label + state
+// ---------------------------------------------------------------------------
+describe('buttonLoadingTextFromState', () => {
+    // Every phase where the button is waiting must say what it waits on.
+    // Before this, the pre-ready phases showed a muted "Complete Order"
+    // with no spinner, and the only readiness cue was the outline color.
+    each([
+        ['idle', 'Loading proof...'],
+        ['requesting', 'Loading proof...'],
+        ['verifying', 'Verifying payment...'],
+        ['submitting', 'Submitting...'],
+        ['confirming', 'Confirming...'],
+        ['syncing', 'Syncing...'],
+    ])('labels the waiting state %s as "%s"', ([state, expected]) => {
+        assert.equal(buttonLoadingTextFromState({ state, isFeeReady: true }), expected);
+    });
+    it('waits on the fee once the payment is verified', () => {
+        // The headline can't show the real "You'll receive" amount until
+        // the fee loads, so a verified order is not actionable yet.
+        assert.equal(buttonLoadingTextFromState({ state: 'verified', isFeeReady: false }), 'Loading fees...');
+    });
+    each([
+        ['verified'],
+        ['complete'],
+        ['error'],
+    ])('returns undefined for the settled state %s', ([state]) => {
+        // undefined (NOT null) so Chakra's <Button isLoading loadingText>
+        // falls back to its default label rather than rendering "null".
+        assert.equal(buttonLoadingTextFromState({ state, isFeeReady: true }), undefined);
+    });
+});
+describe('isCompleteButtonLoading', () => {
+    it('returns true when wagmi isPending is true (signing phase)', () => {
+        // Before the tx is sent, wagmi reports isPending while waiting
+        // for wallet confirmation. The button should already be in its
+        // loading state at that point.
+        assert.equal(isCompleteButtonLoading({ isPending: true, state: 'verified', isFeeReady: true }), true);
+    });
+    each([
+        ['requesting'],
+        ['verifying'],
+        ['submitting'],
+        ['confirming'],
+        ['syncing'],
+    ])('returns true in %s state regardless of isPending', ([state]) => {
+        assert.equal(isCompleteButtonLoading({ isPending: false, state, isFeeReady: true }), true);
+    });
+    it('returns true for a verified order whose fee is still loading', () => {
+        assert.equal(isCompleteButtonLoading({ isPending: false, state: 'verified', isFeeReady: false }), true);
+    });
+    it('returns false when verified, fee loaded, and not pending (clickable)', () => {
+        assert.equal(isCompleteButtonLoading({ isPending: false, state: 'verified', isFeeReady: true }), false);
+    });
+    it('never shows a spinner without a label, or a label without a spinner', () => {
+        const states = ['idle', 'requesting', 'verifying', 'verified', 'submitting', 'confirming', 'syncing', 'complete', 'error'];
+        for (const state of states) {
+            for (const isFeeReady of [true, false]) {
+                const hasLabel = buttonLoadingTextFromState({ state, isFeeReady }) !== undefined;
+                assert.equal(isCompleteButtonLoading({ isPending: false, state, isFeeReady }), hasLabel);
+            }
+        }
+    });
+});
+describe('isCompleteButtonDisabled', () => {
+    it('returns true unless attestation is verified (or already loading)', () => {
+        // Disabled in every state EXCEPT verified-and-not-loading. A
+        // regression here would either let the user click before
+        // verification finishes or keep the button disabled even when
+        // the attestation is ready.
+        assert.equal(isCompleteButtonDisabled({ state: 'idle', isLoading: false }), true);
+        assert.equal(isCompleteButtonDisabled({ state: 'verifying', isLoading: false }), true);
+        assert.equal(isCompleteButtonDisabled({ state: 'error', isLoading: false }), true);
+    });
+    it('returns false when verified and not loading (clickable)', () => {
+        assert.equal(isCompleteButtonDisabled({ state: 'verified', isLoading: false }), false);
+    });
+    it('returns false when loading (the spinner handles disabling)', () => {
+        // While loading, the button shows a spinner — Chakra's `isLoading`
+        // prop already prevents clicks, so the `disabled` attribute
+        // should be FALSE to avoid the disabled-style overriding the
+        // loading-style.
+        assert.equal(isCompleteButtonDisabled({ state: 'submitting', isLoading: true }), false);
+    });
+});
+// ---------------------------------------------------------------------------
+// Fee + net display
+// ---------------------------------------------------------------------------
+describe('formatFeeTokenAmount', () => {
+    it('formats a 50bps fee on $100 as "0.50"', () => {
+        // 100 USDC * 50bps = 0.5 USDC. The 2-decimal padding keeps the
+        // column aligned with the net amount above it ("99.50" vs "0.50").
+        assert.equal(formatFeeTokenAmount({
+            intentAmount: 100000000n,
+            tokenDecimals: 6,
+            feeBps: 50n,
+        }), '0.50');
+    });
+    it('trims trailing zeros beyond 2 decimals (0.0050 → 0.005)', () => {
+        // The two-step trim/pad: trim trailing zeros from anything past
+        // 2 decimals, then pad back to a minimum of 2. A fee of 5bps on
+        // $1 = 0.0005 USDC, which formats as "0.0005" raw, trim → "0.0005"
+        // (no trailing zeros), but the minimum-2 pad keeps it as-is.
+        // Pinning the shape so a "clean up" refactor doesn't truncate
+        // to "0.00" and hide the fact that there IS a fee.
+        assert.equal(formatFeeTokenAmount({
+            intentAmount: 1000000n,
+            tokenDecimals: 6,
+            feeBps: 5n,
+        }), '0.0005');
+    });
+    it('returns null when no fee applies (feeBps === 0n)', () => {
+        assert.equal(formatFeeTokenAmount({
+            intentAmount: 100000000n,
+            tokenDecimals: 6,
+            feeBps: 0n,
+        }), null);
+    });
+    it('returns null when intentAmount is missing', () => {
+        assert.equal(formatFeeTokenAmount({
+            intentAmount: null,
+            tokenDecimals: 6,
+            feeBps: 50n,
+        }), null);
+    });
+});
+describe('formatNetTokenAmount', () => {
+    it('returns the net-of-fee amount for a 50bps fee on $100', () => {
+        // 100 USDC * (1 - 50bps) = 99.50 USDC.
+        assert.equal(formatNetTokenAmount({
+            intentAmount: 100000000n,
+            tokenDecimals: 6,
+            feeBps: 50n,
+            defaultDisplay: '100.00',
+        }), '99.50');
+    });
+    it('falls back to defaultDisplay when no fee applies', () => {
+        // The defaultDisplay is passed in pre-formatted from
+        // useOrderDisplayValues. Avoids re-running the formatter when
+        // the answer is "same as the gross amount above".
+        assert.equal(formatNetTokenAmount({
+            intentAmount: 100000000n,
+            tokenDecimals: 6,
+            feeBps: 0n,
+            defaultDisplay: '100.00',
+        }), '100.00');
+    });
+    it('falls back to defaultDisplay when intentAmount is missing', () => {
+        assert.equal(formatNetTokenAmount({
+            intentAmount: null,
+            tokenDecimals: 6,
+            feeBps: 50n,
+            defaultDisplay: '0.00',
+        }), '0.00');
+    });
+});

package/dist/buy/verifiableBanks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Which banks a rail can be verified with.
+ *
+ * The names come from the payment configuration, so a bank added there shows
+ * up in the buy panel hint with no change here.
+ */
+import { type ProviderKey } from '../payment.js';
+import type { ChainId } from '../chain.js';
+/**
+ * Display names of the banks a provider can be verified with.
+ *
+ * @param params.providerKey - The rail, for example `zelle`
+ * @param params.chainId - The chain whose provider configuration applies
+ * @returns Bank names in configuration order, or an empty array when the rail has no banks
+ */
+export declare function getVerifiableBankNames({ providerKey, chainId, }: {
+    providerKey: ProviderKey;
+    chainId: ChainId;
+}): string[];
+/**
+ * Join names into an "or" list in the reader's language.
+ *
+ * @param params.names - Names to join
+ * @param params.language - Language tag for the list format
+ */
+export declare function formatDisjunctionList({ names, language, }: {
+    names: readonly string[];
+    language: string;
+}): string;

package/dist/buy/verifiableBanks.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Which banks a rail can be verified with.
+ *
+ * The names come from the payment configuration, so a bank added there shows
+ * up in the buy panel hint with no change here.
+ */
+import { providerConfigs } from '../payment.js';
+/**
+ * Display names of the banks a provider can be verified with.
+ *
+ * @param params.providerKey - The rail, for example `zelle`
+ * @param params.chainId - The chain whose provider configuration applies
+ * @returns Bank names in configuration order, or an empty array when the rail has no banks
+ */
+export function getVerifiableBankNames({ providerKey, chainId, }) {
+    const { subProviders } = providerConfigs(chainId)[providerKey];
+    return [...subProviders].map((subProvider) => subProvider.name);
+}
+/**
+ * Join names into an "or" list in the reader's language.
+ *
+ * @param params.names - Names to join
+ * @param params.language - Language tag for the list format
+ */
+export function formatDisjunctionList({ names, language, }) {
+    const { ListFormat } = Intl;
+    return new ListFormat(language, { style: 'long', type: 'disjunction' }).format(names);
+}

package/dist/buy/verifiableBanks.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @fileoverview Tests for the bank names shown in the "verify with" hint.
+ */
+export {};

package/dist/buy/verifiableBanks.test.js

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Tests for the bank names shown in the "verify with" hint.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { pulsechain } from 'viem/chains';
+import { providers } from '../payment.js';
+import { formatDisjunctionList, getVerifiableBankNames } from './verifiableBanks.js';
+describe('getVerifiableBankNames', () => {
+    it('lists the banks of a rail in configuration order', () => {
+        assert.deepEqual(getVerifiableBankNames({ providerKey: providers.ZELLE, chainId: pulsechain.id }), [
+            'Chase',
+            'Bank of America',
+            'Citi',
+        ]);
+    });
+    it('returns an empty list for a rail with no banks, so the hint stays hidden', () => {
+        assert.deepEqual(getVerifiableBankNames({ providerKey: providers.VENMO, chainId: pulsechain.id }), []);
+    });
+});
+describe('formatDisjunctionList', () => {
+    it('joins names with "or" in English', () => {
+        assert.equal(formatDisjunctionList({ names: ['Chase', 'Bank of America', 'Citi'], language: 'en' }), 'Chase, Bank of America, or Citi');
+    });
+    it('returns a single name unchanged', () => {
+        assert.equal(formatDisjunctionList({ names: ['Chase'], language: 'en' }), 'Chase');
+    });
+    it('joins two names without a comma', () => {
+        assert.equal(formatDisjunctionList({ names: ['Chase', 'Citi'], language: 'en' }), 'Chase or Citi');
+    });
+});

package/dist/consent.js

@@ -23,8 +23,6 @@
  */
 function ambientStorage() {
     try {
-        if (typeof globalThis === 'undefined')
-            return null;
         const candidate = globalThis.localStorage;
         if (candidate !== null &&
             typeof candidate === 'object' &&

package/dist/consent.storage.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Failure and ambient-storage paths of the consent gate.
+ *
+ * The gate decides whether a buyer may continue past the risk modal. The two
+ * dangers are opposite: a storage fault that throws breaks the accept flow,
+ * and a shape the reader trusts could open the gate for a section never read.
+ */
+export {};

package/dist/consent.storage.test.js

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Failure and ambient-storage paths of the consent gate.
+ *
+ * The gate decides whether a buyer may continue past the risk modal. The two
+ * dangers are opposite: a storage fault that throws breaks the accept flow,
+ * and a shape the reader trusts could open the gate for a section never read.
+ */
+import { afterEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { acceptSection, allAccepted, readConsent, writeConsent, } from './consent.js';
+const KEY = 'provex_consent_test';
+function memoryStorage(initial = {}) {
+    const data = new Map(Object.entries(initial));
+    return {
+        data,
+        getItem: (key) => data.get(key) ?? null,
+        setItem: (key, value) => {
+            data.set(key, value);
+        },
+        removeItem: (key) => {
+            data.delete(key);
+        },
+    };
+}
+const globalWithStorage = globalThis;
+const originalDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'localStorage');
+afterEach(() => {
+    if (originalDescriptor)
+        Object.defineProperty(globalThis, 'localStorage', originalDescriptor);
+    else
+        delete globalWithStorage.localStorage;
+});
+describe('writeConsent', () => {
+    it('swallows a quota error so accepting a section never throws', () => {
+        const full = {
+            getItem: () => null,
+            setItem: () => {
+                throw new Error('QuotaExceededError');
+            },
+            removeItem: () => { },
+        };
+        assert.doesNotThrow(() => writeConsent(KEY, { risks: { hash: 'aa', acceptedAt: 'now' } }, full));
+    });
+    it('still returns the accepted state when persisting fails', () => {
+        const full = {
+            getItem: () => null,
+            setItem: () => {
+                throw new Error('QuotaExceededError');
+            },
+            removeItem: () => { },
+        };
+        const state = acceptSection(KEY, 'risks', 'abc12345', { storage: full, now: new Date('2030-01-01T00:00:00Z') });
+        assert.deepEqual(state, { risks: { hash: 'abc12345', acceptedAt: '2030-01-01T00:00:00.000Z' } });
+    });
+    it('does nothing when storage is null', () => {
+        assert.doesNotThrow(() => writeConsent(KEY, {}, null));
+    });
+});
+describe('readConsent shape checks', () => {
+    it('returns {} for a stored JSON array, which would otherwise index like an object', () => {
+        const storage = memoryStorage({ [KEY]: JSON.stringify([{ hash: 'x', acceptedAt: 'y' }]) });
+        assert.deepEqual(readConsent(KEY, storage), {});
+    });
+    it('returns {} for a stored JSON null', () => {
+        const storage = memoryStorage({ [KEY]: 'null' });
+        assert.deepEqual(readConsent(KEY, storage), {});
+    });
+    it('returns {} when reading storage itself throws', () => {
+        const broken = {
+            getItem: () => {
+                throw new Error('SecurityError');
+            },
+            setItem: () => { },
+            removeItem: () => { },
+        };
+        assert.deepEqual(readConsent(KEY, broken), {});
+    });
+});
+describe('ambient storage', () => {
+    it('uses globalThis.localStorage when it has the full storage interface', () => {
+        const storage = memoryStorage();
+        Object.defineProperty(globalThis, 'localStorage', { value: storage, configurable: true, writable: true });
+        acceptSection(KEY, 'terms', 'h1', { now: new Date('2030-01-01T00:00:00Z') });
+        assert.equal(allAccepted(KEY, { terms: 'h1' }), true);
+        assert.ok(storage.data.has(KEY));
+    });
+    it('degrades to an unaccepted gate when localStorage lacks a storage method', () => {
+        // WHY: a partial shim must not be treated as storage. The gate stays closed.
+        Object.defineProperty(globalThis, 'localStorage', {
+            value: { getItem: () => '{"terms":{"hash":"h1","acceptedAt":"x"}}', setItem: () => { } },
+            configurable: true,
+            writable: true,
+        });
+        assert.equal(allAccepted(KEY, { terms: 'h1' }), false);
+    });
+    it('degrades to an unaccepted gate when the localStorage getter throws', () => {
+        // WHY: some browsers throw SecurityError on access in private mode or with cookies blocked.
+        Object.defineProperty(globalThis, 'localStorage', {
+            get() {
+                throw new Error('SecurityError');
+            },
+            configurable: true,
+        });
+        assert.equal(allAccepted(KEY, { terms: 'h1' }), false);
+        assert.doesNotThrow(() => acceptSection(KEY, 'terms', 'h1'));
+    });
+    it('treats a null localStorage as unavailable', () => {
+        Object.defineProperty(globalThis, 'localStorage', { value: null, configurable: true, writable: true });
+        assert.deepEqual(readConsent(KEY), {});
+    });
+});

package/dist/consent.test.js

@@ -1,4 +1,4 @@
-import { describe, it } from 'node:test';
+import { afterEach, describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { hashString, formatRelative, readConsent, writeConsent, sectionStatus, acceptSection, allAccepted, migrateLegacyBoolean, } from './consent.js';
 /**
@@ -269,3 +269,62 @@ describe('migrateLegacyBoolean', () => {
         assert.equal(migrated, false);
     });
 });
+describe('ambient storage', () => {
+    const original = Object.getOwnPropertyDescriptor(globalThis, 'localStorage');
+    /** Replace `globalThis.localStorage` for one case. */
+    const installLocalStorage = (descriptor) => {
+        Object.defineProperty(globalThis, 'localStorage', { configurable: true, ...descriptor });
+    };
+    afterEach(() => {
+        delete globalThis.localStorage;
+        if (original)
+            Object.defineProperty(globalThis, 'localStorage', original);
+    });
+    const hashes = { risks: 'h1' };
+    it('uses the browser storage when no storage is passed', () => {
+        const storage = memStorage();
+        installLocalStorage({ value: storage });
+        acceptSection('key', 'risks', 'h1', { now: new Date('2026-01-01T00:00:00Z') });
+        assert.equal(allAccepted('key', hashes), true);
+        assert.deepEqual(readConsent('key'), {
+            risks: { hash: 'h1', acceptedAt: '2026-01-01T00:00:00.000Z' },
+        });
+        writeConsent('other', {});
+        assert.equal(storage.getItem('other'), '{}');
+    });
+    it('migrates the legacy flag out of the browser storage when none is passed', () => {
+        const storage = memStorage();
+        storage.setItem('legacy', '1');
+        installLocalStorage({ value: storage });
+        assert.equal(migrateLegacyBoolean({ legacyKey: 'legacy', storageKey: 'key', currentHashes: hashes }), true);
+        assert.equal(storage.getItem('legacy'), null);
+    });
+    const unusableStorages = [
+        ['absent', { value: undefined }],
+        ['null', { value: null }],
+        ['not an object', { value: 'storage' }],
+        ['missing getItem', { value: { setItem: () => { }, removeItem: () => { } } }],
+        ['missing setItem', { value: { getItem: () => null, removeItem: () => { } } }],
+        ['missing removeItem', { value: { getItem: () => null, setItem: () => { } } }],
+        ['throwing on access (a private window or blocked site data)', { get: () => { throw new Error('denied'); } }],
+    ];
+    for (const [name, descriptor] of unusableStorages) {
+        it(`treats storage that is ${name} as unavailable, so the gate stays closed and nothing throws`, () => {
+            installLocalStorage(descriptor);
+            assert.deepEqual(readConsent('key'), {});
+            assert.doesNotThrow(() => writeConsent('key', {}));
+            assert.equal(allAccepted('key', hashes), false);
+            assert.equal(migrateLegacyBoolean({ legacyKey: 'legacy', storageKey: 'key', currentHashes: hashes }), false);
+            assert.deepEqual(acceptSection('key', 'risks', 'h1').risks?.hash, 'h1');
+        });
+    }
+    it('lets an acceptance stand for the session when the write is refused', () => {
+        const refusing = {
+            getItem: () => null,
+            setItem: () => { throw new Error('quota'); },
+            removeItem: () => { },
+        };
+        assert.doesNotThrow(() => writeConsent('key', {}, refusing));
+        assert.equal(acceptSection('key', 'risks', 'h1', { storage: refusing }).risks?.hash, 'h1');
+    });
+});

package/dist/contracts.js

@@ -484,8 +484,10 @@ export function getConfiguredOrchestratorForEscrow(escrow) {
     const location = getEscrowLocation(escrow);
     if (!location || location.version !== 'v4')
         return null;
+    // The location index is built from `contracts`, so the chain entry exists
+    // and `orchestrator` is a non-empty array by type.
     const v4ForChain = contracts.v4[location.chainId];
-    return v4ForChain?.orchestrator?.at(-1) ?? null;
+    return v4ForChain.orchestrator.at(-1);
 }
 /**
  * Get all V3 escrow contracts across all chains.

package/dist/contracts.test.js

@@ -1,4 +1,4 @@
-import { describe, it } from 'node:test';
+import { describe, it, mock } from 'node:test';
 import assert from 'node:assert/strict';
 import { base, pulsechain } from 'viem/chains';
 import { getContracts, getLatestContract, getLatestConfiguredVersion, getPaymentAttestationVerifier, checkPaymentAttestationVerifier, detectVersionFromEscrow, getConfiguredOrchestratorForEscrow, getAllEscrowContracts, getAllV3EscrowContracts, shortenEscrowAddress, getEscrowVersion, isV3Escrow, supportsOrchestrator, supportsOrchestratorEscrow, v2BaseContracts, v3BaseContracts, v4BaseContracts, v2PulsechainContracts, v3PulsechainContracts, v4PulsechainContracts, V3_PULSECHAIN_DEPLOYMENT_REFERENCE, contracts, } from './contracts.js';
@@ -464,3 +464,19 @@ describe('contracts', () => {
         });
     });
 });
+describe('contracts: chain with no configured contracts', () => {
+    const UNCONFIGURED_CHAIN = 99999;
+    it('reports v3 as the latest version so callers keep a usable default', () => {
+        assert.strictEqual(getLatestConfiguredVersion(UNCONFIGURED_CHAIN), 'v3');
+    });
+    it('returns null and logs the missing chain instead of throwing', () => {
+        const log = mock.method(console, 'log', () => { });
+        try {
+            assert.strictEqual(getLatestContract(UNCONFIGURED_CHAIN, 'escrow', 'v3'), null);
+            assert.strictEqual(log.mock.callCount(), 1);
+        }
+        finally {
+            log.mock.restore();
+        }
+    });
+});