@tallyforagents/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -14,6 +14,18 @@ declare class TallyClient {
     request<T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown): Promise<T>;
 }
 
+type AgentWallet = {
+    /** Wallet address (lowercased EVM hex) the agent can spend from. */
+    address: string;
+    /** Friendly name the wallet was given in the dashboard. */
+    display_name: string;
+    /** Optional role label (e.g., "main", "treasury"); null if unset. */
+    role_label: string | null;
+    /** Max per-tx spend in USDC as a decimal string. */
+    max_per_tx_usdc: string;
+    /** Daily cap in USDC as a decimal string, null if uncapped. */
+    daily_cap_usdc: string | null;
+};
 type Agent = {
     /** Stable user-provided identifier (e.g., "research-bot"). */
     id: string;
@@ -24,10 +36,18 @@ type Agent = {
     mode: "test" | "live";
     /** ISO 8601 timestamp. */
     created_at: string;
+    /** The account slug this agent belongs to. Surfaced so callers can
+     *  build dashboard deep-links (e.g., when telling the user to grant
+     *  a permission). */
+    account_slug: string;
     /** Count of non-revoked, activated signers. */
     active_signers: number;
     /** Count of non-revoked, not-yet-activated signers. */
     pending_signers: number;
+    /** Wallets this agent has active permission to spend from, with the
+     *  per-wallet caps from the permission. Empty array if no active
+     *  grants. Pick one to pass as `wallet` to tally.payments.create(). */
+    wallets: AgentWallet[];
 };
 type AgentUpsertInput = {
     /** User-provided stable string identifier (e.g., "research-bot"). */
@@ -45,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". */
@@ -104,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 = {
@@ -128,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.
@@ -147,6 +419,42 @@ 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;
 
@@ -188,9 +496,11 @@ declare class ConflictError extends TallyError {
 declare class Tally {
     readonly agents: AgentsResource;
     readonly payments: PaymentsResource;
+    readonly permissions: PermissionsResource;
+    readonly wallets: WalletsResource;
     readonly webhooks: WebhooksResource;
     private readonly client;
     constructor(opts: ClientOptions);
 }
 
-export { type Agent, type AgentUpsertInput, 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, verifySignature };