@avenlabs/halal-trace-sdk 0.1.1

package/src/http.ts

@@ -0,0 +1,449 @@
+import type { ApiErrorResponse } from "./types.js";
+
+export type AuthOptions =
+  | { token: string }
+  | { getToken: () => Promise<string> | string }
+  | undefined;
+
+export type RetryOptions = {
+  enabled?: boolean;
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  jitterMs?: number;
+};
+
+export type ClientHooks = {
+  onRequest?: (context: RequestContext) => void | Promise<void>;
+  onResponse?: (context: ResponseContext) => void | Promise<void>;
+  onError?: (context: ErrorContext) => void | Promise<void>;
+};
+
+export type RequestContext = {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  requestId: string;
+};
+
+export type ResponseContext = {
+  method: string;
+  url: string;
+  status: number;
+  requestId: string;
+  durationMs: number;
+};
+
+export type ErrorContext = {
+  method: string;
+  url: string;
+  status?: number;
+  requestId: string;
+  durationMs: number;
+  error: Error;
+};
+
+export class ApiError extends Error {
+  status?: number;
+  body?: unknown;
+  requestId?: string;
+
+  constructor(message: string, status?: number, body?: unknown, requestId?: string) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.requestId = requestId;
+  }
+}
+
+export type RequestOptions = {
+  headers?: Record<string, string>;
+  body?: unknown;
+  query?: Record<string, string | number | boolean | undefined | null>;
+  timeoutMs?: number;
+  idempotencyKey?: string;
+  allowInsecure?: boolean;
+  retry?: RetryOptions;
+  auth?: AuthOptions;
+  onAuthError?: (error: ApiError) => void | Promise<void>;
+  requestId?: string;
+  sdkHeaders?: Record<string, string>;
+  hooks?: ClientHooks;
+  signingHook?: (context: RequestContext) => Promise<Record<string, string> | void> | Record<string, string> | void;
+  canRetry?: boolean;
+};
+
+const defaultRetry: Required<RetryOptions> = {
+  enabled: true,
+  maxRetries: 2,
+  baseDelayMs: 250,
+  maxDelayMs: 2000,
+  jitterMs: 200,
+};
+
+const transientStatuses = new Set([408, 429, 500, 502, 503, 504]);
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const buildQuery = (query?: RequestOptions["query"]) => {
+  if (!query) {
+    return "";
+  }
+  const entries = Object.entries(query)
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([key, value]) => [key, String(value)]);
+  if (entries.length === 0) {
+    return "";
+  }
+  const params = new URLSearchParams(entries);
+  return `?${params.toString()}`;
+};
+
+const computeBackoff = (attempt: number, baseDelayMs: number, maxDelayMs: number, jitterMs: number) => {
+  const delay = Math.min(baseDelayMs * Math.pow(2, Math.max(attempt - 1, 0)), maxDelayMs);
+  const jitter = Math.floor(Math.random() * jitterMs);
+  return delay + jitter;
+};
+
+const parseRetryAfter = (value: string | null): number | null => {
+  if (!value) {
+    return null;
+  }
+  const seconds = Number(value);
+  if (!Number.isNaN(seconds)) {
+    return seconds * 1000;
+  }
+  const date = Date.parse(value);
+  if (!Number.isNaN(date)) {
+    const delta = date - Date.now();
+    return delta > 0 ? delta : null;
+  }
+  return null;
+};
+
+const ensureHttps = (url: string, allowInsecure?: boolean) => {
+  if (allowInsecure) {
+    return;
+  }
+  if (url.startsWith("http://")) {
+    throw new Error("Insecure baseUrl blocked. Set allowInsecure=true for http://");
+  }
+};
+
+const now = () => (globalThis.performance?.now ? globalThis.performance.now() : Date.now());
+
+const generateRequestId = () => {
+  if (globalThis.crypto?.randomUUID) {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+};
+
+export const request = async <T>(
+  baseUrl: string,
+  path: string,
+  method: string,
+  options: RequestOptions,
+) => {
+  if (!baseUrl) {
+    throw new Error("baseUrl is required");
+  }
+  if (options.timeoutMs !== undefined && options.timeoutMs <= 0) {
+    throw new Error("timeoutMs must be greater than 0");
+  }
+  ensureHttps(baseUrl, options.allowInsecure);
+
+  const retryConfig = { ...defaultRetry, ...options.retry };
+  const url = `${baseUrl.replace(/\/$/, "")}${path}${buildQuery(options.query)}`;
+  const requestId = options.requestId ?? generateRequestId();
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "x-request-id": requestId,
+    ...(options.sdkHeaders ?? {}),
+    ...(options.headers ?? {}),
+  };
+
+  if (options.idempotencyKey) {
+    headers["Idempotency-Key"] = options.idempotencyKey;
+  }
+
+  if (options.auth) {
+    if ("token" in options.auth) {
+      headers.Authorization = `Bearer ${options.auth.token}`;
+    } else if ("getToken" in options.auth) {
+      const token = await options.auth.getToken();
+      if (token) {
+        headers.Authorization = `Bearer ${token}`;
+      }
+    }
+  }
+
+  const body = options.body ? JSON.stringify(options.body) : undefined;
+  const context: RequestContext = { method, url, headers, body: options.body, requestId };
+  if (options.signingHook) {
+    const extraHeaders = await options.signingHook(context);
+    if (extraHeaders) {
+      Object.assign(headers, extraHeaders);
+    }
+  }
+  if (options.hooks?.onRequest) {
+    await options.hooks.onRequest(context);
+  }
+
+  const start = now();
+  let lastError: ApiError | undefined;
+
+  for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt += 1) {
+    try {
+      const controller = options.timeoutMs ? new AbortController() : undefined;
+      const timeoutHandle = options.timeoutMs
+        ? setTimeout(() => controller?.abort(), options.timeoutMs)
+        : undefined;
+      const response = await fetch(url, {
+        method,
+        headers,
+        body,
+        signal: controller?.signal,
+      });
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+      const durationMs = now() - start;
+      const responseRequestId = response.headers.get("x-request-id") ?? requestId;
+      const responseText = await response.text();
+      let responseBody: ApiErrorResponse | T | undefined;
+      if (responseText) {
+        try {
+          responseBody = JSON.parse(responseText) as ApiErrorResponse | T;
+        } catch {
+          responseBody = undefined;
+        }
+      }
+      if (!response.ok) {
+        const message =
+          typeof responseBody === "object" && responseBody && "message" in responseBody
+            ? String((responseBody as ApiErrorResponse).message)
+            : `Request failed: ${response.status}`;
+        const error = new ApiError(message, response.status, responseBody, responseRequestId);
+        if (response.status === 401 && options.onAuthError) {
+          await options.onAuthError(error);
+        }
+        const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+        const shouldRetry =
+          retryConfig.enabled &&
+          options.canRetry &&
+          transientStatuses.has(response.status) &&
+          attempt < retryConfig.maxRetries;
+        if (shouldRetry) {
+          const delay = retryAfter ?? computeBackoff(attempt + 1, retryConfig.baseDelayMs, retryConfig.maxDelayMs, retryConfig.jitterMs);
+          await sleep(delay);
+          continue;
+        }
+        if (options.hooks?.onError) {
+          await options.hooks.onError({
+            method,
+            url,
+            status: response.status,
+            requestId: responseRequestId,
+            durationMs,
+            error,
+          });
+        }
+        throw error;
+      }
+      if (options.hooks?.onResponse) {
+        await options.hooks.onResponse({
+          method,
+          url,
+          status: response.status,
+          requestId: responseRequestId,
+          durationMs,
+        });
+      }
+      return { body: responseBody as T, requestId: responseRequestId };
+    } catch (error) {
+      const durationMs = now() - start;
+      const apiError = error instanceof ApiError ? error : new ApiError("Network error", undefined, undefined, requestId);
+      lastError = apiError;
+      if (
+        retryConfig.enabled &&
+        options.canRetry &&
+        attempt < retryConfig.maxRetries
+      ) {
+        const delay = computeBackoff(attempt + 1, retryConfig.baseDelayMs, retryConfig.maxDelayMs, retryConfig.jitterMs);
+        await sleep(delay);
+        continue;
+      }
+      if (options.hooks?.onError) {
+        await options.hooks.onError({
+          method,
+          url,
+          requestId,
+          durationMs,
+          error: apiError,
+        });
+      }
+      throw apiError;
+    }
+  }
+
+  if (lastError) {
+    throw lastError;
+  }
+  throw new ApiError("Request failed", undefined, undefined, requestId);
+};
+
+export const requestRaw = async (
+  baseUrl: string,
+  path: string,
+  method: string,
+  options: RequestOptions,
+) => {
+  if (!baseUrl) {
+    throw new Error("baseUrl is required");
+  }
+  if (options.timeoutMs !== undefined && options.timeoutMs <= 0) {
+    throw new Error("timeoutMs must be greater than 0");
+  }
+  ensureHttps(baseUrl, options.allowInsecure);
+
+  const retryConfig = { ...defaultRetry, ...options.retry };
+  const url = `${baseUrl.replace(/\/$/, "")}${path}${buildQuery(options.query)}`;
+  const requestId = options.requestId ?? generateRequestId();
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "x-request-id": requestId,
+    ...(options.sdkHeaders ?? {}),
+    ...(options.headers ?? {}),
+  };
+
+  if (options.idempotencyKey) {
+    headers["Idempotency-Key"] = options.idempotencyKey;
+  }
+
+  if (options.auth) {
+    if ("token" in options.auth) {
+      headers.Authorization = `Bearer ${options.auth.token}`;
+    } else if ("getToken" in options.auth) {
+      const token = await options.auth.getToken();
+      if (token) {
+        headers.Authorization = `Bearer ${token}`;
+      }
+    }
+  }
+
+  const body = options.body ? JSON.stringify(options.body) : undefined;
+  const context: RequestContext = { method, url, headers, body: options.body, requestId };
+  if (options.signingHook) {
+    const extraHeaders = await options.signingHook(context);
+    if (extraHeaders) {
+      Object.assign(headers, extraHeaders);
+    }
+  }
+  if (options.hooks?.onRequest) {
+    await options.hooks.onRequest(context);
+  }
+
+  const start = now();
+  let lastError: ApiError | undefined;
+
+  for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt += 1) {
+    try {
+      const controller = options.timeoutMs ? new AbortController() : undefined;
+      const timeoutHandle = options.timeoutMs
+        ? setTimeout(() => controller?.abort(), options.timeoutMs)
+        : undefined;
+      const response = await fetch(url, {
+        method,
+        headers,
+        body,
+        signal: controller?.signal,
+      });
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+      const durationMs = now() - start;
+      const responseRequestId = response.headers.get("x-request-id") ?? requestId;
+      const responseText = await response.text();
+      let responseBody: unknown = responseText;
+      if (responseText) {
+        try {
+          responseBody = JSON.parse(responseText);
+        } catch {
+          responseBody = responseText;
+        }
+      }
+      if (!response.ok) {
+        const message =
+          typeof responseBody === "object" && responseBody && "message" in (responseBody as ApiErrorResponse)
+            ? String((responseBody as ApiErrorResponse).message)
+            : `Request failed: ${response.status}`;
+        const error = new ApiError(message, response.status, responseBody, responseRequestId);
+        if (response.status === 401 && options.onAuthError) {
+          await options.onAuthError(error);
+        }
+        const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+        const shouldRetry =
+          retryConfig.enabled &&
+          options.canRetry &&
+          transientStatuses.has(response.status) &&
+          attempt < retryConfig.maxRetries;
+        if (shouldRetry) {
+          const delay = retryAfter ?? computeBackoff(attempt + 1, retryConfig.baseDelayMs, retryConfig.maxDelayMs, retryConfig.jitterMs);
+          await sleep(delay);
+          continue;
+        }
+        if (options.hooks?.onError) {
+          await options.hooks.onError({
+            method,
+            url,
+            status: response.status,
+            requestId: responseRequestId,
+            durationMs,
+            error,
+          });
+        }
+        throw error;
+      }
+      if (options.hooks?.onResponse) {
+        await options.hooks.onResponse({
+          method,
+          url,
+          status: response.status,
+          requestId: responseRequestId,
+          durationMs,
+        });
+      }
+      return { body: responseBody, requestId: responseRequestId, headers: response.headers };
+    } catch (error) {
+      const durationMs = now() - start;
+      const apiError = error instanceof ApiError ? error : new ApiError("Network error", undefined, undefined, requestId);
+      lastError = apiError;
+      if (
+        retryConfig.enabled &&
+        options.canRetry &&
+        attempt < retryConfig.maxRetries
+      ) {
+        const delay = computeBackoff(attempt + 1, retryConfig.baseDelayMs, retryConfig.maxDelayMs, retryConfig.jitterMs);
+        await sleep(delay);
+        continue;
+      }
+      if (options.hooks?.onError) {
+        await options.hooks.onError({
+          method,
+          url,
+          requestId,
+          durationMs,
+          error: apiError,
+        });
+      }
+      throw apiError;
+    }
+  }
+
+  if (lastError) {
+    throw lastError;
+  }
+  throw new ApiError("Request failed", undefined, undefined, requestId);
+};

