cabloy 5.1.122 → 5.1.124

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentSession.ts

@@ -0,0 +1,278 @@
+import type { TableIdentity } from 'table-identity';
+
+import { BeanBase } from 'vona';
+import { Service } from 'vona-module-a-bean';
+import { Core } from 'vona-module-a-core';
+
+import type { EntityPaymentSession } from '../entity/paymentSession.tsx';
+import type {
+  IPayProviderCapabilities,
+  IPayProviderPaymentSnapshot,
+  TypePaymentNextAction,
+  TypePaymentSessionState,
+} from '../types/payment.ts';
+import type { IDecoratorPaySceneOptions } from '../types/payScene.ts';
+
+export interface IPaymentSessionCreateCommand {
+  userId: TableIdentity;
+  payScene: string;
+  businessReference: string;
+  amountMinor: number;
+  currency: string;
+  correlationId: string;
+}
+
+@Service()
+export class ServicePaymentSession extends BeanBase {
+  async create(command: IPaymentSessionCreateCommand): Promise<EntityPaymentSession> {
+    const sceneOptions = this.bean.payScene.getOptions(command.payScene as never);
+    this._assertCreateCommand(command, sceneOptions);
+    const provider = await this.bean.payScene.resolveProvider(command.payScene as never, command);
+    this._assertProviderCapabilities(provider.capabilities, sceneOptions);
+    const sessionExpiresIn = sceneOptions.sessionExpiresIn;
+    if (!Number.isSafeInteger(sessionExpiresIn) || !sessionExpiresIn || sessionExpiresIn < 0) {
+      this.app.throw(500, 'payment scene has an invalid session expiration');
+    }
+    return await this.scope.model.paymentSession.insert({
+      ...command,
+      providerName: provider.providerName,
+      clientName: provider.clientName,
+      environment: provider.environment,
+      expiresAt: new Date(Date.now() + sessionExpiresIn),
+      state: 'created',
+    });
+  }
+
+  private _assertCreateCommand(
+    command: IPaymentSessionCreateCommand,
+    sceneOptions: IDecoratorPaySceneOptions,
+  ) {
+    if (!Number.isSafeInteger(command.amountMinor) || command.amountMinor < 0) {
+      this.app.throw(422, 'payment amount is invalid');
+    }
+    if (sceneOptions.currencies && !sceneOptions.currencies.includes(command.currency)) {
+      this.app.throw(422, 'payment currency is not allowed by the payment scene');
+    }
+  }
+
+  private _assertProviderCapabilities(
+    capabilities: IPayProviderCapabilities,
+    sceneOptions: IDecoratorPaySceneOptions,
+  ) {
+    if (
+      (sceneOptions.captureMode === 'automatic' && !capabilities.automaticCapture) ||
+      (sceneOptions.captureMode === 'manual' && !capabilities.manualCapture)
+    ) {
+      this.app.throw(500, 'payment scene capture mode is not supported by the payment provider');
+    }
+    if (sceneOptions.refund?.enabled && !capabilities.refunds) {
+      this.app.throw(500, 'payment scene refunds are not supported by the payment provider');
+    }
+    if (sceneOptions.refund?.allowPartial && !capabilities.partialRefunds) {
+      this.app.throw(
+        500,
+        'payment scene partial refunds are not supported by the payment provider',
+      );
+    }
+  }
+
+  async start(paymentSessionId: TableIdentity): Promise<EntityPaymentSession> {
+    const session = await this.beginStart(paymentSessionId);
+    const { provider, clientOptions } = this.bean.payProvider.resolveByName(
+      session.providerName,
+      session.clientName,
+    );
+    if (clientOptions.environment !== session.environment) {
+      this.app.throw(500, 'payment session provider environment is inconsistent');
+    }
+    const snapshot = await provider.startPayment(
+      {
+        paymentSessionId: session.id,
+        businessReference: session.businessReference,
+        idempotencyKey: `${session.correlationId}:start`,
+        amountMinor: session.amountMinor,
+        currency: session.currency,
+        providerOrderId: session.providerOrderId,
+      },
+      clientOptions,
+    );
+    if (isTerminalPaymentSnapshot(snapshot)) {
+      return await this.settleStartSnapshot(session.id, snapshot);
+    }
+    return await this.transition(session.id, snapshot.state, {
+      nextAction: snapshot.nextAction,
+      providerPaymentId: snapshot.providerPaymentId,
+      providerOrderId: snapshot.providerOrderId,
+      providerCaptureId: snapshot.providerCaptureId,
+      source: 'paymentSession.startProvider',
+    });
+  }
+
+  @Core.transaction()
+  async beginStart(paymentSessionId: TableIdentity): Promise<EntityPaymentSession> {
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+    if (session.state !== 'created') this.app.throw(409, 'payment session is not ready to start');
+    if (session.expiresAt <= new Date()) this.app.throw(409, 'payment session is expired');
+    return await this.transition(session.id, 'starting', { source: 'paymentSession.start' });
+  }
+
+  @Core.transaction()
+  async settleStartSnapshot(
+    paymentSessionId: TableIdentity,
+    snapshot: IPayProviderPaymentSnapshot & {
+      state: 'succeeded' | 'failed' | 'cancelled';
+    },
+  ): Promise<EntityPaymentSession> {
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+    if (session.state !== 'starting') this.app.throw(409, 'payment session is not starting');
+    const finalizedAt = new Date();
+    await this.scope.model.paymentSession.updateById(session.id, {
+      state: snapshot.state,
+      nextAction: snapshot.nextAction,
+      providerPaymentId: snapshot.providerPaymentId,
+      providerOrderId: snapshot.providerOrderId,
+      providerCaptureId: snapshot.providerCaptureId,
+      finalizedAt,
+    });
+    await this.scope.model.paymentAudit.insert({
+      paymentSessionId: session.id,
+      fromState: session.state,
+      toState: snapshot.state,
+      correlationId: session.correlationId,
+      source: 'paymentSession.startProvider',
+      occurredAt: finalizedAt,
+    });
+    await this.scope.service.outbox.enqueue(session.id, 'payment.outcome.v1', {
+      eventId: `${session.correlationId}:start`,
+      paymentSessionId: session.id,
+      businessReference: session.businessReference,
+      providerName: session.providerName,
+      state: snapshot.state,
+      providerCaptureId: snapshot.providerCaptureId,
+      amountMinor: session.amountMinor,
+      currency: session.currency,
+    });
+    return { ...session, ...snapshot, state: snapshot.state, finalizedAt };
+  }
+
+  @Core.transaction()
+  async transitionFromWebhook(
+    paymentSessionId: TableIdentity,
+    options: {
+      state: Extract<TypePaymentSessionState, 'succeeded' | 'failed' | 'cancelled'>;
+      providerPaymentId?: string;
+      providerCaptureId?: string;
+      webhookInboxId: TableIdentity;
+    },
+  ): Promise<{
+    session: EntityPaymentSession;
+    changed: boolean;
+    ignoredReason?: string;
+  }> {
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+    if (session.state === options.state) {
+      this._assertWebhookProviderFactsConsistent(session, options);
+      return { session, changed: false };
+    }
+    if (['succeeded', 'failed', 'cancelled', 'expired'].includes(session.state)) {
+      return {
+        session,
+        changed: false,
+        ignoredReason: `terminal payment state ${options.state} ignored after ${session.state}`,
+      };
+    }
+    if (session.expiresAt <= new Date()) {
+      this.app.throw(409, 'payment session is expired');
+    }
+    const finalizedAt = new Date();
+    await this.scope.model.paymentSession.updateById(session.id, {
+      state: options.state,
+      providerPaymentId: options.providerPaymentId,
+      providerCaptureId: options.providerCaptureId,
+      finalizedAt,
+    });
+    await this.scope.model.paymentAudit.insert({
+      paymentSessionId: session.id,
+      webhookInboxId: options.webhookInboxId,
+      fromState: session.state,
+      toState: options.state,
+      correlationId: session.correlationId,
+      source: 'webhook',
+      occurredAt: finalizedAt,
+    });
+    return {
+      session: { ...session, ...options, state: options.state, finalizedAt },
+      changed: true,
+    };
+  }
+
+  private _assertWebhookProviderFactsConsistent(
+    session: EntityPaymentSession,
+    options: {
+      providerPaymentId?: string;
+      providerCaptureId?: string;
+    },
+  ) {
+    if (
+      (session.providerPaymentId &&
+        options.providerPaymentId &&
+        session.providerPaymentId !== options.providerPaymentId) ||
+      (session.providerCaptureId &&
+        options.providerCaptureId &&
+        session.providerCaptureId !== options.providerCaptureId)
+    ) {
+      this.app.throw(409, 'payment webhook provider facts conflict with the payment session');
+    }
+  }
+
+  @Core.transaction()
+  async transition(
+    paymentSessionId: TableIdentity,
+    state: TypePaymentSessionState,
+    options?: {
+      nextAction?: TypePaymentNextAction;
+      providerPaymentId?: string;
+      providerOrderId?: string;
+      providerCaptureId?: string;
+      source?: string;
+    },
+  ): Promise<EntityPaymentSession> {
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+    if (session.state === state) return session;
+    if (['succeeded', 'failed', 'cancelled', 'expired'].includes(session.state)) {
+      this.app.throw(409, 'payment session is already finalized');
+    }
+    const finalizedAt = ['succeeded', 'failed', 'cancelled', 'expired'].includes(state)
+      ? new Date()
+      : undefined;
+    await this.scope.model.paymentSession.updateById(session.id, {
+      state,
+      nextAction: options?.nextAction,
+      providerPaymentId: options?.providerPaymentId,
+      providerOrderId: options?.providerOrderId,
+      providerCaptureId: options?.providerCaptureId,
+      finalizedAt,
+    });
+    await this.scope.model.paymentAudit.insert({
+      paymentSessionId: session.id,
+      fromState: session.state,
+      toState: state,
+      correlationId: session.correlationId,
+      source: options?.source ?? 'paymentSession',
+      occurredAt: new Date(),
+    });
+    return { ...session, ...options, state, finalizedAt };
+  }
+}
+
+function isTerminalPaymentSnapshot(
+  snapshot: IPayProviderPaymentSnapshot,
+): snapshot is IPayProviderPaymentSnapshot & {
+  state: 'succeeded' | 'failed' | 'cancelled';
+} {
+  return ['succeeded', 'failed', 'cancelled'].includes(snapshot.state);
+}

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/providerOperation.ts

