@flopay/shared 1.3.3 → 1.4.0

package/README.md

@@ -77,7 +77,7 @@ throw validationError('Email is required', 'email');
 
 | Type | Description |
 |------|-------------|
-| `FloPayConfig` | Top-level config: `publishableKey`, `locale?`, `appearance?`, `apiVersion?` |
+| `FloPayConfig` | Top-level config: `publishableKey`, `locale?`, `appearance?`, `apiVersion?`, `telemetry?` (set `false` to opt out of browser operational telemetry) |
 | `FloPayAppearance` | Theme config: `theme` (`'default'`/`'flat'`/`'night'`/`'none'`), `variables?`, `rules?` |
 | `FloPayThemeVariables` | CSS custom property overrides: `colorPrimary`, `colorBackground`, `colorText`, `colorDanger`, `borderRadius`, `fontFamily`, `fontSizeBase`, `spacingUnit` |
 | `ButtonsLayoutStyles` | Style overrides for the `buttons` layout: `cardButton`, `cardButtonFontSize`, `cardFormContainer`, `cardInputBorder`, `cardInputColor`, `cardInputPlaceholderColor`, `cardInputFontSize`, `cardInputBackground`, `nameInput`, `backButton`, `backButtonFontSize`, `backButtonIcon`, `submitButton`, `submitButtonFontSize`, `title`, `titleFontSize`, `errorBanner` |
@@ -137,11 +137,28 @@ throw validationError('Email is required', 'email');
 | `rateLimitError(message)` | Factory for rate limit errors |
 | `networkError(message)` | Factory for network errors |
 
+### Privacy-safe telemetry contract
+
+`@flopay/shared` exports the versioned closed telemetry types and builders used
+by both browser packages: `buildTelemetryErrorEvent`,
+`buildTelemetryLogEvent`, `buildTelemetryPerformanceEvent`,
+`buildTelemetryTerminalEvent`, and `serializeTelemetryBatch`. Builders copy
+only allowlisted enum/numeric/opaque fields; arbitrary messages, stacks,
+payloads, URLs, credentials, customer data, and unknown nested fields cannot
+enter serialized events.
+
+`TELEMETRY_LOG_NAMES` is the complete SDK-authored lifecycle catalog. The
+serializer emits the backend-owned v1 envelope with the fixed
+the closed package identity (`@flopay/shared`, `@flopay/js`, or
+`@flopay/react`) and event classes. See
+[`docs/TELEMETRY.md`](../../docs/TELEMETRY.md) for the privacy and operational
+policy.
+
 ### Constants
 
 | Export | Description |
 |--------|-------------|
-| `SDK_VERSION` | Current SDK version (`'0.1.0'`) |
+| `SDK_VERSION` | Current SDK version (`'1.4.0'`) |
 | `DEFAULT_API_BASE_URL` | `'https://api.flopay.io'` |
 | `DEFAULT_API_VERSION` | `'2024-01-01'` |
 | `DEFAULT_APPEARANCE` | Default theme (primary `#4A49FF`, white background, Poppins font) |

package/dist/index.cjs

