@classytic/ledger 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/dist/bridges/index.d.mts +2 -0
  2. package/dist/bridges/index.mjs +1 -0
  3. package/dist/constants/index.d.mts +1 -1
  4. package/dist/constants/index.mjs +2 -2
  5. package/dist/country/index.d.mts +1 -1
  6. package/dist/errors-BI5k4iak.mjs +121 -0
  7. package/dist/events/index.d.mts +2 -0
  8. package/dist/events/index.mjs +2 -0
  9. package/dist/exports/index.d.mts +1 -1
  10. package/dist/exports/index.mjs +1 -1
  11. package/dist/{fx-realization.plugin-DDVK-oYO.mjs → fx-realization.plugin-Bxlb8cIx.mjs} +2 -2
  12. package/dist/{index-RNZsX0Yo.d.mts → index-08IpHhrU.d.mts} +1 -1
  13. package/dist/index-dqkjgpII.d.mts +104 -0
  14. package/dist/index.d.mts +227 -65
  15. package/dist/index.mjs +385 -99
  16. package/dist/{journals-Dd4A9TN3.d.mts → journals-DUpWwFt1.d.mts} +1 -1
  17. package/dist/outbox-store-DQbL-KYT.mjs +132 -0
  18. package/dist/outbox-store-UYC4eZpI.d.mts +249 -0
  19. package/dist/{partner-ledger-D9H5hegI.mjs → partner-ledger-BoebloHk.mjs} +2 -2
  20. package/dist/plugins/index.d.mts +1 -1
  21. package/dist/plugins/index.mjs +1 -1
  22. package/dist/reports/index.d.mts +1 -1
  23. package/dist/reports/index.mjs +1 -1
  24. package/dist/sync/index.d.mts +1 -1
  25. package/dist/sync/index.mjs +1 -1
  26. package/dist/{sync-CnuVf441.d.mts → sync-JvchM3FO.d.mts} +1 -1
  27. package/dist/{trial-balance-DTj-c21f.d.mts → trial-balance-DyNm5bFu.d.mts} +2 -2
  28. package/package.json +14 -4
  29. package/dist/errors-CSDQPNyt.mjs +0 -33
  30. /package/dist/{categories-BkKdv16V.mjs → categories-FJlrvzcl.mjs} +0 -0
  31. /package/dist/{core-MpgjCqK0.d.mts → core-DwjkrRkJ.d.mts} +0 -0
  32. /package/dist/{currencies-CsuBGfgs.mjs → currencies-Jo5oaM_4.mjs} +0 -0
  33. /package/dist/{exports-B3whucXe.mjs → exports-C30yRapf.mjs} +0 -0
  34. /package/dist/{index-BSsvrf3m.d.mts → index-Db0n_6Z8.d.mts} +0 -0
  35. /package/dist/{index-bCEeSzdO.d.mts → index-J-XIbXH-.d.mts} +0 -0
  36. /package/dist/{opening-balance-DPXmAIzN.mjs → opening-balance-1cixYh6Y.mjs} +0 -0
