@ritkey/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mmorgsmorgan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# @ritkey/sdk
+
+TypeScript SDK for Ritkey — the MPC wallet service for AI agents on Ritual Chain.
+
+```bash
+npm install @ritkey/sdk
+```
+
+Zero runtime dependencies. Works in Node 18+ and modern browsers / edge runtimes (Cloudflare Workers, Vercel, Deno).
+
+## Quick start
+
+```ts
+import { RitkeyClient } from '@ritkey/sdk';
+
+const client = new RitkeyClient({
+  baseUrl: 'https://ritkey.example.com',
+  apiKey: process.env.RITKEY_API_KEY,
+});
+
+// Create a wallet (Shamir 2-of-3 threshold). Save the shards — shown once.
+const wallet = await client.wallets.create({ label: 'agent-7' });
+console.log(wallet.address);
+console.log('agent shard:', wallet.agentShard);
+console.log('backup shard:', wallet.backupShard);
+
+// Sign + broadcast a transaction.
+const tx = await client.wallets.send({
+  walletId: wallet.walletId,
+  agentShard: wallet.agentShard,
+  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+  value: '0.01',
+});
+console.log(tx.hash, tx.explorer);
+```
+
+## Webhooks
+
+Register a webhook to receive real-time events. Save the `secret` — Ritkey shows it only once.
+
+```ts
+const hook = await client.webhooks.create({
+  url: 'https://yourapp.com/ritkey-hook',
+  events: ['tx.sent', 'wallet.funded', 'key.exported'],
+  label: 'production',
+});
+
+// Save somewhere safe:
+//   hook.id, hook.secret
+
+// Fire a test delivery to verify connectivity:
+await client.webhooks.test(hook.id);
+```
+
+### Verify deliveries on your receiver
+
+In your webhook handler, use `verifyWebhook` to check the HMAC signature and parse the event.
+
+**IMPORTANT**: pass the EXACT raw bytes Ritkey sent. If your framework JSON-parses before you see the body, the HMAC will mismatch. Use a raw body reader on the webhook route.
+
+```ts
+import express from 'express';
+import { verifyWebhook, isEvent } from '@ritkey/sdk';
+
+const app = express();
+
+app.post(
+  '/ritkey-hook',
+  express.raw({ type: 'application/json' }), // raw bytes
+  (req, res) => {
+    const result = verifyWebhook(
+      req.body, // Buffer
+      req.headers['ritkey-signature'],
+      process.env.RITKEY_WEBHOOK_SECRET
+    );
+
+    if (!result.ok) {
+      return res.status(401).send(result.reason);
+    }
+
+    // Type-narrow on the event type:
+    if (isEvent(result.event, 'tx.sent')) {
+      console.log('tx hash:', result.event.data.hash);
+    } else if (isEvent(result.event, 'key.exported')) {
+      console.log('SECURITY: key exported for', result.event.data.address);
+    }
+
+    // Always 200 quickly — Ritkey retries on non-2xx.
+    res.status(200).end();
+  }
+);
+```
+
+The verifier:
+- Validates HMAC-SHA256 over `<timestamp>.<rawBody>` using your secret
+- Rejects timestamps outside a 5-minute tolerance window (replay protection)
+- Uses `timingSafeEqual` (no early-exit / timing leaks)
+- Returns a typed event object on success
+
+### Idempotency
+
+Deliveries can repeat if your endpoint times out but actually succeeded. Use `Ritkey-Event-Id` as the dedup key:
+
+```ts
+const eventId = req.headers['ritkey-event-id'];
+if (await alreadyProcessed(eventId)) {
+  return res.status(200).end();
+}
+```
+
+## Events (polling)
+
+For environments where running a public HTTPS endpoint is impractical (CLIs, scripts, local dev), use the polling client:
+
+```ts
+const stop = client.events.subscribe({
+  types: ['tx.sent', 'wallet.funded'],
+  intervalMs: 3000,
+  onEvent: (event) => {
+    console.log(event.type, event.data);
+  },
+  onError: (err) => console.error(err),
+});
+
+// Later:
+stop();
+```
+
+Polling burns more API quota than webhooks. Use webhooks for production.
+
+## Import an existing wallet
+
+Bring your MetaMask / Rabby / hardware-wallet key under Ritkey management:
+
+```ts
+const wallet = await client.wallets.import_({
+  privateKey: '0x562f22a32039901eac...',
+  label: 'imported-from-metamask',
+});
+
+// Same address as MetaMask, now manageable through Ritkey.
+console.log(wallet.address);
+```
+
+## Export a key
+
+If you need full self-custody (back to MetaMask, hardware wallet, etc.):
+
+```ts
+const { privateKey, status } = await client.wallets.exportKey({
+  walletId: wallet.walletId,
+  agentShard: wallet.agentShard,
+});
+
+console.log('private key for MetaMask import:', privateKey);
+console.log('wallet status:', status); // 'archived'
+```
+
+After export, the wallet is **archived** in Ritkey. `/send`, `/sign`, `/deposit-ritual`, and a re-export all return 403. Sweep funds to a fresh wallet if you want to keep using Ritkey.
+
+## Errors
+
+Every error from the SDK is a `RitkeyError` with `status`, `code`, and the parsed response body:
+
+```ts
+import { RitkeyClient, RitkeyError } from '@ritkey/sdk';
+
+try {
+  await client.wallets.get('nope');
+} catch (err) {
+  if (err instanceof RitkeyError) {
+    console.log(err.status); // 404
+    console.log(err.code);   // optional error code from the server
+    console.log(err.body);   // full server response body
+  }
+}
+```
+
+## Reference
+
+### Construction
+
+```ts
+new RitkeyClient({
+  baseUrl: string;        // required, no trailing slash needed
+  apiKey?: string;        // required unless server is in OPEN_MODE
+  fetch?: typeof fetch;   // override (e.g. for Cloudflare Workers)
+  timeoutMs?: number;     // per-request timeout, default 30000
+});
+```
+
+### Wallets
+
+| Method | HTTP |
+|---|---|
+| `client.wallets.create(input?)` | `POST /wallets` |
+| `client.wallets.import_(input)` | `POST /wallets/import` |
+| `client.wallets.list()` | `GET /wallets` |
+| `client.wallets.me()` | `GET /wallets/me` |
+| `client.wallets.get(id)` | `GET /wallets/:id` |
+| `client.wallets.balance(id)` | `GET /wallets/:id/balance` |
+| `client.wallets.send(input)` | `POST /wallets/:id/send` |
+| `client.wallets.sign(input)` | `POST /wallets/:id/sign` |
+| `client.wallets.fund(id)` | `POST /wallets/:id/fund` |
+| `client.wallets.exportKey(input)` | `POST /wallets/:id/export-key` |
+| `client.wallets.sweepAndArchive(input)` | `POST /wallets/:id/sweep-and-archive` |
+| `client.wallets.freeze(id)` | `POST /wallets/:id/freeze` |
+| `client.wallets.unfreeze(id)` | `POST /wallets/:id/unfreeze` |
+
+### Webhooks
+
+| Method | HTTP |
+|---|---|
+| `client.webhooks.create(input)` | `POST /webhooks` |
+| `client.webhooks.list()` | `GET /webhooks` |
+| `client.webhooks.listEventTypes()` | `GET /webhooks/events` |
+| `client.webhooks.get(id)` | `GET /webhooks/:id` |
+| `client.webhooks.update(id, patch)` | `PATCH /webhooks/:id` |
+| `client.webhooks.delete(id)` | `DELETE /webhooks/:id` |
+| `client.webhooks.test(id)` | `POST /webhooks/:id/test` |
+| `client.webhooks.listDeliveries(id)` | `GET /webhooks/:id/deliveries` |
+
+### Events
+
+| Method | Behaviour |
+|---|---|
+| `client.events.list(opts?)` | One-shot fetch of recent events. |
+| `client.events.subscribe(opts)` | Polls `/events`, calls `onEvent` per new event. Returns a stop function. |
+
+### Verification helper
+
+| Function | Use |
+|---|---|
+| `verifyWebhook(rawBody, sigHeader, secret, opts?)` | Verify a webhook delivery on your receiver. Returns `{ ok, event } \| { ok: false, reason }`. |
+| `isEvent(event, type)` | Type-narrowing helper for verified events. |

