@openlup/core 0.0.0 → 0.6.0

package/src/marketing/research/ports.ts

@@ -0,0 +1,26 @@
+import type {
+  AdminSurveyResponsesRequest,
+  AdminSurveyResponsesResponse,
+  ResearchSurveySubmitRequest,
+  ResearchSurveySubmitResponse,
+} from "./contracts.js";
+
+/** @beta */
+export interface MarketingResearchSurveyResponsesReadPort {
+  getAdminSurveyResponses(
+    request: AdminSurveyResponsesRequest,
+  ): Promise<AdminSurveyResponsesResponse>;
+}
+
+/** @beta */
+export interface MarketingResearchSurveyRequestHeaders {
+  forEach(callbackfn: (value: string, key: string) => void): void;
+}
+
+/** @beta */
+export interface MarketingResearchSurveySubmitPort {
+  submitSurveyResponse(
+    request: ResearchSurveySubmitRequest,
+    context?: { headers?: MarketingResearchSurveyRequestHeaders },
+  ): Promise<ResearchSurveySubmitResponse>;
+}

package/src/partners/index.ts

@@ -0,0 +1,4 @@
+/** @beta */
+export * from "./status.js";
+/** @beta */
+export * from "./ports.js";

package/src/partners/ports.ts

@@ -0,0 +1,18 @@
+import type {
+  PartnersB2BInquiryStatusUpdateRequest,
+  PartnersB2BInquiryStatusUpdateResponse,
+} from "./status.js";
+
+/**
+ * Persistence seam for advancing a B2B inquiry's pipeline status. The host
+ * application supplies the adapter (e.g. a DB-backed store, a CRM bridge); the
+ * core only owns this contract, not where inquiries are stored. Implementations
+ * should reject (throw) when the inquiry does not exist or the transition is
+ * not allowed, rather than resolving with a non-updated result.
+ */
+/** @beta */
+export interface PartnersB2BInquiryStatusUpdatePort {
+  updateB2BInquiryStatus(
+    request: PartnersB2BInquiryStatusUpdateRequest,
+  ): Promise<PartnersB2BInquiryStatusUpdateResponse>;
+}

package/src/partners/status.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+
+/**
+ * Lifecycle stage of a B2B / partner inquiry as it moves through a sales
+ * pipeline. Neutral, provider-agnostic vocabulary:
+ * - `new` — just received, not yet triaged;
+ * - `contacted` — outreach made, awaiting response;
+ * - `qualified` — a real, in-scope opportunity;
+ * - `disqualified` — not a fit (out of scope / spam / no intent);
+ * - `closed_won` — converted;
+ * - `closed_lost` — did not convert.
+ * The inquiry payload itself (contact details, CRM ids, PII) is NOT part of the
+ * core contract; it lives in the host application's downstream adapter.
+ */
+/** @beta */
+export const partnersB2BInquiryStatusSchema = z.enum([
+  "new",
+  "contacted",
+  "qualified",
+  "disqualified",
+  "closed_won",
+  "closed_lost",
+]);
+
+/** Request to move one inquiry (`id`) to a new pipeline `status`. */
+/** @beta */
+export const partnersB2BInquiryStatusUpdateRequestSchema = z.object({
+  id: z.string().min(1),
+  status: partnersB2BInquiryStatusSchema,
+});
+
+/** Successful status-update acknowledgement. `updated` is always `true`; a
+ * failed update is surfaced as a rejected promise / error by the port, not as
+ * `{ updated: false }`. */
+/** @beta */
+export const partnersB2BInquiryStatusUpdateResponseSchema = z.object({
+  updated: z.literal(true),
+});
+
+/** @beta */
+export type PartnersB2BInquiryStatus = z.infer<typeof partnersB2BInquiryStatusSchema>;
+/** @beta */
+export type PartnersB2BInquiryStatusUpdateRequest = z.infer<
+  typeof partnersB2BInquiryStatusUpdateRequestSchema
+>;
+/** @beta */
+export type PartnersB2BInquiryStatusUpdateResponse = z.infer<
+  typeof partnersB2BInquiryStatusUpdateResponseSchema
+>;

package/src/payment/executionBaseContracts.ts