package/dist/index.d.mts CHANGED
@@ -1,13 +1,128 @@
1
- import { _ as TaxMetadata, a as Cents, c as DateRange, d as JournalType, f as MainType, g as TaxDetail, h as StatementType, i as CategoryKey, l as EntryState, m as ObjectId, n as CashFlowCategory, o as Currency, p as NormalBalance, s as DateOption, t as AccountType, u as JournalItem, v as TotalAccountOp } from "./core-MpgjCqK0.mjs";
2
- import { S as isValidCategory, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, i as getJournalType, l as getCurrency, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, x as isIncomeStatement, y as getNormalBalance } from "./journals-Dd4A9TN3.mjs";
3
- import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-RNZsX0Yo.mjs";
4
- import { _ as PopulatedJournalEntry, a as exportToCsv, h as FlatJournalRow, i as quickbooksFieldMap, m as ExportFieldMap, p as ExportField, r as universalFieldMap, t as flattenJournalEntries } from "./index-bCEeSzdO.mjs";
1
+ import { a as EntryReversedNotification, c as PeriodLockedNotification, i as SourceRef, l as ReconciliationMismatchNotification, n as SourceBridge, o as NotificationBridge, r as SourceBridgeContext, s as NotificationBridgeContext, t as LedgerBridges } from "./index-dqkjgpII.mjs";
2
+ import { _ as TaxMetadata, a as Cents, c as DateRange, d as JournalType, f as MainType, g as TaxDetail, h as StatementType, i as CategoryKey, l as EntryState, m as ObjectId, n as CashFlowCategory, o as Currency, p as NormalBalance, s as DateOption, t as AccountType, u as JournalItem, v as TotalAccountOp } from "./core-DwjkrRkJ.mjs";
3
+ import { S as isValidCategory, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, i as getJournalType, l as getCurrency, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, x as isIncomeStatement, y as getNormalBalance } from "./journals-DUpWwFt1.mjs";
4
+ import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-08IpHhrU.mjs";
5
+ import { C as EntryReversedPayload, D as ReconciliationUnmatchedPayload, E as ReconciliationMatchedPayload, O as LEDGER_EVENTS, S as EntryPostedPayload, T as JournalSeededPayload, _ as AccountBulkCreatedPayload, a as OutboxOwnershipError, b as EntryCreatedPayload, c as InProcessLedgerBus, d as createEvent, f as DomainEvent, g as PublishManyResult, h as EventTransport, i as OutboxFailOptions, k as LedgerEventName, l as InProcessLedgerBusOptions, m as EventLogger, n as OutboxClaimOptions, o as OutboxStore, p as EventHandler, r as OutboxErrorInfo, s as OutboxWriteOptions, t as OutboxAcknowledgeOptions, u as EventContext, v as AccountSeededPayload, w as EntryUnpostedPayload, x as EntryDuplicatedPayload, y as EntryArchivedPayload } from "./outbox-store-UYC4eZpI.mjs";
6
+ import { _ as PopulatedJournalEntry, a as exportToCsv, h as FlatJournalRow, i as quickbooksFieldMap, m as ExportFieldMap, p as ExportField, r as universalFieldMap, t as flattenJournalEntries } from "./index-J-XIbXH-.mjs";
5
7
  import { Money, abs, add, allocate, equals, format, formatPlain, fromDecimal, isNegative, isPositive, isValid, isZero, max, min, multiply, negate, parseCents, percentage, round, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal } from "./money.mjs";
