@classytic/revenue 1.1.3 → 2.0.0

package/dist/engine-types-CcjIb4Fy.d.mts

@@ -0,0 +1,611 @@
+import { t as RevenueContext } from "./context-DRqSeTPM.mjs";
+import { t as RevenueBridges } from "./revenue-bridges-sdlrR85c.mjs";
+import { o as PaymentProvider, t as ProviderRegistry } from "./registry-SvIGPAx_.mjs";
+import { RepositoryPluginBundle, RevenueRepositories } from "./repositories/create-repositories.mjs";
+import { PluginType, Repository } from "@classytic/mongokit";
+import { TenantConfig } from "@classytic/primitives/tenant";
+import mongoose, { Connection, Model, Schema } from "mongoose";
+import { EventTransport } from "@classytic/primitives/events";
+import { OutboxStore } from "@classytic/primitives/outbox";
+
+//#region src/models/transaction.schema.d.ts
+interface TransactionDocument {
+  _id: mongoose.Types.ObjectId;
+  publicId: string;
+  organizationId?: string;
+  customerId?: string | null;
+  type: string;
+  flow: 'inflow' | 'outflow';
+  tags: string[];
+  amount: number;
+  currency: string;
+  fee: number;
+  tax: number;
+  net: number;
+  taxDetails?: {
+    type?: string;
+    rate?: number;
+    isInclusive?: boolean;
+  };
+  method: string;
+  status: string;
+  gateway?: {
+    type: string;
+    sessionId?: string;
+    paymentIntentId?: string;
+    chargeId?: string;
+    metadata?: Record<string, unknown>;
+    verificationData?: Record<string, unknown>;
+  };
+  paymentDetails?: Record<string, unknown>;
+  commission?: {
+    rate: number;
+    grossAmount: number;
+    gatewayFeeRate: number;
+    gatewayFeeAmount: number;
+    netAmount: number;
+    status: string;
+  };
+  splits?: Array<{
+    type: string;
+    recipientId: string;
+    recipientType: string;
+    rate: number;
+    grossAmount: number;
+    gatewayFeeRate: number;
+    gatewayFeeAmount: number;
+    netAmount: number;
+    status: string;
+  }>;
+  hold?: {
+    status: string;
+    heldAmount: number;
+    releasedAmount: number;
+    reason: string;
+    heldAt: Date;
+    holdUntil?: Date;
+    releasedAt?: Date;
+    cancelledAt?: Date;
+    releases: Array<{
+      amount: number;
+      recipientId: string;
+      recipientType: string;
+      releasedAt: Date;
+      releasedBy?: string;
+      reason?: string;
+      metadata?: Record<string, unknown>;
+    }>;
+    metadata?: Record<string, unknown>;
+  };
+  sourceId?: string;
+  sourceModel?: string;
+  relatedTransactionId?: mongoose.Types.ObjectId;
+  refundedAmount?: number;
+  refundedAt?: Date;
+  failureReason?: string;
+  failedAt?: Date;
+  verifiedAt?: Date;
+  verifiedBy?: string;
+  webhook?: {
+    eventId: string;
+    eventType: string;
+    receivedAt: Date;
+    processedAt: Date;
+    data: Record<string, unknown>;
+  };
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+  deletedAt?: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/models/subscription.schema.d.ts
+interface SubscriptionDocument {
+  _id: mongoose.Types.ObjectId;
+  publicId: string;
+  organizationId?: string;
+  customerId?: string | null;
+  planKey: string;
+  amount: number;
+  currency?: string;
+  status: string;
+  isActive: boolean;
+  transactionId?: mongoose.Types.ObjectId | null;
+  paymentIntentId?: string | null;
+  startDate?: Date;
+  endDate?: Date;
+  activatedAt?: Date;
+  pausedAt?: Date;
+  pauseReason?: string;
+  canceledAt?: Date;
+  cancelAt?: Date;
+  cancellationReason?: string;
+  renewalTransactionId?: mongoose.Types.ObjectId;
+  renewalCount: number;
+  metadata?: Record<string, unknown>;
+  deletedAt?: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/models/settlement.schema.d.ts
+interface SettlementDocument {
+  _id: mongoose.Types.ObjectId;
+  publicId: string;
+  organizationId: string;
+  recipientId: string;
+  recipientType: string;
+  type: string;
+  status: string;
+  payoutMethod: string;
+  amount: number;
+  currency: string;
+  sourceTransactionIds: mongoose.Types.ObjectId[];
+  sourceSplitIds: string[];
+  bankTransferDetails?: Record<string, unknown>;
+  mobileWalletDetails?: Record<string, unknown>;
+  cryptoDetails?: Record<string, unknown>;
+  scheduledAt: Date;
+  processedAt?: Date;
+  completedAt?: Date;
+  failedAt?: Date;
+  cancelledAt?: Date;
+  failureReason?: string;
+  failureCode?: string;
+  retryCount: number;
+  notes?: string;
+  metadata?: Record<string, unknown>;
+  deletedAt?: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/models/create-models.d.ts
+interface RevenueModels {
+  Transaction: Model<TransactionDocument>;
+  Subscription?: Model<SubscriptionDocument>;
+  Settlement?: Model<SettlementDocument>;
+}
+interface RevenueSchemaOptions {
+  transaction?: {
+    extraFields?: Record<string, unknown>;
+    extraIndexes?: Array<{
+      fields: Record<string, 1 | -1>;
+      options?: Record<string, unknown>;
+    }>;
+  };
+  subscription?: {
+    extraFields?: Record<string, unknown>;
+    extraIndexes?: Array<{
+      fields: Record<string, 1 | -1>;
+      options?: Record<string, unknown>;
+    }>;
+  };
+  settlement?: {
+    extraFields?: Record<string, unknown>;
+    extraIndexes?: Array<{
+      fields: Record<string, 1 | -1>;
+      options?: Record<string, unknown>;
+    }>;
+  };
+}
+//#endregion
+//#region src/repositories/transaction.repository.d.ts
+interface TransactionRepoDeps {
+  events: EventTransport;
+  /**
+   * Optional host-owned outbox store (PACKAGE_RULES §5.5 + P8). When present,
+   * every domain event is persisted via `outbox.save(event)` before the
+   * in-process `events.publish(event)` so the host's relay (arc's EventOutbox,
+   * a Postgres LISTEN/NOTIFY pump, Kafka Connect, …) can replay on transport
+   * failure. When absent, events fire through `events.publish` only.
+   */
+  outbox?: OutboxStore | undefined;
+  providers: ProviderRegistry;
+  bridges: RevenueBridges;
+  commission?: CommissionConfig;
+  defaultCurrency: string;
+  logger?: {
+    error(...args: unknown[]): void;
+  } | undefined;
+}
+/**
+ * TransactionRepository — extends mongokit Repository.
+ *
+ * CRUD inherited: getAll, getById, getByQuery, create, update, delete, count, exists.
+ * Domain verbs: createPaymentIntent, verify, refund, handleWebhook, hold, release, split.
+ *
+ * All domain verbs return raw mongokit docs — no custom envelopes.
+ * Composite results (refund creates a new doc) are stored in metadata on the primary doc.
+ */
+declare class TransactionRepository extends Repository<TransactionDocument> {
+  private deps;
+  constructor(model: Model<TransactionDocument>, plugins?: PluginType[]);
+  inject(deps: TransactionRepoDeps): void;
+  /**
+   * Thread `ctx.organizationId` (and future ctx fields) into mongokit
+   * options so the `multiTenantPlugin` can auto-scope filters, queries,
+   * and inserts. Merges any caller-supplied extras. Centralizing this
+   * here means every domain verb participates in scope isolation without
+   * per-call boilerplate.
+   */
+  private optsFromCtx;
+  /**
+   * Save an event to the host-owned outbox, session-bound when available.
+   *
+   * When `session` is passed, the outbox row commits atomically with the
+   * business write (P8 true session-bound write). When absent, the save
+   * happens after commit — still durable via the host's relay, but with a
+   * small at-most-once window on process crash.
+   *
+   * Isolated try/catch: an outbox failure never throws out of this helper;
+   * the caller still issues a transport.publish.
+   */
+  private saveToOutbox;
+  /**
+   * Publish an event to the in-process `EventTransport` after commit.
+   * Transport failure is logged — the host relay will still redeliver from
+   * the outbox, so in-process subscribers missing an event is recoverable.
+   */
+  private publishToTransport;
+  /**
+   * Non-transactional dispatch (used by verbs that don't open their own
+   * `withTransaction` block): outbox.save (session-bound when ctx provides
+   * one) → transport.publish. Matches arc's EventOutbox + MemoryEventTransport
+   * wiring bit-for-bit.
+   */
+  private dispatch;
+  /** Creates transaction + calls provider. Returns the created transaction doc. */
+  createPaymentIntent(params: {
+    data?: Record<string, unknown>;
+    planKey?: string;
+    monetizationType?: string;
+    amount: number;
+    currency?: string;
+    gateway: string;
+    paymentData?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /** Verifies payment via provider, updates status. Returns the updated doc. */
+  verify(paymentIntentId: string, options?: {
+    verifiedBy?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * Creates refund transaction, updates original. Returns the refund transaction doc.
+   *
+   * The provider call happens OUTSIDE the transaction — it's a non-idempotent external
+   * side effect we can't roll back. The two Mongo writes (create refund + update original)
+   * run inside `withTransaction` so they commit atomically or both abort. Bridges and
+   * event emission run AFTER commit because they're independent side effects; rolling
+   * them back would not undo external state anyway.
+   *
+   * Powered by mongokit 3.6's module-level `withTransaction` helper. Automatically
+   * retries on `TransientTransactionError` / `UnknownTransactionCommitResult`.
+   */
+  refund(transactionId: string, amount?: number | null, options?: {
+    reason?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /** Handles provider webhook. Returns the updated transaction doc (or null if not found). */
+  handleWebhook(providerName: string, payload: unknown, headers?: Record<string, string>, ctx?: RevenueContext): Promise<TransactionDocument | null>;
+  /** Places hold on verified transaction. Returns the updated doc. */
+  hold(transactionId: string, options?: {
+    amount?: number;
+    reason?: string;
+    holdUntil?: Date;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * Releases held funds. Returns the updated transaction doc.
+   *
+   * The hold update and the escrow_release transaction create happen inside
+   * `withTransaction` — a mid-flow crash can't leave the hold marked released
+   * without the corresponding outflow record (or vice versa).
+   */
+  release(transactionId: string, options: {
+    amount?: number;
+    recipientId: string;
+    recipientType: string;
+    reason?: string;
+    releasedBy?: string;
+    createTransaction?: boolean;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * Splits payment among recipients. Returns the updated transaction doc.
+   *
+   * N + 2 writes (one create per recipient, one update on the parent, one
+   * platform_revenue create) all commit atomically. Partial splits are the
+   * worst class of bug in a payments system — this is exactly what
+   * `withTransaction` is for.
+   */
+  split(transactionId: string, rules: Array<{
+    type: string;
+    recipientId: string;
+    recipientType: string;
+    rate: number;
+  }>, ctx?: RevenueContext): Promise<TransactionDocument>;
+}
+//#endregion
+//#region src/repositories/subscription.repository.d.ts
+interface SubscriptionRepoDeps {
+  events: EventTransport;
+  /** Host-owned outbox (PACKAGE_RULES §5.5 + P8). See TransactionRepoDeps. */
+  outbox?: OutboxStore | undefined;
+  logger?: {
+    error(...args: unknown[]): void;
+  } | undefined;
+}
+/**
+ * SubscriptionRepository — data layer + domain verbs.
+ *
+ * CRUD inherited from mongokit. Domain verbs: activate, cancel, pause, resume.
+ *
+ * Events: each domain verb calls `this.deps.events.publish(createEvent(...))`
+ * with a fully-qualified `REVENUE_EVENTS.*` name. Hosts can subscribe glob-style
+ * via `revenue.events.subscribe('revenue:subscription.*', handler)` — the
+ * injected transport is arc-compatible (PACKAGE_RULES §13–§14).
+ */
+declare class SubscriptionRepository extends Repository<SubscriptionDocument> {
+  private deps;
+  constructor(model: Model<SubscriptionDocument>, plugins?: PluginType[]);
+  inject(deps: SubscriptionRepoDeps): void;
+  /**
+   * Host-owned outbox save → in-process transport publish (PACKAGE_RULES P8).
+   * Session-bound when `ctx.session` is present (atomic outbox row write).
+   */
+  private dispatch;
+  activate(subscriptionId: string, options?: {
+    timestamp?: Date;
+  }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
+  cancel(subscriptionId: string, options?: {
+    immediate?: boolean;
+    reason?: string;
+  }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
+  pause(subscriptionId: string, options?: {
+    reason?: string;
+  }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
+  resume(subscriptionId: string, options?: {
+    extendPeriod?: boolean;
+  }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
+}
+//#endregion
+//#region src/repositories/settlement.repository.d.ts
+interface SettlementRepoDeps {
+  events: EventTransport;
+  /** Host-owned outbox (PACKAGE_RULES §5.5 + P8). See TransactionRepoDeps. */
+  outbox?: OutboxStore | undefined;
+  bridges: RevenueBridges;
+  logger?: {
+    error(...args: unknown[]): void;
+  } | undefined;
+}
+interface SettlementProcessingError {
+  settlementId: SettlementDocument['_id'];
+  error: unknown;
+}
+/**
+ * SettlementRepository — data layer + domain verbs.
+ *
+ * CRUD inherited from mongokit. Domain verbs: schedule, processPending, complete, fail.
+ *
+ * Events are published via the injected `events` transport (arc-compatible).
+ * Hosts subscribe glob-style via `revenue.events.subscribe('revenue:settlement.*', h)`.
+ * See PACKAGE_RULES §13–§14.
+ */
+declare class SettlementRepository extends Repository<SettlementDocument> {
+  private deps;
+  constructor(model: Model<SettlementDocument>, plugins?: PluginType[]);
+  inject(deps: SettlementRepoDeps): void;
+  /**
+   * Host-owned outbox save → in-process transport publish (PACKAGE_RULES P8).
+   * Session-bound when `ctx.session` is present (atomic outbox row write).
+   */
+  private dispatch;
+  schedule(params: {
+    organizationId: string;
+    recipientId: string;
+    recipientType: string;
+    type: string;
+    amount: number;
+    currency: string;
+    payoutMethod: string;
+    sourceTransactionIds?: string[];
+    sourceSplitIds?: string[];
+    scheduledAt?: Date;
+    bankTransferDetails?: Record<string, unknown>;
+    mobileWalletDetails?: Record<string, unknown>;
+    cryptoDetails?: Record<string, unknown>;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<SettlementDocument>;
+  processPending(options?: {
+    limit?: number;
+    organizationId?: string;
+    payoutMethod?: string;
+    dryRun?: boolean;
+  }, ctx?: RevenueContext): Promise<{
+    processed: number;
+    succeeded: number;
+    failed: number;
+    settlements: SettlementDocument[];
+    errors: SettlementProcessingError[];
+  }>;
+  complete(settlementId: string, details?: {
+    transferReference?: string;
+    transferredAt?: Date;
+    transactionHash?: string;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<SettlementDocument>;
+  fail(settlementId: string, reason: string, options?: {
+    code?: string;
+    retry?: boolean;
+  }, ctx?: RevenueContext): Promise<SettlementDocument>;
+}
+//#endregion
+//#region src/engine/engine-types.d.ts
+interface CommissionConfig {
+  defaultRate: number;
+  gatewayFeeRate?: number | undefined;
+  categoryRates?: Record<string, number> | undefined;
+  gatewayRates?: Record<string, number> | undefined;
+}
+interface RetryConfig {
+  maxAttempts?: number | undefined;
+  baseDelay?: number | undefined;
+}
+interface RevenueConfig {
+  connection: Connection;
+  defaultCurrency: string;
+  /**
+   * Event transport — structurally compatible with `@classytic/arc`'s
+   * `EventTransport`. Drop in any arc transport (Memory/Redis/Kafka) and it
+   * works without an adapter. When omitted, the engine uses
+   * `InProcessRevenueBus` (a ~50-line match of arc's `MemoryEventTransport`).
+   */
+  eventTransport?: EventTransport | undefined;
+  /**
+   * Host-owned transactional outbox store (PACKAGE_RULES §5.5 + P8).
+   * Structurally identical to `@classytic/arc`'s `OutboxStore` by design —
+   * primitives is the source of truth for the contract and arc mirrors it.
+   *
+   * **Host responsibility.** Revenue does NOT ship a durable store. Arc 2.10
+   * only ships `MemoryOutboxStore` (dev) + the `OutboxStore` interface — the
+   * host wires durability. The canonical production wiring uses arc's
+   * `repositoryAsOutboxStore` adapter over a mongokit `Repository`:
+   *
+   * ```ts
+   * import mongoose, { Schema } from 'mongoose';
+   * import {
+   *   Repository,
+   *   methodRegistryPlugin,
+   *   batchOperationsPlugin,
+   * } from '@classytic/mongokit';
+   * import { EventOutbox, repositoryAsOutboxStore } from '@classytic/arc/events';
+   * import { createRevenue } from '@classytic/revenue';
+   *
+   * // Arc owns the on-disk doc shape — strict:false forwards every field
+   * // (see arc's events.mdx "Why strict: false").
+   * const OutboxModel = mongoose.model(
+   *   'ArcOutbox',
+   *   new Schema({}, { strict: false, timestamps: false, _id: false }),
+   *   'event_outbox',
+   * );
+   *
+   * // Required plugins: the adapter calls `create` / `findAll` /
+   * // `findOneAndUpdate` (base Repository) + `deleteMany` (batchOperations).
+   * const outboxRepo = new Repository(OutboxModel, [
+   *   methodRegistryPlugin(),
+   *   batchOperationsPlugin(),
+   * ]);
+   * const outbox = repositoryAsOutboxStore(outboxRepo);
+   *
+   * const engine = await createRevenue({
+   *   connection: mongoose.connection,
+   *   defaultCurrency: 'USD',
+   *   outbox,                       // revenue's dispatch saves here
+   *   eventTransport: app.events,   // arc transport for in-process subscribers
+   *   // ...
+   * });
+   *
+   * // Relay + DLQ live in the host, not the package:
+   * const relay = new EventOutbox({ store: outbox, transport: app.events });
+   * setInterval(() => relay.relay(), 1_000);
+   * ```
+   *
+   * **Session-bound atomicity.** Revenue's transactional verbs (`refund`,
+   * `release`, `split`) open a mongokit `withTransaction` and pass the
+   * mongoose `ClientSession` into `outbox.save(event, { session })`, so the
+   * outbox row commits atomically with the business writes. Non-transactional
+   * verbs (`createPaymentIntent`, `verify`, `handleWebhook`, `hold`) forward
+   * `ctx.session` when the host is coordinating its own transaction — pass
+   * `{ session }` in `RevenueContext` to participate.
+   *
+   * **Non-arc hosts.** Any `OutboxStore` works — implement the three-method
+   * floor (`save` / `getPending` / `acknowledge`) over Postgres / Redis /
+   * Kafka / SQS. When omitted, events flow to `eventTransport` only
+   * (durability becomes transport-level, not at-least-once).
+   */
+  outbox?: OutboxStore | undefined;
+  modules?: {
+    subscription?: boolean | undefined;
+    escrow?: boolean | undefined;
+    settlement?: boolean | undefined;
+    commission?: CommissionConfig | boolean | undefined;
+  } | undefined;
+  providers?: Record<string, PaymentProvider> | undefined;
+  bridges?: RevenueBridges | undefined;
+  repositoryPlugins?: RepositoryPluginBundle | undefined;
+  schemaOptions?: RevenueSchemaOptions | undefined;
+  /**
+   * Tenant scope configuration. Delegates to `@classytic/primitives`'
+   * `TenantConfig`. Field names match mongokit's `MultiTenantOptions` so
+   * the resolved config forwards directly into `multiTenantPlugin(...)`.
+   *
+   * - `undefined` / `true` → default field strategy, ObjectId storage.
+   * - `false` → single-tenant (no plugin, field still present, not required).
+   * - `{ fieldType: 'string' }` → string orgIds (UUID/slug hosts).
+   * - `{ strategy: 'custom', resolve: ... }` → composite / derived scope.
+   *
+   * See PACKAGE_RULES.md §9.
+   */
+  scope?: TenantConfig | boolean | undefined;
+  commission?: CommissionConfig | undefined;
+  retry?: RetryConfig | undefined;
+  circuitBreaker?: boolean | undefined;
+  /**
+   * Set `false` to disable Mongoose auto-index on boot. Indexes are then
+   * managed explicitly via `engine.syncIndexes()` or a deploy-time script.
+   */
+  autoIndex?: boolean | Partial<Record<'Transaction' | 'Subscription' | 'Settlement', boolean>> | undefined;
+  /**
+   * Optional prefix prepended to every physical collection this package
+   * creates (see PACKAGE_RULES.md §20.1). Unset → default names
+   * (`revenue_transactions`, `revenue_subscriptions`, `revenue_settlements`).
+   * Model names and `ref:` populate are unaffected.
+   */
+  collectionPrefix?: string | undefined;
+  /**
+   * When true, existing Mongoose models with revenue's names are deleted
+   * from the connection before re-registering. Hot-reload / test fixtures
+   * only. Default `false` — collision throws `RevenueModelCollisionError`.
+   * Hosts that need two revenue engines should use two Mongoose connections
+   * (`mongoose.createConnection(...)`). See PACKAGE_RULES.md §21.
+   */
+  forceRecreate?: boolean | undefined;
+  logger?: {
+    info: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  } | undefined;
+}
+/**
+ * RevenueEngine — no service facade.
+ *
+ * Repositories ARE the domain layer. CRUD is inherited from mongokit.
+ * Domain verbs (verify, refund, hold, activate, etc.) live on repositories.
+ * Arc's BaseController/adapter plugs into repositories directly.
+ *
+ * `events` is structurally compatible with `@classytic/arc`'s
+ * `EventTransport`. Hosts subscribe glob-style:
+ *
+ *     await revenue.events.subscribe('revenue:payment.*', handler);
+ *
+ * and the same transport can be wired into the outbox relay for durable
+ * delivery (see mongokit's `outbox-recipe.ts`). See PACKAGE_RULES §13.
+ */
+interface RevenueEngine {
+  config: Readonly<RevenueConfig>;
+  models: RevenueModels;
+  repositories: RevenueRepositories;
+  providers: ProviderRegistry;
+  events: EventTransport;
+  /** Explicitly build all schema-declared indexes. Non-destructive. */
+  syncIndexes(): Promise<void>;
+  destroy(): Promise<void>;
+}
+//#endregion
+export { SettlementRepository as a, RevenueModels as c, SubscriptionDocument as d, TransactionDocument as f, RevenueEngine as i, RevenueSchemaOptions as l, RetryConfig as n, SubscriptionRepository as o, RevenueConfig as r, TransactionRepository as s, CommissionConfig as t, SettlementDocument as u };