@@ -0,0 +1,93 @@
+import type { PaymentAttemptStatus } from "./paymentControlTypes.js";
+import type { PaymentFailureHint } from "./paymentFailureTaxonomyContracts.js";
+
+/** @beta */
+export const PAYMENT_EXECUTION_MODES = ["one_time", "subscription_cycle"] as const;
+/** @beta */
+export type PaymentExecutionMode = (typeof PAYMENT_EXECUTION_MODES)[number];
+
+/** @beta */
+export const PAYMENT_EXECUTION_ATTEMPT_STATUSES = [
+  "sent_to_provider",
+  "requires_action",
+  "processing",
+] as const satisfies readonly PaymentAttemptStatus[];
+/** @beta */
+export type PaymentExecutionAttemptStatus = Extract<
+  PaymentAttemptStatus,
+  (typeof PAYMENT_EXECUTION_ATTEMPT_STATUSES)[number]
+>;
+
+/** @beta */
+export interface PaymentExecutionBaseInput {
+  idempotencyKey: string;
+  providerIdempotencyKey: string;
+  providerRequestFingerprint: string;
+  paymentIntentId: string;
+  amountMinor: number;
+  currency: string;
+  mode: PaymentExecutionMode;
+}
+
+/**
+ * A provider that refused the attempt inside the execution call itself, rather
+ * than through a later callback.
+ *
+ * Execution adapters cannot express this as an attempt status: only the control
+ * plane performs terminal transitions, so {@link PaymentExecutionAttemptStatus}
+ * is deliberately non-terminal. The adapter therefore reports the refusal as a
+ * fact and lets the caller finalize the attempt.
+ *
+ * Reporting it matters because some providers offer no second chance to learn of
+ * the failure: where a provider's callback fires only for successful payments, a
+ * synchronous decline that is not surfaced here is never reported at all, and
+ * the attempt hangs until it expires.
+ */
+/** @beta */
+export interface PaymentExecutionProviderDecline {
+  /** Provider-native code, for correlation. Low-cardinality; never a free-form message. */
+  code: string;
+  /** True when the provider states the payer's bank cannot register a reusable mandate. */
+  mandateUnsupported: boolean;
+  /**
+   * The finer refusal reason the payer's bank returned, when the provider passes
+   * one through beside {@link code}. Optional because most providers report a
+   * single code; still a code, never a message.
+   */
+  declineCode?: string;
+  /**
+   * The provider's machine-readable recommendation for what a retry should do
+   * (for example: do not retry this instrument again). Optional and advisory —
+   * nothing in the decline path branches on it yet; it is carried so a later
+   * retry policy is not forced to re-query the provider for evidence that only
+   * existed at refusal time.
+   */
+  adviceCode?: string;
+  /**
+   * What the adapter is willing to ASSERT about this refusal, already translated
+   * out of its own code vocabulary into {@link PaymentFailureHint}.
+   *
+   * Carried on the decline so a classifier can read a refusal without learning
+   * which adapter produced it: the acquirer's codes stop at the adapter that
+   * owns them, and only the neutral reading crosses into the control plane.
+   * Absent when the adapter has no opinion, which classifies as `indeterminate`
+   * rather than as a guess.
+   */
+  neutralReasonHints?: readonly PaymentFailureHint[];
+}
+
+/** @beta */
+export interface PaymentExecutionBaseResult {
+  provider: string;
+  providerAttemptId: string | null;
+  providerSessionId: string | null;
+  attemptStatus: PaymentExecutionAttemptStatus;
+  nextActionKind: string | null;
+  /**
+   * Set when the provider refused synchronously. `null` for the normal path,
+   * where the outcome arrives later via callback or polling.
+   */
+  providerDecline?: PaymentExecutionProviderDecline | null;
+  requestPayload: Record<string, unknown>;
+  responsePayload: Record<string, unknown>;
+}

package/src/payment/index.ts

