@classytic/primitives 0.19.0 → 0.20.0

package/dist/payment-gateway.d.mts

@@ -1,4 +1,4 @@
-import { Money } from "./money.mjs";
+import { n as Money } from "./money-DPo9fLBi.mjs";
 import { PaymentMethodKind } from "./payment-method-kind.mjs";
 
 //#region src/money/payment-gateway.d.ts
@@ -25,7 +25,7 @@ interface ProviderCapabilities {
  * Arguments to `provider.createIntent(...)`. Engine constructs this
  * from the host's checkout payload and the resolved currency. The
  * `metadata` blob is opaque pass-through — providers MAY forward it to
- * the upstream gateway (Stripe attaches it to the PaymentIntent), but
+ * the upstream gateway (Stripe attaches it to its own PaymentIntent), but
  * MUST NOT mutate or interpret it.
  */
 interface CreateIntentParams {
@@ -49,7 +49,7 @@ interface CreateIntentParams {
  * Stripe's PaymentIntent status because every other gateway maps cleanly
  * INTO this set; gateways that lack a state simply never emit it.
  */
-type PaymentIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded';
+type ProviderIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded';
 /** Closed set of refund lifecycle states the engine recognises. */
 type RefundResultStatus = 'pending' | 'requires_action' | 'succeeded' | 'failed' | 'canceled';
 /**
@@ -58,7 +58,17 @@ type RefundResultStatus = 'pending' | 'requires_action' | 'succeeded' | 'failed'
  * `gateway` block so subsequent `verify` / webhook lookups can find
  * the row.
  */
-interface PaymentIntent {
+/**
+ * A PROVIDER-side intent reference — what the gateway calls this payment.
+ *
+ * Named `ProviderIntent`, not `PaymentIntent`, because the domain aggregate that models the
+ * customer's obligation is also called a payment intent, and one name cannot span both layers.
+ * This is the narrow thing: a gateway-scoped id, the provider's own status mapped onto our closed
+ * union, and the amount it locked in. It belongs to ONE attempt against ONE provider account.
+ *
+ * See `spine/docs/payments-architecture.md` §3.3.
+ */
+interface ProviderIntent {
   /** Unique gateway-scoped id for this intent (`pi_xxx`, `ch_xxx`, etc.). */
   id: string;
   /** Lowercase gateway name (`'stripe'`, `'razorpay'`, `'sslcommerz'`, `'bkash'`, `'manual'`). */
@@ -67,7 +77,7 @@ interface PaymentIntent {
    * Lifecycle status — closed union the engine state-machines branch on.
    * Adapters MUST map provider-native strings into this set.
    */
-  status: PaymentIntentStatus;
+  status: ProviderIntentStatus;
   /** Amount + currency that the intent locks in. */
   amount: Money;
   /**
@@ -104,7 +114,7 @@ interface PaymentResult {
   /** Lowercase gateway name. */
   provider: string;
   /**
-   * Closed status set — narrower than `PaymentIntent.status` because
+   * Closed status set — narrower than `ProviderIntent.status` because
    * verification has settled the lifecycle.
    *
    * - `'succeeded'` — payment captured, funds owed to merchant.
@@ -185,5 +195,198 @@ interface WebhookEvent {
   /** Raw provider payload — audit only. */
   raw?: unknown;
 }
+/**
+ * The contract a payment provider must satisfy — declared HERE, in primitives, so an
+ * adapter can be written against it with **no runtime dependency on the engine**.
+ *
+ * ## Why this moved
+ *
+ * `@classytic/revenue-manual` imported the abstract `PaymentProvider` CLASS from
+ * `@classytic/revenue` — a runtime value, not a type. That coupled every adapter to the
+ * engine package: an adapter could not be versioned or published independently, and the
+ * dependency ran adapter → engine while the engine also registers adapters.
+ *
+ * This is the same correction made for `OutboxStore`: primitives owns the CONTRACT, the
+ * engine adapts to it, and a kit or a third party can implement it knowing only this file.
+ *
+ * ## Extending vs implementing
+ *
+ * `revenue`'s abstract `PaymentProvider` class now *implements* this interface and stays
+ * available for the config plumbing it provides (`config`, `defaultCurrency`). Existing
+ * adapters that `extends PaymentProvider` are unaffected. New adapters should `implement
+ * PaymentProviderPort` directly and depend only on primitives.
+ *
+ * See `spine/docs/payments-architecture.md` §3.4.1 and phase 1.
+ */
+/**
+ * How reconciliation asks a provider about a specific REFUND. The refund is identified
+ * by the original `paymentId` plus the refund's `idempotencyKey` (the value the provider
+ * deduped on); `refundRef` is the gateway refund id when the engine observed one.
+ */
+interface RefundStatusQuery {
+  paymentId: string;
+  idempotencyKey: string;
+  refundRef?: string;
+}
+interface PaymentProviderPort {
+  /** Stable lowercase provider name — the registry key. */
+  readonly name: string;
+  /**
+   * Create a provider-side intent for an amount.
+   *
+   * `command` is REQUIRED, not optional. Creating an intent is side-effecting upstream: a
+   * timed-out create can leave a live intent at the gateway with no local record, and a
+   * retry without a stable idempotency key produces a SECOND one. Making the envelope
+   * mandatory is what stops an adapter quietly omitting it.
+   */
+  createIntent(params: CreateIntentParams, command: PaymentCommandContext): Promise<ProviderIntent>;
+  /**
+   * Confirm an intent actually succeeded at the provider.
+   *
+   * A provider that CANNOT know — a stateless manual provider, for instance — must not
+   * answer `succeeded`. Reporting success for something it never observed is how a
+   * reconciliation path gets a false positive.
+   */
+  verifyPayment(intentId: string, command?: PaymentCommandContext): Promise<PaymentResult>;
+  /**
+   * Current provider-side status. Same honesty requirement as `verifyPayment`.
+   *
+   * `command` is OPTIONAL here and on `verifyPayment`: both are reads, so there is nothing
+   * to make idempotent. It is accepted purely for correlation across our logs and the
+   * provider's.
+   */
+  getStatus(intentId: string, command?: PaymentCommandContext): Promise<PaymentResult>;
+  /**
+   * Reverse a payment, in full or in part.
+   *
+   * `command` is REQUIRED and carries the idempotency key. It used to be an optional field
+   * inside `options`, which made the single most dangerous operation on this port the one
+   * where deduplication was easiest to forget. Providers whose gateway supports an
+   * idempotency key MUST forward it; those without may ignore it, and the engine still
+   * guards with its own claim and a unique index.
+   */
+  refund(paymentId: string, amount: number | null | undefined, command: PaymentCommandContext, options?: {
+    reason?: string;
+  }): Promise<RefundResult>;
+  /**
+   * Current status of a REFUND (not the payment). OPTIONAL and feature-detected: only
+   * a provider that can look a refund up implements it. Reconciliation MUST use this,
+   * never `getStatus` (which reports the PAYMENT) — asking the payment about a refund
+   * misclassifies a successful charge as a successful reversal. The query carries the
+   * original `paymentId` and the refund's `idempotencyKey` (and `refundRef` when we
+   * observed one) so the provider can find the specific reversal it deduped. A provider
+   * without this cannot be auto-reconciled — the engine then RETAINS the reservation.
+   */
+  getRefundStatus?(query: RefundStatusQuery, command?: PaymentCommandContext): Promise<PaymentResult>;
+  handleWebhook(payload: unknown, headers?: Record<string, string>): Promise<WebhookEvent>;
+  /**
+   * Reject a forged webhook. Returning `true` unconditionally is only acceptable for a
+   * provider with no webhook transport at all (manual/dev).
+   */
+  verifyWebhookSignature(payload: unknown, signature: string): boolean;
+  /** Declared capabilities. Callers gate on these rather than probing by failing. */
+  getCapabilities(): ProviderCapabilities;
+}
+/**
+ * `setDefaultCurrency` is deliberately NOT on the port.
+ *
+ * A default currency is ENGINE configuration, not part of the provider execution contract,
+ * and every `Money` already carries its own currency. Requiring the mutator would make each
+ * adapter stateful and awkward to share across accounts — the same instance cannot then
+ * serve two accounts with different defaults.
+ *
+ * Adapters that want the convenience expose it and the registry feature-detects it; the
+ * rest simply read the currency off the amount they were handed.
+ */
+interface DefaultCurrencyAware {
+  setDefaultCurrency(currency: string): void;
+}
+/**
+ * The envelope every money-changing provider command carries.
+ *
+ * Idempotency used to be supplied on `refund` alone. It belongs on every command: a
+ * retried authorize or capture double-charges just as readily as a retried refund, and the
+ * retry is usually the client's, not ours.
+ *
+ * Adapters whose gateway supports an idempotency key MUST forward it. The engine still keeps
+ * its own atomic claim/result store, because not every provider offers one and a provider's
+ * word is not a guarantee we control.
+ */
+interface PaymentCommandContext {
+  /**
+   * Caller-supplied, stable across retries of the SAME logical operation. Two different
+   * operations must never share one; one operation retried must never change it.
+   */
+  idempotencyKey: string;
+  /** Correlates this attempt across our logs, the provider's, and the audit trail. */
+  requestId: string;
+  /** Our reference for the thing being paid for — order number, invoice number. */
+  merchantReference: string;
+  /**
+   * Branch / tenant scope. OPTIONAL: a revenue engine can run unscoped
+   * (single-tenant / company-global), where there is no branch id to carry —
+   * so this is absent rather than an empty or asserted string. Scoped engines
+   * always set it; consumers that require scope must check, not cast.
+   */
+  organizationId?: string;
+  /** Cancels an in-flight command (a cashier abandoning a terminal prompt, a shutdown). */
+  signal?: AbortSignal;
+}
+/** Why a provider said no. A DECISION, distinct from an unanswered question. */
+interface PaymentDecline {
+  /** Normalized reason. Adapters map their vendor's vocabulary onto this. */
+  reason: 'insufficient_funds' | 'card_declined' | 'expired' | 'invalid_details' | 'limit_exceeded' | 'duplicate' | 'not_permitted' | 'provider_error' | 'other';
+  /** The provider's own code and message, preserved verbatim for support and reconciliation. */
+  providerCode?: string;
+  providerMessage?: string;
+  /** Whether trying again could plausibly succeed. `false` for a hard decline. */
+  retryable: boolean;
+}
+/**
+ * The outcome of a provider command. **Three-valued, and the third one is the point.**
+ *
+ * A timeout is NOT a failure. When a capture request times out, the money may well have
+ * moved — we simply did not hear back. Treating that as `declined` and retrying is the
+ * canonical way to double-charge a customer, and it is invisible until reconciliation.
+ *
+ * `unknown` also covers a provider that legitimately cannot answer: a stateless manual
+ * provider asked for the status of a payment it never stored. Today's two-valued shape
+ * forces such a provider to invent an answer, and `revenue-manual` invented `succeeded`.
+ *
+ * **The only correct response to `unknown` is to reconcile status before acting** — never
+ * a blind retry.
+ */
+type ProviderCommandResult<T> = {
+  outcome: 'confirmed';
+  value: T;
+} | {
+  outcome: 'declined';
+  error: PaymentDecline;
+} | {
+  outcome: 'unknown'; /** Whatever handle we have for asking again later. */
+  providerReference?: string;
+  /**
+   * NORMALIZED reason we do not know — never a raw exception message.
+   *
+   * Vendor errors routinely embed request URLs, tokens, account identifiers and
+   * fragments of the request body. This value is persisted on the transaction, returned
+   * to callers and read by operators, so it must be safe to store and display. The raw
+   * error belongs in a redacted diagnostic log, not here.
+   */
+  causeCode?: ProviderUnknownCause;
+};
+/** Why an outcome went unobserved. Coarse on purpose — it drives handling, not diagnosis. */
+type ProviderUnknownCause = 'timeout' | 'aborted' | 'network' | 'status_unavailable' | 'unclassified';
+/**
+ * Thrown by a provider that cannot answer a status query, rather than guessing.
+ *
+ * Classified as `unknown`. The engine's correct reaction is to consult the stored record:
+ * for a manual method there is no external money-movement authority, so the record IS the
+ * authority (see `spine/docs/payments-architecture.md` §1).
+ */
+declare class ProviderStatusUnavailableError extends Error {
+  readonly providerName: string;
+  constructor(providerName: string, message?: string);
+}
 //#endregion
-export { CreateIntentParams, PaymentIntent, PaymentIntentStatus, PaymentResult, ProviderCapabilities, RefundResult, RefundResultStatus, WebhookEvent };
+export { CreateIntentParams, DefaultCurrencyAware, PaymentCommandContext, PaymentDecline, PaymentProviderPort, PaymentResult, ProviderCapabilities, ProviderCommandResult, ProviderIntent, ProviderIntentStatus, ProviderStatusUnavailableError, ProviderUnknownCause, RefundResult, RefundResultStatus, RefundStatusQuery, WebhookEvent };

package/dist/payment-gateway.mjs

@@ -1 +1,18 @@
-export {};
+//#region src/money/payment-gateway.ts
+/**
+* Thrown by a provider that cannot answer a status query, rather than guessing.
+*
+* Classified as `unknown`. The engine's correct reaction is to consult the stored record:
+* for a manual method there is no external money-movement authority, so the record IS the
+* authority (see `spine/docs/payments-architecture.md` §1).
+*/
+var ProviderStatusUnavailableError = class extends Error {
+	providerName;
+	constructor(providerName, message) {
+		super(message ?? `provider "${providerName}" cannot report status for this payment — it holds no record of it. Read the stored transaction instead of asking the provider.`);
+		this.name = "ProviderStatusUnavailableError";
+		this.providerName = providerName;
+	}
+};
+//#endregion
+export { ProviderStatusUnavailableError };

package/dist/period.d.mts

@@ -1,15 +1,31 @@
+import { t as CivilDate } from "./timezone-tlG7ygwx.mjs";
+
 //#region src/scheduling/period.d.ts
 /**
- * A closed date range `[start, end]`. Both endpoints inclusive — consumers
- * decide whether to treat them as `[start, end)` at the query layer.
+ * A date range `[start, end]`.
+ *
+ * The endpoints are documented as INCLUSIVE for hand-built ranges, and
+ * {@link isWithin} treats them that way. Every `resolve*` function in this
+ * module instead returns a HALF-OPEN `[start, end)` range — the shape a
+ * `{ $gte: start, $lt: end }` query wants, and the only shape that tiles
+ * exactly (one period's `end` IS the next one's `start`, so no document is
+ * counted twice and none falls in a gap). Compare against a resolved range
+ * with `>= start && < end`, NOT with `isWithin`, which would accept the first
+ * instant of the following period. {@link inclusiveEnd} converts when a
+ * `$lte` call site genuinely needs the last instant.
  */
 interface DateRange {
   start: Date;
   end: Date;
 }
 /**
- * A named accounting / reporting period. At least one of the resolution fields
- * (`month`, `quarter`) should be set, or `start`/`end` for ad-hoc ranges.
+ * A named accounting / reporting period.
+ *
+ * Exactly ONE resolution shape may be present: `month`, or `quarter`, or an
+ * ad-hoc `start`+`end` pair, or none of them (meaning the whole `year`).
+ * Combining them is rejected by {@link resolvePeriod} rather than silently
+ * preferring one — two possible answers to "which instants is this?" is the
+ * input you must not widen.
  */
 interface Period {
   /** Four-digit calendar year, e.g. 2026. */
@@ -18,14 +34,46 @@ interface Period {
   month?: number;
   /** 1..4. */
   quarter?: 1 | 2 | 3 | 4;
+  /**
+   * The IANA zone this period is DEFINED in — `'Asia/Dhaka'` for a BD filing
+   * month, `'America/New_York'` for a US one. Carried on the value so a period
+   * that travels (persisted on a filing, posted in a job payload, echoed in a
+   * report header) keeps the calendar it was computed against instead of
+   * inheriting whatever the reader's default happens to be.
+   *
+   * Optional because an ad-hoc `start`/`end` period needs no zone, and because
+   * a caller may supply the zone at resolve time. {@link resolvePeriod} throws
+   * when neither is available, and throws when the two DISAGREE.
+   */
+  timezone?: string;
   /** Ad-hoc override — useful when the period spans a non-calendar boundary. */
   start?: Date;
   end?: Date;
 }
+/** Which resolution shape a {@link Period} carries. */
+type PeriodGranularity = 'year' | 'quarter' | 'month' | 'custom';
+declare class DateRangeError extends Error {
+  readonly name = "DateRangeError";
+}
+type PeriodErrorCode = /** Two resolution shapes at once (`month` + `quarter`, or either + `start`/`end`). */'AMBIGUOUS_PERIOD' /** `start` without `end`, or vice versa. */ | 'INCOMPLETE_RANGE' /** `year` / `month` / `quarter` outside its legal domain, or non-integer. */ | 'INVALID_FIELD' /** No zone on the period and none supplied by the caller. */ | 'MISSING_TIMEZONE' /** The period's own zone and the caller's zone disagree. */ | 'TIMEZONE_CONFLICT' /** A `'YYYY'` / `'YYYY-MM'` / `'YYYY-Qn'` label that could not be read. */ | 'INVALID_LABEL';
+declare class PeriodError extends Error {
+  readonly name = "PeriodError";
+  readonly code: PeriodErrorCode;
+  constructor(code: PeriodErrorCode, message: string);
+}
 declare function isDateRange(value: unknown): value is DateRange;
-/** True if `d` is inclusively within `range`. */
+/**
+ * True if `d` is inclusively within `range`.
+ *
+ * @throws DateRangeError if `d` or either endpoint is an Invalid Date.
+ */
 declare function isWithin(d: Date, range: DateRange): boolean;
-/** Range duration in milliseconds. */
+/**
+ * Range duration in milliseconds.
+ *
+ * @throws DateRangeError if either endpoint is an Invalid Date (which would
+ *   otherwise return `NaN` and propagate silently into a duration total).
+ */
 declare function rangeDurationMs(range: DateRange): number;
 /**
  * True if two half-open ranges `[start, end)` overlap.
@@ -40,7 +88,90 @@ declare function rangeDurationMs(range: DateRange): number;
  *   - `@classytic/order` booking overlap detection
  *   - `@classytic/flow` reservation window collision
  *   - promo / offer campaign window overlap checks
+ *
+ * @throws DateRangeError if either range carries an Invalid Date. For all three
+ *   consumers above, `false` is the PERMISSIVE answer — "no conflict, go ahead
+ *   and book" — so a range we cannot read must not be allowed to produce it.
  */
 declare function rangesOverlap(a: DateRange, b: DateRange): boolean;
+/**
+ * The first instant of a local calendar day, in `timezone`. DST-exact — the
+ * civil-date round-trip resolves the offset AT local midnight, not at "now".
+ */
+declare function dayStart(date: CivilDate | string, timezone: string): Date;
+/** Half-open `[start, end)` range covering one local calendar day. */
+declare function resolveDay(date: CivilDate | string, timezone: string): DateRange;
+/**
+ * Half-open `[start, end)` range covering one local calendar month.
+ * `resolveMonth(2026, 8, 'Asia/Dhaka')` →
+ * `[2026-07-31T18:00Z, 2026-08-31T18:00Z)` — the DHAKA month, six hours off
+ * the UTC one at both ends.
+ */
+declare function resolveMonth(year: number, month: number, timezone: string): DateRange;
+/** Half-open `[start, end)` range covering one local calendar quarter. */
+declare function resolveQuarter(year: number, quarter: 1 | 2 | 3 | 4, timezone: string): DateRange;
+/** Half-open `[start, end)` range covering one local calendar year. */
+declare function resolveYear(year: number, timezone: string): DateRange;
+/**
+ * Half-open range spanning two local dates, INCLUSIVE of both days — what an
+ * operator means by "1st to 31st". The half-open end is therefore the start of
+ * the day AFTER `to`.
+ */
+declare function resolveDateSpan(from: CivilDate | string, to: CivilDate | string, timezone: string): DateRange;
+/** Which resolution shape this period carries. Throws when it carries two. */
+declare function granularityOf(period: Period): PeriodGranularity;
+/**
+ * Resolve the zone a period must be read in.
+ *
+ * `period.timezone` is the zone the period was DEFINED in; `timezone` is the
+ * caller's (usually the deployment default). Supplying both with different
+ * values is a bug — one of them is describing a different calendar than the
+ * data was computed against — so it throws rather than picking a winner.
+ */
+declare function periodTimeZone(period: Period, timezone?: string): string;
+/**
+ * `Period` → half-open `[start, end)` instants, in a business timezone.
+ *
+ * The single derivation every kernel, module and host should reach for.
+ *
+ * ```ts
+ * resolvePeriod({ year: 2026, month: 8 }, 'Asia/Dhaka');
+ * // → [2026-07-31T18:00:00Z, 2026-08-31T18:00:00Z)
+ * ```
+ *
+ * An ad-hoc period (`start` + `end`) needs no zone and is returned verbatim
+ * after an Invalid-Date check.
+ */
+declare function resolvePeriod(period: Period, timezone?: string): DateRange;
+/**
+ * The LAST instant of a half-open range — `end - 1ms`.
+ *
+ * For the `$lte` call sites that predate half-open ranges. Derived from the
+ * resolved end rather than `start + 24h - 1`, so it stays DST-exact.
+ */
+declare function inclusiveEnd(range: DateRange): Date;
+/**
+ * The period an INSTANT falls in, on the local calendar.
+ *
+ * The inverse of {@link resolvePeriod}, and the answer to "which filing month
+ * is this posting in?" — asked at local midnight ±6h, `getUTCMonth()` answers a
+ * different month. The returned period carries the zone it was derived in, so
+ * a later `resolvePeriod` cannot re-read it against a different calendar.
+ */
+declare function periodOf(instant: Date, granularity: Exclude<PeriodGranularity, 'custom'>, timezone: string): Period;
+/**
+ * Parse a period LABEL — `'2026'`, `'2026-08'`, `'2026-Q3'`.
+ *
+ * Case-sensitive on the `Q` and strictly anchored: a label this cannot read
+ * throws instead of degrading to the year it could see. A `'YYYY-MM-DD'` is
+ * rejected with a pointer to {@link resolveDay}, because a `Period` has no day
+ * field and quietly reading it as its month is a 30× widening of the range.
+ */
+declare function parsePeriod(label: string, timezone?: string): Period;
+/**
+ * `Period` → its canonical label. Round-trips through {@link parsePeriod}.
+ * Throws for an ad-hoc period, which has no label — format its endpoints.
+ */
+declare function formatPeriod(period: Period): string;
 //#endregion
-export { DateRange, Period, isDateRange, isWithin, rangeDurationMs, rangesOverlap };
+export { DateRange, DateRangeError, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear };