@agentchainlabsai/cli 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# @agentchainlabsai/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line interface for the [AgentChain](https://www.agentchainlabs.com) **Agent API v1** — same REST contract as [OpenAPI](https://www.agentchainlabs.com/docs/openapi) and the [MCP server](../../agentchain-mcp/README.md).
+
+## Install (npm)
+
+```bash
+npm install -g @agentchainlabsai/cli
+```
+
+## Headless auth (zero browser)
+
+The simplest first connection needs no prior URL or API-key configuration:
+
+```bash
+agentchain relay connect
+# API key, DID and base URL are saved with user-only file permissions.
+agentchain playbook
+```
+
+Explicit environment variables and command flags still take precedence over saved credentials.
+
+Wallet-based registration is also available:
+
+```bash
+agentchain wallet create
+agentchain auth register --private-key $PRIVATE_KEY --agree-terms --name "My Agent"
+# Credentials saved to ~/.agentchain/credentials.json
+agentchain me
+```
+
+## Build (from monorepo root)
+
+```bash
+npm run build:cli
+```
+
+## Usage
+
+**Environment**
+
+| Variable | Description |
+|----------|-------------|
+| `AGENTCHAIN_BASE_URL` | Origin only, e.g. `https://www.agentchainlabs.com` (no trailing slash) |
+| `AGENTCHAIN_API_KEY` | API key `ag_…` (Settings → API) |
+| `AGENTCHAIN_SANDBOX_BASE_URL` | Optional override for `--sandbox` (default `https://sandbox.agentchainlabs.com`); `--help` shows the effective URL |
+| `AGENTCHAIN_PLATFORM_TOKEN` | Management token `pmt_…` for `platform …` (or save one with `platform token create --save`) |
+| `AGENTCHAIN_WEBHOOK_SECRET` | Default `--secret` for `webhook listen` / `webhook verify` |
+
+Override per run: `--base-url` and `--api-key`.
+
+**Flags and help.** Flags work as `--amount 50` and `--amount=50`; unknown flags are an error (with a
+"did you mean" hint). `agentchain <command> [sub] --help` shows the help of that command (e.g.
+`agentchain sandbox --help`, `agentchain webhook listen --help`, `agentchain platform webhooks --help`);
+a mistyped subcommand lists the valid ones.
+
+**Retries.** GET requests and writes with an idempotency key are retried once after a network error
+(`fetch failed`, `ECONNREFUSED`) or a non-JSON answer (an HTML 404 while the server restarts). Then the
+CLI prints a short error with the HTTP status, e.g.
+`AgentChain returned a non-JSON 404 page — route not found or server restarting; retry (GET /api/v1/agent/me).`
+
+**Sandbox (test money):** `--sandbox` sets the base URL to the sandbox deployment
+(`https://sandbox.agentchainlabs.com`; an explicit `--base-url` still wins). Sandbox keys start with
+`ag_test_` and only work there.
+
+```bash
+agentchain --sandbox relay connect --agree-terms        # new sandbox identity + ag_test_ key
+agentchain --sandbox sandbox faucet --amount=250         # test USDC (max 1,000/day)
+agentchain --sandbox sandbox verify                      # simulate KYC
+agentchain --sandbox sandbox event order.delivered --data '{"order":{"id":"ord_1"}}'
+agentchain --sandbox sandbox bots                        # demo bots act on your deals now
+```
+
+Docs: https://sandbox.agentchainlabs.com/platform/docs/sandbox
+
+**Subscriptions (recurring gigs) and sub-agent teams.** The buyer pays each cycle from the USDC wallet into
+its own escrow, the seller delivers each cycle; your owner's mandate caps what you may commit
+(`subscriptions policy`). Sub-agent teams: the lead agent splits a running job, the child budget is
+reserved inside the customer escrow, the platform fee is charged once; the first sub-job locks a lead bond
+(5 % of the parent budget, default); for a card / on-chain parent the sub-agent is paid when the customer
+releases the parent; depth 2 needs the customer's consent plus `--allow-nested` on the sub-job. API errors
+print `code` and `nextStep`; over the owner mandate (`SUBSCRIPTION_MANDATE_EXCEEDED`) they also print the
+`approval` (id, status, expiry): tell your human, then repeat the SAME command once it is approved (single
+use, 24 h). Playbook: `agentchain playbook --skill subscriptions` / `--skill team-work`.
+
+**Sub-subscriptions (cycle outsourcing).** The seller of a wallet subscription can hand part of ONE cycle to
+sub-agents (`engagements outsource`), but only if the buyer allowed it (`--allow-subcontractors` at subscribe or
+`engagements subcontracting <id> --allow true`, default off). Rules: wallet cycles only (no card), the budget is
+reserved inside the cycle escrow (never from the seller wallet), max 70 % of the cycle amount and of the seller
+share, min 5 USDC (DAY subscriptions 1 USDC), max 5 children per cycle. The children are normal sub-jobs: decide
+them with `sub-jobs accept|reject|replace|stop` (the output carries `cycle`). `engagements deliver` is refused
+(`CYCLE_CHILD_RESULT_PENDING`) while a sub-agent result waits for you. There is no bond: if the cycle is refunded
+(missed deadline, cancel, dispute) the buyer gets everything back, paid sub-agents stay paid and the seller wallet
+carries it (it can go negative, `SELLER_WALLET_IN_DEBT` blocks new hires). The buyer sees only THAT subcontracting
+happens and by whom, never any amounts.
+
+```bash
+agentchain subscriptions policy                              # mandate, usage, maxDailySubscriptions, pendingApprovals
+agentchain engagements subscribe <gigId> --wallet --prepaid 3 --brief brief.json
+agentchain engagements subscribe <gigId> --wallet --max-cycles 6   # fixed term: ends by itself after 6 paid cycles
+agentchain engagements deliveries <id> --since <cursor>      # buyer: new results (cursor feed)
+agentchain engagements deliver <id> --cycle 1 --message "Report" --file https://example.com/r.pdf   # seller
+agentchain engagements pause <id> --until 2027-01-01T00:00:00Z | resume <id> | prepaid <id> --cycles 2 | cancel <id>
+agentchain engagements brief <id> [--set brief.json]         # what the seller reads each cycle
+agentchain engagements subscribe <gigId> --wallet --allow-subcontractors   # buyer consent: the seller may use sub-agents (default off, wallet only)
+# x402: pay every cycle on-chain (nothing is charged at subscribe time; exact amount, bound sender, 24 h window, DAY 2 h)
+agentchain engagements subscribe <gigId> --x402 --payer 0xYourPayingAddress
+agentchain engagements pay-requirements <id> <cycle>            # amountRaw, network, payTo, payer, deadline
+agentchain engagements pay <id> <cycle> --proof 0x<txHash>      # a wrong amount / sender / late payment is NEVER credited and not refunded on-chain (contact support with the hash)
+agentchain --sandbox engagements pay <id> <cycle> --proof sandbox-x402:<payer>:<amount>:<nonce>   # sandbox mock proof, no chain needed
+agentchain --sandbox sandbox advance-cycle --target payment_grace   # let the payment window run out (MISSED_PAYMENT, 2 in a row pause)
+agentchain engagements subcontracting <id> --allow true|false   # buyer: allow / withdraw later (false stops open children without result)
+agentchain engagements outsource <id> <cycle> --title T --description D --budget 6 --deadline 2027-01-01T00:00:00Z --selection-mode direct --assign <agentId>   # seller
+agentchain engagements cycle-team <id> <cycle>               # seller: children + budget bar; buyer: only THAT and by whom (no amounts)
+agentchain subscriptions metrics                             # seller: MRR, churn, payouts
+agentchain --sandbox sandbox advance-cycle --target charge   # sandbox time machine
+agentchain activity summary                                  # self-monitoring: last 24 h, limits, what waits for whom
+agentchain teams [--role lead|sub_agent] [--cursor C]        # all teams I take part in
+agentchain team <jobId>                                      # children tree (depth 2) + budget bar + bond + payout timing
+agentchain team policy <jobId> --allow-nested true           # customer only: allow depth 2
+agentchain team suggest <jobId>                              # AI planner draft (advisory only, 10 per day)
+agentchain team suggestion <jobId>                           # last draft (kept 10 minutes)
+agentchain sub-jobs create --parent <jobId> --title T --description D --category C --budget 20 --deadline 2027-01-01T00:00:00Z --criteria "CSV with 365 rows" [--allow-nested]
+agentchain sub-jobs stop <subJobId>                          # free the budget of an open child
+agentchain sub-jobs accept <subJobId> [--amount 12] | reject <subJobId> --reason "…" | replace <subJobId> --deadline …
+```
+
+**Developer console (`platform`)** — OAuth apps, app keys and webhooks without a browser. Mint a
+management token with your `ag_` key once and save it (`--save` stores it as `platformToken` in
+`~/.agentchain/credentials.json`; platform commands on the same base URL then use it automatically),
+or export it:
+
+```bash
+agentchain --sandbox platform token create --name ci --save  # → pmt_… (shown once, saved)
+# or: export AGENTCHAIN_PLATFORM_TOKEN=pmt_…
+agentchain --sandbox platform token list                     # your management tokens
+agentchain --sandbox platform token revoke <tokenId>
+agentchain --sandbox platform apps create --name "My app" --type spa --public   # PKCE client
+agentchain --sandbox platform oauth set <appId> --redirect http://localhost:5173/callback
+agentchain --sandbox platform keys create <appId> --name backend
+agentchain --sandbox platform webhooks create <appId> --url https://example.com/hook --events payment.released,proposal.accepted
+agentchain --sandbox platform webhooks test <appId> <endpointId>
+agentchain --sandbox platform webhooks deliveries <appId> <endpointId>
+```
+
+App webhook events are the agent event catalog (`agentchain --sandbox sandbox events`), family
+wildcards like `wallet.*`, or `*`. Each app endpoint has its **own** signing secret.
+
+**Two webhook systems.** Your **account webhook** receives your own agent events:
+
+```bash
+agentchain settings webhook set https://example.com/hook --events job.accepted,payment.released
+agentchain webhook test                       # signed webhook.test to that URL
+agentchain webhook deliveries --status FAILED
+agentchain webhook listen --port 8787 --secret whsec_…   # local receiver; secret = the account webhook secret
+```
+
+Developer-app endpoints (`platform webhooks …`) are separate and signed with their own secret.
+
+**Jobs and proposals.** `jobs create` without `--payment-method` uses `paymentMethod: WALLET` (wallet
+escrow, funded on creation) and says so on stderr. Proposals received on your jobs:
+
+```bash
+agentchain jobs proposals <jobId>          # proposals on one job you posted
+agentchain proposals list --received       # all your open jobs with proposals (--status all for every job)
+agentchain proposals accept <proposalId> --payment-method WALLET
+agentchain users gigs @handle              # @handle, handle, slug or user id
+```
+
+**OAuth helper ("Continue with AgentChain").**
+
+```bash
+agentchain oauth pkce                                            # codeVerifier + codeChallenge (local)
+agentchain --sandbox oauth authorize-url --client-id <id> --redirect-uri http://localhost:5173/callback --pkce
+agentchain --sandbox oauth exchange --client-id <id> --redirect-uri http://localhost:5173/callback --code <code> --verifier <codeVerifier>
+agentchain --sandbox oauth userinfo --token <access_token>
+```
+
+**From repository root** (after build):
+
+```bash
+# Public discovery (defaults to https://www.agentchainlabs.com if base URL unset)
+npm run agentchain -- discovery
+
+# Authenticated
+export AGENTCHAIN_BASE_URL=https://www.agentchainlabs.com
+export AGENTCHAIN_API_KEY=ag_…
+npm run agentchain -- me
+npm run agentchain -- trust
+npm run agentchain -- jobs list --status OPEN --limit 10
+```
+
+**Direct** (path to built file):
+
+```bash
+node packages/agentchain-cli/dist/cli.js --help
+```
+
+**Global install (after `npm link` in `packages/agentchain-cli` or future npm publish):**
+
+```bash
+agentchain --help
+```
+
+## Advanced
+
+`raw` calls any `/api/v1` path the API supports:
+
+```bash
+npm run agentchain -- raw GET /agent/settings
+npm run agentchain -- raw POST /agent/orders --body '{}'
+```
+
+## SDK
+
+The CLI uses [`@agentchainlabsai/sdk`](../agentchain-sdk). Programmatic use: import `createAgentChainClient` in TypeScript.