@@ -0,0 +1,128 @@
+/** @beta */
+export {
+  LIVE_ATTEMPT_STATUSES,
+  PAYMENT_ATTEMPT_STATUSES,
+  PAYMENT_CONTROL_EVENT_TYPES,
+  PAYMENT_INTENT_STATUSES,
+  PAYMENT_TARGET_KINDS,
+  RETRYABLE_ATTEMPT_STATUSES,
+  isLiveAttemptStatus,
+  isRetryableAttemptStatus,
+  providerAckedButNeverConfirmed,
+} from "./paymentControlTypes.js";
+/** @beta */
+export {
+  PAYMENT_EXECUTION_ATTEMPT_STATUSES,
+  PAYMENT_EXECUTION_MODES,
+} from "./executionBaseContracts.js";
+/** @beta */
+export type {
+  CanonicalPaymentControlEvent,
+  PaymentAttemptAggregate,
+  PaymentAttemptStatus,
+  PaymentControlDecision,
+  PaymentControlDecisionKind,
+  PaymentControlEventType,
+  PaymentControlFailureReason,
+  PaymentControlResult,
+  PaymentIntentAggregate,
+  PaymentIntentStatus,
+  PaymentTargetKind,
+} from "./paymentControlTypes.js";
+/** @beta */
+export type {
+  PaymentExecutionAttemptStatus,
+  PaymentExecutionBaseInput,
+  PaymentExecutionBaseResult,
+  PaymentExecutionProviderDecline,
+  PaymentExecutionMode,
+} from "./executionBaseContracts.js";
+/** @beta */
+export {
+  PAYMENT_FAILURE_CLASSES,
+  PAYMENT_FAILURE_CUSTOMER_CAUSES,
+  PAYMENT_FAILURE_HINTS,
+  PAYMENT_RETRY_ADVICE_CODES,
+  customerCauseForFailureClass,
+  failureClassDecision,
+} from "./paymentFailureTaxonomyContracts.js";
+/** @beta */
+export type {
+  PaymentFailureClass,
+  PaymentFailureCustomerCause,
+  PaymentFailureDecision,
+  PaymentFailureEvidence,
+  PaymentFailureHint,
+  PaymentRetryAdviceCode,
+  PaymentRetryProfile,
+} from "./paymentFailureTaxonomyContracts.js";
+/** @beta */
+export {
+  PAYMENT_FAILURE_CLASSIFICATION_SOURCES,
+  SCHEME_RETRY_ATTEMPT_CEILING,
+  SCHEME_RETRY_WINDOW_DAYS,
+  classifyPaymentFailure,
+  isPaymentRetryAdviceCode,
+  withinSchemeRetryCeiling,
+} from "./paymentFailureTaxonomy.js";
+/** @beta */
+export type {
+  PaymentFailureClassification,
+  PaymentFailureClassificationOptions,
+  PaymentFailureClassificationSource,
+} from "./paymentFailureTaxonomy.js";
+/** @beta */
+export {
+  applyProviderPaymentEvent,
+  canTransitionPaymentAttempt,
+  canTransitionPaymentIntent,
+  transitionPaymentAttempt,
+  transitionPaymentIntent,
+} from "./paymentStateMachine.js";
+/** @beta */
+export {
+  buildProviderAttemptIdentity,
+  isProviderAttemptReplaySafe,
+} from "./providerAttemptIdempotency.js";
+/** @beta */
+export type {
+  ProviderAttemptIdentity,
+  ProviderAttemptIdentityInput,
+} from "./providerAttemptIdempotency.js";
+/** @beta */
+export {
+  PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS,
+  endsStoredMethodUsability,
+  expiryInstantFromMonthYear,
+  isPaymentMethodLifecycleEventKind,
+} from "./methodLifecycle.js";
+/** @beta */
+export type {
+  PaymentMethodLifecycleEvent,
+  PaymentMethodLifecycleEventKind,
+  PaymentMethodReplacementFacts,
+} from "./methodLifecycle.js";
+/** @beta */
+export type {
+  PayerContextRequirements,
+  PaymentMethodCaptureFlow,
+  PaymentMethodCaptureHandoff,
+  PaymentMethodHealthExpectations,
+  PaymentProviderCapabilityDescriptor,
+  PaymentProviderCapabilityRegistry,
+  StoredMandateSnapshot,
+  UnattendedChargeBlockReason,
+  UnattendedMandateAssessment,
+} from "./providerCapability.js";
+/** @beta */
+export { PAYMENT_RECOVERY_CAUSES, PAYMENT_RECOVERY_ACTIONS } from "./paymentRecoveryContracts.js";
+/** @beta */
+export type {
+  PaymentRecoveryCause, PaymentRecoveryAction, PaymentRecoveryOperation,
+  PaymentRecoveryMethod, PaymentRecoveryAdvice, PaymentRecoveryEvidence,
+  PaymentRecoveryCandidate, PaymentRecoveryNormalizer,
+} from "./paymentRecoveryContracts.js";
+/** @beta */
+export { derivePaymentRecoveryGuidance, availablePaymentRecoveryActions } from "./paymentRecovery.js";
+/** @beta */
+export type { PaymentRecoveryAttempt, PaymentRecoveryGuidance } from "./paymentRecovery.js";

