@verifyapi/sdk 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @verifyapi/sdk@0.1.0 build /Users/jjfisher/verifyapi_v1/packages/sdk
+> tsc
+

package/.turbo/turbo-lint.log

@@ -0,0 +1,11 @@
+
+> @verifyapi/sdk@0.1.0 lint /Users/jjfisher/verifyapi_v1/packages/sdk
+> eslint src/
+
+
+/Users/jjfisher/verifyapi_v1/packages/sdk/src/client.ts
+  521:15  warning  Forbidden non-null assertion  @typescript-eslint/no-non-null-assertion
+  522:15  warning  Forbidden non-null assertion  @typescript-eslint/no-non-null-assertion
+
+✖ 2 problems (0 errors, 2 warnings)
+

package/.turbo/turbo-test$colon$unit.log

@@ -0,0 +1,19 @@
+
+> @verifyapi/sdk@0.1.0 test:unit /Users/jjfisher/verifyapi_v1/packages/sdk
+> vitest run
+
+
+ RUN  v4.1.0 /Users/jjfisher/verifyapi_v1/packages/sdk
+
+ ✓ src/__tests__/errors.test.ts (8 tests) 8ms
+ ✓ src/__tests__/webhooks.test.ts (11 tests) 19ms
+ ✓ src/__tests__/client.test.ts (31 tests) 3285ms
+     ✓ retries on 429 and succeeds  1100ms
+     ✓ retries on 500 and eventually throws after max retries  1073ms
+     ✓ retries on connection error  1090ms
+
+ Test Files  3 passed (3)
+      Tests  50 passed (50)
+   Start at  18:18:26
+   Duration  3.62s (transform 236ms, setup 0ms, import 378ms, tests 3.31s, environment 0ms)
+

package/.turbo/turbo-typecheck.log

@@ -0,0 +1,4 @@
+
+> @verifyapi/sdk@0.1.0 typecheck /Users/jjfisher/verifyapi_v1/packages/sdk
+> tsc --noEmit
+

package/README.md

