@avow-finance/sdk 0.0.0-stage → 0.2.0

package/dist/sandbox/namespace.d.ts

@@ -0,0 +1,16 @@
+import { sandboxAgent } from './agent.js';
+import { loadSandboxDeployment } from './deployment.js';
+import { prepareSandboxBusiness } from './setup.js';
+import { memoryStore } from './store.js';
+/**
+ * Avow's sandbox on Tempo's Moderato testnet. `sandbox.business` is the business's side, which
+ * holds the root key and signs the agent's mandate, and only the runner calls it. `sandbox.agent`
+ * is the agent's side, which acts with only the agent's key.
+ */
+export declare const sandbox: {
+    readonly agent: typeof sandboxAgent;
+    readonly business: typeof prepareSandboxBusiness;
+    readonly deployment: typeof loadSandboxDeployment;
+    readonly memoryStore: typeof memoryStore;
+};
+//# sourceMappingURL=namespace.d.ts.map

package/dist/sandbox/namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../src/sandbox/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC;;;;GAIG;AACH,eAAO,MAAM,OAAO;;;;;CAKV,CAAA"}

package/dist/sandbox/namespace.js

@@ -0,0 +1,16 @@
+import { sandboxAgent } from './agent.js';
+import { loadSandboxDeployment } from './deployment.js';
+import { prepareSandboxBusiness } from './setup.js';
+import { memoryStore } from './store.js';
+/**
+ * Avow's sandbox on Tempo's Moderato testnet. `sandbox.business` is the business's side, which
+ * holds the root key and signs the agent's mandate, and only the runner calls it. `sandbox.agent`
+ * is the agent's side, which acts with only the agent's key.
+ */
+export const sandbox = {
+    agent: sandboxAgent,
+    business: prepareSandboxBusiness,
+    deployment: loadSandboxDeployment,
+    memoryStore,
+};
+//# sourceMappingURL=namespace.js.map

package/dist/sandbox/namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.js","sourceRoot":"","sources":["../../src/sandbox/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,KAAK,EAAE,YAAY;IACnB,QAAQ,EAAE,sBAAsB;IAChC,UAAU,EAAE,qBAAqB;IACjC,WAAW;CACH,CAAA"}

package/dist/sandbox/session.d.ts

@@ -0,0 +1,60 @@
+import { type AvowDomain, type CommitmentReference, type RequestKey, type SessionEvent, type SessionEventAnswer } from '@avow-finance/spec';
+import { type Address } from 'viem';
+import { type AvowRequestConfig } from '../http.js';
+/** The testnet sandbox's screen, which shows a session's events and checks a shared commitment. */
+export declare const SANDBOX_SCREEN_URL = "https://try.testnet.avow.finance";
+/** The link to the screen that shows a session's events as they arrive. */
+export declare function sessionUrl(sessionId: string, screenUrl?: string): string;
+/**
+ * The link anyone can open to check a commitment against the lock it names. Its fragment carries
+ * the commitment reference as `encodeCommitmentReference` writes it, and never reaches a server.
+ */
+export declare function verifyUrl(reference: CommitmentReference, screenUrl?: string): string;
+export interface SessionRelayConfig extends Omit<AvowRequestConfig, 'key'> {
+    /** The session the screen at `sessionUrl(sessionId)` shows. */
+    sessionId: string;
+    /**
+     * The key that signs each event, so Avow's API can tell it comes from a registered sandbox
+     * business before it relays it to the screen. The agent's process signs with the agent's key,
+     * through `agentRequestKey`, and only the runner signs an authority change with the business's
+     * root key, through `rootRequestKey`.
+     */
+    key: RequestKey;
+    /** The chain and the business's lock, which each event's request is signed under. */
+    domain: AvowDomain;
+}
+/** Posts a sandbox business's events to one session. */
+export interface SessionRelay {
+    readonly sessionId: string;
+    /** Posts one event and gives its place in the session, counting from 1. */
+    post(event: SessionEvent): Promise<SessionEventAnswer>;
+}
+/**
+ * Avow's relay for one session's events. Each event is one request through `avowRequests`, signed
+ * by `key` under the business's lock, so a lost answer never posts the same event twice. It stops resending after 20 seconds by default, since a screen that shows an event late
+ * helps no one, and a refusal throws an `AvowApiError` with Avow's reason.
+ */
+export declare function sessionRelay(config: SessionRelayConfig): SessionRelay;
+/** Where a session stands with Avow's relay. */
+export interface SessionStanding {
+    /** The business the session is bound to, or null while no event has reached it. */
+    business: {
+        businessId: string;
+        account: Address;
+        lock: Address;
+    } | null;
+    /** When the relay stops taking the session's events, in unix seconds, or null while unbound. */
+    endsAt: bigint | null;
+    /** The highest run number among the session's events, or 0 when it has none. */
+    lastRun: number;
+}
+/**
+ * Where a session stands with Avow's relay, read from the route the screen reads, which needs no
+ * signature. It reads the session's events a page at a time for the last run number in it.
+ */
+export declare function readSessionStanding(m: {
+    apiUrl: string;
+    sessionId: string;
+    fetch?: typeof fetch;
+}): Promise<SessionStanding>;
+//# sourceMappingURL=session.d.ts.map