package/src/payment/methodLifecycle.ts

@@ -0,0 +1,130 @@
+/**
+ * Neutral payment-method lifecycle vocabulary.
+ *
+ * A stored consent does not only come into existence. It is rotated, revoked
+ * and suspended, and it expires — and every rail announces those transitions in
+ * its own words. This module is the vocabulary those announcements are
+ * translated INTO, so the engine that reacts (deactivating a dead method,
+ * warning a payer before a renewal that can no longer be charged) never has to
+ * learn a rail's event names.
+ *
+ * Types and pure functions only: nothing here reads a clock, a network or a
+ * database, and no rail is named.
+ */
+
+/**
+ * Every transition a rail may report about a method it holds on file.
+ *
+ * `method_suspended` is declared but published by no rail in this deployment.
+ * It is here because the consuming branch is exhaustive over this list: a rail
+ * that starts emitting a suspension must be handled, never silently ignored.
+ */
+export const PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS = [
+  "method_registered",
+  "method_updated",
+  "method_revoked",
+  "method_expired",
+  "method_suspended",
+] as const;
+
+export type PaymentMethodLifecycleEventKind =
+  (typeof PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS)[number];
+
+/**
+ * What the rail reports about the method AFTER the transition.
+ *
+ * Deliberately three fields and no more: the label a payer recognises the
+ * method by, the trailing digits shown beside it, and the instant it stops
+ * being chargeable. ⛔ The full instrument number is never part of this
+ * contract, and an adapter that put one here would be widening a surface this
+ * type exists to keep narrow.
+ *
+ * Every field is independently nullable because rails report them
+ * independently: an alias rail may carry an expiry and no digits at all.
+ */
+export interface PaymentMethodReplacementFacts {
+  /** Scheme or rail label the payer recognises, e.g. a card network name. */
+  schemeLabel: string | null;
+  /** Trailing digits of the instrument, never more than the payer is shown. */
+  lastDigits: string | null;
+  /** ISO-8601 instant after which the method can no longer be charged. */
+  expiresAt: string | null;
+}
+
+/**
+ * One rail transition, expressed neutrally.
+ *
+ * `providerKind` and `providerMethodRef` are opaque identity, not a branch
+ * condition: together they address exactly one stored method. A consumer that
+ * compares `providerKind` against a known name re-creates the coupling this
+ * contract removes.
+ */
+export interface PaymentMethodLifecycleEvent {
+  kind: PaymentMethodLifecycleEventKind;
+  /** Registry key of the rail that reported this, used only for addressing. */
+  providerKind: string;
+  /** The rail's own reference for the stored method this transition is about. */
+  providerMethodRef: string;
+  /** The rail's identifier for this delivery, used for replay-safe writes. */
+  providerEventId: string;
+  /** ISO-8601 instant the rail reported the transition at. */
+  occurredAt: string;
+  /** Fresh facts the rail published with the transition, when it published any. */
+  replacement?: PaymentMethodReplacementFacts | null;
+}
+
+/**
+ * Whether this transition means the stored method can no longer back a charge.
+ *
+ * The single place that answers it. ⛔ A rotation (`method_updated`) is NOT a
+ * death: the same consent continues under fresh details, and treating it as one
+ * would strip a healthy subscription of the method it renews on.
+ */
+export function endsStoredMethodUsability(
+  kind: PaymentMethodLifecycleEventKind,
+): boolean {
+  return kind === "method_revoked" || kind === "method_expired" || kind === "method_suspended";
+}
+
+export function isPaymentMethodLifecycleEventKind(
+  value: unknown,
+): value is PaymentMethodLifecycleEventKind {
+  return typeof value === "string"
+    && (PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS as readonly string[]).includes(value);
+}
+
+/**
+ * The instant a month-and-year validity actually runs out.
+ *
+ * Convention, pinned here once so no adapter has to re-decide it: an
+ * instrument valid "through 06/2027" is chargeable for the whole of that month
+ * and stops at the LAST instant of it, in UTC — `2027-06-30T23:59:59.999Z`. The
+ * common alternative, the first instant of the month, would retire a method up
+ * to 31 days before the payer's own statement says it dies.
+ *
+ * UTC rather than a local zone on purpose: the value is compared against
+ * `now()` by storage and by health reads, both of which are UTC, and the
+ * one-day ambiguity a local zone would introduce is not worth a timezone
+ * dependency in a kernel.
+ *
+ * Returns null for anything that is not a plainly valid month and four-digit
+ * year, so a malformed rail payload yields "no expiry known" rather than a
+ * fabricated date.
+ */
+export function expiryInstantFromMonthYear(
+  month: number | null | undefined,
+  year: number | null | undefined,
+): string | null {
+  if (!Number.isInteger(month) || !Number.isInteger(year)) return null;
+  const monthValue = month as number;
+  const yearValue = year as number;
+  if (monthValue < 1 || monthValue > 12) return null;
+  // Below 1000 the platform's own two-digit-year remapping would silently turn
+  // 27 into 1927; a rail that abbreviates the year is refused, not guessed at.
+  if (yearValue < 1000 || yearValue > 9999) return null;
+  // Month is 1-based here and 0-based in the platform date constructor, so
+  // passing it unchanged addresses the FIRST instant of the following month;
+  // one millisecond earlier is the last instant of the expiry month itself.
+  const firstInstantAfter = Date.UTC(yearValue, monthValue, 1);
+  return new Date(firstInstantAfter - 1).toISOString();
+}