@@ -0,0 +1,5 @@
+import { BeanBase } from 'vona';
+import { Service } from 'vona-module-a-bean';
+
+@Service()
+export class ServiceProviderOperation extends BeanBase {}

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/webhook.ts

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { BeanBase } from 'vona';
+import { Service } from 'vona-module-a-bean';
+import { Core } from 'vona-module-a-core';
+
+import type {
+  IPayProviderVerifiedWebhook,
+  IPaymentOutcomeEvent,
+  TypePaymentSessionState,
+} from '../types/payment.ts';
+
+export interface IWebhookReceiveCommand {
+  providerName: string;
+  clientName: string;
+  environment: 'sandbox' | 'live';
+  rawBody?: string;
+  verified: IPayProviderVerifiedWebhook;
+}
+
+@Service()
+export class ServiceWebhook extends BeanBase {
+  async receive(command: IWebhookReceiveCommand) {
+    return await this.scope.redlock.lock(
+      `pay.webhook.${command.providerName}.${command.clientName}.${command.environment}.${command.verified.eventId}`,
+      async () => await this.receiveLocked(command),
+    );
+  }
+
+  @Core.transaction()
+  async receiveLocked(command: IWebhookReceiveCommand) {
+    const payment = command.verified.payment;
+    const paymentSessionId = command.verified.paymentSessionId;
+    const amountMinor = command.verified.summary?.amountMinor;
+    const currency = command.verified.summary?.currency;
+    const paymentState = payment?.state as
+      | Extract<TypePaymentSessionState, 'succeeded' | 'failed' | 'cancelled'>
+      | undefined;
+    if (
+      !payment ||
+      !paymentSessionId ||
+      !['succeeded', 'failed', 'cancelled'].includes(paymentState ?? '') ||
+      typeof amountMinor !== 'number' ||
+      !Number.isInteger(amountMinor) ||
+      amountMinor < 0 ||
+      typeof currency !== 'string' ||
+      currency.length !== 3
+    ) {
+      this.app.throw(400, 'payment webhook is incomplete');
+    }
+
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+    if (
+      session.providerName !== command.providerName ||
+      session.clientName !== command.clientName ||
+      session.environment !== command.environment ||
+      session.amountMinor !== amountMinor ||
+      session.currency !== currency
+    ) {
+      this.app.throw(409, 'payment webhook conflicts with the payment session');
+    }
+
+    const payloadHash = createHash('sha256')
+      .update(command.rawBody ?? JSON.stringify(command.verified))
+      .digest('hex');
+    const existing = await this.scope.model.webhookInbox.getForUpdate({
+      providerName: command.providerName,
+      clientName: command.clientName,
+      environment: command.environment,
+      providerEventId: command.verified.eventId,
+    });
+    if (existing) {
+      if (existing.payloadHash !== payloadHash) {
+        this.app.throw(409, 'payment webhook event conflicts with a prior payload');
+      }
+      return existing;
+    }
+
+    const inbox = await this.scope.model.webhookInbox.insert({
+      providerName: command.providerName,
+      clientName: command.clientName,
+      environment: command.environment,
+      providerEventId: command.verified.eventId,
+      eventType: command.verified.eventType,
+      paymentSessionId: session.id,
+      paymentState: paymentState!,
+      amountMinor,
+      currency,
+      providerCaptureId: payment.providerCaptureId,
+      payloadHash,
+      state: 'received',
+      retryCount: 0,
+    });
+
+    const transition = await this.scope.service.paymentSession.transitionFromWebhook(session.id, {
+      state: paymentState!,
+      providerPaymentId: payment.providerPaymentId,
+      providerCaptureId: payment.providerCaptureId,
+      webhookInboxId: inbox.id,
+    });
+    if (transition.changed) {
+      const event: IPaymentOutcomeEvent = {
+        eventId: command.verified.eventId,
+        paymentSessionId: session.id,
+        businessReference: session.businessReference,
+        providerName: session.providerName,
+        state: paymentState!,
+        providerCaptureId: payment.providerCaptureId,
+        amountMinor,
+        currency,
+      };
+      await this.scope.service.outbox.enqueue(session.id, 'payment.outcome.v1', { ...event });
+    }
+    const processedAt = new Date();
+    await this.scope.model.webhookInbox.updateById(inbox.id, {
+      state: 'processed',
+      processedAt,
+      errorSummary: transition.ignoredReason,
+    });
+    return {
+      ...inbox,
+      state: 'processed' as const,
+      processedAt,
+      errorSummary: transition.ignoredReason,
+    };
+  }
+}

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './payment.ts';
+export * from './payProvider.ts';
+export * from './payScene.ts';

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/types/payProvider.ts

