@avenlabs/halal-trace-sdk 0.1.1

package/dist/http.js

@@ -0,0 +1,348 @@
+export class ApiError extends Error {
+    status;
+    body;
+    requestId;
+    constructor(message, status, body, requestId) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.requestId = requestId;
+    }
+}
+const defaultRetry = {
+    enabled: true,
+    maxRetries: 2,
+    baseDelayMs: 250,
+    maxDelayMs: 2000,
+    jitterMs: 200,
+};
+const transientStatuses = new Set([408, 429, 500, 502, 503, 504]);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const buildQuery = (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, baseDelayMs, maxDelayMs, jitterMs) => {
+    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) => {
+    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, allowInsecure) => {
+    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 (baseUrl, path, method, options) => {
+    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 = {
+        "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 = { 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;
+    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;
+            if (responseText) {
+                try {
+                    responseBody = JSON.parse(responseText);
+                }
+                catch {
+                    responseBody = undefined;
+                }
+            }
+            if (!response.ok) {
+                const message = typeof responseBody === "object" && responseBody && "message" in responseBody
+                    ? String(responseBody.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 };
+        }
+        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, path, method, options) => {
+    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 = {
+        "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 = { 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;
+    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 = responseText;
+            if (responseText) {
+                try {
+                    responseBody = JSON.parse(responseText);
+                }
+                catch {
+                    responseBody = responseText;
+                }
+            }
+            if (!response.ok) {
+                const message = typeof responseBody === "object" && responseBody && "message" in responseBody
+                    ? String(responseBody.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/dist/http.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http.test.js

@@ -0,0 +1,7 @@
+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");
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+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/dist/index.js

@@ -0,0 +1,3 @@
+export { ApiClient } from "./client.js";
+export { ApiError } from "./http.js";
+export { saveToFile } from "./utils.js";

package/dist/types.d.ts

@@ -0,0 +1,210 @@
+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/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1 @@
+export declare const saveToFile: (path: string, data: ArrayBuffer | Uint8Array) => Promise<void>;

package/dist/utils.js

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

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@avenlabs/halal-trace-sdk",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "eslint": "^9.6.0",
+    "prettier": "^3.3.2",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.4"
+  }
+}