@defdone/annon 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/browser/login-dom.d.ts

@@ -4,7 +4,7 @@
  */
 import type { Status } from './login-status.js';
 import type { Summary } from './login-view.js';
-declare const IDS: readonly ["title", "pair", "summary", "amount", "rows", "message-box", "message-label", "message", "terms-box", "terms", "warnings", "note", "wallet-field", "approve", "status", "action"];
+declare const IDS: readonly ["current-technical", "step-state", "title", "pair", "summary", "amount", "rows", "message-box", "message-label", "message", "terms-box", "terms", "warnings", "note", "wallet-field", "approve", "status", "action"];
 export type PageElements = Record<(typeof IDS)[number], HTMLElement>;
 export declare function pageElements(doc: Document): PageElements;
 /** Shows one request. Returns the element the caller updates with the time left. */

package/dist/browser/login-dom.js

@@ -3,6 +3,8 @@
  * this module never parses markup.
  */
 const IDS = [
+    'current-technical',
+    'step-state',
     'title',
     'pair',
     'summary',
@@ -59,7 +61,9 @@ export function renderSummary(doc, el, s, technical) {
     el.note.textContent = s.note;
     el.action.textContent = technical;
     el.summary.hidden = false;
-    return dds[dds.length - 1];
+    const expiry = dds[dds.length - 1];
+    expiry.setAttribute('data-expiry', '');
+    return expiry;
 }
 export function showStatus(el, status) {
     el.status.textContent = status.text;

package/dist/browser/login-status.d.ts

@@ -48,7 +48,7 @@ export declare const STATUS: {
     };
     readonly signed: {
         readonly tone: "ok";
-        readonly text: "Signed. Return to the terminal. Keep this tab open if the command asks for another approval.";
+        readonly text: "Signed. Return to the terminal. Keep this tab open until the command finishes.";
     };
     readonly redirected: {
         readonly tone: "ok";

package/dist/browser/login-status.js

@@ -60,7 +60,7 @@ export const STATUS = {
     verifying: { tone: 'wait', text: 'Signed. The CLI is checking the result.' },
     signed: {
         tone: 'ok',
-        text: 'Signed. Return to the terminal. Keep this tab open if the command asks for another approval.',
+        text: 'Signed. Return to the terminal. Keep this tab open until the command finishes.',
     },
     redirected: {
         tone: 'ok',

package/dist/browser/login-steps.d.ts

@@ -0,0 +1,6 @@
+import type { PageElements } from './login-dom.js';
+/** Completed steps contain snapshots of text and review content, never live controls. */
+export declare function approvalSteps(doc: Document, el: PageElements): {
+    start(): void;
+    finish(): void;
+};

package/dist/browser/login-steps.js

@@ -0,0 +1,35 @@
+/** Completed steps contain snapshots of text and review content, never live controls. */
+export function approvalSteps(doc, el) {
+    const list = doc.getElementById('steps');
+    return {
+        start() {
+            el['current-technical'].hidden = false;
+            el['step-state'].textContent = 'In progress';
+        },
+        finish() {
+            const step = doc.createElement('details');
+            step.className = 'step done';
+            const heading = doc.createElement('summary');
+            const mark = doc.createElement('span');
+            mark.className = 'done-mark';
+            mark.textContent = '✓ Done';
+            const title = doc.createElement('span');
+            title.textContent = el.title.textContent;
+            heading.append(mark, title);
+            const content = el.summary.cloneNode(true);
+            // Snapshots have no IDs, so only the current request owns page references.
+            content.removeAttribute('id');
+            for (const node of Array.from(content.querySelectorAll('[id]')))
+                node.removeAttribute('id');
+            for (const node of Array.from(content.querySelectorAll('[data-expiry]')))
+                node.textContent = 'Signed';
+            const technical = doc.createElement('pre');
+            technical.textContent = el.action.textContent;
+            step.append(heading, content, technical);
+            list.append(step);
+            el.summary.hidden = true;
+            el['current-technical'].hidden = true;
+            el['step-state'].textContent = 'Done';
+        },
+    };
+}

package/dist/browser/login.js

@@ -3,6 +3,7 @@ import { pageElements, renderSummary, showStatus } from './login-dom.js';
 import { walletPicker } from './login-dropdown.js';
 import { expiryText } from './login-format.js';
 import { connected, SendUncertain, STATUS, walletFailure } from './login-status.js';
+import { approvalSteps } from './login-steps.js';
 import { describeRequest, technicalDetails } from './login-view.js';
 import { pageWallets } from './login-wallet.js';
 Object.assign(globalThis, { Buffer });
@@ -13,7 +14,11 @@ const fragment = new URLSearchParams(location.hash.slice(1));
 const redirected = location.pathname === '/callback';
 let capability = redirected ? '' : location.hash.slice(1);
 history.replaceState(null, '', location.pathname);
-const api = async (path, body) => {
+let paused = false;
+let finished = false;
+let pollTimer;
+const steps = approvalSteps(document, el);
+const api = async (path, body, accepted) => {
     const r = await fetch(path, {
         method: 'POST',
         headers: { authorization: `Bearer ${capability}`, 'content-type': 'application/json' },
@@ -24,11 +29,13 @@ const api = async (path, body) => {
     });
     if (!r.ok)
         throw new Error('Session expired or wallet result rejected. Return to the terminal.');
+    accepted?.();
     return r.json();
 };
 /** Requests whose result went to the CLI, or that ended here: never signed again. */
 const done = new Set();
 const callbacks = new Map();
+const submitting = new Set();
 const wallets = pageWallets({
     expect: (state, id) => callbacks.set(state, id),
     forget: (state) => callbacks.delete(state),
@@ -60,12 +67,34 @@ function controls() {
         q && wallets.needsConnect(q, walletId()) ? 'Connect wallet' : 'Review in wallet';
 }
 async function submit(id, result) {
+    if (submitting.has(id))
+        return;
+    submitting.add(id);
+    paused = true;
+    clearTimeout(pollTimer);
     done.add(id);
     status(STATUS.verifying);
     controls();
     try {
-        await api('/api/result', { id, result });
-        status(STATUS.signed);
+        let accepted = false;
+        try {
+            const next = await api('/api/result', { id, result, follow: true }, () => {
+                accepted = true;
+                steps.finish();
+                finished = true;
+                status(STATUS.signed);
+            });
+            if (next.action && next.action.id !== id) {
+                show(next.action);
+            }
+        }
+        catch (error) {
+            if (!accepted)
+                throw error;
+            status(STATUS.signed);
+        }
+        paused = false;
+        pollTimer = setTimeout(() => void poll(), 1000);
     }
     catch {
         status(STATUS.rejected);
@@ -99,6 +128,8 @@ else {
 function show(q, sendStarted = false) {
     if (q && q.id !== current?.id) {
         current = q;
+        finished = false;
+        steps.start();
         expiry = renderSummary(document, el, describeRequest(q), technicalDetails(q));
         el['wallet-field'].hidden = !q.operation.startsWith('near.');
         picker.setDisabled('hot-wallet', q.chain !== 'near:mainnet');
@@ -125,19 +156,25 @@ function show(q, sendStarted = false) {
     controls();
 }
 async function poll() {
+    if (paused)
+        return;
     if (!capability) {
         status(STATUS.noCapability);
         return;
     }
     try {
         const r = await api('/api/action');
+        if (paused)
+            return;
         el.pair.textContent = String(r.pairingCode);
         show(r.action ?? undefined, r.sendStarted === true);
-        setTimeout(() => {
+        pollTimer = setTimeout(() => {
             void poll();
         }, 1000);
     }
     catch (e) {
+        if (paused || finished)
+            return;
         status({ tone: 'error', text: e.message });
         capability = '';
         approve.disabled = true;

package/dist/node/adapter-checks.d.ts

@@ -3,4 +3,6 @@ import type { Config } from './config.js';
 declare const fail: (code: AnnonErrorCode, message: string, exit?: PublicError["exitCode"]) => never;
 declare const isId: (id: string) => boolean;
 declare const backupPath: (c: Config, id: string) => string;
-export { backupPath, fail, isId };
+/** A catalog row number in place of a URL: `buy 2 --shop demo`. */
+declare const isRow: (target: string | undefined) => boolean;
+export { backupPath, fail, isId, isRow };

package/dist/node/adapter-checks.js

@@ -10,4 +10,6 @@ const backupPath = (c, id) => {
         throw usage();
     return join(c.stateDir, 'backups', `${id.replaceAll(':', '-')}.json`);
 };
-export { backupPath, fail, isId };
+/** A catalog row number in place of a URL: `buy 2 --shop demo`. */
+const isRow = (target) => /^[1-9][0-9]{0,4}$/.test(target ?? '');
+export { backupPath, fail, isId, isRow };

package/dist/node/adapter.js

@@ -2,6 +2,7 @@
 import { createCoreAdapter } from './core-adapter.js';
 // core-adapter.js loads first: it imports the SDK modules in the order this file did, so they initialize as before.
 import { identityJson, parseIdentity } from '../settle-near/identity.js';
+import { isRow } from './adapter-checks.js';
 import { agentPolicy, configPath, initAgent, savePublicConfig } from './agent.js';
 import { initBackupSecret, initPolicy } from './backup-secret-init.js';
 import { startBrowserSession } from './browser-login.js';
@@ -9,7 +10,7 @@ import { loadConfig } from './config.js';
 import { AdapterError } from './errors.js';
 import { osKeychain } from './keychain.js';
 import { confinePaths } from './paths.js';
-import { discoverShops, isDiscovery } from './shops.js';
+import { catalogRow, discoverShops, isDiscovery } from './shops.js';
 import { assertSignerInput, configuredWallet } from './signer-wallet.js';
 import { signingRequest, verifySigningResult } from './signing.js';
 import { identity } from './wallets.js';
@@ -29,6 +30,9 @@ export function createAdapter(env = process.env, d = {}) {
         const c = await loadConfig(o, env, o.command === 'login', d.agent);
         if (agent || c.agent)
             o = await confinePaths(o, c.workDir);
+        // Agents buy allowed resource URLs only; a row number stays a refused target for them.
+        else if (o.command === 'buy' && isRow(o.target))
+            o = await catalogRow(o, env, d.notify, d.fetch);
         if (c.signer) {
             assertSignerInput(o);
             if (o.recovery && identityJson(identity(o.recovery)) !== identityJson(c.signer.identity))

package/dist/node/agent.js

@@ -47,6 +47,7 @@ export async function agentPolicy(o, env, forced = false) {
             o.command === 'login' ||
             (o.config !== undefined && resolve(o.config) !== resolve(pinned)) ||
             o.stateDir !== undefined ||
+            o.open !== undefined ||
             [
                 o.contractId,
                 o.nearRpc,
@@ -60,7 +61,7 @@ export async function agentPolicy(o, env, forced = false) {
                 o.listingStorage,
                 o.fundAmount,
             ].some((v) => v !== undefined)))
-        throw new AdapterError('agent_policy', 'Agent mode pins deployment, trust, price and state policy; per-call overrides, init and login are refused.', 2);
+        throw new AdapterError('agent_policy', 'Agent mode pins deployment, trust, price and state policy; per-call overrides, buy --open, init and login are refused.', 2);
     return agent;
 }
 export async function savePublicConfig(path, patch) {

package/dist/node/browser-login.js

@@ -54,6 +54,12 @@ export async function startBrowserSession(o) {
     const sent = (p) => p.sending === true ||
         p.action.operation === 'near.signTransaction';
     let pending;
+    const followers = new Set();
+    const advance = (action = null) => {
+        for (const response of followers)
+            response.end(JSON.stringify({ action }));
+        followers.clear();
+    };
     const server = createServer((req, res) => {
         void (async () => {
             const headers = {
@@ -146,9 +152,16 @@ export async function startBrowserSession(o) {
                         armIdle();
                     }
                     notify(APPROVED_LINE);
-                    p.resolve(b.result);
                     complete(200);
-                    send(200, '{}');
+                    if (b.follow === true) {
+                        res.writeHead(200, { ...headers, 'content-type': 'application/json' });
+                        res.flushHeaders();
+                        followers.add(res);
+                        res.on('close', () => followers.delete(res));
+                    }
+                    else
+                        send(200, '{}');
+                    p.resolve(b.result);
                 }
                 catch (error) {
                     clearTimeout(p.timer);
@@ -198,8 +211,19 @@ export async function startBrowserSession(o) {
             pending.reject(new Error('session closed'));
             pending = undefined;
         }
+        const flushed = [...followers].map((response) => new Promise((resolve) => response.end(JSON.stringify({ action: null }), resolve)));
+        followers.clear();
+        const stopped = new Promise((resolve) => server.close(() => resolve()));
+        let flushTimer;
+        await Promise.race([
+            Promise.all(flushed),
+            new Promise((resolve) => {
+                flushTimer = setTimeout(resolve, 1000);
+            }),
+        ]);
+        clearTimeout(flushTimer);
         server.closeAllConnections();
-        await new Promise((resolve) => server.close(() => resolve()));
+        await stopped;
     };
     let timeout;
     const armIdle = () => {
@@ -251,6 +275,7 @@ export async function startBrowserSession(o) {
                 }, action.expiresAt - Date.now()),
             };
             pending = entry;
+            advance(entry.action);
             notify(waitingLine(action.expiresAt - Date.now()));
         }),
     };

package/dist/node/buy-commands.js

@@ -1,5 +1,5 @@
 /** Buyer commands before a purchase exists: `verify` a file and `buy` it. */
-import { mkdir, readdir, readFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { inspect, inspectHeader, MAX_HEADER, parseHeader } from '../envelope/pay2.js';
 import { AnnonError } from '../errors.js';
@@ -17,6 +17,7 @@ import { offer, resourceHeader, response } from './offers.js';
 import { originFor } from './origin.js';
 import { humanPaymentTerms, quotedSource, savedPayment, validatePaymentToken, } from './payment-terms.js';
 import { claimPurchase } from './purchase-guard.js';
+import { rememberPurchase, savedRecordIds } from './purchase-ref.js';
 import { resourceAllowed } from './resources.js';
 /** `verify`: a local file's header and body, or a remote file's header, against its listing. */
 async function verifyFile(ctx) {
@@ -155,13 +156,10 @@ async function buy(ctx, preparedBuy) {
     const guardDir = join(c.stateDir, 'purchase-guards');
     await mkdir(guardDir, { recursive: true, mode: 0o700 });
     const known = [];
-    for (const name of await readdir(storeDir)) {
-        if (!/^[0-9a-f]{64}\.json$/.test(name))
+    for (const id of await savedRecordIds(storeDir)) {
+        if (!isId(id))
             continue;
-        const envelope = JSON.parse(await readFile(join(storeDir, name), 'utf8'));
-        if (!isId(envelope.id))
-            continue;
-        const saved = await sdk.store.load(purchaseKey(envelope.id));
+        const saved = await sdk.store.load(purchaseKey(id));
         if (saved?.purchase.file_id === found.fileId &&
             saved.purchase.contract === c.contractId &&
             saved.terms.network === (saved.purchase.route === 'base-usdc' ? 'eip155:8453' : c.network))
@@ -216,6 +214,7 @@ async function buy(ctx, preparedBuy) {
                 if (renewalError)
                     throw renewalError;
                 await guard.saved(record.id);
+                await rememberPurchase(c, record.id);
             },
             recovery: buyer,
             ...(baseSponsorship ? { baseSponsorship } : {}),
@@ -288,7 +287,9 @@ async function buy(ctx, preparedBuy) {
             ...(source ? { source } : {}),
             next: bought.uncertain
                 ? `The wallet may have sent this payment. Do not pay again. Run annon status ${bought.record.id} until it is accepted.`
-                : 'Fund the deposit if instructed, then check status and open this purchase.',
+                : bought.instructions
+                    ? 'Fund the deposit as instructed, then check status and open this purchase.'
+                    : `Payment sent. Run annon status ${bought.record.id}, then annon open ${bought.record.id} --output <file>.`,
         };
     }
     catch (error) {

package/dist/node/buy-flow.d.ts

@@ -0,0 +1,18 @@
+import type { Input } from './cli.js';
+export interface BuyFollow {
+    notify?: (message: string) => void;
+    /** Pause between status checks; resolves early when `signal` aborts. */
+    wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Aborting stops the waiting only. The saved purchase is left as it is. */
+    signal?: AbortSignal;
+    /** Asked once the purchase is accepted and no `--open` path was given. */
+    savePath?: () => Promise<string | undefined>;
+    onWaiting?: (waiting: boolean) => void;
+}
+type Execute = (input: Input) => Promise<unknown>;
+/**
+ * Runs one command. A `buy` is followed when the caller is a person (`follow`) or asked for
+ * `--open`; a deposit route returns its instructions without waiting.
+ */
+export declare function buyFlow(input: Input, execute: Execute, follow: boolean, o?: BuyFollow): Promise<unknown>;
+export {};

package/dist/node/buy-flow.js

@@ -0,0 +1,89 @@
+import { commonInput } from './cli-flags.js';
+import { publicError } from './errors.js';
+import { newOutput } from './io.js';
+const CHECKS = 60;
+const INTERVAL_MS = 3000;
+const pause = (ms, signal) => new Promise((resolve) => {
+    const done = () => {
+        clearTimeout(timer);
+        resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+});
+/** Status checks until the purchase is accepted, the checks run out or the wait is cancelled. */
+async function accepted(execute, input, id, o) {
+    o.onWaiting?.(true);
+    try {
+        for (let check = 0; check < CHECKS && !o.signal?.aborted; check++) {
+            if (check > 0)
+                await (o.wait ?? pause)(INTERVAL_MS, o.signal);
+            if (o.signal?.aborted)
+                break;
+            const status = (await execute({
+                ...commonInput(input),
+                command: 'status',
+                target: id,
+            }));
+            if (status.state === 'accepted')
+                return true;
+        }
+        return false;
+    }
+    finally {
+        o.onWaiting?.(false);
+    }
+}
+/**
+ * Runs one command. A `buy` is followed when the caller is a person (`follow`) or asked for
+ * `--open`; a deposit route returns its instructions without waiting.
+ */
+export async function buyFlow(input, execute, follow, o = {}) {
+    if (input.command !== 'buy' || (!follow && input.open === undefined))
+        return execute(input);
+    // Refuse a taken output name before any payment step.
+    if (input.open !== undefined)
+        await newOutput(input.open);
+    const bought = (await execute(input));
+    const id = bought.purchaseId;
+    if (typeof id !== 'string' || !['submitted', 'uncertain'].includes(String(bought.state)))
+        return bought;
+    o.notify?.(bought.state === 'uncertain'
+        ? 'The wallet may have sent this payment. Do not pay again. Checking NEAR...'
+        : 'Payment sent. Waiting for NEAR to accept...');
+    // From here the payment exists: a later failure is reported next to the purchase, never instead.
+    const pending = (statusError) => ({
+        ...bought,
+        settlement: 'pending',
+        ...(statusError ? { statusError } : {}),
+        next: `Not accepted yet. Do not pay again. Run annon status ${id} until it is accepted, then annon open ${id} --output <file>.`,
+    });
+    try {
+        if (!(await accepted(execute, input, id, o)))
+            return pending();
+    }
+    catch (error) {
+        return pending(publicError(error));
+    }
+    const settled = { ...bought, state: 'accepted', next: `annon open ${id} --output <file>` };
+    const output = input.open ?? (await o.savePath?.());
+    if (!output)
+        return settled;
+    try {
+        const opened = (await execute({
+            ...commonInput(input),
+            command: 'open',
+            target: id,
+            output,
+        }));
+        return {
+            ...bought,
+            state: 'opened',
+            opened: { output: opened.output, bytes: opened.bytes },
+            next: 'The file is saved.',
+        };
+    }
+    catch (error) {
+        return { ...settled, openError: publicError(error) };
+    }
+}

package/dist/node/cli-flags.d.ts

@@ -0,0 +1,10 @@
+/** The flag tables of the CLI: what every command accepts, for parsing, completion and follow-ups. */
+import type { Command, Input } from './cli.js';
+export declare const common: string[];
+export declare const perCommand: Record<Command, string[]>;
+export declare const camel: (flag: string) => string;
+export declare const commandNames: Command[];
+/** Every flag a command accepts, as typed on the command line. */
+export declare const commandFlags: (command: Command) => string[];
+/** The deployment, wallet and output options of one command, for a follow-up command it starts. */
+export declare const commonInput: (input: Input) => Partial<Input>;

package/dist/node/cli-flags.js

@@ -0,0 +1,68 @@
+export const common = [
+    'no-open',
+    'json',
+    'config',
+    'contract-id',
+    'near-rpc',
+    'base-rpc',
+    'network',
+    'state-dir',
+    'relayer',
+    'trust-contract',
+    'wallet',
+    'evm-key-file',
+    'solana-key-file',
+    'near-key-file',
+    'near-account',
+    'near-public-key',
+    'backup-secret-file',
+];
+export const perCommand = {
+    shops: ['search', 'limit', 'offset'],
+    shop: ['id'],
+    catalog: ['shop', 'search', 'limit', 'offset'],
+    fund: [],
+    budget: [],
+    login: [],
+    init: [
+        'signer',
+        'credential-env',
+        'credential-keychain',
+        'agent',
+        'recovery',
+        'key-env',
+        'keychain-entry',
+        'new-key',
+        'daily-budget',
+    ],
+    share: ['resume', 'price', 'shop', 'title', 'description', 'storage-budget', 'listing-storage'],
+    sell: ['resume', 'price', 'split', 'base', 'moderator', 'output', 'storage-budget'],
+    buy: [
+        'force',
+        'origin',
+        'route',
+        'from-chain',
+        'from-asset',
+        'refund-to',
+        'recovery',
+        'max-price',
+        'moderator',
+        'url',
+        'open',
+        'shop',
+        'search',
+    ],
+    open: ['purchase', 'file', 'url', 'output'],
+    recover: ['recovery', 'purchase'],
+    stop: [],
+    verify: [],
+    status: [],
+};
+export const camel = (flag) => flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+export const commandNames = Object.keys(perCommand);
+/** Every flag a command accepts, as typed on the command line. */
+export const commandFlags = (command) => [...perCommand[command], ...common].map((flag) => `--${flag}`);
+/** The deployment, wallet and output options of one command, for a follow-up command it starts. */
+export const commonInput = (input) => Object.fromEntries(common
+    .map((flag) => [camel(flag), input[camel(flag)]])
+    .filter(([, v]) => v !== undefined));

package/dist/node/cli.d.ts

@@ -1,4 +1,5 @@
 import type { BuyRoute } from '../routes.js';
+import { type BuyFollow } from './buy-flow.js';
 export type Command = 'shops' | 'shop' | 'catalog' | 'fund' | 'budget' | 'share' | 'sell' | 'buy' | 'open' | 'recover' | 'stop' | 'verify' | 'status' | 'login' | 'init';
 export interface Input {
     command: Command;
@@ -55,6 +56,13 @@ export interface Input {
     file?: string;
     url?: string;
     output?: string;
+    /** `buy --open <path>`: wait for acceptance, then write the opened file there. */
+    open?: string;
 }
 export declare function parseCli(argv: string[]): Input;
-export declare function runCli(argv: string[], execute: (input: Input) => Promise<unknown>, write: (text: string) => void): Promise<number>;
+/** How one command line is presented and followed up; the defaults are the script contract. */
+export interface RunOptions extends BuyFollow {
+    /** Readable text in place of the JSON envelope. `--json` always wins. */
+    human?: boolean;
+}
+export declare function runCli(argv: string[], execute: (input: Input) => Promise<unknown>, write: (text: string) => void, options?: RunOptions): Promise<number>;