@ethitrust/sdk 1.0.0

package/src/types.ts

@@ -0,0 +1,286 @@
+/**
+ * Typed models for the Ethitrust org-escrows API.
+ * Generated by hand from the OpenAPI spec (ethi-mono v0.1.0).
+ */
+
+// ───── Enums ─────────────────────────────────────────────────────────────────
+
+export type EscrowType = 'onetime' | 'milestone' | 'recurring';
+
+export type EscrowStatus =
+  | 'invited'
+  | 'counter_pending_initiator'
+  | 'counter_pending_counterparty'
+  | 'rejected'
+  | 'expired'
+  | 'pending'
+  | 'active'
+  | 'submitted'
+  | 'in_review'
+  | 'completed'
+  | 'disputed'
+  | 'cancelled'
+  | 'refunded';
+
+export type InitiatorActorType = 'user' | 'organization';
+export type InitiatorRole = 'buyer' | 'seller';
+export type FeePayer = 'buyer' | 'seller' | 'split';
+export type CounterStatus =
+  | 'none'
+  | 'awaiting_initiator'
+  | 'awaiting_counterparty'
+  | 'accepted'
+  | 'rejected';
+export type RiskSeverity = 'low' | 'medium' | 'high';
+export type MilestoneStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'delivered'
+  | 'completed'
+  | 'disputed';
+
+// ───── Shared sub-types ──────────────────────────────────────────────────────
+
+export interface RiskFlag {
+  code: string;
+  message: string;
+  severity: RiskSeverity;
+}
+
+export interface LatestEvent {
+  event_type: string;
+  actor: string;
+  timestamp: string;
+  metadata?: Record<string, unknown> | null;
+}
+
+export interface EscrowVolumePoint {
+  date: string;
+  count: number;
+  total_amount: number;
+}
+
+export interface MilestoneRequest {
+  title: string;
+  description?: string | null;
+  amount: number;
+  due_date?: string | null;
+  /** Defaults to 48 on the server. */
+  inspection_hrs?: number;
+}
+
+export interface MilestoneResponse {
+  id: string;
+  escrow_id: string;
+  title: string;
+  description: string | null;
+  amount: number;
+  due_date: string | null;
+  inspection_hrs: number;
+  status: MilestoneStatus;
+  delivered_at: string | null;
+  completed_at: string | null;
+  sort_order: number;
+}
+
+// ───── Requests ──────────────────────────────────────────────────────────────
+
+export interface OrganizationInitializeEscrowRequest {
+  invitee_email: string;
+  /** Defaults to 'onetime'. */
+  escrow_type?: EscrowType;
+  title: string;
+  description?: string | null;
+  /** Defaults to 'ETB'. */
+  currency?: string;
+  amount: number;
+  acceptance_criteria?: string | null;
+  /** Hours. Defaults to 48. */
+  inspection_period?: number;
+  delivery_date?: string | null;
+  /** Hours. Defaults to 72. */
+  dispute_window?: number;
+  /** Defaults to 'buyer'. */
+  who_pays_fees?: FeePayer;
+  milestones?: MilestoneRequest[] | null;
+}
+
+export interface ListOrgEscrowsParams {
+  status?: string;
+  is_active?: boolean;
+  /** ISO 8601 date-time. */
+  date_from?: string | Date;
+  /** ISO 8601 date-time. */
+  date_to?: string | Date;
+  search?: string;
+  page?: number;
+  page_size?: number;
+}
+
+export interface OrgEscrowReportParams {
+  /** ISO 8601 date-time. */
+  date_from?: string | Date;
+  /** ISO 8601 date-time. */
+  date_to?: string | Date;
+}
+
+// ───── Responses ─────────────────────────────────────────────────────────────
+
+export interface InitializeEscrowResponse {
+  id: string;
+  escrow_type: EscrowType;
+  status: EscrowStatus;
+  initiator_actor_type: InitiatorActorType;
+  initiator_id: string | null;
+  initiator_org_id: string | null;
+  receiver_id: string | null;
+  receiver_email: string | null;
+  initiator_role: InitiatorRole;
+  title: string;
+  description: string | null;
+  currency: string;
+  amount: number;
+  fee_amount: number;
+  acceptance_criteria: string | null;
+  inspection_period: number;
+  delivery_date: string | null;
+  dispute_window: number;
+  who_pays_fees: FeePayer;
+  org_id: string | null;
+  offer_version: number;
+  counter_status: CounterStatus;
+  active_counter_offer_version: number | null;
+  created_at: string;
+  updated_at: string;
+  invitation_sent?: boolean;
+}
+
+export interface OrgEscrowCancelResponse extends InitializeEscrowResponse {
+  refunded?: boolean;
+}
+
+export interface OrgEscrowListItem {
+  escrow_id: string;
+  organization_id: string | null;
+  title: string;
+  status: string;
+  is_active: boolean;
+  amount: number;
+  currency: string;
+  receiver_email?: string | null;
+  funded_amount: number;
+  created_at: string;
+  updated_at: string;
+  expires_at?: string | null;
+}
+
+export interface OrgEscrowListResponse {
+  items: OrgEscrowListItem[];
+  page: number;
+  page_size: number;
+  total: number;
+  total_pages: number;
+}
+
+export interface OrgEscrowStatusResponse {
+  escrow_id: string;
+  organization_id: string | null;
+  status: string;
+  is_active: boolean;
+  can_cancel: boolean;
+  can_resend_invite: boolean;
+  can_accept: boolean;
+  expires_at: string | null;
+  funded_amount: number;
+  currency: string;
+  amount: number;
+  updated_at: string;
+}
+
+export interface OrgEscrowDetailResponse extends OrgEscrowStatusResponse {
+  title: string;
+  description?: string | null;
+  escrow_type: string;
+  initiator_role: string;
+  receiver_email?: string | null;
+  receiver_id?: string | null;
+  fee_amount: number;
+  who_pays_fees: string;
+  created_at: string;
+  /** 0-100. */
+  progress_percentage: number;
+  current_phase: string;
+  next_action?: string | null;
+  risk_flags?: RiskFlag[];
+  latest_event?: LatestEvent | null;
+}
+
+export interface OrgEscrowHealthResponse {
+  escrow_id: string;
+  is_active: boolean;
+  is_expired: boolean;
+  is_fundable: boolean;
+  is_cancellable: boolean;
+  is_disputable: boolean;
+  is_settled: boolean;
+}
+
+export interface OrgEscrowReportResponse {
+  organization_id: string;
+  period_from: string;
+  period_to: string;
+  total_escrows: number;
+  active_escrow_count: number;
+  completion_rate: number;
+  dispute_rate: number;
+  avg_settlement_time_hours?: number | null;
+  volume_over_time?: EscrowVolumePoint[];
+}
+
+export interface OrgEscrowAuditEvent {
+  event_id: string;
+  escrow_id: string;
+  actor: string;
+  action: string;
+  timestamp: string;
+  metadata?: Record<string, unknown> | null;
+}
+
+export interface OrgEscrowAuditTrailResponse {
+  escrow_id: string;
+  events: OrgEscrowAuditEvent[];
+  total: number;
+}
+
+export interface WebhookLogEntry {
+  id: string;
+  event_type: string;
+  target_url: string;
+  http_status: number | null;
+  attempt: number;
+  delivery_status: string;
+  error_message?: string | null;
+  created_at: string;
+  next_retry_at?: string | null;
+}
+
+export interface WebhookTestResponse {
+  success: boolean;
+  http_status?: number | null;
+  error?: string | null;
+  target_url?: string | null;
+}
+
+// ───── Validation error envelope ─────────────────────────────────────────────
+
+export interface ValidationErrorItem {
+  loc: Array<string | number>;
+  msg: string;
+  type: string;
+  input?: unknown;
+  ctx?: Record<string, unknown>;
+}
+
+export interface HTTPValidationError {
+  detail?: ValidationErrorItem[];
+}

