@munchi_oy/payments 1.6.10 → 1.10.1

package/src/strategies/VivaSessionStrategy.ts

@@ -0,0 +1,402 @@
+import {
+  type InitiateVivaSessionDto,
+  PaymentFailureCode,
+  PaymentSessionApi,
+  PaymentSessionStatus,
+  type PaymentSessionViewDto,
+  type PaymentStatusDto,
+  type ReverseSessionDto,
+  SimplePaymentStatus,
+  type TransactionDto,
+} from "@munchi_oy/core";
+import type { AxiosInstance } from "axios";
+
+import { PaymentErrorCode, PaymentSDKError } from "../error";
+import {
+  type IMessagingAdapter,
+  type PaymentInteractionState,
+  PaymentInteractionState as InteractionState,
+  type PaymentRequest,
+  type PaymentResult,
+  type PaymentTerminalConfig,
+  type RefundRequest,
+  type RevertRequest,
+  SdkPaymentStatus,
+} from "../types/payment";
+import type { IPaymentStrategy } from "./IPaymentStrategy";
+import { mapSessionResult, pendingResult } from "./sessionResult";
+
+export class VivaSessionStrategy implements IPaymentStrategy {
+  private static readonly POLLING_DURATION_MS = 180000;
+  private static readonly POLLING_INTERVAL_MS = 1000;
+  private static readonly VERIFY_DURATION_MS = 30000;
+  private static readonly INITIAL_POLL_DELAY_MS = 10000;
+
+  private sessionApi: PaymentSessionApi;
+  private abortController: AbortController | null = null;
+  private idempotencyKey: string | null = null;
+  private idempotencyOrderRef: string | null = null;
+  private currentClientToken: string | null = null;
+
+  constructor(
+    axios: AxiosInstance,
+    private messaging: IMessagingAdapter,
+    private config: PaymentTerminalConfig,
+  ) {
+    this.sessionApi = new PaymentSessionApi(undefined, "", axios);
+  }
+
+  async processPayment(
+    request: PaymentRequest,
+    onStateChange: (state: PaymentInteractionState, detail?: { sessionId?: string }) => void,
+  ): Promise<PaymentResult> {
+    this.abortController = new AbortController();
+    if (
+      this.idempotencyKey === null ||
+      this.idempotencyOrderRef !== request.orderRef
+    ) {
+      this.idempotencyKey = this.generateIdempotencyKey();
+      this.idempotencyOrderRef = request.orderRef;
+    }
+    this.currentClientToken = null;
+
+    onStateChange(InteractionState.CONNECTING);
+
+    const payload: InitiateVivaSessionDto = {
+      amount: request.amountCents,
+      businessId: Number(this.config.storeId),
+      orderId: request.orderRef,
+    };
+    if (request.splitContext !== undefined) {
+      payload.splitContext = request.splitContext;
+    }
+
+    try {
+      const { data } = await this.sessionApi.initiateVivaSession(
+        payload,
+        this.idempotencyKey,
+      );
+      this.currentClientToken = data.clientToken;
+      const signal = this.abortController.signal;
+
+      if (signal.aborted) {
+        throw new Error("Aborted");
+      }
+
+      onStateChange(InteractionState.REQUIRES_INPUT, { sessionId: data.sessionId });
+
+      const terminal = await this.waitForCompletion(
+        data.clientToken,
+        data.sessionId,
+        request,
+        signal,
+      );
+
+      if (terminal) {
+        return this.finalize(terminal);
+      }
+
+      await this.armCancel(data.clientToken);
+      return pendingResult(request.orderRef);
+    } catch (err) {
+      if (err instanceof PaymentSDKError) throw err;
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to create Viva payment session",
+        err,
+      );
+    }
+  }
+
+  async verifyFinalStatus(
+    request: PaymentRequest,
+    _sessionId: string,
+  ): Promise<PaymentResult> {
+    if (!this.currentClientToken) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "No active payment session to verify",
+      );
+    }
+
+    const terminal = await this.pollUntilTerminal(
+      this.currentClientToken,
+      request,
+      undefined,
+      VivaSessionStrategy.VERIFY_DURATION_MS,
+    );
+
+    return this.finalize(terminal ?? pendingResult(request.orderRef));
+  }
+
+  async cancelTransaction(
+    _onStateChange: (state: PaymentInteractionState) => void,
+  ): Promise<boolean> {
+    if (!this.currentClientToken) {
+      return false;
+    }
+
+    try {
+      await this.sessionApi.cancelVivaSession(this.currentClientToken);
+    } catch (error) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to cancel Viva payment session",
+        error,
+      );
+    }
+
+    this.abortController?.abort();
+    return true;
+  }
+
+  async refundTransaction(
+    request: RefundRequest,
+    _onStateChange: (state: PaymentInteractionState, detail?: { sessionId?: string }) => void,
+  ): Promise<PaymentResult> {
+    try {
+      const payload: ReverseSessionDto = {
+        sessionId: request.originalTransactionId,
+        amount: request.amountCents,
+      };
+
+      const { data } = await this.sessionApi.refundVivaSession(payload);
+
+      const isRefunded =
+        data.status === PaymentSessionStatus.Refunded ||
+        data.status === PaymentSessionStatus.Refunding;
+
+      const result: PaymentResult = {
+        success: isRefunded,
+        status: isRefunded ? SdkPaymentStatus.SUCCESS : SdkPaymentStatus.FAILED,
+        orderId: request.orderRef,
+        transactionId: data.providerTransactionId ?? data.sessionId,
+      };
+
+      if (!isRefunded) {
+        if (data.errorCode) result.errorCode = data.errorCode;
+        if (data.errorMessage) result.errorMessage = data.errorMessage;
+      }
+
+      return result;
+    } catch (error) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to refund Viva transaction",
+        error,
+      );
+    }
+  }
+
+  async revertTransaction(request: RevertRequest): Promise<PaymentResult> {
+    try {
+      const payload: ReverseSessionDto = {
+        sessionId: request.originalTransactionId,
+      };
+
+      const { data } = await this.sessionApi.revertVivaSession(payload);
+
+      const isReverted =
+        data.status === PaymentSessionStatus.Refunded ||
+        data.status === PaymentSessionStatus.Refunding;
+
+      const result: PaymentResult = {
+        success: isReverted,
+        status: isReverted ? SdkPaymentStatus.SUCCESS : SdkPaymentStatus.FAILED,
+        orderId: request.orderRef,
+        transactionId: data.providerTransactionId ?? data.sessionId,
+      };
+
+      if (!isReverted) {
+        if (data.errorCode) result.errorCode = data.errorCode;
+        if (data.errorMessage) result.errorMessage = data.errorMessage;
+      }
+
+      return result;
+    } catch (error) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to revert Viva transaction",
+        error,
+      );
+    }
+  }
+
+  abort(): void {
+    this.abortController?.abort();
+  }
+
+  private async pollUntilTerminal(
+    clientToken: string,
+    request: PaymentRequest,
+    signal: AbortSignal | undefined,
+    durationMs: number,
+  ): Promise<PaymentResult | undefined> {
+    const deadline = Date.now() + durationMs;
+
+    while (Date.now() < deadline) {
+      if (signal?.aborted) {
+        throw new Error("Aborted");
+      }
+
+      let data: PaymentSessionViewDto | undefined;
+      try {
+        data = (await this.sessionApi.getPaymentSession(clientToken)).data;
+      } catch (error) {
+        if (error instanceof Error && error.message === "Aborted") throw error;
+      }
+
+      if (signal?.aborted) {
+        throw new Error("Aborted");
+      }
+
+      if (data) {
+        const result = mapSessionResult(data, request.orderRef);
+        if (result.status !== SdkPaymentStatus.PENDING) {
+          return result;
+        }
+      }
+
+      await this.delay(VivaSessionStrategy.POLLING_INTERVAL_MS, signal);
+    }
+
+    return undefined;
+  }
+
+  private waitForCompletion(
+    clientToken: string,
+    sessionId: string,
+    request: PaymentRequest,
+    signal: AbortSignal,
+  ): Promise<PaymentResult | undefined> {
+    const channelName = `viva.${this.config.channel.toLowerCase()}.requests.${sessionId}`;
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+
+      const cleanup = () => {
+        settled = true;
+        if (typeof unsubscribe === "function") unsubscribe();
+        clearTimeout(pollTimer);
+        signal.removeEventListener("abort", onAbort);
+      };
+
+      const onAbort = () => {
+        cleanup();
+        reject(new Error("Aborted"));
+      };
+      signal.addEventListener("abort", onAbort);
+
+      const unsubscribe = this.messaging.subscribe<PaymentStatusDto>(
+        channelName,
+        "payment:status-changed",
+        (data: PaymentStatusDto) => {
+          if (settled) return;
+          if (data.status === SimplePaymentStatus.Pending) return;
+          cleanup();
+          resolve(this.mapStatusDto(data, request));
+        },
+      );
+
+      const pollTimer = setTimeout(() => {
+        if (settled) return;
+        this.pollUntilTerminal(
+          clientToken,
+          request,
+          signal,
+          VivaSessionStrategy.POLLING_DURATION_MS,
+        ).then(
+          (result) => {
+            if (settled) return;
+            cleanup();
+            resolve(result);
+          },
+          (error) => {
+            if (settled) return;
+            cleanup();
+            reject(error);
+          },
+        );
+      }, VivaSessionStrategy.INITIAL_POLL_DELAY_MS);
+    });
+  }
+
+  private mapStatusDto(
+    data: PaymentStatusDto,
+    request: PaymentRequest,
+  ): PaymentResult {
+    const isSuccess = data.status === SimplePaymentStatus.Success;
+
+    const result: PaymentResult = {
+      success: isSuccess,
+      status: isSuccess ? SdkPaymentStatus.SUCCESS : SdkPaymentStatus.FAILED,
+      orderId: request.orderRef,
+      errorCode:
+        data.error?.code || (isSuccess ? "" : PaymentFailureCode.SystemUnknown),
+      errorMessage:
+        data.error?.message ||
+        (isSuccess ? "" : "Transaction failed without error details"),
+    };
+
+    if (data.transactionId) {
+      result.transactionId = data.transactionId;
+    }
+    if (data.error?.referenceError) {
+      result.errorReference = data.error.referenceError;
+    }
+    if (data.transaction) {
+      result.transaction = data.transaction as unknown as TransactionDto;
+    }
+
+    return result;
+  }
+
+  private finalize(result: PaymentResult): PaymentResult {
+    if (result.status !== SdkPaymentStatus.PENDING) {
+      this.idempotencyKey = null;
+      this.idempotencyOrderRef = null;
+    }
+    return result;
+  }
+
+  private armCancel(clientToken: string): Promise<void> {
+    return this.sessionApi.cancelVivaSession(clientToken).then(
+      () => undefined,
+      () => undefined,
+    );
+  }
+
+  private generateIdempotencyKey(): string {
+    const cryptoRef = (
+      globalThis as { crypto?: { randomUUID?: () => string } }
+    ).crypto;
+
+    if (cryptoRef?.randomUUID) {
+      return cryptoRef.randomUUID();
+    }
+
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+      const random = (Math.random() * 16) | 0;
+      const value = char === "x" ? random : (random & 0x3) | 0x8;
+      return value.toString(16);
+    });
+  }
+
+  private delay(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      const onAbort = () => {
+        clearTimeout(timeout);
+        resolve();
+      };
+      if (signal) {
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      const timeout = setTimeout(() => {
+        if (signal) {
+          signal.removeEventListener("abort", onAbort);
+        }
+        resolve();
+      }, ms);
+    });
+  }
+}

