@vtex/faststore 0.0.5 → 0.0.6

package/dist/matter/card-entry/card-entry.d.ts

@@ -0,0 +1,120 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import "../../sdk/payment/submission-registry.js";
+import { CardCaptureNetwork } from "./card-capture.js";
+//#region src/matter/card-entry/card-entry.d.ts
+/**
+ * The new-card entry matter (specs/card-entry.md, T7 of the Credit Card epic;
+ * docs/features/credit-card/rfc.md § D2). Composes the `Field`/`Fieldset` particles and reuses
+ * `document-field`'s `applyMask` progressive mask engine to capture a card number, holder name,
+ * expiration, and CVV, with masks/required-ness driven by the network's server-driven validator
+ * config (T1) rather than hardcoded per network.
+ *
+ * This is the PCI-critical core of the credit-card feature: it is the **only** component that ever
+ * holds a full card number or CVV, and both live only in this component's local state — never a
+ * schema prop, a fragment field, an action payload, or a value handed to another component. It reads
+ * only the `card-capture` context (card-capture.tsx), so the checkout and the account compose it
+ * alike: it registers a capture, builds the card *inside* that closure, and hands it to the target
+ * the provider passes in — `sendPayments` at checkout, `savedCard.tokenize` in the account.
+ *
+ * Network detection is a pure, local computation (never waits on a server round-trip): the typed
+ * digits are tested against every method's `validator.numberRegex` on every keystroke, first match
+ * wins. The selection waits for a complete BIN (T190): only once the field holds eight digits does a
+ * match — on a genuine transition, or once the engine has released the BIN (T174) — publish those
+ * eight digits as the BIN (`setDraftBin`) and dispatch `selectMethod` to persist the selection
+ * server-side — both through `card-capture`'s `selection` member, so only at checkout. Below eight digits nothing is published or sent — see specs/card-entry.md
+ * Decisions 1 and 3, and specs/send-the-typed-bin-to-the.md, which adds the gate — except that the
+ * first keystroke off the new-card path records that path locally with `selectNewCard()`
+ * (specs/collapse-the-card-form-when-a.md, FR-10).
+ */
+export type CardEntryProps = {
+  /** `Fieldset.Legend` text. */
+  legend?: string;
+  numberLabel?: string;
+  numberPlaceholder?: string;
+  holderNameLabel?: string;
+  holderNamePlaceholder?: string;
+  expirationLabel?: string;
+  expirationPlaceholder?: string;
+  cvvLabel?: string;
+  cvvPlaceholder?: string;
+  /** Helper copy under the CVV field, rendered through `Field.Description` and linked to the
+   *  input via `aria-describedby`. An empty string renders nothing. Copy configuration only —
+   *  never the security code itself. */
+  cvvDescription?: string;
+  /** Shown on the number field when it is left blank. */
+  numberRequiredMessage?: string;
+  /** Shown on the number field for a Luhn-invalid PAN, or a Luhn-valid one that matches no
+   *  configured method (FR-3 — the same string covers both sites). */
+  numberInvalidMessage?: string;
+  /** Shown on the holder-name field when it is left blank and the detected method requires it. */
+  holderNameRequiredMessage?: string;
+  /** Shown on the expiration field when it is left blank and the detected method requires it. */
+  expirationRequiredMessage?: string;
+  /** Shown on the expiration field for a structurally malformed `MM/YY`. */
+  expirationInvalidMessage?: string;
+  /** Shown on the expiration field for a structurally valid `MM/YY` that has already passed. */
+  expirationExpiredMessage?: string;
+  /** Shown on the CVV field when it is left blank and the detected method requires it. */
+  cvvRequiredMessage?: string;
+  /** Shown on the CVV field for a value that fails the detected method's format. */
+  cvvInvalidMessage?: string;
+  /** Disables every field. */
+  disabled?: boolean;
+  className?: string;
+};
+/**
+ * First method whose `validator.numberRegex` admits `digits` as a BIN-level prefix, or `null`.
+ *
+ * N1: relaxing every store regex into a pure prefix test (F1, above) means two networks whose fixed
+ * prefixes *nest* — one network's whole discriminating prefix is itself a prefix of a different,
+ * longer network's real PAN — both keep "relax-matching" once the shorter network's fixed prefix is
+ * satisfied, including at the longer network's own full, syntactically valid length, where the exact,
+ * unrelaxed regex alone correctly discriminates by length. Left as pure first-match-wins over the
+ * relaxed test, the answer at full PAN length silently depends on which order the store's `methods`
+ * happen to arrive in — something this component does not control.
+ *
+ * The fix tries the **exact** regex first, across every method in `methods` order, and only falls back
+ * to the relaxed (prefix) match for input too short to satisfy any exact pattern yet. This restores the
+ * exact regex's authority the instant a full PAN is present, which resolves the nesting-prefix case
+ * above deterministically regardless of order. **It is not, however, order-independent in general**
+ * (T22, V2): two configured networks' exact patterns can both match the very same full-length input —
+ * e.g. a real Visa regex and an Elo BIN range both match `4011788888888888` (Elo is issued on
+ * Visa-range BINs) — and `exactMatch` below is a plain `methods.find(...)`, so **the first exact match
+ * in `methods` order wins the tie**. This is pre-existing (pre-N1 code used the same `find` over exact
+ * regexes) and is not introduced or fixed by N1; N1 only shrank how much of the input space stays
+ * order-dependent. A caller that needs a specific tie winner must order `methods` by specificity itself
+ * before calling — this function does not infer specificity from a regex. See also `resolveNumberMask`
+ * below: this function alone cannot help if the field's own mask capacity has already been capped
+ * narrower than the digit count an exact match needs to resolve, and see `resolveNetworkMethod` below
+ * `resolveNumberMask` (T22, V3/V4) for this component's own order-independent wrapper around the
+ * *relaxed*-fallback branch, which this component's own call sites use instead of calling this function
+ * directly.
+ */
+export declare function detectNetworkMethod(methods: readonly CardCaptureNetwork[], digits: string): CardCaptureNetwork | null;
+/**
+ * Standard Luhn checksum. Rejects non-digit strings and anything shorter than 12 digits — no real
+ * card network issues a PAN shorter than that.
+ */
+export declare function isValidLuhn(digits: string): boolean;
+/** `MM/YY` structural check: month 01–12, two-digit year. */
+export declare function isExpirationFormatValid(value: string): boolean;
+/**
+ * True when the printed `MM/YY` has not yet ended — cards are valid through the end of their
+ * printed month. `now` is injectable for deterministic tests.
+ */
+export declare function isExpirationInFuture(value: string, now?: Date): boolean;
+export declare const CARD_ENTRY_INVALID_DATA_CODE = "INVALID_CARD_DATA";
+/**
+ * The submission and pre-flight refusal for a card form the shopper cannot currently see (T74,
+ * Decision 5), and for a visible form's valid card under a persisted method that cannot take it: one
+ * this section does not serve, one that is not a card (T191, FR-13), or another card network than the
+ * typed number's (T191 fix round 1, finding R1). Distinct from `INVALID_CARD_DATA`: the card may be
+ * perfectly valid — the section is simply not on a method this form can pay it with. A fourth
+ * client-synthesized `CardCaptureError` in `matter/`, beside `CARD_ENTRY_INVALID_DATA_CODE`.
+ */
+export declare const CARD_ENTRY_COLLAPSED_CODE = "CARD_ENTRY_COLLAPSED";
+export declare const CardEntryDefinition: ComponentDefinition<CardEntryProps>;
+export declare function CardEntry({ legend, numberLabel, numberPlaceholder, holderNameLabel, holderNamePlaceholder, expirationLabel, expirationPlaceholder, cvvLabel, cvvPlaceholder, cvvDescription, numberRequiredMessage, numberInvalidMessage, holderNameRequiredMessage, expirationRequiredMessage, expirationInvalidMessage, expirationExpiredMessage, cvvRequiredMessage, cvvInvalidMessage, disabled, className }: CardEntryProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=card-entry.d.ts.map