@@ -0,0 +1,78 @@
+# @verifyapi/sdk — FirstHandAPI TypeScript SDK
+
+Official TypeScript SDK for [FirstHandAPI](https://firsthandapi.com) — the human-in-the-loop (HITL) crowdsourced data collection API.
+
+Post jobs via API. Real human workers capture photos, audio, video, and screen recordings. AI ensemble (Claude Vision + Whisper) auto-scores quality. Approved files delivered to your S3 folder. Use cases: UGC collection, ground truth for AI evaluation, LLM training data.
+
+## Installation
+
+```bash
+npm install @verifyapi/sdk
+```
+
+## Quick Start
+
+```typescript
+import { FirstHandClient } from '@verifyapi/sdk';
+
+const client = new FirstHandClient({
+  apiKey: 'fh_live_your_key_here',
+});
+
+// Post a content collection job
+const job = await client.createJob({
+  type: 'data_collection',
+  description: 'Photos of grocery store shelf labels',
+  files_needed: 100,
+  accepted_formats: ['image/jpeg', 'image/png'],
+  price_per_file_cents: 25,
+});
+
+// Wait for completion
+const completed = await client.createJobAndWait({
+  ...jobData,
+}, 300); // wait up to 5 minutes
+
+// Get approved files
+const files = await client.getJobFiles(job.id);
+files.data.forEach(file => {
+  console.log(file.download_url);
+});
+```
+
+## Methods
+
+### Jobs
+- `createJob(body)` — Post a new job
+- `getJob(id, options?)` — Get job (supports long-poll)
+- `listJobs(params?)` — List jobs
+- `cancelJob(id)` — Cancel and refund
+- `getJobFiles(id)` — Get approved files
+- `getJobSubmissions(id)` — Get submissions
+- `createJobAndWait(body, maxWait)` — Create and poll
+
+### Billing
+- `getCreditBalance()` — Check balance
+- `listTransactions(params?)` — Transaction history
+- `purchaseCredits(body)` — Buy credits
+
+### Webhooks
+- `createWebhookEndpoint(body)` — Register endpoint
+- `listWebhookEndpoints()` — List endpoints
+- `verifyWebhookSignature(payload, signature, secret)` — Verify webhook
+
+### API Keys
+- `createApiKey(body)` — Create key
+- `listApiKeys()` — List keys
+- `rotateApiKey(id)` — Rotate key
+- `revokeApiKey(id)` — Revoke key
+
+## Features
+- Auto-retry with exponential backoff (429, 500+)
+- Idempotency key generation
+- Long-poll support
+- TypeScript-native types
+
+## License
+
+Proprietary

package/dist/client.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @module @firsthandapi/sdk/client
+ * @description FirstHandAPI TypeScript SDK client.
+ * Typed client wrapping all v1 REST endpoints with auto-retry,
+ * idempotency key generation, and proper error handling.
+ *
+ * @example
+ * ```ts
+ * import { FirstHandClient } from '@firsthandapi/sdk';
+ *
+ * const client = new FirstHandClient({ apiKey: 'fh_live_...' });
+ * const job = await client.createJob({
+ *   job_type: 'product_photo',
+ *   title: 'Product photo for listing #1234',
+ *   instructions: 'Take a clean photo of the product on white background',
+ * });
+ * ```
+ *
+ * @see api-contract.md — Full API specification
+ */
+import type { Static } from '@sinclair/typebox';
+import type { CreateJobRequest, JobResponse, JobListParams, CreateApiKeyRequest, CreateApiKeyResponse, ApiKeyListItem, RotateApiKeyResponse, CreateWebhookEndpointRequest, WebhookEndpointResponse, UpdateWebhookEndpointRequest, RotateWebhookSecretResponse, WebhookEventResponse, CreditBalanceResponse, CreditTransaction, PurchaseCreditsRequest, PurchaseCreditsResponse } from '@verifyapi/api-contracts';
+export interface FirstHandClientOptions {
+    /** API key (fh_live_* or fh_test_*) */
+    apiKey: string;
+    /** Base URL (default: https://api.firsthandapi.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+    /** Maximum retry attempts for retryable errors (default: 3) */
+    maxRetries?: number;
+    /** Custom fetch implementation (default: global fetch) */
+    fetch?: typeof globalThis.fetch;
+}
+export interface ListResponse<T> {
+    object: 'list';
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export interface ListOptions {
+    [key: string]: unknown;
+    cursor?: string;
+    limit?: number;
+}
+export interface GetJobOptions {
+    /** Long-poll: wait up to N seconds for job to complete (max 60) */
+    waitSeconds?: number;
+}
+export declare class FirstHandClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchFn;
+    constructor(options: FirstHandClientOptions);
+    /** Create a new job for content collection */
+    createJob(body: Static<typeof CreateJobRequest>, idempotencyKey?: string): Promise<Static<typeof JobResponse>>;
+    /** Get a job by ID. Supports long-polling via waitSeconds option. */
+    getJob(jobId: string, options?: GetJobOptions): Promise<Static<typeof JobResponse>>;
+    /** List jobs with optional filters */
+    listJobs(params?: Static<typeof JobListParams>): Promise<ListResponse<Static<typeof JobResponse>>>;
+    /** Get audit trail for a job */
+    getJobAudit(jobId: string): Promise<Record<string, unknown>>;
+    /** Cancel a pending job */
+    cancelJob(jobId: string): Promise<Static<typeof JobResponse>>;
+    /** Get files associated with a job (approved submissions with download URLs) */
+    getJobFiles(jobId: string): Promise<ListResponse<unknown>>;
+    /** Get submissions for a job */
+    getJobSubmissions(jobId: string): Promise<ListResponse<unknown>>;
+    /** Rate a completed job (1-5 stars with optional feedback) */
+    rateJob(jobId: string, body: {
+        rating: number;
+        feedback?: string;
+    }): Promise<Static<typeof JobResponse>>;
+    /**
+     * Create a job and wait for it to complete.
+     * Polls using long-poll until the job reaches a terminal state or timeout.
+     *
+     * @param body - Job creation request
+     * @param maxWaitSeconds - Maximum total wait time (default: 120)
+     * @param pollIntervalSeconds - Long-poll interval per request (default: 30)
+     */
+    createJobAndWait(body: Static<typeof CreateJobRequest>, maxWaitSeconds?: number, pollIntervalSeconds?: number): Promise<Static<typeof JobResponse>>;
+    /** Create a new API key */
+    createApiKey(body: Static<typeof CreateApiKeyRequest>): Promise<Static<typeof CreateApiKeyResponse>>;
+    /** List API keys (secrets masked) */
+    listApiKeys(options?: ListOptions): Promise<ListResponse<Static<typeof ApiKeyListItem>>>;
+    /** Rotate an API key (24h overlap window) */
+    rotateApiKey(keyId: string): Promise<Static<typeof RotateApiKeyResponse>>;
+    /** Revoke an API key immediately */
+    revokeApiKey(keyId: string): Promise<void>;
+    /** Create a webhook endpoint */
+    createWebhookEndpoint(body: Static<typeof CreateWebhookEndpointRequest>): Promise<Static<typeof WebhookEndpointResponse>>;
+    /** List webhook endpoints */
+    listWebhookEndpoints(options?: ListOptions): Promise<ListResponse<Static<typeof WebhookEndpointResponse>>>;
+    /** Get a webhook endpoint by ID */
+    getWebhookEndpoint(endpointId: string): Promise<Static<typeof WebhookEndpointResponse>>;
+    /** Update a webhook endpoint */
+    updateWebhookEndpoint(endpointId: string, body: Static<typeof UpdateWebhookEndpointRequest>): Promise<Static<typeof WebhookEndpointResponse>>;
+    /** Delete a webhook endpoint */
+    deleteWebhookEndpoint(endpointId: string): Promise<void>;
+    /** Rotate webhook signing secret */
+    rotateWebhookSecret(endpointId: string): Promise<Static<typeof RotateWebhookSecretResponse>>;
+    /** List webhook events */
+    listWebhookEvents(options?: ListOptions & {
+        status?: string;
+        event_type?: string;
+    }): Promise<ListResponse<Static<typeof WebhookEventResponse>>>;
+    /** Replay a webhook event */
+    replayWebhookEvent(eventId: string): Promise<Static<typeof WebhookEventResponse>>;
+    /** Get current credit balance */
+    getCreditBalance(): Promise<Static<typeof CreditBalanceResponse>>;
+    /** List credit transactions */
+    listTransactions(options?: ListOptions & {
+        type?: string;
+    }): Promise<ListResponse<Static<typeof CreditTransaction>>>;
+    /** Initiate credit purchase via Stripe Checkout */
+    purchaseCredits(body: Static<typeof PurchaseCreditsRequest>): Promise<Static<typeof PurchaseCreditsResponse>>;
+    private request;
+}
+/** Generates a random idempotency key (UUID v4 format) */
+export declare function generateIdempotencyKey(): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,314 @@
+/**
+ * @module @firsthandapi/sdk/client
+ * @description FirstHandAPI TypeScript SDK client.
+ * Typed client wrapping all v1 REST endpoints with auto-retry,
+ * idempotency key generation, and proper error handling.
+ *
+ * @example
+ * ```ts
+ * import { FirstHandClient } from '@firsthandapi/sdk';
+ *
+ * const client = new FirstHandClient({ apiKey: 'fh_live_...' });
+ * const job = await client.createJob({
+ *   job_type: 'product_photo',
+ *   title: 'Product photo for listing #1234',
+ *   instructions: 'Take a clean photo of the product on white background',
+ * });
+ * ```
+ *
+ * @see api-contract.md — Full API specification
+ */
+import { FirstHandApiError, FirstHandConnectionError } from './errors.js';
+// ─── Client ─────────────────────────────────────────────────────────────
+const DEFAULT_BASE_URL = 'https://api.firsthandapi.com';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 1_000;
+export class FirstHandClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    fetchFn;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error('apiKey is required');
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    // ── Jobs ───────────────────────────────────────────────────────────
+    /** Create a new job for content collection */
+    async createJob(body, idempotencyKey) {
+        const key = idempotencyKey ?? generateIdempotencyKey();
+        return this.request('POST', '/v1/jobs', {
+            body,
+            headers: { 'Idempotency-Key': key },
+            expectedStatus: 201,
+        });
+    }
+    /** Get a job by ID. Supports long-polling via waitSeconds option. */
+    async getJob(jobId, options) {
+        const headers = {};
+        if (options?.waitSeconds) {
+            headers['Prefer'] = `wait=${Math.min(options.waitSeconds, 60)}`;
+        }
+        return this.request('GET', `/v1/jobs/${jobId}`, { headers });
+    }
+    /** List jobs with optional filters */
+    async listJobs(params) {
+        return this.request('GET', '/v1/jobs', { query: params });
+    }
+    /** Get audit trail for a job */
+    async getJobAudit(jobId) {
+        return this.request('GET', `/v1/jobs/${jobId}/audit`);
+    }
+    /** Cancel a pending job */
+    async cancelJob(jobId) {
+        return this.request('POST', `/v1/jobs/${jobId}/cancel`, {
+            headers: { 'Idempotency-Key': generateIdempotencyKey() },
+        });
+    }
+    /** Get files associated with a job (approved submissions with download URLs) */
+    async getJobFiles(jobId) {
+        return this.request('GET', `/v1/jobs/${jobId}/files`);
+    }
+    /** Get submissions for a job */
+    async getJobSubmissions(jobId) {
+        return this.request('GET', `/v1/jobs/${jobId}/submissions`);
+    }
+    /** Rate a completed job (1-5 stars with optional feedback) */
+    async rateJob(jobId, body) {
+        return this.request('POST', `/v1/jobs/${jobId}/rate`, { body });
+    }
+    /**
+     * Create a job and wait for it to complete.
+     * Polls using long-poll until the job reaches a terminal state or timeout.
+     *
+     * @param body - Job creation request
+     * @param maxWaitSeconds - Maximum total wait time (default: 120)
+     * @param pollIntervalSeconds - Long-poll interval per request (default: 30)
+     */
+    async createJobAndWait(body, maxWaitSeconds = 120, pollIntervalSeconds = 30) {
+        const job = await this.createJob(body);
+        const terminalStatuses = new Set(['resolved', 'completed', 'timed_out', 'failed', 'cancelled']);
+        if (terminalStatuses.has(job.status)) {
+            return job;
+        }
+        const deadline = Date.now() + maxWaitSeconds * 1000;
+        while (Date.now() < deadline) {
+            const remaining = Math.ceil((deadline - Date.now()) / 1000);
+            const waitSeconds = Math.min(pollIntervalSeconds, remaining, 60);
+            if (waitSeconds <= 0)
+                break;
+            const updated = await this.getJob(job.id, { waitSeconds });
+            if (terminalStatuses.has(updated.status)) {
+                return updated;
+            }
+        }
+        // Return latest state even if not terminal
+        return this.getJob(job.id);
+    }
+    // ── API Keys ────────────────────────────────────────────────────────
+    /** Create a new API key */
+    async createApiKey(body) {
+        return this.request('POST', '/v1/api_keys', {
+            body,
+            headers: { 'Idempotency-Key': generateIdempotencyKey() },
+            expectedStatus: 201,
+        });
+    }
+    /** List API keys (secrets masked) */
+    async listApiKeys(options) {
+        return this.request('GET', '/v1/api_keys', { query: options });
+    }
+    /** Rotate an API key (24h overlap window) */
+    async rotateApiKey(keyId) {
+        return this.request('POST', `/v1/api_keys/${keyId}/rotate`, {
+            headers: { 'Idempotency-Key': generateIdempotencyKey() },
+        });
+    }
+    /** Revoke an API key immediately */
+    async revokeApiKey(keyId) {
+        await this.request('POST', `/v1/api_keys/${keyId}/revoke`, {
+            headers: { 'Idempotency-Key': generateIdempotencyKey() },
+            expectedStatus: 204,
+            parseBody: false,
+        });
+    }
+    // ── Webhooks ────────────────────────────────────────────────────────
+    /** Create a webhook endpoint */
+    async createWebhookEndpoint(body) {
+        return this.request('POST', '/v1/webhook_endpoints', {
+            body,
+            headers: { 'Idempotency-Key': generateIdempotencyKey() },
+            expectedStatus: 201,
+        });
+    }
+    /** List webhook endpoints */
+    async listWebhookEndpoints(options) {
+        return this.request('GET', '/v1/webhook_endpoints', { query: options });
+    }
+    /** Get a webhook endpoint by ID */
+    async getWebhookEndpoint(endpointId) {
+        return this.request('GET', `/v1/webhook_endpoints/${endpointId}`);
+    }
+    /** Update a webhook endpoint */
+    async updateWebhookEndpoint(endpointId, body) {
+        return this.request('PATCH', `/v1/webhook_endpoints/${endpointId}`, { body });
+    }
+    /** Delete a webhook endpoint */
+    async deleteWebhookEndpoint(endpointId) {
+        await this.request('DELETE', `/v1/webhook_endpoints/${endpointId}`, {
+            expectedStatus: 204,
+            parseBody: false,
+        });
+    }
+    /** Rotate webhook signing secret */
+    async rotateWebhookSecret(endpointId) {
+        return this.request('POST', `/v1/webhook_endpoints/${endpointId}/rotate_secret`, {
+            headers: { 'Idempotency-Key': generateIdempotencyKey() },
+        });
+    }
+    // ── Webhook Events ─────────────────────────────────────────────────
+    /** List webhook events */
+    async listWebhookEvents(options) {
+        return this.request('GET', '/v1/webhook_events', { query: options });
+    }
+    /** Replay a webhook event */
+    async replayWebhookEvent(eventId) {
+        return this.request('POST', `/v1/webhook_events/${eventId}/replay`, {
+            headers: { 'Idempotency-Key': generateIdempotencyKey() },
+            expectedStatus: 202,
+        });
+    }
+    // ── Billing ────────────────────────────────────────────────────────
+    /** Get current credit balance */
+    async getCreditBalance() {
+        return this.request('GET', '/v1/billing/credits');
+    }
+    /** List credit transactions */
+    async listTransactions(options) {
+        return this.request('GET', '/v1/billing/transactions', { query: options });
+    }
+    /** Initiate credit purchase via Stripe Checkout */
+    async purchaseCredits(body) {
+        return this.request('POST', '/v1/billing/credits/purchase', {
+            body,
+            headers: { 'Idempotency-Key': generateIdempotencyKey() },
+        });
+    }
+    // ── HTTP Layer ─────────────────────────────────────────────────────
+    async request(method, path, options = {}) {
+        const { body, query, headers: extraHeaders, expectedStatus, parseBody = true } = options;
+        let url = `${this.baseUrl}${path}`;
+        if (query) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== null) {
+                    params.set(key, String(value));
+                }
+            }
+            const qs = params.toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+            ...extraHeaders,
+        };
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            if (attempt > 0) {
+                // Exponential backoff with jitter
+                const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1);
+                const jitter = delay * 0.1 * Math.random();
+                await sleep(delay + jitter);
+            }
+            try {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+                let response;
+                try {
+                    response = await this.fetchFn(url, {
+                        method,
+                        headers,
+                        body: body ? JSON.stringify(body) : undefined,
+                        signal: controller.signal,
+                    });
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+                // Success range
+                if (response.ok) {
+                    if (!parseBody || response.status === 204) {
+                        return undefined;
+                    }
+                    return (await response.json());
+                }
+                // Check expected status
+                if (expectedStatus && response.status === expectedStatus) {
+                    if (!parseBody)
+                        return undefined;
+                    return (await response.json());
+                }
+                // Parse error body
+                let errorBody;
+                try {
+                    errorBody = (await response.json());
+                }
+                catch {
+                    errorBody = {
+                        error: {
+                            type: 'unknown',
+                            message: `HTTP ${response.status}`,
+                            request_id: 'unknown',
+                        },
+                    };
+                }
+                const apiError = new FirstHandApiError(response.status, {
+                    type: errorBody.error?.type ?? 'unknown',
+                    message: errorBody.error?.message ?? `HTTP ${response.status}`,
+                    request_id: errorBody.error?.request_id ?? 'unknown',
+                    details: errorBody.error?.details,
+                });
+                // Only retry on retryable errors
+                if (!apiError.retryable || attempt >= this.maxRetries) {
+                    throw apiError;
+                }
+                lastError = apiError;
+            }
+            catch (err) {
+                if (err instanceof FirstHandApiError)
+                    throw err;
+                const connError = new FirstHandConnectionError(`Connection failed: ${err.message}`, err);
+                if (attempt >= this.maxRetries)
+                    throw connError;
+                lastError = connError;
+            }
+        }
+        throw lastError ?? new FirstHandConnectionError('Request failed after retries');
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Generates a random idempotency key (UUID v4 format) */
+export function generateIdempotencyKey() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 1
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module @firsthandapi/sdk/errors
+ * @description SDK error types for FirstHandAPI API responses.
+ */
+export interface FirstHandErrorDetail {
+    field?: string;
+    message: string;
+    code?: string;
+}
+export interface FirstHandErrorBody {
+    type: string;
+    message: string;
+    request_id: string;
+    details?: FirstHandErrorDetail[];
+}
+/**
+ * Error thrown when FirstHandAPI returns a non-2xx response.
+ * Contains the parsed error envelope from the response body.
+ */
+export declare class FirstHandApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly requestId: string;
+    readonly details?: FirstHandErrorDetail[];
+    constructor(status: number, body: FirstHandErrorBody);
+    /** True if the error is retryable (429, 500, 502, 503, 504) */
+    get retryable(): boolean;
+}
+/**
+ * Error thrown when a network failure or timeout occurs.
+ */
+export declare class FirstHandConnectionError extends Error {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;gBAE9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB;IASpD,+DAA+D;IAC/D,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAK3C"}