@flopay/js 1.3.4 → 1.4.1

package/README.md

@@ -24,7 +24,13 @@ const flopay = await loadFloPay('pk_test_...', {
 });
 ```
 
-`loadFloPay` caches the instance -- calling it again with the same key returns the cached `FloPay` instance. The optional second argument accepts a `FloPayConfig` with `billingApiUrl`, `locale`, and `appearance`.
+`loadFloPay` caches by publishable key and behavior-affecting options. Concurrent
+calls with the same key and options share one in-flight provider initialization
+and resolve to the same `FloPay` instance. A failed initialization is evicted so
+a later call can retry. The optional second argument accepts
+`Omit<FloPayConfig, 'publishableKey'>`, including `billingApiUrl`, `locale`,
+`appearance`, and `telemetry`; set `telemetry: false` to opt out of privacy-safe
+operational telemetry.
 
 ### Create and Mount Elements
 
@@ -233,16 +239,46 @@ try {
 
 ## API Reference
 
+## Privacy-safe operational telemetry
+
+Browser telemetry is enabled by default and is best-effort. It reports only
+the closed SDK error/lifecycle/performance taxonomy through a Flo-owned API;
+it never bundles Sentry, reads Resource Timing, persists a queue, or transmits
+payment/customer/form data, credentials, URLs, provider payloads, arbitrary
+messages, or stacks. Existing merchant callbacks remain available with their
+existing arguments and invocation order. Callback exceptions and rejected
+promises are contained and logged only to the merchant console; they are not
+uploaded as SDK telemetry.
+
+```ts
+const flopay = await loadFloPay('pk_live_…', {
+  telemetry: false, // merchant opt-out
+});
+
+const api = new PaymentAPI(billingApiUrl, { telemetry: false });
+const vault = new PciVaultCardCapture({ telemetry: false });
+await createCheckoutSession({ /* normal checkout fields… */ telemetry: false });
+```
+
+There is no custom telemetry endpoint or enrichment option. See
+[`docs/TELEMETRY.md`](../../docs/TELEMETRY.md) for collected categories,
+exclusions, unauthenticated beacon transport, failure isolation, retention,
+and rollout gates.
+
+The same default-on behavior and boolean opt-out apply to direct `FloPay`,
+`PaymentAPI`, `createCheckoutSession`, `createCheckoutSessionWithRetries`, and
+`PciVaultCardCapture` usage.
+
 ### Exports
 
 | Export | Description |
 |--------|-------------|
-| `loadFloPay(publishableKey, options?)` | Initializes the SDK. Returns a `Promise<FloPay>`. Caches by key. |
+| `loadFloPay(publishableKey, options?)` | Initializes the SDK. Returns a `Promise<FloPay>`. Shares successful and in-flight work by key; failed work remains retryable. |
 | `FloPay` | Main SDK class. Methods: `elements()`, `submitElements()`, `createPaymentMethod()`, `confirmCardPayment()`, `cardCapture()`, `confirmPayment()`, `confirmPayPalPayment()`, `resumePayPalPayment()`, `retrieveSession()`, `retrieveUnifiedSession()`, `getRawProvider()`, `destroy()` |
 | `FloPayElements` | Element group manager. Methods: `create(type, options?)`, `getElement(type)`, `submit()`, `destroy()` |
 | `StripeAdapter` | `PaymentProviderAdapter` implementation for Stripe |
 | `PciVaultCardCapture` | `CardCaptureAdapter` implementation that injects the backend-served hosted vault card widget. See [Vault card capture](#vault-card-capture). |
-| `PaymentAPI` | Billing API client. Methods: `getCheckoutSession()`, `getVaultCapture()`, `getUnifiedCheckoutSession()`, `processPayment()`, `waitForCheckoutSessionCompletion()`, `createPaymentIntent()`, `createSetupIntent()`, `getPaymentsByEmail()` |
+| `PaymentAPI` | Billing API client. Methods: `getCheckoutSession()`, `getVaultCapture()`, `getUnifiedCheckoutSession()`, `processPayment()`, `waitForCheckoutSessionCompletion()`, `createPaymentIntent()`, `createSetupIntent()`, `getPaymentsByEmail()`, `destroy()` |
 | `createCheckoutSession(options)` | Creates a checkout session and redirects. Returns `CheckoutSessionResult`. |
 | `createCheckoutSessionWithRetries(options)` | Same as above with automatic retries (default 3, exponential backoff). |