@tallion/sdk 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# @tallion/sdk
+
+TypeScript SDK for [Tallion](https://tallion.ai) — AI agent spend control.
+
+Give your AI agents the ability to make purchases with built-in guardrails: spend limits, approval flows, and full transaction context.
+
+## Install
+
+```bash
+npm install @tallion/sdk
+```
+
+## Quick start
+
+```typescript
+import { Tally } from "@tallion/sdk";
+
+const tally = new Tally({ apiKey: process.env.TALLION_API_KEY! });
+// sk_sandbox_* → sandbox, sk_live_* → production (auto-detected)
+```
+
+## Authorization
+
+Before an agent can spend on behalf of a customer, the customer must authorize it through Tallion's hosted OAuth flow with PKCE.
+
+### 1. Create an authorization URL (server-side)
+
+```typescript
+const { url, state, codeVerifier } = await tally.authorize.createUrl({
+  customerIdentifier: "+1234567890", // phone or email
+  redirectUrl: "https://yourapp.com/callback",
+  scopes: ["purchase", "balance:read"],
+  suggestedLimits: {
+    maxPerTransaction: 10000, // $100.00 (cents)
+    maxPerDay: 50000,
+    requireApprovalAbove: 25000,
+  },
+});
+
+// Store state + codeVerifier in your session, then open `url` as a popup
+```
+
+### 2. Exchange the code (callback handler)
+
+```typescript
+const { accessToken, refreshToken, customerId, installationId } =
+  await tally.authorize.exchangeCode({
+    code: req.query.code,
+    codeVerifier: storedCodeVerifier,
+  });
+
+// Store accessToken securely — this is what you pass to purchase/balance calls
+```
+
+### 3. Refresh tokens
+
+```typescript
+const tokens = await tally.authorize.refreshToken({
+  refreshToken: storedRefreshToken,
+});
+```
+
+### 4. Revoke access
+
+```typescript
+await tally.authorize.revoke(accessToken);
+```
+
+## Purchases
+
+```typescript
+const tx = await tally.purchase({
+  customerToken: accessToken,
+  amount: 2500, // $25.00 in cents
+  merchant: {
+    name: "Delta Airlines",
+    mcc: "3000",
+    country: "US",
+  },
+  context: {
+    description: "Round-trip flight NYC → LAX, March 15",
+    category: "travel",
+    lineItems: [{ name: "Economy seat", quantity: 1, price: 2500 }],
+    externalReference: "booking-abc-123",
+    refundPolicy: "Non-refundable",
+    metadata: { flightNumber: "DL 1234" },
+  },
+});
+
+// tx.status: "approved" | "pending_approval" | "declined"
+console.log(tx.transactionId, tx.status, tx.decisionReason);
+```
+
+## Balance
+
+```typescript
+const balance = await tally.balance(accessToken);
+
+console.log(balance.remaining); // cents remaining in wallet
+console.log(balance.fundingAmount); // total funded
+console.log(balance.spentAmount); // total spent
+```
+
+## Webhooks
+
+Verify incoming webhook signatures using HMAC-SHA256. Works in Node 18+, Deno, Bun, and Cloudflare Workers (uses Web Crypto API).
+
+```typescript
+import { Tally } from "@tallion/sdk";
+
+const tally = new Tally({ apiKey: process.env.TALLION_API_KEY! });
+
+// In your webhook handler
+app.post("/webhooks/tallion", async (req, res) => {
+  const event = await tally.webhooks.verify(
+    req.body, // raw body string
+    req.headers["x-tally-signature"],
+  );
+
+  switch (event.event) {
+    case "transaction.approved":
+      // Handle approved transaction
+      break;
+    case "transaction.declined":
+      // Handle declined transaction
+      break;
+    case "approval.approved":
+      // Customer approved a pending transaction
+      break;
+    case "dispute.created":
+      // Customer filed a dispute
+      break;
+  }
+
+  res.json({ received: true });
+});
+```
+
+### Webhook events
+
+| Event | Description |
+|---|---|
+| `transaction.approved` | Transaction was approved |
+| `transaction.declined` | Transaction was declined by policy |
+| `transaction.pending_approval` | Transaction requires customer approval |
+| `approval.approved` | Customer approved a pending transaction |
+| `approval.declined` | Customer declined a pending transaction |
+| `approval.expired` | Approval request expired |
+| `dispute.created` | Customer opened a dispute |
+| `dispute.resolved` | Dispute was resolved |
+| `authorization.completed` | Customer completed the OAuth flow |
+| `authorization.revoked` | Customer revoked agent access |
+
+## Error handling
+
+```typescript
+import { Tally, TallionError } from "@tallion/sdk";
+
+try {
+  const tx = await tally.purchase({ ... });
+} catch (err) {
+  if (err instanceof TallionError) {
+    console.error(err.status);  // HTTP status code
+    console.error(err.message); // Error description
+    console.error(err.code);    // Error code (e.g. "insufficient_funds")
+  }
+}
+```
+
+## Sandbox vs production
+
+| | Sandbox | Production |
+|---|---|---|
+| API key prefix | `sk_sandbox_*` | `sk_live_*` |
+| Base URL | `api.sandbox.tallion.ai` | `api.tallion.ai` |
+| SMS verification | Code `123456` always works | Real SMS via Twilio |
+| Transactions | Simulated | Real card network |
+| Funding | Plaid Sandbox institutions | Real bank accounts |
+
+The SDK auto-detects the environment from your API key — no configuration needed.
+
+## Requirements
+
+- Node.js 18+ (or any runtime with `fetch` and `crypto.subtle`)
+- Zero runtime dependencies
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,193 @@
+interface TallyConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface CreateAuthUrlOptions {
+    customerIdentifier: string;
+    redirectUrl: string;
+    scopes?: string[];
+    codeChallengeMethod?: "S256" | "plain";
+    suggestedLimits?: SpendLimits;
+}
+interface AuthUrlResult {
+    url: string;
+    state: string;
+    codeVerifier: string;
+    authorizationId: string;
+}
+interface ExchangeCodeOptions {
+    code: string;
+    codeVerifier: string;
+}
+interface TokenResult {
+    accessToken: string;
+    refreshToken: string;
+    tokenType: string;
+    expiresIn: number;
+    customerId: string;
+    installationId: string;
+}
+interface RefreshTokenOptions {
+    refreshToken: string;
+}
+interface PurchaseOptions {
+    customerToken: string;
+    amount: number;
+    currency?: string;
+    merchant: MerchantInfo;
+    context: TransactionContext;
+    walletId?: string;
+}
+interface LegacyPurchaseOptions {
+    amount: number;
+    merchantName: string;
+    merchantMcc?: string;
+    merchantCountry?: string;
+    currency?: string;
+    walletId?: string;
+    reasoning?: string;
+    installationId: string;
+}
+interface MerchantInfo {
+    name: string;
+    mcc?: string;
+    country?: string;
+}
+interface TransactionContext {
+    description: string;
+    category: string;
+    lineItems?: LineItem[];
+    externalReference?: string;
+    refundPolicy?: string;
+    metadata?: Record<string, unknown>;
+}
+interface LineItem {
+    name: string;
+    quantity: number;
+    price: number;
+}
+interface PurchaseResult {
+    transactionId: string;
+    status: "approved" | "pending_approval" | "declined";
+    decision: string;
+    decisionReason: string;
+    amount: number;
+    merchantName: string;
+    approvalDeadline?: string;
+}
+interface BalanceResult {
+    walletId: string;
+    fundingAmount: number;
+    spentAmount: number;
+    remaining: number;
+}
+interface SpendLimits {
+    maxPerTransaction?: number;
+    maxPerDay?: number;
+    maxPerMonth?: number;
+    requireApprovalAbove?: number;
+}
+interface WebhookEvent {
+    event: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+
+declare class AuthorizeModule {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Create an authorization URL for customer consent.
+     * Returns the URL to open in a popup/browser plus the PKCE code verifier.
+     */
+    createUrl(options: CreateAuthUrlOptions): Promise<AuthUrlResult>;
+    /**
+     * Exchange an authorization code for access + refresh tokens.
+     */
+    exchangeCode(options: ExchangeCodeOptions): Promise<TokenResult>;
+    /**
+     * Refresh an access token using a refresh token.
+     */
+    refreshToken(options: RefreshTokenOptions): Promise<TokenResult>;
+    /**
+     * Revoke an access or refresh token.
+     */
+    revoke(token: string): Promise<void>;
+}
+
+declare class BalanceModule {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Get wallet balance for a customer (using OAuth token).
+     */
+    get(customerToken: string, walletId?: string): Promise<BalanceResult>;
+}
+
+declare class PurchaseModule {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Make a purchase using an OAuth customer token.
+     */
+    create(options: PurchaseOptions): Promise<PurchaseResult>;
+    /**
+     * Make a purchase using the legacy API key + installation ID auth.
+     */
+    legacyCreate(options: LegacyPurchaseOptions): Promise<PurchaseResult>;
+}
+
+declare class WebhooksModule {
+    private secret?;
+    constructor(secret?: string | undefined);
+    /**
+     * Verify a webhook signature and parse the event.
+     * Uses Web Crypto API (works in Node 18+, Deno, Bun, Cloudflare Workers, etc.)
+     *
+     * @param body - Raw request body string
+     * @param signature - Value of X-Tally-Signature header
+     * @param tolerance - Max age in seconds (default: 300 = 5 minutes)
+     */
+    verify(body: string, signature: string, tolerance?: number): Promise<WebhookEvent>;
+}
+
+declare class Tally {
+    private baseUrl;
+    private apiKey;
+    /** OAuth authorization flow */
+    authorize: AuthorizeModule;
+    /** Purchase operations */
+    purchases: PurchaseModule;
+    /** Balance operations */
+    balances: BalanceModule;
+    /** Webhook signature verification */
+    webhooks: WebhooksModule;
+    constructor(config: TallyConfig);
+    /**
+     * Convenience method: Make a purchase (delegates to purchases.create).
+     */
+    purchase(options: PurchaseOptions): Promise<PurchaseResult>;
+    /**
+     * Convenience method: Get balance for a customer.
+     */
+    balance(customerToken: string, walletId?: string): Promise<BalanceResult>;
+    /**
+     * Check if this is a sandbox instance.
+     */
+    get isSandbox(): boolean;
+    /**
+     * Get the resolved base URL.
+     */
+    get url(): string;
+}
+
+declare class TallionError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(status: number, message: string, code?: string);
+}
+
+export { type AuthUrlResult, AuthorizeModule, BalanceModule, type BalanceResult, type CreateAuthUrlOptions, type ExchangeCodeOptions, type LegacyPurchaseOptions, type LineItem, type MerchantInfo, PurchaseModule, type PurchaseOptions, type PurchaseResult, type RefreshTokenOptions, type SpendLimits, TallionError, Tally, type TallyConfig, type TokenResult, type TransactionContext, type WebhookEvent, WebhooksModule };

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+interface TallyConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface CreateAuthUrlOptions {
+    customerIdentifier: string;
+    redirectUrl: string;
+    scopes?: string[];
+    codeChallengeMethod?: "S256" | "plain";
+    suggestedLimits?: SpendLimits;
+}
+interface AuthUrlResult {
+    url: string;
+    state: string;
+    codeVerifier: string;
+    authorizationId: string;
+}
+interface ExchangeCodeOptions {
+    code: string;
+    codeVerifier: string;
+}
+interface TokenResult {
+    accessToken: string;
+    refreshToken: string;
+    tokenType: string;
+    expiresIn: number;
+    customerId: string;
+    installationId: string;
+}
+interface RefreshTokenOptions {
+    refreshToken: string;
+}
+interface PurchaseOptions {
+    customerToken: string;
+    amount: number;
+    currency?: string;
+    merchant: MerchantInfo;
+    context: TransactionContext;
+    walletId?: string;
+}
+interface LegacyPurchaseOptions {
+    amount: number;
+    merchantName: string;
+    merchantMcc?: string;
+    merchantCountry?: string;
+    currency?: string;
+    walletId?: string;
+    reasoning?: string;
+    installationId: string;
+}
+interface MerchantInfo {
+    name: string;
+    mcc?: string;
+    country?: string;
+}
+interface TransactionContext {
+    description: string;
+    category: string;
+    lineItems?: LineItem[];
+    externalReference?: string;
+    refundPolicy?: string;
+    metadata?: Record<string, unknown>;
+}
+interface LineItem {
+    name: string;
+    quantity: number;
+    price: number;
+}
+interface PurchaseResult {
+    transactionId: string;
+    status: "approved" | "pending_approval" | "declined";
+    decision: string;
+    decisionReason: string;
+    amount: number;
+    merchantName: string;
+    approvalDeadline?: string;
+}
+interface BalanceResult {
+    walletId: string;
+    fundingAmount: number;
+    spentAmount: number;
+    remaining: number;
+}
+interface SpendLimits {
+    maxPerTransaction?: number;
+    maxPerDay?: number;
+    maxPerMonth?: number;
+    requireApprovalAbove?: number;
+}
+interface WebhookEvent {
+    event: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+
+declare class AuthorizeModule {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Create an authorization URL for customer consent.
+     * Returns the URL to open in a popup/browser plus the PKCE code verifier.
+     */
+    createUrl(options: CreateAuthUrlOptions): Promise<AuthUrlResult>;
+    /**
+     * Exchange an authorization code for access + refresh tokens.
+     */
+    exchangeCode(options: ExchangeCodeOptions): Promise<TokenResult>;
+    /**
+     * Refresh an access token using a refresh token.
+     */
+    refreshToken(options: RefreshTokenOptions): Promise<TokenResult>;
+    /**
+     * Revoke an access or refresh token.
+     */
+    revoke(token: string): Promise<void>;
+}
+
+declare class BalanceModule {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Get wallet balance for a customer (using OAuth token).
+     */
+    get(customerToken: string, walletId?: string): Promise<BalanceResult>;
+}
+
+declare class PurchaseModule {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Make a purchase using an OAuth customer token.
+     */
+    create(options: PurchaseOptions): Promise<PurchaseResult>;
+    /**
+     * Make a purchase using the legacy API key + installation ID auth.
+     */
+    legacyCreate(options: LegacyPurchaseOptions): Promise<PurchaseResult>;
+}
+
+declare class WebhooksModule {
+    private secret?;
+    constructor(secret?: string | undefined);
+    /**
+     * Verify a webhook signature and parse the event.
+     * Uses Web Crypto API (works in Node 18+, Deno, Bun, Cloudflare Workers, etc.)
+     *
+     * @param body - Raw request body string
+     * @param signature - Value of X-Tally-Signature header
+     * @param tolerance - Max age in seconds (default: 300 = 5 minutes)
+     */
+    verify(body: string, signature: string, tolerance?: number): Promise<WebhookEvent>;
+}
+
+declare class Tally {
+    private baseUrl;
+    private apiKey;
+    /** OAuth authorization flow */
+    authorize: AuthorizeModule;
+    /** Purchase operations */
+    purchases: PurchaseModule;
+    /** Balance operations */
+    balances: BalanceModule;
+    /** Webhook signature verification */
+    webhooks: WebhooksModule;
+    constructor(config: TallyConfig);
+    /**
+     * Convenience method: Make a purchase (delegates to purchases.create).
+     */
+    purchase(options: PurchaseOptions): Promise<PurchaseResult>;
+    /**
+     * Convenience method: Get balance for a customer.
+     */
+    balance(customerToken: string, walletId?: string): Promise<BalanceResult>;
+    /**
+     * Check if this is a sandbox instance.
+     */
+    get isSandbox(): boolean;
+    /**
+     * Get the resolved base URL.
+     */
+    get url(): string;
+}
+
+declare class TallionError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(status: number, message: string, code?: string);
+}
+
+export { type AuthUrlResult, AuthorizeModule, BalanceModule, type BalanceResult, type CreateAuthUrlOptions, type ExchangeCodeOptions, type LegacyPurchaseOptions, type LineItem, type MerchantInfo, PurchaseModule, type PurchaseOptions, type PurchaseResult, type RefreshTokenOptions, type SpendLimits, TallionError, Tally, type TallyConfig, type TokenResult, type TransactionContext, type WebhookEvent, WebhooksModule };