@@ -64,13 +64,19 @@ __export(index_exports, {
   MODERN_DARK_APPEARANCE: () => MODERN_DARK_APPEARANCE,
   MODERN_LIGHT_APPEARANCE: () => MODERN_LIGHT_APPEARANCE,
   NIGHT_APPEARANCE: () => NIGHT_APPEARANCE,
-  SDK_VERSION: () => SDK_VERSION,
+  SDK_VERSION: () => SDK_VERSION2,
   STRIPE_EXPRESS_METHODS: () => STRIPE_EXPRESS_METHODS,
   STRIPE_METHOD_AMOUNT_LIMITS: () => STRIPE_METHOD_AMOUNT_LIMITS,
   STRIPE_METHOD_COUNTRIES: () => STRIPE_METHOD_COUNTRIES,
   STRIPE_METHOD_CURRENCIES: () => STRIPE_METHOD_CURRENCIES,
   STRIPE_METHOD_MATRIX: () => STRIPE_METHOD_MATRIX,
   SUPPORTED_CARD_BRANDS: () => SUPPORTED_CARD_BRANDS,
+  TELEMETRY_ERROR_CODES: () => TELEMETRY_ERROR_CODES,
+  TELEMETRY_LOG_NAMES: () => TELEMETRY_LOG_NAMES,
+  TELEMETRY_MAX_BATCH_BYTES: () => TELEMETRY_MAX_BATCH_BYTES,
+  TELEMETRY_MAX_BATCH_EVENTS: () => TELEMETRY_MAX_BATCH_EVENTS,
+  TELEMETRY_SCHEMA_VERSION: () => TELEMETRY_SCHEMA_VERSION,
+  TELEMETRY_SDK_PACKAGES: () => TELEMETRY_SDK_PACKAGES,
   THEMES: () => THEMES,
   US_STATES: () => US_STATES,
   apiError: () => apiError,
@@ -79,6 +85,10 @@ __export(index_exports, {
   buildItemPayload: () => buildItemPayload,
   buildProductPayload: () => buildProductPayload,
   buildSubscriptionPayload: () => buildSubscriptionPayload,
+  buildTelemetryErrorEvent: () => buildTelemetryErrorEvent,
+  buildTelemetryLogEvent: () => buildTelemetryLogEvent,
+  buildTelemetryPerformanceEvent: () => buildTelemetryPerformanceEvent,
+  buildTelemetryTerminalEvent: () => buildTelemetryTerminalEvent,
   configureFlopay: () => configureFlopay,
   filterStripeMethodsByAmount: () => filterStripeMethodsByAmount,
   filterStripeMethodsByCountry: () => filterStripeMethodsByCountry,
@@ -115,6 +125,7 @@ __export(index_exports, {
   resolveSessionCurrency: () => resolveSessionCurrency,
   resolveStripeMethodBrandVariant: () => resolveStripeMethodBrandVariant,
   resolveTheme: () => resolveTheme,
+  serializeTelemetryBatch: () => serializeTelemetryBatch,
   stripeExpressMethodToOptionKey: () => stripeExpressMethodToOptionKey,
   validationError: () => validationError
 });
@@ -167,6 +178,300 @@ function networkError(message) {
   return new FloPayError(message, "network_error");
 }
 
+// src/telemetry.ts
+var TELEMETRY_SCHEMA_VERSION = 1;
+var TELEMETRY_SDK_PACKAGES = [
+  "@flopay/shared",
+  "@flopay/js",
+  "@flopay/react"
+];
+var TELEMETRY_MAX_BATCH_BYTES = 32 * 1024;
+var TELEMETRY_MAX_BATCH_EVENTS = 20;
+var TELEMETRY_PROVIDERS = ["stripe", "paypal"];
+var TELEMETRY_PAYMENT_METHOD_CATEGORIES = [
+  "card",
+  "wallet",
+  "paypal",
+  "apm",
+  "saved",
+  "unknown"
+];
+var TELEMETRY_STAGES = [
+  "callback",
+  "sdk_initialize",
+  "checkout_mount",
+  "session_create",
+  "session_read",
+  "session_first_byte",
+  "session_complete",
+  "checkout_data_ready",
+  "checkout_render",
+  "checkout_interactive",
+  "provider_load",
+  "provider_ready",
+  "overlay_open",
+  "overlay_return",
+  "redirect",
+  "redirect_resume",
+  "vault_request",
+  "vault_mount",
+  "vault_ready",
+  "vault_submit",
+  "tokenization",
+  "three_ds_handoff",
+  "three_ds_return",
+  "processing",
+  "recovery",
+  "completion",
+  "unmount",
+  "total_journey"
+];
+var TELEMETRY_ERROR_CODES = [
+  "CALLBACK_FAILED",
+  "CHECKOUT_SESSION_CREATE_FAILED",
+  "CONFIGURATION_INVALID",
+  "INTERNAL_SDK_ERROR",
+  "NETWORK_REQUEST_FAILED",
+  "PAYMENT_PROCESSING_FAILED",
+  "POPUP_BLOCKED",
+  "PROVIDER_LOAD_FAILED",
+  "PROVIDER_RUNTIME_FAILED",
+  "RECOVERY_FAILED",
+  "REDIRECT_RESUME_FAILED",
+  "REQUEST_TIMEOUT",
+  "SDK_INITIALIZATION_FAILED",
+  "THREE_DS_FAILED",
+  "TOKENIZATION_FAILED",
+  "VAULT_LOAD_FAILED",
+  "VAULT_SUBMIT_FAILED"
+];
+var TELEMETRY_LOG_NAMES = [
+  "sdk.initialize.started",
+  "sdk.initialize.ready",
+  "sdk.cache.hit",
+  "sdk.cache.miss",
+  "checkout.mount",
+  "session.create.started",
+  "session.read.started",
+  "session.request.first_byte",
+  "session.request.completed",
+  "checkout.data.ready",
+  "checkout.rendered",
+  "checkout.interactive",
+  "checkout.recovery.started",
+  "checkout.recovery.completed",
+  "checkout.unmount",
+  "provider.load.started",
+  "provider.eligibility.checked",
+  "provider.availability.checked",
+  "provider.ready",
+  "provider.popup.opened",
+  "provider.overlay.opened",
+  "provider.overlay.returned",
+  "provider.redirect.started",
+  "provider.redirect.resumed",
+  "vault.capture.requested",
+  "vault.widget.mounted",
+  "vault.widget.ready",
+  "vault.submission.started",
+  "vault.action.required",
+  "vault.three_ds.handoff",
+  "vault.three_ds.returned",
+  "vault.terminal",
+  "payment.method.selected",
+  "payment.intent.started",
+  "payment.intent.completed",
+  "payment.tokenization.started",
+  "payment.tokenization.completed",
+  "payment.processing.started",
+  "payment.processing.completed",
+  "payment.three_ds.handoff",
+  "payment.three_ds.returned",
+  "operation.retry",
+  "operation.deduplicated",
+  "operation.fallback",
+  "operation.cache.hit",
+  "operation.cache.miss",
+  "operation.recovery.started",
+  "operation.recovery.completed",
+  "operation.state_transition"
+];
+var TELEMETRY_REQUEST_CATEGORIES = [
+  "session_create",
+  "session_read",
+  "intent_create",
+  "process_payment",
+  "vault_capture",
+  "account_snapshot",
+  "provider_sdk",
+  "other"
+];
+var TELEMETRY_STATUS_CLASSES = [
+  "2xx",
+  "3xx",
+  "4xx",
+  "5xx",
+  "network_error",
+  "timeout",
+  "unknown"
+];
+var TELEMETRY_CHECKOUT_MODES = ["full", "auto", "confirm", "unknown"];
+var TELEMETRY_LAYOUTS = ["embedded", "buttons", "automatic", "unknown"];
+var TELEMETRY_DURATION_MODES = ["machine", "buyer", "total"];
+var TELEMETRY_EXPECTED_OUTCOMES = [
+  "action_required",
+  "customer_abandoned",
+  "payment_cancelled",
+  "payment_declined",
+  "payment_succeeded",
+  "validation_rejected"
+];
+var UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var SDK_VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}(?:-[0-9A-Za-z.-]{1,32})?$/;
+var ERROR_CODES = new Set(TELEMETRY_ERROR_CODES);
+var STAGES = new Set(TELEMETRY_STAGES);
+var PROVIDERS = new Set(TELEMETRY_PROVIDERS);
+var PAYMENT_METHODS = new Set(TELEMETRY_PAYMENT_METHOD_CATEGORIES);
+var LOG_NAMES = new Set(TELEMETRY_LOG_NAMES);
+var CHECKOUT_MODES = new Set(TELEMETRY_CHECKOUT_MODES);
+var LAYOUTS = new Set(TELEMETRY_LAYOUTS);
+var REQUEST_CATEGORIES = new Set(TELEMETRY_REQUEST_CATEGORIES);
+var STATUS_CLASSES = new Set(TELEMETRY_STATUS_CLASSES);
+var DURATION_MODES = new Set(TELEMETRY_DURATION_MODES);
+var EXPECTED_OUTCOMES = new Set(TELEMETRY_EXPECTED_OUTCOMES);
+var SDK_PACKAGES = new Set(TELEMETRY_SDK_PACKAGES);
+function enumOr(value, allowed, fallback) {
+  return typeof value === "string" && allowed.has(value) ? value : fallback;
+}
+function createUuidV4() {
+  try {
+    const id = globalThis.crypto.randomUUID();
+    if (UUID_V4.test(id)) return id;
+  } catch {
+  }
+  const bytes = new Uint8Array(16);
+  try {
+    globalThis.crypto.getRandomValues(bytes);
+  } catch {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function safeUuid(value) {
+  return typeof value === "string" && UUID_V4.test(value) ? value : createUuidV4();
+}
+function safeAttempt(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 100 ? value : void 0;
+}
+function safeSequence(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? Math.min(value, 1e6) : 0;
+}
+function safeDuration(value) {
+  if (!Number.isFinite(value) || value < 0) return 0;
+  return Math.min(Math.round(value), 12e4);
+}
+function addCommonFields(event, input) {
+  const attempt = safeAttempt(input.attempt);
+  if (input.provider && PROVIDERS.has(input.provider)) event.provider = input.provider;
+  if (attempt !== void 0) event.attempt = attempt;
+  if (input.statusClass) event.statusClass = enumOr(input.statusClass, STATUS_CLASSES, "unknown");
+  if (input.requestCategory) {
+    event.requestCategory = enumOr(input.requestCategory, REQUEST_CATEGORIES, "other");
+  }
+  if (input.paymentMethodCategory) {
+    event.paymentMethodCategory = enumOr(
+      input.paymentMethodCategory,
+      PAYMENT_METHODS,
+      "unknown"
+    );
+  }
+  if (input.checkoutMode) {
+    event.checkoutMode = enumOr(input.checkoutMode, CHECKOUT_MODES, "unknown");
+  }
+  if (input.layout) event.layout = enumOr(input.layout, LAYOUTS, "unknown");
+  return event;
+}
+function buildTelemetryErrorEvent(input) {
+  return addCommonFields(
+    {
+      eventId: safeUuid(input.eventId),
+      class: "technical_error",
+      code: enumOr(input.errorCode, ERROR_CODES, "INTERNAL_SDK_ERROR"),
+      stage: enumOr(input.stage, STAGES, "sdk_initialize"),
+      sequence: safeSequence(input.sequence)
+    },
+    input
+  );
+}
+function buildTelemetryLogEvent(input) {
+  return addCommonFields(
+    {
+      eventId: safeUuid(input.eventId),
+      class: "lifecycle",
+      name: enumOr(input.name, LOG_NAMES, "operation.retry"),
+      stage: enumOr(input.stage, STAGES, "sdk_initialize"),
+      sequence: safeSequence(input.sequence)
+    },
+    input
+  );
+}
+function buildTelemetryTerminalEvent(input) {
+  const commonInput = {
+    ...input,
+    stage: input.stage ?? "completion"
+  };
+  return addCommonFields(
+    {
+      eventId: safeUuid(input.eventId),
+      class: "expected_outcome",
+      outcome: enumOr(input.outcome, EXPECTED_OUTCOMES, "customer_abandoned"),
+      stage: enumOr(input.stage, STAGES, "completion"),
+      sequence: safeSequence(input.sequence)
+    },
+    commonInput
+  );
+}
+function buildTelemetryPerformanceEvent(input) {
+  return addCommonFields(
+    {
+      eventId: safeUuid(input.eventId),
+      class: "performance",
+      stage: enumOr(input.stage, STAGES, "sdk_initialize"),
+      sequence: safeSequence(input.sequence),
+      durationMs: safeDuration(input.durationMs),
+      durationMode: enumOr(input.durationMode, DURATION_MODES, "machine")
+    },
+    input
+  );
+}
+function serializeTelemetryBatch(events, options) {
+  const sanitizedEvents = events.slice(0, TELEMETRY_MAX_BATCH_EVENTS).flatMap((event) => {
+    if (event.class === "technical_error") {
+      return [buildTelemetryErrorEvent({ ...event, errorCode: event.code })];
+    }
+    if (event.class === "lifecycle") return [buildTelemetryLogEvent(event)];
+    if (event.class === "expected_outcome") return [buildTelemetryTerminalEvent(event)];
+    if (event.class === "performance") return [buildTelemetryPerformanceEvent(event)];
+    return [];
+  });
+  const envelope = {
+    schemaVersion: TELEMETRY_SCHEMA_VERSION,
+    batchId: safeUuid(options.batchId),
+    correlationId: safeUuid(options.correlationId),
+    sdk: {
+      package: enumOr(options.sdkPackage, SDK_PACKAGES, "@flopay/shared"),
+      version: SDK_VERSION.test(options.sdkVersion) ? options.sdkVersion : "0.0.0"
+    },
+    events: sanitizedEvents
+  };
+  return JSON.stringify(envelope);
+}
+
 // src/config.ts
 var ENV_URL_MAP = {
   local: "https://flo.ngrok.pro",
@@ -201,7 +506,7 @@ var PAYMENT_METHOD_LOGOS = {
 };
 
 // src/constants.ts
-var SDK_VERSION = "1.3.3";
+var SDK_VERSION2 = "1.4.0";
 var FLO_SDK_VERSION_HEADER = "x-flo-sdk-version";
 var BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 var BILLING_API_URL_PRODUCTION = "https://api.flopay.com";
@@ -2365,6 +2670,12 @@ function resolveIdempotencyKey(supplied) {
   STRIPE_METHOD_CURRENCIES,
   STRIPE_METHOD_MATRIX,
   SUPPORTED_CARD_BRANDS,
+  TELEMETRY_ERROR_CODES,
+  TELEMETRY_LOG_NAMES,
+  TELEMETRY_MAX_BATCH_BYTES,
+  TELEMETRY_MAX_BATCH_EVENTS,
+  TELEMETRY_SCHEMA_VERSION,
+  TELEMETRY_SDK_PACKAGES,
   THEMES,
   US_STATES,
   apiError,
@@ -2373,6 +2684,10 @@ function resolveIdempotencyKey(supplied) {
   buildItemPayload,
   buildProductPayload,
   buildSubscriptionPayload,
+  buildTelemetryErrorEvent,
+  buildTelemetryLogEvent,
+  buildTelemetryPerformanceEvent,
+  buildTelemetryTerminalEvent,
   configureFlopay,
   filterStripeMethodsByAmount,
   filterStripeMethodsByCountry,
@@ -2409,6 +2724,7 @@ function resolveIdempotencyKey(supplied) {
   resolveSessionCurrency,
   resolveStripeMethodBrandVariant,
   resolveTheme,
+  serializeTelemetryBatch,
   stripeExpressMethodToOptionKey,
   validationError
 });