@@ -0,0 +1,74 @@
+import type { OmitNever } from 'vona';
+import type { ServiceOnion, TypeOnionOptionsEnableSimple } from 'vona-module-a-onion';
+
+import type { IPayProviderCapabilities, IPayProviderExecute } from './payment.ts';
+
+export interface IPayProviderRecord {}
+
+export interface IPayProviderClientRecord {
+  default: never;
+}
+
+export interface IPayProviderClientOptions {
+  environment: 'sandbox' | 'live';
+  capabilities: IPayProviderCapabilities;
+  secretCredential: unknown;
+  secretWebhook?: unknown;
+  merchantReference?: string;
+}
+
+export type TypePayProviderClientOptions<T> =
+  T extends IDecoratorPayProviderOptions<any, infer O> ? O : never;
+
+export type TypePayProviderClientName<T> =
+  T extends IDecoratorPayProviderOptions<infer R, any> ? keyof R & string : never;
+
+export type TypePayProviderClientOptionsInput<T extends IPayProviderClientOptions> = Omit<
+  T,
+  'capabilities'
+> &
+  Partial<Pick<T, 'capabilities'>>;
+
+export interface IDecoratorPayProviderOptions<
+  R extends IPayProviderClientRecord = IPayProviderClientRecord,
+  T extends IPayProviderClientOptions = IPayProviderClientOptions,
+> extends TypeOnionOptionsEnableSimple {
+  base?: Partial<T>;
+  clients?: {
+    [K in keyof R]?: R[K] extends undefined ? TypePayProviderClientOptionsInput<T> : R[K];
+  };
+}
+
+export type TypePayProviderOptionsByName<N extends keyof IPayProviderRecord> =
+  IPayProviderRecord[N];
+
+export type TypePayProviderClientOptionsByName<N extends keyof IPayProviderRecord> =
+  TypePayProviderOptionsByName<N> extends IDecoratorPayProviderOptions<any, any>
+    ? TypePayProviderClientOptions<TypePayProviderOptionsByName<N>>
+    : never;
+
+export type TypePayProviderClientNameByName<N extends keyof IPayProviderRecord> =
+  TypePayProviderOptionsByName<N> extends IDecoratorPayProviderOptions<any, any>
+    ? TypePayProviderClientName<TypePayProviderOptionsByName<N>>
+    : never;
+
+export type TypePayProviderExecuteByName<N extends keyof IPayProviderRecord> =
+  TypePayProviderOptionsByName<N> extends IDecoratorPayProviderOptions<any, any>
+    ? IPayProviderExecute<TypePayProviderClientOptionsByName<N>>
+    : never;
+
+declare module 'vona-module-a-onion' {
+  export interface BeanOnion {
+    payProvider: ServiceOnion<IPayProviderRecord>;
+  }
+}
+
+declare module 'vona' {
+  export interface ConfigOnions {
+    payProvider: OmitNever<IPayProviderRecord>;
+  }
+
+  export interface IBeanSceneRecord {
+    payProvider: never;
+  }
+}

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/types/payScene.ts

