@tallyforagents/sdk 0.1.1 → 0.3.0

package/dist/index.cjs

@@ -66,6 +66,22 @@ function makeError(payload, status) {
 }
 
 // src/client.ts
+var warnedRotations = /* @__PURE__ */ new Set();
+function warnRotationOnce(key, until) {
+  const id = `${key.slice(0, 12)}:${until}`;
+  if (warnedRotations.has(id)) return;
+  warnedRotations.add(id);
+  const remaining = (() => {
+    const ms = new Date(until).getTime() - Date.now();
+    if (ms <= 0) return "shortly";
+    const h = Math.floor(ms / 36e5);
+    const m = Math.floor(ms % 36e5 / 6e4);
+    return h > 0 ? `${h}h ${m}m` : `${m}m`;
+  })();
+  console.warn(
+    `[tally] API key is in its rotation grace window (ends in ~${remaining}, at ${until}). Switch to the rotated key before then to avoid 401s.`
+  );
+}
 var TallyClient = class {
   apiKey;
   baseUrl;
@@ -100,6 +116,8 @@ var TallyClient = class {
       },
       body: body === void 0 ? void 0 : JSON.stringify(body)
     });
+    const graceUntil = res.headers.get("tally-rotation-grace-until");
+    if (graceUntil) warnRotationOnce(this.apiKey, graceUntil);
     if (!res.ok) {
       let payload = {};
       try {
@@ -151,6 +169,88 @@ var AgentsResource = class {
     );
     return 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.
+   */
+  async delete(id) {
+    await this.client.request(
+      "DELETE",
+      `/v1/agents/${encodeURIComponent(id)}`
+    );
+  }
+};
+
+// src/pagination.ts
+var AsyncResourcePage = class {
+  constructor(fetchPage) {
+    this.fetchPage = fetchPage;
+  }
+  fetchPage;
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async *[Symbol.asyncIterator]() {
+    let cursor = null;
+    while (true) {
+      const page = await this.fetchPage(cursor);
+      for (const item of page.data) yield item;
+      if (!page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async toArray(maxItems) {
+    const out = [];
+    for await (const item of this) {
+      out.push(item);
+      if (maxItems !== void 0 && out.length >= maxItems) break;
+    }
+    return out;
+  }
+  /**
+   * 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)
+   * ```
+   */
+  async firstPage() {
+    return this.fetchPage(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.
+   */
+  async pageAfter(cursor) {
+    return this.fetchPage(cursor);
+  }
 };
 
 // src/resources/payments.ts
@@ -194,10 +294,126 @@ var PaymentsResource = class {
     );
     return 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 = {}) {
+    const { limit, status, direction, agent_id, wallet, q } = filters;
+    return new AsyncResourcePage(async (cursor) => {
+      const qs = new URLSearchParams();
+      if (cursor) qs.set("cursor", cursor);
+      if (limit !== void 0) qs.set("limit", String(limit));
+      if (status) qs.set("status", status);
+      if (direction) qs.set("direction", direction);
+      if (agent_id) qs.set("agent_id", agent_id);
+      if (wallet) qs.set("wallet", wallet);
+      if (q) qs.set("q", q);
+      const query = qs.toString();
+      const path = query ? `/v1/payments?${query}` : "/v1/payments";
+      return this.client.request(
+        "GET",
+        path
+      );
+    });
+  }
+};
+
+// src/resources/permissions.ts
+var PermissionsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * 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 = {}) {
+    const { limit, agent_id } = filters;
+    return new AsyncResourcePage(async (cursor) => {
+      const qs = new URLSearchParams();
+      if (cursor) qs.set("cursor", cursor);
+      if (limit !== void 0) qs.set("limit", String(limit));
+      if (agent_id) qs.set("agent_id", agent_id);
+      const query = qs.toString();
+      const path = query ? `/v1/permissions?${query}` : "/v1/permissions";
+      return this.client.request("GET", path);
+    });
+  }
+};
+
+// src/resources/wallets.ts
+var WalletsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * 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).
+   */
+  async list() {
+    const { wallets } = await this.client.request(
+      "GET",
+      "/v1/wallets"
+    );
+    return wallets;
+  }
+  /**
+   * 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.
+   */
+  async create(input) {
+    const { wallet } = await this.client.request(
+      "POST",
+      "/v1/wallets",
+      input
+    );
+    return wallet;
+  }
 };
 var SIGNATURE_VERSION = "v1";
 var DEFAULT_TOLERANCE_SECONDS = 300;
 var WebhooksResource = class {
+  /**
+   * 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) {
+    this.client = client;
+  }
+  client;
   /**
    * Verify a `tally-signature` header against the request body. Use in
    * your webhook handler before processing the payload.
@@ -218,6 +434,58 @@ var WebhooksResource = class {
   verifySignature(input) {
     return verifySignature(input);
   }
+  requireClient() {
+    if (!this.client) {
+      throw new Error(
+        "WebhooksResource was constructed without a TallyClient. Use `new Tally({ apiKey })` to enable list/create/revoke."
+      );
+    }
+    return this.client;
+  }
+  /**
+   * 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(",")}`);
+   * }
+   * ```
+   */
+  async list() {
+    const { webhooks } = await this.requireClient().request("GET", "/v1/webhooks");
+    return webhooks;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async create(input) {
+    const { webhook } = await this.requireClient().request("POST", "/v1/webhooks", input);
+    return webhook;
+  }
+  /**
+   * 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...");
+   * ```
+   */
+  async revoke(id) {
+    const { webhook } = await this.requireClient().request("POST", `/v1/webhooks/${encodeURIComponent(id)}/revoke`);
+    return webhook;
+  }
 };
 function verifySignature(input) {
   const { body, header, secret } = input;
@@ -252,11 +520,195 @@ function verifySignature(input) {
   return { ok: true };
 }
 
+// src/resources/x402.ts
+var X402_HEADER = "x-payment";
+var SUPPORTED_NETWORKS = /* @__PURE__ */ new Set(["base-sepolia", "base"]);
+var X402Resource = class {
+  #payments;
+  constructor(client) {
+    this.#payments = new PaymentsResource(client);
+  }
+  /**
+   * 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.
+   */
+  async fetch(url, input) {
+    const initial = await this.#doFetch(
+      url,
+      input,
+      /*paymentTxHash*/
+      null
+    );
+    if (initial.status !== 402) {
+      return { response: initial, payment: null };
+    }
+    let parsed;
+    try {
+      parsed = await initial.json();
+    } catch {
+      throw new TallyError({
+        type: "x402_protocol",
+        message: "Service returned 402 with a non-JSON body.",
+        status: 0
+      });
+    }
+    const terms = parsed.accepts?.[0];
+    if (!terms) {
+      throw new TallyError({
+        type: "x402_protocol",
+        message: "402 response had no `accepts[]` payment terms.",
+        status: 0,
+        details: { x402Version: parsed.x402Version, error: parsed.error }
+      });
+    }
+    if (!SUPPORTED_NETWORKS.has(terms.network)) {
+      throw new TallyError({
+        type: "x402_protocol",
+        message: `x402 service requested unsupported network: ${terms.network}. Tally supports base-sepolia (test) and base (live).`,
+        status: 0,
+        details: { network: terms.network }
+      });
+    }
+    const atomicAmount = (() => {
+      try {
+        return BigInt(terms.maxAmountRequired);
+      } catch {
+        throw new TallyError({
+          type: "x402_protocol",
+          message: `x402 service quoted an unparseable amount: ${terms.maxAmountRequired}`,
+          status: 0
+        });
+      }
+    })();
+    const decimalAmount = formatAtomicUSDC(atomicAmount);
+    if (input.max_amount_usdc !== void 0) {
+      const capAtomic = parseDecimalUSDC(input.max_amount_usdc);
+      if (atomicAmount > capAtomic) {
+        throw new TallyError({
+          type: "x402_amount_exceeds_cap",
+          message: `x402 service requested ${decimalAmount} USDC, which exceeds the caller-supplied max_amount_usdc of ${input.max_amount_usdc}.`,
+          status: 0,
+          details: { requested_usdc: decimalAmount, max_usdc: input.max_amount_usdc }
+        });
+      }
+    }
+    const memo = input.memo ?? defaultMemo(url);
+    const idempotencyKey = input.idempotency_key ?? defaultIdempotencyKey(url);
+    let payment;
+    try {
+      payment = await this.#payments.create({
+        agent_id: input.agent_id,
+        wallet: input.wallet,
+        to: terms.payTo,
+        amount_usdc: decimalAmount,
+        memo,
+        idempotency_key: idempotencyKey
+      });
+    } catch (e) {
+      throw e;
+    }
+    if (!payment.tx_hash) {
+      throw new TallyError({
+        type: "x402_payment_missing_tx_hash",
+        message: "Tally accepted the payment but returned no tx_hash.",
+        status: 0,
+        details: { payment_id: payment.id }
+      });
+    }
+    const retry = await this.#doFetch(url, input, payment.tx_hash);
+    return {
+      response: retry,
+      payment: {
+        id: payment.id,
+        tx_hash: payment.tx_hash,
+        amount_usdc: decimalAmount,
+        to: terms.payTo,
+        network: terms.network,
+        memo: payment.memo
+      }
+    };
+  }
+  async #doFetch(url, input, paymentTxHash) {
+    const headers = { ...input.headers ?? {} };
+    if (paymentTxHash) headers[X402_HEADER] = paymentTxHash;
+    const init = {
+      method: input.method ?? "GET",
+      headers,
+      body: input.body ?? void 0
+    };
+    if (input.timeout_ms !== void 0) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), input.timeout_ms);
+      init.signal = controller.signal;
+      try {
+        return await fetch(url, init);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+    return await fetch(url, init);
+  }
+};
+function defaultMemo(url) {
+  try {
+    const u = new URL(url);
+    return `x402:${u.host}${u.pathname}`.slice(0, 200);
+  } catch {
+    return "x402";
+  }
+}
+function defaultIdempotencyKey(url) {
+  try {
+    const u = new URL(url);
+    return `x402:${u.host}${u.pathname}:${Date.now()}`.slice(0, 64);
+  } catch {
+    return `x402:${Date.now()}`;
+  }
+}
+function formatAtomicUSDC(atomic) {
+  const whole = atomic / 1000000n;
+  const frac = atomic % 1000000n;
+  const fracStr = frac.toString().padStart(6, "0").replace(/0+$/, "");
+  return fracStr ? `${whole}.${fracStr}` : `${whole}`;
+}
+function parseDecimalUSDC(decimal) {
+  if (!/^\d+(\.\d{1,6})?$/.test(decimal.trim())) {
+    throw new TallyError({
+      type: "validation_failed",
+      message: `Invalid decimal USDC amount: "${decimal}". Expected up to 6 fractional digits.`,
+      status: 0
+    });
+  }
+  const [whole, frac = ""] = decimal.trim().split(".");
+  const fracPadded = (frac + "000000").slice(0, 6);
+  return BigInt(whole) * 1000000n + BigInt(fracPadded);
+}
+
 // src/index.ts
 var Tally = class {
   agents;
   payments;
+  permissions;
+  wallets;
   webhooks;
+  x402;
   // Expose the underlying client for advanced use (custom retries, etc.).
   // Internal callers go through the resource classes instead.
   client;
@@ -264,10 +716,14 @@ var Tally = class {
     this.client = new TallyClient(opts);
     this.agents = new AgentsResource(this.client);
     this.payments = new PaymentsResource(this.client);
-    this.webhooks = new WebhooksResource();
+    this.permissions = new PermissionsResource(this.client);
+    this.wallets = new WalletsResource(this.client);
+    this.webhooks = new WebhooksResource(this.client);
+    this.x402 = new X402Resource(this.client);
   }
 };
 
+exports.AsyncResourcePage = AsyncResourcePage;
 exports.AuthenticationError = AuthenticationError;
 exports.ConflictError = ConflictError;
 exports.NotFoundError = NotFoundError;