@flopay/shared 1.3.3 → 1.4.0

package/dist/index.mjs

@@ -45,6 +45,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",
@@ -79,7 +373,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";
@@ -2235,13 +2529,19 @@ export {
   MODERN_DARK_APPEARANCE,
   MODERN_LIGHT_APPEARANCE,
   NIGHT_APPEARANCE,
-  SDK_VERSION,
+  SDK_VERSION2 as SDK_VERSION,
   STRIPE_EXPRESS_METHODS,
   STRIPE_METHOD_AMOUNT_LIMITS,
   STRIPE_METHOD_COUNTRIES,
   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,
@@ -2250,6 +2550,10 @@ export {
   buildItemPayload,
   buildProductPayload,
   buildSubscriptionPayload,
+  buildTelemetryErrorEvent,
+  buildTelemetryLogEvent,
+  buildTelemetryPerformanceEvent,
+  buildTelemetryTerminalEvent,
   configureFlopay,
   filterStripeMethodsByAmount,
   filterStripeMethodsByCountry,
@@ -2286,6 +2590,7 @@ export {
   resolveSessionCurrency,
   resolveStripeMethodBrandVariant,
   resolveTheme,
+  serializeTelemetryBatch,
   stripeExpressMethodToOptionKey,
   validationError
 };