cabloy 5.1.122 → 5.1.124

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

@@ -0,0 +1,151 @@
+import type { TableIdentity } from 'table-identity';
+
+import type { IPayProviderClientOptions } from './payProvider.ts';
+
+export type TypePayEnvironment = 'sandbox' | 'live';
+
+export type TypePaymentSessionState =
+  | 'created'
+  | 'starting'
+  | 'requires_action'
+  | 'processing'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+  | 'expired';
+
+export type TypeRefundOperationState =
+  | 'created'
+  | 'submitting'
+  | 'pending'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled';
+
+export type TypeProviderOperationKind = 'start' | 'confirm' | 'query' | 'refund';
+
+export type TypeProviderOperationState =
+  | 'created'
+  | 'claimed'
+  | 'submitted'
+  | 'succeeded'
+  | 'failed'
+  | 'reconciliation_required';
+
+export type TypeOutboxEventState = 'pending' | 'claimed' | 'dispatched' | 'failed';
+
+export type TypePaymentNextAction =
+  | { kind: 'redirect'; url: string }
+  | { kind: 'embedded'; clientToken: string; publishableConfig?: Record<string, string> }
+  | { kind: 'pending'; retryAfterSeconds?: number }
+  | { kind: 'completed' };
+
+export interface IPayMoney {
+  amountMinor: number;
+  currency: string;
+}
+
+export interface IPayProviderCapabilities {
+  redirectCheckout: boolean;
+  embeddedCheckout: boolean;
+  automaticCapture: boolean;
+  manualCapture: boolean;
+  refunds: boolean;
+  partialRefunds: boolean;
+  webhooks: boolean;
+}
+
+export interface IPayProviderPaymentInput extends IPayMoney {
+  paymentSessionId: TableIdentity;
+  businessReference: string;
+  idempotencyKey: string;
+  returnUrl?: string;
+  cancelUrl?: string;
+  providerOrderId?: string;
+}
+
+export interface IPayProviderRefundInput extends IPayMoney {
+  paymentSessionId: TableIdentity;
+  refundOperationId: TableIdentity;
+  businessReference: string;
+  idempotencyKey: string;
+  providerCaptureId: string;
+}
+
+export interface IPayProviderPaymentSnapshot {
+  state: Extract<
+    TypePaymentSessionState,
+    'requires_action' | 'processing' | 'succeeded' | 'failed' | 'cancelled'
+  >;
+  providerPaymentId?: string;
+  providerOrderId?: string;
+  providerCaptureId?: string;
+  nextAction?: TypePaymentNextAction;
+  summary?: Record<string, string | number | boolean | null>;
+}
+
+export interface IPayProviderRefundSnapshot {
+  state: Extract<TypeRefundOperationState, 'pending' | 'succeeded' | 'failed' | 'cancelled'>;
+  providerRefundId?: string;
+  summary?: Record<string, string | number | boolean | null>;
+}
+
+export interface IPayProviderWebhookInput {
+  rawBody?: string;
+  body: unknown;
+  headers: Record<string, string | string[] | undefined>;
+}
+
+export interface IPayProviderVerifiedWebhook {
+  eventId: string;
+  eventType: string;
+  paymentSessionId?: TableIdentity;
+  refundOperationId?: TableIdentity;
+  payment?: IPayProviderPaymentSnapshot;
+  refund?: IPayProviderRefundSnapshot;
+  summary?: Record<string, string | number | boolean | null>;
+}
+
+export interface IPayProviderExecute<
+  TClientOptions extends IPayProviderClientOptions = IPayProviderClientOptions,
+> {
+  startPayment(
+    input: IPayProviderPaymentInput,
+    clientOptions: TClientOptions,
+  ): Promise<IPayProviderPaymentSnapshot>;
+  queryPayment(
+    input: IPayProviderPaymentInput,
+    clientOptions: TClientOptions,
+  ): Promise<IPayProviderPaymentSnapshot>;
+  createRefund(
+    input: IPayProviderRefundInput,
+    clientOptions: TClientOptions,
+  ): Promise<IPayProviderRefundSnapshot>;
+  queryRefund?(
+    input: IPayProviderRefundInput,
+    clientOptions: TClientOptions,
+  ): Promise<IPayProviderRefundSnapshot>;
+  verifyWebhook(
+    input: IPayProviderWebhookInput,
+    clientOptions: TClientOptions,
+  ): Promise<IPayProviderVerifiedWebhook>;
+}
+
+export interface IPaymentOutcomeEvent extends IPayMoney {
+  eventId: string;
+  paymentSessionId: TableIdentity;
+  businessReference: string;
+  providerName: string;
+  state: Extract<TypePaymentSessionState, 'succeeded' | 'failed' | 'cancelled'>;
+  providerCaptureId?: string;
+}
+
+export interface IRefundOutcomeEvent extends IPayMoney {
+  eventId: string;
+  paymentSessionId: TableIdentity;
+  refundOperationId: TableIdentity;
+  businessReference: string;
+  providerName: string;
+  state: Extract<TypeRefundOperationState, 'succeeded' | 'failed' | 'cancelled'>;
+  providerRefundId?: string;
+}