package/src/utils/idempotency.ts

@@ -0,0 +1,23 @@
+import { randomUUID, randomBytes } from 'node:crypto';
+
+/**
+ * Generate a RFC-4122 v4 idempotency key suitable for the
+ * `X-Idempotency-Key` header.
+ *
+ * Falls back to the Web Crypto API when `node:crypto` is unavailable
+ * (e.g. edge runtimes).
+ */
+export function generateIdempotencyKey(prefix?: string): string {
+  let id: string;
+  try {
+    id = randomUUID();
+  } catch {
+    const g = globalThis as { crypto?: { randomUUID?: () => string } };
+    if (g.crypto?.randomUUID) {
+      id = g.crypto.randomUUID();
+    } else {
+      id = randomBytes(16).toString('hex');
+    }
+  }
+  return prefix ? `${prefix}_${id}` : id;
+}

package/src/utils/query.ts

@@ -0,0 +1,31 @@
+/**
+ * Serialise a flat record to a URLSearchParams instance.
+ *  - `undefined` / `null` values are skipped.
+ *  - `Date` objects are serialised to ISO 8601.
+ *  - Arrays are repeated as `?key=a&key=b`.
+ */
+export function toQueryString(
+  params: Record<string, unknown> | undefined,
+): string {
+  if (!params) return '';
+  const usp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined || v === null) continue;
+    if (Array.isArray(v)) {
+      for (const item of v) {
+        if (item === undefined || item === null) continue;
+        usp.append(k, serialiseScalar(item));
+      }
+    } else {
+      usp.append(k, serialiseScalar(v));
+    }
+  }
+  const s = usp.toString();
+  return s ? `?${s}` : '';
+}
+
+function serialiseScalar(v: unknown): string {
+  if (v instanceof Date) return v.toISOString();
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  return String(v);
+}