@avenlabs/halal-trace-sdk 0.1.1

package/README.md

@@ -0,0 +1,118 @@
+# SDK Package
+
+TypeScript SDK for Halal Trace API.
+
+## Install
+
+```
+pnpm add @halal-trace/sdk
+```
+
+## Usage
+
+```ts
+import { ApiClient } from "@halal-trace/sdk";
+
+const client = new ApiClient({
+  baseUrl: "http://localhost:4000",
+  auth: { token: "<bearer>" },
+  allowInsecure: true,
+  retry: { maxRetries: 2 },
+});
+
+const health = await client.health.get();
+```
+
+Response includes `requestId`:
+
+```ts
+const org = await client.orgs.create({ orgId: "ORG-1" }, { idempotencyKey: "org-ORG-1" });
+console.log(org.requestId);
+```
+
+## Auth strategies
+
+- Static token:
+
+```ts
+auth: { token: "<token>" }
+```
+
+- Async provider:
+
+```ts
+auth: { getToken: async () => "<token>" }
+```
+
+## Auth endpoints
+
+```ts
+const signup = await client.auth.signUpEmail({
+  name: "Admin",
+  email: "admin@company.com",
+  password: "StrongPass123!",
+});
+
+const login = await client.auth.signInEmail({
+  email: "admin@company.com",
+  password: "StrongPass123!",
+});
+
+const token = login.token;
+```
+
+## Org management
+
+```ts
+await client.orgs.addMember("ORG-001", { userId: "USER-1", role: "qa" });
+await client.orgs.addPermission("ORG-001", { action: "batch:create", role: "qa" });
+const lookup = await client.orgs.lookupUserByEmail("ORG-001", "qa@company.com");
+```
+
+## Idempotency
+
+For create/mutate methods, pass `idempotencyKey` to enable safe retries.
+
+```ts
+await client.batches.create(
+  { batchId: "B-01", orgId: "ORG-01", productId: "PROD-01" },
+  { idempotencyKey: "batch-B-01" },
+);
+```
+
+## Observability hooks
+
+```ts
+const client = new ApiClient({
+  baseUrl: "http://localhost:4000",
+  allowInsecure: true,
+  hooks: {
+    onRequest: ({ method, url, requestId }) => console.log("REQ", requestId, method, url),
+    onResponse: ({ status, requestId, durationMs }) => console.log("RES", requestId, status, durationMs),
+    onError: ({ error, requestId }) => console.error("ERR", requestId, error.message),
+  },
+});
+```
+
+## List all relayer jobs
+
+```ts
+for await (const job of client.relayerJobs.listAll("ORG-001")) {
+  console.log(job.status, job.txHash);
+}
+```
+
+## System endpoints
+
+```ts
+const docsHtml = await client.system.docs();
+const openApi = await client.system.openApi();
+const metrics = await client.system.metrics();
+const inviteHtml = await client.system.inviteLanding("ORG-001", "token");
+```
+
+## Commands
+
+```
+pnpm build
+```

package/dist/client.d.ts