6
- import { $ as AgedBalanceParams, A as generateDimensionBreakdown, B as BalanceSheetReport, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as IncomeStatementReport, H as CashFlowSection, I as BudgetVsActualRow, J as ReportCategory, K as LedgerEntry, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as AgedBalanceOptions, T as reopenFiscalPeriod, U as GeneralLedgerAccount, V as CashFlowReport, W as GeneralLedgerReport, X as TrialBalanceReport, Y as ReportGroup, Z as TrialBalanceRow, a as RevaluationReport, at as Logger, b as generateGeneralLedger, c as RevaluationRate, d as computeRevaluation, et as AgedBalanceReport, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as generateAgedBalance, k as DimensionBreakdownRow, l as RevaluationResult, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBucketConfig, o as generateRevaluation, ot as defaultLogger, p as PartnerLedgerOptions, q as ReportAccount, r as RevaluationOptions, rt as DEFAULT_BUCKETS, s as AccountForeignBalance, tt as AgedBalanceRow, u as buildRevaluationEntry, v as generateIncomeStatement, w as closeFiscalPeriod, z as generateBalanceSheet } from "./trial-balance-DTj-c21f.mjs";
7
- import { A as OpenItem, C as AccountRepository, D as JournalItemRef, E as JournalEntryRepository, F as SeedOptions, I as SeedResult, M as ReconciliationRepository, N as ReverseOptions, O as JournalRepository, P as ReverseResult, S as creditLimitPlugin, T as BulkCreateResult, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, i as FiscalLockPluginOptions, j as PostOptions, k as MatchInput, l as createLockPlugin, m as LockResolverContext, n as watermarkResolver, o as fiscalLockPlugin, p as LockResolver, r as DailyLockPluginOptions, s as PeriodResolverOptions, t as WatermarkResolverOptions, u as CreateLockPluginOptions, v as fxRealizationPlugin, w as BulkCreateInput, x as CreditLimitPluginOptions } from "./index-BSsvrf3m.mjs";
8
- import { PaginationConfig, PluginType, QueryParser, QueryParserOptions, Repository } from "@classytic/mongokit";
8
+ import { $ as AgedBalanceParams, A as generateDimensionBreakdown, B as BalanceSheetReport, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as IncomeStatementReport, H as CashFlowSection, I as BudgetVsActualRow, J as ReportCategory, K as LedgerEntry, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as AgedBalanceOptions, T as reopenFiscalPeriod, U as GeneralLedgerAccount, V as CashFlowReport, W as GeneralLedgerReport, X as TrialBalanceReport, Y as ReportGroup, Z as TrialBalanceRow, a as RevaluationReport, at as Logger, b as generateGeneralLedger, c as RevaluationRate, d as computeRevaluation, et as AgedBalanceReport, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as generateAgedBalance, k as DimensionBreakdownRow, l as RevaluationResult, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBucketConfig, o as generateRevaluation, ot as defaultLogger, p as PartnerLedgerOptions, q as ReportAccount, r as RevaluationOptions, rt as DEFAULT_BUCKETS, s as AccountForeignBalance, tt as AgedBalanceRow, u as buildRevaluationEntry, v as generateIncomeStatement, w as closeFiscalPeriod, z as generateBalanceSheet } from "./trial-balance-DyNm5bFu.mjs";
9
+ import { A as OpenItem, C as AccountRepository, D as JournalItemRef, E as JournalEntryRepository, F as SeedOptions, I as SeedResult, M as ReconciliationRepository, N as ReverseOptions, O as JournalRepository, P as ReverseResult, S as creditLimitPlugin, T as BulkCreateResult, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, i as FiscalLockPluginOptions, j as PostOptions, k as MatchInput, l as createLockPlugin, m as LockResolverContext, n as watermarkResolver, o as fiscalLockPlugin, p as LockResolver, r as DailyLockPluginOptions, s as PeriodResolverOptions, t as WatermarkResolverOptions, u as CreateLockPluginOptions, v as fxRealizationPlugin, w as BulkCreateInput, x as CreditLimitPluginOptions } from "./index-Db0n_6Z8.mjs";
10
+ import { PaginationConfig, PluginFunction, PluginType, QueryParser, QueryParserOptions, Repository } from "@classytic/mongokit";
9
11
  import { ClientSession, Connection, Model } from "mongoose";
10
12
 