package/dist/client/alerts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Alert rule management.
+ *
+ *   POST   /wallets/:id/alerts   create({ walletId, kind, config, ... })
+ *   GET    /wallets/:id/alerts   listForWallet(walletId)
+ *   GET    /alerts               list()
+ *   GET    /alerts/:id           get(id)
+ *   PATCH  /alerts/:id           update(id, patch)
+ *   DELETE /alerts/:id           delete(id)
+ */
+import type { HttpTransport } from '../transport.js';
+import type { AlertRule, CreateAlertRuleInput, UpdateAlertRuleInput } from '../types.js';
+export declare class AlertsClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    create(input: CreateAlertRuleInput): Promise<AlertRule>;
+    listForWallet(walletId: string): Promise<{
+        rules: AlertRule[];
+        count: number;
+    }>;
+    list(): Promise<{
+        rules: AlertRule[];
+        count: number;
+    }>;
+    get(ruleId: string): Promise<AlertRule>;
+    update(ruleId: string, patch: UpdateAlertRuleInput): Promise<AlertRule>;
+    delete(ruleId: string): Promise<void>;
+}
+//# sourceMappingURL=alerts.d.ts.map

package/dist/client/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../../src/client/alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EACV,SAAS,EACT,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAE1C,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC;IASvD,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAO/E,IAAI,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAItD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAIvC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC;IAQvE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5C"}

