@wirexapp/card-sdk-core 1.1.0-beta.4 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,241 @@
 # @wirexapp/card-sdk-core
 
+## 1.1.0
+
+### Minor Changes
+
+- 8097859: CVV entry masking — show / hide what was typed into the top-up CVV field. The
+  CVV has always been masked as it is typed (a password input); this adds the
+  reveal element's masking model to that input, for both collect variants
+  (`createCardTopUpFields`, `createCardTopUpForm`). The card number is not
+  affected, and with no option passed nothing changes.
+
+  - `masked` (boolean, default `true`) — the state at mount; `false` starts the
+    field shown.
+  - `maskToggle: 'button' | 'text' | 'none'` (default `'none'`) — an in-frame
+    control at the field's right edge: the reveal's eye / eye-off icon, or a
+    text button from the new collect strings `show` / `hide`. It is the same
+    control the reveal rows draw (one module in the frames), themed by the same
+    `copyIconSize` / `colorCopyIcon` / `colorCopyIconHover` tokens. No `'row'`
+    mode: a tap on an input has to focus it. The toggle never takes the focus
+    from the field; the value and the caret stay.
+  - `maskAfter` (ms, default never) — shown digits re-mask from the frame,
+    counted from the moment they are visible.
+  - `setMasked(boolean)` on `PciCollectElement` and `PciCollectGroup` (the group
+    forwards to its `cvv` field) — host control in place, safe before `mount()`
+    resolves and after `destroy()`. Host→frame event `collect-set-masked`, sent
+    with the reply-less `PciFrameChannel.post()`.
+  - `onMaskedChange({ masked, reason })` — the state the frame applied, once at
+    mount (`'init'`) and after every change (`'user'`, `'host'`, `'timeout'`).
+    Frame→host event `collect-masked-changed`: a boolean and a reason, never
+    the value.
+  - `PciCollectGroup.field(name, options?)` takes the same masking options for
+    the `cvv` field (they win over the group config's).
+  - React: `CardCvvField` takes `masked` (live — forwarded in place, never a
+    remount), `maskToggle`, `maskAfter` and `onMaskedChange`. Mirroring
+    `onMaskedChange` into the state `masked` is rendered from is safe — the rule
+    is "when in doubt, mask": a hide is always sent, a show is not sent when it
+    is the echo of the frame's own "shown" report.
+
+  No reveal gate (`onRevealRequested`) on the input — the digits are the user's
+  own typing — and no `maskedPlaceholder`: the masked rendering is the browser's
+  password bullet. Microsoft Edge's built-in reveal button is now hidden in the
+  CVV field (it showed the digits behind the frame's state); the SDK's toggle
+  and `setMasked()` are the only ways to show them, in every browser alike.
+  The OCT package's surface is unchanged (its profile has no CVV). Additive
+  within protocol v1: frames that predate this ignore the three options and
+  `collect-set-masked`, keep the CVV masked and never send
+  `collect-masked-changed`; ship the frames first.
+
+- 901cddf: Collect failures. `PciFrameRequestError` gains `code`,
+  `retryable` and `reason`: the mobile SDK's failure payload
+  (`WirexCollectErrorPayload`), with the same values classified by the same rules.
+
+  - `code` is one of a frozen set: `unauthorized`, `actionRequired`,
+    `updateRequired`, `invalidInput`, `temporary`, `failed`. It is typed as the
+    `PciFrameErrorCode` union, so a `switch` over it checks exhaustively.
+  - `retryable` says whether sending the request again is safe.
+  - `reason` is present where one `code` has two remedies: `invalidInput` with
+    `cardAlreadyLinked` (enter another card) or `cardLimitReached` (remove one
+    first). The set grows; handle an unknown value.
+
+  The frame classifies a tokenize failure by the backend's business code on a 400
+  (`0243`, `0366`), otherwise by the HTTP status. A request without an answer is
+  `temporary`; a `Validation failed — …` reply is `invalidInput`. Messages are
+  unchanged. Older frames send none of the fields (`code` and `reason` undefined,
+  `retryable` false): ship the frames first.
+
+- cc46627: Protocol (additive within v1): every frame init config accepts an optional `diagnostics.userId` — an opaque, host-chosen correlation id the frames attach as `user.id` to the error events they report to Wirex (`PciDiagnosticsInit`, docs/ERROR-TRACKING.md §5, §7). Validated in-frame; never an email or wallet address. The wallet documents honour it from this release; the host-side packages do not send it yet (Phase 3).
+- 390c416: New `fontSmoothing` appearance token — `'auto'` (default, as today) or
+  `'antialiased'`: the frame document gets `-webkit-font-smoothing:
+antialiased` and `-moz-osx-font-smoothing: grayscale`. Host pages whose
+  global CSS antialiases the body (Mantine, Tailwind preflight, most design
+  systems) otherwise sit next to frame text that macOS renders visibly heavier
+  at the same family, size and weight. Applies to the collect, reveal and
+  wallet frames; enumerated and re-validated in the frame, and an older frame
+  drops the token and keeps `auto`.
+- b43affc: Wallet availability tells WHY Google Pay is unavailable: `PciWalletAvailability`
+  gains `googlePayState` — `ready` / `handoff` / `needs_card` / `unavailable`.
+  `needs_card` is an Android device where Google Pay works but no card in Google
+  Wallet on the phone qualifies for the cryptogram-only top-up (the probe's
+  cryptogram check fails, a `PAN_ONLY` capability check passes, and the WebView
+  is at or above the config's `min_webview_version`). A host may keep the wallet
+  row and send the user to Google Wallet instead of checkout.
+
+  Additive: `googlePay` keeps meaning "can pay here", so hosts that ignore the
+  new field behave as before. `checkWalletAvailability` persists the field and
+  derives it from the booleans when an older frames deployment omits it.
+
+- d4654e9: Reveal `copy` option — `'button'` (default: the icon button, as today),
+  `'row'` (the whole row is one copy control: a real `<button>`, no icon, no
+  reserved width; the copied state shows on the value and is announced to
+  assistive tech) or `'none'` (no copy affordance; the value stays selectable
+  text). Copy still runs inside the frame and `onCopied` still carries the
+  field name only. Enumerated and re-validated in the frame; an older frame
+  ignores the option and renders the icon button.
+
+  Reveal `showLabels` option (default `true`). `false` renders no label
+  element at all — not an empty one — so a row is exactly as tall as its
+  value; the label string becomes the value's `aria-label`, and the icon copy
+  button's name carries the field ("Card Number: Copy"). With `copy:
+'button'` such a row is floored at the icon's hit target (`copyIconSize` +
+  12px) so adjacent buttons never overlap. Replaces the `fontSizeLabel: '0px'`
+  / `lineHeightLabel: '0px'` workaround.
+
+  Reveal `rowStyle` option — `'plain'` (default, as today) or `'boxed'`: each
+  row becomes a pill drawn from the box tokens the collect inputs already use
+  (`colorBackground`, `colorBorder`, `borderRadius`, `borderWidth`,
+  `controlMinHeight`; 16px horizontal padding, `spacingUnit` vertical,
+  `fieldGap` between pills), so a border hugs the value instead of the
+  iframe. Deliberately opt-in: those tokens already reach reveal frames from
+  hosts that share one appearance object with collect, so honouring them on
+  presence would have restyled existing reveal rows.
+
+  Reveal `layout` option — `'column'` (default) or `'row'`: the frame's
+  fields sit side by side with equal widths, separated by the new `fieldGap`
+  appearance token (length; default `12px`; also the gap between `'boxed'`
+  pills). `fields: ['expiry', 'cvv']` with `layout: 'row'` is one frame and
+  one `/details` call where two single-field frames called it twice with the
+  same action token. Frame-wide on purpose: a mixed arrangement is two
+  frames, because a nested `fields` shape would not be ignorable by older
+  frames.
+
+  New `wordSpacing` appearance token (length grammar): extra space between
+  the card number's four-digit groups in the reveal frame — the value is
+  still chunked with single spaces, and no other row is affected. Reveal
+  `fields` entries are now validated against the known row names (unknown
+  entries are dropped instead of rendering an `undefined` label).
+
+- 417ab29: Reveal masking — show/hide each sensitive value in place (WPAY-5064). The
+  masked state is per row (number, expiry, CVV, PIN; never the cardholder) and
+  lives in the frame; while masked the value TEXT is replaced (card number:
+  one glyph per digit except the last four; expiry `••/••`; CVV / PIN fully),
+  with the same character count so the row keeps its height. The values are
+  still fetched once at mount under the step-up and the copy control still
+  copies the real value — masking is a display aid, not a second
+  authorisation. Two things change the state:
+
+  - the USER, through an opt-in in-frame control: `maskToggle` (`'button'` =
+    eye / eye-off icon, themed by the `copyIcon*` tokens; `'text'` = a text
+    button from the new `show` / `hide` strings, sized to the wider word;
+    `'row'` = the value itself; default `'none'`), with `maskToggleByField`
+    overrides;
+  - the HOST, through `masked` at mount (`true`, or a per-row map such as
+    `{ cvv: true, pin: true }`) and `PciRevealElement.setMasked(boolean | map)`
+    later — no refetch, no new `actionToken` (host→frame event
+    `reveal-set-masked`, sent with the new reply-less `PciFrameChannel.post()`).
+
+  `onMaskedChange` / `reveal-masked-changed` reports the state of every
+  rendered maskable row (never the cardholder) after every change with
+  `{ masked, field?, reason }` (`'init'`,
+  `'user'`, `'host'`, `'timeout'`). `maskAfter` (ms, a number or a per-row map;
+  default never) re-masks a shown row from the frame; `onRevealRequested`
+  gates revealing: the toggle then only asks (`reveal-requested { field }`)
+  and the host reveals with `setMasked({ [field]: false })`. React: the
+  `masked` prop of `CardReveal` is live (forwarded in place, a map compared by
+  value); `onMaskedChange` and `onRevealRequested` are props. New string
+  `maskedPlaceholder` (the glyph; default `•`). Older frames ignore every
+  masking option and show the values: ship the frames first.
+
+  Reveal copy control — `copy: 'text'` renders the `copy` / `copied` strings
+  as a text button (the same shape set as `maskToggle`), and `copyByField`
+  overrides `copy` per row (`{ pin: 'none' }` keeps the icon button everywhere
+  but the PIN). Each entry is validated in the frame; an invalid entry leaves
+  that row on `copy`; older frames ignore the map. `copy: 'none'` keeps its
+  meaning (no control, the value stays selectable text).
+
+  Frames: the reveal presentation options are now resolved in one pure module
+  (`revealOptions.ts`) with unit tests; `fields` that is not an array is
+  ignored instead of thrown on; a row's side controls (toggle, copy) are
+  siblings of the cell, so `copy: 'row'` and a toggle button combine.
+
+- 1d89a12: Wallet polish: `checkWalletAvailability` gains a persistent
+  stale-while-revalidate `cache` option (Storage-shaped adapter,
+  localStorage by default, `null` to disable); the checkout popup centers
+  over the opener window; the payment-sheet's billing contact, cardholder
+  name and Apple transaction id ride the token payload as optional fields
+  (collected only when the provider config requests billing).
+- 5f67be4: Wallet checkout polish: loading skeleton + popup page padding; the popup
+  carries `appearance` in the URL fragment so the pre-quote skeleton renders
+  themed; privacy-only legal line with a partner-configurable
+  `branding.privacyUrl` (https-only, validated in-frame, Wirex policy
+  fallback); Google Pay button draws the design pill radius natively; fee row
+  rounds up to the minor unit (host-app parity).
+- 33b4595: New wallet frame mode `wallet-preview` (`PciWalletPreviewInitConfig`): Google's
+  own Google Pay sheet with no price (`NOT_CURRENTLY_KNOWN`), for the probe's
+  `needs_card` — a phone where Google Pay works but Google Wallet holds no card
+  the top-up accepts. No quote and no backend call; the sheet's result is dropped
+  in the frame and the host hears only how it closed (`wallet-preview-closed`,
+  `PciWalletPreviewOutcome`) and, with `autoOpen`, whether it opened without a tap
+  (`wallet-preview-auto`). `PciFrameDocument` gains `wallet-preview`. Additive.
+- 731da3e: Wallet checkout TOKEN MODE (WPAY-4431): pass the backend's short-lived top-up
+  token as `auth.checkoutToken` and the hosted checkout executes the top-up
+  itself, reporting `onExecuted` / `onExecuteFailed` (`wallet-executed` /
+  `wallet-execute-failed` on the wire) — the wallet payment token never leaves
+  the frame. Legacy tokenize-and-return (`onToken`) is unchanged without `auth`.
+
+  Token mode also brings Google Pay to desktop (`googlePayHandoff: 'qr' | 'none'`,
+  probe flag `googlePayHandoff`): the frame draws a QR that carries the checkout
+  itself — the token, the quote and the estimate's `provider` name (new init /
+  `arm()` / `update()` field) — and an Android phone opens the same checkout
+  top-level, pays and executes. Nothing is stored on the frames service and the
+  desktop never learns the outcome: hosts reconcile by their own status reads
+  after `wallet-state: handoff-pending`. `arm(quote, config, auth?, provider?)` /
+  `update(quote, config?, auth?, provider?)`; `wallet-update` carries `auth` and
+  `provider`; new `wallet-state` values `executing`, `handoff-pending`.
+
+  `buildWalletLaunchFragment` / `buildWalletLaunchUrl` (core) build the same
+  compact fragment for a Chrome Custom Tab launch (`#t=&e=&s=&p=[&r=]`); the page
+  resolves the provider block from the public BaaS config by name.
+
+### Patch Changes
+
+- 274c69f: Fixed: the frames rendered as solid white rectangles in host pages that declare
+  `<meta name="color-scheme" content="dark">` (or `light dark` with dark
+  preferred) — typical of hybrid-app shells and dark-themed sites. The SDK set
+  `color-scheme: normal` on the iframe element; Chromium resolves `normal` from
+  the host's meta, so under a dark host the element became dark while the frame
+  document is light, and on that mismatch the browser paints the frame's canvas
+  opaque (CSS Color Adjust). The iframe element is now explicitly
+  `color-scheme: light`, matching the frame documents, which now declare
+  `:root { color-scheme: light }` as well — the frames stay transparent under any
+  host scheme. Hosts that set their dark theme through CSS alone were never
+  affected. The SDK change alone removes the mismatch for an updated host; the
+  frame-document change makes the pair explicit and independent of any meta.
+- a629a98: Wallet checkout return link: `returnUrl` (`buildWalletLaunchUrl` → `r`) may
+  now be your app's own scheme (`com.partner.app:/wallet/return`) as well as an
+  `https` App Link / Universal Link. Only the schemes a browser would execute in
+  the checkout's own origin (`javascript:`, `data:`, `blob:`, …),
+  browser-internal ones and cleartext `http:` are refused —
+  `buildWalletLaunchFragment` throws a `TypeError` on those, and the frame
+  ignores them. New exports `resolveWalletReturnUrl` and
+  `PCI_WALLET_RETURN_URL_BLOCKED_SCHEMES`.
+
+  The frames (service) must be deployed for an app scheme to be offered; an SDK
+  built before this release already passes any `returnUrl` through, so the
+  frames deployment alone enables the change — this release only adds the
+  early validation and the documentation.
+
 ## 1.1.0-beta.4
 
 ### Minor Changes

package/dist/collectElement.d.ts

@@ -1,11 +1,48 @@
-import type { PciAppearance, PciCollectChangeState, PciCollectProfile, PciFrameStrings, PciTokenizeOctResult, PciTokenizeTopUpResult } from './protocol.js';
+import type { PciAppearance, PciCollectChangeState, PciCollectMaskedReason, PciCollectMaskToggleMode, PciCollectProfile, PciFrameStrings, PciTokenizeOctResult, PciTokenizeTopUpResult } from './protocol.js';
 export interface PciCollectAuth {
     /** Called right before every backend hop so the frame always gets a fresh
      *  access token. By design the frame authenticates with the caller's bearer —
      *  the host passes its own user's bearer. There is no publishable-key layer. */
     getBearerToken: () => Promise<string>;
 }
-export interface PciCollectElementConfig {
+/** `onMaskedChange` payload: whether the CVV input is masked after a change
+ *  and who made it — the mount report (`'init'`), the user's in-frame toggle
+ *  (`'user'`), your `setMasked()` (`'host'`) or the `maskAfter` timer
+ *  (`'timeout'`). A boolean and a reason — never the value. */
+export interface PciCollectMaskedChange {
+    masked: boolean;
+    reason: PciCollectMaskedReason;
+}
+/**
+ * Masking of the CVV input while the user types — the same options on the
+ * single-form element and the per-field group. The card number is never
+ * masked; a profile without a CVV (`oct-destination`) ignores all of this.
+ */
+export interface PciCollectMaskConfig {
+    /** Start with the CVV masked (default `true` — the digits are bullets as
+     *  they are typed, as before this option existed). `false` starts it
+     *  shown. The state lives in the frame; the user's `maskToggle` and your
+     *  `setMasked()` change it in place — the value, the caret and the focus
+     *  stay. Read at mount. */
+    masked?: boolean;
+    /** The in-frame show/hide control at the field's right edge (default
+     *  `'none'`: no control — today's field). `'button'` — an eye / eye-off
+     *  icon, the same control and `copyIcon*` tokens as the reveal element's;
+     *  `'text'` — a text button from the `show` / `hide` strings. Read at
+     *  mount. */
+    maskToggle?: PciCollectMaskToggleMode;
+    /** Re-mask a shown CVV after this many milliseconds, counted from the
+     *  moment typed digits are visible; masking it earlier cancels the timer.
+     *  Default: never. Reported through `onMaskedChange` with reason
+     *  `'timeout'`. Read at mount. */
+    maskAfter?: number;
+    /** The CVV input's masked state as the frame applied it: once at mount,
+     *  then after every change. A frame deployment that predates CVV masking
+     *  never calls it (and keeps the field masked) — that is how you can
+     *  tell. */
+    onMaskedChange?: (event: PciCollectMaskedChange) => void;
+}
+export interface PciCollectElementConfig extends PciCollectMaskConfig {
     profile: PciCollectProfile;
     auth: PciCollectAuth;
     appearance?: PciAppearance;
@@ -46,8 +83,17 @@ export interface PciCollectTokenizer {
 export declare class PciCollectElement implements PciCollectTokenizer {
     private readonly config;
     private readonly channel;
+    private readonly mask;
     constructor(frameUrl: string, config: PciCollectElementConfig);
     mount(container: HTMLElement): Promise<void>;
+    /** Mask (`true`) or show (`false`) the CVV input in place — the value,
+     *  the caret and the focus stay where they are. Safe to call before
+     *  `mount()` resolves (the last value is applied once the frame is
+     *  initialized) and after `destroy()` (ignored). The frame confirms
+     *  through `onMaskedChange` when the state actually changed; a profile
+     *  without a CVV, and a frame deployment that predates CVV masking,
+     *  ignore it. */
+    setMasked(masked: boolean): void;
     /** Profile `topup`: link a new external top-up card. */
     tokenizeTopUp(params: TokenizeTopUpParams): Promise<PciTokenizeTopUpResult>;
     /** Profile `oct-destination`: tokenize a payout destination card (no CVV). */

package/dist/collectElement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collectElement.d.ts","sourceRoot":"","sources":["../src/collectElement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EAEjB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B;;oFAEgF;IAChF,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE;QACd,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,4BAA4B;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;4DAC4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC5E,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC7F;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,mBAAmB;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB;IAQvD,KAAK,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBlD,wDAAwD;IAClD,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAsBjF,8EAA8E;IACxE,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkBjG,OAAO,IAAI,IAAI;CAGhB"}
+{"version":3,"file":"collectElement.d.ts","sourceRoot":"","sources":["../src/collectElement.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EAEjB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B;;oFAEgF;IAChF,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED;;;+DAG+D;AAC/D,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;+BAI2B;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;iBAIa;IACb,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC;;;sCAGkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;gBAGY;IACZ,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE;QACd,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,4BAA4B;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;4DAC4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC5E,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC7F;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,mBAAmB;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;gBAE7B,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB;IAYvD,KAAK,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBlD;;;;;;qBAMiB;IACjB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAIhC,wDAAwD;IAClD,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAsBjF,8EAA8E;IACxE,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkBjG,OAAO,IAAI,IAAI;CAIhB"}

package/dist/collectElement.js

@@ -1,3 +1,4 @@
+import { CollectMaskSender } from './collectMask.js';
 import { PciFrameChannel } from './frameChannel.js';
 /**
  * Card-entry element. Renders PAN/expiry/CVV/name (profile `topup`) or PAN
@@ -9,9 +10,13 @@ export class PciCollectElement {
     constructor(frameUrl, config) {
         this.config = config;
         this.channel = new PciFrameChannel(frameUrl);
+        this.mask = new CollectMaskSender(this.channel);
         this.channel.onMessage(message => {
             if (message.type === 'change')
                 config.onChange?.(message.state);
+            if (message.type === 'collect-masked-changed') {
+                config.onMaskedChange?.({ masked: message.masked, reason: message.reason });
+            }
         });
     }
     async mount(container) {
@@ -27,8 +32,22 @@ export class PciCollectElement {
                 auth,
                 appearance: this.config.appearance,
                 strings: this.config.strings,
+                masked: this.config.masked,
+                maskToggle: this.config.maskToggle,
+                maskAfter: this.config.maskAfter,
             },
         });
+        this.mask.open();
+    }
+    /** Mask (`true`) or show (`false`) the CVV input in place — the value,
+     *  the caret and the focus stay where they are. Safe to call before
+     *  `mount()` resolves (the last value is applied once the frame is
+     *  initialized) and after `destroy()` (ignored). The frame confirms
+     *  through `onMaskedChange` when the state actually changed; a profile
+     *  without a CVV, and a frame deployment that predates CVV masking,
+     *  ignore it. */
+    setMasked(masked) {
+        this.mask.send(masked);
     }
     /** Profile `topup`: link a new external top-up card. */
     async tokenizeTopUp(params) {
@@ -71,6 +90,7 @@ export class PciCollectElement {
         });
     }
     destroy() {
+        this.mask.close();
         this.channel.destroy();
     }
 }

package/dist/collectElement.js.map

@@ -1 +1 @@
-{"version":3,"file":"collectElement.js","sourceRoot":"","sources":["../src/collectElement.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collectElement.js","sourceRoot":"","sources":["../src/collectElement.ts"],"names":[],"mappings":"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"}

package/dist/collectGroup.d.ts

@@ -1,6 +1,6 @@
-import type { PciCollectAuth, PciCollectTokenizer, TokenizeOctDestinationParams, TokenizeTopUpParams } from './collectElement.js';
+import type { PciCollectAuth, PciCollectMaskConfig, PciCollectTokenizer, TokenizeOctDestinationParams, TokenizeTopUpParams } from './collectElement.js';
 import type { PciAppearance, PciCollectChangeState, PciCollectFieldName, PciCollectProfile, PciFrameStrings, PciTokenizeOctResult, PciTokenizeTopUpResult } from './protocol.js';
-export interface PciCollectGroupConfig {
+export interface PciCollectGroupConfig extends PciCollectMaskConfig {
     profile: PciCollectProfile;
     auth: PciCollectAuth;
     appearance?: PciAppearance;
@@ -8,6 +8,15 @@ export interface PciCollectGroupConfig {
     /** Aggregated validity/brand across all mounted fields (never card values). */
     onChange?: (state: PciCollectChangeState) => void;
 }
+/**
+ * Options of ONE field, passed to `field(name, options)`. Today only the
+ * `cvv` field has any — its masking options — and each entry given here wins
+ * over the group config's for that field; other fields ignore them. The
+ * group config is the usual place (it reads the same for the single-form
+ * element); this is for a wrapper that owns one field, not the group — the
+ * React `CardCvvField` passes its props here.
+ */
+export type PciCollectFieldOptions = PciCollectMaskConfig;
 /** Handle for one field's iframe. The host mounts it into its own container. */
 export interface PciCollectField {
     mount(container: HTMLElement): Promise<void>;
@@ -26,9 +35,20 @@ export declare class PciCollectGroup implements PciCollectTokenizer {
     private readonly channels;
     private readonly states;
     private brand;
+    /** The `setMasked()` path of the CVV field's frame, while that field exists. */
+    private cvvMask;
     constructor(frameUrl: string, config: PciCollectGroupConfig);
-    /** Create a field element. Mount it into your own container for layout. */
-    field(name: PciCollectFieldName): PciCollectField;
+    /** Create a field element. Mount it into your own container for layout.
+     *  `options` — see `PciCollectFieldOptions` (the `cvv` field only). */
+    field(name: PciCollectFieldName, options?: PciCollectFieldOptions): PciCollectField;
+    /** Mask (`true`) or show (`false`) the CVV input in place — forwarded to
+     *  the CVV field's frame; the value, the caret and the focus stay. A no-op
+     *  while no CVV field exists (not created yet, destroyed, or a profile
+     *  without one); called between `field('cvv')` and the end of its
+     *  `mount()`, the last value is applied once the frame is initialized. The
+     *  frame confirms through `onMaskedChange` when the state actually
+     *  changed. */
+    setMasked(masked: boolean): void;
     private emitChange;
     private aggregator;
     private otherFields;

package/dist/collectGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collectGroup.d.ts","sourceRoot":"","sources":["../src/collectGroup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,4BAA4B,EAC5B,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EACV,aAAa,EAEb,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAUpB,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACnD;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,IAAI,IAAI,CAAC;CACjB;AAOD;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,mBAAmB;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmD;IAC5E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkF;IACzG,OAAO,CAAC,KAAK,CAA2B;gBAE5B,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB;IAK3D,2EAA2E;IAC3E,KAAK,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe;IAsCjD,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;IAIb,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAuB3E,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAmBjG,OAAO,IAAI,IAAI;CAIhB"}
+{"version":3,"file":"collectGroup.d.ts","sourceRoot":"","sources":["../src/collectGroup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,4BAA4B,EAC5B,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EACV,aAAa,EAEb,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAapB,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAE1D,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,IAAI,IAAI,CAAC;CACjB;AAOD;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,mBAAmB;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmD;IAC5E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkF;IACzG,OAAO,CAAC,KAAK,CAA2B;IACxC,gFAAgF;IAChF,OAAO,CAAC,OAAO,CAAkC;gBAErC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB;IAK3D;2EACuE;IACvE,KAAK,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe;IA2DvF;;;;;;mBAMe;IACf,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAIhC,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;IAIb,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAuB3E,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAmBjG,OAAO,IAAI,IAAI;CAMhB"}

package/dist/collectGroup.js

@@ -1,3 +1,4 @@
+import { CollectMaskSender } from './collectMask.js';
 import { PciFrameChannel } from './frameChannel.js';
 const FIELDS_BY_PROFILE = {
     topup: ['number', 'expiry', 'cvv', 'name'],
@@ -5,6 +6,8 @@ const FIELDS_BY_PROFILE = {
 };
 /** The aggregator field — the one that gathers siblings and POSTs. */
 const AGGREGATOR = 'number';
+/** The one field with a masked state — see `PciCollectMaskConfig`. */
+const MASKABLE = 'cvv';
 const randomId = () => typeof crypto !== 'undefined' && 'randomUUID' in crypto
     ? crypto.randomUUID()
     : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
@@ -20,11 +23,14 @@ export class PciCollectGroup {
         this.channels = new Map();
         this.states = {};
         this.brand = 'unknown';
+        /** The `setMasked()` path of the CVV field's frame, while that field exists. */
+        this.cvvMask = null;
         this.frameUrl = frameUrl;
         this.config = config;
     }
-    /** Create a field element. Mount it into your own container for layout. */
-    field(name) {
+    /** Create a field element. Mount it into your own container for layout.
+     *  `options` — see `PciCollectFieldOptions` (the `cvv` field only). */
+    field(name, options = {}) {
         if (!FIELDS_BY_PROFILE[this.config.profile].includes(name)) {
             throw new Error(`Field "${name}" is not part of the "${this.config.profile}" profile`);
         }
@@ -33,7 +39,17 @@ export class PciCollectGroup {
         }
         const channel = new PciFrameChannel(this.frameUrl, { group: this.groupId });
         this.channels.set(name, channel);
+        const mask = name === MASKABLE ? new CollectMaskSender(channel) : null;
+        if (mask)
+            this.cvvMask = mask;
         channel.onMessage(message => {
+            if (message.type === 'collect-masked-changed') {
+                // Only the CVV frame has a masked state to report.
+                if (mask) {
+                    (options.onMaskedChange ?? this.config.onMaskedChange)?.({ masked: message.masked, reason: message.reason });
+                }
+                return;
+            }
             if (message.type !== 'change')
                 return;
             Object.assign(this.states, message.state.fields);
@@ -52,15 +68,38 @@ export class PciCollectGroup {
                         groupId: this.groupId,
                         appearance: this.config.appearance,
                         strings: this.config.strings,
+                        // The masking options go to the CVV frame only; the field's own
+                        // options win over the group's, entry by entry.
+                        ...(mask
+                            ? {
+                                masked: options.masked ?? this.config.masked,
+                                maskToggle: options.maskToggle ?? this.config.maskToggle,
+                                maskAfter: options.maskAfter ?? this.config.maskAfter,
+                            }
+                            : {}),
                     },
                 });
+                mask?.open();
             },
             destroy: () => {
+                mask?.close();
+                if (mask && this.cvvMask === mask)
+                    this.cvvMask = null;
                 channel.destroy();
                 this.channels.delete(name);
             },
         };
     }
+    /** Mask (`true`) or show (`false`) the CVV input in place — forwarded to
+     *  the CVV field's frame; the value, the caret and the focus stay. A no-op
+     *  while no CVV field exists (not created yet, destroyed, or a profile
+     *  without one); called between `field('cvv')` and the end of its
+     *  `mount()`, the last value is applied once the frame is initialized. The
+     *  frame confirms through `onMaskedChange` when the state actually
+     *  changed. */
+    setMasked(masked) {
+        this.cvvMask?.send(masked);
+    }
     emitChange() {
         const active = FIELDS_BY_PROFILE[this.config.profile];
         const fields = {};
@@ -123,6 +162,8 @@ export class PciCollectGroup {
         });
     }
     destroy() {
+        this.cvvMask?.close();
+        this.cvvMask = null;
         for (const channel of this.channels.values())
             channel.destroy();
         this.channels.clear();

package/dist/collectGroup.js.map

@@ -1 +1 @@
-{"version":3,"file":"collectGroup.js","sourceRoot":"","sources":["../src/collectGroup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collectGroup.js","sourceRoot":"","sources":["../src/collectGroup.ts"],"names":[],"mappings":"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"}

package/dist/collectMask.d.ts

@@ -0,0 +1,24 @@
+import type { PciFrameChannel } from './frameChannel.js';
+/**
+ * The host→frame `collect-set-masked` path of ONE collect frame, shared by
+ * the single-form element and the per-field group (internal — not part of
+ * the package surface).
+ *
+ * A frame drops every event that arrives before its `init`, so a command
+ * given earlier is held and sent once `open()` says the init was
+ * acknowledged. Only the LAST one is kept: the state is a single boolean, an
+ * earlier command has nothing left to say. After `close()` everything is
+ * ignored, so `setMasked()` on a destroyed element is safe.
+ */
+export declare class CollectMaskSender {
+    private readonly channel;
+    private pending;
+    private opened;
+    private closed;
+    constructor(channel: PciFrameChannel);
+    send(masked: boolean): void;
+    /** The frame acknowledged its init: events reach it from now on. */
+    open(): void;
+    close(): void;
+}
+//# sourceMappingURL=collectMask.d.ts.map

package/dist/collectMask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectMask.d.ts","sourceRoot":"","sources":["../src/collectMask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,eAAe;IAIpC,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAS3B,oEAAoE;IACpE,IAAI,IAAI,IAAI;IAOZ,KAAK,IAAI,IAAI;CAId"}

package/dist/collectMask.js

@@ -0,0 +1,42 @@
+/**
+ * The host→frame `collect-set-masked` path of ONE collect frame, shared by
+ * the single-form element and the per-field group (internal — not part of
+ * the package surface).
+ *
+ * A frame drops every event that arrives before its `init`, so a command
+ * given earlier is held and sent once `open()` says the init was
+ * acknowledged. Only the LAST one is kept: the state is a single boolean, an
+ * earlier command has nothing left to say. After `close()` everything is
+ * ignored, so `setMasked()` on a destroyed element is safe.
+ */
+export class CollectMaskSender {
+    constructor(channel) {
+        this.pending = null;
+        this.opened = false;
+        this.closed = false;
+        this.channel = channel;
+    }
+    send(masked) {
+        if (this.closed)
+            return;
+        if (!this.opened) {
+            this.pending = masked;
+            return;
+        }
+        this.channel.post({ type: 'collect-set-masked', masked });
+    }
+    /** The frame acknowledged its init: events reach it from now on. */
+    open() {
+        if (this.closed || this.opened)
+            return;
+        this.opened = true;
+        if (this.pending !== null)
+            this.channel.post({ type: 'collect-set-masked', masked: this.pending });
+        this.pending = null;
+    }
+    close() {
+        this.closed = true;
+        this.pending = null;
+    }
+}
+//# sourceMappingURL=collectMask.js.map

package/dist/collectMask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectMask.js","sourceRoot":"","sources":["../src/collectMask.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,iBAAiB;IAM5B,YAAY,OAAwB;QAJ5B,YAAO,GAAmB,IAAI,CAAC;QAC/B,WAAM,GAAG,KAAK,CAAC;QACf,WAAM,GAAG,KAAK,CAAC;QAGrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,IAAI,CAAC,MAAe;QAClB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;YACtB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,oEAAoE;IACpE,IAAI;QACF,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;YAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACnG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;CACF"}