@whocomply/ledger 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WhoComply
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @whocomply/ledger
+
+TypeScript SDK for the WhoComply Ledger API.
+
+```bash
+npm install @whocomply/ledger
+```
+
+Zero runtime dependencies, built on global `fetch` (Node 18+ and browsers),
+dual ESM/CJS output with full type declarations. MIT licensed.
+
+```ts
+import { LedgerClient, LedgerApiError } from '@whocomply/ledger';
+
+const ledger = new LedgerClient({
+    baseUrl: 'https://ledger.internal.example.com',
+    tenant: 'demo-fintech',
+    apiKey: process.env.LEDGER_API_KEY,
+});
+
+// Post a balanced double-entry transaction
+const tx = await ledger.transactions.post({
+    description: 'Customer deposit via bank transfer',
+    reference: 'DEP-2026-001',
+    idempotencyKey: 'deposit-evt-8842',   // optional; generated when omitted
+    entries: [
+        { account_code: '1000', amount: '250000.00', side: 'debit', currency: 'NGN' },
+        { account_code: '2100', amount: '250000.00', side: 'credit', currency: 'NGN' },
+    ],
+});
+
+// Balances, current and historical
+const now = await ledger.accounts.balance(accountId);
+const mayClose = await ledger.accounts.balanceAsOf(accountId, '2026-05-31');
+
+// Reverse (at most once; second attempt raises a 409)
+await ledger.transactions.reverse(tx.id);
+
+// Treasury surface
+await ledger.currencies.register({ code: 'BTC', exponent: 8, name: 'Bitcoin' });
+await ledger.periods.create({ name: 'June 2026', starts_on: '2026-06-01', ends_on: '2026-06-30' });
+const tb = await ledger.reports.trialBalance({ asOf: '2026-06-30' });
+const csv = await ledger.reports.xeroJournalsCsv({ startDate: '2026-06-01', endDate: '2026-06-30' });
+```
+
+## Rules the types enforce
+
+- **Amounts are strings, always.** The ledger stores NUMERIC(38,18); JavaScript
+  numbers cannot represent one wei or one satoshi exactly. Send strings,
+  receive strings.
+- **Errors are `LedgerApiError`** with `status`, the server's message, and an
+  `isConflict` helper for the 409 family (double reversal, closed period,
+  duplicate currency or period).
+- The wire format (snake_case) is preserved verbatim; the SDK adds no mapping
+  layer that could drift from the API.
+
+## Development
+
+```bash
+npm install
+npm test          # unit tests, mocked fetch
+npm run build     # dual ESM/CJS + d.ts via tsup
+npm run smoke     # live end-to-end against localhost:8080 (see docs/development.md)
+```

package/dist/index.cjs

