@hirosystems/chainhooks-client 0.1.4

package/README.md

@@ -0,0 +1,224 @@
+# @hirosystems/chainhooks-client
+
+A TypeScript client for the Chainhooks API with full type safety and comprehensive schema definitions.
+
+## Features
+
+- 🚀 **Full TypeScript Support** - Complete type safety using TypeBox schemas
+- 🔐 **Authentication** - Built-in API key and JWT support
+- 📚 **Schema Export** - Access to all Chainhook schemas and types
+- 🎯 **Modern API** - Promise-based async/await interface
+- 🛡️ **Error Handling** - Comprehensive error handling with meaningful messages
+- 🌐 **HTTP Client** - Uses undici for high-performance HTTP requests
+- 🏗️ **Built-in URLs** - Pre-configured URLs for mainnet and testnet
+
+## Installation
+
+```bash
+npm install @hirosystems/chainhooks-client
+```
+
+**Note:** This package uses [undici](https://github.com/nodejs/undici) as its HTTP client, which provides high-performance HTTP/1.1 and HTTP/2 support. It's automatically installed as a dependency.
+
+## Quick Start
+
+```typescript
+import { ChainhooksClient, ChainhookDefinition } from '@hirosystems/chainhooks-client';
+
+// Initialize the client
+const client = new ChainhooksClient({
+  baseUrl: 'https://api.mainnet.hiro.so',
+  apiKey: 'your-api-key-here',
+});
+
+// Register a new chainhook
+const chainhook: ChainhookDefinition = {
+  name: 'My Stacks Chainhook',
+  chain: 'stacks',
+  network: 'mainnet',
+  filters: {
+    // Your filters here
+  },
+  options: {
+    start_at_block_height: 1000000,
+  },
+  action: {
+    // Your action configuration
+  },
+};
+
+try {
+  const result = await client.registerChainhook(chainhook);
+  console.log('Chainhook registered:', result.uuid);
+} catch (error) {
+  console.error('Failed to register chainhook:', error.message);
+}
+```
+
+## Pre-configured URLs
+
+The client provides pre-configured URLs for convenience:
+
+```typescript
+import { CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client';
+
+const client = new ChainhooksClient({
+  baseUrl: CHAINHOOKS_BASE_URL.mainnet,  // https://api.mainnet.hiro.so
+  apiKey: 'your-api-key',
+});
+
+// Or for testnet
+const testnetClient = new ChainhooksClient({
+  baseUrl: CHAINHOOKS_BASE_URL.testnet,  // https://api.testnet.hiro.so
+  apiKey: 'your-api-key',
+});
+```
+
+## API Methods
+
+### Chainhook Management
+
+#### `registerChainhook(definition: ChainhookDefinition): Promise<Chainhook>`
+Register a new chainhook with the API.
+
+#### `getChainhooks(options?: PaginationOptions): Promise<PaginatedChainhookResponse>`
+Retrieve all chainhooks with optional pagination.
+
+```typescript
+// Get first 20 chainhooks
+const chainhooks = await client.getChainhooks({ limit: 20, offset: 0 });
+
+// Get next page
+const nextPage = await client.getChainhooks({ limit: 20, offset: 20 });
+```
+
+#### `getChainhook(uuid: string): Promise<Chainhook>`
+Retrieve a specific chainhook by its UUID.
+
+#### `deleteChainhook(uuid: string): Promise<void>`
+Delete a chainhook by its UUID.
+
+### API Status
+
+#### `getStatus(): Promise<ApiStatusResponse>`
+Check the API status and version information.
+
+## Configuration
+
+The client accepts the following configuration options:
+
+```typescript
+interface ChainhooksClientConfig {
+  baseUrl: string;           // Required: API base URL
+  apiKey?: string;           // Optional: API key for authentication
+  jwt?: string;              // Optional: JWT token for authentication
+}
+```
+
+**Note:** You can use either `apiKey` or `jwt` for authentication, or both if needed.
+
+## Schema Types
+
+All Chainhook schemas are exported for use in your application:
+
+```typescript
+import {
+  Chainhook,
+  ChainhookDefinition,
+  ChainhookStatus,
+  ChainhookNetwork,
+  PaginatedChainhookResponse,
+  ApiStatusResponse,
+  // ... and many more
+} from '@hirosystems/chainhooks-client';
+```
+
+## Pagination
+
+The client supports pagination for list operations:
+
+```typescript
+interface PaginationOptions {
+  offset?: number;  // Starting position (default: 0)
+  limit?: number;   // Number of results (default: 20, max: 60)
+}
+```
+
+## Examples
+
+### Complete Workflow
+
+```typescript
+import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client';
+
+const client = new ChainhooksClient({
+  baseUrl: CHAINHOOKS_BASE_URL.mainnet,
+  apiKey: process.env.CHAINHOOKS_API_KEY,
+});
+
+async function manageChainhooks() {
+  try {
+    // Check API status
+    const status = await client.getStatus();
+    console.log('API Status:', status.status);
+    console.log('Server Version:', status.server_version);
+
+    // List all chainhooks
+    const { results, total } = await client.getChainhooks({ limit: 50 });
+    console.log(`Found ${total} chainhooks`);
+
+    // Get details of first chainhook
+    if (results.length > 0) {
+      const firstChainhook = await client.getChainhook(results[0].uuid);
+      console.log('First chainhook:', firstChainhook.definition.name);
+    }
+
+  } catch (error) {
+    console.error('Error managing chainhooks:', error.message);
+  }
+}
+```
+
+### Using JWT Authentication
+
+```typescript
+const client = new ChainhooksClient({
+  baseUrl: CHAINHOOKS_BASE_URL.mainnet,
+  jwt: 'your-jwt-token-here',
+});
+
+try {
+  const result = await client.registerChainhook(chainhookDefinition);
+  console.log('Success:', result.uuid);
+} catch (error) {
+  console.error('Failed:', error.message);
+}
+```
+
+### Error Handling
+
+```typescript
+const client = new ChainhooksClient({
+  baseUrl: CHAINHOOKS_BASE_URL.mainnet,
+  apiKey: 'your-key',
+});
+
+try {
+  const result = await client.registerChainhook(chainhookDefinition);
+  console.log('Success:', result.uuid);
+} catch (error) {
+  console.error('Failed:', error.message);
+}
+```
+
+## TypeScript Support
+
+This package is written in TypeScript and provides full type definitions. All API methods, request/response types, and configuration interfaces are fully typed.
+
+## Contributing
+
+Contributions are welcome! Please ensure all changes maintain type safety and include appropriate tests.
+
+## License
+
+Apache-2.0

package/dist/src/client.d.ts

@@ -0,0 +1,61 @@
+import { ApiStatusResponse, Chainhook, ChainhookDefinition, PaginatedChainhookResponse } from './schemas';
+/**
+ * Network URLs for the Chainhooks Client
+ */
+export declare const CHAINHOOKS_BASE_URL: {
+    mainnet: string;
+    testnet: string;
+};
+/**
+ * Configuration for the Chainhooks Client
+ */
+export interface ChainhooksClientConfig {
+    /** Base URL to use when interacting with the Chainhooks API */
+    baseUrl: string;
+    /** API key to use */
+    apiKey?: string;
+    /** JSON Web Token to use */
+    jwt?: string;
+}
+/**
+ * Pagination options for the Chainhooks Client
+ */
+export interface PaginationOptions {
+    /** Offset of the first item to return */
+    offset?: number;
+    /** Number of items to return */
+    limit?: number;
+}
+/**
+ * Chainhooks Client
+ *
+ * A TypeScript client for interacting with the Chainhooks API.
+ */
+export declare class ChainhooksClient {
+    private readonly config;
+    private readonly requestHeaders;
+    private readonly baseUrl;
+    constructor(config: ChainhooksClientConfig);
+    /**
+     * Register a new chainhook
+     */
+    registerChainhook(definition: ChainhookDefinition): Promise<Chainhook>;
+    /**
+     * Get all chainhooks with pagination
+     */
+    getChainhooks(options?: PaginationOptions): Promise<PaginatedChainhookResponse>;
+    /**
+     * Get a specific chainhook by UUID
+     */
+    getChainhook(uuid: string): Promise<Chainhook>;
+    /**
+     * Delete a chainhook by UUID
+     */
+    deleteChainhook(uuid: string): Promise<void>;
+    /**
+     * Get API status
+     */
+    getStatus(): Promise<ApiStatusResponse>;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,SAAS,EACT,mBAAmB,EACnB,0BAA0B,EAC3B,MAAM,WAAW,CAAC;AAGnB;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;CAG/B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,sBAAsB;IAe1C;;OAEG;IACG,iBAAiB,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAQ5E;;OAEG;IACG,aAAa,CACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,0BAA0B,CAAC;IAetC;;OAEG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAOpD;;OAEG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlD;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,iBAAiB,CAAC;YAO/B,OAAO;CAgCtB"}

package/dist/src/client.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChainhooksClient = exports.CHAINHOOKS_BASE_URL = void 0;
+const undici_1 = require("undici");
+/**
+ * Network URLs for the Chainhooks Client
+ */
+exports.CHAINHOOKS_BASE_URL = {
+    mainnet: 'https://api.mainnet.hiro.so',
+    testnet: 'https://api.testnet.hiro.so',
+};
+/**
+ * Chainhooks Client
+ *
+ * A TypeScript client for interacting with the Chainhooks API.
+ */
+class ChainhooksClient {
+    config;
+    requestHeaders;
+    baseUrl;
+    constructor(config) {
+        this.config = config;
+        this.requestHeaders = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        if (this.config.jwt) {
+            this.requestHeaders['Authorization'] = `Bearer ${this.config.jwt}`;
+        }
+        if (this.config.apiKey) {
+            this.requestHeaders['x-api-key'] = this.config.apiKey;
+        }
+        this.baseUrl = this.config.baseUrl;
+    }
+    /**
+     * Register a new chainhook
+     */
+    async registerChainhook(definition) {
+        return this.request({
+            method: 'POST',
+            path: '/chainhooks/me',
+            body: JSON.stringify(definition),
+        });
+    }
+    /**
+     * Get all chainhooks with pagination
+     */
+    async getChainhooks(options = {}) {
+        const query = {};
+        if (options.offset !== undefined) {
+            query.offset = options.offset.toString();
+        }
+        if (options.limit !== undefined) {
+            query.limit = options.limit.toString();
+        }
+        return this.request({
+            method: 'GET',
+            path: '/chainhooks/me',
+            query,
+        });
+    }
+    /**
+     * Get a specific chainhook by UUID
+     */
+    async getChainhook(uuid) {
+        return this.request({
+            method: 'GET',
+            path: `/chainhooks/me/${uuid}`,
+        });
+    }
+    /**
+     * Delete a chainhook by UUID
+     */
+    async deleteChainhook(uuid) {
+        await this.request({
+            method: 'DELETE',
+            path: `/chainhooks/me/${uuid}`,
+        });
+    }
+    /**
+     * Get API status
+     */
+    async getStatus() {
+        return this.request({
+            method: 'GET',
+            path: '/chainhooks',
+        });
+    }
+    async request(options) {
+        const { method, path, body, query } = options;
+        const url = new URL(path, this.baseUrl);
+        if (query) {
+            Object.entries(query).forEach(([key, value]) => {
+                url.searchParams.append(key, value.toString());
+            });
+        }
+        const { statusCode, body: responseBody } = await (0, undici_1.request)(url.toString(), {
+            method,
+            headers: this.requestHeaders,
+            body,
+        });
+        if (statusCode >= 400) {
+            let errorMessage;
+            try {
+                const errorData = (await responseBody.json());
+                errorMessage = errorData.error || `HTTP ${statusCode}`;
+            }
+            catch {
+                errorMessage = `HTTP ${statusCode}`;
+            }
+            throw new Error(`ChainhooksClient error: ${errorMessage}`);
+        }
+        if (statusCode === 204) {
+            return undefined;
+        }
+        const data = await responseBody.json();
+        return data;
+    }
+}
+exports.ChainhooksClient = ChainhooksClient;
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './schemas';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);
+__exportStar(require("./schemas"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,4CAA0B"}