@primer-io/primer-js 1.6.1 → 1.6.2

package/dist/primer-loader.d.ts

@@ -614,14 +614,75 @@ export type TranslateFunction = (key: string, fallback: string) => string;
  * Analytics environment type (mirrors @primer-io/sdk-utils/analytics)
  */
 export type AnalyticsEnvironment = "LOCAL" | "DEV" | "STAGING" | "SANDBOX" | "PRODUCTION";
+/**
+ * Who should act on an SDK error (mirrors `SdkErrorOrigin` from
+ * @primer-io/sdk-utils/errors/types):
+ * - `integration`: the merchant's integration must be fixed — see `suggestion`
+ * - `primer`: unexpected Primer-side behaviour — report to Primer support
+ * - `user`: expected outcome of a shopper action (e.g. cancellation)
+ * - `network`: an API request failed at the transport/HTTP level
+ * - `payment`: the payment failed or was declined — check the Dashboard
+ */
+export type SdkErrorOrigin = "integration" | "primer" | "user" | "network" | "payment";
 /**
  * SDK Error class interface (mirrors @primer-io/sdk-utils/errors/errors)
- * Base class for all SDK errors with error code and nested error.
+ * Class for all SDK errors with origin, error code and nested error.
  */
 export interface SdkError extends Error {
+	/** Who should act on this error — see {@link SdkErrorOrigin} */
+	readonly origin: SdkErrorOrigin;
 	readonly code: string;
+	/** How to fix this error, present on `integration`-origin errors */
+	readonly suggestion?: string;
 	readonly error?: unknown;
 }
+/**
+ * Session-bound telemetry client (mirrors `Telemetry` from
+ * @primer-io/sdk-utils/telemetry). One instance per checkout session, created
+ * with the checkout context and disposed on teardown.
+ */
+export interface TelemetryClient {
+	readonly session: {
+		environment: AnalyticsEnvironment;
+		checkoutSessionId: string;
+		clientSessionId: string;
+		primerAccountId: string;
+		sdkVersion: string;
+		clientSessionToken?: string;
+		userAgent: string;
+		/** Timestamp (ms) when the first backend call (/configuration) started */
+		sdkInitStartTime?: number;
+	};
+	readonly analytics: {
+		sendEvent(event: {
+			eventName: string;
+			[key: string]: unknown;
+		}): void;
+	};
+	readonly remoteLog: {
+		log(messageOrError: unknown, config?: {
+			metadata?: Record<string, unknown>;
+			status?: "error" | "warn" | "info";
+		}): void;
+		error(messageOrError: unknown, config?: {
+			metadata?: Record<string, unknown>;
+			status?: "error" | "warn" | "info";
+		}): void;
+		checkoutInitialized(initDurationMs?: number): void;
+	};
+	/**
+	 * Console error + Datadog report for unexpected technical errors, exactly
+	 * once per error. Do NOT use for expected operational errors (payment
+	 * failures, validation errors, etc). `options.message` gives the report a
+	 * call-site context message.
+	 */
+	reportSdkError(error: unknown, options?: {
+		message?: string;
+	}): void;
+	setSdkInitStartTime(timestamp: number): void;
+	getSdkInitStartTime(): number | undefined;
+	dispose(): void;
+}
 declare enum HeadlessManagerType {
 	BLIK = "BLIK",
 	CARD = "CARD",
@@ -1180,21 +1241,12 @@ export interface SDKUtilities {
 	getPaymentMethodConfiguration: (paymentType: PaymentMethodType) => PaymentMethodConfig | undefined;
 	setBillingAddress: (address: NullableAddress) => Promise<void>;
 }
-export interface AnalyticsUtils {
-	environment: AnalyticsEnvironment;
-	primerAccountId?: string;
-	checkoutSessionId: string;
-	clientSessionId?: string;
-	clientSessionToken?: string;
-	sdkVersion?: string;
-	/** Timestamp (ms) when the first backend call (/configuration) started */
-	configurationFetchStartTime?: number;
-}
 export interface PrimerHeadlessCheckout {
 	start: () => Promise<void>;
 	createPaymentMethodManager: (type: string, managerOptions?: PaymentMethodManagerOptions) => Promise<PaymentMethodManager | null>;
 	getSDKUtilities: () => SDKUtilities;
-	getAnalyticsUtils?: () => AnalyticsUtils;
+	/** Session-bound telemetry, shared with all sdk-core internals via the checkout context */
+	getTelemetry: () => TelemetryClient;
 	createVaultManager: () => HeadlessVaultManager;
 	getAssetsManager: () => unknown;
 	refreshClientSession: () => Promise<boolean>;
@@ -1732,7 +1784,11 @@ export type SdkState = {
 	} | null;
 };
 export type ContextType = {
-	analytics?: AnalyticsUtils;
+	/**
+	 * Session-bound analytics and remote logging, published once the headless
+	 * SDK has initialized. Absent while loading and in legacy mode.
+	 */
+	telemetry?: TelemetryClient;
 	configuration?: ClientConfiguration;
 	computedStyles?: CSSStyleDeclaration | null;
 	klarnaCategories: KlarnaCategoriesContextType;
@@ -2494,6 +2550,12 @@ declare class HeadlessSdkController implements ReactiveController {
 	private primerJS;
 	private loadingTimeout;
 	private isDisconnected;
+	/**
+	 * Session-bound telemetry of the current SDK instance. Held here (in
+	 * addition to the Lit context) so teardown paths can still emit
+	 * PAYMENT_FLOW_EXITED before the instance is disposed.
+	 */
+	private telemetry;
 	constructor(host: PrimerCheckoutType);
 	get primerJSInstance(): PrimerJS | null;
 	hostConnected(): void;
@@ -2501,6 +2563,12 @@ declare class HeadlessSdkController implements ReactiveController {
 	private setupLoadingTimeout;
 	private clearLoadingTimeout;
 	private cleanupResources;
+	/**
+	 * Datadog error reporting that works across the whole lifecycle: uses the
+	 * session telemetry once it exists, and the pre-init error context while
+	 * initialization is still in flight (e.g. createCheckoutContext threw).
+	 */
+	private reportError;
 	/**
 	 * MANUAL approval flow: on a `:pay` 202, sdk-core invokes this. Keep the SDK
 	 * in the processing state (so the checkout shows its loading UI and stays