@starfish-codes/hellgate 3.8.1 → 3.9.1

package/dist/3ds/typings.d.ts

@@ -26,6 +26,7 @@ export type Do3DSChallengeActionDTO = {
     action: '3ds_challenge';
     result: {
         requestor_trans_id: string;
+        requestorTransId?: string;
         event: string;
         param?: string;
     };

package/dist/__tests__/test-utils.d.ts

@@ -1,2 +1,13 @@
 export declare function wait(milliseconds: number): Promise<void>;
 export declare function fill(input: HTMLInputElement, value: string): void;
+export declare const HELLGATE_BASE_URL: string;
+type CreateHellgateSessionParams = {
+    bypass_identification?: boolean;
+};
+export declare function createHellgateSession(params: CreateHellgateSessionParams): Promise<{
+    session_id: string;
+}>;
+export declare function refreshHellgateSession(): Promise<{
+    session_id: string;
+}>;
+export {};

package/dist/card/card-handler.d.ts

@@ -1,20 +1,43 @@
 import { CompleteActionResult, HellgateSession } from '../session';
+import { Coordinator } from '../coordinator';
 import { CreateCardFieldsOptions, CreateCardFormOptions, PaymentAdditionalData, RefreshSecurityCodeSessionStateDTO, TokenizeCardSessionStateDTO, TokenizedData } from './typings';
 import { CardElement, CardExpirationDateElement, CardNumberElement, CardVerificationCodeElement, TextElement } from './ui/elements';
+import { CardElementBase } from './ui/elements/base-element';
+import { CardExpirationMonthElement } from './ui/elements/card-expiration-month';
+import { CardExpirationYearElement } from './ui/elements/card-expiration-year';
 import { ChangeEvent, ElementBaseOptions } from './ui/typings';
-export type FormFieldState = Omit<ChangeEvent<never>['data'], 'type'>;
+export type FormFieldState = Omit<ChangeEvent['data'], 'type'>;
 export type CardHandlerSessionInitState = TokenizeCardSessionStateDTO | RefreshSecurityCodeSessionStateDTO;
+type FormField<T extends CardElementBase<any, any>> = {
+    element: T;
+    state: FormFieldState;
+};
+type ElementsMap = {
+    card: FormField<CardElement>;
+    cardNumber: FormField<CardNumberElement>;
+    cardExpirationDate: FormField<CardExpirationDateElement>;
+    cardExpirationMonth: FormField<CardExpirationMonthElement>;
+    cardExpirationYear: FormField<CardExpirationYearElement>;
+    cardVerificationCode: FormField<CardVerificationCodeElement>;
+};
 export declare class HellgateCardHandler {
     session: HellgateSession<CardHandlerSessionInitState>;
+    private coordinator;
     state: FormFieldState;
-    private cardElements;
+    cardElements: Partial<ElementsMap>;
     private textElements;
     private stateChangeHandlers;
     readonly cvcOnlyEnabled: boolean;
-    static init(session: HellgateSession<CardHandlerSessionInitState>): Promise<HellgateCardHandler>;
-    constructor(session: HellgateSession<CardHandlerSessionInitState>);
+    static init(session: HellgateSession<CardHandlerSessionInitState>, coordinator: Coordinator): Promise<HellgateCardHandler>;
+    constructor(session: HellgateSession<CardHandlerSessionInitState>, coordinator: Coordinator);
     createForm: (options?: CreateCardFormOptions) => CardElement;
-    createFormFields: (options?: CreateCardFieldsOptions) => {
+    createFormFields(options: CreateCardFieldsOptions<'separate'>): {
+        cardNumber: CardNumberElement;
+        expiryMonth: CardExpirationMonthElement;
+        expiryYear: CardExpirationYearElement;
+        securityCode: CardVerificationCodeElement;
+    };
+    createFormFields(options: CreateCardFieldsOptions<'combined'>): {
         cardNumber: CardNumberElement;
         expiryDate: CardExpirationDateElement;
         securityCode: CardVerificationCodeElement;
@@ -27,13 +50,12 @@ export declare class HellgateCardHandler {
     dispose: () => void;
     process: (additionalData?: PaymentAdditionalData) => Promise<CompleteActionResult>;
     private refreshSecurityCode;
-    private getFormValue;
     private hasFormElements;
     private disableFormElements;
-    private extractAdditionalData;
-    private encryptCardData;
     private addElementStateListener;
     updateFormState(): void;
     private createFieldDefaultState;
+    private serializeAdditionalData;
     private getCardDataValidationError;
 }
+export {};

package/dist/card/coordinator/card-handler-coordinator.d.ts

@@ -0,0 +1,34 @@
+import { CompleteActionResult, HellgateSession } from '../../session';
+import { FormFieldState } from '../card-handler';
+import { PaymentAdditionalDataDTO, TokenizedData } from '../typings';
+type FormField<Value = string> = {
+    value?: Value;
+    state: FormFieldState;
+};
+type ElementsMap = {
+    card: FormField<{
+        number: string;
+        expiry_date: string;
+        cvc: string;
+    }>;
+    cardNumber: FormField;
+    cardExpirationDate: FormField;
+    cardExpirationMonth: FormField;
+    cardExpirationYear: FormField;
+    cardVerificationCode: FormField;
+} & Record<string, FormField>;
+export declare class CardHandlerCoordinator {
+    private session;
+    private cardElements;
+    constructor(session: HellgateSession);
+    tokenize: (additionalData: PaymentAdditionalDataDTO) => Promise<TokenizedData>;
+    process: (additionalData?: PaymentAdditionalDataDTO) => Promise<CompleteActionResult>;
+    refreshSecurityCode(): Promise<CompleteActionResult>;
+    onElementChange: (key: keyof ElementsMap | string, data: FormFieldState) => void;
+    dispose(): void;
+    private getFormValue;
+    private extractAdditionalData;
+    private encryptCardData;
+    private extractAdditionalDataStringValue;
+}
+export {};

package/dist/card/coordinator/index.d.ts

@@ -0,0 +1,2 @@
+export * from './card-handler-coordinator';
+export * from './typings';

package/dist/card/coordinator/typings.d.ts

@@ -0,0 +1,36 @@
+import { CompleteActionResult } from '../../session';
+import { FormFieldState } from '../card-handler';
+import { PaymentAdditionalDataDTO, TokenizedData } from '../typings';
+export type CardHandlerToCoordinatorMessage = {
+    type: 'card:tokenize';
+    additionalData?: PaymentAdditionalDataDTO;
+} | {
+    type: 'card:process';
+    additionalData?: PaymentAdditionalDataDTO;
+} | {
+    type: 'card:refresh_security_code';
+};
+export type CoordinatorToCardHandlerMessage = {
+    type: 'card:tokenize:response';
+    success: boolean;
+    result: TokenizedData | null;
+    error?: string;
+} | {
+    type: 'card:process:response';
+    success: boolean;
+    result: CompleteActionResult | null;
+    error?: string;
+} | {
+    type: 'card:refresh_security_code:response';
+    success: boolean;
+    result: CompleteActionResult | null;
+    error?: string;
+};
+export type ElementToCoordinatorMessage = {
+    type: 'element:change';
+    data: {
+        element: string;
+        key: string;
+        state: FormFieldState;
+    };
+};

package/dist/card/typings.d.ts

@@ -6,13 +6,23 @@ export type CreateCardFormOptions = Pick<ElementBaseOptions, 'style' | 'disabled
     icon?: IconPosition;
     schemes?: CardSchema[];
 };
-export type CreateCardFieldsOptions = Pick<ElementBaseOptions, 'style' | 'disabled' | 'autocomplete'> & {
+export type ExpiryDateElementType = 'combined' | 'separate';
+export type CreateCardFieldsOptions<T extends ExpiryDateElementType = 'combined'> = Pick<ElementBaseOptions, 'style' | 'disabled' | 'autocomplete'> & {
     cardNumber?: ElementBaseOptions;
-    expiryDate?: ElementBaseOptions;
     securityCode?: ElementBaseOptions;
     schemes?: CardSchema[];
-};
+} & (T extends 'separate' ? {
+    expiryDateElement: 'separate';
+    expiryMonth?: ElementBaseOptions;
+    expiryYear?: ElementBaseOptions;
+} : {
+    expiryDateElement?: 'combined';
+    expiryDate?: ElementBaseOptions;
+});
 export type AdditionalDataValue = string | TextElement;
+export type AdditionalDataValueDTO = string | {
+    key: string;
+};
 export type PaymentAdditionalData<FieldValue = AdditionalDataValue> = {
     cardholder_name?: FieldValue;
     email?: FieldValue;
@@ -25,6 +35,7 @@ export type PaymentAdditionalData<FieldValue = AdditionalDataValue> = {
         country?: FieldValue;
     };
 };
+export type PaymentAdditionalDataDTO = PaymentAdditionalData<AdditionalDataValueDTO>;
 export type ElementsCardData = {
     number: string | null;
     expiration_month: number | null;

package/dist/card/ui/elements/base-element.d.ts

@@ -8,15 +8,15 @@ export declare abstract class CardElementBase<Value, IframeValue = string> {
     protected abstract type: ElementType;
     protected abstract extractValue: (rawValue: IframeValue | null) => Value | null;
     protected abstract putValue: (rawValue: Value | null) => IframeValue | null;
-    constructor(options: ElementBaseOptions<Value>, key?: string);
+    key: string;
+    constructor(options: ElementBaseOptions<Value>);
     mount(selector: string | Element): Promise<void>;
     update: ({ ...data }: ElementBaseOptions<Value>) => Promise<void>;
     clear: () => void;
     focus: () => void;
     blur: () => void;
     unmount: () => void;
-    on<T extends EventType>(eventType: T, listener: (event: FindByType<Explicit<CardElementEvents<never>>, T>['data']) => void): Subscription;
-    secureValue(key: string): Value | null;
+    on<T extends EventType>(eventType: T, listener: (event: FindByType<Explicit<CardElementEvents>, T>['data']) => void): Subscription;
     private emitEvent;
     private iframePostMessage;
 }

package/dist/card/ui/elements/card-expiration-month.d.ts

@@ -0,0 +1,9 @@
+import { ElementType } from '../typings';
+import { CardElementBase } from './base-element';
+export declare class CardExpirationMonthElement extends CardElementBase<number> {
+    protected type: ElementType;
+    protected extractValue: typeof extractExpiryMonthValue;
+    protected putValue: typeof putExpiryMonthValue;
+}
+export declare function extractExpiryMonthValue(rawValue: string | null): number | null;
+export declare function putExpiryMonthValue(rawValue: number | null): string | null;

package/dist/card/ui/elements/card-expiration-year.d.ts

@@ -0,0 +1,9 @@
+import { ElementType } from '../typings';
+import { CardElementBase } from './base-element';
+export declare class CardExpirationYearElement extends CardElementBase<number> {
+    protected type: ElementType;
+    protected extractValue: typeof extractExpiryYearValue;
+    protected putValue: typeof putExpiryYearValue;
+}
+export declare function extractExpiryYearValue(rawValue: string | null): number | null;
+export declare function putExpiryYearValue(rawValue: number | null): string | null;

package/dist/card/ui/elements/utils.d.ts

@@ -1,6 +1,8 @@
 import { ElementBaseOptions } from '../typings';
 import { CardElement } from './card';
 import { CardExpirationDateElement } from './card-expiration-date';
+import { CardExpirationMonthElement } from './card-expiration-month';
+import { CardExpirationYearElement } from './card-expiration-year';
 import { CardNumberElement } from './card-number';
 import { CardVerificationCodeElement } from './card-verification-code';
 import { TextElement } from './text-element';
@@ -8,9 +10,10 @@ type Elements = {
     card: CardElement;
     cardNumber: CardNumberElement;
     cardExpirationDate: CardExpirationDateElement;
+    cardExpirationMonth: CardExpirationMonthElement;
+    cardExpirationYear: CardExpirationYearElement;
     cardVerificationCode: CardVerificationCodeElement;
     text: TextElement;
 };
-export declare function createElement<T extends keyof Elements>(type: T, options: ElementBaseOptions, key?: string): Elements[T];
-export declare function uid(): string;
+export declare function createElement<T extends keyof Elements>(type: T, options: ElementBaseOptions): Elements[T];
 export {};

package/dist/card/ui/iframe/elements/base-element.d.ts

@@ -3,7 +3,6 @@ import { FactoryArg, InputMask, Masked } from 'imask';
 import { BaseElement, CardElementEvents, ElementBaseOptions, ElementEventListener, ElementMetadata, ElementType, EventType, Subscription } from '../../typings';
 export type PostMessageOptions = {
     postMessageOrigin: string;
-    postMessageRoot: Window;
 };
 export declare abstract class IframeCardElementBase implements BaseElement<ElementBaseOptions, CardElementEvents<string>, string> {
     protected rootNode: Element;
@@ -16,9 +15,10 @@ export declare abstract class IframeCardElementBase implements BaseElement<Eleme
     protected abstract options: ElementBaseOptions;
     protected abstract inputMaskOptions: FactoryArg;
     protected inputMask?: InputMask<FactoryArg>;
-    private id;
+    protected id: string;
     cardType?: CreditCardType;
     value: null;
+    private channel;
     constructor(rootNode: Element, postMessageOptions: PostMessageOptions);
     mount(): Promise<void>;
     unmount(): void;
@@ -29,6 +29,7 @@ export declare abstract class IframeCardElementBase implements BaseElement<Eleme
     updateState(): void;
     update(options: ElementBaseOptions): Promise<void>;
     on<T extends EventType>(eventType: T, listener: ElementEventListener<CardElementEvents<string>, T>): Subscription;
+    protected get key(): string;
     private emitEvent;
     protected validate(masked: Masked): ElementMetadata;
     protected renderHTML(): string;

package/dist/card/ui/iframe/elements/card-expiration-month.d.ts

@@ -0,0 +1,10 @@
+import { FactoryArg, Masked } from 'imask';
+import { ElementBaseOptions, ElementMetadata, ElementType, ITextElement } from '../../typings';
+import { IframeCardElementBase } from './base-element';
+export declare class IframeCardExpirationMonth extends IframeCardElementBase implements ITextElement {
+    readonly type: ElementType;
+    protected options: ElementBaseOptions;
+    compiledMask?: Masked;
+    protected inputMaskOptions: FactoryArg;
+    protected validate(masked: Masked): ElementMetadata;
+}

package/dist/card/ui/iframe/elements/card-expiration-year.d.ts

@@ -0,0 +1,9 @@
+import { FactoryArg, Masked } from 'imask';
+import { ElementBaseOptions, ElementMetadata, ElementType, ITextElement } from '../../typings';
+import { IframeCardElementBase } from './base-element';
+export declare class IframeCardExpirationYear extends IframeCardElementBase implements ITextElement {
+    readonly type: ElementType;
+    protected options: ElementBaseOptions;
+    protected inputMaskOptions: FactoryArg;
+    protected validate(masked: Masked): ElementMetadata;
+}

package/dist/card/ui/iframe/elements/text-element.d.ts

@@ -5,4 +5,5 @@ export declare class IframeTextElement extends IframeCardElementBase implements
     readonly type: ElementType;
     protected options: ElementBaseOptions;
     protected inputMaskOptions: FactoryArg;
+    protected get key(): string;
 }

package/dist/card/ui/iframe/index.d.ts

@@ -1 +1,2 @@
 export * from './iframe';
+export { parseURLSearchParams } from './utils';

package/dist/card/ui/iframe/utils.d.ts

@@ -21,4 +21,5 @@ export declare function generateElementId(type: ElementType): string;
 export declare function mergeOptions(options1: ElementBaseOptions, options2: ElementBaseOptions): ElementBaseOptions;
 export declare function mergeStyles(style1: ElementStyle, style2: ElementStyle): ElementStyle;
 export declare function applyStyle(id: string, { fonts, ...styles }: ElementStyle): void;
+export declare function uid(): string;
 export {};

package/dist/card/ui/typings.d.ts

@@ -7,18 +7,21 @@ type EventType = 'ready' | 'change' | 'focus' | 'blur' | 'keydown';
 export declare const EVENT_TYPES: EventType[];
 type BaseEvent<T extends EventType, TData = unknown> = {
     type: T;
+    id: string;
     element: ElementType;
 } & (TData extends object ? {
     data: TData;
 } : unknown);
-type ReadyEvent = BaseEvent<'ready'>;
-type ChangeEvent<Value> = BaseEvent<'change', {
+type ReadyEvent = BaseEvent<'ready', {
+    key: string;
+}>;
+type ChangeEvent<Value = never> = BaseEvent<'change', {
     empty: boolean;
     complete: boolean;
     valid?: boolean;
     error?: string;
     errorCode?: CardValidationError;
-    value: Value extends never ? never : Value | null;
+    value?: Value extends never ? never : Value | null;
 }>;
 type InputFocusEvent = BaseEvent<'focus'>;
 type InputBlurEvent = BaseEvent<'blur'>;
@@ -26,11 +29,11 @@ type InputKeydownEvent = BaseEvent<'keydown', {
     key: ListenableKey;
 } & Pick<KeyboardEvent, 'altKey' | 'ctrlKey' | 'shiftKey' | 'metaKey'>>;
 type BaseElementEvents = ReadyEvent | InputFocusEvent | InputBlurEvent | InputKeydownEvent;
-type CardElementEvents<Value> = BaseElementEvents | ChangeEvent<Value>;
+type CardElementEvents<Value = never> = BaseElementEvents | ChangeEvent<Value>;
 /**
  * Utility type that helps find a Union type based on a `type` property
  */
-type FindByType<Union, Type extends EventType> = Union extends {
+type FindByType<Union, Type extends string> = Union extends {
     type: Type;
 } ? Union : never;
 type ElementEventListener<Events, Type extends EventType> = (event: FindByType<Events, Type>) => void;
@@ -38,7 +41,7 @@ interface Subscription {
     unsubscribe(): void;
 }
 export type { BaseElementEvents, BaseEvent, CardElementEvents, ChangeEvent, ElementEventListener, EventType, FindByType, InputBlurEvent, InputFocusEvent, InputKeydownEvent, ReadyEvent, Subscription, };
-export type ElementType = 'card' | 'cardNumber' | 'cardExpirationDate' | 'cardVerificationCode' | 'text';
+export type ElementType = 'card' | 'cardNumber' | 'cardExpirationDate' | 'cardExpirationMonth' | 'cardExpirationYear' | 'cardVerificationCode' | 'text';
 export declare const ELEMENT_TYPES: ElementType[];
 export declare enum CardValidationError {
     NOT_COMPLETE = "NOT_COMPLETE",
@@ -76,6 +79,7 @@ export type ElementBaseOptions<Value = unknown> = {
     schemes?: CardSchema[];
     value?: Value;
     cardType?: string;
+    expiryYear?: string;
 };
 /**
  * Card brands type

package/dist/coordinator/coordinator.d.ts

@@ -0,0 +1,38 @@
+import { FindByType } from '../card/ui/typings';
+import { CoordinatorToParentMessage, ParentToCoordinatorMessage } from './typings';
+/**
+ * Coordinator lives on the parent (merchant) page.
+ *
+ * It creates a hidden iframe with `?type=coordinator` that hosts the
+ * IframeCoordinator. All sensitive card operations (data collection,
+ * encryption, API calls) happen inside that iframe — card data never
+ * crosses the iframe boundary back to the merchant page.
+ *
+ * Communication with the iframe uses window.postMessage, carrying only
+ * commands and validation state — never card data.
+ */
+export declare class Coordinator {
+    private iframe;
+    private iframeBaseUrl;
+    private messageHandler;
+    constructor();
+    /**
+     * Mount the coordinator iframe into the DOM and wait until it is
+     * fully initialised (receives `coordinator:ready` from the iframe with the session state).
+     *
+     * The iframe is hidden — it has no visual presence on the page.
+     * It serves purely as an isolated execution environment for secure
+     * card-data handling.
+     */
+    init: (sessionId: string, baseUrl: string, abortCtrl?: AbortController) => Promise<void>;
+    /**
+     * Send a command to the coordinator iframe.
+     * Only commands and configuration — never card data.
+     */
+    postMessage(message: ParentToCoordinatorMessage): void;
+    onMessage<T extends CoordinatorToParentMessage['type']>(type: T, callback: (message: FindByType<CoordinatorToParentMessage, T>) => void): void;
+    /**
+     * Clean up the coordinator iframe and all associated resources.
+     */
+    dispose(): void;
+}

package/dist/coordinator/iframe/constants.d.ts

@@ -0,0 +1 @@
+export declare const COORDINATOR_IFRAME_CHANNEL_NAME = "coordinator-channel";

package/dist/coordinator/iframe/iframe-coordinator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * IframeCoordinator lives entirely within the iframe isolation layer.
+ *
+ * It coordinates all card form elements via the Channel Messaging API,
+ * combines and validates card data within the iframe, encrypts sensitive
+ * data, and makes direct API calls to the Hellgate backend.
+ *
+ * SECURITY: Card data NEVER crosses the iframe boundary.
+ * - Card form elements send raw values only to the coordinator (same origin, via MessagePort)
+ * - The coordinator encrypts data and communicates with the backend directly
+ * - Only validation state (empty, complete, valid) is sent to the parent via postMessage
+ */
+export declare class IframeCoordinator {
+    private parentOrigin;
+    private cardHandlerCoordinator;
+    private session;
+    private channel;
+    constructor(sessionId: string, apiBaseUrl: string, parentOrigin: string);
+    init: () => Promise<void>;
+    private setupChannelListener;
+    /**
+     * Listen for messages from the parent CardHandler.
+     * Only commands and configuration cross this boundary - never card data.
+     */
+    private setupParentMessageListener;
+    private handleParentMessage;
+    /**
+     * Send a message to the parent CardHandler.
+     * Only validation state and results - never card data.
+     */
+    private postMessageToParent;
+    dispose(): void;
+}

package/dist/coordinator/iframe/iframe.d.ts

@@ -0,0 +1 @@
+export declare function initCoordinatorIframe(sessionId: string, apiBaseUrl: string, origin: string): void;

package/dist/coordinator/iframe/index.d.ts

@@ -0,0 +1,2 @@
+export { initCoordinatorIframe } from './iframe';
+export { IframeCoordinator } from './iframe-coordinator';

package/dist/coordinator/index.d.ts

@@ -0,0 +1,3 @@
+export { Coordinator } from './coordinator';
+export { IframeCoordinator } from './iframe/iframe-coordinator';
+export type { CoordinatorFormState, CoordinatorToParentMessage, ParentToCoordinatorMessage, } from './typings';

package/dist/coordinator/typings.d.ts

@@ -0,0 +1,39 @@
+import { CardHandlerToCoordinatorMessage, CoordinatorToCardHandlerMessage } from '../card/coordinator/typings';
+import { SessionStateDTO } from '../session';
+/**
+ * Message types sent FROM the parent CardHandler TO the coordinator iframe
+ * via window.postMessage (crosses iframe boundary)
+ *
+ * IMPORTANT: No card data flows through these messages.
+ * Only commands and configuration are sent.
+ */
+export type ParentToCoordinatorMessage = {
+    type: 'coordinator:init';
+    sessionId: string;
+    baseUrl: string;
+} | {
+    type: 'coordinator:dispose';
+} | CardHandlerToCoordinatorMessage;
+/**
+ * Message types sent FROM the coordinator iframe TO the parent CardHandler
+ * via window.postMessage (crosses iframe boundary)
+ *
+ * IMPORTANT: No card data flows through these messages.
+ * Only validation state and tokenization results are sent.
+ */
+export type CoordinatorToParentMessage = {
+    type: 'coordinator:ready';
+} | {
+    type: 'coordinator:error';
+    error: unknown;
+} | {
+    type: 'coordinator:session_state_change';
+    state: SessionStateDTO;
+} | CoordinatorToCardHandlerMessage;
+export type CoordinatorFormState = {
+    empty: boolean;
+    complete: boolean;
+    valid: boolean;
+    error?: string;
+    errorCode?: string;
+};