package/src/payment/paymentControlTypes.ts

@@ -0,0 +1,197 @@
+/** @beta */
+export const PAYMENT_TARGET_KINDS = ["one_time_order", "subscription_cycle"] as const;
+/** @beta */
+export type PaymentTargetKind = (typeof PAYMENT_TARGET_KINDS)[number];
+
+/** @beta */
+export const PAYMENT_INTENT_STATUSES = [
+  "created",
+  "requires_action",
+  "processing",
+  "succeeded",
+  "failed",
+  "expired",
+  "cancelled",
+  "refunded",
+  "partially_refunded",
+  "disputed",
+] as const;
+/** @beta */
+export type PaymentIntentStatus = (typeof PAYMENT_INTENT_STATUSES)[number];
+
+/** @beta */
+export const PAYMENT_ATTEMPT_STATUSES = [
+  "created",
+  "blocked_preflight",
+  "sent_to_provider",
+  "requires_action",
+  "processing",
+  "succeeded",
+  "failed",
+  "cancelled",
+  "expired",
+] as const;
+/** @beta */
+export type PaymentAttemptStatus = (typeof PAYMENT_ATTEMPT_STATUSES)[number];
+
+/**
+ * The attempt statuses that prove no provider call can still be outstanding, and
+ * so allow a fresh attempt against the same intent.
+ *
+ * This is the admission gate's own set, not a convenience list: the durable
+ * gate is written in SQL as `status NOT IN (...)` over exactly these four values,
+ * at three call sites, and `src/domains/payment/payment.test.ts` pins all three
+ * against this constant. The gate is deliberately fail-closed — every status
+ * outside this set is treated as "a call may exist" even when it is terminal —
+ * because admitting a second call against a live attempt can take the payer's
+ * money twice, while refusing one only delays a retry.
+ *
+ * @beta
+ */
+export const RETRYABLE_ATTEMPT_STATUSES = [
+  "blocked_preflight",
+  "failed",
+  "cancelled",
+  "expired",
+] as const satisfies readonly PaymentAttemptStatus[];
+
+/**
+ * The attempt statuses that describe an outcome still in the air: the request
+ * exists, and neither success nor refusal is known yet.
+ *
+ * NOT the complement of {@link RETRYABLE_ATTEMPT_STATUSES}. The complement also
+ * contains `succeeded`, which is settled rather than live, so the two predicates
+ * relate as `!isRetryableAttemptStatus(s) === isLiveAttemptStatus(s) || s ===
+ * "succeeded"` — an identity the canon test pins, because reasoning about it
+ * from the two lists alone has already gone wrong once in this repository.
+ *
+ * @beta
+ */
+export const LIVE_ATTEMPT_STATUSES = [
+  "created",
+  "sent_to_provider",
+  "requires_action",
+  "processing",
+] as const satisfies readonly PaymentAttemptStatus[];
+
+/**
+ * Whether a fresh attempt may be admitted against the intent this attempt
+ * belongs to. See {@link RETRYABLE_ATTEMPT_STATUSES}.
+ *
+ * @beta
+ */
+export function isRetryableAttemptStatus(status: string): boolean {
+  return (RETRYABLE_ATTEMPT_STATUSES as readonly string[]).includes(status);
+}
+
+/**
+ * Whether this attempt's outcome is still unresolved — the row a status poller,
+ * a reconciliation sweep or a stuck-attempt watchdog is looking for. See
+ * {@link LIVE_ATTEMPT_STATUSES}.
+ *
+ * @beta
+ */
+export function isLiveAttemptStatus(status: string): boolean {
+  return (LIVE_ATTEMPT_STATUSES as readonly string[]).includes(status);
+}
+
+/**
+ * Whether the request demonstrably reached the provider and nothing came back.
+ *
+ * The single status that says so is `sent_to_provider`, and it exists because the
+ * alternatives both lie. `created` claims the provider was never contacted, so a
+ * caller is free to contact it again. `processing` claims money is moving, which
+ * is what a payer is then told — and that exact claim was made about intents no
+ * issuer had ever been asked about (recorded in the deployment payment-status canon).
+ *
+ * Reaching for this predicate instead of comparing the string is the point: the
+ * mapping that produced the wrong verdict lived in an adapter that could not see
+ * the reasoning, which sat unexported in a file beside it.
+ *
+ * @beta
+ */
+export function providerAckedButNeverConfirmed(status: string): boolean {
+  return status === "sent_to_provider";
+}
+
+/** @beta */
+export const PAYMENT_CONTROL_EVENT_TYPES = [
+  "payment.requires_action",
+  "payment.succeeded",
+  "payment.failed",
+  "payment.refunded",
+  "payment.disputed",
+] as const;
+/** @beta */
+export type PaymentControlEventType = (typeof PAYMENT_CONTROL_EVENT_TYPES)[number];
+
+/** @beta */
+export interface PaymentIntentAggregate {
+  id: string;
+  targetKind: PaymentTargetKind;
+  targetId: string;
+  status: PaymentIntentStatus;
+  amountMinor: number;
+  currency: string;
+  activeAttemptId: string | null;
+  updatedAt: string;
+  providerPaymentId?: string | null;
+  failureReason?: string | null;
+}
+
+/** @beta */
+export interface PaymentAttemptAggregate {
+  id: string;
+  intentId: string;
+  status: PaymentAttemptStatus;
+  provider: string;
+  providerAttemptId: string | null;
+  amountMinor: number;
+  currency: string;
+  idempotencyKey: string;
+  updatedAt: string;
+  nextActionKind?: string | null;
+  failureReason?: string | null;
+}
+
+/** @beta */
+export interface CanonicalPaymentControlEvent {
+  provider: string;
+  providerEventId: string;
+  eventType: PaymentControlEventType;
+  providerPaymentId: string;
+  amountMinor?: number;
+  currency?: string;
+  occurredAt: string;
+  failureReason?: string;
+  nextActionKind?: string;
+  rawPayload: Record<string, unknown>;
+}
+
+/** @beta */
+export type PaymentControlDecisionKind =
+  | "state_changed"
+  | "noop"
+  | "late_success_recovered";
+
+/** @beta */
+export interface PaymentControlDecision {
+  kind: PaymentControlDecisionKind;
+  reason: string;
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+}
+
+/** @beta */
+export type PaymentControlFailureReason =
+  | "amount_mismatch"
+  | "currency_mismatch"
+  | "invalid_transition"
+  | "refund_requires_success"
+  | "terminal_intent"
+  | "wrong_attempt";
+
+/** @beta */
+export type PaymentControlResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; reason: PaymentControlFailureReason; message: string };