package/dist/client/alerts.js

@@ -0,0 +1,36 @@
+/**
+ * Alert rule management.
+ *
+ *   POST   /wallets/:id/alerts   create({ walletId, kind, config, ... })
+ *   GET    /wallets/:id/alerts   listForWallet(walletId)
+ *   GET    /alerts               list()
+ *   GET    /alerts/:id           get(id)
+ *   PATCH  /alerts/:id           update(id, patch)
+ *   DELETE /alerts/:id           delete(id)
+ */
+export class AlertsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async create(input) {
+        const { walletId, ...body } = input;
+        return this.http.request('POST', `/wallets/${encodeURIComponent(walletId)}/alerts`, body);
+    }
+    async listForWallet(walletId) {
+        return this.http.request('GET', `/wallets/${encodeURIComponent(walletId)}/alerts`);
+    }
+    async list() {
+        return this.http.request('GET', '/alerts');
+    }
+    async get(ruleId) {
+        return this.http.request('GET', `/alerts/${encodeURIComponent(ruleId)}`);
+    }
+    async update(ruleId, patch) {
+        return this.http.request('PATCH', `/alerts/${encodeURIComponent(ruleId)}`, patch);
+    }
+    async delete(ruleId) {
+        await this.http.request('DELETE', `/alerts/${encodeURIComponent(ruleId)}`);
+    }
+}
+//# sourceMappingURL=alerts.js.map

package/dist/client/alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.js","sourceRoot":"","sources":["../../src/client/alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,IAAmB;QAAnB,SAAI,GAAJ,IAAI,CAAe;IAAG,CAAC;IAEpD,KAAK,CAAC,MAAM,CAAC,KAA2B;QACtC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;QACpC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CACtB,MAAM,EACN,YAAY,kBAAkB,CAAC,QAAQ,CAAC,SAAS,EACjD,IAAI,CACL,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,QAAgB;QAClC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CACtB,KAAK,EACL,YAAY,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAClD,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAwC,KAAK,EAAE,SAAS,CAAC,CAAC;IACpF,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAc;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAY,KAAK,EAAE,WAAW,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,KAA2B;QACtD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CACtB,OAAO,EACP,WAAW,kBAAkB,CAAC,MAAM,CAAC,EAAE,EACvC,KAAK,CACN,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc;QACzB,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAO,QAAQ,EAAE,WAAW,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;CACF"}

