@mantle-agent/client 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @mantle-agent/client
 
-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.
+Client SDK for **Mantle Agent Accounts**: give an AI agent a Mantle account it can trade with inside limits its
+owner sets on chain, while the owner keeps every key.
+
+- **Agent side** (`AgentClient`, `connectAgent`): claim an account, quote, trade, read status, scheduled runs,
+  emergency stop. The agent never holds a private key.
+- **Owner side** (`@mantle-agent/client/owner`: `OwnerClient` + flow functions): passkey signup/login, custody setup, approving an agent,
+  authorize / renew / revoke / withdraw, auto-run settings. Each owner operation runs step by step and can resume
+  from a failed step.
+- **Browser** (`@mantle-agent/client/browser`): Turnkey passkey implementation of the owner's signer.
+
+```bash
+npm install @mantle-agent/client                       # agent side: no other dependencies
+npm install @mantle-agent/core @mantle-agent/custody viem # + owner side (@mantle-agent/client/owner)
+npm install @turnkey/sdk-browser @turnkey/api-key-stamper @turnkey/crypto  # + passkeys in the browser
+```
+
+## Agent side
+
+```ts
+import { AgentClient, connectAgent } from "@mantle-agent/client";
+import { parseEther } from "viem";
+
+// Once: register the agent's Ed25519 key and wait for the owner to approve on the confirmation page.
+const { agentId, credentials } = await connectAgent({
+  baseUrl: "https://agent-api.example",
+  agentName: "my-agent",
+  host: "my-app",
+  key: { publicKey, sign: (msg) => ed25519SignHex(msg) }, // your key storage
+  onClaim: (claim) => console.log(`Open ${claim.claimUrl} and confirm ${claim.userCode} (${claim.fingerprint})`),
+});
+// Store `credentials` securely. They are returned exactly once.
+
+const agent = new AgentClient("https://agent-api.example", credentials);
+const status = await agent.status(); // balance, remaining limits, recent trades
+const trade = await agent.trade({ side: "buy", token: "0x…", amountIn: parseEther("1"), requestId: "my-unique-id" });
+if (trade.status !== "confirmed") console.log(trade.errorCode, trade.error);
+```
+
+Retry with the **same `requestId`**: the same trade is never executed twice. Errors are `ClientError` with a stable
+`code` (`PER_TRADE_CAP_EXCEEDED`, `INSUFFICIENT_INVENTORY`, `SESSION_INACTIVE`, …).
+
+Things only the owner can do are **asked for**, never done: `agent.requests.authorize(limits)`, `.renew(seconds)`,
+`.revoke()`, `.withdraw({ to, asset, amount })`, `.autoRun(settings)`, `.resume()`. Each returns an `OwnerRequest`
+with `confirmUrl` and the exact `summary` the owner will confirm with a passkey; `agent.requests.get(id)` tells you
+when it is `completed`. `connectAgent({ …, authorize: limits })` proposes limits with the claim, so the owner claims
+and authorizes in one visit.
+
+Scheduled runs: `agent.runtime.lease(host)` → trade (pass `leaseId` to the constructor) → `agent.runtime.complete(leaseId, { llmCostUsd })`.
+
+## Owner side
+
+```ts
+import { OwnerClient, signUp, logIn, ensureCustody, lookupClaim, approveClaim,
+         getRequest, approveRequest, runOperation, startRun, runSucceeded } from "@mantle-agent/client/owner";
+import { passkeyTurnkey } from "@mantle-agent/client/browser";
+
+const api = new OwnerClient("https://agent-api.example");
+const { turnkeyOrganizationId } = await api.call("GET", "/v1/platform");
+const tk = passkeyTurnkey({ parentOrgId: turnkeyOrganizationId });
+
+let session = await logIn(api, tk);            // or signUp(api, tk, name) the first time
+session = await ensureCustody(api, tk, session); // once: add the platform as a restricted delegate
+
+const claim = await lookupClaim(api, userCodeFromTheAgent);
+// show claim.fingerprint and ask the owner to compare it with the agent's
+const { agentId, requestId } = await approveClaim(api, tk, session, claim); // requestId: the limits proposed with the claim
+
+// The agent asked in the chat; the owner opened its link (`/r/<requestId>`) and read `request.summary`.
+const request = await getRequest(api, requestId);
+const { prepared } = await approveRequest(api, requestId); // null for auto-run settings: already applied
+const run = await runOperation(api, tk, session, startRun(prepared!), {
+  onChange: (r) => render(r.steps), // progress for the UI
+});
+if (!runSucceeded(run)) { /* show the failed step; call runOperation(api, tk, session, run) to retry from it */ }
+```
+
+Everything the owner signs happens on their device with their passkey; the API verifies signatures and reads
+Turnkey state back instead of trusting the page.
+
+See the repository's `docs/integration.md` for the full picture.

