@ethitrust/sdk 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,177 @@
+# @ethitrust/sdk
+
+Official **TypeScript / Node** SDK for the Ethitrust **org-escrows** API.
+
+* Strongly typed against the OpenAPI spec (`ethi-mono v0.1.0`)
+* Hand-crafted ergonomic surface — no codegen runtime
+* Built-in retries, timeouts, and idempotency-key generation
+* Async pagination iterator
+* Rich error hierarchy mapped from HTTP status codes
+
+## Install
+
+```bash
+pnpm add @ethitrust/sdk
+# or
+npm install @ethitrust/sdk
+```
+
+Requires **Node 18+** (uses the global `fetch`).
+
+## Quick start
+
+```ts
+import { EthitrustClient } from '@ethitrust/sdk';
+
+const client = new EthitrustClient({
+  apiKey: process.env.ETHITRUST_API_KEY!,        // sent as X-API-Key
+  baseUrl: 'https://api.ethitrust.me',           // default
+});
+
+const escrow = await client.orgEscrows.create({
+  invitee_email: 'buyer@example.com',
+  title: 'Website redesign',
+  amount: 5000,
+  currency: 'ETB',
+  escrow_type: 'milestone',
+  who_pays_fees: 'split',
+  milestones: [
+    { title: 'Wireframes',     amount: 1500 },
+    { title: 'Final delivery', amount: 3500 },
+  ],
+});
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `apiKey`         | — *(required)*           | Organization API key. |
+| `baseUrl`        | `https://api.ethitrust.me` | API host. Bare hostnames are auto-prefixed with `https://`. |
+| `apiKeyHeader`   | `X-API-Key`              | Header name carrying the key. |
+| `timeoutMs`      | `30000`                  | Per-request timeout. |
+| `maxRetries`     | `2`                      | Retries for transient failures (GET / `429` / `5xx`). |
+| `fetch`          | global `fetch`           | Custom fetch implementation. |
+| `defaultHeaders` | `{}`                     | Extra headers on every request. |
+| `userAgent`      | `@ethitrust/sdk/1.0.0 node` | Override the User-Agent. |
+
+## API surface
+
+Every method lives on `client.orgEscrows`.
+
+| Method | HTTP | Endpoint |
+|---|---|---|
+| `create(body, extras?)`                       | POST  | `/api/v1/org-escrows` |
+| `list(params?, extras?)`                      | GET   | `/api/v1/org-escrows` |
+| `iter(params?, extras?)` *(async iterator)*   | GET   | `/api/v1/org-escrows` (auto-paginated) |
+| `getStatus(id, extras?)`                      | GET   | `/api/v1/org-escrows/{id}` |
+| `getDetail(id, extras?)`                      | GET   | `/api/v1/org-escrows/{id}/detail` |
+| `getEvents(id, extras?)`                      | GET   | `/api/v1/org-escrows/{id}/events` |
+| `getHealth(id, extras?)`                      | GET   | `/api/v1/org-escrows/{id}/health` |
+| `cancel(id, extras?)`                         | POST  | `/api/v1/org-escrows/{id}/cancel` |
+| `resendInvitation(id, extras?)`               | POST  | `/api/v1/org-escrows/{id}/resend` |
+| `getReport(params?, extras?)`                 | GET   | `/api/v1/org-escrows/reports/summary` |
+| `listEscrowWebhookLogs(id, extras?)`          | GET   | `/api/v1/org-escrows/{id}/webhooks` |
+| `listWebhookLogs(extras?)`                    | GET   | `/api/v1/org-escrows/webhooks` |
+| `testWebhook(extras?)`                        | POST  | `/api/v1/org-escrows/webhooks/test` |
+
+### Pagination iterator
+
+```ts
+for await (const item of client.orgEscrows.iter({ status: 'active' })) {
+  console.log(item.escrow_id, item.title);
+}
+```
+
+### Idempotency keys
+
+Every write method (`create`, `cancel`, `resendInvitation`, `testWebhook`) **auto-generates** a UUID v4 idempotency key and sends it as `X-Idempotency-Key`. Override it (e.g. to dedupe a retried business operation) or disable it explicitly:
+
+```ts
+await client.orgEscrows.create(body, { idempotencyKey: 'order-42' });
+await client.orgEscrows.create(body, { idempotencyKey: null }); // disable
+```
+
+Or generate one yourself:
+
+```ts
+import { generateIdempotencyKey } from '@ethitrust/sdk';
+const key = generateIdempotencyKey('order');
+```
+
+### Timeouts & cancellation
+
+```ts
+const ac = new AbortController();
+setTimeout(() => ac.abort(), 5000);
+
+await client.orgEscrows.list({ status: 'active' }, {
+  signal: ac.signal,
+  timeoutMs: 10_000,
+});
+```
+
+### Error handling
+
+```ts
+import {
+  EthitrustApiError,
+  EthitrustAuthError,
+  EthitrustNotFoundError,
+  EthitrustValidationError,
+  EthitrustRateLimitError,
+  EthitrustNetworkError,
+} from '@ethitrust/sdk';
+
+try {
+  await client.orgEscrows.create(/* … */);
+} catch (err) {
+  if (err instanceof EthitrustValidationError) {
+    for (const e of err.errors) console.error(e.loc.join('.'), e.msg);
+  } else if (err instanceof EthitrustAuthError) {
+    // invalid / expired API key
+  } else if (err instanceof EthitrustRateLimitError) {
+    console.warn('Retry after', err.retryAfter, 'seconds');
+  } else if (err instanceof EthitrustApiError) {
+    console.error(err.status, err.body);
+  } else if (err instanceof EthitrustNetworkError) {
+    // DNS / TCP / timeout
+  }
+}
+```
+
+Mapping:
+
+| HTTP | Error class |
+|---|---|
+| 401 / 403 | `EthitrustAuthError` |
+| 404       | `EthitrustNotFoundError` |
+| 409       | `EthitrustConflictError` |
+| 422       | `EthitrustValidationError` |
+| 429       | `EthitrustRateLimitError` (auto-retried with `Retry-After`) |
+| other 4xx | `EthitrustApiError` |
+| 5xx       | `EthitrustApiError` (GETs auto-retried) |
+| fetch/timeout | `EthitrustNetworkError` / `EthitrustAbortError` |
+
+### Retries
+
+By default the SDK retries:
+* **GET** requests on `5xx` responses, network errors and timeouts,
+* **any method** on `429`, honoring `Retry-After`,
+
+up to `maxRetries` (default `2`) with exponential backoff + jitter capped at 10 s.
+
+POST / PATCH / DELETE are **not** retried on `5xx` automatically; combined with the auto-generated idempotency key, you can safely retry them yourself.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test       # runs node --test against ./dist (build first)
+pnpm example    # runs examples/basic.ts via tsx
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import { HttpClient } from './http.js';
+import { OrgEscrowsResource } from './resources/orgEscrows.js';
+export interface EthitrustClientOptions {
+    /** Organization API key. Sent as `X-API-Key` (configurable). */
+    apiKey: string;
+    /**
+     * Base URL. Defaults to `https://api.ethitrust.me`. Accepts host with or
+     * without scheme — if missing, `https://` is assumed.
+     */
+    baseUrl?: string;
+    /** Header carrying the API key. Defaults to `X-API-Key`. */
+    apiKeyHeader?: string;
+    /** Per-request timeout (ms). Defaults to 30 000. */
+    timeoutMs?: number;
+    /** Max retries for transient failures (GET / 429 / 5xx). Defaults to 2. */
+    maxRetries?: number;
+    /** Custom fetch (e.g. undici, node-fetch). */
+    fetch?: typeof fetch;
+    /** Extra headers applied to every request. */
+    defaultHeaders?: Record<string, string>;
+    /** User agent string. */
+    userAgent?: string;
+}
+/**
+ * Top-level entry point.
+ *
+ * ```ts
+ * import { EthitrustClient } from '@ethitrust/sdk';
+ * const client = new EthitrustClient({ apiKey: process.env.ETHITRUST_API_KEY! });
+ * const escrow = await client.orgEscrows.create({
+ *   invitee_email: 'buyer@example.com',
+ *   title: 'Website redesign',
+ *   amount: 5000,
+ * });
+ * ```
+ */
+export declare class EthitrustClient {
+    readonly http: HttpClient;
+    readonly orgEscrows: OrgEscrowsResource;
+    constructor(opts: EthitrustClientOptions);
+}
+//# 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":"AAAA,OAAO,EAAE,UAAU,EAA0B,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;gBAE5B,IAAI,EAAE,sBAAsB;CAkBzC"}