package/src/strategies/sessionResult.ts

@@ -0,0 +1,92 @@
+import {
+  PaymentFailureCode,
+  PaymentSessionStatus,
+  type PaymentSessionViewDto,
+} from "@munchi_oy/core";
+
+import { PaymentErrorCode, PaymentSDKError } from "../error";
+import { type PaymentResult, SdkPaymentStatus } from "../types/payment";
+
+function assertNever(value: never): never {
+  throw new PaymentSDKError(
+    PaymentErrorCode.UNKNOWN,
+    `Unhandled payment session status: ${String(value)}`,
+  );
+}
+
+export function pendingResult(orderId: string): PaymentResult {
+  return {
+    success: false,
+    status: SdkPaymentStatus.PENDING,
+    orderId,
+    errorCode: "",
+    errorMessage: "",
+  };
+}
+
+export function mapSessionResult(
+  data: PaymentSessionViewDto,
+  orderId: string,
+): PaymentResult {
+  switch (data.status) {
+    case PaymentSessionStatus.Initiated:
+    case PaymentSessionStatus.Processing:
+    case PaymentSessionStatus.Voiding:
+    case PaymentSessionStatus.Refunding:
+      return pendingResult(orderId);
+
+    case PaymentSessionStatus.Success:
+    case PaymentSessionStatus.Closed: {
+      const result: PaymentResult = {
+        success: true,
+        status: SdkPaymentStatus.SUCCESS,
+        orderId,
+        errorCode: "",
+        errorMessage: "",
+      };
+      if (data.providerTransactionId) {
+        result.transactionId = data.providerTransactionId;
+      }
+      return result;
+    }
+
+    case PaymentSessionStatus.VoidFailed:
+    case PaymentSessionStatus.Failed: {
+      const result: PaymentResult = {
+        success: false,
+        status: SdkPaymentStatus.FAILED,
+        orderId,
+        errorCode: data.errorCode || PaymentFailureCode.SystemUnknown,
+        errorMessage:
+          data.errorMessage || "Transaction failed without error details",
+      };
+      if (data.providerTransactionId) {
+        result.transactionId = data.providerTransactionId;
+      }
+      return result;
+    }
+
+    case PaymentSessionStatus.Cancelled:
+    case PaymentSessionStatus.Voided:
+    case PaymentSessionStatus.Refunded: {
+      const result: PaymentResult = {
+        success: false,
+        status: SdkPaymentStatus.CANCELLED,
+        orderId,
+      };
+      if (data.errorCode) {
+        result.errorCode = data.errorCode;
+      }
+      if (data.errorMessage) {
+        result.errorMessage = data.errorMessage;
+      }
+      if (data.providerTransactionId) {
+        result.transactionId = data.providerTransactionId;
+      }
+      return result;
+    }
+
+    default:
+      return assertNever(data.status);
+  }
+}