13
+ //#region src/plugins/immutable-guard.plugin.d.ts
14
+ interface ImmutableGuardOptions {
15
+ /** The JournalEntry Mongoose model, for looking up current state on update. */
16
+ JournalEntryModel: Model<unknown>;
17
+ /** Multi-tenant org field name (if enabled). */
18
+ orgField?: string;
19
+ }
20
+ /**
21
+ * Returns a mongokit plugin function. Install only when
22
+ * `config.strictness.immutable === true`.
23
+ */
24
+ declare function immutableGuardPlugin(options: ImmutableGuardOptions): PluginFunction;
25
+ //#endregion
26
+ //#region src/utils/errors.d.ts
27
+ /**
28
+ * Typed error for the accounting package.
29
+ * Carries HTTP status + machine-readable code + structured field errors.
30
+ *
31
+ * The `fields` array lets AI agents and API clients pinpoint exactly
32
+ * what failed in a multi-field validation:
33
+ *
34
+ * throw Errors.validationWithFields('Journal entry invalid', [
35
+ * { path: 'journalItems.2.account', issue: 'account does not exist', value: '...' },
36
+ * { path: 'journalItems', issue: 'debits must equal credits', value: { debit: 500, credit: 450 } },
37
+ * ]);
38
+ */
39
+ /** A single field-level validation error. */
40
+ interface FieldError {
41
+ /** Dot-notation path to the invalid field (e.g. `journalItems.2.account`) */
42
+ readonly path: string;
43
+ /** Human-readable description of what's wrong */
44
+ readonly issue: string;
45
+ /** The offending value (optional — omit for sensitive data) */
46
+ readonly value?: unknown;
47
+ }
48
+ declare class AccountingError extends Error {
49
+ readonly status: number;
50
+ readonly code: string;
51
+ readonly fields?: ReadonlyArray<FieldError>;
52
+ constructor(message: string, status?: number, code?: string, fields?: ReadonlyArray<FieldError>);
53
+ /** Serialize to a plain object for API responses and logs. */
54
+ toJSON(): {
55
+ name: string;
56
+ message: string;
57
+ status: number;
58
+ code: string;
59
+ fields?: ReadonlyArray<FieldError>;
60
+ };
61
+ }
62
+ interface ErrorsFactories {
63
+ validation: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
64
+ notFound: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
65
+ conflict: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
66
+ immutable: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
67
+ locked: (scope: string, msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
68
+ }
69
+ declare const Errors: ErrorsFactories;
70
+ /**
71
+ * Thrown when an idempotent create was attempted with a key that already
72
+ * resolved to a different winner (not the common "same winner, same payload"
73
+ * replay — that returns the existing doc without throwing).
74
+ *
75
+ * Typically surfaces when the host supplies an `idempotencyKey` that collides
76
+ * with a logically-different prior write.
77
+ */
78
+ declare class IdempotencyConflictError extends AccountingError {
79
+ readonly idempotencyKey: string;
80
+ readonly existingId: unknown;
81
+ constructor(idempotencyKey: string, existingId: unknown, message?: string);
82
+ }
83
+ /**
84
+ * Thrown when the unique `referenceNumber` index fires. With the new atomic
85
+ * counter this should be effectively impossible — if it ever throws, it
86
+ * indicates either a pre-atomic-counter doc that was hand-inserted OR a bug
87
+ * in the counter partitioning.
88
+ */
89
+ declare class DuplicateReferenceError extends AccountingError {
90
+ readonly referenceNumber: string;
91
+ constructor(referenceNumber: string, message?: string);
92
+ }
93
+ /**
94
+ * Thrown when an optimistic-concurrency FSM transition fails because another
95
+ * writer advanced the state or version between our read and our write.
96
+ *
97
+ * Callers should re-fetch the doc and decide whether to retry or surface.
98
+ */
99
+ declare class ConcurrencyError extends AccountingError {
100
+ readonly resource: string;
101
+ readonly resourceId: unknown;
102
+ constructor(resource: string, resourceId: unknown, message?: string);
103
+ }
104
+ /**
105
+ * Thrown when a mutation targets an entry that is protected by immutability —
106
+ * either `strictness.immutable` or the double-entry plugin's posted-entry
107
+ * guard. Factory `Errors.immutable(msg)` returns this subclass so callers
108
+ * can `instanceof`-match without sniffing the `code` field.
109
+ */
110
+ declare class ImmutableViolationError extends AccountingError {
111
+ readonly entryId: unknown;
112
+ constructor(entryId: unknown, message?: string, fields?: ReadonlyArray<FieldError>);
113
+ }
114
+ /**
115
+ * Detect a Mongo duplicate-key error (11000) and return the index name the
116
+ * conflict hit on, so callers can switch on which unique key fired.
117
+ *
118
+ * Handles both driver-style and mongoose-style error shapes. Safe to call
119
+ * with any `unknown` — returns `null` when the error is not a dup-key.
120
+ */
121
+ declare function classifyDuplicateKey(err: unknown): {
122
+ indexName: string;
123
+ keyPattern?: Record<string, unknown>;
124
+ } | null;
125
+ //#endregion
11
126
  //#region src/types/engine.d.ts
12
127
  /** Mongokit plugins to install per repository (composes with engine built-ins). */
13
128
  interface LedgerRepositoryPlugins {
@@ -33,6 +148,22 @@ interface MultiTenantConfig {
33
148
  orgField: string;
34
149
  /** Mongoose model name the org field references (e.g., 'Business', 'Organization') */
35
150
  orgRef: string;
151
+ /**
152
+ * Enable mongokit's `multiTenantPlugin` on every ledger repository. The plugin
153
+ * injects the tenant filter at POLICY priority (before cache/audit) whenever
154
+ * `ctx.organizationId` is present on a call. When `false` (default), only
155
+ * manual `orgField` filters inside domain verbs enforce scoping.
156
+ *
157
+ * Recommended: `true` for new hosts. Keep `false` if your app has not yet
158
+ * migrated to context-based scoping.
159
+ */
160
+ plugin?: boolean;
161
+ /**
162
+ * Fail closed when `ctx.organizationId` is missing on a plugin-scoped call.
163
+ * Only applies when `plugin: true`. Default: `false` (skip injection when
164
+ * context is empty — matches historical ledger behavior).
165
+ */
166
+ required?: boolean;
36
167
  }
37
168
  /** Options passed to schema factory functions */
38
169
  interface SchemaOptions {
@@ -148,12 +279,70 @@ interface AccountingEngineConfig {
148
279
  audit?: AuditConfig;
149
280
  /** Enable built-in idempotency key field on journal entries */
150
281
  idempotency?: boolean;
282
+ /**
283
+ * TTL in seconds for idempotency records — stale replay keys auto-expire
284
+ * via a partial TTL index so they don't collide with legitimate reuse
285
+ * after the window closes. Default: 86400 (24h). Matches Stripe / Saleor
286
+ * convention. Only applies when `idempotency: true`.
287
+ */
288
+ idempotencyTtlSeconds?: number;
289
+ /**
290
+ * Automatically call `Model.syncIndexes()` on every managed model right
291
+ * after the engine boots. Ensures new partial/TTL indexes (0.9.0+) are
292
+ * present in MongoDB before the first write. Default: `false` — hosts
293
+ * that run migrations themselves should leave this off.
294
+ */
295
+ syncIndexes?: boolean;
151
296
  /** Strictness rules for the ledger */
152
297
  strictness?: StrictnessConfig;
153
298
  /** Mongokit plugins to install per repository. */
154
299
  plugins?: LedgerRepositoryPlugins;
155
300
  /** Pagination caps per repository. */
156
301
  pagination?: LedgerPaginationConfig;
302
+ /**
303
+ * Mongoose type for the multi-tenant field on all ledger schemas.
304
+ *
305
+ * - `'string'` (default, back-compat): stores tenant IDs as strings.
306
+ * Accepts any external auth system (UUIDs, slugs, external identifiers).
307
+ * - `'objectId'`: stores tenant IDs as native MongoDB ObjectId with a
308
+ * Mongoose ref to the organization collection. Enables `$lookup` and
309
+ * `.populate()` against Better Auth's `organization` collection.
310
+ *
311
+ * New hosts wiring Better Auth should pass `'objectId'`. See
312
+ * PACKAGE_RULES §9.1 and §9.2.
313
+ *
314
+ * Note: this field is plumbed into `multiTenantPlugin` when
315
+ * `multiTenant.plugin: true`. Schema-level type switching is applied
316
+ * by the models factory when it supports dynamic type declaration.
317
+ */
318
+ tenantFieldType?: 'objectId' | 'string';
319
+ /**
320
+ * Optional event transport — structurally identical to `@classytic/arc`'s
321
+ * `EventTransport`. Drop in any arc transport (Memory, Redis, Kafka, BullMQ)
322
+ * or provide a custom one. When omitted, the engine uses an in-process bus
323
+ * (`InProcessLedgerBus`) that is NOT suitable for multi-instance deployments.
324
+ */
325
+ eventTransport?: EventTransport;
326
+ /**
327
+ * Optional host-owned outbox store — structurally identical to
328
+ * `@classytic/arc`'s `OutboxStore`. When provided, domain events are
329
+ * persisted via `outbox.save(event, { session })` inside the same
330
+ * mongoose session as the ledger write, giving at-least-once delivery
331
+ * guarantees. A host-side relay worker calls `store.claimPending` +
332
+ * `transport.publish` + `store.acknowledge` independently.
333
+ *
334
+ * Package-owned durable outbox storage is an anti-pattern per
335
+ * PACKAGE_RULES §5.5. Ledger does NOT ship a concrete store — the
336
+ * host picks `MongoOutboxStore` (arc), a SQL store, a Redis store,
337
+ * etc. See `src/events/outbox-store.ts` for the interface contract.
338
+ */
339
+ outboxStore?: OutboxStore;
340
+ /**
341
+ * Host-provided bridges for external integrations (source resolution,
342
+ * notifications). All bridges and all methods are optional — features
343
+ * degrade gracefully when a bridge is missing.
344
+ */
345
+ bridges?: LedgerBridges;
157
346
  }
158
347
  //#endregion
159
348
  //#region src/models/factory.d.ts
@@ -185,16 +374,20 @@ interface LedgerRepositories {
185
374
  reconciliations: ReconciliationRepository<unknown>;
186
375
  journals: JournalRepository<unknown>;
187
376
  }
377
+ /**
378
+ * Extra wiring context passed into wireXxxMethods so domain verbs can emit
379
+ * events and reach out through host-provided bridges. Always optional so
380
+ * consumers without events/bridges see no behavioral change.
381
+ */
382
+ interface LedgerRepositoryIntegrations {
383
+ events?: EventTransport;
384
+ bridges?: LedgerBridges;
385
+ outboxStore?: OutboxStore;
386
+ }
188
387
  /**
189
388
  * Build all ledger repositories with plugins + domain methods pre-wired.
190
- *
191
- * - `accounts` — has seedAccounts(), bulkCreate()
192
- * - `journalEntries` — has post(), unpost(), reverse(), duplicate() + double-entry + fiscal-lock (+ idempotency if enabled)
193
- * - `fiscalPeriods` — plain CRUD
194
- * - `budgets` — plain CRUD
195
- * - `reconciliations` — has reconcile(), unreconcile(), getUnreconciled()
196
389
  */
197
- declare function createRepositories(models: LedgerModels, config: AccountingEngineConfig, plugins?: LedgerRepositoryPlugins, pagination?: LedgerPaginationConfig): LedgerRepositories;
390
+ declare function createRepositories(models: LedgerModels, config: AccountingEngineConfig, plugins?: LedgerRepositoryPlugins, pagination?: LedgerPaginationConfig, integrations?: LedgerRepositoryIntegrations): LedgerRepositories;
198
391
  //#endregion
199
392
  //#region src/semantic/introspect.d.ts
200
393
  interface AccountSummary {
@@ -500,6 +693,25 @@ declare class AccountingEngine {
500
693
  readonly repositories: LedgerRepositories;
501
694
  readonly record: RecordAPI;
502
695
  readonly introspect: IntrospectAPI;
696
+ /**
697
+ * Event transport — structurally matches `@classytic/arc`'s `EventTransport`.
698
+ * When the host does not inject one, the engine instantiates
699
+ * `InProcessLedgerBus` (suitable for single-instance deployments only).
700
+ * Subscribe with glob patterns: `ledger:entry.*`, `ledger:reconciliation.*`, `*`.
701
+ */
702
+ readonly events: EventTransport;
703
+ /**
704
+ * Host-provided bridges. Empty object when none supplied. Callers should
705
+ * optional-chain every method (`engine.bridges.source?.resolve?.(...)`).
706
+ */
707
+ readonly bridges: LedgerBridges;
708
+ /**
709
+ * Host-provided outbox store for durable event delivery (0.9.0). When
710
+ * present, every domain event is persisted to the outbox in the same
711
+ * mongoose session as the ledger write before the transport publish.
712
+ * Undefined when the host opts out of durable delivery.
713
+ */
714
+ readonly outboxStore: OutboxStore | undefined;
503
715
  private _reports?;
504
716
  constructor(config: AccountingEngineConfig);
505
717
  /**
@@ -752,56 +964,6 @@ declare function buildDimensionIndexes(dimensions: DimensionDefinition[], orgFie
752
964
  options?: Record<string, unknown>;
753
965
  }>;
754
966
  //#endregion
755
- //#region src/utils/errors.d.ts
756
- /**
757
- * Typed error for the accounting package.
758
- * Carries HTTP status + machine-readable code + structured field errors.
759
- *
760
- * The `fields` array lets AI agents and API clients pinpoint exactly
761
- * what failed in a multi-field validation:
762
- *
763
- * throw Errors.validationWithFields('Journal entry invalid', [
764
- * { path: 'journalItems.2.account', issue: 'account does not exist', value: '...' },
765
- * { path: 'journalItems', issue: 'debits must equal credits', value: { debit: 500, credit: 450 } },
766
- * ]);
767
- */
768
- /** A single field-level validation error. */
769
- interface FieldError {
770
- /** Dot-notation path to the invalid field (e.g. `journalItems.2.account`) */
771
- readonly path: string;
772
- /** Human-readable description of what's wrong */
773
- readonly issue: string;
774
- /** The offending value (optional — omit for sensitive data) */
775
- readonly value?: unknown;
776
- }
777
- declare class AccountingError extends Error {
778
- readonly status: number;
779
- readonly code: string;
780
- readonly fields?: ReadonlyArray<FieldError>;
781
- constructor(message: string, status?: number, code?: string, fields?: ReadonlyArray<FieldError>);
782
- /** Serialize to a plain object for API responses and logs. */
783
- toJSON(): {
784
- name: string;
785
- message: string;
786
- status: number;
787
- code: string;
788
- fields?: ReadonlyArray<FieldError>;
789
- };
790
- }
791
- /** Convenience factory functions. */
792
- declare const Errors: {
793
- readonly validation: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
794
- readonly notFound: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
795
- readonly conflict: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
796
- readonly immutable: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
797
- /**
798
- * Period/scope lock violation. Replaces the old `fiscal` factory — use the
799
- * `scope` argument to distinguish fiscal / tax / daily / bank / etc. The
800
- * resulting error code is `PERIOD_LOCKED_{SCOPE}` (e.g. `PERIOD_LOCKED_FISCAL`).
801
- */
802
- readonly locked: (scope: string, msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
803
- };
804
- //#endregion
805
967
  //#region src/utils/filter-builder.d.ts
806
968
  /**
807
969
  * Filter Builder — Sanitizes user-supplied dimension filters for aggregation pipelines.
@@ -881,4 +1043,4 @@ interface PostingResult {
881
1043
  idempotencyKeys?: string[];
882
1044
  }
883
1045
  //#endregion
884
- export { type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSummary, type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type ActorContext, type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type AuditConfig, type BalanceSheetReport, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type BulkCreateInput, type BulkCreateResult, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, type CountryPack, type CountryPackInput, type CreateLockPluginOptions, type CreditLimitPluginOptions, type Currency, DEFAULT_BUCKETS, type DailyLockPluginOptions, type DateOption, type DateRange, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type DimensionDefinition, type EntryState, Errors, type ExportField, type ExportFieldMap, type FieldError, type FiscalLockPluginOptions, type FiscalPeriodSummary, type FlatJournalRow, type FxRealizationPluginOptions, type GeneralLedgerAccount, type GeneralLedgerReport, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, type JournalTemplate, type JournalType, type LedgerEntry, type LedgerModels, type LedgerPaginationConfig, type LedgerRepositories, type LedgerRepositoryPlugins, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type Logger, type MainType, type MatchHookContext, type MatchHookItem, type MatchInput, type ModelNames, Money, type MultiCurrencyConfig, type MultiTenantConfig, type NormalBalance, type OpenItem, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type ReconciliationRepository, type RecordAPI, type RecordAdjustmentInput, type RecordAdjustmentLine, type RecordExpenseInput, type RecordOptions, type RecordPaymentInput, type RecordSaleInput, type RecordTransferInput, type ReportAccount, type ReportCategory, type ReportDescriptor, type ReportGroup, type ResolvedModelNames, type RevaluationOptions, type RevaluationParams, type RevaluationRate, type RevaluationReport, type RevaluationResult, type ReverseOptions, type ReverseResult, type SchemaOptions, type SeedOptions, type SeedResult, type Cents$1 as SemanticCents, type SessionResult, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxDetail, type TaxMetadata, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, type UnmatchHookContext, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildRevaluationEntry, calculateTotal, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createLockPlugin, createModels, createRepositories, creditLimitPlugin, dailyLockPlugin, defaultLogger, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, fxRealizationPlugin, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, getCurrency, getCustomJournalTypes, getDateRange, getFiscalYearStart, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };
1046
+ export { type AccountBulkCreatedPayload, type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSeededPayload, type AccountSummary, type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type ActorContext, type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type AuditConfig, type BalanceSheetReport, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type BulkCreateInput, type BulkCreateResult, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, ConcurrencyError, type CountryPack, type CountryPackInput, type CreateLockPluginOptions, type CreditLimitPluginOptions, type Currency, DEFAULT_BUCKETS, type DailyLockPluginOptions, type DateOption, type DateRange, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type DimensionDefinition, type DomainEvent, DuplicateReferenceError, type EntryArchivedPayload, type EntryCreatedPayload, type EntryDuplicatedPayload, type EntryPostedPayload, type EntryReversedNotification, type EntryReversedPayload, type EntryState, type EntryUnpostedPayload, Errors, type EventContext, type EventHandler, type EventLogger, type EventTransport, type ExportField, type ExportFieldMap, type FieldError, type FiscalLockPluginOptions, type FiscalPeriodSummary, type FlatJournalRow, type FxRealizationPluginOptions, type GeneralLedgerAccount, type GeneralLedgerReport, IdempotencyConflictError, type ImmutableGuardOptions, ImmutableViolationError, InProcessLedgerBus, type InProcessLedgerBusOptions, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, type JournalSeededPayload, type JournalTemplate, type JournalType, LEDGER_EVENTS, type LedgerBridges, type LedgerEntry, type LedgerEventName, type LedgerModels, type LedgerPaginationConfig, type LedgerRepositories, type LedgerRepositoryPlugins, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type Logger, type MainType, type MatchHookContext, type MatchHookItem, type MatchInput, type ModelNames, Money, type MultiCurrencyConfig, type MultiTenantConfig, type NormalBalance, type NotificationBridge, type NotificationBridgeContext, type OpenItem, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodLockedNotification, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type PublishManyResult, type ReconciliationMatchedPayload, type ReconciliationMismatchNotification, type ReconciliationRepository, type ReconciliationUnmatchedPayload, type RecordAPI, type RecordAdjustmentInput, type RecordAdjustmentLine, type RecordExpenseInput, type RecordOptions, type RecordPaymentInput, type RecordSaleInput, type RecordTransferInput, type ReportAccount, type ReportCategory, type ReportDescriptor, type ReportGroup, type ResolvedModelNames, type RevaluationOptions, type RevaluationParams, type RevaluationRate, type RevaluationReport, type RevaluationResult, type ReverseOptions, type ReverseResult, type SchemaOptions, type SeedOptions, type SeedResult, type Cents$1 as SemanticCents, type SessionResult, type SourceBridge, type SourceBridgeContext, type SourceRef, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxDetail, type TaxMetadata, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, type UnmatchHookContext, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildRevaluationEntry, calculateTotal, classifyDuplicateKey, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createEvent, createLockPlugin, createModels, createRepositories, creditLimitPlugin, dailyLockPlugin, defaultLogger, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, fxRealizationPlugin, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, getCurrency, getCustomJournalTypes, getDateRange, getFiscalYearStart, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, immutableGuardPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };