@ethitrust/sdk 1.0.0

package/src/http.ts

@@ -0,0 +1,246 @@
+import {
+  EthitrustAbortError,
+  EthitrustNetworkError,
+  EthitrustRateLimitError,
+  buildApiError,
+} from './errors.js';
+import { toQueryString } from './utils/query.js';
+
+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 class HttpClient {
+  readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly apiKeyHeader: string;
+  private readonly timeoutMs: number;
+  private readonly maxRetries: number;
+  private readonly retryBaseDelayMs: number;
+  private readonly fetchImpl: typeof fetch;
+  private readonly defaultHeaders: Record<string, string>;
+
+  constructor(opts: HttpClientOptions) {
+    if (!opts.apiKey) throw new Error('apiKey is required');
+    if (!opts.baseUrl) throw new Error('baseUrl is required');
+    this.apiKey = opts.apiKey;
+    this.apiKeyHeader = opts.apiKeyHeader ?? 'X-API-Key';
+    this.baseUrl = stripTrailingSlash(opts.baseUrl);
+    this.timeoutMs = opts.timeoutMs ?? 30_000;
+    this.maxRetries = opts.maxRetries ?? 2;
+    this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 300;
+    const fImpl = opts.fetch ?? globalThis.fetch;
+    if (!fImpl) {
+      throw new Error(
+        'No fetch implementation found. Use Node 18+ or pass `fetch` explicitly.',
+      );
+    }
+    this.fetchImpl = fImpl.bind(globalThis);
+    this.defaultHeaders = {
+      Accept: 'application/json',
+      'User-Agent': opts.userAgent ?? '@ethitrust/sdk/1.0.0 node',
+      ...opts.defaultHeaders,
+    };
+  }
+
+  async request<T>(opts: RequestOptions): Promise<T> {
+    const url = this.buildUrl(opts.path, opts.query);
+    const headers = this.buildHeaders(opts);
+
+    const hasBody = opts.body !== undefined && opts.body !== null;
+    const init: RequestInit = {
+      method: opts.method,
+      headers,
+      body: hasBody ? JSON.stringify(opts.body) : undefined,
+    };
+
+    let attempt = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const { signal, cancel } = mergeSignals(
+        opts.signal,
+        opts.timeoutMs ?? this.timeoutMs,
+      );
+      try {
+        const response = await this.fetchImpl(url, { ...init, signal });
+        cancel();
+        if (response.ok) {
+          return (await parseBody(response)) as T;
+        }
+
+        const body = await parseBody(response);
+        const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));
+        const err = buildApiError({
+          status: response.status,
+          statusText: response.statusText,
+          url,
+          method: opts.method,
+          body,
+          requestId: response.headers.get('X-Request-Id') ?? undefined,
+          retryAfter,
+        });
+
+        if (this.shouldRetry(response.status, attempt) && opts.method === 'GET') {
+          await sleep(this.backoff(attempt, retryAfter));
+          attempt++;
+          continue;
+        }
+        // Always retry 429s regardless of method, since the server signals it.
+        if (response.status === 429 && attempt < this.maxRetries) {
+          await sleep(this.backoff(attempt, retryAfter));
+          attempt++;
+          continue;
+        }
+        throw err;
+      } catch (err) {
+        cancel();
+        if (err instanceof EthitrustRateLimitError) throw err;
+        if (isAbortError(err)) {
+          if (opts.signal?.aborted) throw new EthitrustAbortError();
+          // Timeout: treat as network error, eligible for retry on GET.
+          if (opts.method === 'GET' && attempt < this.maxRetries) {
+            await sleep(this.backoff(attempt));
+            attempt++;
+            continue;
+          }
+          throw new EthitrustNetworkError('Request timed out', err);
+        }
+        // Non-API error rethrown (validation, etc.).
+        if (err && typeof err === 'object' && 'status' in (err as object)) {
+          throw err;
+        }
+        if (opts.method === 'GET' && attempt < this.maxRetries) {
+          await sleep(this.backoff(attempt));
+          attempt++;
+          continue;
+        }
+        throw new EthitrustNetworkError(
+          err instanceof Error ? err.message : 'Network error',
+          err,
+        );
+      }
+    }
+  }
+
+  private buildUrl(path: string, query?: Record<string, unknown>): string {
+    const p = path.startsWith('/') ? path : `/${path}`;
+    const qs = query ? toQueryString(query) : '';
+    return `${this.baseUrl}${p}${qs}`;
+  }
+
+  private buildHeaders(opts: RequestOptions): Headers {
+    const h = new Headers(this.defaultHeaders);
+    h.set(this.apiKeyHeader, this.apiKey);
+    if (opts.body !== undefined && opts.body !== null) {
+      h.set('Content-Type', 'application/json');
+    }
+    if (opts.idempotencyKey) {
+      h.set('X-Idempotency-Key', opts.idempotencyKey);
+    }
+    if (opts.headers) {
+      for (const [k, v] of Object.entries(opts.headers)) h.set(k, v);
+    }
+    return h;
+  }
+
+  private shouldRetry(status: number, attempt: number): boolean {
+    if (attempt >= this.maxRetries) return false;
+    return status >= 500 && status < 600;
+  }
+
+  private backoff(attempt: number, retryAfterSec?: number): number {
+    if (retryAfterSec && retryAfterSec > 0) return retryAfterSec * 1000;
+    const jitter = Math.random() * 0.25 + 0.875; // 0.875–1.125
+    return Math.min(this.retryBaseDelayMs * 2 ** attempt * jitter, 10_000);
+  }
+}
+
+function stripTrailingSlash(s: string): string {
+  return s.endsWith('/') ? s.slice(0, -1) : s;
+}
+
+async function parseBody(res: Response): Promise<unknown> {
+  if (res.status === 204) return undefined;
+  const ct = res.headers.get('Content-Type') ?? '';
+  if (ct.includes('application/json')) {
+    try {
+      return await res.json();
+    } catch {
+      return undefined;
+    }
+  }
+  const txt = await res.text();
+  return txt || undefined;
+}
+
+function parseRetryAfter(h: string | null): number | undefined {
+  if (!h) return undefined;
+  const n = Number(h);
+  if (Number.isFinite(n)) return n;
+  const date = Date.parse(h);
+  if (Number.isFinite(date)) {
+    return Math.max(0, Math.round((date - Date.now()) / 1000));
+  }
+  return undefined;
+}
+
+function mergeSignals(
+  user: AbortSignal | undefined,
+  timeoutMs: number,
+): { signal: AbortSignal; cancel: () => void } {
+  const ctrl = new AbortController();
+  const onUserAbort = () => ctrl.abort(user?.reason);
+  if (user) {
+    if (user.aborted) ctrl.abort(user.reason);
+    else user.addEventListener('abort', onUserAbort, { once: true });
+  }
+  const timer = setTimeout(() => ctrl.abort(new Error('timeout')), timeoutMs);
+  return {
+    signal: ctrl.signal,
+    cancel: () => {
+      clearTimeout(timer);
+      if (user) user.removeEventListener('abort', onUserAbort);
+    },
+  };
+}
+
+function isAbortError(err: unknown): boolean {
+  return (
+    err instanceof Error &&
+    (err.name === 'AbortError' || err.name === 'TimeoutError')
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { EthitrustClient } from './client.js';
+export type { EthitrustClientOptions } from './client.js';
+
+export { HttpClient } from './http.js';
+export type { HttpClientOptions, RequestOptions } from './http.js';
+
+export { OrgEscrowsResource } from './resources/orgEscrows.js';
+export type { RequestExtras } from './resources/orgEscrows.js';
+
+export { generateIdempotencyKey } from './utils/idempotency.js';
+
+export * from './types.js';
+export {
+  EthitrustError,
+  EthitrustApiError,
+  EthitrustAuthError,
+  EthitrustNotFoundError,
+  EthitrustConflictError,
+  EthitrustValidationError,
+  EthitrustRateLimitError,
+  EthitrustNetworkError,
+  EthitrustAbortError,
+} from './errors.js';

package/src/resources/orgEscrows.ts

@@ -0,0 +1,246 @@
+import type { HttpClient } from '../http.js';
+import type {
+  InitializeEscrowResponse,
+  ListOrgEscrowsParams,
+  OrgEscrowAuditTrailResponse,
+  OrgEscrowCancelResponse,
+  OrgEscrowDetailResponse,
+  OrgEscrowHealthResponse,
+  OrgEscrowListItem,
+  OrgEscrowListResponse,
+  OrgEscrowReportParams,
+  OrgEscrowReportResponse,
+  OrgEscrowStatusResponse,
+  OrganizationInitializeEscrowRequest,
+  WebhookLogEntry,
+  WebhookTestResponse,
+} from '../types.js';
+import { generateIdempotencyKey } from '../utils/idempotency.js';
+
+export interface RequestExtras {
+  /**
+   * Idempotency key for write operations. If omitted, the SDK auto-generates
+   * a UUID v4 so safe retries remain idempotent.
+   * Pass `null` to explicitly disable the header.
+   */
+  idempotencyKey?: string | null;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+}
+
+export class OrgEscrowsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  // ── CRUD-ish ──────────────────────────────────────────────────────────────
+
+  /** POST /api/v1/org-escrows — initialise a new escrow on behalf of the org. */
+  create(
+    body: OrganizationInitializeEscrowRequest,
+    extras: RequestExtras = {},
+  ): Promise<InitializeEscrowResponse> {
+    return this.http.request<InitializeEscrowResponse>({
+      method: 'POST',
+      path: '/api/v1/org-escrows',
+      body,
+      idempotencyKey: resolveIdempotencyKey(extras.idempotencyKey),
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /** GET /api/v1/org-escrows — paginated, filterable list. */
+  list(
+    params: ListOrgEscrowsParams = {},
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): Promise<OrgEscrowListResponse> {
+    return this.http.request<OrgEscrowListResponse>({
+      method: 'GET',
+      path: '/api/v1/org-escrows',
+      query: params as Record<string, unknown>,
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /**
+   * Async iterator over every page of org escrows. Yields individual
+   * `OrgEscrowListItem` records.
+   *
+   * ```ts
+   * for await (const e of client.orgEscrows.iter({ status: 'active' })) {
+   *   console.log(e.escrow_id);
+   * }
+   * ```
+   */
+  async *iter(
+    params: ListOrgEscrowsParams = {},
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): AsyncGenerator<OrgEscrowListItem, void, void> {
+    let page = params.page ?? 1;
+    const pageSize = params.page_size ?? 20;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const res = await this.list({ ...params, page, page_size: pageSize }, extras);
+      for (const item of res.items) yield item;
+      if (page >= res.total_pages || res.items.length === 0) return;
+      page++;
+    }
+  }
+
+  /** GET /api/v1/org-escrows/{escrow_id} — lightweight status snapshot. */
+  getStatus(
+    escrowId: string,
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): Promise<OrgEscrowStatusResponse> {
+    return this.http.request<OrgEscrowStatusResponse>({
+      method: 'GET',
+      path: `/api/v1/org-escrows/${encodeURIComponent(escrowId)}`,
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /** GET /api/v1/org-escrows/{escrow_id}/detail — full detail incl. progress, risk flags. */
+  getDetail(
+    escrowId: string,
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): Promise<OrgEscrowDetailResponse> {
+    return this.http.request<OrgEscrowDetailResponse>({
+      method: 'GET',
+      path: `/api/v1/org-escrows/${encodeURIComponent(escrowId)}/detail`,
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /** GET /api/v1/org-escrows/{escrow_id}/events — audit trail. */
+  getEvents(
+    escrowId: string,
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): Promise<OrgEscrowAuditTrailResponse> {
+    return this.http.request<OrgEscrowAuditTrailResponse>({
+      method: 'GET',
+      path: `/api/v1/org-escrows/${encodeURIComponent(escrowId)}/events`,
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /** GET /api/v1/org-escrows/{escrow_id}/health — boolean state flags. */
+  getHealth(
+    escrowId: string,
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): Promise<OrgEscrowHealthResponse> {
+    return this.http.request<OrgEscrowHealthResponse>({
+      method: 'GET',
+      path: `/api/v1/org-escrows/${encodeURIComponent(escrowId)}/health`,
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /** POST /api/v1/org-escrows/{escrow_id}/cancel — cancel & refund (if eligible). */
+  cancel(
+    escrowId: string,
+    extras: RequestExtras = {},
+  ): Promise<OrgEscrowCancelResponse> {
+    return this.http.request<OrgEscrowCancelResponse>({
+      method: 'POST',
+      path: `/api/v1/org-escrows/${encodeURIComponent(escrowId)}/cancel`,
+      idempotencyKey: resolveIdempotencyKey(extras.idempotencyKey),
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /** POST /api/v1/org-escrows/{escrow_id}/resend — resend the invitation email. */
+  resendInvitation(
+    escrowId: string,
+    extras: RequestExtras = {},
+  ): Promise<InitializeEscrowResponse> {
+    return this.http.request<InitializeEscrowResponse>({
+      method: 'POST',
+      path: `/api/v1/org-escrows/${encodeURIComponent(escrowId)}/resend`,
+      idempotencyKey: resolveIdempotencyKey(extras.idempotencyKey),
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  // ── Reports ───────────────────────────────────────────────────────────────────
+
+  /** GET /api/v1/org-escrows/reports/summary — org-wide aggregates over a period. */
+  getReport(
+    params: OrgEscrowReportParams = {},
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): Promise<OrgEscrowReportResponse> {
+    return this.http.request<OrgEscrowReportResponse>({
+      method: 'GET',
+      path: '/api/v1/org-escrows/reports/summary',
+      query: params as Record<string, unknown>,
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  // ── Webhooks ─────────────────────────────────────────────────────────────────
+
+  /** GET /api/v1/org-escrows/{escrow_id}/webhooks — deliveries for one escrow. */
+  listEscrowWebhookLogs(
+    escrowId: string,
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): Promise<WebhookLogEntry[]> {
+    return this.http.request<WebhookLogEntry[]>({
+      method: 'GET',
+      path: `/api/v1/org-escrows/${encodeURIComponent(escrowId)}/webhooks`,
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /** GET /api/v1/org-escrows/webhooks — 50 most recent deliveries across the org. */
+  listWebhookLogs(
+    extras: Omit<RequestExtras, 'idempotencyKey'> = {},
+  ): Promise<WebhookLogEntry[]> {
+    return this.http.request<WebhookLogEntry[]>({
+      method: 'GET',
+      path: '/api/v1/org-escrows/webhooks',
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+
+  /** POST /api/v1/org-escrows/webhooks/test — send a synthetic delivery. */
+  testWebhook(
+    extras: RequestExtras = {},
+  ): Promise<WebhookTestResponse> {
+    return this.http.request<WebhookTestResponse>({
+      method: 'POST',
+      path: '/api/v1/org-escrows/webhooks/test',
+      idempotencyKey: resolveIdempotencyKey(extras.idempotencyKey),
+      signal: extras.signal,
+      timeoutMs: extras.timeoutMs,
+      headers: extras.headers,
+    });
+  }
+}
+
+function resolveIdempotencyKey(
+  k: string | null | undefined,
+): string | undefined {
+  if (k === null) return undefined; // explicitly disabled
+  if (k === undefined) return generateIdempotencyKey();
+  return k;
+}