@ozura/elements 1.0.2-next.9 → 1.1.0-next.21

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 {

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

@@ -27,6 +27,7 @@ export declare class ElementFrame {
     private cvvMaxLength;
     private _composing;
     private _appliedBaseStyleKeys;
+    private _appliedStateStyleKeys;
     private containerEl;
     private inputEl;
     private iconEl;
@@ -53,6 +54,14 @@ export declare class ElementFrame {
     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;

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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozura/elements",
-  "version": "1.0.2-next.9",
+  "version": "1.1.0-next.21",
   "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",