package/src/index.ts

@@ -0,0 +1,32 @@
+export { ApiClient } from "./client.js";
+export type {
+  Anchor,
+  ApiErrorResponse,
+  ApiResponse,
+  AuthResult,
+  AuthSession,
+  AuditLog,
+  AuditPack,
+  AuditPackManifest,
+  Batch,
+  CertificationRecord,
+  Device,
+  DocumentAnchor,
+  EventDepartment,
+  HealthResponse,
+  Hologram,
+  HologramVerification,
+  Invite,
+  Member,
+  Org,
+  OrgInviteResult,
+  OrgUserLookup,
+  Permission,
+  PublicAttribute,
+  RelayerJobSummary,
+  SignatureRecord,
+  TraceEvent,
+} from "./types.js";
+export { ApiError } from "./http.js";
+export type { AuthOptions, ClientHooks, RetryOptions } from "./http.js";
+export { saveToFile } from "./utils.js";

package/src/types.ts

@@ -0,0 +1,228 @@
+export type ApiStatus = "ok" | "error" | "not_found";
+
+export type ApiResponse<T> = {
+  status: ApiStatus;
+  data?: T;
+  relayerJob?: RelayerJobSummary | null;
+  requestId?: string;
+};
+
+export type ApiErrorResponse = {
+  status: "error";
+  message: string;
+};
+
+export type RelayerJobSummary = {
+  id: number;
+  status: string;
+  txHash: string | null;
+  jobType: string;
+  batchId: string | null;
+  requestId: string | null;
+};
+
+export type Org = {
+  orgId: string;
+  name?: string | null;
+  adminId: string;
+  active?: boolean;
+  createdAt?: string;
+};
+
+export type Batch = {
+  batchId: string;
+  orgId: string;
+  productId: string;
+  facilityId?: string | null;
+  createdAt: string;
+  active: boolean;
+};
+
+export type PublicAttribute = {
+  id: number;
+  batchId: string;
+  key: string;
+  value: string;
+  recordedAt: string;
+};
+
+export type TraceEvent = {
+  id: number;
+  batchId: string;
+  eventType: string;
+  metadataHash: string;
+  actorRole: string;
+  deviceId?: string | null;
+  recordedAt: string;
+};
+
+export type DocumentAnchor = {
+  id: number;
+  batchId: string;
+  docHash: string;
+  docType: string;
+  uri: string;
+  recordedAt: string;
+};
+
+export type SignatureRecord = {
+  id: number;
+  batchId: string;
+  signatureHash: string;
+  signerRole: string;
+  signerIdHash: string;
+  recordedAt: string;
+};
+
+export type CertificationRecord = {
+  id: number;
+  batchId: string;
+  status: "pending" | "approved" | "rejected";
+  decisionHash: string;
+  reviewerRole: string;
+  reviewerIdHash: string;
+  recordedAt: string;
+};
+
+export type Device = {
+  deviceId: string;
+  orgId: string;
+  deviceType: string;
+  label: string;
+  active: boolean;
+  registeredAt: string;
+  updatedAt: string;
+};
+
+export type Anchor = {
+  id: number;
+  orgId: string;
+  merkleRoot: string;
+  metadataHash: string;
+  periodStart: number;
+  periodEnd: number;
+  anchorChainId: number;
+  anchorTxHash: string;
+  recordedAt: string;
+};
+
+export type AuditPack = {
+  id: number;
+  batchId: string;
+  pdfHash: string;
+  jsonHash?: string | null;
+  packVersion: string;
+  pdfUri: string;
+  jsonUri?: string | null;
+  recordedAt: string;
+};
+
+export type Hologram = {
+  hologramId: string;
+  batchId: string;
+  orgId: string;
+  metadataHash: string;
+  uri: string;
+  publicCode?: string | null;
+  active: boolean;
+  issuedAt: string;
+  revokedAt?: string | null;
+};
+
+export type AuditPackManifest = {
+  batchId: string;
+  orgId: string;
+  auditPack: AuditPack;
+  publicAttributes: PublicAttribute[];
+};
+
+export type HologramVerification = {
+  hologramId: string;
+  publicCode: string;
+  active: boolean;
+  issuedAt: string;
+  revokedAt?: string | null;
+  metadataHash: string;
+  uri: string;
+  batch: Batch;
+  publicAttributes: PublicAttribute[];
+  auditPack?: AuditPack | null;
+};
+
+export type AuditLog = {
+  id: number;
+  orgId: string;
+  actorId?: string | null;
+  action: string;
+  targetType: string;
+  targetId?: string | null;
+  metadata?: string | null;
+  createdAt: string;
+};
+
+export type Member = {
+  orgId: string;
+  userId: string;
+  role: string;
+  department: string;
+  active: boolean;
+  createdAt: string;
+  updatedAt: string;
+  name?: string | null;
+  email?: string | null;
+  emailVerified?: boolean | null;
+};
+
+export type Invite = {
+  token: string;
+  orgId: string;
+  email: string;
+  role: string;
+  department: string;
+  status: string;
+  invitedBy: string;
+  createdAt: string;
+  expiresAt: string;
+  acceptedAt?: string | null;
+};
+
+export type Permission = {
+  orgId: string;
+  action: string;
+  role: string;
+  createdAt?: string;
+};
+
+export type OrgInviteResult =
+  | { mode: "member_added"; member: Member }
+  | { mode: "invite_pending"; invite: Invite }
+  | { mode: "invite_sent"; invite: Invite };
+
+export type OrgUserLookup = {
+  id: string;
+  email: string;
+  name?: string | null;
+  emailVerified?: boolean | null;
+} | null;
+
+export type EventDepartment = {
+  orgId: string;
+  eventType: string;
+  department: string;
+};
+
+export type AuthSession = {
+  user: {
+    id: string;
+    email: string;
+    name?: string | null;
+  };
+};
+
+export type AuthResult<T = unknown> = {
+  data: T;
+  token?: string | null;
+  requestId: string;
+};
+
+export type HealthResponse = { status: "ok" };

package/src/utils.ts

@@ -0,0 +1,6 @@
+import { writeFile } from "node:fs/promises";
+
+export const saveToFile = async (path: string, data: ArrayBuffer | Uint8Array) => {
+  const buffer = data instanceof Uint8Array ? data : Buffer.from(data);
+  await writeFile(path, buffer);
+};