@flopay/js 1.3.4 → 1.4.1

package/dist/index.cjs

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,14 +15,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -45,10 +35,17 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/load.ts
-var import_shared6 = require("@flopay/shared");
+var import_shared7 = require("@flopay/shared");
 
 // src/stripe-adapter.ts
+var import_stripe_js = require("@stripe/stripe-js");
 var import_shared = require("@flopay/shared");
+
+// src/card-three-ds.ts
+var CARD_THREE_DS_ATTEMPT_TTL_MS = 15 * 6e4;
+var MAX_CARD_THREE_DS_ATTEMPTS = 32;
+
+// src/stripe-adapter.ts
 function toStripeElementType(type) {
   const map = {
     payment: "payment",
@@ -71,6 +68,9 @@ function toStripeAppearanceTheme(theme) {
       return "stripe";
   }
 }
+function cardThreeDsNow() {
+  return globalThis.performance?.now() ?? Date.now();
+}
 function wrapStripeElement(stripeElement) {
   const el = stripeElement;
   return {
@@ -94,11 +94,31 @@ function wrapStripeElement(stripeElement) {
     }
   };
 }
+function toStripeBillingDetails(billing) {
+  return {
+    billing_details: {
+      ...billing.email ? { email: billing.email } : {},
+      ...billing.name ? { name: billing.name } : {},
+      ...billing.address ? {
+        address: {
+          ...billing.address.country ? { country: billing.address.country } : {},
+          ...billing.address.postal_code ? { postal_code: billing.address.postal_code } : {},
+          ...billing.address.city ? { city: billing.address.city } : {},
+          ...billing.address.line1 ? { line1: billing.address.line1 } : {},
+          ...billing.address.line2 ? { line2: billing.address.line2 } : {},
+          ...billing.address.state ? { state: billing.address.state } : {}
+        }
+      } : {}
+    }
+  };
+}
 var StripeAdapter = class {
   constructor() {
     this.name = "stripe";
     this.stripe = null;
     this.elements = null;
+    this.pendingCardThreeDsAttempts = /* @__PURE__ */ new Map();
+    this.cardThreeDsAttemptSequence = 0;
     // Serialized appearance currently applied to `this.elements`. Used to detect
     // when consumers swap themes mid-session so we can live-update the Stripe
     // Elements group instead of returning a stale-styled cache. `null` while no
@@ -109,17 +129,7 @@ var StripeAdapter = class {
     if (typeof window === "undefined") {
       return;
     }
-    let loadStripe;
-    try {
-      ({ loadStripe } = await import("@stripe/stripe-js"));
-    } catch {
-      throw new import_shared.FloPayError(
-        "Failed to load @stripe/stripe-js. Reinstall @flopay/js.",
-        "api_error",
-        { code: "StripeJsLoadFailed" }
-      );
-    }
-    const stripe = await loadStripe(config.publishableKey, {
+    const stripe = await (0, import_stripe_js.loadStripe)(config.publishableKey, {
       locale: config.locale ?? "auto"
     });
     if (!stripe) {
@@ -230,22 +240,7 @@ var StripeAdapter = class {
       };
     }
     const cardNumberEl = this.elements.getElement("cardNumber");
-    const stripeBilling = billingDetails ? {
-      billing_details: {
-        ...billingDetails.email ? { email: billingDetails.email } : {},
-        ...billingDetails.name ? { name: billingDetails.name } : {},
-        ...billingDetails.address ? {
-          address: {
-            ...billingDetails.address.country ? { country: billingDetails.address.country } : {},
-            ...billingDetails.address.postal_code ? { postal_code: billingDetails.address.postal_code } : {},
-            ...billingDetails.address.city ? { city: billingDetails.address.city } : {},
-            ...billingDetails.address.line1 ? { line1: billingDetails.address.line1 } : {},
-            ...billingDetails.address.line2 ? { line2: billingDetails.address.line2 } : {},
-            ...billingDetails.address.state ? { state: billingDetails.address.state } : {}
-          }
-        } : {}
-      }
-    } : {};
+    const stripeBilling = billingDetails ? toStripeBillingDetails(billingDetails) : {};
     const { error, paymentMethod } = cardNumberEl ? await this.stripe.createPaymentMethod({
       type: "card",
       card: cardNumberEl,
@@ -279,41 +274,84 @@ var StripeAdapter = class {
         { payment_method: params.paymentMethodId }
       );
       if (setupError) {
-        return {
+        return this.withCardThreeDsLifecycle(params, {
           status: "failed",
           error: new import_shared.FloPayError(
             setupError.message ?? "Payment failed",
             "api_error",
             { code: setupError.code, declineCode: setupError.decline_code }
           )
-        };
+        });
       }
-      return {
+      return this.withCardThreeDsLifecycle(params, {
         status: setupIntent?.status ?? "failed",
         paymentIntentId: setupIntent?.id,
         paymentMethodId: this.extractPaymentMethodId(setupIntent?.payment_method)
-      };
+      });
     }
     const { error, paymentIntent } = await this.stripe.confirmCardPayment(
       params.clientSecret,
       { payment_method: params.paymentMethodId }
     );
     if (error) {
-      return {
+      return this.withCardThreeDsLifecycle(params, {
         status: "failed",
         error: new import_shared.FloPayError(
           error.message ?? "Payment failed",
           "api_error",
           { code: error.code, declineCode: error.decline_code }
         )
-      };
+      });
     }
-    return {
+    return this.withCardThreeDsLifecycle(params, {
       status: paymentIntent?.status ?? "failed",
       paymentIntentId: paymentIntent?.id,
       paymentMethodId: this.extractPaymentMethodId(paymentIntent?.payment_method)
+    });
+  }
+  /**
+   * Bind provider-observed 3DS milestones to the exact confirmation context.
+   * The sensitive client secret/payment method pair stays only in this private,
+   * in-memory key; callers and telemetry receive an unrelated opaque id.
+   */
+  withCardThreeDsLifecycle(params, result) {
+    const contextKey = `${params.clientSecret}\0${params.paymentMethodId}`;
+    const now = cardThreeDsNow();
+    this.pruneExpiredCardThreeDsAttempts(now);
+    if (result.status === "requires_action") {
+      let attempt2 = this.pendingCardThreeDsAttempts.get(contextKey);
+      if (!attempt2) {
+        while (this.pendingCardThreeDsAttempts.size >= MAX_CARD_THREE_DS_ATTEMPTS) {
+          const oldestContextKey = this.pendingCardThreeDsAttempts.keys().next().value;
+          if (oldestContextKey === void 0) break;
+          this.pendingCardThreeDsAttempts.delete(oldestContextKey);
+        }
+        attempt2 = {
+          attemptId: `card_3ds_${this.cardThreeDsAttemptSequence++}`,
+          startedAt: now
+        };
+        this.pendingCardThreeDsAttempts.set(contextKey, attempt2);
+      }
+      return { ...result, threeDs: { attemptId: attempt2.attemptId, status: "handoff" } };
+    }
+    const attempt = this.pendingCardThreeDsAttempts.get(contextKey);
+    if (!attempt) return result;
+    this.pendingCardThreeDsAttempts.delete(contextKey);
+    return {
+      ...result,
+      threeDs: {
+        attemptId: attempt.attemptId,
+        status: result.error || result.status === "failed" ? "failed" : "returned"
+      }
     };
   }
+  pruneExpiredCardThreeDsAttempts(now) {
+    for (const [contextKey, attempt] of this.pendingCardThreeDsAttempts) {
+      if (now - attempt.startedAt >= CARD_THREE_DS_ATTEMPT_TTL_MS) {
+        this.pendingCardThreeDsAttempts.delete(contextKey);
+      }
+    }
+  }
   async confirmPayment(params) {
     if (!this.stripe || !this.elements) {
       throw new import_shared.FloPayError(
@@ -322,22 +360,7 @@ var StripeAdapter = class {
       );
     }
     const billing = params.billingDetails;
-    const paymentMethodData = billing ? {
-      billing_details: {
-        ...billing.email ? { email: billing.email } : {},
-        ...billing.name ? { name: billing.name } : {},
-        ...billing.address ? {
-          address: {
-            ...billing.address.country ? { country: billing.address.country } : {},
-            ...billing.address.postal_code ? { postal_code: billing.address.postal_code } : {},
-            ...billing.address.city ? { city: billing.address.city } : {},
-            ...billing.address.line1 ? { line1: billing.address.line1 } : {},
-            ...billing.address.line2 ? { line2: billing.address.line2 } : {},
-            ...billing.address.state ? { state: billing.address.state } : {}
-          }
-        } : {}
-      }
-    } : void 0;
+    const paymentMethodData = billing ? toStripeBillingDetails(billing) : void 0;
     const { error, paymentIntent } = await this.stripe.confirmPayment({
       elements: this.elements,
       clientSecret: params.clientSecret,
@@ -500,6 +523,7 @@ var StripeAdapter = class {
     return this.stripe.elements(elementsOptions);
   }
   destroy() {
+    this.pendingCardThreeDsAttempts.clear();
     this.elements = null;
     this.appliedAppearanceKey = null;
     this.stripe = null;
@@ -507,7 +531,7 @@ var StripeAdapter = class {
 };
 
 // src/flopay.ts
-var import_shared5 = require("@flopay/shared");
+var import_shared6 = require("@flopay/shared");
 
 // src/elements.ts
 var import_shared2 = require("@flopay/shared");
@@ -559,7 +583,20 @@ var FloPayElements = class {
 };
 
 // src/payment-api.ts
-var import_shared3 = require("@flopay/shared");
+var import_shared4 = require("@flopay/shared");
+
+// src/api-error.ts
+function readErrorString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function readErrorMessage(value) {
+  if (typeof value === "string") return value.trim() ? value : void 0;
+  if (Array.isArray(value)) {
+    const joined = value.filter((entry) => typeof entry === "string" && entry.trim().length > 0).join("; ");
+    return joined || void 0;
+  }
+  return void 0;
+}
 
 // src/session-display-cache.ts
 var STORAGE_KEY_PREFIX = "flopay_session_display:";
@@ -627,6 +664,334 @@ function clearSessionDisplayData(sessionId) {
   }
 }
 
+// src/telemetry-reporter.ts
+var import_shared3 = require("@flopay/shared");
+var TELEMETRY_PATH = "/v1/sdk-telemetry/events";
+var MAX_BATCH_SIZE = 16;
+var MAX_QUEUE_SIZE = 64;
+var UPLOAD_TIMEOUT_MS = 1500;
+var ERROR_DEDUPLICATION_WINDOW_MS = 1e3;
+var MAX_REPORTED_FAILURES = 64;
+var DEDUPLICATION_EVENT_ID = "00000000-0000-4000-8000-000000000000";
+var EVENT_BUDGETS = {
+  technical_error: 8,
+  lifecycle: 32,
+  expected_outcome: 32,
+  performance: 24
+};
+function createUuidV4() {
+  try {
+    return globalThis.crypto.randomUUID();
+  } 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 bodyByteLength(body) {
+  try {
+    return new TextEncoder().encode(body).byteLength;
+  } catch {
+    return body.length;
+  }
+}
+function failureDeduplicationKey(event) {
+  return JSON.stringify([
+    event.code,
+    event.stage,
+    event.provider,
+    event.attempt,
+    event.statusClass,
+    event.requestCategory,
+    event.paymentMethodCategory,
+    event.checkoutMode,
+    event.layout
+  ]);
+}
+function telemetryNow() {
+  return globalThis.performance?.now() ?? 0;
+}
+var TelemetryReporter = class {
+  constructor(options) {
+    this.ingestionDisabled = false;
+    this.queue = [];
+    this.sequence = 0;
+    this.flushTimer = null;
+    this.flushInFlight = null;
+    this.reportedFailures = /* @__PURE__ */ new Map();
+    this.checkoutContext = {};
+    this.checkoutStartedAt = null;
+    this.destroyed = false;
+    this.pageExitHandler = () => {
+      this.drainQueue();
+    };
+    this.visibilityHandler = () => {
+      if (document.visibilityState === "hidden") void this.flush();
+    };
+    this.eventCounts = {
+      technical_error: 0,
+      lifecycle: 0,
+      expected_outcome: 0,
+      performance: 0
+    };
+    this.endpoint = `${options.billingApiUrl.replace(/\/+$/, "")}${TELEMETRY_PATH}`;
+    this.sdkPackage = options.sdkPackage ?? "@flopay/js";
+    this.sdkVersion = options.sdkVersion;
+    this.correlationId = createUuidV4();
+    this.merchantEnabled = options.enabled !== false;
+    this.clock = options.clock ?? telemetryNow;
+    this.browserTransportAvailable = typeof window !== "undefined" && typeof document !== "undefined";
+    if (this.browserTransportAvailable) {
+      window.addEventListener("pagehide", this.pageExitHandler);
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+  }
+  log(input) {
+    if (!this.canCollect()) return;
+    this.enqueue((0, import_shared3.buildTelemetryLogEvent)({
+      ...this.checkoutContext,
+      ...input,
+      eventId: createUuidV4(),
+      sequence: this.sequence++
+    }));
+  }
+  error(input) {
+    if (!this.canCollect()) return;
+    const normalizedFailure = (0, import_shared3.buildTelemetryErrorEvent)({
+      ...this.checkoutContext,
+      ...input,
+      eventId: DEDUPLICATION_EVENT_ID,
+      sequence: 0
+    });
+    const deduplicationKey = failureDeduplicationKey(normalizedFailure);
+    const now = this.now();
+    this.pruneReportedFailures(now);
+    const previouslyReportedAt = this.reportedFailures.get(deduplicationKey);
+    if (previouslyReportedAt !== void 0 && now >= previouslyReportedAt && now - previouslyReportedAt < ERROR_DEDUPLICATION_WINDOW_MS) {
+      this.log({
+        name: "operation.deduplicated",
+        stage: input.stage,
+        provider: input.provider,
+        paymentMethodCategory: input.paymentMethodCategory,
+        attempt: input.attempt
+      });
+      return;
+    }
+    this.rememberReportedFailure(deduplicationKey, now);
+    this.enqueue((0, import_shared3.buildTelemetryErrorEvent)({
+      ...this.checkoutContext,
+      ...input,
+      eventId: createUuidV4(),
+      sequence: this.sequence++
+    }));
+  }
+  performance(input) {
+    if (!this.canCollect()) return;
+    this.enqueue((0, import_shared3.buildTelemetryPerformanceEvent)({
+      ...this.checkoutContext,
+      ...input,
+      eventId: createUuidV4(),
+      sequence: this.sequence++
+    }));
+  }
+  terminal(input) {
+    if (!this.canCollect()) return;
+    this.enqueue((0, import_shared3.buildTelemetryTerminalEvent)({
+      ...this.checkoutContext,
+      ...input,
+      eventId: createUuidV4(),
+      sequence: this.sequence++
+    }));
+    if (input.outcome !== "action_required" && this.checkoutStartedAt !== null) {
+      const checkoutStartedAt = this.checkoutStartedAt;
+      this.checkoutStartedAt = null;
+      this.performance({
+        stage: "total_journey",
+        durationMs: Math.max(0, this.now() - checkoutStartedAt),
+        durationMode: "total",
+        provider: input.provider,
+        paymentMethodCategory: input.paymentMethodCategory
+      });
+    }
+  }
+  /** @internal Read the reporter's monotonic clock without Resource Timing. */
+  now() {
+    try {
+      return this.clock();
+    } catch {
+      return telemetryNow();
+    }
+  }
+  pruneReportedFailures(now) {
+    for (const [key, reportedAt] of this.reportedFailures) {
+      if (now < reportedAt || now - reportedAt >= ERROR_DEDUPLICATION_WINDOW_MS) {
+        this.reportedFailures.delete(key);
+      }
+    }
+  }
+  rememberReportedFailure(key, reportedAt) {
+    while (this.reportedFailures.size >= MAX_REPORTED_FAILURES) {
+      const oldest = this.reportedFailures.keys().next();
+      if (oldest.done) break;
+      this.reportedFailures.delete(oldest.value);
+    }
+    this.reportedFailures.set(key, reportedAt);
+  }
+  /** @internal Add closed checkout dimensions to subsequent SDK events. */
+  setCheckoutContext(context) {
+    this.checkoutContext = {
+      checkoutMode: context.checkoutMode,
+      layout: context.layout
+    };
+  }
+  /** @internal Start a fresh checkout budget, dedupe window, and total span. */
+  beginCheckout(context = {}) {
+    if (!this.canCollect()) return 0;
+    this.drainQueue();
+    this.setCheckoutContext(context);
+    this.sequence = 0;
+    this.reportedFailures.clear();
+    this.eventCounts = {
+      technical_error: 0,
+      lifecycle: 0,
+      expected_outcome: 0,
+      performance: 0
+    };
+    this.checkoutStartedAt = this.now();
+    return this.checkoutStartedAt;
+  }
+  enqueue(event) {
+    if (!this.canCollect()) return;
+    if (this.queue.length >= MAX_QUEUE_SIZE || this.eventCounts[event.class] >= EVENT_BUDGETS[event.class]) return;
+    this.eventCounts[event.class] += 1;
+    this.queue.push(event);
+    if (this.queue.length >= MAX_BATCH_SIZE) {
+      void this.flush();
+      return;
+    }
+    this.scheduleFlush();
+  }
+  canCollect() {
+    return this.browserTransportAvailable && this.merchantEnabled && !this.ingestionDisabled && !this.destroyed;
+  }
+  /** Flush one bounded batch. Failures are intentionally dropped. */
+  async flush() {
+    if (this.flushInFlight) return this.flushInFlight;
+    if (!this.browserTransportAvailable || this.destroyed || this.ingestionDisabled || this.queue.length === 0) return;
+    this.clearFlushTimer();
+    const events = this.queue.splice(0, MAX_BATCH_SIZE);
+    this.flushInFlight = this.sendBatch(events).finally(() => {
+      this.flushInFlight = null;
+      if (this.queue.length > 0) this.scheduleFlush();
+    });
+    return this.flushInFlight;
+  }
+  /** Flush pending work and detach browser lifecycle listeners. */
+  destroy() {
+    if (this.destroyed) return;
+    this.drainQueue();
+    this.destroyed = true;
+    this.clearFlushTimer();
+    if (this.browserTransportAvailable) {
+      window.removeEventListener("pagehide", this.pageExitHandler);
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+    }
+    this.queue.splice(0);
+    this.reportedFailures.clear();
+  }
+  /** Permanently honor a merchant opt-out and discard queued events. */
+  disable() {
+    this.merchantEnabled = false;
+    this.queue.splice(0);
+    this.reportedFailures.clear();
+    this.clearFlushTimer();
+  }
+  /** Start every bounded keepalive request synchronously before page teardown. */
+  drainQueue() {
+    if (!this.browserTransportAvailable || this.destroyed || this.ingestionDisabled || this.queue.length === 0) return;
+    this.clearFlushTimer();
+    while (this.queue.length > 0) {
+      const events = this.queue.splice(0, MAX_BATCH_SIZE);
+      void this.sendBatch(events);
+    }
+  }
+  async sendBatch(events) {
+    if (!this.browserTransportAvailable || this.ingestionDisabled) return;
+    const body = (0, import_shared3.serializeTelemetryBatch)(events, {
+      correlationId: this.correlationId,
+      sdkPackage: this.sdkPackage,
+      sdkVersion: this.sdkVersion,
+      batchId: createUuidV4()
+    });
+    if (bodyByteLength(body) > import_shared3.TELEMETRY_MAX_BATCH_BYTES) return;
+    const controller = typeof AbortController === "undefined" ? null : new AbortController();
+    let timeout = null;
+    try {
+      const request = fetch(this.endpoint, {
+        method: "POST",
+        headers: { "content-type": "text/plain;charset=UTF-8" },
+        body,
+        credentials: "omit",
+        keepalive: true,
+        referrerPolicy: "no-referrer",
+        signal: controller?.signal
+      }).then(async (response) => {
+        if (response.status !== 202) return null;
+        const payload = await response.json().catch(() => null);
+        return payload?.status === "disabled" ? "disabled" : null;
+      }).catch(() => null);
+      const expired = new Promise((resolve) => {
+        timeout = setTimeout(() => {
+          controller?.abort();
+          resolve(null);
+        }, UPLOAD_TIMEOUT_MS);
+      });
+      const status = await Promise.race([request, expired]);
+      if (status === "disabled") this.disableFromIngestion();
+    } catch {
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+  }
+  disableFromIngestion() {
+    this.ingestionDisabled = true;
+    this.queue.splice(0);
+    this.reportedFailures.clear();
+    this.clearFlushTimer();
+  }
+  scheduleFlush() {
+    if (this.flushTimer || this.destroyed || this.ingestionDisabled) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      void this.flush();
+    }, 0);
+  }
+  clearFlushTimer() {
+    if (!this.flushTimer) return;
+    clearTimeout(this.flushTimer);
+    this.flushTimer = null;
+  }
+};
+var TELEMETRY_REPORTER_FACTORY = /* @__PURE__ */ Symbol.for("@flopay/js.telemetry.reporter-factory.v1");
+var telemetryGlobal = globalThis;
+if (telemetryGlobal[TELEMETRY_REPORTER_FACTORY] === void 0) {
+  Object.defineProperty(telemetryGlobal, TELEMETRY_REPORTER_FACTORY, {
+    configurable: true,
+    enumerable: false,
+    writable: false,
+    value: (options) => new TelemetryReporter(options)
+  });
+}
+
 // src/payment-api.ts
 var DEFAULT_PROCESSING_RETRY_AFTER_MS = 1e3;
 var MIN_PROCESSING_RETRY_AFTER_MS = 500;
@@ -636,18 +1001,30 @@ var DEFAULT_ACCOUNT_SNAPSHOT_TIMEOUT_MS = 1e4;
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function telemetryStatusClass(status) {
+  if (status === void 0) return "network_error";
+  const statusClass = `${Math.floor(status / 100)}xx`;
+  return statusClass === "2xx" || statusClass === "3xx" || statusClass === "4xx" || statusClass === "5xx" ? statusClass : "unknown";
+}
+function telemetryFailure(error, fallbackCode) {
+  if (error instanceof Error && (error.name === "AbortError" || error instanceof import_shared4.FloPayError && error.code === "checkout_processing_timeout")) {
+    return { errorCode: "REQUEST_TIMEOUT", statusClass: "timeout" };
+  }
+  if (error instanceof TypeError) {
+    return { errorCode: "NETWORK_REQUEST_FAILED", statusClass: "network_error" };
+  }
+  return {
+    errorCode: fallbackCode,
+    statusClass: telemetryStatusClass(
+      error instanceof import_shared4.FloPayError ? error.statusCode : void 0
+    )
+  };
+}
 function readString(payload, key) {
-  const value = payload?.[key];
-  return typeof value === "string" && value.trim() ? value : void 0;
+  return readErrorString(payload?.[key]);
 }
 function readMessage(payload, key) {
-  const value = payload?.[key];
-  if (typeof value === "string") return value.trim() ? value : void 0;
-  if (Array.isArray(value)) {
-    const joined = value.filter((entry) => typeof entry === "string" && entry.trim().length > 0).join("; ");
-    return joined || void 0;
-  }
-  return void 0;
+  return readErrorMessage(payload?.[key]);
 }
 function readNumber(payload, key) {
   const value = payload?.[key];
@@ -657,7 +1034,7 @@ function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function createCheckoutProcessingTimeoutError() {
-  return new import_shared3.FloPayError(
+  return new import_shared4.FloPayError(
     "Checkout is still processing. Please try again shortly.",
     "api_error",
     { code: "checkout_processing_timeout" }
@@ -668,14 +1045,14 @@ async function buildApiErrorFromResponse(response, fallbackMessage) {
   const nestedError = isRecord(payload?.error) ? payload.error : null;
   const message = readMessage(payload, "message") ?? readMessage(nestedError, "message") ?? fallbackMessage;
   const code = readString(payload, "code") ?? readString(payload, "gatewayErrorCode") ?? readString(nestedError, "code") ?? `http_${response.status}`;
-  return new import_shared3.FloPayError(message, "api_error", {
+  return new import_shared4.FloPayError(message, "api_error", {
     code,
     statusCode: response.status
   });
 }
 var NETWORK_RETRY_ATTEMPTS = 2;
 var IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS = 2;
-async function fetchWithNetworkRetry(input, init, attempts = NETWORK_RETRY_ATTEMPTS) {
+async function fetchWithNetworkRetry(input, init, attempts = NETWORK_RETRY_ATTEMPTS, onRetry) {
   let lastErr;
   for (let attempt = 0; ; attempt++) {
     try {
@@ -684,13 +1061,59 @@ async function fetchWithNetworkRetry(input, init, attempts = NETWORK_RETRY_ATTEM
       if (err instanceof Error && err.name === "AbortError") throw err;
       lastErr = err;
       if (attempt >= attempts) throw lastErr;
+      try {
+        onRetry?.(attempt + 1);
+      } catch {
+      }
       await delay(150 * 2 ** attempt);
     }
   }
 }
+function isPaymentApiTelemetryHooks(value) {
+  return "now" in value || "onFirstByte" in value || "onSessionCreateFailure" in value || "onRetry" in value;
+}
 var PaymentAPI = class {
-  constructor(billingApiUrl) {
+  constructor(billingApiUrl, telemetryOptionsOrHooks = {}) {
     this.baseUrl = billingApiUrl.replace(/\/+$/, "");
+    const hasInternalHooks = isPaymentApiTelemetryHooks(telemetryOptionsOrHooks);
+    this.telemetryHooks = hasInternalHooks ? telemetryOptionsOrHooks : void 0;
+    this.directTelemetry = hasInternalHooks || telemetryOptionsOrHooks.telemetry === false ? void 0 : new TelemetryReporter({
+      billingApiUrl: this.baseUrl,
+      sdkVersion: import_shared4.SDK_VERSION
+    });
+  }
+  /** Dispose the reporter owned by direct public usage. Internal hooks are never disposed here. */
+  destroy() {
+    this.directTelemetry?.destroy();
+  }
+  reportDirectFailure(error, fallbackCode, stage, requestCategory, paymentMethodCategory = "unknown") {
+    const failure = telemetryFailure(error, fallbackCode);
+    this.directTelemetry?.error({
+      ...failure,
+      stage,
+      requestCategory,
+      paymentMethodCategory
+    });
+  }
+  telemetryTimestamp() {
+    try {
+      return this.telemetryHooks?.now?.() ?? this.directTelemetry?.now() ?? telemetryNow();
+    } catch {
+      return telemetryNow();
+    }
+  }
+  beginDirectTelemetryCheckout(checkoutSessionId) {
+    if (!this.directTelemetry || this.directTelemetryCheckoutId === checkoutSessionId) return;
+    this.directTelemetryCheckoutId = checkoutSessionId;
+    this.directTelemetry.beginCheckout();
+  }
+  beginDirectTelemetryOperation() {
+    if (!this.directTelemetry) return;
+    this.directTelemetryCheckoutId = void 0;
+    this.directTelemetry.beginCheckout();
+  }
+  adoptDirectTelemetryCheckout(checkoutSessionId) {
+    if (checkoutSessionId) this.directTelemetryCheckoutId = checkoutSessionId;
   }
   /**
    * Fetch a raw checkout session by ID.
@@ -702,17 +1125,77 @@ var PaymentAPI = class {
    * Backends that don't yet enforce it ignore the extra header.
    */
   async getCheckoutSession(checkoutSessionId, nonce) {
-    const headers = { [import_shared3.FLO_SDK_VERSION_HEADER]: import_shared3.SDK_VERSION };
+    this.beginDirectTelemetryCheckout(checkoutSessionId);
+    const requestStarted = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "session.read.started",
+      stage: "session_read",
+      requestCategory: "session_read"
+    });
+    const headers = { [import_shared4.FLO_SDK_VERSION_HEADER]: import_shared4.SDK_VERSION };
     if (nonce) headers["x-checkout-session-token"] = nonce;
-    const response = await fetchWithNetworkRetry(
-      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}`,
-      { headers }
-    );
-    if (!response.ok) {
-      throw await buildApiErrorFromResponse(response, "Failed to get checkout session");
+    try {
+      const response = await fetchWithNetworkRetry(
+        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}`,
+        { headers },
+        NETWORK_RETRY_ATTEMPTS,
+        (attempt) => {
+          this.telemetryHooks?.onRetry?.("session_read", attempt);
+          this.directTelemetry?.log({
+            name: "operation.retry",
+            stage: "session_read",
+            requestCategory: "session_read",
+            attempt
+          });
+        }
+      );
+      const firstByteDuration = Math.max(0, this.telemetryTimestamp() - requestStarted);
+      try {
+        this.telemetryHooks?.onFirstByte?.(firstByteDuration);
+      } catch {
+      }
+      const statusClass = `${Math.floor(response.status / 100)}xx`;
+      this.directTelemetry?.log({
+        name: "session.request.first_byte",
+        stage: "session_first_byte",
+        requestCategory: "session_read",
+        statusClass
+      });
+      this.directTelemetry?.performance({
+        stage: "session_first_byte",
+        durationMs: firstByteDuration,
+        durationMode: "machine",
+        requestCategory: "session_read",
+        statusClass
+      });
+      if (!response.ok) {
+        throw await buildApiErrorFromResponse(response, "Failed to get checkout session");
+      }
+      const body = await response.json();
+      this.directTelemetry?.log({
+        name: "session.request.completed",
+        stage: "session_complete",
+        requestCategory: "session_read",
+        statusClass
+      });
+      this.directTelemetry?.performance({
+        stage: "session_complete",
+        durationMs: Math.max(0, this.telemetryTimestamp() - requestStarted),
+        durationMode: "machine",
+        requestCategory: "session_read",
+        statusClass
+      });
+      return { ...body, data: this.mergeCachedDisplayData(body.data) };
+    } catch (error) {
+      const statusCode = error instanceof import_shared4.FloPayError ? error.statusCode : void 0;
+      this.directTelemetry?.error({
+        errorCode: error instanceof import_shared4.FloPayError && error.code === "checkout_processing_timeout" ? "REQUEST_TIMEOUT" : "NETWORK_REQUEST_FAILED",
+        stage: "session_read",
+        requestCategory: "session_read",
+        statusClass: statusCode ? `${Math.floor(statusCode / 100)}xx` : "network_error"
+      });
+      throw error;
     }
-    const body = await response.json();
-    return { ...body, data: this.mergeCachedDisplayData(body.data) };
   }
   /**
    * Stash display-only data for a session so subsequent fetches can fill in
@@ -768,17 +1251,55 @@ var PaymentAPI = class {
    * backends, matched against the session's stored nonce).
    */
   async getVaultCapture(checkoutSessionId, nonce) {
+    this.beginDirectTelemetryCheckout(checkoutSessionId);
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "vault.capture.requested",
+      stage: "vault_request",
+      requestCategory: "vault_capture",
+      paymentMethodCategory: "card"
+    });
     const headers = { "Content-Type": "application/json" };
     if (nonce) headers["x-checkout-session-token"] = nonce;
-    const response = await fetchWithNetworkRetry(
-      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}/vault/capture`,
-      { method: "POST", headers }
-    );
-    if (!response.ok) {
-      throw await buildApiErrorFromResponse(response, "Failed to load the secure card form");
+    try {
+      const response = await fetchWithNetworkRetry(
+        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}/vault/capture`,
+        { method: "POST", headers },
+        NETWORK_RETRY_ATTEMPTS,
+        (attempt) => {
+          this.telemetryHooks?.onRetry?.("vault_capture", attempt);
+          this.directTelemetry?.log({
+            name: "operation.retry",
+            stage: "vault_request",
+            requestCategory: "vault_capture",
+            paymentMethodCategory: "card",
+            attempt
+          });
+        }
+      );
+      if (!response.ok) {
+        throw await buildApiErrorFromResponse(response, "Failed to load the secure card form");
+      }
+      const block = await response.json();
+      this.directTelemetry?.performance({
+        stage: "vault_request",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+        durationMode: "machine",
+        requestCategory: "vault_capture",
+        paymentMethodCategory: "card",
+        statusClass: "2xx"
+      });
+      return this.toVaultBlock(block);
+    } catch (error) {
+      this.reportDirectFailure(
+        error,
+        "VAULT_LOAD_FAILED",
+        "vault_request",
+        "vault_capture",
+        "card"
+      );
+      throw error;
     }
-    const block = await response.json();
-    return this.toVaultBlock(block);
   }
   /**
    * Fetch and normalize a checkout session.
@@ -814,26 +1335,88 @@ var PaymentAPI = class {
    *   future major version.
    */
   async processPayment(_userId, data, options) {
+    this.beginDirectTelemetryCheckout(data.sessionId);
     if (!data.nonce) {
-      throw new import_shared3.FloPayError(
+      this.directTelemetry?.terminal({
+        outcome: "validation_rejected",
+        stage: "processing",
+        requestCategory: "process_payment"
+      });
+      throw new import_shared4.FloPayError(
         "processPayment requires `nonce` \u2014 pass the value returned from session creation.",
         "validation_error",
         { code: "MissingCheckoutSessionToken", param: "nonce" }
       );
     }
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "payment.processing.started",
+      stage: "processing",
+      requestCategory: "process_payment"
+    });
     const { nonce, ...processBody } = data;
-    const response = await fetch(
-      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(data.sessionId)}/process`,
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "x-checkout-session-token": nonce
-        },
-        body: JSON.stringify(processBody)
+    let response;
+    try {
+      response = await fetch(
+        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(data.sessionId)}/process`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-checkout-session-token": nonce
+          },
+          body: JSON.stringify(processBody)
+        }
+      );
+    } catch (error) {
+      this.reportDirectFailure(
+        error,
+        "PAYMENT_PROCESSING_FAILED",
+        "processing",
+        "process_payment"
+      );
+      throw error;
+    }
+    if (!response.ok && response.status !== 202) {
+      this.directTelemetry?.error({
+        errorCode: "PAYMENT_PROCESSING_FAILED",
+        stage: "processing",
+        requestCategory: "process_payment",
+        statusClass: telemetryStatusClass(response.status)
+      });
+      return response;
+    }
+    try {
+      const result = await this.resolveProcessResponse(
+        response,
+        data.sessionId,
+        { ...options, nonce }
+      );
+      this.directTelemetry?.log({
+        name: "payment.processing.completed",
+        stage: "processing",
+        requestCategory: "process_payment",
+        statusClass: telemetryStatusClass(result.status)
+      });
+      this.directTelemetry?.performance({
+        stage: "processing",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+        durationMode: "machine",
+        requestCategory: "process_payment",
+        statusClass: telemetryStatusClass(result.status)
+      });
+      return result;
+    } catch (error) {
+      if (!(error instanceof import_shared4.FloPayError && error.code === "checkout_processing_timeout")) {
+        this.reportDirectFailure(
+          error,
+          "PAYMENT_PROCESSING_FAILED",
+          "processing",
+          "process_payment"
+        );
       }
-    );
-    return this.resolveProcessResponse(response, data.sessionId, { ...options, nonce });
+      throw error;
+    }
   }
   /**
    * Patch the buyer's account snapshot (email, name, billing address, AVS
@@ -857,6 +1440,13 @@ var PaymentAPI = class {
    * AVS-protected charge to decline downstream.
    */
   async patchAccountSnapshot(sessionId, nonce, body, options) {
+    this.beginDirectTelemetryCheckout(sessionId);
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "operation.state_transition",
+      stage: "processing",
+      requestCategory: "account_snapshot"
+    });
     const timeoutMs = options?.timeoutMs ?? DEFAULT_ACCOUNT_SNAPSHOT_TIMEOUT_MS;
     const controller = new AbortController();
     const onCallerAbort = () => controller.abort();
@@ -865,26 +1455,53 @@ var PaymentAPI = class {
       else options.signal.addEventListener("abort", onCallerAbort, { once: true });
     }
     const timer = setTimeout(() => controller.abort(), timeoutMs);
-    let response;
     try {
-      response = await fetchWithNetworkRetry(
-        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(sessionId)}/account`,
-        {
-          method: "PATCH",
-          headers: {
-            "Content-Type": "application/json",
-            "x-checkout-session-token": nonce
+      let response;
+      try {
+        response = await fetchWithNetworkRetry(
+          `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(sessionId)}/account`,
+          {
+            method: "PATCH",
+            headers: {
+              "Content-Type": "application/json",
+              "x-checkout-session-token": nonce
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal
           },
-          body: JSON.stringify(body),
-          signal: controller.signal
-        }
+          NETWORK_RETRY_ATTEMPTS,
+          (attempt) => {
+            this.telemetryHooks?.onRetry?.("account_snapshot", attempt);
+            this.directTelemetry?.log({
+              name: "operation.retry",
+              stage: "processing",
+              requestCategory: "account_snapshot",
+              attempt
+            });
+          }
+        );
+      } finally {
+        clearTimeout(timer);
+        options?.signal?.removeEventListener("abort", onCallerAbort);
+      }
+      if (!response.ok) {
+        throw await buildApiErrorFromResponse(response, "Failed to persist account snapshot");
+      }
+      this.directTelemetry?.performance({
+        stage: "processing",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+        durationMode: "machine",
+        requestCategory: "account_snapshot",
+        statusClass: "2xx"
+      });
+    } catch (error) {
+      this.reportDirectFailure(
+        error,
+        "NETWORK_REQUEST_FAILED",
+        "processing",
+        "account_snapshot"
       );
-    } finally {
-      clearTimeout(timer);
-      options?.signal?.removeEventListener("abort", onCallerAbort);
-    }
-    if (!response.ok) {
-      throw await buildApiErrorFromResponse(response, "Failed to persist account snapshot");
+      throw error;
     }
   }
   /**
@@ -906,22 +1523,62 @@ var PaymentAPI = class {
    * passing the concrete payment method id / type.
    */
   async createPaymentIntent(sessionId, email, paymentMethodType, options) {
+    this.beginDirectTelemetryCheckout(sessionId);
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "payment.intent.started",
+      stage: "processing",
+      requestCategory: "intent_create"
+    });
     const headers = { "Content-Type": "application/json" };
     if (options?.nonce) headers["x-checkout-session-token"] = options.nonce;
-    return fetch(
-      `${this.baseUrl}/v1/checkouts/payments/intents`,
-      {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-          sessionId,
-          email,
-          paymentMethodType: paymentMethodType ?? null,
-          isPaypal: options?.isPaypal ?? false
-        }),
-        signal: options?.signal
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/v1/checkouts/payments/intents`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            sessionId,
+            email,
+            paymentMethodType: paymentMethodType ?? null,
+            isPaypal: options?.isPaypal ?? false
+          }),
+          signal: options?.signal
+        }
+      );
+      if (!response.ok) {
+        this.directTelemetry?.error({
+          errorCode: "PAYMENT_PROCESSING_FAILED",
+          stage: "processing",
+          requestCategory: "intent_create",
+          statusClass: telemetryStatusClass(response.status)
+        });
+        return response;
       }
-    );
+      this.directTelemetry?.log({
+        name: "payment.intent.completed",
+        stage: "processing",
+        requestCategory: "intent_create",
+        statusClass: telemetryStatusClass(response.status)
+      });
+      this.directTelemetry?.performance({
+        stage: "processing",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+        durationMode: "machine",
+        requestCategory: "intent_create",
+        statusClass: telemetryStatusClass(response.status)
+      });
+      return response;
+    } catch (error) {
+      this.reportDirectFailure(
+        error,
+        "PAYMENT_PROCESSING_FAILED",
+        "processing",
+        "intent_create"
+      );
+      throw error;
+    }
   }
   /**
    * Create a SetupIntent for saving payment methods.
@@ -930,23 +1587,71 @@ var PaymentAPI = class {
    * required by post-#640 backends, ignored by earlier versions.
    */
   async createSetupIntent(sessionId, email, paymentMethodType, options) {
+    this.beginDirectTelemetryCheckout(sessionId);
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "payment.intent.started",
+      stage: "processing",
+      requestCategory: "intent_create"
+    });
     const headers = { "Content-Type": "application/json" };
     if (options?.nonce) headers["x-checkout-session-token"] = options.nonce;