package/src/types/payment.ts

@@ -1,8 +1,9 @@
 import type {
-    CurrencyCode,
-    PaymentProvider,
-    ProviderEnum,
-    TransactionDto,
+  CurrencyCode,
+  PaymentProvider,
+  ProviderEnum,
+  SplitContextDto,
+  TransactionDto,
 } from "@munchi_oy/core";
 
 export type TransactionDetails = Omit<
@@ -63,6 +64,12 @@ export interface PaymentRequest {
   currency: CurrencyCode;
   displayId: string;
   options?: VivaOptions | NetsOptions | WorldlineOptions;
+  /**
+   * Split context for the payment-session flow. Omit for a full-cart payment,
+   * or send { mode, partId|seatId } for a split. Must match the order's
+   * checkoutModel. Only consumed by VivaSessionStrategy.
+   */
+  splitContext?: SplitContextDto;
 }
 
 export interface RefundRequest {
@@ -83,9 +90,33 @@ export interface RefundRequest {
   options?: VivaRefundOptions | NetsRefundOptions | WorldlineRefundOptions;
 }
 
+export interface ManualPaymentRequest {
+  orderRef: string;
+  amountCents: number;
+  paymethod: string;
+  tipAmount?: number;
+  splitContext?: SplitContextDto;
+  /**
+   * Arbitrary client metadata persisted on the session (e.g. voucher code,
+   * gift card id, employee id, external reference, notes). Surfaced to
+   * reconciliation when building the order paymentEvent.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+export interface VoidRequest {
+  orderRef: string;
+  sessionId: string;
+}
+
+export interface RevertRequest {
+  orderRef: string;
+  originalTransactionId: string;
+}
+
 export interface PaymentTerminalConfig {
-  channel: ProviderEnum,
-  provider?: PaymentProvider | null;
+  channel: ProviderEnum;
+  provider: PaymentProvider;
   kioskId: string;
   storeId: string;
 }
@@ -102,13 +133,28 @@ export interface PaymentResult {
 }
 
 export interface TransactionOptions {
-  onConnecting?: (ctx: { orderRef: string; refPaymentId?: string | undefined }) => void;
-  onRequiresInput?: (ctx: { orderRef: string; refPaymentId?: string | undefined }) => void;
-  onProcessing?: (ctx: { orderRef: string; refPaymentId?: string | undefined }) => void;
-  onVerifying?: (ctx: { orderRef: string; refPaymentId?: string | undefined }) => void;
+  onConnecting?: (ctx: {
+    orderRef: string;
+    refPaymentId?: string | undefined;
+  }) => void;
+  onRequiresInput?: (ctx: {
+    orderRef: string;
+    refPaymentId?: string | undefined;
+  }) => void;
+  onProcessing?: (ctx: {
+    orderRef: string;
+    refPaymentId?: string | undefined;
+  }) => void;
+  onVerifying?: (ctx: {
+    orderRef: string;
+    refPaymentId?: string | undefined;
+  }) => void;
   onSuccess?: (result: PaymentResult) => void;
   onError?: (result: PaymentResult) => void;
-  onCancelled?: (ctx: { orderRef: string; refPaymentId?: string | undefined }) => void;
+  onCancelled?: (ctx: {
+    orderRef: string;
+    refPaymentId?: string | undefined;
+  }) => void;
 }
 
 export interface IMessagingAdapter {
@@ -129,6 +175,21 @@ export interface IMunchiPaymentSDK {
     options?: TransactionOptions,
   ): Promise<PaymentResult>;
   cancel(): Promise<boolean>;
-  refund(params: RefundRequest, options?: TransactionOptions): Promise<PaymentResult>;
+  refund(
+    params: RefundRequest,
+    options?: TransactionOptions,
+  ): Promise<PaymentResult>;
+  revert(
+    params: RevertRequest,
+    options?: TransactionOptions,
+  ): Promise<PaymentResult>;
+  recordManualPayment(
+    params: ManualPaymentRequest,
+    options?: TransactionOptions,
+  ): Promise<PaymentResult>;
+  voidManualPayment(
+    params: VoidRequest,
+    options?: TransactionOptions,
+  ): Promise<PaymentResult>;
   reset(): void;
 }

package/src/types/sdk.ts

@@ -57,4 +57,14 @@ export interface SDKOptions {
    */
   autoResetOnPaymentComplete?: AutoResetOptions;
   appToApp?: AppToAppConfig;
+  /**
+   * Routes POS Viva payments through the backend payment-session flow
+   * (VivaSessionStrategy) instead of the legacy v4 VivaStrategy. Kiosk/handheld
+   * leave this unset and stay on the legacy flow.
+   */
+  paymentSession?: PaymentSessionConfig;
+}
+
+export interface PaymentSessionConfig {
+  enabled: boolean;
 }

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated. Do not edit manually.
 // Run 'pnpm version:sync' to update this file.
-export const VERSION = "1.6.10";
+export const VERSION = "1.10.1";