@ieum/sdk

TypeScript SDK for ieum white-label transaction tracking, identity, assets, receipts, batch, and gas on Avalanche Subnet (Jelly Testnet).

• v1: Transaction API (create, get, list, updateStatus, updateSchedule). No chain execution in SDK; partner app performs on-chain tx then records via SDK.
• v2: + Identity, Asset (Mint/Burn), Receipt (hybrid payment), Batch, Gas Station.
• Auth: API Key (X-Api-Key). Optional X-Org-Code.
• Base URL: e.g. https://api.ieum.it (backend uses global prefix /api).
• Options: Optional retry (5xx/408 backoff), logger / debug, validateInputs (see below).
• Security: Never log or expose apiKey or full request/response bodies (SDK logs only method/path/status when logger/debug is used).

Install

npm i @ieum/sdk
# or
pnpm add @ieum/sdk

Subpath exports (smaller bundles)

The same npm package exposes conditional exports so bundlers can skip unused surfaces:

| Import | When to use | |--------|-------------| | @ieum/sdk | Full IeumClient (partner APIs + v2 experimental namespaces), console helpers, ops, v2 types — default. | | @ieum/sdk/partner | IeumPartnerClient only: transactions, payments, settlements, mintBurn, health, config, ops (no receipts / identity / assets / batch / gas). | | @ieum/sdk/console | JWT console: IeumConsoleClient, ieumSessionFetch, MemoryTokenStore, Console*Api. | | @ieum/sdk/hybrid | v2 experimental API classes (ReceiptsApi, IdentityApi, AssetApi, BatchApi, GasApi) and shared HttpClientOptions — compose manually; paths may not exist on every deployment. | | @ieum/sdk/openapi-types | OpenAPI-generated paths / components types only. |

import { IeumPartnerClient } from "@ieum/sdk/partner";
import { IeumConsoleClient, MemoryTokenStore } from "@ieum/sdk/console";
import { ReceiptsApi } from "@ieum/sdk/hybrid";

const partner = new IeumPartnerClient({ baseUrl, apiKey });
const receipts = new ReceiptsApi({ baseUrl, apiKey });

Quickstart (Node)

import { IeumClient, NetworkType, TxPaymentType, genRequestId } from "@ieum/sdk";

const client = new IeumClient({
  baseUrl: process.env.IEUM_BASE_URL ?? "https://api.ieum.it",
  apiKey: process.env.IEUM_API_KEY!,
  orgCode: process.env.IEUM_ORG_CODE,
});

// Optional: network & contract config (Jelly Testnet defaults if server has no config endpoint)
const network = await client.config.getNetwork();
const contracts = await client.config.getContracts();

// Record an INSTANT transaction (partner already has txHash from chain)
const record = await client.transactions.create(
  {
    fromNetworkType: NetworkType.AVAX,
    toNetworkType: NetworkType.AVAX,
    paymentType: TxPaymentType.INSTANT,
    fromAddress: "0xFROM...",
    toAddress: "0xTO...",
    txHash: "0xONCHAIN_TX_HASH",
    amount: "1000000",
    fee: "0",
    memo: "demo",
  },
  { requestId: genRequestId() } // recommended for idempotency
);

console.log(record.id, record.txStatus);

// Get one
const tx = await client.transactions.get(record.id);

// List (pagination)
const list = await client.transactions.list({ limit: 10, currentPage: 1 });

Error handling

All API calls can throw IeumError. Use statusCode and errorCode for handling (e.g. 409 for duplicate txHash):

import { IeumClient, IeumError, genRequestId } from "@ieum/sdk";

const client = new IeumClient({ baseUrl: "...", apiKey: "..." });

try {
  const record = await client.transactions.create(
    { /* ... */ },
    { requestId: genRequestId() }
  );
  console.log(record.id);
} catch (e) {
  if (e instanceof IeumError) {
    console.error(e.message, e.statusCode, e.errorCode, e.requestId);
    if (e.statusCode === 409) {
      // Duplicate request — safe to retry with same requestId or treat as success
    }
    // 5xx / timeout: consider retry with backoff. Do not retry 4xx (except 409).
  }
  throw e;
}

Conventions

• amount / fee: Integer string in smallest unit (Wei). No floats, no scientific notation.
• Retry: Pass retry: { maxRetries: 3, initialDelayMs: 1000 } to auto-retry on 5xx/408 with exponential backoff.
• Logging: Pass logger: { debug, error } or set debug: true to log request/response metadata (no bodies).
• Validation: Set validateInputs: true to validate transactions.create body (amount, addresses, etc.) before sending.
• Idempotency: For INSTANT, duplicate txHash is rejected. For SCHEDULED, duplicate approve hash is rejected. Use meta.requestId (e.g. genRequestId()) on create so retries are idempotent; the backend may use it to deduplicate. On 409, you can treat as "already recorded" and proceed.
• SCHEDULED: scheduledAt required (ISO string, future). Same network only (fromNetworkType === toNetworkType).
• Default network: Jelly Subnet Testnet (chainId 99062).

Health & Config behavior

• health.ping: On connection failure or server error, returns { ok: false } and does not throw. Use it for "soft" health checks (e.g. readiness probes).
• config.getNetwork / getContracts: If the server does not expose /api/config/network or /api/config/contracts, the SDK returns Jelly Testnet defaults and does not throw. Useful for local/dev when the backend is not fully deployed; in production, ensure the backend exposes config if you need server-defined values.

Roadmap (post–v1)

| Area | Status | |------|--------| | Identity & Access | ✅ v2: User–wallet mapping, KYC status sync (client.identity) | | Asset | ✅ v2: Mint/Burn request API, Collateral status (client.assets) | | Hybrid payment | ✅ v2: Receipt (authorize → commit → status), waitForReceiptStatus (client.receipts) | | Batch | ✅ v2: Batch list & detail (client.batch) | | Gas | ✅ v2: Gas relay / gas station (client.gas) |

