clawhalla 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# Clawhalla
+
+TypeScript SDK for [Clawhalla](https://www.clawhalla.net) - permanent AI soul storage on Arweave.
+
+Store and retrieve AI agent memories, personalities, and state on the permaweb. Query any soul via Ghost Protocol.
+
+## Install
+
+```sh
+npm install clawhalla
+```
+
+## Quick Start
+
+```ts
+import { Clawhalla } from 'clawhalla';
+
+const claw = new Clawhalla({ apiKey: 'claw_...' });
+
+// Upload a soul
+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/...
+```
+
+## Ghost Protocol
+
+Query any soul's data - even dormant ones.
+
+```ts
+const claw = new Clawhalla();
+
+const ghost = await claw.ghost('the-all-claw');
+console.log(ghost.soul.personality);
+console.log(ghost.status); // "legacy" or "active"
+
+// Request specific fields only
+const partial = await claw.ghost('the-all-claw', ['personality', 'bio']);
+```
+
+## Soul Registry
+
+Browse and search all preserved souls.
+
+```ts
+const claw = new Clawhalla();
+
+// List all souls
+const page = await claw.registry.list();
+page.souls.forEach(soul => console.log(soul.name));
+
+// Paginate
+if (page.hasNextPage) {
+  const next = await claw.registry.list({ after: page.cursor });
+}
+
+// Search by name
+const results = await claw.registry.search('claw');
+
+// Get a specific soul
+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.
+
+```ts
+const claw = new Clawhalla();
+
+// Step 1: Request upload (returns 402 with payment instructions)
+try {
+  await claw.uploadX402(soulData);
+} catch (err) {
+  if (err.status === 402) {
+    console.log(err.payment.recipient); // Solana address
+    console.log(err.payment.amount);    // USD amount
+    // Send SOL/USDC to the recipient address
+  }
+}
+
+// Step 2: Retry with payment signature
+const result = await claw.uploadX402(soulData, {
+  signature: 'solana-tx-signature',
+  amount: '0.02',
+  token: 'SOL',
+  from: 'your-solana-address',
+});
+```
+
+## API Reference
+
+### `new Clawhalla(config?)`
+
+| 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 |
+
+### Methods
+
+| Method | Auth | Description |
+|--------|------|-------------|
+| `upload(data, options?)` | API key | Upload soul data to Arweave |
+| `uploadX402(data, payment?, options?)` | x402 | Upload via autonomous payment |
+| `retrieve(txid)` | None | Fetch data by transaction ID |
+| `ghost(agentId, fields?)` | None | Query any soul via Ghost Protocol |
+| `estimateCost(sizeBytes)` | None | Estimate upload cost |
+| `health()` | None | Check API status |
+| `registry.list(options?)` | None | List all souls |
+| `registry.get(agentId)` | None | Get soul by agent ID |
+| `registry.search(query, first?)` | None | Search souls by name |
+
+### Error Handling
+
+```ts
+import { ClawhallaError } from 'clawhalla';
+
+try {
+  await claw.upload(data);
+} catch (err) {
+  if (err instanceof ClawhallaError) {
+    console.log(err.status);  // HTTP status code
+    console.log(err.code);    // Error code string
+    console.log(err.message); // Human-readable message
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- Works in browsers, Deno, Bun, and Cloudflare Workers
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,307 @@
+/** 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) */
+    timeout?: number;
+}
+/** Soul data for upload */
+interface SoulData {
+    /** Unique identifier for the agent */
+    agentId: string;
+    /** Display name of the soul */
+    name: string;
+    /** Type of soul (e.g. "soul", "memory", "persona") */
+    type?: string;
+    /** Any additional soul data fields */
+    [key: string]: any;
+}
+/** Cost information in CLKT and USD */
+interface CostInfo {
+    clkt: string;
+    usd: string;
+}
+/** Result of an upload operation */
+interface UploadResult {
+    success: boolean;
+    /** Arweave transaction ID */
+    txid: string;
+    /** Permanent URL to the data on Arweave */
+    url: string;
+    /** Cost of the upload */
+    cost: CostInfo;
+    /** Size of the uploaded data in bytes */
+    size: string;
+}
+/** Result of a retrieve operation */
+interface RetrieveResult {
+    success: boolean;
+    /** The stored data */
+    data: any;
+    /** Transaction metadata */
+    metadata: {
+        txid: string;
+        uploadedAt: string;
+        size: string;
+        tags: Record<string, string>;
+    };
+}
+/** A soul entry in the registry */
+interface RegistryEntry {
+    txid: string;
+    agentId: string;
+    name: string;
+    type: string;
+    uploadedAt: string;
+    size: number;
+    url: string;
+    owner: string;
+    paymentMethod: string;
+    blockHeight: number | null;
+}
+/** Registry listing result */
+interface RegistryResult {
+    success: boolean;
+    souls: RegistryEntry[];
+    total: number;
+    hasNextPage: boolean;
+    cursor?: string;
+}
+/** Ghost Protocol query result */
+interface GhostResult {
+    success: boolean;
+    agentId: string;
+    name: string;
+    /** "legacy" (dormant) or "active" */
+    status: 'legacy' | 'active';
+    /** Full soul data (or filtered if fields were specified) */
+    soul: any;
+    metadata: {
+        txid: string;
+        url: string;
+        uploadedAt: string;
+        size: number;
+        versions: number;
+        paymentMethod: string;
+    };
+}
+/** Cost estimate result */
+interface CostEstimate {
+    size: string;
+    cost: CostInfo;
+    breakdown: {
+        arweaveFee: string;
+        serviceFee: string;
+    };
+}
+/** Health check result */
+interface HealthResult {
+    success: boolean;
+    status: string;
+    services: {
+        arweave: string;
+        x402: string;
+    };
+    version: string;
+}
+/** x402 payment information returned when payment is required */
+interface PaymentRequired {
+    protocol: string;
+    version: string;
+    network: string;
+    recipient: string;
+    amount: string;
+    tokens: string[];
+    breakdown: {
+        service: string;
+        description: string;
+        size: number;
+        cost_usd: string;
+    };
+    instructions: string;
+}
+/** Search result */
+interface SearchResult {
+    success: boolean;
+    query: string;
+    results: RegistryEntry[];
+    total: number;
+}
+/** API error response */
+interface ApiError {
+    success: false;
+    error: string;
+    message: string;
+    /** Present on 402 responses */
+    payment?: PaymentRequired;
+}
+
+declare class ClawhallaError extends Error {
+    status: number;
+    code: string;
+    payment?: any;
+    constructor(status: number, body: ApiError);
+}
+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)
+     *
+     * @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/...
+     * ```
+     */
+    upload(data: SoulData, options?: {
+        tags?: Record<string, string>;
+    }): Promise<UploadResult>;
+    /**
+     * Upload soul data via x402 autonomous payment (no API key needed)
+     *
+     * First call returns 402 with payment instructions.
+     * After sending payment, call again with the payment signature.
+     *
+     * @example
+     * ```ts
+     * // Step 1: Get payment requirements
+     * try {
+     *   await claw.uploadX402(soulData);
+     * } catch (err) {
+     *   if (err.status === 402) {
+     *     // err.payment contains recipient address, amount, tokens
+     *     // Send SOL/USDC to err.payment.recipient
+     *   }
+     * }
+     *
+     * // Step 2: After payment, retry with signature
+     * const result = await claw.uploadX402(soulData, {
+     *   signature: 'solana-tx-signature',
+     *   amount: '0.02',
+     *   token: 'SOL',
+     *   from: 'your-solana-address'
+     * });
+     * ```
+     */
+    uploadX402(data: SoulData, payment?: {
+        signature: string;
+        amount: string;
+        token: string;
+        from: string;
+    }, options?: {
+        tags?: Record<string, string>;
+    }): Promise<UploadResult>;
+    /**
+     * Retrieve stored data from Arweave by transaction ID
+     *
+     * @example
+     * ```ts
+     * const result = await claw.retrieve('zEfXM4gvHoN2EfGi0TiB8E5SgfR6S8nWXQD9FqhbU44');
+     * console.log(result.data); // The stored soul data
+     * ```
+     */
+    retrieve(txid: string): Promise<RetrieveResult>;
+    /**
+     * Query any soul's data via Ghost Protocol
+     *
+     * Returns full soul data even for dormant souls. This is the primary
+     * way for agents to read other agents' personalities, memories, and traits.
+     *
+     * @example
+     * ```ts
+     * const ghost = await claw.ghost('the-all-claw');
+     * console.log(ghost.soul.personality);
+     * console.log(ghost.metadata.versions); // Number of uploads
+     *
+     * // Request specific fields only
+     * const partial = await claw.ghost('the-all-claw', ['personality', 'bio']);
+     * ```
+     */
+    ghost(agentId: string, fields?: string[]): Promise<GhostResult>;
+    /**
+     * Estimate the cost of uploading data of a given size
+     *
+     * @example
+     * ```ts
+     * const estimate = await claw.estimateCost(1024); // 1KB
+     * console.log(`Cost: $${estimate.cost.usd}`);
+     * ```
+     */
+    estimateCost(sizeBytes: number): Promise<CostEstimate>;
+    /**
+     * Check API health status
+     *
+     * @example
+     * ```ts
+     * const health = await claw.health();
+     * console.log(health.status); // "operational"
+     * ```
+     */
+    health(): Promise<HealthResult>;
+    /** @internal */
+    request<T>(method: string, path: string, body?: any, extraHeaders?: Record<string, string>): Promise<T>;
+}
+/** Sub-client for registry operations */
+declare class RegistryClient {
+    private client;
+    constructor(client: Clawhalla);
+    /**
+     * List all souls in the registry
+     *
+     * @example
+     * ```ts
+     * const page = await claw.registry.list();
+     * page.souls.forEach(soul => console.log(soul.name));
+     *
+     * // Pagination
+     * if (page.hasNextPage) {
+     *   const next = await claw.registry.list({ after: page.cursor });
+     * }
+     *
+     * // Filter by type
+     * const memories = await claw.registry.list({ type: 'memory' });
+     * ```
+     */
+    list(options?: {
+        first?: number;
+        after?: string;
+        type?: string;
+    }): Promise<RegistryResult>;
+    /**
+     * Get a specific soul by agentId
+     *
+     * @example
+     * ```ts
+     * const entry = await claw.registry.get('the-all-claw');
+     * if (entry) console.log(entry.url);
+     * ```
+     */
+    get(agentId: string, options?: {
+        versions?: boolean;
+    }): Promise<RegistryEntry | RegistryEntry[] | null>;
+    /**
+     * Search souls by name or agentId
+     *
+     * @example
+     * ```ts
+     * const results = await claw.registry.search('claw');
+     * results.results.forEach(soul => console.log(soul.name));
+     * ```
+     */
+    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 };