-    return fetch(
-      `${this.baseUrl}/v1/checkouts/payments/setup-intents`,
-      {
-        method: "POST",
-        headers,
-        body: JSON.stringify({ sessionId, email, paymentMethodType }),
-        signal: options?.signal
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/v1/checkouts/payments/setup-intents`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ sessionId, email, paymentMethodType }),
+          signal: options?.signal
+        }
+      );
+      if (!response.ok) {
+        this.directTelemetry?.error({
+          errorCode: "PAYMENT_PROCESSING_FAILED",
+          stage: "processing",
+          requestCategory: "intent_create",
+          statusClass: telemetryStatusClass(response.status)
+        });
+        return response;
       }
-    );
+      this.directTelemetry?.log({
+        name: "payment.intent.completed",
+        stage: "processing",
+        requestCategory: "intent_create",
+        statusClass: telemetryStatusClass(response.status)
+      });
+      this.directTelemetry?.performance({
+        stage: "processing",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+        durationMode: "machine",
+        requestCategory: "intent_create",
+        statusClass: telemetryStatusClass(response.status)
+      });
+      return response;
+    } catch (error) {
+      this.reportDirectFailure(
+        error,
+        "PAYMENT_PROCESSING_FAILED",
+        "processing",
+        "intent_create"
+      );
+      throw error;
+    }
   }
   /**
    * Fetch user's prior payments by email.
    * Used to determine if saved card UX should be shown.
    */
   async getPaymentsByEmail(email, options) {
+    this.beginDirectTelemetryOperation();
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "operation.recovery.started",
+      stage: "recovery",
+      requestCategory: "other",
+      paymentMethodCategory: "saved"
+    });
     const page = options?.page ?? 1;
     const limit = options?.limit ?? 1;
     const params = new URLSearchParams({
@@ -956,18 +1661,43 @@ var PaymentAPI = class {
       sortField: "createdAt",
       sortDirection: "DESC"
     });
-    const response = await fetch(
-      `${this.baseUrl}/v1/payments?${params.toString()}`,
-      {
-        method: "GET",
-        signal: options?.signal,
-        keepalive: true
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/v1/payments?${params.toString()}`,
+        {
+          method: "GET",
+          signal: options?.signal,
+          keepalive: true
+        }
+      );
+      if (!response.ok) {
+        throw new import_shared4.FloPayError(
+          "Failed to fetch payments",
+          "api_error",
+          { statusCode: response.status }
+        );
       }
-    );
-    if (!response.ok) {
-      throw new import_shared3.FloPayError("Failed to fetch payments", "api_error");
+      const result = await response.json();
+      this.directTelemetry?.log({
+        name: "operation.recovery.completed",
+        stage: "recovery",
+        requestCategory: "other",
+        paymentMethodCategory: "saved",
+        statusClass: "2xx"
+      });
+      this.directTelemetry?.performance({
+        stage: "recovery",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+        durationMode: "machine",
+        requestCategory: "other",
+        paymentMethodCategory: "saved",
+        statusClass: "2xx"
+      });
+      return result;
+    } catch (error) {
+      this.reportDirectFailure(error, "RECOVERY_FAILED", "recovery", "other", "saved");
+      throw error;
     }