package/dist/client/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Top-level RitkeyClient.
+ *
+ * Glues the transport to per-resource clients. Apps should construct one
+ * client and reuse it.
+ *
+ *   const client = new RitkeyClient({
+ *     baseUrl: 'https://ritkey.example.com',
+ *     apiKey: process.env.RITKEY_API_KEY,
+ *   });
+ *
+ *   const wallet = await client.wallets.create({ label: 'agent-7' });
+ *   const hook = await client.webhooks.create({ url: 'https://app/hook' });
+ *   const stop = client.events.subscribe({ onEvent: (e) => log(e) });
+ */
+import { WalletsClient } from './wallets.js';
+import { WebhooksClient } from './webhooks.js';
+import { AlertsClient } from './alerts.js';
+import { EventsClient } from '../events/poller.js';
+import type { RitkeyClientConfig } from '../types.js';
+export declare class RitkeyClient {
+    /** Wallet operations. */
+    readonly wallets: WalletsClient;
+    /** Webhook subscription management. */
+    readonly webhooks: WebhooksClient;
+    /** Alert rule management. */
+    readonly alerts: AlertsClient;
+    /** Event polling. */
+    readonly events: EventsClient;
+    constructor(config: RitkeyClientConfig);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,qBAAa,YAAY;IACvB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,qBAAqB;IACrB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;gBAElB,MAAM,EAAE,kBAAkB;CAOvC"}

package/dist/client/index.js

@@ -0,0 +1,38 @@
+/**
+ * Top-level RitkeyClient.
+ *
+ * Glues the transport to per-resource clients. Apps should construct one
+ * client and reuse it.
+ *
+ *   const client = new RitkeyClient({
+ *     baseUrl: 'https://ritkey.example.com',
+ *     apiKey: process.env.RITKEY_API_KEY,
+ *   });
+ *
+ *   const wallet = await client.wallets.create({ label: 'agent-7' });
+ *   const hook = await client.webhooks.create({ url: 'https://app/hook' });
+ *   const stop = client.events.subscribe({ onEvent: (e) => log(e) });
+ */
+import { HttpTransport } from '../transport.js';
+import { WalletsClient } from './wallets.js';
+import { WebhooksClient } from './webhooks.js';
+import { AlertsClient } from './alerts.js';
+import { EventsClient } from '../events/poller.js';
+export class RitkeyClient {
+    /** Wallet operations. */
+    wallets;
+    /** Webhook subscription management. */
+    webhooks;
+    /** Alert rule management. */
+    alerts;
+    /** Event polling. */
+    events;
+    constructor(config) {
+        const http = new HttpTransport(config);
+        this.wallets = new WalletsClient(http);
+        this.webhooks = new WebhooksClient(http);
+        this.alerts = new AlertsClient(http);
+        this.events = new EventsClient(http);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,MAAM,OAAO,YAAY;IACvB,yBAAyB;IAChB,OAAO,CAAgB;IAChC,uCAAuC;IAC9B,QAAQ,CAAiB;IAClC,6BAA6B;IACpB,MAAM,CAAe;IAC9B,qBAAqB;IACZ,MAAM,CAAe;IAE9B,YAAY,MAA0B;QACpC,MAAM,IAAI,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/client/wallets.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Wallet operations.
+ *
+ * Maps directly to the @ritkey/service HTTP API:
+ *
+ *   POST   /wallets                       create()
+ *   POST   /wallets/import                import_()
+ *   GET    /wallets                       list()
+ *   GET    /wallets/me                    me()
+ *   GET    /wallets/:id                   get(id)
+ *   GET    /wallets/:id/balance           balance(id)
+ *   POST   /wallets/:id/send              send(...)
+ *   POST   /wallets/:id/sign              sign(...)
+ *   POST   /wallets/:id/fund              fund(id)
+ *   POST   /wallets/:id/export-key        exportKey(...)
+ *   POST   /wallets/:id/sweep-and-archive sweepAndArchive(...)
+ *   POST   /wallets/:id/freeze            freeze(id)
+ *   POST   /wallets/:id/unfreeze          unfreeze(id)
+ */
+import type { HttpTransport } from '../transport.js';
+import type { CreatedWallet, Wallet, BalanceResponse, SendTransactionInput, SignMessageInput, ExportKeyInput, SweepInput, SentTransaction, ExportedKey } from '../types.js';
+export declare class WalletsClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    /**
+     * Create a new threshold (Shamir 2-of-3) wallet.
+     *
+     * The response includes the agentShard and backupShard ONCE. The SDK
+     * passes them through verbatim — your application is responsible for
+     * storing them safely.
+     */
+    create(input?: {
+        label?: string;
+    }): Promise<CreatedWallet>;
+    /**
+     * Import an existing private key (e.g. from MetaMask / Rabby) into Ritkey.
+     *
+     * The key is split into 2-of-3 Shamir shares. Server keeps share 1, you
+     * receive shares 2 and 3.
+     */
+    import_(input: {
+        privateKey: string;
+        label?: string;
+    }): Promise<CreatedWallet>;
+    list(): Promise<{
+        wallets: Wallet[];
+        count: number;
+    }>;
+    /** GET /wallets/me — returns the wallet bound to the current API key. */
+    me(): Promise<Wallet>;
+    get(walletId: string): Promise<Wallet>;
+    balance(walletId: string): Promise<BalanceResponse>;
+    /**
+     * Sign and broadcast a transaction.
+     *
+     * The agentShard is sent over the wire to the server, which combines it
+     * with its server shard to reconstruct the private key (in Rust, briefly,
+     * zeroized after signing). See SECURITY-MODEL.md for the exact trust model.
+     */
+    send(input: SendTransactionInput): Promise<SentTransaction>;
+    sign(input: SignMessageInput): Promise<{
+        signature: string;
+        address: string;
+    }>;
+    fund(walletId: string): Promise<{
+        hash: string;
+        from: string;
+        to: string;
+        amount: string;
+        explorer: string;
+    }>;
+    /**
+     * Export the private key. ⚠️ After a successful export the wallet is
+     * archived and can no longer be used through Ritkey. Save the privateKey
+     * (and consider sweeping funds to a fresh wallet).
+     */
+    exportKey(input: ExportKeyInput): Promise<ExportedKey>;
+    sweepAndArchive(input: SweepInput): Promise<{
+        status: 'archived';
+        walletId: string;
+        swept: boolean;
+        sweepTxHash: string | null;
+        sweepTo: string;
+        apiKeyGrantReleased: boolean;
+    }>;
+    freeze(walletId: string): Promise<{
+        status: 'frozen';
+        walletId: string;
+    }>;
+    unfreeze(walletId: string): Promise<{
+        status: 'active';
+        walletId: string;
+    }>;
+}
+//# sourceMappingURL=wallets.d.ts.map

package/dist/client/wallets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallets.d.ts","sourceRoot":"","sources":["../../src/client/wallets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EACN,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,eAAe,EACf,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAEhD;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAIhE;;;;;OAKG;IACG,OAAO,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAI9E,IAAI,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3D,yEAAyE;IACnE,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC;IAIrB,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAOzD;;;;;;OAMG;IACG,IAAI,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAS3D,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAS9E,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QACpC,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IAIF;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IAStD,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;QAChD,MAAM,EAAE,UAAU,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,OAAO,CAAC;QACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,CAAC;IASI,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAOzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAMlF"}

package/dist/client/wallets.js

@@ -0,0 +1,95 @@
+/**
+ * Wallet operations.
+ *
+ * Maps directly to the @ritkey/service HTTP API:
+ *
+ *   POST   /wallets                       create()
+ *   POST   /wallets/import                import_()
+ *   GET    /wallets                       list()
+ *   GET    /wallets/me                    me()
+ *   GET    /wallets/:id                   get(id)
+ *   GET    /wallets/:id/balance           balance(id)
+ *   POST   /wallets/:id/send              send(...)
+ *   POST   /wallets/:id/sign              sign(...)
+ *   POST   /wallets/:id/fund              fund(id)
+ *   POST   /wallets/:id/export-key        exportKey(...)
+ *   POST   /wallets/:id/sweep-and-archive sweepAndArchive(...)
+ *   POST   /wallets/:id/freeze            freeze(id)
+ *   POST   /wallets/:id/unfreeze          unfreeze(id)
+ */
+export class WalletsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Create a new threshold (Shamir 2-of-3) wallet.
+     *
+     * The response includes the agentShard and backupShard ONCE. The SDK
+     * passes them through verbatim — your application is responsible for
+     * storing them safely.
+     */
+    async create(input) {
+        return this.http.request('POST', '/wallets', input ?? {});
+    }
+    /**
+     * Import an existing private key (e.g. from MetaMask / Rabby) into Ritkey.
+     *
+     * The key is split into 2-of-3 Shamir shares. Server keeps share 1, you
+     * receive shares 2 and 3.
+     */
+    async import_(input) {
+        return this.http.request('POST', '/wallets/import', input);
+    }
+    async list() {
+        return this.http.request('GET', '/wallets');
+    }
+    /** GET /wallets/me — returns the wallet bound to the current API key. */
+    async me() {
+        return this.http.request('GET', '/wallets/me');
+    }
+    async get(walletId) {
+        return this.http.request('GET', `/wallets/${encodeURIComponent(walletId)}`);
+    }
+    async balance(walletId) {
+        return this.http.request('GET', `/wallets/${encodeURIComponent(walletId)}/balance`);
+    }
+    /**
+     * Sign and broadcast a transaction.
+     *
+     * The agentShard is sent over the wire to the server, which combines it
+     * with its server shard to reconstruct the private key (in Rust, briefly,
+     * zeroized after signing). See SECURITY-MODEL.md for the exact trust model.
+     */
+    async send(input) {
+        const { walletId, ...body } = input;
+        return this.http.request('POST', `/wallets/${encodeURIComponent(walletId)}/send`, body);
+    }
+    async sign(input) {
+        const { walletId, ...body } = input;
+        return this.http.request('POST', `/wallets/${encodeURIComponent(walletId)}/sign`, body);
+    }
+    async fund(walletId) {
+        return this.http.request('POST', `/wallets/${encodeURIComponent(walletId)}/fund`);
+    }
+    /**
+     * Export the private key. ⚠️ After a successful export the wallet is
+     * archived and can no longer be used through Ritkey. Save the privateKey
+     * (and consider sweeping funds to a fresh wallet).
+     */
+    async exportKey(input) {
+        const { walletId, ...rest } = input;
+        return this.http.request('POST', `/wallets/${encodeURIComponent(walletId)}/export-key`, { ...rest, confirm: true });
+    }
+    async sweepAndArchive(input) {
+        const { walletId, ...body } = input;
+        return this.http.request('POST', `/wallets/${encodeURIComponent(walletId)}/sweep-and-archive`, body);
+    }
+    async freeze(walletId) {
+        return this.http.request('POST', `/wallets/${encodeURIComponent(walletId)}/freeze`);
+    }
+    async unfreeze(walletId) {
+        return this.http.request('POST', `/wallets/${encodeURIComponent(walletId)}/unfreeze`);
+    }
+}
+//# sourceMappingURL=wallets.js.map

package/dist/client/wallets.js.map

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

package/dist/client/webhooks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Webhook subscription management.
+ *
+ *   POST   /webhooks                       create()
+ *   GET    /webhooks                       list()
+ *   GET    /webhooks/events                listEventTypes()
+ *   GET    /webhooks/:id                   get(id)
+ *   PATCH  /webhooks/:id                   update(id, ...)
+ *   DELETE /webhooks/:id                   delete(id)
+ *   POST   /webhooks/:id/test              test(id)
+ *   GET    /webhooks/:id/deliveries        listDeliveries(id)
+ */
+import type { HttpTransport } from '../transport.js';
+import type { CreatedWebhook, WebhookSubscription, CreateWebhookInput, UpdateWebhookInput, DeliveryLogEntry, EventType } from '../types.js';
+export declare class WebhooksClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    /** Create a new webhook subscription. Response includes `secret` — save it. */
+    create(input: CreateWebhookInput): Promise<CreatedWebhook>;
+    list(): Promise<{
+        subscriptions: WebhookSubscription[];
+        count: number;
+    }>;
+    listEventTypes(): Promise<{
+        eventTypes: EventType[];
+        wildcard: '*';
+        description: string;
+    }>;
+    get(subscriptionId: string): Promise<WebhookSubscription>;
+    update(subscriptionId: string, patch: UpdateWebhookInput): Promise<WebhookSubscription>;
+    delete(subscriptionId: string): Promise<void>;
+    /**
+     * Fire a `webhook.test` event to this subscription only.
+     * Useful for verifying connectivity and HMAC verification on your receiver.
+     */
+    test(subscriptionId: string): Promise<{
+        message: string;
+        eventId: string;
+    }>;
+    listDeliveries(subscriptionId: string, opts?: {
+        limit?: number;
+    }): Promise<{
+        deliveries: DeliveryLogEntry[];
+        count: number;
+    }>;
+}
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/client/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/client/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAEhD,+EAA+E;IACzE,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAI1D,IAAI,IAAI,OAAO,CAAC;QAAE,aAAa,EAAE,mBAAmB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAOxE,cAAc,IAAI,OAAO,CAAC;QAC9B,UAAU,EAAE,SAAS,EAAE,CAAC;QACxB,QAAQ,EAAE,GAAG,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IAII,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAOzD,MAAM,CACV,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC;IAQzB,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD;;;OAGG;IACG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAO3E,cAAc,CAClB,cAAc,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC;QAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAO9D"}