@@ -0,0 +1,559 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LedgerApiError: () => LedgerApiError,
+  LedgerClient: () => LedgerClient,
+  MissingIdempotencyKeyError: () => MissingIdempotencyKeyError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var LedgerApiError = class extends Error {
+  /** HTTP status code */
+  status;
+  /** Alias for status, per the Alphaex integration contract. */
+  httpStatus;
+  /** Stable machine-readable code (absent on transport-level failures). */
+  code;
+  /** Structured error context (e.g. InsufficientBalanceDetails). */
+  details;
+  /** Raw response body, when one could be read */
+  body;
+  constructor(status, message, options = {}) {
+    super(message);
+    this.name = "LedgerApiError";
+    this.status = status;
+    this.httpStatus = status;
+    this.code = options.code;
+    this.details = options.details;
+    this.body = options.body;
+  }
+  /** True for 409s: double reversals, closed periods, existing resources. */
+  get isConflict() {
+    return this.status === 409;
+  }
+  /** Typed accessor for INSUFFICIENT_BALANCE detail. */
+  get insufficientBalance() {
+    if (this.code !== "INSUFFICIENT_BALANCE") {
+      return void 0;
+    }
+    return this.details;
+  }
+};
+var MissingIdempotencyKeyError = class extends Error {
+  constructor(method) {
+    super(`${method} requires an explicit idempotencyKey (client has requireIdempotencyKey: true)`);
+    this.name = "MissingIdempotencyKeyError";
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  baseUrl;
+  headers;
+  fetchImpl;
+  timeoutMs;
+  tenant;
+  requireIdempotencyKey;
+  constructor(options) {
+    if (!options.baseUrl) {
+      throw new Error("baseUrl is required");
+    }
+    if (!options.tenant) {
+      throw new Error("tenant is required");
+    }
+    if (!options.apiKey && !options.token) {
+      throw new Error("either apiKey or token is required");
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.tenant = options.tenant;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.timeoutMs = options.timeoutMs;
+    this.requireIdempotencyKey = options.requireIdempotencyKey ?? false;
+    this.headers = { "Content-Type": "application/json" };
+    if (options.apiKey) {
+      this.headers["X-API-Key"] = options.apiKey;
+    } else if (options.token) {
+      this.headers["Authorization"] = `Bearer ${options.token}`;
+    }
+  }
+  /** Path inside the tenant scope, e.g. tenantPath('/accounts') */
+  tenantPath(path) {
+    return `/tenants/${encodeURIComponent(this.tenant)}${path}`;
+  }
+  effectiveSignal(callerSignal) {
+    const timeoutSignal = this.timeoutMs ? AbortSignal.timeout(this.timeoutMs) : void 0;
+    if (callerSignal && timeoutSignal) {
+      return typeof AbortSignal.any === "function" ? AbortSignal.any([callerSignal, timeoutSignal]) : callerSignal;
+    }
+    return callerSignal ?? timeoutSignal;
+  }
+  async request(method, path, options = {}) {
+    let url = `${this.baseUrl}/api/v1${path}`;
+    if (options.query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(options.query)) {
+        if (value !== void 0 && value !== "") {
+          params.set(key, String(value));
+        }
+      }
+      const qs = params.toString();
+      if (qs) {
+        url += `?${qs}`;
+      }
+    }
+    const response = await this.fetchImpl(url, {
+      method,
+      headers: this.headers,
+      body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+      signal: this.effectiveSignal(options.signal)
+    });
+    if (options.raw) {
+      const text = await response.text();
+      if (!response.ok) {
+        throw new LedgerApiError(response.status, text || response.statusText, { body: text });
+      }
+      return text;
+    }
+    let envelope;
+    try {
+      envelope = await response.json();
+    } catch {
+      envelope = void 0;
+    }
+    if (!response.ok || !envelope || envelope.success !== true) {
+      const message = envelope?.error ?? `request failed with status ${response.status}`;
+      throw new LedgerApiError(response.status, message, {
+        code: envelope?.code,
+        details: envelope?.details,
+        body: envelope
+      });
+    }
+    return envelope.data;
+  }
+};
+var generateIdempotencyKey = () => {
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi && "randomUUID" in cryptoApi) {
+    return cryptoApi.randomUUID();
+  }
+  return `idem-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+};
+
+// src/resources/accounts.ts
+var AccountsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  create(input, options = {}) {
+    return this.http.request("POST", this.http.tenantPath("/accounts"), { body: input, signal: options.signal });
+  }
+  list(params = {}, options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/accounts"), {
+      signal: options.signal,
+      query: {
+        account_type: params.accountType,
+        parent_code: params.parentCode,
+        currency: params.currency,
+        search: params.search,
+        page: params.page,
+        page_size: params.pageSize
+      }
+    });
+  }
+  get(accountId, options = {}) {
+    return this.http.request("GET", this.http.tenantPath(`/accounts/${accountId}`), { signal: options.signal });
+  }
+  getByCode(code, options = {}) {
+    return this.http.request("GET", this.http.tenantPath(`/accounts/code/${encodeURIComponent(code)}`), { signal: options.signal });
+  }
+  update(accountId, input, options = {}) {
+    return this.http.request("PUT", this.http.tenantPath(`/accounts/${accountId}`), { body: input, signal: options.signal });
+  }
+  deactivate(accountId, options = {}) {
+    return this.http.request("DELETE", this.http.tenantPath(`/accounts/${accountId}`), { signal: options.signal });
+  }
+  /** Current materialized balance. Currency defaults to the tenant base currency. */
+  balance(accountId, options = {}) {
+    return this.http.request("GET", this.http.tenantPath(`/accounts/${accountId}/balance`), {
+      signal: options.signal,
+      query: { currency: options.currency }
+    });
+  }
+  /** Journal-derived balance through the end of a past day (YYYY-MM-DD, UTC). */
+  balanceAsOf(accountId, asOf, options = {}) {
+    return this.http.request("GET", this.http.tenantPath(`/accounts/${accountId}/balance`), {
+      signal: options.signal,
+      query: { as_of: asOf, currency: options.currency }
+    });
+  }
+  hierarchy(options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/accounts/hierarchy"), { signal: options.signal });
+  }
+  stats(options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/accounts/stats"), { signal: options.signal });
+  }
+};
+
+// src/resources/balances.ts
+var BalancesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Bulk balances: every (account, currency) row with its monotonic
+   * version. Filter by codePrefix/codeSuffix, currency, or account
+   * metadata containment (e.g. { org_id: '...' }).
+   */
+  list(params = {}, options = {}) {
+    const metadata = params.metadata && Object.keys(params.metadata).length > 0 ? Object.entries(params.metadata).map(([key, value]) => `${key}:${value}`).join(",") : void 0;
+    return this.http.request("GET", this.http.tenantPath("/balances"), {
+      query: {
+        limit: params.limit,
+        offset: params.offset,
+        code_prefix: params.codePrefix,
+        code_suffix: params.codeSuffix,
+        currency: params.currency,
+        metadata
+      },
+      signal: options.signal
+    });
+  }
+};
+
+// src/resources/events.ts
+var EventsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Durable event feed, strictly ordered by sequence. Poll with
+   * afterId = the last sequence you processed; store next_cursor.
+   */
+  list(params = {}, options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/events"), {
+      query: {
+        after_id: params.afterId,
+        limit: params.limit
+      },
+      signal: options.signal
+    });
+  }
+};
+
+// src/resources/currencies.ts
+var CurrenciesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Register a currency with its precision policy. Postings beyond the
+   * exponent's decimal places are rejected. Unregistered currencies fall
+   * back to the storage maximum of 18 decimal places.
+   */
+  register(input, options = {}) {
+    return this.http.request("POST", this.http.tenantPath("/currencies"), { body: input, signal: options.signal });
+  }
+  list(options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/currencies"), { signal: options.signal });
+  }
+  update(code, input, options = {}) {
+    return this.http.request("PUT", this.http.tenantPath(`/currencies/${encodeURIComponent(code)}`), {
+      signal: options.signal,
+      body: input
+    });
+  }
+};
+
+// src/resources/periods.ts
+var PeriodsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Periods of one tenant may not overlap; violations raise a 409. */
+  create(input, options = {}) {
+    return this.http.request("POST", this.http.tenantPath("/periods"), { body: input, signal: options.signal });
+  }
+  list(options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/periods"), { signal: options.signal });
+  }
+  /**
+   * Close a period. Enforced by the database: nothing can post into a
+   * closed period, and posting attempts raise a 409.
+   */
+  close(periodId, options = {}) {
+    return this.http.request("POST", this.http.tenantPath(`/periods/${periodId}/close`), { signal: options.signal });
+  }
+  reopen(periodId, options = {}) {
+    return this.http.request("POST", this.http.tenantPath(`/periods/${periodId}/reopen`), { signal: options.signal });
+  }
+};
+
+// src/resources/recurring.ts
+var RecurringJournalsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Register a repeating journal. Each occurrence posts exactly once: the
+   * worker derives the idempotency key from (schedule id, run date).
+   */
+  create(input, options = {}) {
+    return this.http.request("POST", this.http.tenantPath("/recurring-journals"), { body: input, signal: options.signal });
+  }
+  list(options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/recurring-journals"), { signal: options.signal });
+  }
+  pause(scheduleId, options = {}) {
+    return this.http.request("POST", this.http.tenantPath(`/recurring-journals/${scheduleId}/pause`), { signal: options.signal });
+  }
+  resume(scheduleId, options = {}) {
+    return this.http.request("POST", this.http.tenantPath(`/recurring-journals/${scheduleId}/resume`), { signal: options.signal });
+  }
+};
+
+// src/resources/reports.ts
+var dimensionsParam = (dimensions) => {
+  if (!dimensions || Object.keys(dimensions).length === 0) {
+    return void 0;
+  }
+  return Object.entries(dimensions).map(([key, value]) => `${key}:${value}`).join(",");
+};
+var ReportsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Trial balance derived from posted journal lines, grouped by currency.
+   * asOf (YYYY-MM-DD) means "through the end of that day, UTC"; defaults
+   * to now.
+   */
+  trialBalance(options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/reports/trial-balance"), {
+      signal: options.signal,
+      query: { as_of: options.asOf }
+    });
+  }
+  /** Revenue and expenses over an inclusive date range, optionally filtered by dimensions. */
+  profitAndLoss(options) {
+    return this.http.request("GET", this.http.tenantPath("/reports/profit-and-loss"), {
+      signal: options.signal,
+      query: {
+        start_date: options.startDate,
+        end_date: options.endDate,
+        dimensions: dimensionsParam(options.dimensions)
+      }
+    });
+  }
+  /** Assets, liabilities, and equity (with computed retained earnings) as of a date. */
+  balanceSheet(options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/reports/balance-sheet"), {
+      signal: options.signal,
+      query: { as_of: options.asOf }
+    });
+  }
+  /** One account's activity with opening, running, and closing balances. */
+  generalLedger(options) {
+    return this.http.request("GET", this.http.tenantPath("/reports/general-ledger"), {
+      signal: options.signal,
+      query: {
+        account_code: options.accountCode,
+        start_date: options.startDate,
+        end_date: options.endDate,
+        currency: options.currency
+      }
+    });
+  }
+  /** Per-currency net positions with base equivalents at the provided rates. */
+  fxExposure(options = {}) {
+    const rates = options.rates ? Object.entries(options.rates).map(([code, rate]) => `${code}:${rate}`).join(",") : void 0;
+    return this.http.request("GET", this.http.tenantPath("/reports/fx-exposure"), {
+      signal: options.signal,
+      query: { rates, as_of: options.asOf }
+    });
+  }
+  /**
+   * Posted journals as a Xero manual-journal import CSV (raw string).
+   * Dates are inclusive. Currency defaults to the tenant base currency.
+   */
+  xeroJournalsCsv(options) {
+    return this.http.request("GET", this.http.tenantPath("/reports/xero-journals"), {
+      signal: options.signal,
+      query: {
+        start_date: options.startDate,
+        end_date: options.endDate,
+        currency: options.currency
+      },
+      raw: true
+    });
+  }
+};
+
+// src/resources/transactions.ts
+var TransactionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  idempotencyKey(method, provided) {
+    if (provided) {
+      return provided;
+    }
+    if (this.http.requireIdempotencyKey) {
+      throw new MissingIdempotencyKeyError(method);
+    }
+    return generateIdempotencyKey();
+  }
+  /**
+   * Post a balanced double-entry transaction. Debits must equal credits per
+   * currency or the API rejects with UNBALANCED_TRANSACTION. posted_at
+   * backdates the posting and requires the transactions:backdate scope.
+   */
+  post(input, options = {}) {
+    const { idempotencyKey, postedAt, ...rest } = input;
+    return this.http.request("POST", this.http.tenantPath("/transactions/double-entry"), {
+      body: {
+        ...rest,
+        idempotency_key: this.idempotencyKey("transactions.post", idempotencyKey),
+        ...postedAt ? { posted_at: postedAt } : {}
+      },
+      signal: options.signal
+    });
+  }
+  get(transactionId, options = {}) {
+    return this.http.request("GET", this.http.tenantPath(`/transactions/${transactionId}`), {
+      query: { include: options.includeLines ? "lines" : void 0 },
+      signal: options.signal
+    });
+  }
+  lines(transactionId, options = {}) {
+    return this.http.request("GET", this.http.tenantPath(`/transactions/${transactionId}/lines`), {
+      signal: options.signal
+    });
+  }
+  list(params = {}, options = {}) {
+    return this.http.request("GET", this.http.tenantPath("/transactions"), {
+      query: {
+        limit: params.limit,
+        offset: params.offset,
+        account_code: params.accountCode,
+        reference: params.reference,
+        status: params.status,
+        start_date: params.startDate,
+        end_date: params.endDate,
+        include: params.includeLines ? "lines" : void 0
+      },
+      signal: options.signal
+    });
+  }
+  /**
+   * Maker-checker: store a fully validated entry with zero balance impact.
+   * Balances apply only when a DIFFERENT actor approves.
+   */
+  draft(input, options = {}) {
+    const { idempotencyKey, postedAt, ...rest } = input;
+    void postedAt;
+    return this.http.request("POST", this.http.tenantPath("/transactions/draft"), {
+      body: {
+        ...rest,
+        idempotency_key: this.idempotencyKey("transactions.draft", idempotencyKey)
+      },
+      signal: options.signal
+    });
+  }
+  /** Approve a draft (requires the transactions:approve scope and a different actor). */
+  approve(transactionId, options = {}) {
+    return this.http.request("POST", this.http.tenantPath(`/transactions/${transactionId}/approve`), {
+      signal: options.signal
+    });
+  }
+  /** Reject a draft; it never had balance impact. */
+  reject(transactionId, options = {}) {
+    return this.http.request("POST", this.http.tenantPath(`/transactions/${transactionId}/reject`), {
+      signal: options.signal
+    });
+  }
+  /** Append an immutable note (audit support). */
+  addNote(transactionId, note, options = {}) {
+    return this.http.request("POST", this.http.tenantPath(`/transactions/${transactionId}/notes`), {
+      body: { note },
+      signal: options.signal
+    });
+  }
+  listNotes(transactionId, options = {}) {
+    return this.http.request("GET", this.http.tenantPath(`/transactions/${transactionId}/notes`), {
+      signal: options.signal
+    });
+  }
+  /**
+   * Post a reversal: a new transaction mirroring the original with debits
+   * and credits swapped, linked via reverses_transaction_id. A transaction
+   * can be reversed at most once; a second attempt raises ALREADY_REVERSED.
+   */
+  reverse(transactionId, reverseOptions = {}, options = {}) {
+    return this.http.request("POST", this.http.tenantPath(`/transactions/${transactionId}/reverse`), {
+      body: {
+        idempotency_key: this.idempotencyKey("transactions.reverse", reverseOptions.idempotencyKey),
+        description: reverseOptions.description,
+        metadata: reverseOptions.metadata
+      },
+      signal: options.signal
+    });
+  }
+};
+
+// src/index.ts
+var LedgerClient = class {
+  accounts;
+  balances;
+  events;
+  transactions;
+  currencies;
+  periods;
+  recurringJournals;
+  reports;
+  constructor(options) {
+    const http = new HttpClient(options);
+    this.accounts = new AccountsResource(http);
+    this.balances = new BalancesResource(http);
+    this.events = new EventsResource(http);
+    this.transactions = new TransactionsResource(http);
+    this.currencies = new CurrenciesResource(http);
+    this.periods = new PeriodsResource(http);
+    this.recurringJournals = new RecurringJournalsResource(http);
+    this.reports = new ReportsResource(http);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LedgerApiError,
+  LedgerClient,
+  MissingIdempotencyKeyError
+});
+//# sourceMappingURL=index.cjs.map