SDK Package

TypeScript SDK for Halal Trace API.

Install

pnpm add @avenlabs/halal-trace-sdk

Usage

import { ApiClient } from "@avenlabs/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:

const org = await client.orgs.create({ orgId: "ORG-1" }, { idempotencyKey: "org-ORG-1" });
console.log(org.requestId);

Auth strategies

• Static token:

auth: { token: "<token>" }

• Async provider:

auth: { getToken: async () => "<token>" }

Auth endpoints

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

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.

await client.batches.create(
  { batchId: "B-01", orgId: "ORG-01", productId: "PROD-01" },
  { idempotencyKey: "batch-B-01" },
);

Observability hooks

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),
  },
});

Node-only helpers

import { saveToFile } from "@avenlabs/halal-trace-sdk/node";

List all relayer jobs

for await (const job of client.relayerJobs.listAll("ORG-001")) {
  console.log(job.status, job.txHash);
}

System endpoints

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