@ozura/elements 1.0.2 → 1.1.0

package/dist/server/frame/protocol.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared postMessage protocol constants.
+ *
+ * PROTOCOL_VERSION must be incremented any time a breaking change is made to
+ * the postMessage message shape (new required fields, renamed types, removed
+ * fields, changed semantics). The SDK reads this value from OZ_FRAME_READY
+ * messages and warns when the frame and SDK are out of sync.
+ *
+ * Non-breaking additions (new optional fields, new message types that old
+ * frames can safely ignore) do NOT require a version bump.
+ */
+export declare const PROTOCOL_VERSION = 1;

package/dist/server/sdk/OzVault.d.ts

@@ -44,6 +44,8 @@ export declare class OzVault {
     private tokenizerReady;
     private _tokenizing;
     private _destroyed;
+    private _resetCount;
+    private _debug;
     private _tokenizeSuccessCount;
     private _maxTokenizeCalls;
     private boundHandleMessage;
@@ -155,6 +157,29 @@ export declare class OzVault {
      * Returns a token and cvcSession that can be passed to the Ozura Pay API.
      */
     createToken(options?: TokenizeOptions): Promise<TokenResponse>;
+    /**
+     * Clears all mounted element fields without tearing down the vault.
+     *
+     * Call this after a failed payment (e.g. card declined) to let the customer
+     * re-enter their details. The vault instance, tokenizer iframe, wax key, and
+     * tokenization budget counter are all preserved — no network calls are made.
+     *
+     * **Wax key session model:** by design, one wax key covers the full checkout
+     * session. The default `max_tokenize_calls: 3` supports two declined attempts
+     * and one final attempt on the same key. Do not call `vault.destroy()` and
+     * recreate the vault between declines — that unnecessarily re-mints the key
+     * and discards the remaining budget.
+     *
+     * @example
+     * try {
+     *   const { token, cvcSession } = await vault.createToken({ billing });
+     *   await chargeCard(token, cvcSession);
+     * } catch (err) {
+     *   vault.reset();       // clear fields; let customer re-enter
+     *   showError(err.message);
+     * }
+     */
+    reset(): void;
     /**
      * Tears down the vault: removes all element iframes, the tokenizer iframe,
      * and the global message listener. Call this when the checkout component
@@ -172,6 +197,30 @@ export declare class OzVault {
      * while avoiding spurious refreshes for brief tab-switches.
      */
     private handleVisibilityChange;
+    /**
+     * Emits a `[OzVault]`-prefixed entry to `console.log`. No-op when `debug` is
+     * not set. Never called with sensitive values — callers use presence flags only.
+     */
+    private log;
+    /**
+     * Returns a plain-object snapshot of the vault's current internal state.
+     * Safe to attach to bug reports — no wax keys, tokens, or billing data included.
+     *
+     * Available on all vault instances regardless of whether `debug` was enabled.
+     *
+     * @example
+     * console.log(vault.debugState());
+     * // {
+     * //   vaultId: 'vault-abc123',
+     * //   isReady: true,
+     * //   tokenizing: null,
+     * //   destroyed: false,
+     * //   waxKeyPresent: true,
+     * //   elements: ['cardNumber', 'expirationDate', 'cvv'],
+     * //   ...
+     * // }
+     */
+    debugState(): Record<string, unknown>;
     private mountTokenizerFrame;
     private handleMessage;
     /**

package/dist/server/types/index.d.ts

@@ -256,6 +256,24 @@ export interface VaultOptions {
      * }
      */
     appearance?: Appearance;
+    /**
+     * Enables structured debug logging to the browser console.
+     *
+     * When `true`, the vault emits a `[OzVault]`-prefixed `console.log` entry at
+     * every meaningful lifecycle event: vault creation, tokenizer readiness, element
+     * readiness, field changes, tokenization start/result/error, wax key refresh,
+     * tab-visibility refreshes, `reset()`, and `destroy()`.
+     *
+     * **No sensitive data is ever logged.** Wax keys, tokens, CVC sessions, and
+     * billing fields are represented only as boolean presence flags. Frame IDs and
+     * request IDs are truncated. Output is safe to paste directly into bug reports.
+     *
+     * Use `vault.debugState()` to capture a full snapshot of internal state at any
+     * point, regardless of whether `debug` is enabled.
+     *
+     * @default false
+     */
+    debug?: boolean;
 }
 /** Billing address. All string fields are validated to 1–50 characters. */
 export interface BillingAddress {
@@ -593,6 +611,8 @@ export interface TransactionQueryResponse {
 export type OzMessageType = 'OZ_FRAME_READY' | 'OZ_INIT' | 'OZ_UPDATE' | 'OZ_CLEAR' | 'OZ_CHANGE' | 'OZ_FOCUS' | 'OZ_BLUR' | 'OZ_RESIZE' | 'OZ_BEGIN_COLLECT' | 'OZ_FIELD_VALUE' | 'OZ_TOKENIZE' | 'OZ_TOKEN_RESULT' | 'OZ_TOKEN_ERROR' | 'OZ_FOCUS_REQUEST' | 'OZ_BLUR_REQUEST' | 'OZ_SET_CVV_LENGTH' | 'OZ_BANK_TOKENIZE' | 'OZ_BANK_TOKEN_RESULT' | 'OZ_TOKENIZE_CANCEL';
 export interface OzMessage {
     __oz: true;
+    /** Protocol version stamped by the frame on OZ_FRAME_READY. Read by the SDK to detect stale CDN frames. */
+    __ozVersion?: number;
     vaultId: string;
     type: OzMessageType;
     [key: string]: unknown;

package/dist/types/frame/elementFrame.d.ts

@@ -5,4 +5,73 @@
  * communicates with the host SDK via postMessage. Raw values NEVER leave this
  * file except when sent directly to the tokenizer frame (same-origin).
  */
-export {};
+/**
+ * Validates a US ABA routing number using the standard checksum algorithm.
+ * The checksum is: (3*(d1+d4+d7) + 7*(d2+d5+d8) + 1*(d3+d6+d9)) mod 10 === 0
+ */
+export declare function validateRoutingNumber(routing: string): boolean;
+export declare const ALLOWED_STYLE_PROPERTIES: Set<string>;
+export declare const BLOCKED_VALUE_PATTERNS: RegExp;
+/** Matches `url('https://...')` or `url(https://...)` with optional `format('woff2')`. */
+export declare const FONT_SRC_PATTERN: RegExp;
+export declare const CSS_BREAKOUT: RegExp;
+export declare function sanitizeCssString(value: string, maxLen: number): string;
+export declare function sanitizeCssToken(value: string, maxLen?: number): string;
+export declare class ElementFrame {
+    private elementType;
+    private vaultId;
+    private frameId;
+    private hostOrigin;
+    private rawValue;
+    private cardBrand;
+    private cvvMaxLength;
+    private _composing;
+    private _appliedBaseStyleKeys;
+    private _appliedStateStyleKeys;
+    private containerEl;
+    private inputEl;
+    private iconEl;
+    private liveRegion;
+    private options;
+    private _boundOnMessage;
+    constructor();
+    private buildDOM;
+    private getInputType;
+    private getAutocomplete;
+    private getDefaultPlaceholder;
+    private getAriaLabel;
+    private onInput;
+    private onKeydown;
+    private onFocus;
+    private onBlur;
+    private updateBrandIcon;
+    private isComplete;
+    private isValid;
+    private getError;
+    private emitChange;
+    private onMessage;
+    private placeholderStyleEl;
+    private applyOptions;
+    private applyStyles;
+    private static readonly PLACEHOLDER_INPUT_ID;
+    /** Clears all CSS properties that were applied from a state-style bucket
+     *  (focus, complete, or invalid), then restores any that exist in the base
+     *  style so that base values are not lost when transitioning between states. */
+    private clearStateStyles;
+    /** Clears stale state styles then re-applies the correct state bucket based
+     *  on current focus and validity. Used after a base-style update so the
+     *  on-screen state visual stays accurate without requiring user interaction. */
+    private reapplyStateStyles;
+    private applyPlaceholderStyles;
+    private fontsInjected;
+    private injectFonts;
+    /**
+     * Delivers this field's raw value to the tokenizer iframe via the MessagePort
+     * transferred in OZ_BEGIN_COLLECT. The port provides a direct channel that
+     * bypasses the merchant page entirely — no named-window lookup is needed.
+     */
+    private sendValueToTokenizer;
+    private sendResize;
+    private postToParent;
+    destroy(): void;
+}

package/dist/types/frame/protocol.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared postMessage protocol constants.
+ *
+ * PROTOCOL_VERSION must be incremented any time a breaking change is made to
+ * the postMessage message shape (new required fields, renamed types, removed
+ * fields, changed semantics). The SDK reads this value from OZ_FRAME_READY
+ * messages and warns when the frame and SDK are out of sync.
+ *
+ * Non-breaking additions (new optional fields, new message types that old
+ * frames can safely ignore) do NOT require a version bump.
+ */
+export declare const PROTOCOL_VERSION = 1;

package/dist/types/sdk/OzVault.d.ts

@@ -44,6 +44,8 @@ export declare class OzVault {
     private tokenizerReady;
     private _tokenizing;
     private _destroyed;
+    private _resetCount;
+    private _debug;
     private _tokenizeSuccessCount;
     private _maxTokenizeCalls;
     private boundHandleMessage;
@@ -155,6 +157,29 @@ export declare class OzVault {
      * Returns a token and cvcSession that can be passed to the Ozura Pay API.
      */
     createToken(options?: TokenizeOptions): Promise<TokenResponse>;
+    /**
+     * Clears all mounted element fields without tearing down the vault.
+     *
+     * Call this after a failed payment (e.g. card declined) to let the customer
+     * re-enter their details. The vault instance, tokenizer iframe, wax key, and
+     * tokenization budget counter are all preserved — no network calls are made.
+     *
+     * **Wax key session model:** by design, one wax key covers the full checkout
+     * session. The default `max_tokenize_calls: 3` supports two declined attempts
+     * and one final attempt on the same key. Do not call `vault.destroy()` and
+     * recreate the vault between declines — that unnecessarily re-mints the key
+     * and discards the remaining budget.
+     *
+     * @example
+     * try {
+     *   const { token, cvcSession } = await vault.createToken({ billing });
+     *   await chargeCard(token, cvcSession);
+     * } catch (err) {
+     *   vault.reset();       // clear fields; let customer re-enter
+     *   showError(err.message);
+     * }
+     */
+    reset(): void;
     /**
      * Tears down the vault: removes all element iframes, the tokenizer iframe,
      * and the global message listener. Call this when the checkout component
@@ -172,6 +197,30 @@ export declare class OzVault {
      * while avoiding spurious refreshes for brief tab-switches.
      */
     private handleVisibilityChange;
+    /**
+     * Emits a `[OzVault]`-prefixed entry to `console.log`. No-op when `debug` is
+     * not set. Never called with sensitive values — callers use presence flags only.
+     */
+    private log;
+    /**
+     * Returns a plain-object snapshot of the vault's current internal state.
+     * Safe to attach to bug reports — no wax keys, tokens, or billing data included.
+     *
+     * Available on all vault instances regardless of whether `debug` was enabled.
+     *
+     * @example
+     * console.log(vault.debugState());
+     * // {
+     * //   vaultId: 'vault-abc123',
+     * //   isReady: true,
+     * //   tokenizing: null,
+     * //   destroyed: false,
+     * //   waxKeyPresent: true,
+     * //   elements: ['cardNumber', 'expirationDate', 'cvv'],
+     * //   ...
+     * // }
+     */
+    debugState(): Record<string, unknown>;
     private mountTokenizerFrame;
     private handleMessage;
     /**

package/dist/types/types/index.d.ts

@@ -256,6 +256,24 @@ export interface VaultOptions {
      * }
      */
     appearance?: Appearance;
+    /**
+     * Enables structured debug logging to the browser console.
+     *
+     * When `true`, the vault emits a `[OzVault]`-prefixed `console.log` entry at
+     * every meaningful lifecycle event: vault creation, tokenizer readiness, element
+     * readiness, field changes, tokenization start/result/error, wax key refresh,
+     * tab-visibility refreshes, `reset()`, and `destroy()`.
+     *
+     * **No sensitive data is ever logged.** Wax keys, tokens, CVC sessions, and
+     * billing fields are represented only as boolean presence flags. Frame IDs and
+     * request IDs are truncated. Output is safe to paste directly into bug reports.
+     *
+     * Use `vault.debugState()` to capture a full snapshot of internal state at any
+     * point, regardless of whether `debug` is enabled.
+     *
+     * @default false
+     */
+    debug?: boolean;
 }
 /** Billing address. All string fields are validated to 1–50 characters. */
 export interface BillingAddress {
@@ -593,6 +611,8 @@ export interface TransactionQueryResponse {
 export type OzMessageType = 'OZ_FRAME_READY' | 'OZ_INIT' | 'OZ_UPDATE' | 'OZ_CLEAR' | 'OZ_CHANGE' | 'OZ_FOCUS' | 'OZ_BLUR' | 'OZ_RESIZE' | 'OZ_BEGIN_COLLECT' | 'OZ_FIELD_VALUE' | 'OZ_TOKENIZE' | 'OZ_TOKEN_RESULT' | 'OZ_TOKEN_ERROR' | 'OZ_FOCUS_REQUEST' | 'OZ_BLUR_REQUEST' | 'OZ_SET_CVV_LENGTH' | 'OZ_BANK_TOKENIZE' | 'OZ_BANK_TOKEN_RESULT' | 'OZ_TOKENIZE_CANCEL';
 export interface OzMessage {
     __oz: true;
+    /** Protocol version stamped by the frame on OZ_FRAME_READY. Read by the SDK to detect stale CDN frames. */
+    __ozVersion?: number;
     vaultId: string;
     type: OzMessageType;
     [key: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozura/elements",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "PCI-compliant card tokenization SDK for the Ozura Vault — collect card data in iframe-isolated fields and tokenize without PCI scope",
   "main": "dist/oz-elements.umd.js",
   "module": "dist/oz-elements.esm.js",