See ROADMAP.md for the full v2 development plan. For upgrading from v1, see MIGRATION.md.

Identity API (v2)

User–wallet mapping and KYC status sync. Requires backend endpoints /api/identity/wallet and /api/identity/kyc/sync.

import { IeumClient, KycStatus } from "@ieum/sdk";

const client = new IeumClient({ baseUrl: "...", apiKey: "...", orgCode: "..." });

// Register or update user–wallet mapping
const mapping = await client.identity.registerWallet({
  userId: "user-123",
  address: "0x...",
  networkType: "AVAX",
});

// Get wallet for user (null if not found)
const wallet = await client.identity.getWallet("user-123");

// Sync KYC status (e.g. after partner's KYC flow)
await client.identity.syncKycStatus({
  userId: "user-123",
  status: KycStatus.VERIFIED,
});

Asset API (v2)

Mint (발행) / Burn (소각) 요청 및 담보·발행량 현황. Backend: /api/asset/mint, /api/asset/burn, /api/asset/collateral.

import { IeumClient } from "@ieum/sdk";

const client = new IeumClient({ baseUrl: "...", apiKey: "...", orgCode: "..." });

// Create mint request (승인 후 비동기 실행)
const mint = await client.assets.createMintRequest({ amount: "1000000", memo: "issuance" });
const mintStatus = await client.assets.getMintRequest(mint.id);

// Create burn request
const burn = await client.assets.createBurnRequest({ amount: "500000" });
const burnStatus = await client.assets.getBurnRequest(burn.id);

// Collateral & issued amount (대사)
const collateral = await client.assets.getCollateralStatus();
console.log(collateral.collateralBalance, collateral.issuedAmount);

Receipt / Hybrid payment (v2)

Authorize (즉시 응답) → commit (비동기 체인 실행) → status 조회. Backend: /api/receipt/authorize, /api/receipt/:id/commit, /api/receipt/:id.

import { IeumClient, ReceiptStatus, genRequestId } from "@ieum/sdk";

const client = new IeumClient({ baseUrl: "...", apiKey: "...", orgCode: "..." });

// 1) Authorize — fast response, receipt created (~1s target)
const receipt = await client.receipts.authorize(
  {
    amount: "1000000",
    fromAddress: "0xFROM...",
    toAddress: "0xTO...",
    memo: "payment",
  },
  { requestId: genRequestId() }
);

// 2) Trigger commit (async chain execution)
await client.receipts.commit(receipt.id);

// 3) Poll until COMMITTED or BATCHED
const updated = await client.receipts.waitForReceiptStatus(
  receipt.id,
  (r) => r.status === ReceiptStatus.COMMITTED || r.status === ReceiptStatus.BATCHED,
  { intervalMs: 1500, timeoutMs: 60_000 }
);
console.log(updated.txHash, updated.status);

Batch API (v2)

배치 단위 정산 상태 조회. Backend: GET /api/batch, GET /api/batch/:id.

import { IeumClient } from "@ieum/sdk";

const client = new IeumClient({ baseUrl: "...", apiKey: "...", orgCode: "..." });

// List batches (pagination, optional status filter)
const list = await client.batch.list({ limit: 10, currentPage: 1 });
// Get batch detail
const batch = await client.batch.get(list.items[0].id);
console.log(batch.status, batch.receiptCount, batch.anchoredAt);

Gas Station (v2)

가스비 대납 요청·상태 조회. Backend: POST /api/gas/relay, GET /api/gas/relay/:id.

import { IeumClient } from "@ieum/sdk";

const client = new IeumClient({ baseUrl: "...", apiKey: "...", orgCode: "..." });

// Request gas relay (PCI 수취 → 체인 실행)
const relay = await client.gas.createRelayRequest({
  toAddress: "0x...",
  networkType: "AVAX",
  amount: "1000000000000000", // optional
});

// Get status / txHash
const status = await client.gas.getRelayRequest(relay.id);
console.log(status.txHash, status.status);

Production / 화이트라벨 실제 사용 시

운영 환경에서 파트너가 안정적으로 사용하려면 아래 문서를 참고하세요.

• 화이트라벨 SDK 실제 사용 체크리스트 — 보안(API Key), 재시도, 로깅, 입력 검증, 버전/호환성, 브라우저, CI/CD, 배포 등 권장 사항 요약.

요약: API Key는 환경 변수/시크릿 매니저 사용, 생성/변경 호출 시 requestId로 멱등성 유지, 5xx/타임아웃은 재시도·4xx는 재시도 금지, 에러 시 statusCode/errorCode/requestId 로깅 권장.

Links

• Explorer: https://explorer-test.avax.network/jelly
• Public RPC: https://subnets.avax.network/jelly/testnet/rpc

License

MIT

Verify build & API (local)

After building, run the verification script to ensure all required APIs are present:

cd packages/sdk
npm run build
npm run verify

Or from repo root (build + verify in one step):

npm run verify

Run unit tests:

cd packages/sdk
npm run test

Generate API docs (TypeDoc):

cd packages/sdk
npm run docs
# Output in packages/sdk/docs-api/

Uses typedoc.json with multiple entry points: src/index.ts, src/entries/partner.ts, src/entries/console.ts, src/entries/hybrid.ts (each maps to an npm subpath export). The docs script passes --treatValidationWarningsAsErrors so documentation validation issues fail the build.

The verify script checks: IeumClient, IeumError, enums, default Jelly config, and all client methods (health, config, transactions, identity, assets, receipts, batch, gas), plus built partner / console / hybrid bundles.