@tallyforagents/sdk 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -65,22 +65,123 @@ declare class AgentsResource {
     upsert(input: AgentUpsertInput): Promise<Agent>;
     list(): Promise<Agent[]>;
     get(id: string): Promise<Agent>;
+    /**
+     * Soft-deletes an agent. The row stays in the DB so historical
+     * transactions keep their attribution; future list/get responses
+     * hide it.
+     *
+     * Throws `ConflictError` (HTTP 409, `code: "has_active_grants"`) if
+     * the agent has any active permissions — revoke them first.
+     *
+     * Re-creating an agent with the same `id` via `upsert()` is the
+     * supported way to bring a deleted agent back.
+     */
+    delete(id: string): Promise<void>;
+}
+
+interface PageFetcher<T> {
+    (cursor: string | null): Promise<{
+        data: T[];
+        next_cursor: string | null;
+    }>;
+}
+declare class AsyncResourcePage<T> implements AsyncIterable<T> {
+    private readonly fetchPage;
+    constructor(fetchPage: PageFetcher<T>);
+    /**
+     * Async-iterates every item across all pages. Stops when the server
+     * returns `next_cursor: null`.
+     *
+     * ```ts
+     * for await (const p of tally.payments.list({ status: "confirmed" })) {
+     *   console.log(p.id);
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<T>;
+    /**
+     * Collects items into an array, optionally bounded. `toArray()` with
+     * no argument pulls every page; `toArray(20)` stops after the first
+     * 20 items (across whatever page boundaries that crosses).
+     *
+     * ```ts
+     * const recent = await tally.payments.list().toArray(20);
+     * ```
+     */
+    toArray(maxItems?: number): Promise<T[]>;
+    /**
+     * Returns just the first page (no auto-pagination). Use when the
+     * cursor itself matters — e.g., persisting it across runs to resume
+     * iteration later.
+     *
+     * ```ts
+     * const { data, next_cursor } = await tally.payments.list().firstPage();
+     * // … store next_cursor; next run: tally.payments.list().pageAfter(saved_cursor)
+     * ```
+     */
+    firstPage(): Promise<{
+        data: T[];
+        next_cursor: string | null;
+    }>;
+    /**
+     * Returns the page that follows the given cursor. Useful for resuming
+     * iteration from a previously-persisted cursor, or for manual paging
+     * when the auto-iterator's eager fetching isn't a fit.
+     */
+    pageAfter(cursor: string): Promise<{
+        data: T[];
+        next_cursor: string | null;
+    }>;
 }
 
 type Payment = {
     id: string;
     /** "pending" until the on-chain tx confirms; updated by a follow-up
-     *  GET (planned) or webhook (Phase 6). */
+     *  GET or webhook. */
     status: "pending" | "confirmed" | "failed";
     /** Transaction hash on the underlying chain. Set as soon as Privy
      *  accepts the signed RPC; the SDK does not wait for receipt. */
     tx_hash: string | null;
     amount_usdc: string;
+    /** Destination address. For outbound, this is the external recipient.
+     *  For inbound, this is one of your wallets. */
     to: string;
+    /** Source address. For outbound, this is your wallet. For inbound,
+     *  this is the external sender. */
     from: string;
     memo: string | null;
     idempotency_key: string | null;
     created_at: string;
+    /** "inbound" or "outbound". Populated on list responses; may be
+     *  undefined on responses from `create()` or `get()` (which always
+     *  describe outbound payments). */
+    direction?: "inbound" | "outbound";
+    /** Your wallet's address — always one of YOUR wallets regardless of
+     *  direction. Same as `from` for outbound, `to` for inbound. */
+    wallet_address?: string;
+    /** Friendly name of `wallet_address`. */
+    wallet_display_name?: string;
+    /** The agent's externalId for outbound payments; null for inbound. */
+    agent_id?: string | null;
+    /** Block timestamp from the chain, set after the tx confirms. */
+    block_timestamp?: string | null;
+    /** Human-readable reason for `status: "failed"` rows. */
+    error_reason?: string | null;
+};
+type PaymentListFilters = {
+    /** Filter by payment status. */
+    status?: "pending" | "confirmed" | "failed";
+    /** Filter by direction. */
+    direction?: "inbound" | "outbound";
+    /** Filter by agent (external id, the user-provided string). */
+    agent_id?: string;
+    /** Filter by wallet address (case-insensitive). */
+    wallet?: string;
+    /** Free-text search over tx hash, addresses, memo. */
+    q?: string;
+    /** Max items per page. Default 50, max 100. The auto-iterator uses
+     *  this for each page fetch. */
+    limit?: number;
 };
 type PaymentCreateInput = {
     /** Agent's user-provided id (the externalId), e.g. "research-bot". */
@@ -124,6 +225,120 @@ declare class PaymentsResource {
      * this is the canonical way to wait for `confirmed` / `failed`.
      */
     get(id: string): Promise<Payment>;
+    /**
+     * Lists payments in the API key's account + mode, auto-paginated.
+     * Returns an `AsyncResourcePage` you can `for await` over to iterate
+     * every payment, or call `.toArray(n)` for a bounded read.
+     *
+     * Pending outbound rows are lazily refreshed from the chain on read,
+     * matching the dashboard's behavior — polling `list({ status: "pending" })`
+     * is a valid way to wait for confirmation.
+     *
+     * ```ts
+     * for await (const p of tally.payments.list({ status: "confirmed" })) {
+     *   console.log(p.id, p.amount_usdc, p.to);
+     * }
+     *
+     * // Or bounded:
+     * const last20 = await tally.payments.list({ direction: "outbound" }).toArray(20);
+     * ```
+     */
+    list(filters?: PaymentListFilters): AsyncResourcePage<Payment>;
+}
+
+type Permission = {
+    /** Stable cuid for this grant. Use as the reference id if/when revoke
+     *  or update endpoints land. */
+    id: string;
+    /** Agent's user-provided externalId (e.g., "research-bot"). */
+    agent_id: string;
+    /** Wallet address this grant is on. */
+    wallet_address: string;
+    /** Friendly wallet name set at provisioning. */
+    wallet_display_name: string;
+    /** "active" once the wallet owner has authorized the signer on-chain;
+     *  "pending" before that. */
+    status: "active" | "pending";
+    max_per_tx_usdc: string;
+    daily_cap_usdc: string | null;
+    /** USDC already moved by this grant today (UTC). */
+    used_today_usdc: string;
+    /** daily_cap_usdc minus used_today_usdc, or null if uncapped. Clamped
+     *  to 0 when over-spent (shouldn't happen — daily-cap enforcement is
+     *  pre-broadcast — but defensively non-negative). */
+    remaining_today_usdc: string | null;
+    /** Whitelisted recipient addresses. Empty = unrestricted. */
+    recipient_allowlist: string[];
+    /** Whitelisted contract addresses. Defaults to the mode's USDC contract. */
+    contract_allowlist: string[];
+    /** ISO 8601 timestamp; null if no expiry. */
+    expires_at: string | null;
+    created_at: string;
+    activated_at: string | null;
+};
+type PermissionListFilters = {
+    /** Filter by agent (external id). */
+    agent_id?: string;
+    /** Max items per page. Default 50, max 100. */
+    limit?: number;
+};
+declare class PermissionsResource {
+    private readonly client;
+    constructor(client: TallyClient);
+    /**
+     * Lists active grants in the API key's account + mode, auto-paginated.
+     * Returns an `AsyncResourcePage` you can `for await` over to iterate
+     * every permission, or call `.toArray(n)` for a bounded read.
+     *
+     * Each row includes the granted caps, today's usage, and the rolling
+     * remaining-daily-allowance, so agent code can preflight a payment
+     * without round-tripping the policy bounds.
+     *
+     * ```ts
+     * for await (const p of tally.permissions.list({ agent_id: "research-bot" })) {
+     *   console.log(`${p.wallet_display_name}: $${p.remaining_today_usdc} left`);
+     * }
+     * ```
+     */
+    list(filters?: PermissionListFilters): AsyncResourcePage<Permission>;
+}
+
+type Wallet = {
+    /** Stable Tally cuid for this wallet. Pass as `wallet_id` to permission
+     *  routes (grant / edit / revoke). */
+    id: string;
+    /** EVM address. Use as `wallet` in `tally.payments.create({ wallet })`. */
+    address: string;
+    /** Friendly name set when the wallet was created. */
+    display_name: string;
+    /** Optional role label (e.g., "treasury", "ops"); null if unset. */
+    role_label: string | null;
+    mode: "test" | "live";
+    /** ISO 8601 timestamp. */
+    created_at: string;
+};
+type WalletCreateInput = {
+    /** Human-friendly name. 1–60 chars after trimming. */
+    display_name: string;
+    /** Optional role label (1–40 chars after trimming). */
+    role_label?: string;
+};
+declare class WalletsResource {
+    private readonly client;
+    constructor(client: TallyClient);
+    /**
+     * Lists every wallet in the API key's account + mode. Wallets are
+     * returned oldest-first (so the "Main Wallet" auto-provisioned at
+     * sign-in shows up first).
+     */
+    list(): Promise<Wallet[]>;
+    /**
+     * Provisions a new Privy server wallet in the API key's account + mode.
+     * The wallet is owned (in Privy) by the oldest `owner`-role member of
+     * the account, so SDK-created wallets behave identically to dashboard-
+     * created ones: the same passkey approves any future signer changes.
+     */
+    create(input: WalletCreateInput): Promise<Wallet>;
 }
 
 type WebhookVerifyResult = {
@@ -148,7 +363,44 @@ type WebhookVerifyInput = {
      *  the longer a stolen signature stays replayable. */
     toleranceSeconds?: number;
 };
+type WebhookEventType = "payment.created" | "payment.confirmed" | "payment.failed" | "inbound.received" | "permission.granted" | "permission.updated" | "permission.revoked";
+type Webhook = {
+    /** Stable cuid for this endpoint. Pass to `revoke()`. */
+    id: string;
+    mode: "test" | "live";
+    /** Receiver URL Tally POSTs to. */
+    url: string;
+    /** Event types this endpoint subscribes to. */
+    events: string[];
+    /** First few characters of the secret (e.g., `whsec_test_abc…`).
+     *  Useful for identifying the secret in dashboards without
+     *  exposing the plaintext. */
+    secret_prefix: string;
+    created_at: string;
+    revoked_at: string | null;
+    /** ISO timestamp of the last delivery attempt. null until first send. */
+    last_delivery_at: string | null;
+};
+type CreatedWebhook = Webhook & {
+    /** Plaintext signing secret. Returned exactly once at creation.
+     *  Store it now — it's NOT recoverable later. */
+    secret: string;
+};
+type WebhookCreateInput = {
+    /** Receiver URL. Must be https:// (or http://localhost for dev). */
+    url: string;
+    /** Event types to subscribe to. */
+    events: WebhookEventType[];
+};
 declare class WebhooksResource {
+    private readonly client?;
+    /**
+     * The TallyClient is optional so legacy zero-arg construction
+     * (`new WebhooksResource()`) still works for non-class consumers who
+     * only use `verifySignature`. List / create / revoke require a
+     * client; calling them on a clientless instance throws.
+     */
+    constructor(client?: TallyClient | undefined);
     /**
      * Verify a `tally-signature` header against the request body. Use in
      * your webhook handler before processing the payload.
@@ -167,9 +419,149 @@ declare class WebhooksResource {
      * ```
      */
     verifySignature(input: WebhookVerifyInput): WebhookVerifyResult;
+    private requireClient;
+    /**
+     * Lists every webhook endpoint in the API key's account + mode.
+     * Revoked endpoints are included (with `revoked_at` set) for audit.
+     *
+     * ```ts
+     * for (const w of await tally.webhooks.list()) {
+     *   console.log(`${w.url} → ${w.events.join(",")}`);
+     * }
+     * ```
+     */
+    list(): Promise<Webhook[]>;
+    /**
+     * Creates a new webhook endpoint. The signing secret is returned in
+     * `webhook.secret` **exactly once** — store it now; it's not
+     * recoverable later. If you lose it, revoke and recreate.
+     *
+     * ```ts
+     * const webhook = await tally.webhooks.create({
+     *   url: "https://example.com/tally/events",
+     *   events: ["payment.confirmed", "payment.failed"],
+     * });
+     * console.log(webhook.secret); // shown once
+     * ```
+     */
+    create(input: WebhookCreateInput): Promise<CreatedWebhook>;
+    /**
+     * Revokes a webhook endpoint by id. No further deliveries will be
+     * enqueued; deliveries already in-flight are not cancelled.
+     * Idempotent: revoking an already-revoked endpoint is a no-op.
+     *
+     * ```ts
+     * await tally.webhooks.revoke("whk_01HXYZ...");
+     * ```
+     */
+    revoke(id: string): Promise<Webhook>;
 }
 declare function verifySignature(input: WebhookVerifyInput): WebhookVerifyResult;
 
+/** Shape of a single offer inside an x402 402 response's `accepts[]`. */
+type X402PaymentTerms = {
+    scheme: string;
+    network: string;
+    /** Atomic USDC amount (micro-units, 6 decimals). String to preserve
+     *  precision over JSON. */
+    maxAmountRequired: string;
+    resource: string;
+    description?: string;
+    payTo: string;
+    asset: string;
+    /** Optional metadata the server may attach. */
+    extra?: Record<string, unknown>;
+};
+/** Shape of an x402 402 response body. */
+type X402Response = {
+    x402Version: number;
+    error?: string;
+    accepts?: X402PaymentTerms[];
+};
+type X402FetchInput = {
+    /** Agent's externalId. The agent must have an active permission
+     *  grant on `wallet` with enough headroom to cover the x402 charge. */
+    agent_id: string;
+    /** Sender wallet address. Typically `agent.wallets[0].address` from
+     *  the response to `tally.agents.upsert()`. */
+    wallet: string;
+    /** HTTP method for the request. Defaults to "GET". */
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Extra request headers. The SDK overrides `x-payment` on the retry
+     *  but everything else passes through. */
+    headers?: Record<string, string>;
+    /** Request body. Passed through to fetch on both the initial call
+     *  and the retry; the SDK does not modify it. */
+    body?: BodyInit | null;
+    /** Client-side cap on what the SDK will spend on this call. If the
+     *  402 asks for more than this, the SDK throws before paying. The
+     *  agent's policy caps remain authoritative server-side; this is a
+     *  per-call belt to the policy's suspenders. Decimal USDC, e.g. "1.00". */
+    max_amount_usdc?: string;
+    /** Memo stored on the Tally Payment row. Defaults to
+     *  `x402:${host}${pathname}`. */
+    memo?: string;
+    /** Idempotency key for the underlying `payments.create` call. If you
+     *  may retry the same logical x402 call, set this to a stable string
+     *  so a retry returns the original payment instead of double-spending.
+     *  Defaults to a fresh per-call key. */
+    idempotency_key?: string;
+    /** Per-call timeout in ms for the underlying fetches. Default: no
+     *  timeout (the runtime's default applies). */
+    timeout_ms?: number;
+};
+type X402PaymentReceipt = {
+    /** Tally Payment id (e.g. `pay_…`). */
+    id: string;
+    /** On-chain transaction hash. */
+    tx_hash: string;
+    /** Decimal USDC amount paid, e.g. "0.05". */
+    amount_usdc: string;
+    /** Recipient address from the 402 terms. */
+    to: string;
+    /** Network the payment landed on. */
+    network: string;
+    /** Memo stored on the Tally Payment row. */
+    memo: string | null;
+};
+type X402FetchResult = {
+    /** The final HTTP response. If the first call returned 200, this is
+     *  that response. Otherwise it's the post-payment retry response.
+     *  Check `response.ok` / `response.status` as you would with any
+     *  fetch — the SDK does not throw for non-200s after a successful
+     *  payment, because some x402 services return 4xx/5xx legitimately. */
+    response: Response;
+    /** Receipt for the payment the SDK made on your behalf. Null when
+     *  the first call returned 200 (no payment was needed). */
+    payment: X402PaymentReceipt | null;
+};
+declare class X402Resource {
+    #private;
+    constructor(client: TallyClient);
+    /**
+     * Fetch a URL that may be paywalled by the x402 protocol. If the
+     * service returns 402, the SDK pays via Tally and retries
+     * automatically. The agent code sees one call.
+     *
+     * ```ts
+     * const { response, payment } = await tally.x402.fetch(
+     *   "https://api.example.com/weather?city=Tokyo",
+     *   { agent_id: "hermes", wallet: agent.wallets[0].address }
+     * );
+     *
+     * if (response.ok) {
+     *   const data = await response.json();
+     *   if (payment) console.log(`paid ${payment.amount_usdc} USDC — ${payment.tx_hash}`);
+     * }
+     * ```
+     *
+     * Throws `TallyError` for SDK-side problems (network unreachable,
+     * malformed 402 body, unsupported network, payment refused by
+     * Tally, etc.). Lets non-200 retry responses pass through as-is.
+     */
+    fetch(url: string, input: X402FetchInput): Promise<X402FetchResult>;
+}
+
 type ApiErrorPayload = {
     type: string;
     message: string;
@@ -208,9 +600,12 @@ declare class ConflictError extends TallyError {
 declare class Tally {
     readonly agents: AgentsResource;
     readonly payments: PaymentsResource;
+    readonly permissions: PermissionsResource;
+    readonly wallets: WalletsResource;
     readonly webhooks: WebhooksResource;
+    readonly x402: X402Resource;
     private readonly client;
     constructor(opts: ClientOptions);
 }
 
-export { type Agent, type AgentUpsertInput, type AgentWallet, AuthenticationError, type ClientOptions, ConflictError, NotFoundError, type Payment, type PaymentCreateInput, RateLimitError, Tally, TallyError, ValidationError, type WebhookVerifyInput, type WebhookVerifyResult, verifySignature };
+export { type Agent, type AgentUpsertInput, type AgentWallet, AsyncResourcePage, AuthenticationError, type ClientOptions, ConflictError, type CreatedWebhook, NotFoundError, type Payment, type PaymentCreateInput, type PaymentListFilters, type Permission, type PermissionListFilters, RateLimitError, Tally, TallyError, ValidationError, type Wallet, type WalletCreateInput, type Webhook, type WebhookCreateInput, type WebhookEventType, type WebhookVerifyInput, type WebhookVerifyResult, type X402FetchInput, type X402FetchResult, type X402PaymentReceipt, type X402PaymentTerms, type X402Response, verifySignature };