@starfish-codes/hellgate 3.9.0 → 3.10.0

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__/card-handler.spec.d.ts

@@ -0,0 +1 @@
+export {};

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,35 @@
 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'>;
+import { CardSchema, ChangeEvent, ElementBaseOptions } from './ui/typings';
+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<'separate'>): {
         cardNumber: CardNumberElement;
@@ -35,13 +50,14 @@ 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 getSessionSchemes;
     private getCardDataValidationError;
 }
+export declare function resolveSchemes(sessionSchemes: CardSchema[] | undefined, userSchemes: CardSchema[] | undefined): CardSchema[] | undefined;
+export {};

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

@@ -0,0 +1 @@
+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,45 @@
+import { CompleteActionResult } from '../../session';
+import { FormFieldState } from '../card-handler';
+import { PaymentAdditionalDataDTO, TokenizedData } from '../typings';
+import { ElementBaseOptions } from '../ui/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;
+    };
+};
+export type CoordinatorToElementMessage = {
+    type: 'coordinator:element:update';
+    data: {
+        element: string;
+        key: string;
+        options: ElementBaseOptions;
+    };
+};

package/dist/card/typings.d.ts

@@ -20,6 +20,9 @@ export type CreateCardFieldsOptions<T extends ExpiryDateElementType = 'combined'
     expiryDate?: ElementBaseOptions;
 });
 export type AdditionalDataValue = string | TextElement;
+export type AdditionalDataValueDTO = string | {
+    key: string;
+};
 export type PaymentAdditionalData<FieldValue = AdditionalDataValue> = {
     cardholder_name?: FieldValue;
     email?: FieldValue;
@@ -31,7 +34,21 @@ export type PaymentAdditionalData<FieldValue = AdditionalDataValue> = {
         city?: FieldValue;
         country?: FieldValue;
     };
+    /**
+     * Token lifecycle intent. When `true` (the SDK default), the resulting PCI
+     * token is ephemeral and cleaned up after a short TTL. When `false`, the
+     * token is persistent. Use `false` only on cardholder consent.
+     */
+    ephemeral?: boolean;
+    /**
+     * Optional ISO-8601 timestamp setting an explicit expiration for the
+     * resulting PCI token. When present it takes precedence over `ephemeral`
+     * (subject to a server-side cap). Use this for a "Save my card" UX where
+     * the merchant chooses the exact retention window after cardholder consent.
+     */
+    expiration_date?: string;
 };
+export type PaymentAdditionalDataDTO = PaymentAdditionalData<AdditionalDataValueDTO>;
 export type ElementsCardData = {
     number: string | null;
     expiration_month: number | null;
@@ -48,11 +65,13 @@ export type TokenizeCardActionDTO = {
     action: 'tokenize_card';
     result: TokenizedData;
 };
+export type HellgateCardScheme = 'visa' | 'mastercard' | 'americanexpress' | 'discover' | 'dinersclub' | 'jcb' | 'unionpay';
 export type TokenizeCardConfig = {
     provider: 'guardian';
     api_key: string;
     base_url: string;
     jwk: JWK;
+    allowed_schemes?: HellgateCardScheme[];
 };
 export type TokenizeCardSessionStateDTO = {
     next_action: 'tokenize_card';
@@ -65,6 +84,17 @@ export type CardTokenizeData = {
     security_code: string;
     cardholder_name?: string;
     additional_data: PaymentAdditionalData<string>;
+    /**
+     * Optional token lifecycle intent decrypted by Guardian inside the JWE.
+     * `true` requests an ephemeral PCI token, `false` a persistent one. Absent
+     * preserves Guardian's pre-existing default behavior.
+     */
+    ephemeral?: boolean;
+    /**
+     * Optional ISO-8601 expiration timestamp decrypted by Guardian inside the
+     * JWE. Wins over `ephemeral` server side.
+     */
+    expiration_date?: string;
 };
 export type TokenizedCardMaskedData = {
     account_number_last_four: string;

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/utils.d.ts

@@ -15,6 +15,5 @@ type Elements = {
     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,11 +15,13 @@ 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>;
+    protected onMount(): void;
     unmount(): void;
     focus(): void;
     blur(): void;
@@ -29,6 +30,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

@@ -7,4 +7,5 @@ export declare class IframeCardExpirationMonth extends IframeCardElementBase imp
     compiledMask?: Masked;
     protected inputMaskOptions: FactoryArg;
     protected validate(masked: Masked): ElementMetadata;
+    protected onMount(): void;
 }

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;

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

@@ -1,2 +1,4 @@
-import { TokenizedCardMaskedData } from '../typings';
+import { HellgateCardScheme, TokenizedCardMaskedData } from '../typings';
+import { CardSchema } from './typings';
+export declare function mapHellgateSchemesToCardSchema(schemes: HellgateCardScheme[]): CardSchema[];
 export declare function getMaskedCardNumber(data: TokenizedCardMaskedData): string;

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;
+};