@@ -0,0 +1,63 @@
+import type { TableIdentity } from 'table-identity';
+import type { OmitNever, VonaContext } from 'vona';
+import type { ServiceOnion } from 'vona-module-a-onion';
+
+import type { IPaymentOutcomeEvent } from './payment.ts';
+import type { IPayProviderRecord } from './payProvider.ts';
+
+export interface IPaySceneExecute {
+  onPaymentOutcome(event: IPaymentOutcomeEvent): Promise<void>;
+}
+
+export interface IPaySceneRecord {}
+
+export type TypePaySceneExecuteByName<N extends keyof IPaySceneRecord> =
+  IPaySceneRecord[N] extends IDecoratorPaySceneOptions ? IPaySceneExecute : never;
+
+export interface IPaySceneProviderCandidate {
+  key: string;
+  providerName: keyof IPayProviderRecord;
+  clientName: string;
+}
+
+export interface IPaySceneResolveProviderInput {
+  payScene: keyof IPaySceneRecord;
+  userId: TableIdentity;
+  businessReference: string;
+  amountMinor: number;
+  currency: string;
+  providers: readonly IPaySceneProviderCandidate[];
+}
+
+export type TypePaySceneResolveProvider = (
+  ctx: VonaContext,
+  input: IPaySceneResolveProviderInput,
+) => string | Promise<string>;
+
+export interface IDecoratorPaySceneOptions {
+  providers?: readonly IPaySceneProviderCandidate[];
+  resolveProvider?: TypePaySceneResolveProvider;
+  currencies?: readonly string[];
+  captureMode?: 'automatic' | 'manual';
+  sessionExpiresIn?: number;
+  refund?: {
+    enabled?: boolean;
+    allowPartial?: boolean;
+  };
+}
+
+declare module 'vona-module-a-onion' {
+  export interface BeanOnion {
+    payScene: ServiceOnion<IPaySceneRecord>;
+  }
+}
+
+declare module 'vona' {
+  export interface ConfigOnions {
+    payScene: OmitNever<IPaySceneRecord>;
+  }
+
+  export interface IBeanSceneRecord {
+    payScene: never;
+  }
+}