package/vona/src/suite-vendor/a-pay/modules/a-pay/test/outbox.test.ts

@@ -0,0 +1,209 @@
+import assert from 'node:assert';
+import { randomUUID } from 'node:crypto';
+import { describe, it } from 'node:test';
+import { app } from 'vona-mock';
+
+import type { IPaymentOutcomeEvent } from '../src/types/payment.ts';
+
+interface IFixture {
+  userId?: number;
+  paymentSessionId?: number;
+  outboxEventIds: number[];
+}
+
+async function createFixture(suffix: string): Promise<IFixture> {
+  const scope = app.scope('a-pay');
+  const user = await app.bean.user.register({ name: `pay-outbox-${suffix}` }, true);
+  const session = await scope.service.paymentSession.create({
+    userId: user.id,
+    payScene: 'commerce-payment:commerceOrder',
+    businessReference: `business-${suffix}`,
+    amountMinor: 1299,
+    currency: 'USD',
+    correlationId: `payment-${suffix}`,
+  });
+  return { userId: user.id as number, paymentSessionId: session.id as number, outboxEventIds: [] };
+}
+
+function createOutcomePayload(fixture: IFixture): IPaymentOutcomeEvent {
+  return {
+    eventId: randomUUID(),
+    paymentSessionId: fixture.paymentSessionId!,
+    businessReference: 'outbox-test',
+    providerName: 'test-provider',
+    state: 'succeeded',
+    amountMinor: 1299,
+    currency: 'USD',
+  };
+}
+
+async function insertOutbox(
+  fixture: IFixture,
+  overrides?: Partial<{
+    eventType: 'payment.outcome.v1';
+    state: 'pending' | 'claimed';
+    attemptCount: number;
+    nextAttemptAt: Date;
+    claimToken: string;
+    claimedAt: Date;
+    claimExpiresAt: Date;
+  }>,
+) {
+  const event = await app.scope('a-pay').model.outboxEvent.insert({
+    eventType: overrides?.eventType ?? 'payment.outcome.v1',
+    paymentSessionId: fixture.paymentSessionId!,
+    payload: createOutcomePayload(fixture),
+    state: overrides?.state ?? 'pending',
+    attemptCount: overrides?.attemptCount ?? 0,
+    nextAttemptAt: overrides?.nextAttemptAt ?? new Date(Date.now() - 1_000),
+    claimToken: overrides?.claimToken,
+    claimedAt: overrides?.claimedAt,
+    claimExpiresAt: overrides?.claimExpiresAt,
+  });
+  fixture.outboxEventIds.push(event.id as number);
+  return event;
+}
+
+async function cleanup(fixture: IFixture) {
+  const scope = app.scope('a-pay');
+  for (const id of fixture.outboxEventIds) await scope.model.outboxEvent.delete({ id });
+  if (fixture.paymentSessionId !== undefined) {
+    await scope.model.paymentAudit.delete({ paymentSessionId: fixture.paymentSessionId });
+    await scope.model.webhookInbox.delete({ paymentSessionId: fixture.paymentSessionId });
+    await scope.model.paymentSession.delete({ id: fixture.paymentSessionId });
+  }
+  if (fixture.userId !== undefined) {
+    await app.scope('home-user').model.roleUser.delete({ userId: fixture.userId });
+    await app.bean.user.removeById(fixture.userId);
+  }
+}
+
+describe('outbox.test.ts', { concurrency: false }, () => {
+  it('claims, backs off, and exhausts durable delivery attempts', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const fixture = await createFixture(randomUUID().slice(0, 12));
+      try {
+        const event = await insertOutbox(fixture);
+        const scope = app.scope('a-pay');
+        const first = await scope.service.outbox.claim(event.id);
+        assert.equal(first?.attemptCount, 1);
+        assert.ok(first?.claimToken);
+        const releaseStart = Date.now();
+        await scope.service.outbox.release(
+          event.id,
+          first!.claimToken!,
+          new Error('first failure'),
+        );
+        let persisted = await scope.model.outboxEvent.getById(event.id);
+        assert.equal(persisted?.state, 'pending');
+        assert.equal(persisted?.errorSummary, 'first failure');
+        assert.ok((persisted?.nextAttemptAt?.getTime() ?? 0) >= releaseStart + 900);
+        assert.equal(await scope.service.outbox.claim(event.id), undefined);
+        await scope.model.outboxEvent.updateById(event.id, {
+          nextAttemptAt: new Date(Date.now() - 1),
+        });
+        const second = await scope.service.outbox.claim(event.id);
+        assert.equal(second?.attemptCount, 2);
+        const secondReleaseStart = Date.now();
+        await scope.service.outbox.release(
+          event.id,
+          second!.claimToken!,
+          new Error('second failure'),
+        );
+        persisted = await scope.model.outboxEvent.getById(event.id);
+        assert.ok((persisted?.nextAttemptAt?.getTime() ?? 0) >= secondReleaseStart + 1_900);
+
+        const exhausted = await insertOutbox(fixture, { attemptCount: 10 });
+        assert.equal(await scope.service.outbox.claim(exhausted.id), undefined);
+        assert.equal((await scope.model.outboxEvent.getById(exhausted.id))?.state, 'failed');
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
+  it('retries a dispatch when the persisted payment scene is unavailable', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const fixture = await createFixture(randomUUID().slice(0, 12));
+      try {
+        const scope = app.scope('a-pay');
+        await scope.model.paymentSession.updateById(fixture.paymentSessionId!, {
+          payScene: 'test-payment',
+        });
+        const event = await insertOutbox(fixture);
+        await scope.queue.outboxDispatch.pushAsync({ outboxEventId: event.id });
+        const persisted = await scope.model.outboxEvent.getById(event.id);
+        assert.equal(persisted?.state, 'pending');
+        assert.equal(persisted?.attemptCount, 1);
+        assert.match(persisted?.errorSummary ?? '', /payment scene not found/);
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
+  it('reclaims expired leases and fences stale claim tokens', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const fixture = await createFixture(randomUUID().slice(0, 12));
+      try {
+        const event = await insertOutbox(fixture);
+        const scope = app.scope('a-pay');
+        const first = await scope.service.outbox.claim(event.id);
+        await scope.model.outboxEvent.updateById(event.id, {
+          claimExpiresAt: new Date(Date.now() - 1),
+        });
+        const second = await scope.service.outbox.claim(event.id);
+        assert.ok(second?.claimToken);
+        assert.notEqual(second?.claimToken, first?.claimToken);
+        assert.equal(second?.attemptCount, 2);
+        assert.equal(
+          await scope.service.outbox.markDispatched(event.id, first!.claimToken!),
+          undefined,
+        );
+        assert.equal(
+          await scope.service.outbox.release(event.id, first!.claimToken!, new Error('stale')),
+          undefined,
+        );
+        assert.equal(
+          (await scope.model.outboxEvent.getById(event.id))?.claimToken,
+          second?.claimToken,
+        );
+        await scope.service.outbox.markDispatched(event.id, second!.claimToken!);
+        const persisted = await scope.model.outboxEvent.getById(event.id);
+        assert.equal(persisted?.state, 'dispatched');
+        assert.equal(persisted?.claimToken, undefined);
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
+  it('rolls back enqueued durable rows with the enclosing transaction', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const fixture = await createFixture(randomUUID().slice(0, 12));
+      try {
+        const scope = app.scope('a-pay');
+        const eventId = await assert.rejects(
+          app.ctx.db.transaction.begin(async () => {
+            const event = await scope.service.outbox.enqueue(
+              fixture.paymentSessionId!,
+              'payment.outcome.v1',
+              createOutcomePayload(fixture),
+            );
+            fixture.outboxEventIds.push(event.id as number);
+            throw new Error(String(event.id));
+          }),
+          /\d+/,
+        );
+        assert.equal(eventId, undefined);
+        const events = await scope.model.outboxEvent.select({
+          where: { paymentSessionId: fixture.paymentSessionId },
+        });
+        assert.deepEqual(events, []);
+        fixture.outboxEventIds = [];
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+});

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

@@ -0,0 +1,153 @@
+import assert from 'node:assert';
+import { randomUUID } from 'node:crypto';
+import { describe, it } from 'node:test';
+import { app } from 'vona-mock';
+
+interface IFixture {
+  userId?: number;
+  paymentSessionId?: number;
+}
+
+async function createFixture(expiresAt: Date): Promise<IFixture> {
+  const scope = app.scope('a-pay');
+  const suffix = randomUUID().slice(0, 12);
+  const user = await app.bean.user.register({ name: `payment-session-${suffix}` }, true);
+  const session = await scope.service.paymentSession.create({
+    userId: user.id,
+    payScene: 'commerce-payment:commerceOrder',
+    businessReference: `business-${suffix}`,
+    amountMinor: 1299,
+    currency: 'USD',
+    correlationId: `payment-${suffix}`,
+  });
+  await scope.model.paymentSession.updateById(session.id, { expiresAt });
+  return { userId: user.id as number, paymentSessionId: session.id as number };
+}
+
+async function cleanup(fixture: IFixture) {
+  const scope = app.scope('a-pay');
+  if (fixture.paymentSessionId !== undefined) {
+    await scope.model.paymentAudit.delete({ paymentSessionId: fixture.paymentSessionId });
+    await scope.model.paymentSession.delete({ id: fixture.paymentSessionId });
+  }
+  if (fixture.userId !== undefined) {
+    await app.scope('home-user').model.roleUser.delete({ userId: fixture.userId });
+    await app.bean.user.removeById(fixture.userId);
+  }
+}
+
+describe('paymentSession.test.ts', { concurrency: false }, () => {
+  it('derives provider facts and expiry from the payment scene', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const scope = app.scope('a-pay');
+      const suffix = randomUUID().slice(0, 12);
+      const user = await app.bean.user.register({ name: `payment-session-${suffix}` }, true);
+      const fixture: IFixture = { userId: user.id as number };
+      try {
+        const createdAt = Date.now();
+        const session = await scope.service.paymentSession.create({
+          userId: user.id,
+          payScene: 'commerce-payment:commerceOrder',
+          businessReference: `business-${suffix}`,
+          amountMinor: 1299,
+          currency: 'USD',
+          correlationId: `payment-${suffix}`,
+        });
+        fixture.paymentSessionId = session.id as number;
+        assert.equal(session.providerName, 'pay-mock:mock');
+        assert.equal(session.clientName, 'default');
+        assert.equal(session.environment, 'sandbox');
+        assert.ok(session.expiresAt.getTime() >= createdAt + 30 * 60 * 1000);
+        assert.ok(session.expiresAt.getTime() <= Date.now() + 30 * 60 * 1000);
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
+  it('rejects a currency outside the payment scene policy', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const scope = app.scope('a-pay');
+      const suffix = randomUUID().slice(0, 12);
+      const user = await app.bean.user.register({ name: `payment-session-${suffix}` }, true);
+      const fixture: IFixture = { userId: user.id as number };
+      try {
+        await assert.rejects(
+          scope.service.paymentSession.create({
+            userId: user.id,
+            payScene: 'commerce-payment:commerceOrder',
+            businessReference: `business-${suffix}`,
+            amountMinor: 1299,
+            currency: 'EUR',
+            correlationId: `payment-${suffix}`,
+          }),
+          { status: 422 },
+        );
+        assert.deepEqual(
+          await scope.model.paymentSession.select({
+            where: { correlationId: `payment-${suffix}` },
+          }),
+          [],
+        );
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
+  it('starts only an unexpired created payment session', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const fixture = await createFixture(new Date(Date.now() + 60_000));
+      try {
+        const scope = app.scope('a-pay');
+        const session = await scope.service.paymentSession.start(fixture.paymentSessionId!);
+        assert.equal(session.state, 'requires_action');
+        await assert.rejects(scope.service.paymentSession.start(fixture.paymentSessionId!), {
+          status: 409,
+        });
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
+  it('does not start an expired payment session', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const fixture = await createFixture(new Date(Date.now() - 1));
+      try {
+        const scope = app.scope('a-pay');
+        await assert.rejects(scope.service.paymentSession.start(fixture.paymentSessionId!), {
+          status: 409,
+        });
+        assert.equal(
+          (await scope.model.paymentSession.getById(fixture.paymentSessionId!))?.state,
+          'created',
+        );
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
+  it('allows only one competing start to call the provider', async () => {
+    const fixture = await app.bean.executor.mockCtx(async () => {
+      return await createFixture(new Date(Date.now() + 60_000));
+    });
+    try {
+      const results = await Promise.allSettled([
+        app.bean.executor.mockCtx(async () => {
+          return await app.scope('a-pay').service.paymentSession.start(fixture.paymentSessionId!);
+        }),
+        app.bean.executor.mockCtx(async () => {
+          return await app.scope('a-pay').service.paymentSession.start(fixture.paymentSessionId!);
+        }),
+      ]);
+      assert.equal(results.filter(result => result.status === 'fulfilled').length, 1);
+      assert.equal(results.filter(result => result.status === 'rejected').length, 1);
+    } finally {
+      await app.bean.executor.mockCtx(async () => {
+        await cleanup(fixture);
+      });
+    }
+  });
+});