@avenlabs/halal-trace-sdk 0.1.1

package/src/client.ts

@@ -0,0 +1,491 @@
+import type {
+  Anchor,
+  ApiResponse,
+  AuditLog,
+  AuditPack,
+  AuditPackManifest,
+  AuthResult,
+  Batch,
+  CertificationRecord,
+  Device,
+  DocumentAnchor,
+  EventDepartment,
+  HealthResponse,
+  Hologram,
+  HologramVerification,
+  Invite,
+  Member,
+  Org,
+  OrgInviteResult,
+  OrgUserLookup,
+  Permission,
+  PublicAttribute,
+  RelayerJobSummary,
+  SignatureRecord,
+  TraceEvent,
+} from "./types.js";
+import { ApiError, request, requestRaw, type AuthOptions, type ClientHooks, type RequestOptions, type RetryOptions } from "./http.js";
+
+type BaseClientOptions = {
+  baseUrl: string;
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+  auth?: AuthOptions;
+  retry?: RetryOptions;
+  allowInsecure?: boolean;
+  onAuthError?: (error: ApiError) => void | Promise<void>;
+  hooks?: ClientHooks;
+  userAgent?: string;
+  clientVersion?: string;
+  signingHook?: RequestOptions["signingHook"];
+};
+
+type RequestConfig = Omit<RequestOptions, "sdkHeaders" | "hooks" | "signingHook"> & {
+  auth?: AuthOptions;
+  timeoutMs?: number;
+  retry?: RetryOptions;
+  allowInsecure?: boolean;
+  onAuthError?: (error: ApiError) => void | Promise<void>;
+};
+
+const sdkVersion = "0.1.0";
+
+const withDefaults = (client: ApiClient, options: RequestConfig = {}): RequestOptions => {
+  return {
+    ...options,
+    timeoutMs: options.timeoutMs ?? client.timeoutMs,
+    allowInsecure: options.allowInsecure ?? client.allowInsecure,
+    retry: options.retry ?? client.retry,
+    auth: options.auth ?? client.authOptions,
+    onAuthError: options.onAuthError ?? client.onAuthError,
+    sdkHeaders: {
+      "x-sdk-name": "@halal-trace/sdk",
+      "x-sdk-version": sdkVersion,
+      ...(client.clientVersion ? { "x-client-version": client.clientVersion } : {}),
+      ...(client.userAgent ? { "User-Agent": client.userAgent } : {}),
+    },
+    hooks: client.hooks,
+    signingHook: client.signingHook,
+  };
+};
+
+const unwrap = <T>(response: ApiResponse<T>): T => response.data ?? (undefined as T);
+
+type PaginatedQuery = Record<string, string | number | boolean | undefined> & { limit?: number };
+
+async function* listPaginated<T>(client: ApiClient, path: string, query?: PaginatedQuery) {
+  const limit = query?.limit ?? 50;
+  let offset = 0;
+  while (true) {
+    const response = await client.request<T[]>("GET", path, { query: { ...query, limit, offset }, canRetry: true });
+    const items = response.body.data ?? [];
+    for (const item of items) {
+      yield item;
+    }
+    if (items.length < limit) {
+      break;
+    }
+    offset += limit;
+  }
+}
+
+async function* listSingle<T>(client: ApiClient, path: string, query?: Record<string, string | number | boolean | undefined>) {
+  const response = await client.request<T[]>("GET", path, { query, canRetry: true });
+  const items = response.body.data ?? [];
+  for (const item of items) {
+    yield item;
+  }
+}
+
+async function* listRelayerJobsAll(
+  client: ApiClient,
+  orgId: string,
+  query?: { status?: string; jobType?: string; batchId?: string; requestId?: string; limit?: number },
+) {
+  const limit = query?.limit ?? 100;
+  let offset = 0;
+  while (true) {
+    const response = await client.orgs.listRelayerJobs(orgId, { ...query, limit, offset });
+    const items = response.data ?? [];
+    for (const item of items) {
+      yield item;
+    }
+    if (items.length < limit) {
+      break;
+    }
+    offset += limit;
+  }
+}
+
+export class ApiClient {
+  baseUrl: string;
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+  authOptions?: AuthOptions;
+  retry?: RetryOptions;
+  allowInsecure?: boolean;
+  onAuthError?: (error: ApiError) => void | Promise<void>;
+  hooks?: ClientHooks;
+  userAgent?: string;
+  clientVersion?: string;
+  signingHook?: RequestOptions["signingHook"];
+
+  constructor(options: BaseClientOptions) {
+    if (!options.baseUrl) {
+      throw new Error("baseUrl is required");
+    }
+    this.baseUrl = options.baseUrl;
+    this.timeoutMs = options.timeoutMs;
+    this.headers = options.headers;
+    this.authOptions = options.auth;
+    this.retry = options.retry;
+    this.allowInsecure = options.allowInsecure;
+    this.onAuthError = options.onAuthError;
+    this.hooks = options.hooks;
+    this.userAgent = options.userAgent;
+    this.clientVersion = options.clientVersion;
+    this.signingHook = options.signingHook;
+  }
+
+  async request<T>(method: string, path: string, options: RequestConfig = {}) {
+    const response = await request<ApiResponse<T>>(this.baseUrl, path, method, {
+      ...withDefaults(this, options),
+      headers: {
+        ...(this.headers ?? {}),
+        ...(options.headers ?? {}),
+      },
+    });
+    return {
+      body: {
+        ...response.body,
+        requestId: response.requestId,
+      },
+      requestId: response.requestId,
+    };
+  }
+
+  health = {
+    get: async () => unwrap((await this.request<HealthResponse>("GET", "/health", { canRetry: true })).body),
+    live: async () => unwrap((await this.request<HealthResponse>("GET", "/live", { canRetry: true })).body),
+    ready: async () => unwrap((await this.request<HealthResponse>("GET", "/ready", { canRetry: true })).body),
+  };
+
+  system = {
+    docs: async () => {
+      const response = await requestRaw(this.baseUrl, "/docs", "GET", { ...withDefaults(this, {}), canRetry: true });
+      return response.body as string;
+    },
+    openApi: async () => {
+      const response = await requestRaw(this.baseUrl, "/docs/openapi.json", "GET", { ...withDefaults(this, {}), canRetry: true });
+      return response.body as unknown;
+    },
+    metrics: async () => {
+      const response = await requestRaw(this.baseUrl, "/metrics", "GET", { ...withDefaults(this, {}), canRetry: true });
+      return response.body as string;
+    },
+    inviteLanding: async (orgId: string, token: string) => {
+      const response = await requestRaw(this.baseUrl, "/invites/accept", "GET", {
+        ...withDefaults(this, {}),
+        query: { orgId, token },
+        canRetry: true,
+      });
+      return response.body as string;
+    },
+  };
+
+  auth = {
+    signUpEmail: async (payload: { name: string; email: string; password: string; callbackURL?: string }, options?: RequestConfig): Promise<AuthResult> => {
+      const response = await requestRaw(this.baseUrl, "/api/auth/sign-up/email", "POST", {
+        ...withDefaults(this, options ?? {}),
+        body: payload,
+        canRetry: false,
+      });
+      return { data: response.body, token: response.headers.get("set-auth-token"), requestId: response.requestId };
+    },
+    signInEmail: async (payload: { email: string; password: string }, options?: RequestConfig): Promise<AuthResult> => {
+      const response = await requestRaw(this.baseUrl, "/api/auth/sign-in/email", "POST", {
+        ...withDefaults(this, options ?? {}),
+        body: payload,
+        canRetry: false,
+      });
+      return { data: response.body, token: response.headers.get("set-auth-token"), requestId: response.requestId };
+    },
+    verifyEmail: async (token: string, callbackURL?: string): Promise<AuthResult> => {
+      const response = await requestRaw(this.baseUrl, "/api/auth/verify-email", "GET", {
+        ...withDefaults(this, {}),
+        query: { token, callbackURL },
+        canRetry: true,
+      });
+      return { data: response.body, token: response.headers.get("set-auth-token"), requestId: response.requestId };
+    },
+    requestPasswordReset: async (payload: { email: string }): Promise<AuthResult> => {
+      const response = await requestRaw(this.baseUrl, "/api/auth/request-password-reset", "POST", {
+        ...withDefaults(this, {}),
+        body: payload,
+        canRetry: false,
+      });
+      return { data: response.body, token: response.headers.get("set-auth-token"), requestId: response.requestId };
+    },
+    resetPassword: async (payload: { token: string; newPassword: string }): Promise<AuthResult> => {
+      const response = await requestRaw(this.baseUrl, "/api/auth/reset-password", "POST", {
+        ...withDefaults(this, {}),
+        body: payload,
+        canRetry: false,
+      });
+      return { data: response.body, token: response.headers.get("set-auth-token"), requestId: response.requestId };
+    },
+  };
+
+  orgs = {
+    create: async (payload: { orgId: string; name?: string }, options?: RequestConfig) =>
+      await this.request<Org>("POST", "/orgs", {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    addMember: async (orgId: string, payload: { userId: string; role: string; department?: string }, options?: RequestConfig) =>
+      await this.request<Member>("POST", `/orgs/${orgId}/members`, {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    updateMember: async (orgId: string, userId: string, payload: { role?: string; department?: string }) =>
+      await this.request<Member>("PATCH", `/orgs/${orgId}/members/${userId}`, { body: payload, canRetry: false }).then((res) => res.body),
+    removeMember: async (orgId: string, userId: string) =>
+      await this.request<Member>("DELETE", `/orgs/${orgId}/members/${userId}`, { canRetry: false }).then((res) => res.body),
+    listMembers: async (orgId: string) =>
+      await this.request<Member[]>("GET", `/orgs/${orgId}/members`, { canRetry: true }).then((res) => res.body),
+    listMembersAll: (orgId: string) => listSingle<Member>(this, `/orgs/${orgId}/members`),
+    listAuditLogs: async (orgId: string, query?: { limit?: number; offset?: number }) =>
+      await this.request<AuditLog[]>("GET", `/orgs/${orgId}/audit-logs`, { query, canRetry: true }).then((res) => res.body),
+    listAuditLogsAll: (orgId: string, query?: { limit?: number }) => listPaginated<AuditLog>(this, `/orgs/${orgId}/audit-logs`, query),
+    listRelayerJobs: async (
+      orgId: string,
+      query?: { status?: string; jobType?: string; batchId?: string; requestId?: string; limit?: number; offset?: number },
+    ) =>
+      await this.request<RelayerJobSummary[]>("GET", `/orgs/${orgId}/relayer-jobs`, { query, canRetry: true }).then((res) => res.body),
+    getRelayerJob: async (orgId: string, jobId: number) =>
+      await this.request<RelayerJobSummary>("GET", `/orgs/${orgId}/relayer-jobs/${jobId}`, { canRetry: true }).then((res) => res.body),
+    listDeadRelayerJobs: async (orgId: string) =>
+      await this.request<RelayerJobSummary[]>("GET", `/orgs/${orgId}/relayer-jobs/dead`, { canRetry: true }).then((res) => res.body),
+    retryRelayerJob: async (orgId: string, jobId: number) =>
+      await this.request<RelayerJobSummary>("POST", `/orgs/${orgId}/relayer-jobs/${jobId}/retry`, { canRetry: false }).then((res) => res.body),
+    backfillOrg: async (orgId: string) =>
+      await this.request<RelayerJobSummary>("POST", `/orgs/${orgId}/relayer-jobs/backfill`, { canRetry: false }).then((res) => res.body),
+    listInvites: async (orgId: string, query?: { status?: string }) =>
+      await this.request<Invite[]>("GET", `/orgs/${orgId}/invites`, { query, canRetry: true }).then((res) => res.body),
+    listInvitesAll: (orgId: string, query?: { status?: string }) => listSingle<Invite>(this, `/orgs/${orgId}/invites`, query),
+    inviteMember: async (orgId: string, payload: { email: string; role: string; department?: string; inviteUrl?: string }, options?: RequestConfig) =>
+      await this.request<OrgInviteResult>("POST", `/orgs/${orgId}/invites`, {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    acceptInvite: async (orgId: string, token: string) =>
+      await this.request<{ invite: Invite; member: Member }>("POST", `/orgs/${orgId}/invites/${token}/accept`, { canRetry: false }).then((res) => res.body),
+    lookupUserByEmail: async (orgId: string, email: string) =>
+      await this.request<OrgUserLookup>("GET", `/orgs/${orgId}/users`, { query: { email }, canRetry: true }).then((res) => res.body),
+    listPermissions: async (orgId: string) =>
+      await this.request<Permission[]>("GET", `/orgs/${orgId}/permissions`, { canRetry: true }).then((res) => res.body),
+    addPermission: async (orgId: string, payload: { action: string; role: string }) =>
+      await this.request<Permission>("POST", `/orgs/${orgId}/permissions`, { body: payload, canRetry: false }).then((res) => res.body),
+    removePermission: async (orgId: string, payload: { action: string; role: string }) =>
+      await this.request<{ orgId: string; action: string; role: string }>("DELETE", `/orgs/${orgId}/permissions`, {
+        body: payload,
+        canRetry: false,
+      }).then((res) => res.body),
+    setEventDepartment: async (orgId: string, payload: { eventType: string; department: string }) =>
+      await this.request<EventDepartment>("POST", `/orgs/${orgId}/event-departments`, { body: payload, canRetry: false }).then((res) => res.body),
+  };
+
+  relayerJobs = {
+    listAll: (orgId: string, query?: { status?: string; jobType?: string; batchId?: string; limit?: number }) =>
+      listRelayerJobsAll(this, orgId, query),
+    get: async (orgId: string, jobId: number) => this.orgs.getRelayerJob(orgId, jobId).then((res) => res.data),
+    waitFor: async (orgId: string, jobId: number, options?: { timeoutMs?: number; intervalMs?: number }) => {
+      const timeoutMs = options?.timeoutMs ?? 60000;
+      const intervalMs = options?.intervalMs ?? 2000;
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        const job = await this.relayerJobs.get(orgId, jobId);
+        if (job && (job.status === "completed" || job.status === "dead" || job.status === "failed")) {
+          return job;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      }
+      throw new ApiError("Timeout waiting for relayer job");
+    },
+    waitForRequest: async (orgId: string, requestId: string, options?: { timeoutMs?: number; intervalMs?: number }) => {
+      const timeoutMs = options?.timeoutMs ?? 60000;
+      const intervalMs = options?.intervalMs ?? 2000;
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        const jobs = await this.orgs.listRelayerJobs(orgId, { requestId, limit: 10, offset: 0 });
+        const job = jobs.data?.[0];
+        if (job) {
+          return job;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      }
+      throw new ApiError("Timeout waiting for request relayer job");
+    },
+  };
+
+  batches = {
+    create: async (payload: { batchId: string; orgId: string; productId: string; facilityId?: string }, options?: RequestConfig) =>
+      await this.request<Batch>("POST", "/batches", {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    addPublicAttribute: async (batchId: string, payload: { key: string; value: string }, options?: RequestConfig) =>
+      await this.request<PublicAttribute>("POST", `/batches/${batchId}/public-attributes`, {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    addEvent: async (
+      batchId: string,
+      payload: { eventType: string; metadataHash: string; actorRole: string; deviceId?: string },
+      options?: RequestConfig,
+    ) =>
+      await this.request<TraceEvent>("POST", `/batches/${batchId}/events`, {
+        ...options,
+        body: payload,
+        canRetry: Boolean(options?.idempotencyKey),
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    addDocument: async (batchId: string, payload: { docHash: string; docType: string; uri: string }, options?: RequestConfig) =>
+      await this.request<DocumentAnchor>("POST", `/batches/${batchId}/documents`, {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    addSignature: async (batchId: string, payload: { signatureHash: string; signerRole: string; signerIdHash: string }, options?: RequestConfig) =>
+      await this.request<SignatureRecord>("POST", `/batches/${batchId}/signatures`, {
+        ...options,
+        body: payload,
+        canRetry: Boolean(options?.idempotencyKey),
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    addCertification: async (
+      batchId: string,
+      payload: { status: "pending" | "approved" | "rejected"; decisionHash: string; reviewerRole: string; reviewerIdHash: string },
+      options?: RequestConfig,
+    ) =>
+      await this.request<CertificationRecord>("POST", `/batches/${batchId}/certifications`, {
+        ...options,
+        body: payload,
+        canRetry: Boolean(options?.idempotencyKey),
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    getAuditPackManifest: async (batchId: string) =>
+      await this.request<AuditPackManifest>("GET", `/batches/${batchId}/audit-pack/manifest`, { canRetry: true }).then((res) => res.body),
+    listRelayerJobs: async (batchId: string, query?: { status?: string; jobType?: string; limit?: number; offset?: number }) =>
+      await this.request<RelayerJobSummary[]>("GET", `/batches/${batchId}/relayer-jobs`, { query, canRetry: true }).then((res) => res.body),
+    listRelayerJobsAll: (batchId: string, query?: { status?: string; jobType?: string; limit?: number }) =>
+      listPaginated<RelayerJobSummary>(this, `/batches/${batchId}/relayer-jobs`, query),
+    backfillBatch: async (batchId: string) =>
+      await this.request<RelayerJobSummary>("POST", `/batches/${batchId}/relayer-jobs/backfill`, { canRetry: false }).then((res) => res.body),
+  };
+
+  devices = {
+    register: async (payload: { deviceId: string; orgId: string; deviceType: string; label: string }, options?: RequestConfig) =>
+      await this.request<Device>("POST", "/devices", {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    update: async (deviceId: string, payload: { deviceType: string; label: string }, options?: RequestConfig) =>
+      await this.request<Device>("PATCH", `/devices/${deviceId}`, {
+        ...options,
+        body: payload,
+        canRetry: Boolean(options?.idempotencyKey),
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    setStatus: async (deviceId: string, payload: { active: boolean }, options?: RequestConfig) =>
+      await this.request<Device>("PATCH", `/devices/${deviceId}/status`, {
+        ...options,
+        body: payload,
+        canRetry: Boolean(options?.idempotencyKey),
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+  };
+
+  anchors = {
+    create: async (
+      payload: { orgId: string; merkleRoot: string; metadataHash: string; periodStart: number; periodEnd: number; anchorChainId: number; anchorTxHash: string },
+      options?: RequestConfig,
+    ) =>
+      await this.request<Anchor>("POST", "/anchors", {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+  };
+
+  auditPacks = {
+    create: async (
+      payload: { batchId: string; pdfHash: string; jsonHash?: string; packVersion: string; pdfUri: string; jsonUri?: string },
+      options?: RequestConfig,
+    ) =>
+      await this.request<AuditPack>("POST", "/audit-packs", {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    downloadPdf: async (pdfUri: string) => {
+      const response = await fetch(pdfUri);
+      if (!response.ok) {
+        throw new ApiError(`Failed to download PDF: ${response.status}`, response.status);
+      }
+      return response.arrayBuffer();
+    },
+    downloadJson: async (jsonUri: string) => {
+      const response = await fetch(jsonUri);
+      if (!response.ok) {
+        throw new ApiError(`Failed to download JSON: ${response.status}`, response.status);
+      }
+      return response.text();
+    },
+  };
+
+  holograms = {
+    issue: async (
+      payload: { batchId: string; hologramId: string; metadataHash: string; uri: string; publicCode?: string },
+      options?: RequestConfig,
+    ) =>
+      await this.request<Hologram>("POST", "/holograms", {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    revoke: async (payload: { hologramId: string; reasonHash: string }, options?: RequestConfig) =>
+      await this.request<{ hologramId: string; active: boolean }>("POST", "/holograms/revoke", {
+        ...options,
+        body: payload,
+        canRetry: true,
+        idempotencyKey: options?.idempotencyKey,
+      }).then((res) => res.body),
+    verify: async (publicCode: string) => {
+      const response = await this.request<HologramVerification>("GET", `/verify/holograms/${publicCode}`, { canRetry: true });
+      if (response.body.status !== "ok") {
+        return null;
+      }
+      return response.body.data ?? null;
+    },
+  };
+
+}
+
+export type { BaseClientOptions, RequestConfig };

package/src/http.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { request } from "./http.js";
+
+describe("request", () => {
+  it("rejects insecure baseUrl without allowInsecure", async () => {
+    await expect(
+      request("http://localhost:4000", "/health", "GET", { canRetry: true }),
+    ).rejects.toThrow("Insecure baseUrl blocked");
+  });
+});