@p2pdotme/sdk 1.2.15 → 1.2.17

package/dist/country.d.ts

@@ -29,6 +29,8 @@ type CurrencyCode = (typeof CURRENCY)[keyof typeof CURRENCY];
  */
 declare const CURRENCY_CODES: [CurrencyCode, ...CurrencyCode[]];
 
+/** Joins an optional QR payload with typed fields (`qr||phone|cci`). */
+declare const PACKED_PAYMENT_ID_SEP = "||";
 interface PaymentIdFieldConfig {
     readonly key: string;
     readonly label: string;
@@ -36,6 +38,11 @@ interface PaymentIdFieldConfig {
     readonly displayLabel: string | null;
     readonly validate: (value: string) => boolean;
     readonly validationErrorMessage: string;
+    /**
+     * When true, an empty value is allowed. If every field is optional, at least
+     * one field must still be filled (see `validatePaymentIdFields`).
+     */
+    readonly optional?: boolean;
 }
 interface CountryOption {
     readonly country: string;
@@ -57,14 +64,97 @@ interface CountryOption {
     readonly isAlpha: boolean;
     readonly disabled: boolean;
     readonly disabledPaymentTypes: readonly string[];
+    /**
+     * Merchant/seller provides payment details by uploading a QR image.
+     * Distinct from PAY, where the buyer scans a QR. Default: false.
+     */
+    readonly uploadPaymentQR?: boolean;
+    /** Structural check for a standalone QR payload (no `||` pack). */
+    readonly validateQr?: (payload: string) => boolean;
+    /**
+     * Fill catalog fields from a validated QR (e.g. Yape/Plin phone in EMVCo).
+     * Only used when the typed fallback did not already set the key.
+     */
+    readonly hydrateFieldsFromQr?: (qr: string) => Partial<Record<string, string>>;
 }
 
 /** All supported countries with their currency metadata, payment methods, and display config. */
 declare const COUNTRY_OPTIONS: readonly CountryOption[];
+declare function getCountryOption(currency: CurrencyCode | null | undefined): CountryOption | undefined;
+/**
+ * Whether the merchant/seller provides payment details by uploading a QR image.
+ * Distinct from PAY (`disabledPaymentTypes`), where the buyer scans a QR.
+ */
+declare function uploadsPaymentQR(currency: CurrencyCode | null | undefined): boolean;
+/**
+ * Whether a stored payment ID may include a QR payload (`qr||fields` or
+ * standalone QR). Derived from `validateQr` — no extra flag.
+ */
+declare function usesPackedPaymentId(currency: CurrencyCode | null | undefined): boolean;
+/**
+ * Apps mount the catalog form (PackedPaymentInput): QR upload and/or
+ * more than one typed field.
+ */
+declare function usesCatalogPaymentForm(currency: CurrencyCode | null | undefined): boolean;
 
 /** Payment ID field configuration for each supported currency. */
 declare const PAYMENT_ID_FIELDS: Record<CurrencyCode, PaymentIdFieldConfig[]>;
 
+/**
+ * Yape/Plin EMVCo: country PE, currency 604, CRC-16/CCITT-FALSE.
+ * CRC is required on upload so we never persist a truncated screenshot.
+ * (PAY render in the merchant is looser; that path does not use this.)
+ */
+declare function validatePeruvianQr(payload: string): boolean;
+/**
+ * Suiche 7B / Pago Móvil collection QR: `base64?merchantId=NNNN&…`.
+ * The base64 is bank AES — we cannot decode phone/RIF from it, only the
+ * envelope. Reject packed `||` IDs so a stored compound string is never
+ * treated as a QR. Scan & Pay uses the looser `isPagoMovilQr` envelope.
+ */
+declare function validateVenezuelanQr(payload: string): boolean;
+
+/** Validates a 20-digit Peruvian CCI (spaces ignored). */
+declare function validatePeruvianCci(value: string): boolean;
+/**
+ * Validates a Yape/Plin phone: `9` + 8 digits, optional `+51` / `51` prefix.
+ */
+declare function validatePeruvianPhone(value: string): boolean;
+/**
+ * Validates a Peruvian payment key for the legacy single-field path.
+ * Accepts either a 20-digit CCI or a Yape/Plin phone number.
+ */
+declare function validatePeruvianPaymentKey(value: string): boolean;
+type PeruvianPaymentIdParts = {
+    qr: string | null;
+    phone: string | null;
+    cci: string | null;
+};
+/** QR payload and/or CCI and/or Yape/Plin phone. */
+declare function validatePeruvianPaymentId(value: string): boolean;
+
+/**
+ * Validates Venezuelan phone number for Pago Movil.
+ * Format: 04XX-XXXXXXX (11 digits starting with 04).
+ */
+declare function validateVenezuelanPhoneNumber(phoneNumber: string): boolean;
+/**
+ * Validates Venezuelan Cédula/RIF for Pago Móvil.
+ * Format: prefix (V|E|J|G|R|P) followed by digits.
+ * Includes natural persons (V), foreigners (E), companies (J), government (G),
+ * residual (R), and passport-linked accounts (P).
+ */
+declare function validateVenezuelanRif(rif: string): boolean;
+type VenezuelanPaymentIdParts = {
+    qr: string | null;
+    compound: string | null;
+};
+/**
+ * Accepts a Suiche 7B QR payload, the typed `phone|rif|bank` fallback,
+ * or both packed as `qr||phone|rif|bank`.
+ */
+declare function validateVenezuelanPaymentId(value: string): boolean;
+
 /**
  * Validates Argentine payment IDs (CBU, CVU, or Alias).
  * CBU/CVU: 22 digits with checksum. Alias: 6-20 alphanumeric characters.
@@ -139,18 +229,6 @@ declare function validateNigerianAccountNumber(accountNumber: string): boolean;
  */
 declare function validateNigerianAccountName(accountName: string): boolean;
 
-/**
- * Validates a Peruvian payment key for the SELL text-key path.
- * Accepts either a 20-digit CCI (Código de Cuenta Interbancario, spaces ignored)
- * or a Yape/Plin phone number (optional `+51`/`51` prefix, then `9` + 8 digits).
- */
-declare function validatePeruvianPaymentKey(value: string): boolean;
-/**
- * Validates a Yape/Plin EMVCo QR payload: parseable TLV, country (tag 58) `PE`,
- * currency (tag 53) `604` (PEN), and a matching CRC-16/CCITT-FALSE (tag 63).
- */
-declare function validatePeruvianQr(payload: string): boolean;
-
 /**
  * Validates a Philippine mobile number for InstaPay (GCash / Maya).
  * Mobile numbers are 10 digits starting with 9, and are commonly written
@@ -158,25 +236,52 @@ declare function validatePeruvianQr(payload: string): boolean;
  */
 declare function validatePhilippinePhoneNumber(phoneNumber: string): boolean;
 
-/**
- * Validates Venezuelan phone number for Pago Movil.
- * Format: 04XX-XXXXXXX (11 digits starting with 04).
- */
-declare function validateVenezuelanPhoneNumber(phoneNumber: string): boolean;
-/**
- * Validates Venezuelan Cédula. Format: "V" followed by digits.
- * Only natural-person cédulas (V) are accepted; legal-entity RIFs are not.
- */
-declare function validateVenezuelanRif(rif: string): boolean;
-
 /** Serializes multiple fields into a pipe-separated string. */
 declare function serializeCompoundPaymentId(...fields: string[]): string;
 /** Deserializes a pipe-separated payment ID into its component fields. */
 declare function deserializeCompoundPaymentId(paymentId: string): string[];
 /**
  * Formats a compound payment ID for display using optional labels.
- * Fields without a label are shown as-is, fields with a label are shown as "Label: value".
+ * Empty parts (optional fields left blank) are omitted.
  */
 declare function formatCompoundPaymentIdForDisplay(paymentId: string, labels: (string | null)[]): string;
+/**
+ * Validates a stored payment ID against `PAYMENT_ID_FIELDS`.
+ * Optional fields may be empty; if every field is optional, at least one must
+ * be filled. A legacy single token (no `|`) matches any one field's validator.
+ */
+declare function validatePaymentIdFields(fields: readonly PaymentIdFieldConfig[], paymentId: string): boolean;
+/**
+ * Splits a stored payment ID into per-field values for form hydration.
+ * A legacy single token is assigned to the first field whose validator matches.
+ */
+declare function assignPaymentIdToFieldValues(fields: readonly PaymentIdFieldConfig[], paymentId: string): Record<string, string>;
+declare function unpackPackedPaymentId(paymentId: string): {
+    qr: string;
+    rest: string;
+};
+/**
+ * QR blob from a stored payment ID, or `null` if none / invalid.
+ */
+declare function getStoredQrPayload(currency: CurrencyCode | null | undefined, paymentId: string | null | undefined): string | null;
+/**
+ * Builds a stored payment ID: optional validated QR packed with catalog fields.
+ */
+declare function packStoredPaymentId(currency: CurrencyCode, qr: string | null | undefined, fieldValues: Record<string, string>): string;
+/**
+ * Validates a stored payment ID: optional packed QR, then catalog fields.
+ * QR-only is valid when the country exposes `validateQr`.
+ */
+declare function validateStoredPaymentId(currency: CurrencyCode, paymentId: string): boolean;
+/**
+ * Typed-field values for form hydration. Packed QR prefix is stripped.
+ * `hydrateFieldsFromQr` fills keys the typed fallback left empty (PEN phone).
+ */
+declare function assignStoredPaymentIdToFieldValues(currency: CurrencyCode, paymentId: string): Record<string, string>;
+/**
+ * Human-readable stored ID: labeled typed fields, never the raw QR blob.
+ * QR-only returns an empty string so the caller can substitute a label.
+ */
+declare function formatStoredPaymentIdForDisplay(currency: CurrencyCode, paymentId: string): string;
 
-export { COUNTRY_OPTIONS, CURRENCY, CURRENCY_CODES, type CountryOption, type CurrencyCode, PAYMENT_ID_FIELDS, type PaymentIdFieldConfig, deserializeCompoundPaymentId, formatCompoundPaymentIdForDisplay, serializeCompoundPaymentId, validateArgentinePaymentId, validateColombianPaymentId, validateCubanCardNumber, validateCubanPhoneNumber, validateEcuadorianAccountName, validateEcuadorianAccountNumber, validateEcuadorianCedula, validateIndonesianPhoneNumber, validateMexicanPaymentId, validateNigerianAccountName, validateNigerianAccountNumber, validatePIXId, validatePeruvianPaymentKey, validatePeruvianQr, validatePhilippinePhoneNumber, validateRevolutId, validateUPIId, validateVenezuelanPhoneNumber, validateVenezuelanRif };
+export { COUNTRY_OPTIONS, CURRENCY, CURRENCY_CODES, type CountryOption, type CurrencyCode, PACKED_PAYMENT_ID_SEP, PAYMENT_ID_FIELDS, type PaymentIdFieldConfig, type PeruvianPaymentIdParts, type VenezuelanPaymentIdParts, assignPaymentIdToFieldValues, assignStoredPaymentIdToFieldValues, deserializeCompoundPaymentId, formatCompoundPaymentIdForDisplay, formatStoredPaymentIdForDisplay, getCountryOption, getStoredQrPayload, packStoredPaymentId, serializeCompoundPaymentId, unpackPackedPaymentId, uploadsPaymentQR, usesCatalogPaymentForm, usesPackedPaymentId, validateArgentinePaymentId, validateColombianPaymentId, validateCubanCardNumber, validateCubanPhoneNumber, validateEcuadorianAccountName, validateEcuadorianAccountNumber, validateEcuadorianCedula, validateIndonesianPhoneNumber, validateMexicanPaymentId, validateNigerianAccountName, validateNigerianAccountNumber, validatePIXId, validatePaymentIdFields, validatePeruvianCci, validatePeruvianPaymentId, validatePeruvianPaymentKey, validatePeruvianPhone, validatePeruvianQr, validatePhilippinePhoneNumber, validateRevolutId, validateStoredPaymentId, validateUPIId, validateVenezuelanPaymentId, validateVenezuelanPhoneNumber, validateVenezuelanQr, validateVenezuelanRif };