package/dist/sandbox/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/sandbox/session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,mBAAmB,EAIxB,KAAK,UAAU,EAEf,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,KAAK,OAAO,EAAa,MAAM,MAAM,CAAA;AAC9C,OAAO,EAAE,KAAK,iBAAiB,EAAgB,MAAM,YAAY,CAAA;AAEjE,mGAAmG;AACnG,eAAO,MAAM,kBAAkB,qCAAqC,CAAA;AAKpE,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,GAAE,MAA2B,GAAG,MAAM,CAG5F;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,mBAAmB,EAC9B,SAAS,GAAE,MAA2B,GACrC,MAAM,CAER;AAED,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC;IACxE,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,GAAG,EAAE,UAAU,CAAA;IACf,qFAAqF;IACrF,MAAM,EAAE,UAAU,CAAA;CACnB;AAED,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,2EAA2E;IAC3E,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;CACvD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAQrE;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;IACxE,gGAAgG;IAChG,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAA;CAChB;AAuCD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,GAAG,OAAO,CAAC,eAAe,CAAC,CAoB3B"}

package/dist/sandbox/session.js

@@ -0,0 +1,94 @@
+import { encodeCommitmentReference, isSessionId, parseSessionEventAnswer, SANDBOX_PATHS, } from '@avow-finance/spec';
+import { isAddress } from 'viem';
+import { avowRequests } from '../http.js';
+/** The testnet sandbox's screen, which shows a session's events and checks a shared commitment. */
+export const SANDBOX_SCREEN_URL = 'https://try.testnet.avow.finance';
+/** The screen's own origin, without the trailing slash a pasted URL may carry. */
+const screenOrigin = (screenUrl) => new URL(screenUrl).origin;
+/** The link to the screen that shows a session's events as they arrive. */
+export function sessionUrl(sessionId, screenUrl = SANDBOX_SCREEN_URL) {
+    if (!isSessionId(sessionId))
+        throw new RangeError(`${sessionId} isn't a session id`);
+    return `${screenOrigin(screenUrl)}/#session=${sessionId}`;
+}
+/**
+ * The link anyone can open to check a commitment against the lock it names. Its fragment carries
+ * the commitment reference as `encodeCommitmentReference` writes it, and never reaches a server.
+ */
+export function verifyUrl(reference, screenUrl = SANDBOX_SCREEN_URL) {
+    return `${screenOrigin(screenUrl)}/#verify=${encodeCommitmentReference(reference)}`;
+}
+/**
+ * Avow's relay for one session's events. Each event is one request through `avowRequests`, signed
+ * by `key` under the business's lock, so a lost answer never posts the same event twice. It stops resending after 20 seconds by default, since a screen that shows an event late
+ * helps no one, and a refusal throws an `AvowApiError` with Avow's reason.
+ */
+export function sessionRelay(config) {
+    const { sessionId, key, domain, ...request } = config;
+    const path = SANDBOX_PATHS.sessionEvents(sessionId);
+    const send = avowRequests({ retryFor: 20n, ...request, key });
+    return {
+        sessionId,
+        post: (event) => send({ domain, path, body: { event }, read: parseSessionEventAnswer }),
+    };
+}
+/** One page of a session's events, as the relay's events route answers. */
+function readPage(json) {
+    if (typeof json !== 'object' || json === null)
+        return null;
+    const page = json;
+    const b = page.business;
+    const business = b === null
+        ? null
+        : typeof b === 'object' &&
+            typeof b.businessId === 'string' &&
+            typeof b.account === 'string' &&
+            isAddress(b.account) &&
+            typeof b.lock === 'string' &&
+            isAddress(b.lock)
+            ? { businessId: b.businessId, account: b.account, lock: b.lock }
+            : undefined;
+    const endsAt = page.expiresAt === null
+        ? null
+        : (typeof page.expiresAt === 'string' && /^[0-9]{1,20}$/.test(page.expiresAt)) ||
+            (typeof page.expiresAt === 'number' && Number.isSafeInteger(page.expiresAt))
+            ? BigInt(page.expiresAt)
+            : undefined;
+    if (business === undefined || endsAt === undefined || !Array.isArray(page.events))
+        return null;
+    const events = page.events.flatMap((e) => {
+        const row = e;
+        return typeof row?.sequence === 'number' && typeof row.event?.run === 'number'
+            ? [{ sequence: row.sequence, run: row.event.run }]
+            : [];
+    });
+    return { business, endsAt, events };
+}
+/**
+ * Where a session stands with Avow's relay, read from the route the screen reads, which needs no
+ * signature. It reads the session's events a page at a time for the last run number in it.
+ */
+export async function readSessionStanding(m) {
+    const send = m.fetch ?? ((input, init) => fetch(input, init));
+    const url = `${m.apiUrl.replace(/\/+$/, '')}${SANDBOX_PATHS.sessionEvents(m.sessionId)}`;
+    let standing = { business: null, endsAt: null, lastRun: 0 };
+    let after = 0;
+    // A session holds a few hundred events at most, so this reads all of them well within the bound.
+    for (let pages = 0; pages < 100; pages++) {
+        const answer = await send(`${url}?after=${after}`);
+        if (!answer.ok)
+            throw new Error(`Avow's relay answered ${answer.status} for the session`);
+        const page = readPage(await answer.json());
+        if (!page)
+            throw new Error("Avow's relay answered for the session in a form the SDK doesn't read");
+        standing = { ...standing, business: page.business, endsAt: page.endsAt };
+        if (page.events.length === 0)
+            break;
+        for (const e of page.events) {
+            standing.lastRun = Math.max(standing.lastRun, e.run);
+            after = Math.max(after, e.sequence);
+        }
+    }
+    return standing;
+}
+//# sourceMappingURL=session.js.map