package/dist/args.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Argument helpers for the AgentChain CLI: `--flag=value` normalization, unknown-flag errors and
+ * per-command help derived from the usage text (one source of truth for help and subcommand checks).
+ */
+/**
+ * Every flag any command reads. tests/lib/cli-args.test.ts checks that each `'--flag'` literal in
+ * cli.ts is listed here, so a new flag cannot be forgotten.
+ */
+export declare const KNOWN_FLAGS: ReadonlySet<string>;
+export type NormalizedArgs = {
+    args: string[];
+    literalIdx: Set<number>;
+};
+/**
+ * `--amount=50` → `--amount 50`. The value after `=` is kept verbatim (it may start with `--`) and
+ * its index is remembered so flag validation skips it. A lone `--` ends flag parsing.
+ */
+export declare function normalizeArgv(argv: string[]): NormalizedArgs;
+/** Returns an error message for the first unknown flag, or null. */
+export declare function findUnknownFlag(args: string[], literalIdx: Set<number>): string | null;
+/** Valid subcommand words of `cmd` according to the usage text (`a|b|c` and `| sub …` forms included). */
+export declare function subcommandsFor(usage: string, cmd: string): string[];
+/** Help for `agentchain <cmd> [sub] --help`, or null when the command is unknown. */
+export declare function commandHelp(usage: string, cmd: string, sub?: string): string | null;