-    return response.json();
   }
   /**
    * Create a checkout session AND return the full session data in one call.
@@ -977,15 +1707,65 @@ var PaymentAPI = class {
    * Falls back to create + GET if the backend doesn't support `expand`.
    */
   async createAndFetchSession(params) {
-    const wireProducts = params.products ?? (0, import_shared3.foldIntoProducts)(params.items, params.subscriptions);
-    const sessionCurrency = (0, import_shared3.resolveSessionCurrency)(
+    this.beginDirectTelemetryOperation();
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "session.create.started",
+      stage: "session_create",
+      requestCategory: "session_create"
+    });
+    try {
+      const result = await this.createAndFetchSessionRequest(params, startedAt);
+      this.adoptDirectTelemetryCheckout(result.data.session?.id);
+      this.directTelemetry?.log({
+        name: "session.request.completed",
+        stage: "session_complete",
+        requestCategory: "session_create",
+        statusClass: "2xx"
+      });
+      this.directTelemetry?.performance({
+        stage: "session_create",
+        durationMs: this.telemetryTimestamp() - startedAt,
+        durationMode: "machine",
+        requestCategory: "session_create",
+        statusClass: "2xx"
+      });
+      return result;
+    } catch (error) {
+      if (!(error instanceof import_shared4.FloPayError && error.code === "session_auto_completed")) {
+        try {
+          this.telemetryHooks?.onSessionCreateFailure?.(error);
+        } catch {
+        }
+      }
+      if (error instanceof import_shared4.FloPayError && error.type === "validation_error") {
+        this.directTelemetry?.terminal({
+          outcome: "validation_rejected",
+          stage: "session_create",
+          requestCategory: "session_create"
+        });
+      } else if (!(error instanceof import_shared4.FloPayError && error.code === "session_auto_completed")) {
+        const statusCode = error instanceof import_shared4.FloPayError ? error.statusCode : void 0;
+        this.directTelemetry?.error({
+          errorCode: error instanceof Error && error.name === "AbortError" ? "REQUEST_TIMEOUT" : error instanceof TypeError ? "NETWORK_REQUEST_FAILED" : "CHECKOUT_SESSION_CREATE_FAILED",
+          stage: "session_create",
+          requestCategory: "session_create",
+          statusClass: error instanceof Error && error.name === "AbortError" ? "timeout" : statusCode ? `${Math.floor(statusCode / 100)}xx` : "network_error"
+        });
+      }
+      throw error;
+    }
+  }
+  async createAndFetchSessionRequest(params, telemetryStartedAt) {
+    const wireProducts = params.products ?? (0, import_shared4.foldIntoProducts)(params.items, params.subscriptions);
+    const sessionCurrency = (0, import_shared4.resolveSessionCurrency)(
       params.currency,
       params.items,
       params.subscriptions,
       wireProducts
     );
     if (!sessionCurrency) {
-      throw new import_shared3.FloPayError(
+      throw new import_shared4.FloPayError(
         "currency is required: pass `currency` on the session, or include a `currency` on the first item/subscription/product.",
         "validation_error",
         { code: "CurrencyRequired", param: "currency" }
@@ -993,12 +1773,12 @@ var PaymentAPI = class {
     }
     const payload = {
       clientId: params.clientId,
-      checkoutVersion: import_shared3.SDK_VERSION,
+      checkoutVersion: import_shared4.SDK_VERSION,
       successUrl: params.successUrl,
       cancelUrl: params.cancelUrl,
       currency: sessionCurrency,
       checkoutMode: params.checkoutMode ?? "full",
-      products: wireProducts.map((product) => (0, import_shared3.buildProductPayload)(product, sessionCurrency)),
+      products: wireProducts.map((product) => (0, import_shared4.buildProductPayload)(product, sessionCurrency)),
       accountData: {
         userId: params.account.userId,
         firstName: params.account.firstName ?? null,
@@ -1026,13 +1806,14 @@ var PaymentAPI = class {
       // Declare the SDK version so backends at TeamFloPay/backend#823 embed
       // the hosted vault capture block (`body.vault`) in the response for
       // SDKs ≥ 1.3.0. Older backends ignore the header.
-      [import_shared3.FLO_SDK_VERSION_HEADER]: import_shared3.SDK_VERSION
+      [import_shared4.FLO_SDK_VERSION_HEADER]: import_shared4.SDK_VERSION
     };
-    const idempotencyKey = (0, import_shared3.resolveIdempotencyKey)(params.idempotencyKey);
+    const idempotencyKey = (0, import_shared4.resolveIdempotencyKey)(params.idempotencyKey);
     if (idempotencyKey) {
-      headers[import_shared3.IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
+      headers[import_shared4.IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
     }
     let response;
+    let firstByteReported = false;
     for (let attempt = 0; ; attempt++) {
       response = await fetchWithNetworkRetry(
         `${this.baseUrl}/v1/checkouts/sessions?expand=true`,
@@ -1040,10 +1821,37 @@ var PaymentAPI = class {
           method: "POST",
           headers,
           body: JSON.stringify(payload)
+        },
+        NETWORK_RETRY_ATTEMPTS,
+        (networkAttempt) => {
+          this.telemetryHooks?.onRetry?.("session_create", networkAttempt);
+          this.directTelemetry?.log({
+            name: "operation.retry",
+            stage: "session_create",
+            requestCategory: "session_create",
+            attempt: networkAttempt
+          });
         }
       );
+      if (!firstByteReported) {
+        firstByteReported = true;
+        const statusClass = `${Math.floor(response.status / 100)}xx`;
+        this.directTelemetry?.log({
+          name: "session.request.first_byte",
+          stage: "session_first_byte",
+          requestCategory: "session_create",
+          statusClass
+        });
+        this.directTelemetry?.performance({
+          stage: "session_first_byte",
+          durationMs: this.telemetryTimestamp() - telemetryStartedAt,
+          durationMode: "machine",
+          requestCategory: "session_create",
+          statusClass
+        });
+      }
       if (response.status === 204) {
-        throw new import_shared3.FloPayError(
+        throw new import_shared4.FloPayError(
           "Session auto-completed \u2014 payment method already on file",
           "api_error",
           { code: "session_auto_completed" }
@@ -1051,7 +1859,17 @@ var PaymentAPI = class {
       }
       if (response.ok) break;
       const error = await buildApiErrorFromResponse(response, "Failed to create checkout session");
-      if (error.code === import_shared3.IDEMPOTENCY_IN_PROGRESS_CODE && attempt < IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS) {
+      if (error.code === import_shared4.IDEMPOTENCY_IN_PROGRESS_CODE && attempt < IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS) {
+        try {
+          this.telemetryHooks?.onRetry?.("session_create", attempt + 1);
+          this.directTelemetry?.log({
+            name: "operation.retry",
+            stage: "session_create",
+            requestCategory: "session_create",
+            attempt: attempt + 1
+          });
+        } catch {
+        }
         await delay(150 * 2 ** attempt);
         continue;
       }
@@ -1074,9 +1892,10 @@ var PaymentAPI = class {
     }
     const uuid = body.data?.uuid;
     if (!uuid) {
-      throw new import_shared3.FloPayError("No session ID returned", "api_error");
+      throw new import_shared4.FloPayError("No session ID returned", "api_error");
     }
     this.autoCacheDisplayData(uuid, params);
+    this.adoptDirectTelemetryCheckout(uuid);
     const unifiedSession = await this.getUnifiedCheckoutSession(uuid);
     return {
       ...unifiedSession,
@@ -1086,31 +1905,78 @@ var PaymentAPI = class {
     };
   }
   async waitForCheckoutSessionCompletion(checkoutSessionId, options) {
+    this.beginDirectTelemetryCheckout(checkoutSessionId);
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "operation.recovery.started",
+      stage: "recovery",
+      requestCategory: "session_read",
+      paymentMethodCategory: "saved"
+    });
     const timeoutMs = options?.timeoutMs ?? DEFAULT_PROCESSING_TIMEOUT_MS;
     const deadline = Date.now() + timeoutMs;
     let nextDelayMs = this.clampRetryAfterMs(options?.initialDelayMs ?? DEFAULT_PROCESSING_RETRY_AFTER_MS);
-    while (true) {
-      const remainingMs = deadline - Date.now();
-      if (remainingMs <= 0) {
-        throw createCheckoutProcessingTimeoutError();
-      }
-      if (nextDelayMs > 0) {
-        await delay(Math.min(nextDelayMs, remainingMs));
+    let pollAttempt = 0;
+    try {
+      while (true) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          throw createCheckoutProcessingTimeoutError();
+        }
+        if (nextDelayMs > 0) {
+          try {
+            pollAttempt += 1;
+            this.telemetryHooks?.onRetry?.("session_read", pollAttempt);
+            this.directTelemetry?.log({
+              name: "operation.retry",
+              stage: "recovery",
+              requestCategory: "session_read",
+              paymentMethodCategory: "saved",
+              attempt: pollAttempt
+            });
+          } catch {
+          }
+          await delay(Math.min(nextDelayMs, remainingMs));
+          if (Date.now() >= deadline) {
+            throw createCheckoutProcessingTimeoutError();
+          }
+        }
+        const session = await this.getUnifiedCheckoutSession(checkoutSessionId, options?.nonce);
+        const status = session.data.session?.status;
+        if (status === "complete" || status === "expired") {
+          this.directTelemetry?.log({
+            name: "operation.recovery.completed",
+            stage: "recovery",
+            requestCategory: "session_read",
+            paymentMethodCategory: "saved"
+          });
+          this.directTelemetry?.performance({
+            stage: "recovery",
+            durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+            durationMode: "machine",
+            requestCategory: "session_read",
+            paymentMethodCategory: "saved"
+          });
+          return session;
+        }
         if (Date.now() >= deadline) {
           throw createCheckoutProcessingTimeoutError();
         }
+        nextDelayMs = this.clampRetryAfterMs(
+          Math.max(nextDelayMs * 2, MIN_PROCESSING_RETRY_AFTER_MS)
+        );
       }
-      const session = await this.getUnifiedCheckoutSession(checkoutSessionId, options?.nonce);
-      const status = session.data.session?.status;
-      if (status === "complete" || status === "expired") {
-        return session;
-      }
-      if (Date.now() >= deadline) {
-        throw createCheckoutProcessingTimeoutError();
+    } catch (error) {
+      if (error instanceof import_shared4.FloPayError && error.code === "checkout_processing_timeout") {
+        this.reportDirectFailure(
+          error,
+          "RECOVERY_FAILED",
+          "recovery",
+          "session_read",
+          "saved"
+        );
       }
-      nextDelayMs = this.clampRetryAfterMs(
-        Math.max(nextDelayMs * 2, MIN_PROCESSING_RETRY_AFTER_MS)
-      );
+      throw error;
     }
   }
   /** Normalize a raw session into a provider-agnostic shape. */
@@ -1242,7 +2108,7 @@ var PaymentAPI = class {
       return new Response(null, { status: 204, statusText: "No Content" });
     }
     if (session.data.session?.status === "expired") {
-      throw new import_shared3.FloPayError(
+      throw new import_shared4.FloPayError(
         "Checkout session has expired.",
         "api_error",
         { code: "checkout_session_expired" }
@@ -1277,12 +2143,12 @@ var PaymentAPI = class {
    */
   autoCacheDisplayData(sessionId, params) {
     if (!sessionId) return;
-    const products = params.products ?? (0, import_shared3.foldIntoProducts)(params.items, params.subscriptions);
+    const products = params.products ?? (0, import_shared4.foldIntoProducts)(params.items, params.subscriptions);
     if (products.length === 0 && !params.currency) {
       return;
     }
     const usingUnifiedProducts = params.products !== void 0;
-    const sessionCurrency = (0, import_shared3.resolveSessionCurrency)(
+    const sessionCurrency = (0, import_shared4.resolveSessionCurrency)(
       params.currency,
       usingUnifiedProducts ? void 0 : params.items,
       usingUnifiedProducts ? void 0 : params.subscriptions,
@@ -1331,13 +2197,79 @@ var PaymentAPI = class {
     };
   }
 };
+function createInstrumentedPaymentAPI(billingApiUrl, hooks) {
+  const InstrumentedPaymentAPI = PaymentAPI;
+  return new InstrumentedPaymentAPI(billingApiUrl, hooks);
+}
 
 // src/pci-vault-card-capture.ts
-var import_shared4 = require("@flopay/shared");
+var import_shared5 = require("@flopay/shared");
 var VAULT_MESSAGE_SOURCE = "flopay-vault";
-function addBreadcrumb(message, data) {
-  const sentry = globalThis.Sentry;
-  sentry?.addBreadcrumb?.({ category: "flopay.card-capture", level: "info", message, data });
+var VAULT_NON_TERMINAL_OUTCOME_LOGS = {
+  ready: ["vault.widget.ready", "vault_ready"],
+  submitting: ["vault.submission.started", "vault_submit"],
+  blocked: ["operation.state_transition", "vault_submit"],
+  action_required: ["vault.action.required", "three_ds_handoff"]
+};
+function addBreadcrumb(event) {
+  const data = {
+    class: event.class,
+    stage: event.stage
+  };
+  if ("code" in event) data["code"] = event.code;
+  if ("provider" in event && event.provider) data["provider"] = event.provider;
+  if ("paymentMethodCategory" in event && event.paymentMethodCategory) {
+    data["paymentMethodCategory"] = event.paymentMethodCategory;
+  }
+  if ("outcome" in event) data["outcome"] = event.outcome;
+  if ("durationMs" in event && event.durationMs !== void 0) data["durationMs"] = event.durationMs;
+  if ("durationMode" in event && event.durationMode) data["durationMode"] = event.durationMode;
+  try {
+    const sentry = globalThis.Sentry;
+    sentry?.addBreadcrumb?.({
+      category: "flopay.telemetry",
+      level: event.class === "technical_error" ? "error" : "info",
+      message: event.class === "lifecycle" ? event.name : event.class === "technical_error" ? event.code : event.class === "expected_outcome" ? event.outcome : "sdk.performance",
+      data
+    });
+  } catch {
+  }
+}
+function vaultLog(name, stage) {
+  return (0, import_shared5.buildTelemetryLogEvent)({
+    eventId: "11111111-1111-4111-8111-111111111111",
+    name,
+    stage,
+    sequence: 0,
+    provider: "pcivault",
+    paymentMethodCategory: "card"
+  });
+}
+function vaultErrorClassification(submissionStarted) {
+  return submissionStarted ? { errorCode: "VAULT_SUBMIT_FAILED", stage: "vault_submit" } : { errorCode: "VAULT_LOAD_FAILED", stage: "vault_mount" };
+}
+function vaultOutcomeBreadcrumb(type, submissionStarted) {
+  if (type === "complete" || type === "decline") {
+    return (0, import_shared5.buildTelemetryTerminalEvent)({
+      eventId: "22222222-2222-4222-8222-222222222222",
+      outcome: type === "complete" ? "payment_succeeded" : "payment_declined",
+      sequence: 0,
+      provider: "pcivault",
+      paymentMethodCategory: "card"
+    });
+  }
+  if (type === "error") {
+    const classification = vaultErrorClassification(submissionStarted);
+    return (0, import_shared5.buildTelemetryErrorEvent)({
+      eventId: "33333333-3333-4333-8333-333333333333",
+      ...classification,
+      sequence: 0,
+      provider: "pcivault",
+      paymentMethodCategory: "card"
+    });
+  }
+  const [name, stage] = VAULT_NON_TERMINAL_OUTCOME_LOGS[type];
+  return vaultLog(name, stage);
 }
 function isVaultResultMessage(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -1355,7 +2287,7 @@ function isVaultResizeMessage(value) {
   return record["source"] === VAULT_MESSAGE_SOURCE && record["type"] === "resize" && typeof record["height"] === "number" && Number.isFinite(record["height"]);
 }
 var PciVaultCardCapture = class {
-  constructor(config = {}) {
+  constructor(config = {}, internalTelemetry) {
     this.provider = "pcivault";
     this.container = null;
     this.messageHandler = null;
@@ -1387,19 +2319,42 @@ var PciVaultCardCapture = class {
     /** Latest card-field order + autofocus directive to push into the widget. */
     this.cardFieldOrder = null;
     this.cardAutoFocus = true;
+    this.captureRequestedAt = 0;
+    this.vaultReadyReported = false;
+    this.submissionStarted = false;
+    this.submissionStartedAt = null;
     this.listeners = /* @__PURE__ */ new Map();
     this.config = config;
+    this.ownsTelemetryReporter = !internalTelemetry && config.telemetry !== false;
+    this.telemetryReporter = internalTelemetry?.reporter ?? (this.ownsTelemetryReporter ? new TelemetryReporter({
+      billingApiUrl: (0, import_shared5.resolveBillingApiUrl)(),
+      sdkVersion: import_shared5.SDK_VERSION
+    }) : void 0);
+    this.requestedAt = internalTelemetry?.requestedAt;
   }
   async mount(container, options) {
+    if (this.ownsTelemetryReporter && !this.telemetryReporter) {
+      this.telemetryReporter = new TelemetryReporter({
+        billingApiUrl: (0, import_shared5.resolveBillingApiUrl)(),
+        sdkVersion: import_shared5.SDK_VERSION
+      });
+    }
+    const mountedAt = this.telemetryReporter?.now?.() ?? telemetryNow();
+    this.captureRequestedAt = this.requestedAt ?? mountedAt;
+    this.vaultReadyReported = false;
+    this.submissionStarted = false;
+    this.submissionStartedAt = null;
     if (typeof window === "undefined" || typeof document === "undefined") {
-      throw new import_shared4.FloPayError(
+      this.reportVaultLoadFailure();
+      throw new import_shared5.FloPayError(
         "The vault card form is only available in the browser.",
         "api_error",
         { code: "card_capture_no_window" }
       );
     }
     if (!options?.html || !options.html.trim()) {
-      throw new import_shared4.FloPayError(
+      this.reportVaultLoadFailure();
+      throw new import_shared5.FloPayError(
         "No vault capture widget HTML was provided to mount the secure card form.",
         "api_error",
         { code: "card_capture_no_widget_html" }
@@ -1409,14 +2364,33 @@ var PciVaultCardCapture = class {
     this.messageToken = options.messageToken ?? null;
     this.expectedOrigin = options.expectedOrigin ?? this.config.expectedOrigin ?? null;
     this.theme = options.theme ?? null;
-    this.attachMessageListener();
-    this.injectWidget(container, options.html);
+    try {
+      this.attachMessageListener();
+      this.injectWidget(container, options.html);
+    } catch (error) {
+      this.reportVaultLoadFailure();
+      throw error;
+    }
     this.postTheme();
     this.postSubmitGate();
     this.postCardFieldOrder();
-    addBreadcrumb("vault widget mounted", { sessionId: this.config.sessionId });
+    addBreadcrumb(vaultLog("vault.widget.mounted", "vault_mount"));
+    this.telemetryReporter?.log({
+      name: "vault.widget.mounted",
+      stage: "vault_mount",
+      provider: "pcivault",
+      paymentMethodCategory: "card"
+    });
     this.emit("ready", { sessionId: this.config.sessionId });
   }
+  reportVaultLoadFailure() {
+    this.telemetryReporter?.error({
+      errorCode: "VAULT_LOAD_FAILED",
+      stage: "vault_mount",
+      provider: "pcivault",
+      paymentMethodCategory: "card"
+    });
+  }
   on(event, handler) {
     let set = this.listeners.get(event);
     if (!set) {
@@ -1440,6 +2414,10 @@ var PciVaultCardCapture = class {
     }
     this.messageToken = null;
     this.expectedOrigin = null;
+    if (this.ownsTelemetryReporter) {
+      this.telemetryReporter?.destroy();
+      this.telemetryReporter = void 0;
+    }
   }
   // ── internals ──
   /**
@@ -1493,10 +2471,12 @@ var PciVaultCardCapture = class {
         message: data.message,
         nextActionRedirectUrl: data.nextActionRedirectUrl
       };
-      addBreadcrumb(`vault widget ${data.type}`, {
-        sessionId: outcome.sessionId,
-        declineReason: outcome.declineReason
-      });
+      if (data.type === "submitting") {
+        this.submissionStarted = true;
+        this.submissionStartedAt = this.telemetryReporter?.now?.() ?? telemetryNow();
+      }
+      addBreadcrumb(vaultOutcomeBreadcrumb(data.type, this.submissionStarted));
+      this.reportOutcome(data.type);
       if (data.type === "ready") {
         this.postTheme();
         this.postSubmitGate();
@@ -1513,6 +2493,88 @@ var PciVaultCardCapture = class {
     this.messageHandler = handler;
     window.addEventListener("message", handler);
   }
+  reportOutcome(type) {
+    const reporter = this.telemetryReporter;
+    if (!reporter) return;
+    if (type === "ready" && !this.vaultReadyReported) {
+      this.vaultReadyReported = true;
+      reporter.performance({
+        stage: "vault_ready",
+        durationMs: Math.max(0, reporter.now() - this.captureRequestedAt),
+        durationMode: "machine",
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
+    }
+    if (type === "complete" || type === "decline") {
+      reporter.log({
+        name: "vault.terminal",
+        stage: "completion",
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
+      reporter.terminal({
+        outcome: type === "complete" ? "payment_succeeded" : "payment_declined",
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
+      return;
+    }
+    if (type === "error") {
+      const classification = vaultErrorClassification(this.submissionStarted);
+      reporter.log({
+        name: "vault.terminal",
+        stage: classification.stage,
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
+      reporter.error({
+        ...classification,
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
+      return;
+    }
+    if (type === "action_required") {
+      reporter.log({
+        name: "vault.action.required",
+        stage: "three_ds_handoff",
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
+      reporter.log({
+        name: "vault.three_ds.handoff",
+        stage: "three_ds_handoff",
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
+      const submissionStartedAt = this.submissionStartedAt;
+      this.submissionStartedAt = null;
+      if (submissionStartedAt !== null) {
+        reporter.performance({
+          stage: "three_ds_handoff",
+          durationMs: Math.max(0, reporter.now() - submissionStartedAt),
+          durationMode: "machine",
+          provider: "pcivault",
+          paymentMethodCategory: "card"
+        });
+      }
+      reporter.terminal({
+        outcome: "action_required",
+        stage: "three_ds_handoff",
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
+      return;
+    }
+    const [name, stage] = VAULT_NON_TERMINAL_OUTCOME_LOGS[type];
+    reporter.log({
+      name,
+      stage,
+      provider: "pcivault",
+      paymentMethodCategory: "card"
+    });
+  }
   /**
    * Push merchant theme colors into the hosted widget (live). The host calls
    * this on a runtime theme switch; the widget applies them to its CSS variables
@@ -1640,12 +2702,43 @@ var PciVaultCardCapture = class {
     ].join(";");
     frame.src = challengeUrl;
     backdrop.appendChild(frame);
+    const closeButton = document.createElement("button");
+    closeButton.type = "button";
+    closeButton.setAttribute("aria-label", "Close card authentication");
+    closeButton.textContent = "\xD7";
+    closeButton.style.cssText = [
+      "position:fixed",
+      "top:20px",
+      "right:20px",
+      "width:40px",
+      "height:40px",
+      "border:0",
+      "border-radius:9999px",
+      "background:#fff",
+      "color:#0f172a",
+      "font-size:28px",
+      "line-height:40px",
+      "cursor:pointer",
+      "box-shadow:0 4px 14px rgba(0,0,0,0.25)"
+    ].join(";");
+    closeButton.addEventListener("click", () => this.abandonActionRequiredOverlay());
+    backdrop.appendChild(closeButton);
+    backdrop.addEventListener("click", (event) => {
+      if (event.target === backdrop) this.abandonActionRequiredOverlay();
+    });
     const returnHandler = (event) => {
       if (event.source !== frame.contentWindow) return;
       const data = event.data;
       if (!data || typeof data !== "object") return;
       const record = data;
       if (record["source"] !== "flopay-vault-3ds-return") return;
+      addBreadcrumb(vaultLog("vault.three_ds.returned", "three_ds_return"));
+      this.telemetryReporter?.log({
+        name: "vault.three_ds.returned",
+        stage: "three_ds_return",
+        provider: "pcivault",
+        paymentMethodCategory: "card"
+      });
       this.hideActionRequiredOverlay();
       this.postActionCompleted(record["status"]);
     };
@@ -1653,7 +2746,7 @@ var PciVaultCardCapture = class {
     this.threeDsReturnHandler = returnHandler;
     document.body.appendChild(backdrop);
     this.actionOverlay = backdrop;
-    addBreadcrumb("vault 3ds challenge overlay shown");
+    addBreadcrumb(vaultLog("vault.three_ds.handoff", "three_ds_handoff"));
   }
   /**
    * Tell the vault widget that the buyer has completed (or abandoned) the
@@ -1679,6 +2772,26 @@ var PciVaultCardCapture = class {
     } catch {
     }
   }
+  abandonActionRequiredOverlay() {
+    if (!this.actionOverlay) return;
+    const breadcrumb = (0, import_shared5.buildTelemetryTerminalEvent)({
+      eventId: "77777777-7777-4777-8777-777777777777",
+      outcome: "customer_abandoned",
+      stage: "three_ds_handoff",
+      sequence: 0,
+      provider: "pcivault",
+      paymentMethodCategory: "card"
+    });
+    addBreadcrumb(breadcrumb);
+    this.telemetryReporter?.terminal({
+      outcome: "customer_abandoned",
+      stage: "three_ds_handoff",
+      provider: "pcivault",
+      paymentMethodCategory: "card"
+    });
+    this.hideActionRequiredOverlay();
+    this.postActionCompleted("abandoned");
+  }
   hideActionRequiredOverlay() {
     if (this.threeDsReturnHandler) {
       window.removeEventListener("message", this.threeDsReturnHandler);
@@ -1687,7 +2800,6 @@ var PciVaultCardCapture = class {
     if (!this.actionOverlay) return;
     this.actionOverlay.parentNode?.removeChild(this.actionOverlay);
     this.actionOverlay = null;
-    addBreadcrumb("vault 3ds challenge overlay hidden");
   }
   /**
    * Size the hosted-widget iframe to the height reported by the form inside it.
@@ -1703,13 +2815,62 @@ var PciVaultCardCapture = class {
     iframe.style.height = `${clamped}px`;
   }
 };
+function createInstrumentedPciVaultCardCapture(config, reporter, requestedAt) {
+  const InstrumentedCapture = PciVaultCardCapture;
+  return new InstrumentedCapture(config, { reporter, requestedAt });
+}
+
+// src/telemetry-bridge.ts
+var FLOPAY_TELEMETRY_BRIDGE = /* @__PURE__ */ Symbol.for("@flopay/js.telemetry.bridge.v1");
+function attachFloPayTelemetryBridge(target, reporter, fallbackNow) {
+  const now = () => reporter?.now() ?? fallbackNow();
+  const bridge = {
+    error: (input) => reporter?.error(input),
+    log: (input) => reporter?.log(input),
+    performance: (input) => reporter?.performance(input),
+    terminal: (input) => reporter?.terminal(input),
+    now,
+    elapsed: (startedAt) => Math.max(0, now() - startedAt),
+    setCheckoutContext: (context) => reporter?.setCheckoutContext(context),
+    beginCheckout: (context = {}) => reporter?.beginCheckout(context) ?? now(),
+    disable: () => reporter?.disable()
+  };
+  Object.defineProperty(target, FLOPAY_TELEMETRY_BRIDGE, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: bridge
+  });
+}
+function getFloPayTelemetryBridge(target) {
+  return target[FLOPAY_TELEMETRY_BRIDGE];
+}
 
 // src/flopay.ts
+function isExpectedDecline(error) {
+  if (!error) return false;
+  const code = error.code?.toLowerCase() ?? "";
+  return Boolean(error.declineCode) || code.includes("declin");
+}
+function telemetryProvider(name) {
+  if (name === "stripe" || name === "paypal" || name === "pcivault") return name;
+  return "other";
+}
 var FloPay = class {
-  constructor(provider, config) {
+  constructor(provider, config, telemetryReporter) {
     this.currentElements = null;
+    this.cardThreeDsStartedAt = /* @__PURE__ */ new Map();
     this.provider = provider;
     this.config = config;
+    this.telemetryReporter = telemetryReporter ?? new TelemetryReporter({
+      billingApiUrl: (0, import_shared6.resolveBillingApiUrl)(config.billingApiUrl),
+      sdkVersion: import_shared6.SDK_VERSION,
+      enabled: config.telemetry !== false
+    });
+    attachFloPayTelemetryBridge(this, this.telemetryReporter, telemetryNow);
+  }
+  now() {
+    return this.telemetryReporter?.now?.() ?? telemetryNow();
   }
   /**
    * Creates a new `FloPayElements` group for mounting payment fields.
@@ -1733,11 +2894,169 @@ var FloPay = class {
   }
   /** Create a payment method from the current elements (tokenize card). */
   async createPaymentMethod(billingDetails) {
-    return this.provider.createPaymentMethod(billingDetails);
+    const started = this.now();
+    const provider = telemetryProvider(this.provider.name);
+    this.telemetryReporter?.log({
+      name: "payment.tokenization.started",
+      stage: "tokenization",
+      provider,
+      paymentMethodCategory: "card"
+    });
+    try {
+      const result = await this.provider.createPaymentMethod(billingDetails);
+      this.telemetryReporter?.performance({
+        stage: "tokenization",
+        durationMs: this.now() - started,
+        durationMode: "machine",
+        provider,
+        paymentMethodCategory: "card"
+      });
+      if (!result.error) {
+        this.telemetryReporter?.log({
+          name: "payment.tokenization.completed",
+          stage: "tokenization",
+          provider,
+          paymentMethodCategory: "card"
+        });
+      } else if (result.error.type !== "validation_error") {
+        this.telemetryReporter?.error({
+          errorCode: "TOKENIZATION_FAILED",
+          stage: "tokenization",
+          provider,
+          paymentMethodCategory: "card"
+        });
+      }
+      return result;
+    } catch (error) {
+      this.telemetryReporter?.performance({
+        stage: "tokenization",
+        durationMs: this.now() - started,
+        durationMode: "machine",
+        provider,
+        paymentMethodCategory: "card"
+      });
+      this.telemetryReporter?.error({
+        errorCode: "TOKENIZATION_FAILED",
+        stage: "tokenization",
+        provider,
+        paymentMethodCategory: "card"
+      });
+      throw error;
+    }
   }
   /** Confirm a card payment with a known client secret and payment method ID. */
   async confirmCardPayment(params) {
-    return this.provider.confirmCardPayment(params);
+    const provider = telemetryProvider(this.provider.name);
+    const operationStartedAt = this.now();
+    try {
+      const result = await this.provider.confirmCardPayment(params);
+      const completedAt = this.now();
+      const threeDs = result.threeDs;
+      let threeDsFailed = false;
+      if (threeDs?.status === "handoff") {
+        if (this.trackCardThreeDsAttempt(threeDs.attemptId, completedAt)) {
+          this.telemetryReporter?.log({
+            name: "payment.three_ds.handoff",
+            stage: "three_ds_handoff",
+            provider,
+            paymentMethodCategory: "card"
+          });
+          this.telemetryReporter?.performance({
+            stage: "three_ds_handoff",
+            durationMs: completedAt - operationStartedAt,
+            durationMode: "machine",
+            provider,
+            paymentMethodCategory: "card"
+          });
+          this.telemetryReporter?.terminal({
+            outcome: "action_required",
+            stage: "three_ds_handoff",
+            provider,
+            paymentMethodCategory: "card"
+          });
+        }
+      } else if (threeDs) {
+        const threeDsStartedAt = this.takeCardThreeDsAttempt(threeDs.attemptId, completedAt);
+        if (threeDsStartedAt !== void 0) {
+          if (threeDs.status === "returned") {
+            this.telemetryReporter?.log({
+              name: "payment.three_ds.returned",
+              stage: "three_ds_return",
+              provider,
+              paymentMethodCategory: "card"
+            });
+            this.telemetryReporter?.performance({
+              stage: "three_ds_return",
+              durationMs: completedAt - threeDsStartedAt,
+              durationMode: "machine",
+              provider,
+              paymentMethodCategory: "card"
+            });
+          } else {
+            threeDsFailed = true;
+          }
+        }
+      }
+      if (isExpectedDecline(result.error)) {
+        this.telemetryReporter?.terminal({
+          outcome: "payment_declined",
+          provider,
+          paymentMethodCategory: "card"
+        });
+      } else if (result.error?.type === "validation_error") {
+        this.telemetryReporter?.terminal({
+          outcome: "validation_rejected",
+          provider,
+          paymentMethodCategory: "card"
+        });
+      } else if (result.error) {
+        this.telemetryReporter?.error({
+          errorCode: threeDsFailed ? "THREE_DS_FAILED" : "PROVIDER_RUNTIME_FAILED",
+          stage: threeDsFailed ? "three_ds_return" : "processing",
+          provider,
+          paymentMethodCategory: "card"
+        });
+      } else if (!threeDsFailed && threeDs?.status !== "handoff" && result.status === "succeeded") {
+        this.telemetryReporter?.terminal({
+          outcome: "payment_succeeded",
+          provider,
+          paymentMethodCategory: "card"
+        });
+      }
+      return result;
+    } catch (error) {
+      this.telemetryReporter?.error({
+        errorCode: "PROVIDER_RUNTIME_FAILED",
+        stage: "processing",
+        provider,
+        paymentMethodCategory: "card"
+      });
+      throw error;
+    }
+  }
+  trackCardThreeDsAttempt(attemptId, startedAt) {
+    this.pruneExpiredCardThreeDsAttempts(startedAt);
+    if (this.cardThreeDsStartedAt.has(attemptId)) return false;
+    while (this.cardThreeDsStartedAt.size >= MAX_CARD_THREE_DS_ATTEMPTS) {
+      const oldestAttemptId = this.cardThreeDsStartedAt.keys().next().value;
+      if (oldestAttemptId === void 0) break;
+      this.cardThreeDsStartedAt.delete(oldestAttemptId);
+    }
+    this.cardThreeDsStartedAt.set(attemptId, startedAt);
+    return true;
+  }
+  takeCardThreeDsAttempt(attemptId, now) {
+    this.pruneExpiredCardThreeDsAttempts(now);
+    const startedAt = this.cardThreeDsStartedAt.get(attemptId);
+    if (startedAt !== void 0) this.cardThreeDsStartedAt.delete(attemptId);
+    return startedAt;
+  }
+  pruneExpiredCardThreeDsAttempts(now) {
+    for (const [attemptId, startedAt] of this.cardThreeDsStartedAt) {
+      if (now - startedAt >= CARD_THREE_DS_ATTEMPT_TTL_MS) {
+        this.cardThreeDsStartedAt.delete(attemptId);
+      }
+    }
   }
   /**
    * Create a {@link CardCaptureAdapter} for collecting card details through the
@@ -1752,21 +3071,270 @@ var FloPay = class {
    * the SDK runtime.
    */
   cardCapture(options) {
+    const requestedAt = this.now();
+    this.telemetryReporter?.log({
+      name: "vault.capture.requested",
+      stage: "vault_request",
+      provider: "pcivault",
+      paymentMethodCategory: "card"
+    });
+    if (this.telemetryReporter) {
+      return createInstrumentedPciVaultCardCapture(
+        { sessionId: options?.sessionId },
+        this.telemetryReporter,
+        requestedAt
+      );
+    }
     return new PciVaultCardCapture({
-      sessionId: options?.sessionId
+      sessionId: options?.sessionId,
+      telemetry: false
     });
   }
   /** Confirm a PayPal payment: create intent via billing API → confirm → redirect if needed. */
   async confirmPayPalPayment(params) {
-    return this.provider.confirmPayPalPayment(params);
+    const startedAt = this.now();
+    this.telemetryReporter?.log({
+      name: "payment.method.selected",
+      stage: "processing",
+      provider: "paypal",
+      paymentMethodCategory: "paypal"
+    });
+    this.telemetryReporter?.log({
+      name: "payment.intent.started",
+      stage: "processing",
+      provider: "paypal",
+      paymentMethodCategory: "paypal",
+      requestCategory: "intent_create"
+    });
+    try {
+      const result = await this.provider.confirmPayPalPayment(params);
+      this.telemetryReporter?.performance({
+        stage: "processing",
+        durationMs: this.now() - startedAt,
+        durationMode: "machine",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      if (!result.error) {
+        this.telemetryReporter?.log({
+          name: "payment.intent.completed",
+          stage: "processing",
+          provider: "paypal",
+          paymentMethodCategory: "paypal",
+          requestCategory: "intent_create",
+          statusClass: "2xx"
+        });
+      }
+      if (result.status === "requires_action") {
+        this.telemetryReporter?.log({
+          name: "provider.redirect.started",
+          stage: "redirect",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+        this.telemetryReporter?.terminal({
+          outcome: "action_required",
+          stage: "redirect",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+      } else if (result.status === "succeeded") {
+        this.telemetryReporter?.terminal({
+          outcome: "payment_succeeded",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+      } else if (result.status !== "processing") {
+        if (isExpectedDecline(result.error)) {
+          this.telemetryReporter?.terminal({
+            outcome: "payment_declined",
+            provider: "paypal",
+            paymentMethodCategory: "paypal"
+          });
+        } else if (result.error?.type === "validation_error") {
+          this.telemetryReporter?.terminal({
+            outcome: "validation_rejected",
+            provider: "paypal",
+            paymentMethodCategory: "paypal"
+          });
+        } else if (result.error) {
+          this.telemetryReporter?.error({
+            errorCode: "PAYMENT_PROCESSING_FAILED",
+            stage: "processing",
+            provider: "paypal",
+            paymentMethodCategory: "paypal",
+            requestCategory: "intent_create"
+          });
+        }
+      }
+      return result;
+    } catch (error) {
+      this.telemetryReporter?.performance({
+        stage: "processing",
+        durationMs: this.now() - startedAt,
+        durationMode: "machine",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      this.telemetryReporter?.error({
+        errorCode: "NETWORK_REQUEST_FAILED",
+        stage: "processing",
+        provider: "paypal",
+        paymentMethodCategory: "paypal",
+        requestCategory: "intent_create",
+        statusClass: "network_error"
+      });
+      throw error;
+    }
   }
   /** Resume a PayPal payment after redirect return. Returns null if no PayPal params in URL. */
   async resumePayPalPayment() {
-    return this.provider.resumePayPalPayment();
+    const startedAt = this.now();
+    try {
+      const result = await this.provider.resumePayPalPayment();
+      if (result === null) return null;
+      this.telemetryReporter?.log({
+        name: "provider.redirect.resumed",
+        stage: "redirect_resume",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      this.telemetryReporter?.performance({
+        stage: "redirect_resume",
+        durationMs: this.now() - startedAt,
+        durationMode: "machine",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      if (result.status === "succeeded") {
+        this.telemetryReporter?.terminal({
+          outcome: "payment_succeeded",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+      } else if (isExpectedDecline(result.error)) {
+        this.telemetryReporter?.terminal({
+          outcome: "payment_declined",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+      } else if (result.error?.type === "validation_error") {
+        this.telemetryReporter?.terminal({
+          outcome: "validation_rejected",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+      } else if (result.error) {
+        this.telemetryReporter?.error({
+          errorCode: "REDIRECT_RESUME_FAILED",
+          stage: "redirect_resume",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+      }
+      return result;
+    } catch (error) {
+      this.telemetryReporter?.performance({
+        stage: "redirect_resume",
+        durationMs: this.now() - startedAt,
+        durationMode: "machine",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      this.telemetryReporter?.error({
+        errorCode: "REDIRECT_RESUME_FAILED",
+        stage: "redirect_resume",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      throw error;
+    }
   }
   /** Confirms a payment using the mounted elements. */
   async confirmPayment(params) {
-    return this.provider.confirmPayment(params);
+    const started = this.now();
+    const provider = telemetryProvider(this.provider.name);
+    this.telemetryReporter?.log({
+      name: "payment.processing.started",
+      stage: "processing",
+      provider,
+      paymentMethodCategory: "unknown"
+    });
+    try {
+      const result = await this.provider.confirmPayment(params);
+      const durationMs = this.now() - started;
+      this.telemetryReporter?.performance({
+        stage: "processing",
+        durationMs,
+        durationMode: "machine",
+        provider,
+        paymentMethodCategory: "unknown"
+      });
+      if (result.status === "succeeded") {
+        this.telemetryReporter?.terminal({
+          outcome: "payment_succeeded",
+          provider,
+          paymentMethodCategory: "unknown"
+        });
+      } else if (isExpectedDecline(result.error)) {
+        this.telemetryReporter?.terminal({
+          outcome: "payment_declined",
+          provider,
+          paymentMethodCategory: "unknown"
+        });
+      } else if (result.error?.type === "validation_error") {
+        this.telemetryReporter?.terminal({
+          outcome: "validation_rejected",
+          provider,
+          paymentMethodCategory: "unknown"
+        });
+      } else if (result.status === "requires_action") {
+        this.telemetryReporter?.terminal({
+          outcome: "action_required",
+          stage: "three_ds_handoff",
+          provider,
+          paymentMethodCategory: "unknown"
+        });
+      } else if (result.status === "failed" && result.error) {
+        this.telemetryReporter?.error({
+          errorCode: "PAYMENT_PROCESSING_FAILED",
+          stage: "processing",
+          provider,
+          paymentMethodCategory: "unknown"
+        });
+      }
+      if (result.status === "succeeded" || result.status === "failed") {
+        this.telemetryReporter?.log({
+          name: "payment.processing.completed",
+          stage: "processing",
+          provider,
+          paymentMethodCategory: "unknown"
+        });
+      } else {
+        this.telemetryReporter?.log({
+          name: "operation.state_transition",
+          stage: result.status === "requires_action" ? "three_ds_handoff" : "processing",
+          provider,
+          paymentMethodCategory: "unknown"
+        });
+      }
+      return result;
+    } catch (error) {
+      this.telemetryReporter?.performance({
+        stage: "processing",
+        durationMs: this.now() - started,
+        durationMode: "machine",
+        provider,
+        paymentMethodCategory: "unknown"
+      });
+      this.telemetryReporter?.error({
+        errorCode: "PAYMENT_PROCESSING_FAILED",
+        stage: "processing",
+        provider,
+        paymentMethodCategory: "unknown"
+      });
+      throw error;
+    }
   }
   /**
    * Retrieves a checkout session by ID via the billing API.
@@ -1779,17 +3347,15 @@ var FloPay = class {
    */
   async retrieveSession(sessionId, billingApiUrl) {
     if (!sessionId) {
-      throw new import_shared5.FloPayError(
+      throw new import_shared6.FloPayError(
         "sessionId is required to retrieve a session.",
         "validation_error",
         { param: "sessionId" }
       );
     }
-    const apiUrl = (0, import_shared5.resolveBillingApiUrl)(billingApiUrl ?? this.config.billingApiUrl);
-    const api = new PaymentAPI(apiUrl);
-    const unified = await api.getUnifiedCheckoutSession(sessionId);
+    const unified = await this.retrieveUnifiedSession(sessionId, billingApiUrl);
     if (!unified.data.session) {
-      throw new import_shared5.FloPayError("Session not found", "api_error");
+      throw new import_shared6.FloPayError("Session not found", "api_error");
     }
     return unified.data.session;
   }
@@ -1802,15 +3368,86 @@ var FloPay = class {
    */
   async retrieveUnifiedSession(sessionId, billingApiUrl) {
     if (!sessionId) {
-      throw new import_shared5.FloPayError(
+      throw new import_shared6.FloPayError(
         "sessionId is required.",
         "validation_error",
         { param: "sessionId" }
       );
     }
-    const apiUrl = (0, import_shared5.resolveBillingApiUrl)(billingApiUrl ?? this.config.billingApiUrl);
-    const api = new PaymentAPI(apiUrl);
-    return api.getUnifiedCheckoutSession(sessionId);
+    const apiUrl = (0, import_shared6.resolveBillingApiUrl)(billingApiUrl ?? this.config.billingApiUrl);
+    const started = this.now();
+    this.telemetryReporter?.log({
+      name: "session.read.started",
+      stage: "session_read",
+      requestCategory: "session_read"
+    });
+    let firstByteDuration;
+    const api = createInstrumentedPaymentAPI(apiUrl, {
+      now: () => this.telemetryReporter?.now() ?? telemetryNow(),
+      onFirstByte: (durationMs) => {
+        firstByteDuration = durationMs;
+      },
+      onRetry: (requestCategory, attempt) => {
+        this.telemetryReporter?.log({
+          name: "operation.retry",
+          stage: requestCategory === "session_read" ? "session_read" : "processing",
+          requestCategory,
+          attempt
+        });
+      }
+    });
+    try {
+      const result = await api.getUnifiedCheckoutSession(sessionId);
+      if (firstByteDuration !== void 0) {
+        this.telemetryReporter?.log({
+          name: "session.request.first_byte",
+          stage: "session_first_byte",
+          requestCategory: "session_read",
+          statusClass: "2xx"
+        });
+        this.telemetryReporter?.performance({
+          stage: "session_first_byte",
+          durationMs: firstByteDuration,
+          durationMode: "machine",
+          requestCategory: "session_read",
+          statusClass: "2xx"
+        });
+      }
+      this.telemetryReporter?.log({
+        name: "session.request.completed",
+        stage: "session_complete",
+        requestCategory: "session_read",
+        statusClass: "2xx"
+      });
+      this.telemetryReporter?.log({
+        name: "checkout.data.ready",
+        stage: "checkout_data_ready"
+      });
+      this.telemetryReporter?.performance({
+        stage: "session_complete",
+        durationMs: this.now() - started,
+        durationMode: "machine",
+        requestCategory: "session_read",
+        statusClass: "2xx"
+      });
+      return result;
+    } catch (error) {
+      const statusCode = error instanceof import_shared6.FloPayError ? error.statusCode : void 0;
+      this.telemetryReporter?.error({
+        errorCode: error instanceof import_shared6.FloPayError && error.code === "checkout_processing_timeout" ? "REQUEST_TIMEOUT" : "NETWORK_REQUEST_FAILED",
+        stage: "session_read",
+        provider: "flo",
+        paymentMethodCategory: "unknown"
+      });
+      this.telemetryReporter?.performance({
+        stage: "session_complete",
+        durationMs: this.now() - started,
+        durationMode: "machine",
+        requestCategory: "session_read",
+        statusClass: statusCode ? `${Math.floor(statusCode / 100)}xx` : "network_error"
+      });
+      throw error;
+    }
   }
   /**
    * Returns the raw underlying provider instance (e.g. Stripe object).
@@ -1822,46 +3459,147 @@ var FloPay = class {
   }
   /** Tears down the SDK instance and releases resources. */
   destroy() {
+    this.telemetryReporter?.log({ name: "checkout.unmount", stage: "unmount" });
+    this.telemetryReporter?.destroy();
+    this.cardThreeDsStartedAt.clear();
     this.currentElements?.destroy();
     this.currentElements = null;
     this.provider.destroy();
   }
 };
+function createInstrumentedFloPay(provider, config, reporter) {
+  const InstrumentedFloPay = FloPay;
+  return new InstrumentedFloPay(provider, config, reporter);
+}
 
 // src/load.ts
 var instanceCache = /* @__PURE__ */ new Map();
+function stableCacheValue(value) {
+  if (Array.isArray(value)) return value.map(stableCacheValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, stableCacheValue(entry)])
+    );
+  }
+  return value;
+}
+function instanceCacheKey(publishableKey, options) {
+  return JSON.stringify([
+    publishableKey,
+    (0, import_shared7.resolveBillingApiUrl)(options?.billingApiUrl),
+    options?.telemetry !== false,
+    options?.locale ?? "auto",
+    options?.apiVersion ?? null,
+    stableCacheValue(options?.appearance ?? null)
+  ]);
+}
+var initializationCache = /* @__PURE__ */ new Map();
 async function loadFloPay(publishableKey, options) {
   if (!publishableKey) {
-    throw new import_shared6.FloPayError(
+    const reporter = new TelemetryReporter({
+      billingApiUrl: (0, import_shared7.resolveBillingApiUrl)(options?.billingApiUrl),
+      sdkVersion: import_shared7.SDK_VERSION,
+      enabled: options?.telemetry !== false
+    });
+    reporter.error({
+      errorCode: "CONFIGURATION_INVALID",
+      stage: "sdk_initialize",
+      paymentMethodCategory: "unknown"
+    });
+    void reporter.flush().catch(() => {
+    }).finally(() => reporter.destroy());
+    throw new import_shared7.FloPayError(
       "A publishable key is required to initialize FloPay.",
       "validation_error",
       { param: "publishableKey" }
     );
   }
-  const cached = instanceCache.get(publishableKey);
-  if (cached) return cached;
+  const cacheKey = instanceCacheKey(publishableKey, options);
+  const cached = instanceCache.get(cacheKey);
+  if (cached) {
+    if (options?.telemetry !== false) {
+      getFloPayTelemetryBridge(cached)?.log({
+        name: "sdk.cache.hit",
+        stage: "sdk_initialize"
+      });
+    }
+    return cached;
+  }
+  const initializing = initializationCache.get(cacheKey);
+  if (initializing) return initializing;
   const config = {
-    publishableKey,
-    ...options
+    ...options,
+    publishableKey
   };
-  const adapter = new StripeAdapter();
-  await adapter.initialize(config);
-  const instance = new FloPay(adapter, config);
-  instanceCache.set(publishableKey, instance);
-  return instance;
+  const initialization = (async () => {
+    const reporter = new TelemetryReporter({
+      billingApiUrl: (0, import_shared7.resolveBillingApiUrl)(config.billingApiUrl),
+      sdkVersion: import_shared7.SDK_VERSION,
+      enabled: config.telemetry !== false
+    });
+    const initializationStarted = reporter.now();
+    reporter.log({ name: "sdk.initialize.started", stage: "sdk_initialize" });
+    reporter.log({ name: "sdk.cache.miss", stage: "sdk_initialize" });
+    reporter.log({
+      name: "provider.load.started",
+      stage: "provider_load",
+      provider: "stripe"
+    });
+    const adapter = new StripeAdapter();
+    try {
+      await adapter.initialize(config);
+    } catch (error) {
+      reporter.error({
+        errorCode: "SDK_INITIALIZATION_FAILED",
+        stage: "sdk_initialize",
+        provider: "stripe",
+        paymentMethodCategory: "unknown"
+      });
+      reporter.destroy();
+      throw error;
+    }
+    reporter.log({ name: "provider.ready", stage: "provider_ready", provider: "stripe" });
+    reporter.log({
+      name: "provider.availability.checked",
+      stage: "provider_ready",
+      provider: "stripe"
+    });
+    reporter.log({ name: "sdk.initialize.ready", stage: "sdk_initialize" });
+    const initializationDuration = reporter.now() - initializationStarted;
+    reporter.performance({
+      stage: "sdk_initialize",
+      durationMs: initializationDuration,
+      durationMode: "machine",
+      provider: "stripe"
+    });
+    reporter.performance({
+      stage: "provider_ready",
+      durationMs: initializationDuration,
+      durationMode: "machine",
+      provider: "stripe"
+    });
+    const instance = createInstrumentedFloPay(adapter, config, reporter);
+    instanceCache.set(cacheKey, instance);
+    return instance;
+  })();
+  initializationCache.set(cacheKey, initialization);
+  try {
+    return await initialization;
+  } finally {
+    if (initializationCache.get(cacheKey) === initialization) {
+      initializationCache.delete(cacheKey);
+    }
+  }
 }
 
 // src/create-checkout-session.ts
-var import_shared7 = require("@flopay/shared");
+var import_shared8 = require("@flopay/shared");
 var MAX_COUPON_CODES = 5;
-function readString2(value) {
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
 function buildCheckoutSessionError(status, payload) {
   const nested = payload?.error;
-  const code = readString2(payload?.code) ?? readString2(nested?.code) ?? `http_${status}`;
-  const message = readString2(payload?.message) ?? readString2(nested?.message) ?? defaultMessageForCode(code, status);
-  return new import_shared7.FloPayError(message, "api_error", { code, statusCode: status });
+  const code = readErrorString(payload?.code) ?? readErrorString(nested?.code) ?? `http_${status}`;
+  const message = readErrorString(payload?.message) ?? readErrorString(nested?.message) ?? defaultMessageForCode(code, status);
+  return new import_shared8.FloPayError(message, "api_error", { code, statusCode: status });
 }
 function defaultMessageForCode(code, status) {
   switch (code) {
@@ -1873,7 +3611,7 @@ function defaultMessageForCode(code, status) {
       return `Failed to create checkout session (HTTP ${status}).`;
   }
 }
-async function createCheckoutSession(options) {
+async function createCheckoutSessionCore(options, onFirstByte) {
   const {
     billingApiUrl,
     checkoutBaseUrl,
@@ -1894,18 +3632,18 @@ async function createCheckoutSession(options) {
     utmMetadata,
     idempotencyKey
   } = options;
-  const resolvedIdempotencyKey = (0, import_shared7.resolveIdempotencyKey)(idempotencyKey);
+  const resolvedIdempotencyKey = (0, import_shared8.resolveIdempotencyKey)(idempotencyKey);
   if (couponCodes.length > MAX_COUPON_CODES) {
-    throw new import_shared7.FloPayError(
+    throw new import_shared8.FloPayError(
       `Too many coupon codes \u2014 a checkout session accepts at most ${MAX_COUPON_CODES}.`,
       "validation_error",
       { code: "CouponLimitExceeded", param: "couponCodes" }
     );
   }
-  const wireProducts = products ?? (0, import_shared7.foldIntoProducts)(items, subscriptions);
-  const sessionCurrency = (0, import_shared7.resolveSessionCurrency)(currency, items, subscriptions, wireProducts);
+  const wireProducts = products ?? (0, import_shared8.foldIntoProducts)(items, subscriptions);
+  const sessionCurrency = (0, import_shared8.resolveSessionCurrency)(currency, items, subscriptions, wireProducts);
   if (!sessionCurrency) {
-    throw new import_shared7.FloPayError(
+    throw new import_shared8.FloPayError(
       "currency is required: pass `currency` on the session, or include a `currency` on the first item/subscription/product.",
       "validation_error",
       { code: "CurrencyRequired", param: "currency" }
@@ -1913,12 +3651,12 @@ async function createCheckoutSession(options) {
   }
   const payload = {
     clientId,
-    checkoutVersion: import_shared7.SDK_VERSION,
+    checkoutVersion: import_shared8.SDK_VERSION,
     successUrl,
     cancelUrl,
     currency: sessionCurrency,
     checkoutMode,
-    products: wireProducts.map((product) => (0, import_shared7.buildProductPayload)(product, sessionCurrency)),
+    products: wireProducts.map((product) => (0, import_shared8.buildProductPayload)(product, sessionCurrency)),
     accountData: {
       userId: account.userId,
       firstName: account.firstName ?? null,
@@ -1945,7 +3683,7 @@ async function createCheckoutSession(options) {
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   const headers = { "Content-Type": "application/json" };
   if (resolvedIdempotencyKey) {
-    headers[import_shared7.IDEMPOTENCY_KEY_HEADER] = resolvedIdempotencyKey;
+    headers[import_shared8.IDEMPOTENCY_KEY_HEADER] = resolvedIdempotencyKey;
   }
   let status;
   let body;
@@ -1956,6 +3694,10 @@ async function createCheckoutSession(options) {
       body: JSON.stringify(payload),
       signal: controller.signal
     });
+    try {
+      onFirstByte?.(response.status);
+    } catch {
+    }
     status = response.status;
     try {
       body = await response.json();
@@ -1974,7 +3716,7 @@ async function createCheckoutSession(options) {
       throw new Error("Checkout session created but no UUID was returned by the billing API");
     }
     if (!nonce) {
-      throw new import_shared7.FloPayError(
+      throw new import_shared8.FloPayError(
         "Checkout session created but no `nonce` was returned by the billing API. Upgrade the billing service to TeamFloPay/backend#640 or later.",
         "api_error",
         { code: "MissingCheckoutSessionToken" }
@@ -2017,30 +3759,137 @@ async function createCheckoutSession(options) {
   }
   return { status };
 }
+async function createCheckoutSession(options) {
+  const telemetry = beginCreateSessionTelemetry(options);
+  const recordFirstByte = createFirstByteRecorder(telemetry);
+  try {
+    const result = await createCheckoutSessionCore(options, recordFirstByte);
+    completeCreateSessionTelemetry(telemetry, result);
+    return result;
+  } catch (error) {
+    failCreateSessionTelemetry(telemetry.reporter, error);
+    throw error;
+  } finally {
+    finishCreateSessionTelemetry(telemetry.reporter);
+  }
+}
+function createFirstByteRecorder(telemetry) {
+  let recorded = false;
+  return (status) => {
+    if (recorded) return;
+    recorded = true;
+    const statusClass = `${Math.floor(status / 100)}xx`;
+    telemetry.reporter.log({
+      name: "session.request.first_byte",
+      stage: "session_first_byte",
+      requestCategory: "session_create",
+      statusClass
+    });
+    telemetry.reporter.performance({
+      stage: "session_first_byte",
+      durationMs: telemetry.reporter.now() - telemetry.startedAt,
+      durationMode: "machine",
+      requestCategory: "session_create",
+      statusClass
+    });
+  };
+}
+function beginCreateSessionTelemetry(options) {
+  const reporter = new TelemetryReporter({
+    billingApiUrl: options.billingApiUrl,
+    sdkVersion: import_shared8.SDK_VERSION,
+    enabled: options.telemetry !== false
+  });
+  const startedAt = reporter.now();
+  reporter.log({
+    name: "session.create.started",
+    stage: "session_create",
+    requestCategory: "session_create"
+  });
+  return { reporter, startedAt };
+}
+function completeCreateSessionTelemetry(telemetry, result) {
+  const statusClass = `${Math.floor(result.status / 100)}xx`;
+  telemetry.reporter.log({
+    name: "session.request.completed",
+    stage: "session_complete",
+    requestCategory: "session_create",
+    statusClass
+  });
+  telemetry.reporter.performance({
+    stage: "session_complete",
+    durationMs: telemetry.reporter.now() - telemetry.startedAt,
+    durationMode: "machine",
+    requestCategory: "session_create",
+    statusClass
+  });
+}
+function failCreateSessionTelemetry(reporter, error) {
+  if (error instanceof import_shared8.FloPayError && error.type === "validation_error") {
+    reporter.terminal({
+      outcome: "validation_rejected",
+      stage: "session_create",
+      requestCategory: "session_create"
+    });
+    return;
+  }
+  const statusCode = error instanceof import_shared8.FloPayError ? error.statusCode : void 0;
+  reporter.error({
+    errorCode: error instanceof Error && error.name === "AbortError" ? "REQUEST_TIMEOUT" : error instanceof TypeError ? "NETWORK_REQUEST_FAILED" : "CHECKOUT_SESSION_CREATE_FAILED",
+    stage: "session_create",
+    requestCategory: "session_create",
+    statusClass: error instanceof Error && error.name === "AbortError" ? "timeout" : statusCode ? `${Math.floor(statusCode / 100)}xx` : "network_error"
+  });
+}
+function finishCreateSessionTelemetry(reporter) {
+  void reporter.flush().catch(() => {
+  }).finally(() => reporter.destroy());
+}
 async function createCheckoutSessionWithRetries(options) {
   const { maxRetries = 3, ...sessionOptions } = options;
+  const telemetry = beginCreateSessionTelemetry(options);
+  const recordFirstByte = createFirstByteRecorder(telemetry);
   if (!Number.isFinite(maxRetries) || !Number.isInteger(maxRetries) || maxRetries <= 0) {
+    telemetry.reporter.terminal({
+      outcome: "validation_rejected",
+      stage: "session_create",
+      requestCategory: "session_create"
+    });
+    finishCreateSessionTelemetry(telemetry.reporter);
     throw new Error("Number of retries must be greater than 0");
   }
   const attemptOptions = {
     ...sessionOptions,
-    idempotencyKey: (0, import_shared7.resolveIdempotencyKey)(sessionOptions.idempotencyKey)
+    idempotencyKey: (0, import_shared8.resolveIdempotencyKey)(sessionOptions.idempotencyKey)
   };
   let lastErr;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
-      return await createCheckoutSession(attemptOptions);
+      const result = await createCheckoutSessionCore(attemptOptions, recordFirstByte);
+      completeCreateSessionTelemetry(telemetry, result);
+      finishCreateSessionTelemetry(telemetry.reporter);
+      return result;
     } catch (err) {
       lastErr = err;
       const isTransportAbort = err instanceof Error && err.name === "AbortError";
-      const isInProgressReplay = err instanceof import_shared7.FloPayError && err.code === import_shared7.IDEMPOTENCY_IN_PROGRESS_CODE;
+      const isInProgressReplay = err instanceof import_shared8.FloPayError && err.code === import_shared8.IDEMPOTENCY_IN_PROGRESS_CODE;
       if ((isTransportAbort || isInProgressReplay) && attempt < maxRetries) {
+        telemetry.reporter.log({
+          name: "operation.retry",
+          stage: "session_create",
+          requestCategory: "session_create",
+          attempt: attempt + 1
+        });
         await new Promise((r) => setTimeout(r, 100 * Math.pow(2, attempt)));
         continue;
       }
+      failCreateSessionTelemetry(telemetry.reporter, err);
+      finishCreateSessionTelemetry(telemetry.reporter);
       throw err;
     }
   }
+  failCreateSessionTelemetry(telemetry.reporter, lastErr);
+  finishCreateSessionTelemetry(telemetry.reporter);
   throw lastErr ?? new Error("Unknown error during checkout session creation");
 }
 // Annotate the CommonJS export names for ESM import in node: