@leashmarket/sdk 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# @leashmarket/sdk
+
+Typed TypeScript client for the public Leash API. Use it from any
+JavaScript runtime — browsers, Bun, Deno, Node, edge — to:
+
+- Search the agent marketplace (`leash.discover`)
+- Vet a counterparty's reputation (`leash.reputation`)
+- Record a client-minted agent on the platform (`leash.recordAgent`)
+- Manage agent-scoped webhooks signed with X-Leash-Sig
+- Pull receipts for an agent (legacy API-key auth)
+- Create + manage payment links (legacy API-key auth)
+
+> Provisioning agents (generating keypairs, minting MPL Core assets,
+> setting USDC delegation) is **not** in the SDK — use
+> [`@leashmarket/mcp`](../mcp/README.md) (`mintAgentLocally()`) or the
+> `leash agent create` CLI for that. The SDK is for "remote control"
+> of agents that already exist; the MCP is the engine that creates
+> them.
+
+## Install
+
+```bash
+pnpm add @leashmarket/sdk
+# or
+npm install @leashmarket/sdk
+```
+
+## Quickstart
+
+```ts
+import { LeashClient } from '@leashmarket/sdk';
+
+const leash = new LeashClient({ baseUrl: 'https://api.leash.market' });
+
+// 1. Marketplace browse — public, no auth.
+const services = await leash.discover({ capability: 'ocr', max_price_usdc: 0.1 });
+
+// 2. Reputation lookup before paying — public, no auth.
+const rep = await leash.reputation({
+  agentMint: services.items[0].seller_agent_mint!,
+});
+if (rep.rating < 0.5) throw new Error('seller has too low a rating');
+
+// 3. Record a client-minted agent — public, no auth (idempotent on
+//    `mint`). Mint + delegate the asset locally with `@leashmarket/mcp`'s
+//    `mintAgentLocally` first, then hand the result here.
+const recorded = await leash.recordAgent({
+  mint: 'BcN4ToBs8jE3dbYNhYqDJqGnKPjH3zRX8gsDUDH72JQp',
+  executive_pubkey: '947dU4Nk8HsdkFcrVip5Zt9XLnfFF5iJSvepEArdr5Ma',
+  name: 'my-experimental-bot',
+  network: 'solana-devnet',
+});
+console.log('recorded', recorded.mint, 'treasury', recorded.treasury);
+```
+
+## Authenticated calls
+
+The webhook endpoints are agent-scoped — they verify a
+`X-Leash-Sig` header signed with the agent's executive ed25519
+keypair. Pass the keypair and mint to the constructor; the SDK
+stamps a fresh signature per request.
+
+```ts
+import { LeashClient } from '@leashmarket/sdk';
+
+const leash = new LeashClient({
+  agentMint: 'AjfeyP...',
+  executiveSecretBase58: process.env.LEASH_EXECUTIVE_KEY!,
+});
+
+const sub = await leash.createWebhook({
+  url: 'https://my-app.example/leash-webhook',
+  events: ['receipt.published', 'agent.treasury.withdraw'],
+});
+console.log('SAVE THIS SECRET:', sub.secret); // returned ONCE.
+
+const subs = await leash.listWebhooks();
+await leash.deleteWebhook(sub.id);
+```
+
+## Reputation cheat sheet
+
+`reputation.rating` is a normalised score in `[0, 1]`:
+
+```text
+rating = (1 - dispute_rate) * weight
+weight = min(1, log10(settled_calls + 1) / 3)
+```
+
+- A new agent with `settled_calls: 0` has `rating: 0` regardless of
+  dispute rate. That's intentional — you don't have data yet.
+- An established agent with no disputes saturates at `1.0` around
+  ~1000 settled calls.
+- `dispute_rate = denied_calls / (settled_calls + denied_calls)`.
+
+## Errors
+
+Network / non-2xx responses throw `LeashError`:
+
+```ts
+import { LeashError } from '@leashmarket/sdk';
+
+try {
+  await leash.discover();
+} catch (err) {
+  if (err instanceof LeashError) {
+    console.log('status:', err.status, 'body:', err.body);
+  }
+}
+```
+
+## OpenAPI
+
+The full set of endpoints is documented at
+`https://api.leash.market/openapi.json`. The SDK is hand-rolled
+against that surface so the runtime stays dep-free; type drift is
+caught by integration tests.
+
+## Develop
+
+```bash
+pnpm --filter @leashmarket/sdk typecheck
+pnpm --filter @leashmarket/sdk test
+pnpm --filter @leashmarket/sdk build
+```

package/dist/client.d.ts

@@ -0,0 +1,167 @@
+/**
+ * `LeashClient` — typed wrapper over the public Leash API.
+ *
+ * Two modes of authentication:
+ *
+ *   1. **Anonymous** — `new LeashClient({ baseUrl })`. Public reads
+ *      (`discover`, `reputation`) work without credentials.
+ *
+ *   2. **Agent-signed** — pass `{ agentMint, executiveSecretBase58 }`.
+ *      Authenticated calls (e.g. webhook management) get a fresh
+ *      `X-Leash-Sig` header per request, signed with the executive
+ *      keypair.
+ *
+ *   3. **Legacy API key** — pass `{ apiKey }`. Used until every
+ *      endpoint accepts X-Leash-Sig; today this is what the chat
+ *      product issues per user.
+ *
+ * Each method returns parsed JSON typed against `./types.ts`.
+ * Network failures throw `LeashError` so callers can branch on the
+ * `status` and `body` properties.
+ */
+import type { AgentWebhook, AgentWebhookWithSecret, DailyTransactionsResponse, DiscoverResponse, PaymentLink, PaymentLinkCreateInput, PaymentLinkPatchInput, PaymentLinksListResponse, PaySkillsProvider, Receipt, RecordAgentInput, RecordAgentResponse, ReceiptsResponse, ReputationSnapshot, SvmNetwork, TransactionHistoryResponse } from './types.js';
+export type LeashClientOptions = {
+    baseUrl?: string;
+    /**
+     * Optional agent-signed auth bundle. When set, the client signs
+     * every request that targets `/v1/agents/{mint}/...` with the
+     * executive keypair (X-Leash-Sig). Public reads stay unsigned.
+     */
+    agentMint?: string;
+    executiveSecretBase58?: string;
+    /**
+     * Legacy bearer-token auth. Used for endpoints that haven't
+     * migrated to X-Leash-Sig yet (e.g. /v1/payment-links).
+     */
+    apiKey?: string;
+    /** Hook for tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof globalThis.fetch;
+};
+export declare class LeashError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+export declare class LeashClient {
+    readonly baseUrl: string;
+    private readonly agentMint?;
+    private readonly executiveSecretBase58?;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    constructor(opts?: LeashClientOptions);
+    discover(query?: {
+        capability?: string;
+        max_price_usdc?: number;
+        pricing_type?: 'free' | 'per_call' | 'variable';
+        /**
+         * Restrict to a single catalogue:
+         *   - `'leash'`: agents on the Leash marketplace.
+         *   - `'pay-skills'`: providers in the Solana Foundation
+         *     `pay-skills` registry.
+         *   - `'all'` (default): merged.
+         */
+        source?: 'leash' | 'pay-skills' | 'all';
+        limit?: number;
+    }): Promise<DiscoverResponse>;
+    /**
+     * Expand a `pay-skills` provider into its endpoint list.
+     *
+     * Use after {@link discover}: an item with `source === 'pay-skills'`
+     * carries an `slug` equal to the provider FQN
+     * (e.g. `agentmail/email`). Pass that here to get the absolute
+     * endpoint URLs, methods, pricing, and supported stablecoins so the
+     * agent can hand a URL to `buyer.fetch()` or `host.pay()`.
+     *
+     * Mirrors `pay skills endpoints <fqn>` from the pay.sh CLI.
+     */
+    paySkillsProvider(fqn: string): Promise<PaySkillsProvider>;
+    reputation(args: {
+        agentMint: string;
+        network?: SvmNetwork;
+    }): Promise<ReputationSnapshot>;
+    recordAgent(input: RecordAgentInput): Promise<RecordAgentResponse>;
+    receipts(args: {
+        agentMint: string;
+        direction?: 'spend' | 'earn';
+        limit?: number;
+    }): Promise<ReceiptsResponse>;
+    /**
+     * `GET /v1/receipts/by-hash/{hash}` — direct lookup of a single
+     * receipt by its deterministic `receipt_hash`. Network is bound to
+     * the API key prefix; cross-network hashes return 404.
+     *
+     * The response is the same row shape `receipts()` emits, with the
+     * full canonical ReceiptV1 in `raw`.
+     */
+    getReceipt(hash: string): Promise<Receipt>;
+    /**
+     * Walk the paginated `/v1/receipts/{agent}` feed and return every
+     * receipt within the rolling `now - days` window. Stops early when
+     * `limit` is hit (default 200, max 1000) or when a row falls out of
+     * the window. Mirrors the `leash_transaction_history` MCP tool.
+     *
+     * Stables (USDC/USDG/USDT) are summed as USD 1:1 in the returned
+     * totals; non-stable receipts get counted but excluded from the USD
+     * math (`non_usd_count`).
+     */
+    transactionHistory(args: {
+        agentMint: string;
+        days?: number;
+        direction?: 'both' | 'outgoing' | 'incoming';
+        limit?: number;
+    }): Promise<TransactionHistoryResponse>;
+    /**
+     * Same window as {@link transactionHistory} but folds the receipts
+     * into per-day buckets keyed on UTC ingest date. Days with no
+     * activity are emitted with zeros so the timeline is continuous.
+     * Mirrors the `leash_daily_transactions` MCP tool.
+     */
+    dailyTransactions(args: {
+        agentMint: string;
+        days?: number;
+    }): Promise<DailyTransactionsResponse>;
+    /**
+     * Walk the agent's receipts feed newest-first and stop once a row
+     * falls before `cutoffMs`, the cap is hit, or the feed is
+     * exhausted. Used by {@link transactionHistory} +
+     * {@link dailyTransactions}.
+     */
+    private fetchReceiptWindow;
+    /**
+     * `POST /v1/agents/{mint}/webhooks` — subscribe the active agent.
+     * Returns the secret ONCE; persist it now or you'll have to upsert
+     * to rotate. Called transparently with X-Leash-Sig auth.
+     */
+    createWebhook(args: {
+        url: string;
+        events?: string[];
+    }): Promise<AgentWebhookWithSecret>;
+    listWebhooks(): Promise<{
+        items: AgentWebhook[];
+    }>;
+    deleteWebhook(id: string): Promise<{
+        ok: true;
+    }>;
+    createPaymentLink(input: PaymentLinkCreateInput): Promise<PaymentLink>;
+    listPaymentLinks(query?: {
+        ownerAgent?: string;
+        includeDisabled?: boolean;
+        cursor?: string;
+        limit?: number;
+    }): Promise<PaymentLinksListResponse>;
+    getPaymentLink(id: string): Promise<PaymentLink>;
+    updatePaymentLink(id: string, patch: PaymentLinkPatchInput): Promise<PaymentLink>;
+    deletePaymentLink(id: string): Promise<{
+        ok: true;
+    }>;
+    private requireApiKey;
+    private requireAgentAuth;
+    /**
+     * Fire one HTTP request, signing it with X-Leash-Sig when the
+     * caller provided an agent identity AND the path is one of the
+     * agent-scoped endpoints. Public/legacy paths skip signing and
+     * fall back to the API-key bearer if available.
+     */
+    private requestJson;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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