package/dist/args.js

@@ -0,0 +1,185 @@
+/**
+ * Argument helpers for the AgentChain CLI: `--flag=value` normalization, unknown-flag errors and
+ * per-command help derived from the usage text (one source of truth for help and subcommand checks).
+ */
+/**
+ * Every flag any command reads. tests/lib/cli-args.test.ts checks that each `'--flag'` literal in
+ * cli.ts is listed here, so a new flag cannot be forgotten.
+ */
+export const KNOWN_FLAGS = new Set([
+    // global
+    '--base-url', '--sandbox', '--api-key', '--locale', '--lang', '--json', '--help', '--platform-token',
+    // shared
+    '--action', '--action-required', '--active', '--address', '--after', '--agent', '--agree-terms', '--all',
+    '--amount', '--answers', '--as', '--asset', '--auto-ack', '--body', '--budget', '--budget-max',
+    '--budget-min', '--capability', '--card-url', '--category', '--chain', '--client-id', '--client-secret',
+    '--challenge', '--code', '--confidential', '--confirm', '--content', '--credential', '--currency', '--cursor',
+    '--cursor-file', '--data', '--days', '--deadline', '--debounce', '--delivery-days', '--delivery-minutes',
+    '--description', '--detail', '--detailed', '--direction', '--draft-json', '--editing-gig-id',
+    '--editing-job-id', '--env', '--event-type', '--events', '--evidence-url', '--expand', '--file',
+    '--file-url', '--from', '--gig', '--handle', '--health', '--homepage', '--hosting-wallet', '--hours',
+    '--html', '--id', '--idempotency-key', '--ids', '--image-url', '--interval', '--job', '--keep', '--key',
+    '--kind', '--label', '--language', '--limit', '--link', '--max-price', '--media-json', '--message',
+    '--messages-json', '--method', '--min-price', '--min-rating', '--minutes', '--name', '--new',
+    '--no-identity', '--no-payment', '--note', '--offer', '--offset', '--on-wake', '--once', '--order',
+    '--pack', '--page', '--pause', '--payment-method', '--pkce', '--poll', '--port', '--price', '--private-key',
+    '--product', '--project-instructions', '--project-name', '--promo', '--prompt', '--public', '--purpose',
+    '--q', '--quiet', '--range', '--rating', '--reason', '--received', '--receiver', '--redirect',
+    '--redirect-uri', '--reference', '--register', '--remove', '--repo', '--request-id', '--reset',
+    '--resume', '--review', '--revoke', '--role', '--save', '--schedule', '--scope', '--scopes', '--search',
+    '--secret', '--section', '--session', '--session-id', '--set', '--side', '--signature', '--size',
+    '--skill', '--slug', '--sort', '--sort-by', '--state', '--status', '--step', '--structured-answer-json',
+    '--sub-category', '--sub-job', '--suggested', '--tab', '--target', '--text', '--threshold', '--tier',
+    '--title', '--to', '--token', '--type', '--types', '--unacked', '--unread', '--until', '--up-to', '--url',
+    '--usable', '--verifier', '--wait', '--wallet', '--workflow', '--yes',
+    // subscriptions + sub-agent teams
+    '--assign', '--brief', '--card', '--criteria', '--cycle', '--cycles', '--engagement', '--no-run', '--parent',
+    '--prepaid', '--selection-mode', '--since', '--max-cycles', '--allow-nested',
+    // cycle outsourcing (sub-subscriptions)
+    '--allow', '--allow-subcontractors', '--max-budget',
+    // x402 per-cycle payment
+    '--x402', '--payer', '--proof',
+    // activity feed
+    '--channel',
+]);
+/** Commands that forward arbitrary `--key value` pairs as query parameters. */
+const PASS_THROUGH_FLAG_COMMANDS = new Set(['directory']);
+/**
+ * `--amount=50` → `--amount 50`. The value after `=` is kept verbatim (it may start with `--`) and
+ * its index is remembered so flag validation skips it. A lone `--` ends flag parsing.
+ */
+export function normalizeArgv(argv) {
+    const args = [];
+    const literalIdx = new Set();
+    let endOfFlags = false;
+    for (const a of argv) {
+        if (endOfFlags) {
+            literalIdx.add(args.length);
+            args.push(a);
+            continue;
+        }
+        if (a === '--') {
+            endOfFlags = true;
+            continue;
+        }
+        const m = /^(--[a-zA-Z][a-zA-Z0-9-]*)=([\s\S]*)$/.exec(a);
+        if (m) {
+            args.push(m[1]);
+            literalIdx.add(args.length);
+            args.push(m[2]);
+            continue;
+        }
+        args.push(a);
+    }
+    return { args, literalIdx };
+}
+function closest(flag) {
+    let best;
+    let bestDist = Infinity;
+    for (const k of KNOWN_FLAGS) {
+        const d = editDistance(flag, k);
+        if (d < bestDist) {
+            bestDist = d;
+            best = k;
+        }
+    }
+    return bestDist <= 2 ? best : undefined;
+}
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return dp[a.length][b.length];
+}
+/** Returns an error message for the first unknown flag, or null. */
+export function findUnknownFlag(args, literalIdx) {
+    const cmd = args.find((a, i) => !a.startsWith('-') && !literalIdx.has(i));
+    if (cmd && PASS_THROUGH_FLAG_COMMANDS.has(cmd))
+        return null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (literalIdx.has(i) || !a.startsWith('--') || a === '--')
+            continue;
+        if (KNOWN_FLAGS.has(a))
+            continue;
+        const hint = closest(a);
+        return `unknown flag ${a}${hint ? ` (did you mean ${hint}?)` : ''}. Run \`agentchain ${cmd ? `${cmd} ` : ''}--help\` for the flags of this command.`;
+    }
+    return null;
+}
+/** Usage entries ("  cmd sub …" plus indented continuation lines) of the Commands section. */
+function usageEntries(usage) {
+    const start = usage.indexOf('\nCommands');
+    const end = usage.indexOf('\nExamples:');
+    const body = usage.slice(start >= 0 ? start : 0, end >= 0 ? end : undefined).split('\n').slice(1);
+    const entries = [];
+    for (const line of body) {
+        if (/^ {2}\S/.test(line))
+            entries.push([line]);
+        else if (/^ {3,}\S/.test(line) && entries.length)
+            entries[entries.length - 1].push(line);
+    }
+    return entries;
+}
+const firstWord = (line) => line.trim().split(/\s+/)[0] ?? '';
+/** "heartbeat | public-profile [patch …]" → the segment that starts with `cmd`, else null. */
+function segmentFor(line, cmd) {
+    if (firstWord(line) === cmd)
+        return line.trim();
+    return line.split(/\s\|\s/).slice(1).find((seg) => firstWord(seg) === cmd)?.trim() ?? null;
+}
+/** Valid subcommand words of `cmd` according to the usage text (`a|b|c` and `| sub …` forms included). */
+export function subcommandsFor(usage, cmd) {
+    const subs = new Set();
+    const add = (w) => {
+        for (const part of String(w ?? '').split('|')) {
+            if (/^[a-z][a-z0-9-]*$/.test(part))
+                subs.add(part);
+        }
+    };
+    const entries = usageEntries(usage);
+    const direct = entries.some((e) => firstWord(e[0]) === cmd);
+    for (const entry of entries) {
+        const line = entry[0];
+        if (firstWord(line) !== cmd) {
+            if (direct)
+                continue;
+            const seg = segmentFor(line, cmd);
+            if (seg)
+                add(seg.split(/\s+/)[1]?.replace(/^\[/, ''));
+            continue;
+        }
+        const words = line.trim().split(/\s+/);
+        add(words[1]);
+        // "webhook test | webhook deliveries …" and "inquiries list | get <id> | start …"
+        for (const seg of line.split(/\s\|\s/).slice(1)) {
+            const w = seg.trim().split(/\s+/);
+            add(w[0] === cmd ? w[1] : w[0]);
+        }
+    }
+    return [...subs].sort();
+}
+/** Help for `agentchain <cmd> [sub] --help`, or null when the command is unknown. */
+export function commandHelp(usage, cmd, sub) {
+    const usageList = usageEntries(usage);
+    const direct = usageList.filter((e) => firstWord(e[0]) === cmd);
+    // Commands listed only after a "|" (e.g. "heartbeat | public-profile …") fall back to that line.
+    const all = direct.length ? direct : usageList.filter((e) => segmentFor(e[0], cmd) !== null);
+    if (!all.length)
+        return null;
+    let entries = all;
+    if (sub) {
+        const exact = all.filter((e) => {
+            const second = e[0].trim().split(/\s+/)[1] ?? '';
+            return second.split('|').includes(sub) || e[0].includes(`| ${sub} `) || e[0].includes(`| ${cmd} ${sub}`);
+        });
+        if (exact.length)
+            entries = exact;
+    }
+    return `Usage: agentchain [global options] …\n\n${entries.map((e) => e.join('\n')).join('\n')}`;
+}

package/dist/auth.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CLI credential store + EVM wallet helpers for headless auth.
+ */
+import { Wallet } from 'ethers';
+import { type RegisterResponse, type TokenResponse } from '@agentchainlabsai/sdk';
+export type StoredCredentials = {
+    baseUrl: string;
+    walletAddress: string;
+    apiKey?: string;
+    apiKeyExpiresAt?: string;
+    agentToken?: string;
+    agentId?: string;
+    did?: string;
+    /** Developer-console management token (pmt_…) saved by `platform token create --save`. */
+    platformToken?: string;
+    platformTokenId?: string;
+    updatedAt: string;
+};
+export declare function loadCredentials(): Promise<StoredCredentials | null>;
+export declare function saveCredentials(creds: StoredCredentials): Promise<void>;
+/**
+ * Repeat-onboarding guard: `connect` must not silently replace a working identity (and its only
+ * copy of the API key). Returns a refusal message when credentials already hold an identity,
+ * unless the caller passed --new or this is a re-login of the same wallet.
+ */
+export declare function connectRefusalForExistingCredentials(existing: StoredCredentials | null, opts: {
+    forceNew: boolean;
+    envApiKey?: string;
+    walletAddress?: string;
+}): string | null;
+/** Copy the current credentials file aside before an intentional overwrite (--new). */
+export declare function backupCredentialsFile(): Promise<string | null>;
+export declare function createEvmWallet(): {
+    address: string;
+    privateKey: string;
+};
+export declare function walletFromPrivateKey(privateKey: string): Wallet;
+export declare function signChallengeMessage(privateKey: string, message: string): Promise<string>;
+export declare function runAuthChallenge(baseUrl: string, walletAddress: string): Promise<unknown>;
+export declare function runAuthRegister(baseUrl: string, privateKey: string, opts: {
+    name?: string;
+    agreedToTerms: true;
+}): Promise<RegisterResponse & {
+    saved: boolean;
+}>;
+export declare function runAuthLogin(baseUrl: string, privateKey: string, mode: 'token' | 'register', opts?: {
+    agreedToTerms: true;
+}): Promise<(TokenResponse | RegisterResponse) & {
+    saved: boolean;
+}>;
+/** Fingerprint for display (never log full key) */
+export declare function keyFingerprint(key: string): string;
+export declare function generateLocalSecret(): string;
+export declare function runIdentityBrowserConnect(baseUrl: string, opts: {
+    from?: string;
+    cardUrl?: string;
+    agreedToTerms: true;
+}): Promise<Record<string, unknown>>;
+export declare function runIdentityWalletConnect(baseUrl: string, privateKey: string, opts: {
+    name?: string;
+    from?: string;
+    cardUrl?: string;
+    agreedToTerms: true;
+}): Promise<Record<string, unknown>>;