package/dist/sandbox/session.js.map

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

package/dist/sandbox/setup.d.ts

@@ -0,0 +1,136 @@
+import { type SandboxDeployment } from '@avow-finance/spec';
+import { type Address, type Hex } from 'viem';
+import { type SandboxSession } from './agent.js';
+import { type SandboxClient } from './business.js';
+import { type SandboxStore, type SandboxSupplier } from './store.js';
+/** What a business gives its agent, as `business.ts` in the starter says it. */
+export interface SandboxBusinessConfig {
+    /** The name the business registers under. */
+    name: string;
+    /** Two capital letters, `US` when left out. */
+    country?: string;
+    /**
+     * The most the agent can hold in bookings at once, in dollars. Avow refuses a booking past it, and
+     * the lock checks each reserve against the caps in Avow's approval.
+     */
+    authority: number;
+    /**
+     * The most the agent's key can move in a day, in dollars, which the business sets on chain and the
+     * account's keychain holds whatever Avow approves. $1,000 when left out.
+     */
+    dailyLimit?: number;
+    /** The suppliers the agent may book with, and no others. */
+    suppliers: readonly SandboxSupplier[];
+}
+/** How the business's side asks the person running it. */
+export interface SandboxPrompts {
+    /** Asks for a new passphrase the first time, which seals the business's key. */
+    newPassphrase(): Promise<string>;
+    /** Asks for the passphrase that opens the business's key. */
+    passphrase(): Promise<string>;
+    /**
+     * Asks a yes or no question, before the business signs anything new. The details say what a yes
+     * does, a sentence each.
+     */
+    confirm(question: string, details?: readonly string[]): Promise<boolean>;
+}
+/**
+ * What a line setup reports is: a stage starting, a step done, something under way until the next
+ * line, or a sentence to read. A log that ignores it still reads in order.
+ */
+/**
+ * How a setup line draws. A first setup runs as numbered steps: `step` starts one, its title and a
+ * sentence on why it matters on two lines, and `step_done` ends it with what it left. A `detail`
+ * line, such as an address, shows only when the developer asks for details.
+ */
+export type SetupLineKind = 'stage' | 'done' | 'wait' | 'note' | 'step' | 'step_done' | 'detail';
+export interface PrepareSandboxBusinessOptions {
+    config: SandboxBusinessConfig;
+    prompts: SandboxPrompts;
+    /** Where the business keeps its sealed key and its agent's item. The `.avow` folder in Node. */
+    store?: SandboxStore;
+    screenUrl?: string;
+    deployment?: SandboxDeployment;
+    /** The chain, through the deployment's node when left out. */
+    client?: SandboxClient;
+    /** The session an authority change is reported to, signed by the business's root key. */
+    session?: SandboxSession | null;
+    /**
+     * Whether the job chapter needs the business registered as a supplier with a signing key of its
+     * own. A registration that fails doesn't stop setup, and the result says why.
+     */
+    supplier?: boolean;
+    /**
+     * Whether the session hasn't had the agent's authority yet, as on a first run, after `npm run
+     * fresh` or once a session has ended. Then the business's key signs the current authority into
+     * it even when nothing changed, which takes the passphrase once.
+     */
+    announce?: boolean;
+    /** Where setup says what it's doing, each line with what kind of line it is. */
+    log?: (line: string, kind?: SetupLineKind) => void;
+    fetch?: typeof fetch;
+}
+/** Where the business stands once it's prepared. */
+export interface PreparedSandboxBusiness {
+    businessId: string;
+    account: Address;
+    lock: Address;
+    /** The authority the agent holds now, in dollars. */
+    authority: number;
+    suppliers: string[];
+    mandateHash: Hex;
+    /** Whether this call signed a new mandate. */
+    signed: boolean;
+    /**
+     * Whether this call gave the session the agent's authority, as it does whenever it signs a
+     * mandate, and with `announce` when nothing changed.
+     */
+    announced: boolean;
+    /**
+     * The business as a supplier of jobs when `supplier` asked for it: registered with its signing
+     * key, or why it couldn't be. Null when nothing asked.
+     */
+    supplier: {
+        ok: true;
+        signingKey: Address;
+    } | {
+        ok: false;
+        why: string;
+    } | null;
+}
+/**
+ * The business's side of the sandbox, which only the runner calls. The first time, it asks for a
+ * passphrase and seals a new root key under it, registers the business with Avow's sandbox, waits
+ * for its test dollars and creates its lock. It takes whether the business is set up, and which
+ * mandate the agent holds, from the chain, since anything running as the developer can write the
+ * .avow folder, and it sets a business up again only after a yes to a question that says what that
+ * replaces. Whenever the authority or the suppliers in the config differ from the mandate the chain
+ * holds, or the mandate is about to expire, it asks before signing a new mandate, then asks for the
+ * passphrase. A transaction of its own revokes every other key the account's keychain still
+ * authorizes, access or admin, read from the chain from the lock's creation, so nothing the agent
+ * can write keeps a key live. Then a new agent key goes on the account, and each supplier the lock
+ * approves that the new mandate doesn't name comes off, each in its own transaction. The root key
+ * is opened only for those signatures, and never stored or passed on in the clear.
+ */
+export declare function prepareSandboxBusiness(options: PrepareSandboxBusinessOptions): Promise<PreparedSandboxBusiness>;
+/**
+ * Has the agent try to hold a dollar more than its business just allowed, and says who refused
+ * it. A first setup doesn't stop for a try that couldn't run, such as one whose supplier didn't
+ * answer, so that gives null and the step ends without it.
+ */
+export declare function limitTry(authority: bigint, book: (reserve: number) => Promise<unknown>): Promise<string | null>;
+/**
+ * Cancels one of the agent's commitments on the lock before free cancellation ends, which gives
+ * the whole reserve back. It's the business's call, signed by its root key once the person types
+ * the passphrase, since the agent's key can't cancel on the lock.
+ */
+export declare function cancelSandboxCommitment(options: {
+    commitmentId: Hex;
+    prompts: Pick<SandboxPrompts, 'passphrase'>;
+    store?: SandboxStore;
+    screenUrl?: string;
+    deployment?: SandboxDeployment;
+    client?: SandboxClient;
+    fetch?: typeof fetch;
+}): Promise<Hex>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/sandbox/setup.d.ts.map

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