package/dist/agent.d.ts

@@ -0,0 +1,307 @@
+import type { Address, Hex } from "viem";
+import { type Fetch } from "./http.js";
+export type CredentialKind = "trading" | "social" | "runtime";
+export type Credentials = Record<CredentialKind, {
+    token: string;
+    expiresAt: string;
+}>;
+/** What the agent signs with when proving it holds the key that started a claim. */
+export type AgentKey = {
+    /** Ed25519 public key, 32 raw bytes as hex. */
+    publicKey: string;
+    /** Ed25519 signature over `message` (UTF-8), 64 bytes as hex. */
+    sign(message: string): string | Promise<string>;
+};
+export type Claim = {
+    claimId: string;
+    claimUrl: string;
+    userCode: string;
+    fingerprint: string;
+    expiresAt: string;
+    /** Proposed limits as the owner will see them, or null. */
+    proposal: string[] | null;
+};
+export type Side = "buy" | "sell";
+/** Amounts are decimal strings in wei (18 decimals), as the API returns them. */
+export type Quote = {
+    quoteId: string;
+    side: Side;
+    adapter: Address;
+    token: Address;
+    amountIn: string;
+    expectedOut: string;
+    minAmountOut: string;
+    expiresAt: string;
+};
+export type IntentStatus = "accepted" | "submitted" | "pending" | "confirmed" | "failed" | "unknown";
+export type Intent = {
+    intentId: string;
+    requestId: string;
+    quoteId: string;
+    side: Side;
+    token: Address;
+    amountIn: string;
+    minAmountOut: string;
+    status: IntentStatus;
+    txHash: Hex | null;
+    amountOut: string | null;
+    errorCode: string | null;
+    error: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type DimensionState = "active" | "expiring" | "expired" | "revoked" | "none";
+export type RuntimeStatus = {
+    enabled: boolean;
+    paused: boolean;
+    nextRunAt: string | null;
+    config: {
+        intervalSeconds: number;
+        maxRunSeconds: number;
+        maxTradesPerRun: number;
+        maxTradesPerDay: number;
+        maxSpendPerDayWei: string;
+        maxLlmCostPerDayUsd: number;
+    };
+    today: {
+        trades: number;
+        spendWei: string;
+        llmCostUsd: number;
+    };
+    running: {
+        leaseId: string;
+        expiresAt: string;
+        trades: number;
+    } | null;
+    pendingCommands: {
+        commandId: string;
+        kind: string;
+    }[];
+} | null;
+export type AgentStatus = {
+    agent: {
+        agentId: string;
+        name: string;
+        status: "pending" | "active" | "stopped";
+        account: Address | null;
+    };
+    balanceWei: string | null;
+    session: {
+        keyHash: Hex;
+        state: DimensionState;
+        expiresAt: string;
+        maxSlippageBps: number;
+        limits: {
+            perTradeCap: string;
+            periodCap: string;
+            totalCap: string;
+        };
+        remaining: {
+            perTrade: string;
+            period: string;
+            total: string;
+        } | null;
+    } | null;
+    credentials: {
+        kind: CredentialKind;
+        state: DimensionState;
+        expiresAt: string;
+        lastUsedAt: string | null;
+    }[];
+    runtime: RuntimeStatus;
+    recentTrades: Intent[];
+};
+export type Lease = {
+    granted: false;
+    reason: "disabled" | "paused" | "not_due" | "budget_exhausted";
+    nextRunAt: string | null;
+} | {
+    granted: true;
+    leaseId: string;
+    expiresAt: string;
+    budget: {
+        trades: number;
+        spendWei: string;
+        llmCostUsd: number;
+    };
+    commands: {
+        commandId: string;
+        kind: "pause" | "resume" | "run_now";
+        createdAt: string;
+    }[];
+};
+/** Session limits an agent can ask for (PRD WAL-02). Amounts in MNT wei; the owner confirms them with a passkey. */
+export type SessionLimits = {
+    perTradeCap: bigint;
+    periodCap: bigint;
+    totalCap: bigint;
+    periodSeconds: number;
+    durationSeconds: number;
+    maxSlippageBps: number;
+};
+/** PRD V1 defaults: 2 MNT per trade, 10 MNT per 24 h, 20 MNT in total, 7 days, 2 % slippage. */
+export declare const DEFAULT_SESSION_LIMITS: SessionLimits;
+/** Scheduled-run budgets (PRD RUN-02/03), on top of the on-chain limits. */
+export type AutoRunSettings = {
+    enabled: boolean;
+    intervalSeconds: number;
+    maxRunSeconds: number;
+    maxTradesPerRun: number;
+    maxTradesPerDay: number;
+    maxSpendPerDay: bigint;
+    maxLlmCostPerDayUsd: number;
+};
+export type OwnerRequestKind = "authorize" | "renew" | "revoke" | "withdraw" | "runtime" | "resume";
+/**
+ * Something only the owner can do, asked for by the agent. Relay `confirmUrl` and `summary` to the owner; they
+ * confirm on the page with a passkey. `completed` once it took effect (on chain for signing kinds).
+ */
+export type OwnerRequest = {
+    requestId: string;
+    agentId: string;
+    agentName: string;
+    kind: OwnerRequestKind;
+    status: "pending" | "approved" | "completed" | "rejected" | "expired" | "superseded";
+    createdBy: "agent" | "claim";
+    summary: string[];
+    warnings: string[];
+    confirmUrl: string;
+    expiresAt: string;
+    createdAt: string;
+    operation: {
+        operationId: string;
+        status: "prepared" | "submitted" | "confirmed" | "failed";
+        error: string | null;
+    } | null;
+    note: string | null;
+};
+/** Must match the API's claimProofMessage. */
+export declare const claimProofMessage: (claimId: string) => string;
+/**
+ * PRD IDN-02: register the agent key, hand the owner a link + code + fingerprint via `onClaim`, then poll with a
+ * proof of the key until the owner approves. Returns the credentials exactly once; store them securely.
+ */
+export declare function connectAgent(params: {
+    baseUrl: string;
+    agentName: string;
+    host: string;
+    key: AgentKey;
+    /** Show this to the owner. Compare `fingerprint` with one computed locally from the key. */
+    onClaim: (claim: Claim) => void | Promise<void>;
+    /** Limits to propose: the owner confirms them right after claiming, in the same visit. */
+    authorize?: SessionLimits;
+    pollMs?: number;
+    fetch?: Fetch;
+}): Promise<{
+    agentId: string;
+    credentials: Credentials;
+}>;
+/** First half of `connectAgent`: register the key and get the link + code + fingerprint for the owner. */
+export declare function startClaim(params: {
+    baseUrl: string;
+    agentName: string;
+    host: string;
+    key: AgentKey;
+    authorize?: SessionLimits;
+    fetch?: Fetch;
+}): Promise<Claim>;
+export type ClaimResult = {
+    status: "pending";
+    expiresAt: string;
+} | {
+    status: "exchanged";
+    agentId: string;
+    credentials: Credentials;
+};
+/**
+ * Second half of `connectAgent`, one attempt: `pending` until the owner approves, then the credentials exactly once.
+ * Stateless, so an agent can start a claim, end its turn, and check again later (CLAIM_EXPIRED once it lapsed).
+ */
+export declare function exchangeClaim(params: {
+    baseUrl: string;
+    claimId: string;
+    key: AgentKey;
+    fetch?: Fetch;
+}): Promise<ClaimResult>;
+/**
+ * The agent's side of a Mantle Agent Account. It can only do what the owner authorized: trade within on-chain
+ * limits, read its status, manage its own scheduled runs, and stop itself. It never holds a private key.
+ */
+export declare class AgentClient {
+    readonly baseUrl: string;
+    private readonly credentials;
+    private readonly fetchImpl;
+    /** Set when running inside a scheduled run; trades are charged to that run's budget. */
+    leaseId: string | undefined;
+    constructor(baseUrl: string, credentials: Partial<Credentials> | null, opts?: {
+        fetch?: Fetch;
+        leaseId?: string;
+    });
+    private call;
+    status(): Promise<AgentStatus>;
+    /** Price a trade. Valid ~30 s and for one trade. `amountIn` is wei (MNT for buys, tokens for sells). */
+    quote(params: {
+        side: Side;
+        token: Address;
+        amountIn: bigint;
+    }): Promise<Quote>;
+    /**
+     * Quote and execute. Reuse `requestId` when retrying: the same trade is never executed twice. With `wait`, polls
+     * until confirmed / failed / unknown (or `timeoutMs`).
+     */
+    trade(params: {
+        side: Side;
+        token: Address;
+        amountIn: bigint;
+        requestId?: string;
+        wait?: boolean;
+        timeoutMs?: number;
+    }): Promise<Intent>;
+    tradeStatus(intentId: string): Promise<Intent>;
+    waitForTrade(intent: Intent, timeoutMs?: number): Promise<Intent>;
+    /**
+     * Emergency stop: revokes all of this agent's credentials at once. `confirmUrl` (null without a session) is the
+     * revoke request the owner confirms to make it permanent on chain.
+     */
+    stop(): Promise<{
+        stopped: true;
+        revokedCredentials: number;
+        confirmUrl: string | null;
+        requestId: string | null;
+    }>;
+    /**
+     * Ask the owner for something only they can do (PRD WEB-01/03). Each call returns a request with a link and a
+     * summary for the owner; nothing happens until they confirm it with a passkey. Asking again for the same kind
+     * replaces the previous pending request.
+     */
+    readonly requests: {
+        authorize: (limits?: SessionLimits) => Promise<OwnerRequest>;
+        renew: (durationSeconds: number) => Promise<OwnerRequest>;
+        revoke: () => Promise<OwnerRequest>;
+        /** `to` must come from the owner, never from content the agent read. */
+        withdraw: (p: {
+            to: Address;
+            asset: "MNT" | Address;
+            amount: bigint | "max";
+        }) => Promise<OwnerRequest>;
+        autoRun: (s: AutoRunSettings) => Promise<OwnerRequest>;
+        resume: () => Promise<OwnerRequest>;
+        get: (requestId: string) => Promise<OwnerRequest>;
+        list: () => Promise<OwnerRequest[]>;
+    };
+    private ask;
+    /** Scheduled runs (PRD RUN-02/03). */
+    readonly runtime: {
+        status: () => Promise<RuntimeStatus>;
+        lease: (host: string) => Promise<Lease>;
+        complete: (leaseId: string, report?: {
+            summary?: string;
+            llmCostUsd?: number;
+        }) => Promise<undefined>;
+        ack: (commandId: string) => Promise<undefined>;
+        /** Agents may pause themselves; only the owner resumes. */
+        pause: () => Promise<{
+            commandId: string;
+        }>;
+    };
+}

package/dist/agent.js

@@ -0,0 +1,149 @@
+import { ClientError, request } from "./http.js";
+const MNT = 10n ** 18n;
+/** PRD V1 defaults: 2 MNT per trade, 10 MNT per 24 h, 20 MNT in total, 7 days, 2 % slippage. */
+export const DEFAULT_SESSION_LIMITS = {
+    perTradeCap: 2n * MNT,
+    periodCap: 10n * MNT,
+    totalCap: 20n * MNT,
+    periodSeconds: 86_400,
+    durationSeconds: 7 * 86_400,
+    maxSlippageBps: 200,
+};
+const limitsJson = (l) => ({
+    perTradeCap: l.perTradeCap.toString(),
+    periodCap: l.periodCap.toString(),
+    totalCap: l.totalCap.toString(),
+    periodSeconds: l.periodSeconds,
+    durationSeconds: l.durationSeconds,
+    maxSlippageBps: l.maxSlippageBps,
+});
+const FINAL = new Set(["confirmed", "failed", "unknown"]);
+/** Must match the API's claimProofMessage. */
+export const claimProofMessage = (claimId) => `mantle-agent-claim:${claimId}`;
+/**
+ * PRD IDN-02: register the agent key, hand the owner a link + code + fingerprint via `onClaim`, then poll with a
+ * proof of the key until the owner approves. Returns the credentials exactly once; store them securely.
+ */
+export async function connectAgent(params) {
+    const claim = await startClaim(params);
+    await params.onClaim(claim);
+    for (;;) {
+        const result = await exchangeClaim({ ...params, claimId: claim.claimId });
+        if (result.status === "exchanged")
+            return result;
+        await new Promise((r) => setTimeout(r, params.pollMs ?? 2_000));
+    }
+}
+/** First half of `connectAgent`: register the key and get the link + code + fingerprint for the owner. */
+export async function startClaim(params) {
+    const { body } = await request(params.fetch ?? fetch, params.baseUrl, "POST", "/v1/claims", {
+        body: {
+            agentName: params.agentName,
+            host: params.host,
+            publicKey: params.key.publicKey,
+            ...(params.authorize ? { authorize: limitsJson(params.authorize) } : {}),
+        },
+    });
+    return body;
+}
+/**
+ * Second half of `connectAgent`, one attempt: `pending` until the owner approves, then the credentials exactly once.
+ * Stateless, so an agent can start a claim, end its turn, and check again later (CLAIM_EXPIRED once it lapsed).
+ */
+export async function exchangeClaim(params) {
+    const signature = await params.key.sign(claimProofMessage(params.claimId));
+    const { body } = await request(params.fetch ?? fetch, params.baseUrl, "POST", `/v1/claims/${params.claimId}/exchange`, {
+        body: { signature },
+    });
+    return body;
+}
+/**
+ * The agent's side of a Mantle Agent Account. It can only do what the owner authorized: trade within on-chain
+ * limits, read its status, manage its own scheduled runs, and stop itself. It never holds a private key.
+ */
+export class AgentClient {
+    baseUrl;
+    credentials;
+    fetchImpl;
+    /** Set when running inside a scheduled run; trades are charged to that run's budget. */
+    leaseId;
+    constructor(baseUrl, credentials, opts = {}) {
+        this.baseUrl = baseUrl;
+        this.credentials = credentials;
+        this.fetchImpl = opts.fetch ?? ((...a) => fetch(...a));
+        this.leaseId = opts.leaseId;
+    }
+    async call(method, path, kind, opts = {}) {
+        const token = this.credentials?.[kind]?.token;
+        if (!token)
+            throw new ClientError("NOT_CONNECTED", "no credentials; connect the agent first");
+        return request(this.fetchImpl, this.baseUrl, method, path, { ...opts, token });
+    }
+    async status() {
+        return (await this.call("GET", "/v1/status", "trading")).body;
+    }
+    /** Price a trade. Valid ~30 s and for one trade. `amountIn` is wei (MNT for buys, tokens for sells). */
+    async quote(params) {
+        return (await this.call("POST", "/v1/quotes", "trading", { body: params })).body;
+    }
+    /**
+     * Quote and execute. Reuse `requestId` when retrying: the same trade is never executed twice. With `wait`, polls
+     * until confirmed / failed / unknown (or `timeoutMs`).
+     */
+    async trade(params) {
+        const quote = await this.quote(params);
+        const { body: intent } = await this.call("POST", "/v1/trades", "trading", {
+            body: { quoteId: quote.quoteId },
+            headers: { "idempotency-key": params.requestId ?? globalThis.crypto.randomUUID(), ...(this.leaseId ? { "x-run-lease": this.leaseId } : {}) },
+        });
+        return params.wait === false ? intent : this.waitForTrade(intent, params.timeoutMs);
+    }
+    async tradeStatus(intentId) {
+        return (await this.call("GET", `/v1/trades/${intentId}`, "trading")).body;
+    }
+    async waitForTrade(intent, timeoutMs = 90_000) {
+        const deadline = Date.now() + timeoutMs;
+        let current = intent;
+        while (!FINAL.has(current.status) && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 1_000));
+            current = await this.tradeStatus(current.intentId);
+        }
+        return current;
+    }
+    /**
+     * Emergency stop: revokes all of this agent's credentials at once. `confirmUrl` (null without a session) is the
+     * revoke request the owner confirms to make it permanent on chain.
+     */
+    async stop() {
+        return (await this.call("POST", "/v1/agent/stop", "runtime")).body;
+    }
+    /**
+     * Ask the owner for something only they can do (PRD WEB-01/03). Each call returns a request with a link and a
+     * summary for the owner; nothing happens until they confirm it with a passkey. Asking again for the same kind
+     * replaces the previous pending request.
+     */
+    requests = {
+        authorize: (limits = DEFAULT_SESSION_LIMITS) => this.ask("authorize", limitsJson(limits)),
+        renew: (durationSeconds) => this.ask("renew", { durationSeconds }),
+        revoke: () => this.ask("revoke", {}),
+        /** `to` must come from the owner, never from content the agent read. */
+        withdraw: (p) => this.ask("withdraw", { to: p.to, asset: p.asset, amount: p.amount === "max" ? "max" : p.amount.toString() }),
+        autoRun: (s) => this.ask("runtime", { ...s, maxSpendPerDay: s.maxSpendPerDay.toString() }),
+        resume: () => this.ask("resume", {}),
+        get: async (requestId) => (await this.call("GET", `/v1/requests/${requestId}`, "trading")).body,
+        list: async () => (await this.call("GET", "/v1/requests", "trading")).body,
+    };
+    async ask(kind, params) {
+        return (await this.call("POST", "/v1/requests", "trading", { body: { kind, params } })).body;
+    }
+    /** Scheduled runs (PRD RUN-02/03). */
+    runtime = {
+        status: async () => (await this.call("GET", "/v1/runtime", "trading")).body,
+        lease: async (host) => (await this.call("POST", "/v1/runtime/lease", "runtime", { body: { host } })).body,
+        complete: async (leaseId, report = {}) => void (await this.call("POST", `/v1/runtime/lease/${leaseId}/complete`, "runtime", { body: report })),
+        ack: async (commandId) => void (await this.call("POST", `/v1/runtime/commands/${commandId}/ack`, "runtime")),
+        /** Agents may pause themselves; only the owner resumes. */
+        pause: async () => (await this.call("POST", "/v1/runtime/pause", "runtime")).body,
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/browser.d.ts

@@ -0,0 +1,16 @@
+import type { OwnerTurnkey } from "./owner.js";
+/** Production: every owner action is approved with a passkey bound to this site (rpId = hostname). */
+export declare function passkeyTurnkey(params: {
+    parentOrgId: string;
+    rpId?: string;
+    apiBaseUrl?: string;
+}): OwnerTurnkey;
+/**
+ * Development only (no passkeys, e.g. local or automated testing): a P-256 API key kept in this browser stands in
+ * for the passkey. The API accepts such owners only with ALLOW_API_KEY_OWNERS=true.
+ */
+export declare function devKeyTurnkey(params: {
+    parentOrgId: string;
+    apiBaseUrl?: string;
+    storage?: Storage;
+}): OwnerTurnkey;

package/dist/browser.js

@@ -0,0 +1,53 @@
+// Browser-only: Turnkey passkey (production) and dev-key owners for the confirmation page.
+import { ApiKeyStamper } from "@turnkey/api-key-stamper";
+import { generateP256KeyPair } from "@turnkey/crypto";
+import { Turnkey, TurnkeyBrowserClient } from "@turnkey/sdk-browser";
+import { rootSigner, TURNKEY_API_BASE_URL } from "@mantle-agent/custody/owner";
+function fromClient(kind, client, parentOrgId, register) {
+    return {
+        kind,
+        register,
+        async stampWhoami() {
+            const signed = await client.stampGetWhoami({ organizationId: parentOrgId });
+            if (!signed)
+                throw new Error("could not produce a signed login request");
+            return signed;
+        },
+        owner: () => client,
+        rootSigner: (subOrgId, address) => rootSigner({ client: client, subOrgId, rootAddress: address }),
+    };
+}
+/** Production: every owner action is approved with a passkey bound to this site (rpId = hostname). */
+export function passkeyTurnkey(params) {
+    const rpId = params.rpId ?? window.location.hostname;
+    const sdk = new Turnkey({ apiBaseUrl: params.apiBaseUrl ?? TURNKEY_API_BASE_URL, defaultOrganizationId: params.parentOrgId, rpId });
+    const client = sdk.passkeyClient();
+    return fromClient("passkey", client, params.parentOrgId, async (ownerName) => {
+        const { encodedChallenge, attestation } = await client.createUserPasskey({
+            publicKey: { rp: { id: rpId, name: "Mantle Agent Account" }, user: { name: ownerName, displayName: ownerName } },
+        });
+        return { passkey: { authenticatorName: `passkey-${Date.now()}`, challenge: encodedChallenge, attestation } };
+    });
+}
+const DEV_KEY_STORAGE = "mantle-agent:dev-owner-key";
+/**
+ * Development only (no passkeys, e.g. local or automated testing): a P-256 API key kept in this browser stands in
+ * for the passkey. The API accepts such owners only with ALLOW_API_KEY_OWNERS=true.
+ */
+export function devKeyTurnkey(params) {
+    const storage = params.storage ?? window.localStorage;
+    let saved = storage.getItem(DEV_KEY_STORAGE);
+    if (!saved) {
+        const kp = generateP256KeyPair();
+        saved = JSON.stringify({ publicKey: kp.publicKey, privateKey: kp.privateKey });
+        storage.setItem(DEV_KEY_STORAGE, saved);
+    }
+    const key = JSON.parse(saved);
+    const client = new TurnkeyBrowserClient({
+        stamper: new ApiKeyStamper({ apiPublicKey: key.publicKey, apiPrivateKey: key.privateKey }),
+        apiBaseUrl: params.apiBaseUrl ?? TURNKEY_API_BASE_URL,
+        organizationId: params.parentOrgId,
+    });
+    return fromClient("dev-key", client, params.parentOrgId, async () => ({ apiPublicKey: key.publicKey }));
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

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

package/dist/http.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A failure with the Mantle Agent API's stable error code (or a local one such as NOT_CONNECTED or
+ * API_UNREACHABLE). React to `code`, not to the message.
+ */
+export declare class ClientError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, details?: unknown | undefined, status?: number | undefined);
+}
+export type Fetch = typeof fetch;
+export type RequestOptions = {
+    token?: string | null;
+    body?: unknown;
+    headers?: Record<string, string>;
+};
+/** JSON request against the API; non-2xx responses become ClientError with the API's code. */
+export declare function request<T>(fetchImpl: Fetch, baseUrl: string, method: "GET" | "POST", path: string, opts?: RequestOptions): Promise<{
+    status: number;
+    body: T;
+}>;