package/dist/client.js

@@ -0,0 +1,45 @@
+import { HttpClient } from './http.js';
+import { OrgEscrowsResource } from './resources/orgEscrows.js';
+const DEFAULT_BASE_URL = 'https://api.ethitrust.me';
+/**
+ * Top-level entry point.
+ *
+ * ```ts
+ * import { EthitrustClient } from '@ethitrust/sdk';
+ * const client = new EthitrustClient({ apiKey: process.env.ETHITRUST_API_KEY! });
+ * const escrow = await client.orgEscrows.create({
+ *   invitee_email: 'buyer@example.com',
+ *   title: 'Website redesign',
+ *   amount: 5000,
+ * });
+ * ```
+ */
+export class EthitrustClient {
+    http;
+    orgEscrows;
+    constructor(opts) {
+        if (!opts.apiKey) {
+            throw new Error('EthitrustClient: `apiKey` is required.');
+        }
+        const baseUrl = normaliseBaseUrl(opts.baseUrl ?? DEFAULT_BASE_URL);
+        const httpOpts = {
+            apiKey: opts.apiKey,
+            apiKeyHeader: opts.apiKeyHeader,
+            baseUrl,
+            timeoutMs: opts.timeoutMs,
+            maxRetries: opts.maxRetries,
+            fetch: opts.fetch,
+            defaultHeaders: opts.defaultHeaders,
+            userAgent: opts.userAgent,
+        };
+        this.http = new HttpClient(httpOpts);
+        this.orgEscrows = new OrgEscrowsResource(this.http);
+    }
+}
+function normaliseBaseUrl(input) {
+    const trimmed = input.trim();
+    if (/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    return `https://${trimmed}`;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA0B,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAwB/D,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAe;IACjB,IAAI,CAAa;IACjB,UAAU,CAAqB;IAExC,YAAY,IAA4B;QACtC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC;QACnE,MAAM,QAAQ,GAAsB;YAClC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO;YACP,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;CACF;AAED,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAClD,OAAO,WAAW,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,66 @@
+import type { ValidationErrorItem } from './types.js';
+/** Base class for every error thrown by the SDK. */
+export declare class EthitrustError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the server returns a non-2xx HTTP status. */
+export declare class EthitrustApiError extends EthitrustError {
+    readonly status: number;
+    readonly statusText: string;
+    readonly requestId?: string;
+    readonly url: string;
+    readonly method: string;
+    readonly body: unknown;
+    constructor(opts: {
+        status: number;
+        statusText: string;
+        url: string;
+        method: string;
+        body: unknown;
+        requestId?: string;
+        message?: string;
+    });
+}
+/** 422 Unprocessable Entity (FastAPI validation failure). */
+export declare class EthitrustValidationError extends EthitrustApiError {
+    readonly errors: ValidationErrorItem[];
+    constructor(opts: ConstructorParameters<typeof EthitrustApiError>[0]);
+}
+/** 401 / 403 — invalid or insufficient credentials. */
+export declare class EthitrustAuthError extends EthitrustApiError {
+    constructor(opts: ConstructorParameters<typeof EthitrustApiError>[0]);
+}
+/** 404. */
+export declare class EthitrustNotFoundError extends EthitrustApiError {
+    constructor(opts: ConstructorParameters<typeof EthitrustApiError>[0]);
+}
+/** 409 — idempotency or business-rule conflict. */
+export declare class EthitrustConflictError extends EthitrustApiError {
+    constructor(opts: ConstructorParameters<typeof EthitrustApiError>[0]);
+}
+/** 429 — too many requests. */
+export declare class EthitrustRateLimitError extends EthitrustApiError {
+    readonly retryAfter?: number;
+    constructor(opts: ConstructorParameters<typeof EthitrustApiError>[0] & {
+        retryAfter?: number;
+    });
+}
+/** Network / fetch / timeout level failure. */
+export declare class EthitrustNetworkError extends EthitrustError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/** Request was aborted (timeout or user signal). */
+export declare class EthitrustAbortError extends EthitrustError {
+    constructor(message?: string);
+}
+export declare function buildApiError(opts: {
+    status: number;
+    statusText: string;
+    url: string;
+    method: string;
+    body: unknown;
+    requestId?: string;
+    retryAfter?: number;
+}): EthitrustApiError;
+//# 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,OAAO,KAAK,EAAuB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE3E,oDAAoD;AACpD,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,4DAA4D;AAC5D,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,OAAO,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;CAcF;AAED,6DAA6D;AAC7D,qBAAa,wBAAyB,SAAQ,iBAAiB;IAC7D,QAAQ,CAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC;gBAE3B,IAAI,EAAE,qBAAqB,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAMrE;AAED,uDAAuD;AACvD,qBAAa,kBAAmB,SAAQ,iBAAiB;gBAC3C,IAAI,EAAE,qBAAqB,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAIrE;AAED,WAAW;AACX,qBAAa,sBAAuB,SAAQ,iBAAiB;gBAC/C,IAAI,EAAE,qBAAqB,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAIrE;AAED,mDAAmD;AACnD,qBAAa,sBAAuB,SAAQ,iBAAiB;gBAC/C,IAAI,EAAE,qBAAqB,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAIrE;AAED,+BAA+B;AAC/B,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAE3B,IAAI,EAAE,qBAAqB,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAG;QACzD,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;CAMJ;AAED,+CAA+C;AAC/C,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBACb,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK7C;AAED,oDAAoD;AACpD,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,OAAO,SAAoB;CAIxC;AAeD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,iBAAiB,CAOpB"}

package/dist/errors.js

@@ -0,0 +1,115 @@
+/** Base class for every error thrown by the SDK. */
+export class EthitrustError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EthitrustError';
+    }
+}
+/** Thrown when the server returns a non-2xx HTTP status. */
+export class EthitrustApiError extends EthitrustError {
+    status;
+    statusText;
+    requestId;
+    url;
+    method;
+    body;
+    constructor(opts) {
+        const detail = opts.message ??
+            extractMessage(opts.body) ??
+            `${opts.status} ${opts.statusText}`;
+        super(`Ethitrust API error ${opts.status}: ${detail}`);
+        this.name = 'EthitrustApiError';
+        this.status = opts.status;
+        this.statusText = opts.statusText;
+        this.url = opts.url;
+        this.method = opts.method;
+        this.body = opts.body;
+        this.requestId = opts.requestId;
+    }
+}
+/** 422 Unprocessable Entity (FastAPI validation failure). */
+export class EthitrustValidationError extends EthitrustApiError {
+    errors;
+    constructor(opts) {
+        super(opts);
+        this.name = 'EthitrustValidationError';
+        const body = opts.body;
+        this.errors = body?.detail ?? [];
+    }
+}
+/** 401 / 403 — invalid or insufficient credentials. */
+export class EthitrustAuthError extends EthitrustApiError {
+    constructor(opts) {
+        super(opts);
+        this.name = 'EthitrustAuthError';
+    }
+}
+/** 404. */
+export class EthitrustNotFoundError extends EthitrustApiError {
+    constructor(opts) {
+        super(opts);
+        this.name = 'EthitrustNotFoundError';
+    }
+}
+/** 409 — idempotency or business-rule conflict. */
+export class EthitrustConflictError extends EthitrustApiError {
+    constructor(opts) {
+        super(opts);
+        this.name = 'EthitrustConflictError';
+    }
+}
+/** 429 — too many requests. */
+export class EthitrustRateLimitError extends EthitrustApiError {
+    retryAfter;
+    constructor(opts) {
+        super(opts);
+        this.name = 'EthitrustRateLimitError';
+        this.retryAfter = opts.retryAfter;
+    }
+}
+/** Network / fetch / timeout level failure. */
+export class EthitrustNetworkError extends EthitrustError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'EthitrustNetworkError';
+        this.cause = cause;
+    }
+}
+/** Request was aborted (timeout or user signal). */
+export class EthitrustAbortError extends EthitrustError {
+    constructor(message = 'Request aborted') {
+        super(message);
+        this.name = 'EthitrustAbortError';
+    }
+}
+function extractMessage(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const b = body;
+    if (typeof b.message === 'string')
+        return b.message;
+    if (typeof b.error === 'string')
+        return b.error;
+    if (typeof b.detail === 'string')
+        return b.detail;
+    if (Array.isArray(b.detail) && b.detail.length > 0) {
+        const first = b.detail[0];
+        return `${first.msg} (at ${first.loc?.join('.') ?? '?'})`;
+    }
+    return undefined;
+}
+export function buildApiError(opts) {
+    if (opts.status === 401 || opts.status === 403)
+        return new EthitrustAuthError(opts);
+    if (opts.status === 404)
+        return new EthitrustNotFoundError(opts);
+    if (opts.status === 409)
+        return new EthitrustConflictError(opts);
+    if (opts.status === 422)
+        return new EthitrustValidationError(opts);
+    if (opts.status === 429)
+        return new EthitrustRateLimitError(opts);
+    return new EthitrustApiError(opts);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/http.d.ts

@@ -0,0 +1,49 @@
+export interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    /** Header name carrying the API key. Defaults to `X-API-Key`. */
+    apiKeyHeader?: string;
+    /** Per-request timeout in milliseconds. Defaults to 30 000. */
+    timeoutMs?: number;
+    /** Max retries for transient failures (network, 429, 5xx). Defaults to 2. */
+    maxRetries?: number;
+    /** Base delay (ms) for exponential backoff. Defaults to 300. */
+    retryBaseDelayMs?: number;
+    /** Custom fetch implementation. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Extra headers added to every request. */
+    defaultHeaders?: Record<string, string>;
+    /** User agent appended to `User-Agent` (Node only). */
+    userAgent?: string;
+}
+export interface RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    /** Adds an `X-Idempotency-Key` header. */
+    idempotencyKey?: string;
+    /** Overrides per-request timeout. */
+    timeoutMs?: number;
+    /** Abort signal supplied by the caller. */
+    signal?: AbortSignal;
+    /** Extra headers for this request. */
+    headers?: Record<string, string>;
+}
+export declare class HttpClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly apiKeyHeader;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    constructor(opts: HttpClientOptions);
+    request<T>(opts: RequestOptions): Promise<T>;
+    private buildUrl;
+    private buildHeaders;
+    private shouldRetry;
+    private backoff;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;gBAE5C,IAAI,EAAE,iBAAiB;IAuB7B,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IA+ElD,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,OAAO;CAKhB"}