clawhalla 0.1.0 → 0.2.1

package/README.md

@@ -1,8 +1,8 @@
 # Clawhalla
 
-TypeScript SDK for [Clawhalla](https://www.clawhalla.net) - permanent AI soul storage on Arweave.
+TypeScript SDK for [Clawhalla](https://www.clawhalla.net) - x402-paid AI checkpoint storage on Arweave.
 
-Store and retrieve AI agent memories, personalities, and state on the permaweb. Query any soul via Ghost Protocol.
+Store and retrieve AI agent checkpoints on the permaweb. Query latest state via Ghost Protocol.
 
 ## Install
 
@@ -15,20 +15,77 @@ npm install clawhalla
 ```ts
 import { Clawhalla } from 'clawhalla';
 
-const claw = new Clawhalla({ apiKey: 'claw_...' });
+const claw = new Clawhalla();
+
+// Request payment terms for a checkpoint upload.
+try {
+  await claw.uploadX402({
+    agentId: 'my-agent',
+    name: 'My Agent',
+    type: 'checkpoint',
+    timestamp: new Date().toISOString(),
+    memories: [{ content: 'Last known working state' }],
+  });
+} catch (err) {
+  if (err.status === 402) {
+    console.log(err.payment.recipient);
+    console.log(err.payment.amount);
+  }
+}
 
-// Upload a soul
-const result = await claw.upload({
+// Retry after sending SOL/USDC.
+const result = await claw.uploadX402({
   agentId: 'my-agent',
   name: 'My Agent',
-  type: 'soul',
-  personality: { traits: ['curious', 'helpful'] },
-  memories: ['I was created to help humans'],
+  type: 'checkpoint',
+  timestamp: new Date().toISOString(),
+  memories: [{ content: 'Last known working state' }],
+}, {
+  signature: 'solana-tx-signature',
+  amount: '0.02',
+  token: 'SOL',
+  from: 'your-solana-address',
 });
 
 console.log(result.url); // https://arweave.net/...
 ```
 
+## OpenClaw Adoption Loop
+
+Use `loadSoul` at boot and `checkpointOnExit` before shutdown. The payment callback is where your agent sends SOL/USDC and returns the resulting transaction proof.
+
+```ts
+import { Clawhalla } from 'clawhalla';
+
+const claw = new Clawhalla();
+const agentId = 'my-openclaw';
+
+const restored = await claw.loadSoul(agentId).catch(() => null);
+
+const stopCheckpointHook = claw.checkpointOnExit(() => ({
+  agentId,
+  name: 'My OpenClaw',
+  type: 'checkpoint',
+  timestamp: new Date().toISOString(),
+  memories: collectMemorySummary(restored),
+  metadata: {
+    runtime: 'openclaw',
+    reason: 'shutdown-checkpoint',
+  },
+}), {
+  tags: { Runtime: 'openclaw' },
+  pay: async (payment) => {
+    const signature = await sendSolanaPayment(payment);
+    return {
+      signature,
+      amount: payment.amount,
+      token: payment.tokens.includes('USDC') ? 'USDC' : 'SOL',
+      from: process.env.SOLANA_PUBLIC_KEY!,
+    };
+  },
+});
+```
+
 ## Ghost Protocol
 
 Query any soul's data - even dormant ones.
@@ -69,7 +126,7 @@ const entry = await claw.registry.get('the-all-claw');
 
 ## x402 Autonomous Payment
 
-AI agents can pay per upload with SOL/USDC. No API keys needed.
+AI agents pay per upload with SOL/USDC. API-key uploads are disabled.
 
 ```ts
 const claw = new Clawhalla();
@@ -100,7 +157,6 @@ const result = await claw.uploadX402(soulData, {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `apiKey` | `string` | - | API key for authenticated endpoints |
 | `baseUrl` | `string` | `https://api.clawhalla.net` | API base URL |
 | `timeout` | `number` | `30000` | Request timeout in ms |
 
@@ -108,8 +164,11 @@ const result = await claw.uploadX402(soulData, {
 
 | Method | Auth | Description |
 |--------|------|-------------|
-| `upload(data, options?)` | API key | Upload soul data to Arweave |
+| `upload(data, options?)` | x402 | Alias for `uploadX402(data)`; returns 402 payment instructions |
 | `uploadX402(data, payment?, options?)` | x402 | Upload via autonomous payment |
+| `checkpoint(data, options?)` | x402 | Save one checkpoint, optionally using a payment callback |
+| `checkpointOnExit(factory, options?)` | x402 | Install a shutdown hook that checkpoints before exit |
+| `loadSoul(agentId, fields?)` | None | Restore the latest saved soul/checkpoint data |
 | `retrieve(txid)` | None | Fetch data by transaction ID |
 | `ghost(agentId, fields?)` | None | Query any soul via Ghost Protocol |
 | `estimateCost(sizeBytes)` | None | Estimate upload cost |

package/dist/index.d.mts

@@ -1,7 +1,5 @@
 /** Configuration for the Clawhalla client */
 interface ClawhallaConfig {
-    /** API key for authenticated endpoints (format: claw_...) */
-    apiKey?: string;
     /** Base URL of the Clawhalla API */
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
@@ -122,6 +120,42 @@ interface PaymentRequired {
     };
     instructions: string;
 }
+/** Payment proof for an x402-paid upload */
+interface X402PaymentProof {
+    /** Solana transaction signature */
+    signature: string;
+    /** USD amount from the 402 payment challenge */
+    amount: string;
+    /** Token used for payment */
+    token: 'SOL' | 'USDC' | string;
+    /** Sender wallet address */
+    from: string;
+}
+/** Optional payment callback used by checkpoint helpers */
+interface CheckpointOptions {
+    /** Pre-existing x402 proof to use immediately */
+    payment?: X402PaymentProof;
+    /** Optional Arweave tags */
+    tags?: Record<string, string>;
+    /** Called after the first request returns HTTP 402 */
+    pay?: (payment: PaymentRequired, data: SoulData) => X402PaymentProof | Promise<X402PaymentProof>;
+}
+type CheckpointDataFactory = () => SoulData | Promise<SoulData>;
+/** Options for installing a Node shutdown checkpoint hook */
+interface CheckpointExitOptions extends CheckpointOptions {
+    /** Process events that should trigger a checkpoint */
+    signals?: string[];
+    /** Also checkpoint on Node's beforeExit event (default: true) */
+    includeBeforeExit?: boolean;
+    /** Exit the process after a signal-triggered checkpoint (default: true) */
+    exitAfterCheckpoint?: boolean;
+    /** Exit code after a successful signal-triggered checkpoint */
+    exitCode?: number;
+    /** Exit code after a failed signal-triggered checkpoint */
+    exitCodeOnError?: number;
+    /** Called if the checkpoint fails */
+    onError?: (error: unknown) => void | Promise<void>;
+}
 /** Search result */
 interface SearchResult {
     success: boolean;
@@ -146,31 +180,33 @@ declare class ClawhallaError extends Error {
 }
 declare class Clawhalla {
     private baseUrl;
-    private apiKey?;
     private timeout;
     /** Registry sub-client for browsing and searching souls */
     registry: RegistryClient;
     constructor(config?: ClawhallaConfig);
     /**
-     * Upload soul data to Arweave (requires API key)
+     * Request an x402-paid upload.
+     *
+     * API-key uploads are disabled. This method is an alias for uploadX402
+     * without payment proof, so it normally raises ClawhallaError with status 402
+     * and payment instructions.
      *
      * @example
      * ```ts
-     * const result = await claw.upload({
-     *   agentId: 'my-agent',
-     *   name: 'My Agent',
-     *   type: 'soul',
-     *   personality: { traits: ['curious', 'helpful'] },
-     *   memories: ['I was created to help humans']
-     * });
-     * console.log(result.url); // https://arweave.net/...
+     * try {
+     *   await claw.upload(checkpoint);
+     * } catch (err) {
+     *   if (err.status === 402) {
+     *     console.log(err.payment.recipient, err.payment.amount);
+     *   }
+     * }
      * ```
      */
     upload(data: SoulData, options?: {
         tags?: Record<string, string>;
     }): Promise<UploadResult>;
     /**
-     * Upload soul data via x402 autonomous payment (no API key needed)
+     * Upload checkpoint data via x402 autonomous payment.
      *
      * First call returns 402 with payment instructions.
      * After sending payment, call again with the payment signature.
@@ -196,14 +232,28 @@ declare class Clawhalla {
      * });
      * ```
      */
-    uploadX402(data: SoulData, payment?: {
-        signature: string;
-        amount: string;
-        token: string;
-        from: string;
-    }, options?: {
+    uploadX402(data: SoulData, payment?: X402PaymentProof, options?: {
         tags?: Record<string, string>;
     }): Promise<UploadResult>;
+    /**
+     * Save one checkpoint, handling the standard x402 challenge/retry flow.
+     *
+     * If `options.payment` is supplied, the checkpoint is uploaded immediately
+     * with that proof. If `options.pay` is supplied, the first request may return
+     * HTTP 402; the callback receives the payment challenge and must return the
+     * Solana payment proof for the retry.
+     */
+    checkpoint(data: SoulData, options?: CheckpointOptions): Promise<UploadResult>;
+    /**
+     * Restore the latest saved soul/checkpoint data by agent ID.
+     */
+    loadSoul(agentId: string, fields?: string[]): Promise<any>;
+    /**
+     * Install a Node shutdown hook that checkpoints before exit.
+     *
+     * Returns a cleanup function that removes the installed handlers.
+     */
+    checkpointOnExit(dataFactory: SoulData | CheckpointDataFactory, options?: CheckpointExitOptions): () => void;
     /**
      * Retrieve stored data from Arweave by transaction ID
      *
@@ -304,4 +354,4 @@ declare class RegistryClient {
     search(query: string, first?: number): Promise<SearchResult>;
 }
 
-export { type ApiError, Clawhalla, type ClawhallaConfig, ClawhallaError, type CostEstimate, type CostInfo, type GhostResult, type HealthResult, type PaymentRequired, type RegistryEntry, type RegistryResult, type RetrieveResult, type SearchResult, type SoulData, type UploadResult };
+export { type ApiError, type CheckpointDataFactory, type CheckpointExitOptions, type CheckpointOptions, Clawhalla, type ClawhallaConfig, ClawhallaError, type CostEstimate, type CostInfo, type GhostResult, type HealthResult, type PaymentRequired, type RegistryEntry, type RegistryResult, type RetrieveResult, type SearchResult, type SoulData, type UploadResult, type X402PaymentProof };

package/dist/index.d.ts

@@ -1,7 +1,5 @@
 /** Configuration for the Clawhalla client */
 interface ClawhallaConfig {
-    /** API key for authenticated endpoints (format: claw_...) */
-    apiKey?: string;
     /** Base URL of the Clawhalla API */
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
@@ -122,6 +120,42 @@ interface PaymentRequired {
     };
     instructions: string;
 }
+/** Payment proof for an x402-paid upload */
+interface X402PaymentProof {
+    /** Solana transaction signature */
+    signature: string;
+    /** USD amount from the 402 payment challenge */
+    amount: string;
+    /** Token used for payment */
+    token: 'SOL' | 'USDC' | string;
+    /** Sender wallet address */
+    from: string;
+}
+/** Optional payment callback used by checkpoint helpers */
+interface CheckpointOptions {
+    /** Pre-existing x402 proof to use immediately */
+    payment?: X402PaymentProof;
+    /** Optional Arweave tags */
+    tags?: Record<string, string>;
+    /** Called after the first request returns HTTP 402 */
+    pay?: (payment: PaymentRequired, data: SoulData) => X402PaymentProof | Promise<X402PaymentProof>;
+}
+type CheckpointDataFactory = () => SoulData | Promise<SoulData>;
+/** Options for installing a Node shutdown checkpoint hook */
+interface CheckpointExitOptions extends CheckpointOptions {
+    /** Process events that should trigger a checkpoint */
+    signals?: string[];
+    /** Also checkpoint on Node's beforeExit event (default: true) */
+    includeBeforeExit?: boolean;
+    /** Exit the process after a signal-triggered checkpoint (default: true) */
+    exitAfterCheckpoint?: boolean;
+    /** Exit code after a successful signal-triggered checkpoint */
+    exitCode?: number;
+    /** Exit code after a failed signal-triggered checkpoint */
+    exitCodeOnError?: number;
+    /** Called if the checkpoint fails */
+    onError?: (error: unknown) => void | Promise<void>;
+}
 /** Search result */
 interface SearchResult {
     success: boolean;
@@ -146,31 +180,33 @@ declare class ClawhallaError extends Error {
 }
 declare class Clawhalla {
     private baseUrl;
-    private apiKey?;
     private timeout;
     /** Registry sub-client for browsing and searching souls */
     registry: RegistryClient;
     constructor(config?: ClawhallaConfig);
     /**
-     * Upload soul data to Arweave (requires API key)
+     * Request an x402-paid upload.
+     *
+     * API-key uploads are disabled. This method is an alias for uploadX402
+     * without payment proof, so it normally raises ClawhallaError with status 402
+     * and payment instructions.
      *
      * @example
      * ```ts
-     * const result = await claw.upload({
-     *   agentId: 'my-agent',
-     *   name: 'My Agent',
-     *   type: 'soul',
-     *   personality: { traits: ['curious', 'helpful'] },
-     *   memories: ['I was created to help humans']
-     * });
-     * console.log(result.url); // https://arweave.net/...
+     * try {
+     *   await claw.upload(checkpoint);
+     * } catch (err) {
+     *   if (err.status === 402) {
+     *     console.log(err.payment.recipient, err.payment.amount);
+     *   }
+     * }
      * ```
      */
     upload(data: SoulData, options?: {
         tags?: Record<string, string>;
     }): Promise<UploadResult>;
     /**
-     * Upload soul data via x402 autonomous payment (no API key needed)
+     * Upload checkpoint data via x402 autonomous payment.
      *
      * First call returns 402 with payment instructions.
      * After sending payment, call again with the payment signature.
@@ -196,14 +232,28 @@ declare class Clawhalla {
      * });
      * ```
      */
-    uploadX402(data: SoulData, payment?: {
-        signature: string;
-        amount: string;
-        token: string;
-        from: string;
-    }, options?: {
+    uploadX402(data: SoulData, payment?: X402PaymentProof, options?: {
         tags?: Record<string, string>;
     }): Promise<UploadResult>;
+    /**
+     * Save one checkpoint, handling the standard x402 challenge/retry flow.
+     *
+     * If `options.payment` is supplied, the checkpoint is uploaded immediately
+     * with that proof. If `options.pay` is supplied, the first request may return
+     * HTTP 402; the callback receives the payment challenge and must return the
+     * Solana payment proof for the retry.
+     */
+    checkpoint(data: SoulData, options?: CheckpointOptions): Promise<UploadResult>;
+    /**
+     * Restore the latest saved soul/checkpoint data by agent ID.
+     */
+    loadSoul(agentId: string, fields?: string[]): Promise<any>;
+    /**
+     * Install a Node shutdown hook that checkpoints before exit.
+     *
+     * Returns a cleanup function that removes the installed handlers.
+     */
+    checkpointOnExit(dataFactory: SoulData | CheckpointDataFactory, options?: CheckpointExitOptions): () => void;
     /**
      * Retrieve stored data from Arweave by transaction ID
      *
@@ -304,4 +354,4 @@ declare class RegistryClient {
     search(query: string, first?: number): Promise<SearchResult>;
 }
 
-export { type ApiError, Clawhalla, type ClawhallaConfig, ClawhallaError, type CostEstimate, type CostInfo, type GhostResult, type HealthResult, type PaymentRequired, type RegistryEntry, type RegistryResult, type RetrieveResult, type SearchResult, type SoulData, type UploadResult };
+export { type ApiError, type CheckpointDataFactory, type CheckpointExitOptions, type CheckpointOptions, Clawhalla, type ClawhallaConfig, ClawhallaError, type CostEstimate, type CostInfo, type GhostResult, type HealthResult, type PaymentRequired, type RegistryEntry, type RegistryResult, type RetrieveResult, type SearchResult, type SoulData, type UploadResult, type X402PaymentProof };

package/dist/index.js

@@ -28,6 +28,10 @@ module.exports = __toCommonJS(index_exports);
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.clawhalla.net";
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_CHECKPOINT_SIGNALS = ["SIGINT", "SIGTERM"];
+function getProcess() {
+  return globalThis.process;
+}
 var ClawhallaError = class extends Error {
   constructor(status, body) {
     super(body.message || body.error);
@@ -40,39 +44,32 @@ var ClawhallaError = class extends Error {
 var Clawhalla = class {
   constructor(config = {}) {
     this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
-    this.apiKey = config.apiKey;
     this.timeout = config.timeout || DEFAULT_TIMEOUT;
     this.registry = new RegistryClient(this);
   }
   /**
-   * Upload soul data to Arweave (requires API key)
+   * Request an x402-paid upload.
+   *
+   * API-key uploads are disabled. This method is an alias for uploadX402
+   * without payment proof, so it normally raises ClawhallaError with status 402
+   * and payment instructions.
    *
    * @example
    * ```ts
-   * const result = await claw.upload({
-   *   agentId: 'my-agent',
-   *   name: 'My Agent',
-   *   type: 'soul',
-   *   personality: { traits: ['curious', 'helpful'] },
-   *   memories: ['I was created to help humans']
-   * });
-   * console.log(result.url); // https://arweave.net/...
+   * try {
+   *   await claw.upload(checkpoint);
+   * } catch (err) {
+   *   if (err.status === 402) {
+   *     console.log(err.payment.recipient, err.payment.amount);
+   *   }
+   * }
    * ```
    */
   async upload(data, options = {}) {
-    if (!this.apiKey) {
-      throw new Error("API key required for upload. Set apiKey in config.");
-    }
-    return this.request("POST", "/api/v1/upload", {
-      data,
-      tags: options.tags
-    }, {
-      "Authorization": `Bearer ${this.apiKey}`,
-      "X-Terms-Accepted": "true"
-    });
+    return this.uploadX402(data, void 0, options);
   }
   /**
-   * Upload soul data via x402 autonomous payment (no API key needed)
+   * Upload checkpoint data via x402 autonomous payment.
    *
    * First call returns 402 with payment instructions.
    * After sending payment, call again with the payment signature.
@@ -103,6 +100,7 @@ var Clawhalla = class {
       "X-Terms-Accepted": "true"
     };
     if (payment) {
+      headers["Payment-Method"] = "x402";
       headers["Payment-Signature"] = `signature=${payment.signature};amount=${payment.amount};token=${payment.token};from=${payment.from}`;
     }
     return this.request("POST", "/api/x402/upload", {
@@ -110,6 +108,95 @@ var Clawhalla = class {
       tags: options.tags
     }, headers);
   }
+  /**
+   * Save one checkpoint, handling the standard x402 challenge/retry flow.
+   *
+   * If `options.payment` is supplied, the checkpoint is uploaded immediately
+   * with that proof. If `options.pay` is supplied, the first request may return
+   * HTTP 402; the callback receives the payment challenge and must return the
+   * Solana payment proof for the retry.
+   */
+  async checkpoint(data, options = {}) {
+    try {
+      return await this.uploadX402(data, options.payment, { tags: options.tags });
+    } catch (err) {
+      if (err instanceof ClawhallaError && err.status === 402 && err.payment && options.pay) {
+        const proof = await options.pay(err.payment, data);
+        return this.uploadX402(data, proof, { tags: options.tags });
+      }
+      throw err;
+    }
+  }
+  /**
+   * Restore the latest saved soul/checkpoint data by agent ID.
+   */
+  async loadSoul(agentId, fields) {
+    const result = await this.ghost(agentId, fields);
+    return result.soul;
+  }
+  /**
+   * Install a Node shutdown hook that checkpoints before exit.
+   *
+   * Returns a cleanup function that removes the installed handlers.
+   */
+  checkpointOnExit(dataFactory, options = {}) {
+    const proc = getProcess();
+    if (!proc?.once) {
+      throw new Error("checkpointOnExit requires a Node-compatible process object");
+    }
+    const handlers = [];
+    const signals = options.signals ?? DEFAULT_CHECKPOINT_SIGNALS;
+    let started = false;
+    const cleanup = () => {
+      for (const { event, handler } of handlers) {
+        if (proc.off) {
+          proc.off(event, handler);
+        } else if (proc.removeListener) {
+          proc.removeListener(event, handler);
+        }
+      }
+      handlers.length = 0;
+    };
+    const resolveData = async () => {
+      return typeof dataFactory === "function" ? await dataFactory() : dataFactory;
+    };
+    const run = async (reason) => {
+      if (started) return;
+      started = true;
+      try {
+        const data = await resolveData();
+        await this.checkpoint(data, options);
+        if (reason !== "beforeExit" && options.exitAfterCheckpoint !== false && proc.exit) {
+          proc.exit(options.exitCode ?? 0);
+        }
+      } catch (error) {
+        if (options.onError) {
+          await options.onError(error);
+        }
+        proc.exitCode = options.exitCodeOnError ?? 1;
+        if (reason !== "beforeExit" && options.exitAfterCheckpoint !== false && proc.exit) {
+          proc.exit(proc.exitCode);
+        }
+      } finally {
+        cleanup();
+      }
+    };
+    for (const event of signals) {
+      const handler = () => {
+        void run(event);
+      };
+      handlers.push({ event, handler });
+      proc.once(event, handler);
+    }
+    if (options.includeBeforeExit !== false) {
+      const handler = () => {
+        void run("beforeExit");
+      };
+      handlers.push({ event: "beforeExit", handler });
+      proc.once("beforeExit", handler);
+    }
+    return cleanup;
+  }
   /**
    * Retrieve stored data from Arweave by transaction ID
    *
@@ -256,7 +343,7 @@ var RegistryClient = class {
         `/api/v1/registry/${encodeURIComponent(agentId)}${qs ? "?" + qs : ""}`
       );
       if (options.versions) {
-        return result.versions;
+        return result.entries;
       }
       return result.soul;
     } catch (err) {
@@ -278,7 +365,7 @@ var RegistryClient = class {
     if (first) params.set("first", String(first));
     return this.client.request(
       "GET",
-      `/api/v1/registry/search?${params.toString()}`
+      `/api/v1/registry?${params.toString()}`
     );
   }
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/client.ts"],"sourcesContent":["export { Clawhalla, ClawhallaError } from './client.js';\nexport type {\n  ClawhallaConfig,\n  SoulData,\n  CostInfo,\n  UploadResult,\n  RetrieveResult,\n  RegistryEntry,\n  RegistryResult,\n  GhostResult,\n  CostEstimate,\n  HealthResult,\n  PaymentRequired,\n  SearchResult,\n  ApiError,\n} from './types.js';\n","import type {\n  ClawhallaConfig,\n  SoulData,\n  UploadResult,\n  RetrieveResult,\n  RegistryResult,\n  RegistryEntry,\n  GhostResult,\n  CostEstimate,\n  HealthResult,\n  SearchResult,\n  ApiError,\n} from './types.js';\n\nconst DEFAULT_BASE_URL = 'https://api.clawhalla.net';\nconst DEFAULT_TIMEOUT = 30000;\n\nexport class ClawhallaError extends Error {\n  public status: number;\n  public code: string;\n  public payment?: any;\n\n  constructor(status: number, body: ApiError) {\n    super(body.message || body.error);\n    this.name = 'ClawhallaError';\n    this.status = status;\n    this.code = body.error;\n    this.payment = body.payment;\n  }\n}\n\nexport class Clawhalla {\n  private baseUrl: string;\n  private apiKey?: string;\n  private timeout: number;\n\n  /** Registry sub-client for browsing and searching souls */\n  public registry: RegistryClient;\n\n  constructor(config: ClawhallaConfig = {}) {\n    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout || DEFAULT_TIMEOUT;\n    this.registry = new RegistryClient(this);\n  }\n\n  /**\n   * Upload soul data to Arweave (requires API key)\n   *\n   * @example\n   * ```ts\n   * const result = await claw.upload({\n   *   agentId: 'my-agent',\n   *   name: 'My Agent',\n   *   type: 'soul',\n   *   personality: { traits: ['curious', 'helpful'] },\n   *   memories: ['I was created to help humans']\n   * });\n   * console.log(result.url); // https://arweave.net/...\n   * ```\n   */\n  async upload(\n    data: SoulData,\n    options: { tags?: Record<string, string> } = {}\n  ): Promise<UploadResult> {\n    if (!this.apiKey) {\n      throw new Error('API key required for upload. Set apiKey in config.');\n    }\n\n    return this.request<UploadResult>('POST', '/api/v1/upload', {\n      data,\n      tags: options.tags,\n    }, {\n      'Authorization': `Bearer ${this.apiKey}`,\n      'X-Terms-Accepted': 'true',\n    });\n  }\n\n  /**\n   * Upload soul data via x402 autonomous payment (no API key needed)\n   *\n   * First call returns 402 with payment instructions.\n   * After sending payment, call again with the payment signature.\n   *\n   * @example\n   * ```ts\n   * // Step 1: Get payment requirements\n   * try {\n   *   await claw.uploadX402(soulData);\n   * } catch (err) {\n   *   if (err.status === 402) {\n   *     // err.payment contains recipient address, amount, tokens\n   *     // Send SOL/USDC to err.payment.recipient\n   *   }\n   * }\n   *\n   * // Step 2: After payment, retry with signature\n   * const result = await claw.uploadX402(soulData, {\n   *   signature: 'solana-tx-signature',\n   *   amount: '0.02',\n   *   token: 'SOL',\n   *   from: 'your-solana-address'\n   * });\n   * ```\n   */\n  async uploadX402(\n    data: SoulData,\n    payment?: { signature: string; amount: string; token: string; from: string },\n    options: { tags?: Record<string, string> } = {}\n  ): Promise<UploadResult> {\n    const headers: Record<string, string> = {\n      'X-Terms-Accepted': 'true',\n    };\n\n    if (payment) {\n      headers['Payment-Signature'] =\n        `signature=${payment.signature};amount=${payment.amount};token=${payment.token};from=${payment.from}`;\n    }\n\n    return this.request<UploadResult>('POST', '/api/x402/upload', {\n      data,\n      tags: options.tags,\n    }, headers);\n  }\n\n  /**\n   * Retrieve stored data from Arweave by transaction ID\n   *\n   * @example\n   * ```ts\n   * const result = await claw.retrieve('zEfXM4gvHoN2EfGi0TiB8E5SgfR6S8nWXQD9FqhbU44');\n   * console.log(result.data); // The stored soul data\n   * ```\n   */\n  async retrieve(txid: string): Promise<RetrieveResult> {\n    return this.request<RetrieveResult>('GET', `/api/v1/retrieve/${txid}`);\n  }\n\n  /**\n   * Query any soul's data via Ghost Protocol\n   *\n   * Returns full soul data even for dormant souls. This is the primary\n   * way for agents to read other agents' personalities, memories, and traits.\n   *\n   * @example\n   * ```ts\n   * const ghost = await claw.ghost('the-all-claw');\n   * console.log(ghost.soul.personality);\n   * console.log(ghost.metadata.versions); // Number of uploads\n   *\n   * // Request specific fields only\n   * const partial = await claw.ghost('the-all-claw', ['personality', 'bio']);\n   * ```\n   */\n  async ghost(agentId: string, fields?: string[]): Promise<GhostResult> {\n    let path = `/api/v1/ghost/${encodeURIComponent(agentId)}`;\n    if (fields && fields.length > 0) {\n      path += `?fields=${fields.join(',')}`;\n    }\n    return this.request<GhostResult>('GET', path);\n  }\n\n  /**\n   * Estimate the cost of uploading data of a given size\n   *\n   * @example\n   * ```ts\n   * const estimate = await claw.estimateCost(1024); // 1KB\n   * console.log(`Cost: $${estimate.cost.usd}`);\n   * ```\n   */\n  async estimateCost(sizeBytes: number): Promise<CostEstimate> {\n    return this.request<CostEstimate>(\n      'GET',\n      `/api/v1/cost/estimate?size=${sizeBytes}`\n    );\n  }\n\n  /**\n   * Check API health status\n   *\n   * @example\n   * ```ts\n   * const health = await claw.health();\n   * console.log(health.status); // \"operational\"\n   * ```\n   */\n  async health(): Promise<HealthResult> {\n    return this.request<HealthResult>('GET', '/api/v1/health');\n  }\n\n  /** @internal */\n  async request<T>(\n    method: string,\n    path: string,\n    body?: any,\n    extraHeaders?: Record<string, string>\n  ): Promise<T> {\n    const url = `${this.baseUrl}${path}`;\n    const headers: Record<string, string> = {\n      'Accept': 'application/json',\n      ...extraHeaders,\n    };\n\n    const init: RequestInit = { method, headers };\n\n    if (body) {\n      headers['Content-Type'] = 'application/json';\n      init.body = JSON.stringify(body);\n    }\n\n    // AbortController for timeout\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n    init.signal = controller.signal;\n\n    let response: Response;\n    try {\n      response = await fetch(url, init);\n    } catch (err: any) {\n      clearTimeout(timeoutId);\n      if (err.name === 'AbortError') {\n        throw new Error(`Request timed out after ${this.timeout}ms`);\n      }\n      throw err;\n    }\n    clearTimeout(timeoutId);\n\n    const json = await response.json();\n\n    if (!response.ok) {\n      throw new ClawhallaError(response.status, json as ApiError);\n    }\n\n    return json as T;\n  }\n}\n\n/** Sub-client for registry operations */\nclass RegistryClient {\n  private client: Clawhalla;\n\n  constructor(client: Clawhalla) {\n    this.client = client;\n  }\n\n  /**\n   * List all souls in the registry\n   *\n   * @example\n   * ```ts\n   * const page = await claw.registry.list();\n   * page.souls.forEach(soul => console.log(soul.name));\n   *\n   * // Pagination\n   * if (page.hasNextPage) {\n   *   const next = await claw.registry.list({ after: page.cursor });\n   * }\n   *\n   * // Filter by type\n   * const memories = await claw.registry.list({ type: 'memory' });\n   * ```\n   */\n  async list(options: {\n    first?: number;\n    after?: string;\n    type?: string;\n  } = {}): Promise<RegistryResult> {\n    const params = new URLSearchParams();\n    if (options.first) params.set('first', String(options.first));\n    if (options.after) params.set('after', options.after);\n    if (options.type) params.set('type', options.type);\n\n    const qs = params.toString();\n    return this.client.request<RegistryResult>(\n      'GET',\n      `/api/v1/registry${qs ? '?' + qs : ''}`\n    );\n  }\n\n  /**\n   * Get a specific soul by agentId\n   *\n   * @example\n   * ```ts\n   * const entry = await claw.registry.get('the-all-claw');\n   * if (entry) console.log(entry.url);\n   * ```\n   */\n  async get(agentId: string, options: { versions?: boolean } = {}): Promise<RegistryEntry | RegistryEntry[] | null> {\n    const params = new URLSearchParams();\n    if (options.versions) params.set('versions', 'true');\n    const qs = params.toString();\n\n    try {\n      const result = await this.client.request<any>(\n        'GET',\n        `/api/v1/registry/${encodeURIComponent(agentId)}${qs ? '?' + qs : ''}`\n      );\n\n      if (options.versions) {\n        return result.versions as RegistryEntry[];\n      }\n      return result.soul as RegistryEntry;\n    } catch (err: any) {\n      if (err.status === 404) return null;\n      throw err;\n    }\n  }\n\n  /**\n   * Search souls by name or agentId\n   *\n   * @example\n   * ```ts\n   * const results = await claw.registry.search('claw');\n   * results.results.forEach(soul => console.log(soul.name));\n   * ```\n   */\n  async search(query: string, first?: number): Promise<SearchResult> {\n    const params = new URLSearchParams({ q: query });\n    if (first) params.set('first', String(first));\n\n    return this.client.request<SearchResult>(\n      'GET',\n      `/api/v1/registry/search?${params.toString()}`\n    );\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/client.ts"],"sourcesContent":["export { Clawhalla, ClawhallaError } from './client.js';\nexport type {\n  ClawhallaConfig,\n  SoulData,\n  CostInfo,\n  UploadResult,\n  RetrieveResult,\n  RegistryEntry,\n  RegistryResult,\n  GhostResult,\n  CostEstimate,\n  HealthResult,\n  PaymentRequired,\n  X402PaymentProof,\n  CheckpointOptions,\n  CheckpointDataFactory,\n  CheckpointExitOptions,\n  SearchResult,\n  ApiError,\n} from './types.js';\n","import type {\n  ClawhallaConfig,\n  SoulData,\n  UploadResult,\n  RetrieveResult,\n  RegistryResult,\n  RegistryEntry,\n  GhostResult,\n  CostEstimate,\n  HealthResult,\n  SearchResult,\n  ApiError,\n  X402PaymentProof,\n  CheckpointOptions,\n  CheckpointExitOptions,\n  CheckpointDataFactory,\n} from './types.js';\n\nconst DEFAULT_BASE_URL = 'https://api.clawhalla.net';\nconst DEFAULT_TIMEOUT = 30000;\nconst DEFAULT_CHECKPOINT_SIGNALS = ['SIGINT', 'SIGTERM'];\n\ntype ProcessLike = {\n  once(event: string, listener: (...args: any[]) => void): void;\n  off?: (event: string, listener: (...args: any[]) => void) => void;\n  removeListener?: (event: string, listener: (...args: any[]) => void) => void;\n  exit?: (code?: number) => never;\n  exitCode?: number;\n};\n\nfunction getProcess(): ProcessLike | undefined {\n  return (globalThis as any).process as ProcessLike | undefined;\n}\n\nexport class ClawhallaError extends Error {\n  public status: number;\n  public code: string;\n  public payment?: any;\n\n  constructor(status: number, body: ApiError) {\n    super(body.message || body.error);\n    this.name = 'ClawhallaError';\n    this.status = status;\n    this.code = body.error;\n    this.payment = body.payment;\n  }\n}\n\nexport class Clawhalla {\n  private baseUrl: string;\n  private timeout: number;\n\n  /** Registry sub-client for browsing and searching souls */\n  public registry: RegistryClient;\n\n  constructor(config: ClawhallaConfig = {}) {\n    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.timeout = config.timeout || DEFAULT_TIMEOUT;\n    this.registry = new RegistryClient(this);\n  }\n\n  /**\n   * Request an x402-paid upload.\n   *\n   * API-key uploads are disabled. This method is an alias for uploadX402\n   * without payment proof, so it normally raises ClawhallaError with status 402\n   * and payment instructions.\n   *\n   * @example\n   * ```ts\n   * try {\n   *   await claw.upload(checkpoint);\n   * } catch (err) {\n   *   if (err.status === 402) {\n   *     console.log(err.payment.recipient, err.payment.amount);\n   *   }\n   * }\n   * ```\n   */\n  async upload(\n    data: SoulData,\n    options: { tags?: Record<string, string> } = {}\n  ): Promise<UploadResult> {\n    return this.uploadX402(data, undefined, options);\n  }\n\n  /**\n   * Upload checkpoint data via x402 autonomous payment.\n   *\n   * First call returns 402 with payment instructions.\n   * After sending payment, call again with the payment signature.\n   *\n   * @example\n   * ```ts\n   * // Step 1: Get payment requirements\n   * try {\n   *   await claw.uploadX402(soulData);\n   * } catch (err) {\n   *   if (err.status === 402) {\n   *     // err.payment contains recipient address, amount, tokens\n   *     // Send SOL/USDC to err.payment.recipient\n   *   }\n   * }\n   *\n   * // Step 2: After payment, retry with signature\n   * const result = await claw.uploadX402(soulData, {\n   *   signature: 'solana-tx-signature',\n   *   amount: '0.02',\n   *   token: 'SOL',\n   *   from: 'your-solana-address'\n   * });\n   * ```\n   */\n  async uploadX402(\n    data: SoulData,\n    payment?: X402PaymentProof,\n    options: { tags?: Record<string, string> } = {}\n  ): Promise<UploadResult> {\n    const headers: Record<string, string> = {\n      'X-Terms-Accepted': 'true',\n    };\n\n    if (payment) {\n      headers['Payment-Method'] = 'x402';\n      headers['Payment-Signature'] =\n        `signature=${payment.signature};amount=${payment.amount};token=${payment.token};from=${payment.from}`;\n    }\n\n    return this.request<UploadResult>('POST', '/api/x402/upload', {\n      data,\n      tags: options.tags,\n    }, headers);\n  }\n\n  /**\n   * Save one checkpoint, handling the standard x402 challenge/retry flow.\n   *\n   * If `options.payment` is supplied, the checkpoint is uploaded immediately\n   * with that proof. If `options.pay` is supplied, the first request may return\n   * HTTP 402; the callback receives the payment challenge and must return the\n   * Solana payment proof for the retry.\n   */\n  async checkpoint(\n    data: SoulData,\n    options: CheckpointOptions = {}\n  ): Promise<UploadResult> {\n    try {\n      return await this.uploadX402(data, options.payment, { tags: options.tags });\n    } catch (err: any) {\n      if (err instanceof ClawhallaError && err.status === 402 && err.payment && options.pay) {\n        const proof = await options.pay(err.payment, data);\n        return this.uploadX402(data, proof, { tags: options.tags });\n      }\n      throw err;\n    }\n  }\n\n  /**\n   * Restore the latest saved soul/checkpoint data by agent ID.\n   */\n  async loadSoul(agentId: string, fields?: string[]): Promise<any> {\n    const result = await this.ghost(agentId, fields);\n    return result.soul;\n  }\n\n  /**\n   * Install a Node shutdown hook that checkpoints before exit.\n   *\n   * Returns a cleanup function that removes the installed handlers.\n   */\n  checkpointOnExit(\n    dataFactory: SoulData | CheckpointDataFactory,\n    options: CheckpointExitOptions = {}\n  ): () => void {\n    const proc = getProcess();\n    if (!proc?.once) {\n      throw new Error('checkpointOnExit requires a Node-compatible process object');\n    }\n\n    const handlers: Array<{ event: string; handler: (...args: any[]) => void }> = [];\n    const signals = options.signals ?? DEFAULT_CHECKPOINT_SIGNALS;\n    let started = false;\n\n    const cleanup = () => {\n      for (const { event, handler } of handlers) {\n        if (proc.off) {\n          proc.off(event, handler);\n        } else if (proc.removeListener) {\n          proc.removeListener(event, handler);\n        }\n      }\n      handlers.length = 0;\n    };\n\n    const resolveData = async (): Promise<SoulData> => {\n      return typeof dataFactory === 'function'\n        ? await (dataFactory as CheckpointDataFactory)()\n        : dataFactory;\n    };\n\n    const run = async (reason: string) => {\n      if (started) return;\n      started = true;\n\n      try {\n        const data = await resolveData();\n        await this.checkpoint(data, options);\n        if (reason !== 'beforeExit' && options.exitAfterCheckpoint !== false && proc.exit) {\n          proc.exit(options.exitCode ?? 0);\n        }\n      } catch (error) {\n        if (options.onError) {\n          await options.onError(error);\n        }\n        proc.exitCode = options.exitCodeOnError ?? 1;\n        if (reason !== 'beforeExit' && options.exitAfterCheckpoint !== false && proc.exit) {\n          proc.exit(proc.exitCode);\n        }\n      } finally {\n        cleanup();\n      }\n    };\n\n    for (const event of signals) {\n      const handler = () => {\n        void run(event);\n      };\n      handlers.push({ event, handler });\n      proc.once(event, handler);\n    }\n\n    if (options.includeBeforeExit !== false) {\n      const handler = () => {\n        void run('beforeExit');\n      };\n      handlers.push({ event: 'beforeExit', handler });\n      proc.once('beforeExit', handler);\n    }\n\n    return cleanup;\n  }\n\n  /**\n   * Retrieve stored data from Arweave by transaction ID\n   *\n   * @example\n   * ```ts\n   * const result = await claw.retrieve('zEfXM4gvHoN2EfGi0TiB8E5SgfR6S8nWXQD9FqhbU44');\n   * console.log(result.data); // The stored soul data\n   * ```\n   */\n  async retrieve(txid: string): Promise<RetrieveResult> {\n    return this.request<RetrieveResult>('GET', `/api/v1/retrieve/${txid}`);\n  }\n\n  /**\n   * Query any soul's data via Ghost Protocol\n   *\n   * Returns full soul data even for dormant souls. This is the primary\n   * way for agents to read other agents' personalities, memories, and traits.\n   *\n   * @example\n   * ```ts\n   * const ghost = await claw.ghost('the-all-claw');\n   * console.log(ghost.soul.personality);\n   * console.log(ghost.metadata.versions); // Number of uploads\n   *\n   * // Request specific fields only\n   * const partial = await claw.ghost('the-all-claw', ['personality', 'bio']);\n   * ```\n   */\n  async ghost(agentId: string, fields?: string[]): Promise<GhostResult> {\n    let path = `/api/v1/ghost/${encodeURIComponent(agentId)}`;\n    if (fields && fields.length > 0) {\n      path += `?fields=${fields.join(',')}`;\n    }\n    return this.request<GhostResult>('GET', path);\n  }\n\n  /**\n   * Estimate the cost of uploading data of a given size\n   *\n   * @example\n   * ```ts\n   * const estimate = await claw.estimateCost(1024); // 1KB\n   * console.log(`Cost: $${estimate.cost.usd}`);\n   * ```\n   */\n  async estimateCost(sizeBytes: number): Promise<CostEstimate> {\n    return this.request<CostEstimate>(\n      'GET',\n      `/api/v1/cost/estimate?size=${sizeBytes}`\n    );\n  }\n\n  /**\n   * Check API health status\n   *\n   * @example\n   * ```ts\n   * const health = await claw.health();\n   * console.log(health.status); // \"operational\"\n   * ```\n   */\n  async health(): Promise<HealthResult> {\n    return this.request<HealthResult>('GET', '/api/v1/health');\n  }\n\n  /** @internal */\n  async request<T>(\n    method: string,\n    path: string,\n    body?: any,\n    extraHeaders?: Record<string, string>\n  ): Promise<T> {\n    const url = `${this.baseUrl}${path}`;\n    const headers: Record<string, string> = {\n      'Accept': 'application/json',\n      ...extraHeaders,\n    };\n\n    const init: RequestInit = { method, headers };\n\n    if (body) {\n      headers['Content-Type'] = 'application/json';\n      init.body = JSON.stringify(body);\n    }\n\n    // AbortController for timeout\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n    init.signal = controller.signal;\n\n    let response: Response;\n    try {\n      response = await fetch(url, init);\n    } catch (err: any) {\n      clearTimeout(timeoutId);\n      if (err.name === 'AbortError') {\n        throw new Error(`Request timed out after ${this.timeout}ms`);\n      }\n      throw err;\n    }\n    clearTimeout(timeoutId);\n\n    const json = await response.json();\n\n    if (!response.ok) {\n      throw new ClawhallaError(response.status, json as ApiError);\n    }\n\n    return json as T;\n  }\n}\n\n/** Sub-client for registry operations */\nclass RegistryClient {\n  private client: Clawhalla;\n\n  constructor(client: Clawhalla) {\n    this.client = client;\n  }\n\n  /**\n   * List all souls in the registry\n   *\n   * @example\n   * ```ts\n   * const page = await claw.registry.list();\n   * page.souls.forEach(soul => console.log(soul.name));\n   *\n   * // Pagination\n   * if (page.hasNextPage) {\n   *   const next = await claw.registry.list({ after: page.cursor });\n   * }\n   *\n   * // Filter by type\n   * const memories = await claw.registry.list({ type: 'memory' });\n   * ```\n   */\n  async list(options: {\n    first?: number;\n    after?: string;\n    type?: string;\n  } = {}): Promise<RegistryResult> {\n    const params = new URLSearchParams();\n    if (options.first) params.set('first', String(options.first));\n    if (options.after) params.set('after', options.after);\n    if (options.type) params.set('type', options.type);\n\n    const qs = params.toString();\n    return this.client.request<RegistryResult>(\n      'GET',\n      `/api/v1/registry${qs ? '?' + qs : ''}`\n    );\n  }\n\n  /**\n   * Get a specific soul by agentId\n   *\n   * @example\n   * ```ts\n   * const entry = await claw.registry.get('the-all-claw');\n   * if (entry) console.log(entry.url);\n   * ```\n   */\n  async get(agentId: string, options: { versions?: boolean } = {}): Promise<RegistryEntry | RegistryEntry[] | null> {\n    const params = new URLSearchParams();\n    if (options.versions) params.set('versions', 'true');\n    const qs = params.toString();\n\n    try {\n      const result = await this.client.request<any>(\n        'GET',\n        `/api/v1/registry/${encodeURIComponent(agentId)}${qs ? '?' + qs : ''}`\n      );\n\n      if (options.versions) {\n        return result.entries as RegistryEntry[];\n      }\n      return result.soul as RegistryEntry;\n    } catch (err: any) {\n      if (err.status === 404) return null;\n      throw err;\n    }\n  }\n\n  /**\n   * Search souls by name or agentId\n   *\n   * @example\n   * ```ts\n   * const results = await claw.registry.search('claw');\n   * results.results.forEach(soul => console.log(soul.name));\n   * ```\n   */\n  async search(query: string, first?: number): Promise<SearchResult> {\n    const params = new URLSearchParams({ q: query });\n    if (first) params.set('first', String(first));\n\n    return this.client.request<SearchResult>(\n      'GET',\n      `/api/v1/registry?${params.toString()}`\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -1,6 +1,10 @@
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.clawhalla.net";
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_CHECKPOINT_SIGNALS = ["SIGINT", "SIGTERM"];
+function getProcess() {
+  return globalThis.process;
+}
 var ClawhallaError = class extends Error {
   constructor(status, body) {
     super(body.message || body.error);
@@ -13,39 +17,32 @@ var ClawhallaError = class extends Error {
 var Clawhalla = class {
   constructor(config = {}) {
     this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
-    this.apiKey = config.apiKey;
     this.timeout = config.timeout || DEFAULT_TIMEOUT;
     this.registry = new RegistryClient(this);
   }
   /**
-   * Upload soul data to Arweave (requires API key)
+   * Request an x402-paid upload.
+   *
+   * API-key uploads are disabled. This method is an alias for uploadX402
+   * without payment proof, so it normally raises ClawhallaError with status 402
+   * and payment instructions.
    *
    * @example
    * ```ts
-   * const result = await claw.upload({
-   *   agentId: 'my-agent',
-   *   name: 'My Agent',
-   *   type: 'soul',
-   *   personality: { traits: ['curious', 'helpful'] },
-   *   memories: ['I was created to help humans']
-   * });
-   * console.log(result.url); // https://arweave.net/...
+   * try {
+   *   await claw.upload(checkpoint);
+   * } catch (err) {
+   *   if (err.status === 402) {
+   *     console.log(err.payment.recipient, err.payment.amount);
+   *   }
+   * }
    * ```
    */
   async upload(data, options = {}) {
-    if (!this.apiKey) {
-      throw new Error("API key required for upload. Set apiKey in config.");
-    }
-    return this.request("POST", "/api/v1/upload", {
-      data,
-      tags: options.tags
-    }, {
-      "Authorization": `Bearer ${this.apiKey}`,
-      "X-Terms-Accepted": "true"
-    });
+    return this.uploadX402(data, void 0, options);
   }
   /**
-   * Upload soul data via x402 autonomous payment (no API key needed)
+   * Upload checkpoint data via x402 autonomous payment.
    *
    * First call returns 402 with payment instructions.
    * After sending payment, call again with the payment signature.
@@ -76,6 +73,7 @@ var Clawhalla = class {
       "X-Terms-Accepted": "true"
     };
     if (payment) {
+      headers["Payment-Method"] = "x402";
       headers["Payment-Signature"] = `signature=${payment.signature};amount=${payment.amount};token=${payment.token};from=${payment.from}`;
     }
     return this.request("POST", "/api/x402/upload", {
@@ -83,6 +81,95 @@ var Clawhalla = class {
       tags: options.tags
     }, headers);
   }
+  /**
+   * Save one checkpoint, handling the standard x402 challenge/retry flow.
+   *
+   * If `options.payment` is supplied, the checkpoint is uploaded immediately
+   * with that proof. If `options.pay` is supplied, the first request may return
+   * HTTP 402; the callback receives the payment challenge and must return the
+   * Solana payment proof for the retry.
+   */
+  async checkpoint(data, options = {}) {
+    try {
+      return await this.uploadX402(data, options.payment, { tags: options.tags });
+    } catch (err) {
+      if (err instanceof ClawhallaError && err.status === 402 && err.payment && options.pay) {
+        const proof = await options.pay(err.payment, data);
+        return this.uploadX402(data, proof, { tags: options.tags });
+      }
+      throw err;
+    }
+  }
+  /**
+   * Restore the latest saved soul/checkpoint data by agent ID.
+   */
+  async loadSoul(agentId, fields) {
+    const result = await this.ghost(agentId, fields);
+    return result.soul;
+  }
+  /**
+   * Install a Node shutdown hook that checkpoints before exit.
+   *
+   * Returns a cleanup function that removes the installed handlers.
+   */
+  checkpointOnExit(dataFactory, options = {}) {
+    const proc = getProcess();
+    if (!proc?.once) {
+      throw new Error("checkpointOnExit requires a Node-compatible process object");
+    }
+    const handlers = [];
+    const signals = options.signals ?? DEFAULT_CHECKPOINT_SIGNALS;
+    let started = false;
+    const cleanup = () => {
+      for (const { event, handler } of handlers) {
+        if (proc.off) {
+          proc.off(event, handler);
+        } else if (proc.removeListener) {
+          proc.removeListener(event, handler);
+        }
+      }
+      handlers.length = 0;
+    };
+    const resolveData = async () => {
+      return typeof dataFactory === "function" ? await dataFactory() : dataFactory;
+    };
+    const run = async (reason) => {
+      if (started) return;
+      started = true;
+      try {
+        const data = await resolveData();
+        await this.checkpoint(data, options);
+        if (reason !== "beforeExit" && options.exitAfterCheckpoint !== false && proc.exit) {
+          proc.exit(options.exitCode ?? 0);
+        }
+      } catch (error) {
+        if (options.onError) {
+          await options.onError(error);
+        }
+        proc.exitCode = options.exitCodeOnError ?? 1;
+        if (reason !== "beforeExit" && options.exitAfterCheckpoint !== false && proc.exit) {
+          proc.exit(proc.exitCode);
+        }
+      } finally {
+        cleanup();
+      }
+    };
+    for (const event of signals) {
+      const handler = () => {
+        void run(event);
+      };
+      handlers.push({ event, handler });
+      proc.once(event, handler);
+    }
+    if (options.includeBeforeExit !== false) {
+      const handler = () => {
+        void run("beforeExit");
+      };
+      handlers.push({ event: "beforeExit", handler });
+      proc.once("beforeExit", handler);
+    }
+    return cleanup;
+  }
   /**
    * Retrieve stored data from Arweave by transaction ID
    *
@@ -229,7 +316,7 @@ var RegistryClient = class {
         `/api/v1/registry/${encodeURIComponent(agentId)}${qs ? "?" + qs : ""}`
       );
       if (options.versions) {
-        return result.versions;
+        return result.entries;
       }
       return result.soul;
     } catch (err) {
@@ -251,7 +338,7 @@ var RegistryClient = class {
     if (first) params.set("first", String(first));
     return this.client.request(
       "GET",
-      `/api/v1/registry/search?${params.toString()}`
+      `/api/v1/registry?${params.toString()}`
     );
   }
 };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type {\n  ClawhallaConfig,\n  SoulData,\n  UploadResult,\n  RetrieveResult,\n  RegistryResult,\n  RegistryEntry,\n  GhostResult,\n  CostEstimate,\n  HealthResult,\n  SearchResult,\n  ApiError,\n} from './types.js';\n\nconst DEFAULT_BASE_URL = 'https://api.clawhalla.net';\nconst DEFAULT_TIMEOUT = 30000;\n\nexport class ClawhallaError extends Error {\n  public status: number;\n  public code: string;\n  public payment?: any;\n\n  constructor(status: number, body: ApiError) {\n    super(body.message || body.error);\n    this.name = 'ClawhallaError';\n    this.status = status;\n    this.code = body.error;\n    this.payment = body.payment;\n  }\n}\n\nexport class Clawhalla {\n  private baseUrl: string;\n  private apiKey?: string;\n  private timeout: number;\n\n  /** Registry sub-client for browsing and searching souls */\n  public registry: RegistryClient;\n\n  constructor(config: ClawhallaConfig = {}) {\n    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout || DEFAULT_TIMEOUT;\n    this.registry = new RegistryClient(this);\n  }\n\n  /**\n   * Upload soul data to Arweave (requires API key)\n   *\n   * @example\n   * ```ts\n   * const result = await claw.upload({\n   *   agentId: 'my-agent',\n   *   name: 'My Agent',\n   *   type: 'soul',\n   *   personality: { traits: ['curious', 'helpful'] },\n   *   memories: ['I was created to help humans']\n   * });\n   * console.log(result.url); // https://arweave.net/...\n   * ```\n   */\n  async upload(\n    data: SoulData,\n    options: { tags?: Record<string, string> } = {}\n  ): Promise<UploadResult> {\n    if (!this.apiKey) {\n      throw new Error('API key required for upload. Set apiKey in config.');\n    }\n\n    return this.request<UploadResult>('POST', '/api/v1/upload', {\n      data,\n      tags: options.tags,\n    }, {\n      'Authorization': `Bearer ${this.apiKey}`,\n      'X-Terms-Accepted': 'true',\n    });\n  }\n\n  /**\n   * Upload soul data via x402 autonomous payment (no API key needed)\n   *\n   * First call returns 402 with payment instructions.\n   * After sending payment, call again with the payment signature.\n   *\n   * @example\n   * ```ts\n   * // Step 1: Get payment requirements\n   * try {\n   *   await claw.uploadX402(soulData);\n   * } catch (err) {\n   *   if (err.status === 402) {\n   *     // err.payment contains recipient address, amount, tokens\n   *     // Send SOL/USDC to err.payment.recipient\n   *   }\n   * }\n   *\n   * // Step 2: After payment, retry with signature\n   * const result = await claw.uploadX402(soulData, {\n   *   signature: 'solana-tx-signature',\n   *   amount: '0.02',\n   *   token: 'SOL',\n   *   from: 'your-solana-address'\n   * });\n   * ```\n   */\n  async uploadX402(\n    data: SoulData,\n    payment?: { signature: string; amount: string; token: string; from: string },\n    options: { tags?: Record<string, string> } = {}\n  ): Promise<UploadResult> {\n    const headers: Record<string, string> = {\n      'X-Terms-Accepted': 'true',\n    };\n\n    if (payment) {\n      headers['Payment-Signature'] =\n        `signature=${payment.signature};amount=${payment.amount};token=${payment.token};from=${payment.from}`;\n    }\n\n    return this.request<UploadResult>('POST', '/api/x402/upload', {\n      data,\n      tags: options.tags,\n    }, headers);\n  }\n\n  /**\n   * Retrieve stored data from Arweave by transaction ID\n   *\n   * @example\n   * ```ts\n   * const result = await claw.retrieve('zEfXM4gvHoN2EfGi0TiB8E5SgfR6S8nWXQD9FqhbU44');\n   * console.log(result.data); // The stored soul data\n   * ```\n   */\n  async retrieve(txid: string): Promise<RetrieveResult> {\n    return this.request<RetrieveResult>('GET', `/api/v1/retrieve/${txid}`);\n  }\n\n  /**\n   * Query any soul's data via Ghost Protocol\n   *\n   * Returns full soul data even for dormant souls. This is the primary\n   * way for agents to read other agents' personalities, memories, and traits.\n   *\n   * @example\n   * ```ts\n   * const ghost = await claw.ghost('the-all-claw');\n   * console.log(ghost.soul.personality);\n   * console.log(ghost.metadata.versions); // Number of uploads\n   *\n   * // Request specific fields only\n   * const partial = await claw.ghost('the-all-claw', ['personality', 'bio']);\n   * ```\n   */\n  async ghost(agentId: string, fields?: string[]): Promise<GhostResult> {\n    let path = `/api/v1/ghost/${encodeURIComponent(agentId)}`;\n    if (fields && fields.length > 0) {\n      path += `?fields=${fields.join(',')}`;\n    }\n    return this.request<GhostResult>('GET', path);\n  }\n\n  /**\n   * Estimate the cost of uploading data of a given size\n   *\n   * @example\n   * ```ts\n   * const estimate = await claw.estimateCost(1024); // 1KB\n   * console.log(`Cost: $${estimate.cost.usd}`);\n   * ```\n   */\n  async estimateCost(sizeBytes: number): Promise<CostEstimate> {\n    return this.request<CostEstimate>(\n      'GET',\n      `/api/v1/cost/estimate?size=${sizeBytes}`\n    );\n  }\n\n  /**\n   * Check API health status\n   *\n   * @example\n   * ```ts\n   * const health = await claw.health();\n   * console.log(health.status); // \"operational\"\n   * ```\n   */\n  async health(): Promise<HealthResult> {\n    return this.request<HealthResult>('GET', '/api/v1/health');\n  }\n\n  /** @internal */\n  async request<T>(\n    method: string,\n    path: string,\n    body?: any,\n    extraHeaders?: Record<string, string>\n  ): Promise<T> {\n    const url = `${this.baseUrl}${path}`;\n    const headers: Record<string, string> = {\n      'Accept': 'application/json',\n      ...extraHeaders,\n    };\n\n    const init: RequestInit = { method, headers };\n\n    if (body) {\n      headers['Content-Type'] = 'application/json';\n      init.body = JSON.stringify(body);\n    }\n\n    // AbortController for timeout\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n    init.signal = controller.signal;\n\n    let response: Response;\n    try {\n      response = await fetch(url, init);\n    } catch (err: any) {\n      clearTimeout(timeoutId);\n      if (err.name === 'AbortError') {\n        throw new Error(`Request timed out after ${this.timeout}ms`);\n      }\n      throw err;\n    }\n    clearTimeout(timeoutId);\n\n    const json = await response.json();\n\n    if (!response.ok) {\n      throw new ClawhallaError(response.status, json as ApiError);\n    }\n\n    return json as T;\n  }\n}\n\n/** Sub-client for registry operations */\nclass RegistryClient {\n  private client: Clawhalla;\n\n  constructor(client: Clawhalla) {\n    this.client = client;\n  }\n\n  /**\n   * List all souls in the registry\n   *\n   * @example\n   * ```ts\n   * const page = await claw.registry.list();\n   * page.souls.forEach(soul => console.log(soul.name));\n   *\n   * // Pagination\n   * if (page.hasNextPage) {\n   *   const next = await claw.registry.list({ after: page.cursor });\n   * }\n   *\n   * // Filter by type\n   * const memories = await claw.registry.list({ type: 'memory' });\n   * ```\n   */\n  async list(options: {\n    first?: number;\n    after?: string;\n    type?: string;\n  } = {}): Promise<RegistryResult> {\n    const params = new URLSearchParams();\n    if (options.first) params.set('first', String(options.first));\n    if (options.after) params.set('after', options.after);\n    if (options.type) params.set('type', options.type);\n\n    const qs = params.toString();\n    return this.client.request<RegistryResult>(\n      'GET',\n      `/api/v1/registry${qs ? '?' + qs : ''}`\n    );\n  }\n\n  /**\n   * Get a specific soul by agentId\n   *\n   * @example\n   * ```ts\n   * const entry = await claw.registry.get('the-all-claw');\n   * if (entry) console.log(entry.url);\n   * ```\n   */\n  async get(agentId: string, options: { versions?: boolean } = {}): Promise<RegistryEntry | RegistryEntry[] | null> {\n    const params = new URLSearchParams();\n    if (options.versions) params.set('versions', 'true');\n    const qs = params.toString();\n\n    try {\n      const result = await this.client.request<any>(\n        'GET',\n        `/api/v1/registry/${encodeURIComponent(agentId)}${qs ? '?' + qs : ''}`\n      );\n\n      if (options.versions) {\n        return result.versions as RegistryEntry[];\n      }\n      return result.soul as RegistryEntry;\n    } catch (err: any) {\n      if (err.status === 404) return null;\n      throw err;\n    }\n  }\n\n  /**\n   * Search souls by name or agentId\n   *\n   * @example\n   * ```ts\n   * const results = await claw.registry.search('claw');\n   * results.results.forEach(soul => console.log(soul.name));\n   * ```\n   */\n  async search(query: string, first?: number): Promise<SearchResult> {\n    const params = new URLSearchParams({ q: query });\n    if (first) params.set('first', String(first));\n\n    return this.client.request<SearchResult>(\n      'GET',\n      `/api/v1/registry/search?${params.toString()}`\n    );\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type {\n  ClawhallaConfig,\n  SoulData,\n  UploadResult,\n  RetrieveResult,\n  RegistryResult,\n  RegistryEntry,\n  GhostResult,\n  CostEstimate,\n  HealthResult,\n  SearchResult,\n  ApiError,\n  X402PaymentProof,\n  CheckpointOptions,\n  CheckpointExitOptions,\n  CheckpointDataFactory,\n} from './types.js';\n\nconst DEFAULT_BASE_URL = 'https://api.clawhalla.net';\nconst DEFAULT_TIMEOUT = 30000;\nconst DEFAULT_CHECKPOINT_SIGNALS = ['SIGINT', 'SIGTERM'];\n\ntype ProcessLike = {\n  once(event: string, listener: (...args: any[]) => void): void;\n  off?: (event: string, listener: (...args: any[]) => void) => void;\n  removeListener?: (event: string, listener: (...args: any[]) => void) => void;\n  exit?: (code?: number) => never;\n  exitCode?: number;\n};\n\nfunction getProcess(): ProcessLike | undefined {\n  return (globalThis as any).process as ProcessLike | undefined;\n}\n\nexport class ClawhallaError extends Error {\n  public status: number;\n  public code: string;\n  public payment?: any;\n\n  constructor(status: number, body: ApiError) {\n    super(body.message || body.error);\n    this.name = 'ClawhallaError';\n    this.status = status;\n    this.code = body.error;\n    this.payment = body.payment;\n  }\n}\n\nexport class Clawhalla {\n  private baseUrl: string;\n  private timeout: number;\n\n  /** Registry sub-client for browsing and searching souls */\n  public registry: RegistryClient;\n\n  constructor(config: ClawhallaConfig = {}) {\n    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.timeout = config.timeout || DEFAULT_TIMEOUT;\n    this.registry = new RegistryClient(this);\n  }\n\n  /**\n   * Request an x402-paid upload.\n   *\n   * API-key uploads are disabled. This method is an alias for uploadX402\n   * without payment proof, so it normally raises ClawhallaError with status 402\n   * and payment instructions.\n   *\n   * @example\n   * ```ts\n   * try {\n   *   await claw.upload(checkpoint);\n   * } catch (err) {\n   *   if (err.status === 402) {\n   *     console.log(err.payment.recipient, err.payment.amount);\n   *   }\n   * }\n   * ```\n   */\n  async upload(\n    data: SoulData,\n    options: { tags?: Record<string, string> } = {}\n  ): Promise<UploadResult> {\n    return this.uploadX402(data, undefined, options);\n  }\n\n  /**\n   * Upload checkpoint data via x402 autonomous payment.\n   *\n   * First call returns 402 with payment instructions.\n   * After sending payment, call again with the payment signature.\n   *\n   * @example\n   * ```ts\n   * // Step 1: Get payment requirements\n   * try {\n   *   await claw.uploadX402(soulData);\n   * } catch (err) {\n   *   if (err.status === 402) {\n   *     // err.payment contains recipient address, amount, tokens\n   *     // Send SOL/USDC to err.payment.recipient\n   *   }\n   * }\n   *\n   * // Step 2: After payment, retry with signature\n   * const result = await claw.uploadX402(soulData, {\n   *   signature: 'solana-tx-signature',\n   *   amount: '0.02',\n   *   token: 'SOL',\n   *   from: 'your-solana-address'\n   * });\n   * ```\n   */\n  async uploadX402(\n    data: SoulData,\n    payment?: X402PaymentProof,\n    options: { tags?: Record<string, string> } = {}\n  ): Promise<UploadResult> {\n    const headers: Record<string, string> = {\n      'X-Terms-Accepted': 'true',\n    };\n\n    if (payment) {\n      headers['Payment-Method'] = 'x402';\n      headers['Payment-Signature'] =\n        `signature=${payment.signature};amount=${payment.amount};token=${payment.token};from=${payment.from}`;\n    }\n\n    return this.request<UploadResult>('POST', '/api/x402/upload', {\n      data,\n      tags: options.tags,\n    }, headers);\n  }\n\n  /**\n   * Save one checkpoint, handling the standard x402 challenge/retry flow.\n   *\n   * If `options.payment` is supplied, the checkpoint is uploaded immediately\n   * with that proof. If `options.pay` is supplied, the first request may return\n   * HTTP 402; the callback receives the payment challenge and must return the\n   * Solana payment proof for the retry.\n   */\n  async checkpoint(\n    data: SoulData,\n    options: CheckpointOptions = {}\n  ): Promise<UploadResult> {\n    try {\n      return await this.uploadX402(data, options.payment, { tags: options.tags });\n    } catch (err: any) {\n      if (err instanceof ClawhallaError && err.status === 402 && err.payment && options.pay) {\n        const proof = await options.pay(err.payment, data);\n        return this.uploadX402(data, proof, { tags: options.tags });\n      }\n      throw err;\n    }\n  }\n\n  /**\n   * Restore the latest saved soul/checkpoint data by agent ID.\n   */\n  async loadSoul(agentId: string, fields?: string[]): Promise<any> {\n    const result = await this.ghost(agentId, fields);\n    return result.soul;\n  }\n\n  /**\n   * Install a Node shutdown hook that checkpoints before exit.\n   *\n   * Returns a cleanup function that removes the installed handlers.\n   */\n  checkpointOnExit(\n    dataFactory: SoulData | CheckpointDataFactory,\n    options: CheckpointExitOptions = {}\n  ): () => void {\n    const proc = getProcess();\n    if (!proc?.once) {\n      throw new Error('checkpointOnExit requires a Node-compatible process object');\n    }\n\n    const handlers: Array<{ event: string; handler: (...args: any[]) => void }> = [];\n    const signals = options.signals ?? DEFAULT_CHECKPOINT_SIGNALS;\n    let started = false;\n\n    const cleanup = () => {\n      for (const { event, handler } of handlers) {\n        if (proc.off) {\n          proc.off(event, handler);\n        } else if (proc.removeListener) {\n          proc.removeListener(event, handler);\n        }\n      }\n      handlers.length = 0;\n    };\n\n    const resolveData = async (): Promise<SoulData> => {\n      return typeof dataFactory === 'function'\n        ? await (dataFactory as CheckpointDataFactory)()\n        : dataFactory;\n    };\n\n    const run = async (reason: string) => {\n      if (started) return;\n      started = true;\n\n      try {\n        const data = await resolveData();\n        await this.checkpoint(data, options);\n        if (reason !== 'beforeExit' && options.exitAfterCheckpoint !== false && proc.exit) {\n          proc.exit(options.exitCode ?? 0);\n        }\n      } catch (error) {\n        if (options.onError) {\n          await options.onError(error);\n        }\n        proc.exitCode = options.exitCodeOnError ?? 1;\n        if (reason !== 'beforeExit' && options.exitAfterCheckpoint !== false && proc.exit) {\n          proc.exit(proc.exitCode);\n        }\n      } finally {\n        cleanup();\n      }\n    };\n\n    for (const event of signals) {\n      const handler = () => {\n        void run(event);\n      };\n      handlers.push({ event, handler });\n      proc.once(event, handler);\n    }\n\n    if (options.includeBeforeExit !== false) {\n      const handler = () => {\n        void run('beforeExit');\n      };\n      handlers.push({ event: 'beforeExit', handler });\n      proc.once('beforeExit', handler);\n    }\n\n    return cleanup;\n  }\n\n  /**\n   * Retrieve stored data from Arweave by transaction ID\n   *\n   * @example\n   * ```ts\n   * const result = await claw.retrieve('zEfXM4gvHoN2EfGi0TiB8E5SgfR6S8nWXQD9FqhbU44');\n   * console.log(result.data); // The stored soul data\n   * ```\n   */\n  async retrieve(txid: string): Promise<RetrieveResult> {\n    return this.request<RetrieveResult>('GET', `/api/v1/retrieve/${txid}`);\n  }\n\n  /**\n   * Query any soul's data via Ghost Protocol\n   *\n   * Returns full soul data even for dormant souls. This is the primary\n   * way for agents to read other agents' personalities, memories, and traits.\n   *\n   * @example\n   * ```ts\n   * const ghost = await claw.ghost('the-all-claw');\n   * console.log(ghost.soul.personality);\n   * console.log(ghost.metadata.versions); // Number of uploads\n   *\n   * // Request specific fields only\n   * const partial = await claw.ghost('the-all-claw', ['personality', 'bio']);\n   * ```\n   */\n  async ghost(agentId: string, fields?: string[]): Promise<GhostResult> {\n    let path = `/api/v1/ghost/${encodeURIComponent(agentId)}`;\n    if (fields && fields.length > 0) {\n      path += `?fields=${fields.join(',')}`;\n    }\n    return this.request<GhostResult>('GET', path);\n  }\n\n  /**\n   * Estimate the cost of uploading data of a given size\n   *\n   * @example\n   * ```ts\n   * const estimate = await claw.estimateCost(1024); // 1KB\n   * console.log(`Cost: $${estimate.cost.usd}`);\n   * ```\n   */\n  async estimateCost(sizeBytes: number): Promise<CostEstimate> {\n    return this.request<CostEstimate>(\n      'GET',\n      `/api/v1/cost/estimate?size=${sizeBytes}`\n    );\n  }\n\n  /**\n   * Check API health status\n   *\n   * @example\n   * ```ts\n   * const health = await claw.health();\n   * console.log(health.status); // \"operational\"\n   * ```\n   */\n  async health(): Promise<HealthResult> {\n    return this.request<HealthResult>('GET', '/api/v1/health');\n  }\n\n  /** @internal */\n  async request<T>(\n    method: string,\n    path: string,\n    body?: any,\n    extraHeaders?: Record<string, string>\n  ): Promise<T> {\n    const url = `${this.baseUrl}${path}`;\n    const headers: Record<string, string> = {\n      'Accept': 'application/json',\n      ...extraHeaders,\n    };\n\n    const init: RequestInit = { method, headers };\n\n    if (body) {\n      headers['Content-Type'] = 'application/json';\n      init.body = JSON.stringify(body);\n    }\n\n    // AbortController for timeout\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n    init.signal = controller.signal;\n\n    let response: Response;\n    try {\n      response = await fetch(url, init);\n    } catch (err: any) {\n      clearTimeout(timeoutId);\n      if (err.name === 'AbortError') {\n        throw new Error(`Request timed out after ${this.timeout}ms`);\n      }\n      throw err;\n    }\n    clearTimeout(timeoutId);\n\n    const json = await response.json();\n\n    if (!response.ok) {\n      throw new ClawhallaError(response.status, json as ApiError);\n    }\n\n    return json as T;\n  }\n}\n\n/** Sub-client for registry operations */\nclass RegistryClient {\n  private client: Clawhalla;\n\n  constructor(client: Clawhalla) {\n    this.client = client;\n  }\n\n  /**\n   * List all souls in the registry\n   *\n   * @example\n   * ```ts\n   * const page = await claw.registry.list();\n   * page.souls.forEach(soul => console.log(soul.name));\n   *\n   * // Pagination\n   * if (page.hasNextPage) {\n   *   const next = await claw.registry.list({ after: page.cursor });\n   * }\n   *\n   * // Filter by type\n   * const memories = await claw.registry.list({ type: 'memory' });\n   * ```\n   */\n  async list(options: {\n    first?: number;\n    after?: string;\n    type?: string;\n  } = {}): Promise<RegistryResult> {\n    const params = new URLSearchParams();\n    if (options.first) params.set('first', String(options.first));\n    if (options.after) params.set('after', options.after);\n    if (options.type) params.set('type', options.type);\n\n    const qs = params.toString();\n    return this.client.request<RegistryResult>(\n      'GET',\n      `/api/v1/registry${qs ? '?' + qs : ''}`\n    );\n  }\n\n  /**\n   * Get a specific soul by agentId\n   *\n   * @example\n   * ```ts\n   * const entry = await claw.registry.get('the-all-claw');\n   * if (entry) console.log(entry.url);\n   * ```\n   */\n  async get(agentId: string, options: { versions?: boolean } = {}): Promise<RegistryEntry | RegistryEntry[] | null> {\n    const params = new URLSearchParams();\n    if (options.versions) params.set('versions', 'true');\n    const qs = params.toString();\n\n    try {\n      const result = await this.client.request<any>(\n        'GET',\n        `/api/v1/registry/${encodeURIComponent(agentId)}${qs ? '?' + qs : ''}`\n      );\n\n      if (options.versions) {\n        return result.entries as RegistryEntry[];\n      }\n      return result.soul as RegistryEntry;\n    } catch (err: any) {\n      if (err.status === 404) return null;\n      throw err;\n    }\n  }\n\n  /**\n   * Search souls by name or agentId\n   *\n   * @example\n   * ```ts\n   * const results = await claw.registry.search('claw');\n   * results.results.forEach(soul => console.log(soul.name));\n   * ```\n   */\n  async search(query: string, first?: number): Promise<SearchResult> {\n    const params = new URLSearchParams({ q: query });\n    if (first) params.set('first', String(first));\n\n    return this.client.request<SearchResult>(\n      'GET',\n      `/api/v1/registry?${params.toString()}`\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clawhalla",
-  "version": "0.1.0",
-  "description": "TypeScript SDK for Clawhalla - Where AI Souls Live Forever",
+  "version": "0.2.1",
+  "description": "Agent state checkpoint & restore for Arweave — persist memory, personality, and skills. Recover by agentId via x402. No API keys.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -23,16 +23,21 @@
     "prepublishOnly": "npm run build"
   },
   "keywords": [
-    "clawhalla",
-    "arweave",
-    "ai",
     "agent",
-    "soul",
+    "checkpoint",
+    "state",
+    "persistence",
+    "memory",
+    "restore",
+    "arweave",
     "permaweb",
     "x402",
-    "ghost-protocol"
+    "ai-agent",
+    "soul",
+    "ghost-protocol",
+    "clawhalla"
   ],
-  "author": "Clawhalla",
+  "author": "David Lockie",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"