@classytic/ledger 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/ledger",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Production-grade double-entry accounting engine for MongoDB — schemas, reports, tax, multi-tenant",
   "type": "module",
   "sideEffects": false,
@@ -90,12 +90,15 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/classytic/accounting.git"
+    "url": "git+https://github.com/classytic/ledger.git"
   },
   "peerDependencies": {
     "@classytic/fin-io": ">=0.1.0",
-    "@classytic/mongokit": ">=3.6.4",
-    "mongoose": ">=9.4.1"
+    "@classytic/mongokit": ">=3.11.0",
+    "@classytic/primitives": ">=0.1.0",
+    "@classytic/repo-core": ">=0.2.0",
+    "mongoose": ">=9.4.1",
+    "zod": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "@classytic/fin-io": {
@@ -103,17 +106,20 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
-    "@classytic/fin-io": "file:../fin-io",
-    "@classytic/mongokit": "^3.6.4",
+    "@biomejs/biome": "^2.4.12",
+    "@classytic/fin-io": ">=0.1.0",
+    "@classytic/mongokit": ">=3.11.0",
+    "@classytic/primitives": ">=0.1.0",
+    "@classytic/repo-core": ">=0.2.0",
     "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "knip": "^6.3.0",
-    "mongodb-memory-server": "^10.2.3",
+    "@vitest/coverage-v8": "^4.1.4",
+    "knip": "^6.4.1",
+    "mongodb-memory-server": "^11.0.1",
     "mongoose": "^9.4.1",
-    "tsdown": "^0.21.5",
+    "tsdown": "^0.21.8",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.4",
+    "zod": "^4.3.6"
   },
   "engines": {
     "node": ">=22"
@@ -121,8 +127,11 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit --project integration",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src/",

package/dist/outbox-store-DQbL-KYT.mjs

@@ -1,132 +0,0 @@
-import { randomUUID } from "node:crypto";
-//#region src/events/event-constants.ts
-/**
-* Ledger domain event names.
-*
-* Convention: `ledger:<resource>.<verb>` — matches the catalog/revenue/flow
-* namespace pattern so hosts can subscribe with a single glob
-* (`ledger:entry.*`, `ledger:*`).
-*/
-const LEDGER_EVENTS = {
-	ENTRY_CREATED: "ledger:entry.created",
-	ENTRY_POSTED: "ledger:entry.posted",
-	ENTRY_UNPOSTED: "ledger:entry.unposted",
-	ENTRY_ARCHIVED: "ledger:entry.archived",
-	ENTRY_DUPLICATED: "ledger:entry.duplicated",
-	ENTRY_REVERSED: "ledger:entry.reversed",
-	ACCOUNT_SEEDED: "ledger:account.seeded",
-	ACCOUNT_BULK_CREATED: "ledger:account.bulk-created",
-	JOURNAL_SEEDED: "ledger:journal.seeded",
-	RECONCILIATION_MATCHED: "ledger:reconciliation.matched",
-	RECONCILIATION_UNMATCHED: "ledger:reconciliation.unmatched"
-};
-//#endregion
-//#region src/events/helpers.ts
-/**
-* Event creation helper.
-*
-* Builds a well-formed DomainEvent with auto-generated `meta.id` + `meta.timestamp`.
-* Threads optional context fields (userId, organizationId, correlationId) that
-* hosts rely on for audit trails and distributed tracing.
-*/
-function toIdString(value) {
-	if (value == null) return void 0;
-	if (typeof value === "string") return value;
-	if (typeof value === "number" || typeof value === "bigint") return String(value);
-	const obj = value;
-	if (typeof obj.toHexString === "function") return obj.toHexString();
-	if (typeof obj.toString === "function") {
-		const s = obj.toString();
-		return s === "[object Object]" ? void 0 : s;
-	}
-}
-function createEvent(type, payload, ctx, meta) {
-	return {
-		type,
-		payload,
-		meta: {
-			id: randomUUID(),
-			timestamp: /* @__PURE__ */ new Date(),
-			userId: toIdString(ctx?.actorId),
-			organizationId: toIdString(ctx?.organizationId),
-			correlationId: ctx?.correlationId ?? ctx?.traceId,
-			...meta
-		}
-	};
-}
-//#endregion
-//#region src/events/in-process-bus.ts
-var InProcessLedgerBus = class {
-	name = "in-process-ledger";
-	handlers = /* @__PURE__ */ new Map();
-	logger;
-	constructor(options) {
-		this.logger = options?.logger ?? console;
-	}
-	async publish(event) {
-		const exact = this.handlers.get(event.type) ?? /* @__PURE__ */ new Set();
-		const wildcard = this.handlers.get("*") ?? /* @__PURE__ */ new Set();
-		const pattern = /* @__PURE__ */ new Set();
-		for (const [p, handlers] of this.handlers.entries()) if (p.endsWith(".*")) {
-			const prefix = p.slice(0, -2);
-			if (event.type.startsWith(`${prefix}.`)) for (const h of handlers) pattern.add(h);
-		} else if (p.endsWith(":*")) {
-			const prefix = p.slice(0, -2);
-			if (event.type.startsWith(`${prefix}:`)) for (const h of handlers) pattern.add(h);
-		}
-		const all = new Set([
-			...exact,
-			...wildcard,
-			...pattern
-		]);
-		for (const handler of all) try {
-			await handler(event);
-		} catch (err) {
-			this.logger.error(`[InProcessLedgerBus] Handler error for ${event.type}:`, err);
-		}
-	}
-	async publishMany(events) {
-		const results = /* @__PURE__ */ new Map();
-		for (const event of events) try {
-			await this.publish(event);
-			results.set(event.meta.id, null);
-		} catch (err) {
-			results.set(event.meta.id, err instanceof Error ? err : new Error(String(err)));
-		}
-		return results;
-	}
-	async subscribe(pattern, handler) {
-		if (!this.handlers.has(pattern)) this.handlers.set(pattern, /* @__PURE__ */ new Set());
-		this.handlers.get(pattern)?.add(handler);
-		return () => {
-			const set = this.handlers.get(pattern);
-			if (set) {
-				set.delete(handler);
-				if (set.size === 0) this.handlers.delete(pattern);
-			}
-		};
-	}
-	async close() {
-		this.handlers.clear();
-	}
-};
-//#endregion
-//#region src/events/outbox-store.ts
-/**
-* Thrown by a store when `acknowledge` / `fail` is called by a consumer that
-* does not own the event's current lease.
-*/
-var OutboxOwnershipError = class extends Error {
-	eventId;
-	attemptedBy;
-	currentOwner;
-	constructor(eventId, attemptedBy, currentOwner) {
-		super(`Outbox ownership mismatch for event "${eventId}": attempted by "${attemptedBy}", current owner is "${currentOwner ?? "none"}". The lease may have expired and been reclaimed by another worker.`);
-		this.name = "OutboxOwnershipError";
-		this.eventId = eventId;
-		this.attemptedBy = attemptedBy;
-		this.currentOwner = currentOwner;
-	}
-};
-//#endregion
-export { LEDGER_EVENTS as i, InProcessLedgerBus as n, createEvent as r, OutboxOwnershipError as t };

package/dist/outbox-store-UYC4eZpI.d.mts

@@ -1,249 +0,0 @@
-//#region src/events/event-constants.d.ts
-/**
- * Ledger domain event names.
- *
- * Convention: `ledger:<resource>.<verb>` — matches the catalog/revenue/flow
- * namespace pattern so hosts can subscribe with a single glob
- * (`ledger:entry.*`, `ledger:*`).
- */
-declare const LEDGER_EVENTS: {
-  readonly ENTRY_CREATED: "ledger:entry.created";
-  readonly ENTRY_POSTED: "ledger:entry.posted";
-  readonly ENTRY_UNPOSTED: "ledger:entry.unposted";
-  readonly ENTRY_ARCHIVED: "ledger:entry.archived";
-  readonly ENTRY_DUPLICATED: "ledger:entry.duplicated";
-  readonly ENTRY_REVERSED: "ledger:entry.reversed";
-  readonly ACCOUNT_SEEDED: "ledger:account.seeded";
-  readonly ACCOUNT_BULK_CREATED: "ledger:account.bulk-created";
-  readonly JOURNAL_SEEDED: "ledger:journal.seeded";
-  readonly RECONCILIATION_MATCHED: "ledger:reconciliation.matched";
-  readonly RECONCILIATION_UNMATCHED: "ledger:reconciliation.unmatched";
-};
-type LedgerEventName = (typeof LEDGER_EVENTS)[keyof typeof LEDGER_EVENTS];
-//#endregion
-//#region src/events/event-payloads.d.ts
-/**
- * Typed payload definitions for ledger domain events.
- */
-interface EntryCreatedPayload {
-  entryId: unknown;
-  journalType?: string;
-  state: string;
-  referenceNumber?: string;
-  idempotencyKey?: string;
-  organizationId?: unknown;
-}
-interface EntryPostedPayload {
-  entryId: unknown;
-  referenceNumber?: string;
-  postedBy?: unknown;
-  totalDebit: number;
-  totalCredit: number;
-  organizationId?: unknown;
-}
-interface EntryUnpostedPayload {
-  entryId: unknown;
-  unpostedBy?: unknown;
-  organizationId?: unknown;
-}
-interface EntryArchivedPayload {
-  entryId: unknown;
-  archivedBy?: unknown;
-  organizationId?: unknown;
-}
-interface EntryDuplicatedPayload {
-  sourceEntryId: unknown;
-  duplicateEntryId: unknown;
-  organizationId?: unknown;
-}
-interface EntryReversedPayload {
-  originalEntryId: unknown;
-  reversalEntryId: unknown;
-  reversalDate: Date;
-  reversedBy?: unknown;
-  organizationId?: unknown;
-}
-interface AccountSeededPayload {
-  created: number;
-  skipped: number;
-  organizationId?: unknown;
-}
-interface AccountBulkCreatedPayload {
-  created: number;
-  skipped: number;
-  errors: number;
-  organizationId?: unknown;
-}
-interface JournalSeededPayload {
-  created: number;
-  skipped: number;
-  organizationId?: unknown;
-}
-interface ReconciliationMatchedPayload {
-  matchingNumber: string;
-  account: unknown;
-  itemCount: number;
-  debitTotal: number;
-  creditTotal: number;
-  isFullReconcile: boolean;
-  currency: string | null;
-  organizationId?: unknown;
-}
-interface ReconciliationUnmatchedPayload {
-  matchingNumber: string;
-  itemCount: number;
-  organizationId?: unknown;
-}
-//#endregion
-//#region src/events/transport.d.ts
-/**
- * EventTransport — structurally identical to @classytic/arc's EventTransport.
- *
- * DO NOT import from @classytic/arc at runtime. TypeScript structural typing
- * means any arc transport (Memory, Redis, BullMQ, Kafka) is assignable to this
- * interface with zero adapter code, as long as the shape matches exactly.
- *
- * See: packages/arc/src/events/EventTransport.ts
- */
-interface DomainEvent<T = unknown> {
-  type: string;
-  payload: T;
-  meta: {
-    id: string;
-    timestamp: Date;
-    resource?: string;
-    resourceId?: string;
-    userId?: string;
-    organizationId?: string;
-    correlationId?: string;
-  };
-}
-type EventHandler<T = unknown> = (event: DomainEvent<T>) => void | Promise<void>;
-/**
- * Per-event outcome returned by `EventTransport.publishMany`.
- * Key is `event.meta.id`; value is `null` for success or `Error` for per-event failure.
- */
-type PublishManyResult = ReadonlyMap<string, Error | null>;
-interface EventLogger {
-  warn(message: string, ...args: unknown[]): void;
-  error(message: string, ...args: unknown[]): void;
-}
-interface EventTransport {
-  readonly name: string;
-  publish(event: DomainEvent): Promise<void>;
-  publishMany?(events: readonly DomainEvent[]): Promise<PublishManyResult>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close?(): Promise<void>;
-}
-//#endregion
-//#region src/events/helpers.d.ts
-/** Minimal context shape for event metadata. */
-interface EventContext {
-  actorId?: unknown;
-  organizationId?: unknown;
-  correlationId?: string;
-  traceId?: string;
-}
-declare function createEvent<T>(type: string, payload: T, ctx?: EventContext, meta?: Partial<DomainEvent['meta']>): DomainEvent<T>;
-//#endregion
-//#region src/events/in-process-bus.d.ts
-interface InProcessLedgerBusOptions {
-  logger?: EventLogger;
-}
-declare class InProcessLedgerBus implements EventTransport {
-  readonly name = "in-process-ledger";
-  private handlers;
-  private logger;
-  constructor(options?: InProcessLedgerBusOptions);
-  publish(event: DomainEvent): Promise<void>;
-  publishMany(events: readonly DomainEvent[]): Promise<PublishManyResult>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close(): Promise<void>;
-}
-//#endregion
-//#region src/events/outbox-store.d.ts
-/** Options passed to `OutboxStore.save` for richer write semantics. */
-interface OutboxWriteOptions {
-  /** Host-provided DB session/transaction handle for atomic writes. */
-  readonly session?: unknown;
-  /** Earliest time the event should be visible to relay workers. */
-  readonly visibleAt?: Date;
-  /** Idempotency key — stores that support it should dedupe on this. */
-  readonly dedupeKey?: string;
-  /** Partition/routing key for sharded transports (Kafka, Redis Streams). */
-  readonly partitionKey?: string;
-  /** Arbitrary headers propagated to the transport layer. */
-  readonly headers?: Readonly<Record<string, string>>;
-}
-/** Options for lease-based work claim. */
-interface OutboxClaimOptions {
-  readonly limit?: number;
-  readonly consumerId?: string;
-  readonly leaseMs?: number;
-  readonly types?: readonly string[];
-}
-/** Options for `OutboxStore.acknowledge`. */
-interface OutboxAcknowledgeOptions {
-  readonly consumerId?: string;
-}
-/** Options for `OutboxStore.fail`. */
-interface OutboxFailOptions {
-  readonly consumerId?: string;
-  readonly retryAt?: Date;
-  readonly deadLetter?: boolean;
-}
-/** Normalized error info passed to `OutboxStore.fail`. */
-interface OutboxErrorInfo {
-  readonly message: string;
-  readonly code?: string;
-}
-/**
- * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
- * does not own the event's current lease.
- */
-declare class OutboxOwnershipError extends Error {
-  readonly eventId: string;
-  readonly attemptedBy: string;
-  readonly currentOwner: string | null;
-  constructor(eventId: string, attemptedBy: string, currentOwner: string | null);
-}
-/**
- * Durable storage contract for the transactional outbox pattern.
- *
- * **Required**: `save`, `getPending`, `acknowledge`.
- * **Optional** (stores opt-in): `claimPending`, `fail`, `purge`.
- *
- * Structurally identical to arc's `OutboxStore` — assignable in both
- * directions via TypeScript structural typing.
- */
-interface OutboxStore {
-  /**
-   * Save event to outbox (typically inside a business transaction via `options.session`).
-   * MUST reject events missing `type` or `meta.id` — throw rather than persist.
-   */
-  save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
-  /**
-   * Get pending (unrelayed) events, FIFO ordered.
-   * Multi-worker deployments should prefer `claimPending` if supported.
-   */
-  getPending(limit: number): Promise<DomainEvent[]>;
-  /**
-   * Atomically claim pending events with a lease.
-   * Two concurrent callers MUST never receive overlapping events.
-   */
-  claimPending?(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
-  /**
-   * Mark event as successfully relayed. Unknown eventId is a no-op (idempotent).
-   * Ownership mismatch MUST throw `OutboxOwnershipError`.
-   */
-  acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
-  /**
-   * Record a relay failure. Enables retry scheduling and dead-letter flow.
-   * Ownership mismatch MUST throw `OutboxOwnershipError`.
-   */
-  fail?(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
-  /** Purge old delivered events (older than `olderThanMs`). Returns count. */
-  purge?(olderThanMs: number): Promise<number>;
-}
-//#endregion
-export { EntryReversedPayload as C, ReconciliationUnmatchedPayload as D, ReconciliationMatchedPayload as E, LEDGER_EVENTS as O, EntryPostedPayload as S, JournalSeededPayload as T, AccountBulkCreatedPayload as _, OutboxOwnershipError as a, EntryCreatedPayload as b, InProcessLedgerBus as c, createEvent as d, DomainEvent as f, PublishManyResult as g, EventTransport as h, OutboxFailOptions as i, LedgerEventName as k, InProcessLedgerBusOptions as l, EventLogger as m, OutboxClaimOptions as n, OutboxStore as o, EventHandler as p, OutboxErrorInfo as r, OutboxWriteOptions as s, OutboxAcknowledgeOptions as t, EventContext as u, AccountSeededPayload as v, EntryUnpostedPayload as w, EntryDuplicatedPayload as x, EntryArchivedPayload as y };