@@ -0,0 +1,442 @@
+import type { Anchor, 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, 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>;
+};
+export declare 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);
+    request<T>(method: string, path: string, options?: RequestConfig): Promise<{
+        body: {
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: T | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        };
+        requestId: string;
+    }>;
+    health: {
+        get: () => Promise<HealthResponse>;
+        live: () => Promise<HealthResponse>;
+        ready: () => Promise<HealthResponse>;
+    };
+    system: {
+        docs: () => Promise<string>;
+        openApi: () => Promise<unknown>;
+        metrics: () => Promise<string>;
+        inviteLanding: (orgId: string, token: string) => Promise<string>;
+    };
+    auth: {
+        signUpEmail: (payload: {
+            name: string;
+            email: string;
+            password: string;
+            callbackURL?: string;
+        }, options?: RequestConfig) => Promise<AuthResult>;
+        signInEmail: (payload: {
+            email: string;
+            password: string;
+        }, options?: RequestConfig) => Promise<AuthResult>;
+        verifyEmail: (token: string, callbackURL?: string) => Promise<AuthResult>;
+        requestPasswordReset: (payload: {
+            email: string;
+        }) => Promise<AuthResult>;
+        resetPassword: (payload: {
+            token: string;
+            newPassword: string;
+        }) => Promise<AuthResult>;
+    };
+    orgs: {
+        create: (payload: {
+            orgId: string;
+            name?: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Org | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        addMember: (orgId: string, payload: {
+            userId: string;
+            role: string;
+            department?: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Member | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        updateMember: (orgId: string, userId: string, payload: {
+            role?: string;
+            department?: string;
+        }) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Member | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        removeMember: (orgId: string, userId: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Member | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listMembers: (orgId: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Member[] | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listMembersAll: (orgId: string) => AsyncGenerator<Member, void, unknown>;
+        listAuditLogs: (orgId: string, query?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: AuditLog[] | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listAuditLogsAll: (orgId: string, query?: {
+            limit?: number;
+        }) => AsyncGenerator<AuditLog, void, unknown>;
+        listRelayerJobs: (orgId: string, query?: {
+            status?: string;
+            jobType?: string;
+            batchId?: string;
+            requestId?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: RelayerJobSummary[] | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        getRelayerJob: (orgId: string, jobId: number) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: RelayerJobSummary | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listDeadRelayerJobs: (orgId: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: RelayerJobSummary[] | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        retryRelayerJob: (orgId: string, jobId: number) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: RelayerJobSummary | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        backfillOrg: (orgId: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: RelayerJobSummary | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listInvites: (orgId: string, query?: {
+            status?: string;
+        }) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Invite[] | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listInvitesAll: (orgId: string, query?: {
+            status?: string;
+        }) => AsyncGenerator<Invite, void, unknown>;
+        inviteMember: (orgId: string, payload: {
+            email: string;
+            role: string;
+            department?: string;
+            inviteUrl?: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: OrgInviteResult | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        acceptInvite: (orgId: string, token: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: {
+                invite: Invite;
+                member: Member;
+            } | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        lookupUserByEmail: (orgId: string, email: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: OrgUserLookup | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listPermissions: (orgId: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Permission[] | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        addPermission: (orgId: string, payload: {
+            action: string;
+            role: string;
+        }) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Permission | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        removePermission: (orgId: string, payload: {
+            action: string;
+            role: string;
+        }) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: {
+                orgId: string;
+                action: string;
+                role: string;
+            } | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        setEventDepartment: (orgId: string, payload: {
+            eventType: string;
+            department: string;
+        }) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: EventDepartment | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+    };
+    relayerJobs: {
+        listAll: (orgId: string, query?: {
+            status?: string;
+            jobType?: string;
+            batchId?: string;
+            limit?: number;
+        }) => AsyncGenerator<RelayerJobSummary, void, unknown>;
+        get: (orgId: string, jobId: number) => Promise<RelayerJobSummary | undefined>;
+        waitFor: (orgId: string, jobId: number, options?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+        }) => Promise<RelayerJobSummary>;
+        waitForRequest: (orgId: string, requestId: string, options?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+        }) => Promise<RelayerJobSummary>;
+    };
+    batches: {
+        create: (payload: {
+            batchId: string;
+            orgId: string;
+            productId: string;
+            facilityId?: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Batch | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        addPublicAttribute: (batchId: string, payload: {
+            key: string;
+            value: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: PublicAttribute | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        addEvent: (batchId: string, payload: {
+            eventType: string;
+            metadataHash: string;
+            actorRole: string;
+            deviceId?: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: TraceEvent | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        addDocument: (batchId: string, payload: {
+            docHash: string;
+            docType: string;
+            uri: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: DocumentAnchor | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        addSignature: (batchId: string, payload: {
+            signatureHash: string;
+            signerRole: string;
+            signerIdHash: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: SignatureRecord | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        addCertification: (batchId: string, payload: {
+            status: "pending" | "approved" | "rejected";
+            decisionHash: string;
+            reviewerRole: string;
+            reviewerIdHash: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: CertificationRecord | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        getAuditPackManifest: (batchId: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: AuditPackManifest | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listRelayerJobs: (batchId: string, query?: {
+            status?: string;
+            jobType?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: RelayerJobSummary[] | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        listRelayerJobsAll: (batchId: string, query?: {
+            status?: string;
+            jobType?: string;
+            limit?: number;
+        }) => AsyncGenerator<RelayerJobSummary, void, unknown>;
+        backfillBatch: (batchId: string) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: RelayerJobSummary | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+    };
+    devices: {
+        register: (payload: {
+            deviceId: string;
+            orgId: string;
+            deviceType: string;
+            label: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Device | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        update: (deviceId: string, payload: {
+            deviceType: string;
+            label: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Device | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        setStatus: (deviceId: string, payload: {
+            active: boolean;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Device | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+    };
+    anchors: {
+        create: (payload: {
+            orgId: string;
+            merkleRoot: string;
+            metadataHash: string;
+            periodStart: number;
+            periodEnd: number;
+            anchorChainId: number;
+            anchorTxHash: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Anchor | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+    };
+    auditPacks: {
+        create: (payload: {
+            batchId: string;
+            pdfHash: string;
+            jsonHash?: string;
+            packVersion: string;
+            pdfUri: string;
+            jsonUri?: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: AuditPack | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        downloadPdf: (pdfUri: string) => Promise<ArrayBuffer>;
+        downloadJson: (jsonUri: string) => Promise<string>;
+    };
+    holograms: {
+        issue: (payload: {
+            batchId: string;
+            hologramId: string;
+            metadataHash: string;
+            uri: string;
+            publicCode?: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: Hologram | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        revoke: (payload: {
+            hologramId: string;
+            reasonHash: string;
+        }, options?: RequestConfig) => Promise<{
+            requestId: string;
+            status: import("./types.js").ApiStatus;
+            data?: {
+                hologramId: string;
+                active: boolean;
+            } | undefined;
+            relayerJob?: RelayerJobSummary | null;
+        }>;
+        verify: (publicCode: string) => Promise<HologramVerification | null>;
+    };
+}
+export type { BaseClientOptions, RequestConfig };