framepayments 2.3.0 → 2.4.0

package/README.md

@@ -83,6 +83,42 @@ await frame.configuration.getEvervaultConfiguration({ usePublishableKey: true })
 
 The SDK defaults match the native Frame iOS / Android SDKs exactly — endpoints that those SDKs invoke with `usePublishableKey: true` are publishable-by-default here as well (`paymentMethods.createApplePayPaymentMethod`, `paymentMethods.createGooglePayPaymentMethod`, `deviceAttestation.*`, `wallet.getGooglePayConfiguration`). Everything else defaults to secret.
 
+## 🪪 Onboarding sessions & per-object client secrets
+
+Publishable-key-only mobile clients can authenticate **onboarding sessions** and **per-object client secrets**, matching the three-tier auth model of the native Frame iOS / Android SDKs. The bearer for any request is resolved in this precedence order:
+
+1. a per-request `authToken` (an object `client_secret`, e.g. `ci_..._secret_...`), else
+2. the active onboarding-session token (e.g. `onb_sess_...`), else
+3. the publishable key (when `usePublishableKey: true`) or the secret key.
+
+### Onboarding sessions
+
+Begin a session to route **every** request through the session token, overriding the configured keys (and ignoring `usePublishableKey`) while it is active. Mirrors iOS `beginOnboardingSession` / `endOnboardingSession`.
+
+```ts
+const frame = new FrameSDK({ publishableKey: 'pk_...' });
+
+frame.setOnboardingSession('onb_sess_...');
+// Every call now sends `Authorization: Bearer onb_sess_...`.
+await frame.onboardingSessions.create({ /* ... */ });
+await frame.termsOfService.createToken();
+
+// End the session, reverting to the publishable key.
+frame.clearOnboardingSession();
+```
+
+`clearOnboardingSession(token?)` is **safe-clear**: passing a `token` only clears the session when it matches the active one (so a stale unmount can't wipe a newer session), and returns `true` if it cleared / `false` if the guard prevented it. Omit the argument to force-clear.
+
+### Per-object client secrets
+
+For charge-intent confirm/show and 3-D Secure, pass the object's `client_secret` as a per-request `authToken`. It wins over both an active session and the configured keys:
+
+```ts
+await frame.chargeIntents.confirm('ci_123', { authToken: 'ci_123_secret_...' });
+await frame.chargeIntents.get('ci_123', { authToken: 'ci_123_secret_...' });
+await frame.threeDS.get('tds_123', { authToken: 'tds_123_secret_...' });
+```
+
 ## 📚 Available APIs
 
 | Namespace | Purpose |

package/dist/index.cjs

@@ -35,12 +35,14 @@ var FrameAPIError = class extends Error {
 };
 //#endregion
 //#region src/client.ts
-const PUBLISHABLE_FLAG_KEY = "X-Frame-Use-Publishable-Key";
+const FRAME_USE_PUBLISHABLE_KEY = "frameUsePublishableKey";
+const FRAME_AUTH_TOKEN = "frameAuthToken";
+const createOnboardingSessionStore = () => ({ token: null });
 function safeRawFromAxiosError(err) {
 	if (!err || typeof err !== "object") return err;
 	const cleanedConfig = err.config ? (() => {
-		const { headers, ...restConfig } = err.config;
-		const cleanedHeaders = headers && typeof headers === "object" ? Object.fromEntries(Object.entries(headers).filter(([k]) => k.toLowerCase() !== "authorization" && k !== PUBLISHABLE_FLAG_KEY)) : headers;
+		const { headers, [FRAME_AUTH_TOKEN]: _authToken, ...restConfig } = err.config;
+		const cleanedHeaders = headers && typeof headers === "object" ? Object.fromEntries(Object.entries(headers).filter(([k]) => k.toLowerCase() !== "authorization")) : headers;
 		return {
 			...restConfig,
 			headers: cleanedHeaders
@@ -53,7 +55,7 @@ function safeRawFromAxiosError(err) {
 		config: cleanedConfig
 	};
 }
-const createApiClient = (config) => {
+const createApiClient = (config, sessionStore = createOnboardingSessionStore()) => {
 	const { apiKey, publishableKey, defaultHeaders } = config;
 	if (!apiKey && !publishableKey) throw new Error("FrameSDK config requires at least one of: apiKey, publishableKey. Mobile clients should ship publishableKey only; server code should use apiKey.");
 	const baseURL = config.baseURL ?? "https://api.framepayments.com";
@@ -63,9 +65,11 @@ const createApiClient = (config) => {
 	});
 	client.interceptors.request.use((requestConfig) => {
 		const headers = requestConfig.headers;
-		const wantsPublishable = headers instanceof axios.AxiosHeaders ? headers.has(PUBLISHABLE_FLAG_KEY) : Boolean(headers?.[PUBLISHABLE_FLAG_KEY]);
-		if (headers instanceof axios.AxiosHeaders) headers.delete(PUBLISHABLE_FLAG_KEY);
-		else if (headers && PUBLISHABLE_FLAG_KEY in headers) delete headers[PUBLISHABLE_FLAG_KEY];
+		const cfg = requestConfig;
+		const wantsPublishable = cfg.frameUsePublishableKey === true;
+		const rawAuthToken = cfg.frameAuthToken;
+		if (rawAuthToken === "") throw new FrameAPIError("Frame authToken was provided but empty. Pass a non-empty client_secret (e.g. ci_..._secret_...), or omit authToken to use the configured key.", "invalid_auth_token", 0, null);
+		const perRequestAuthToken = typeof rawAuthToken === "string" && rawAuthToken.length > 0 ? rawAuthToken : void 0;
 		if (defaultHeaders) for (const [name, value] of Object.entries(defaultHeaders)) {
 			if (value == null) continue;
 			if (headers instanceof axios.AxiosHeaders) {
@@ -75,10 +79,17 @@ const createApiClient = (config) => {
 				if (h[name] === void 0) h[name] = value;
 			}
 		}
-		const keyToUse = wantsPublishable ? publishableKey : apiKey;
-		if (!keyToUse) throw new FrameAPIError(wantsPublishable ? "Frame publishable key is not configured. Pass { publishableKey } to new FrameSDK(...) before calling endpoints with { usePublishableKey: true }." : "Frame API key is not configured. Pass { apiKey } to new FrameSDK(...) before calling secret-keyed endpoints.", wantsPublishable ? "missing_publishable_key" : "missing_api_key", 0, null);
-		if (headers instanceof axios.AxiosHeaders) headers.set("Authorization", `Bearer ${keyToUse}`);
-		else if (headers) headers["Authorization"] = `Bearer ${keyToUse}`;
+		const sessionToken = sessionStore.token;
+		let bearer;
+		if (perRequestAuthToken) bearer = perRequestAuthToken;
+		else if (sessionToken) bearer = sessionToken;
+		else {
+			const keyToUse = wantsPublishable ? publishableKey : apiKey;
+			if (!keyToUse) throw new FrameAPIError(wantsPublishable ? "Frame publishable key is not configured. Pass { publishableKey } to new FrameSDK(...) before calling endpoints with { usePublishableKey: true }." : "Frame API key is not configured. Pass { apiKey } to new FrameSDK(...) before calling secret-keyed endpoints.", wantsPublishable ? "missing_publishable_key" : "missing_api_key", 0, null);
+			bearer = keyToUse;
+		}
+		if (headers instanceof axios.AxiosHeaders) headers.set("Authorization", `Bearer ${bearer}`);
+		else if (headers) headers["Authorization"] = `Bearer ${bearer}`;
 		return requestConfig;
 	});
 	client.interceptors.response.use((response) => response, (error) => {
@@ -92,33 +103,18 @@ const createApiClient = (config) => {
 	});
 	return client;
 };
+function buildRequestConfig(publishableDefault, opts) {
+	const { usePublishableKey = publishableDefault, authToken, ...rest } = opts ?? {};
+	const cfg = { ...rest };
+	if (usePublishableKey) cfg[FRAME_USE_PUBLISHABLE_KEY] = true;
+	if (authToken !== void 0) cfg[FRAME_AUTH_TOKEN] = authToken;
+	return cfg;
+}
 function withPublishableKey(opts) {
-	const { usePublishableKey = true, headers, ...rest } = opts ?? {};
-	if (!usePublishableKey) return headers ? {
-		...rest,
-		headers
-	} : { ...rest };
-	return {
-		...rest,
-		headers: {
-			...headers ?? {},
-			[PUBLISHABLE_FLAG_KEY]: "1"
-		}
-	};
+	return buildRequestConfig(true, opts);
 }
 function maybePublishableKey(opts) {
-	const { usePublishableKey = false, headers, ...rest } = opts ?? {};
-	if (!usePublishableKey) return headers ? {
-		...rest,
-		headers
-	} : { ...rest };
-	return {
-		...rest,
-		headers: {
-			...headers ?? {},
-			[PUBLISHABLE_FLAG_KEY]: "1"
-		}
-	};
+	return buildRequestConfig(false, opts);
 }
 //#endregion
 //#region src/utils/paginator.ts
@@ -186,11 +182,11 @@ var CapabilitiesAPI = class {
 	constructor(client) {
 		this.client = client;
 	}
-	async list(accountId) {
-		return (await this.client.get(`/v1/accounts/${accountId}/capabilities`)).data;
+	async list(accountId, opts) {
+		return (await this.client.get(`/v1/accounts/${accountId}/capabilities`, maybePublishableKey(opts))).data;
 	}
-	async request(accountId, params) {
-		return (await this.client.post(`/v1/accounts/${accountId}/capabilities`, params)).data;
+	async request(accountId, params, opts) {
+		return (await this.client.post(`/v1/accounts/${accountId}/capabilities`, params, maybePublishableKey(opts))).data;
 	}
 	async get(accountId, name) {
 		return (await this.client.get(`/v1/accounts/${accountId}/capabilities/${name}`)).data;
@@ -205,11 +201,14 @@ var OnboardingSessionsAPI = class {
 	constructor(client) {
 		this.client = client;
 	}
-	async create(params) {
-		return (await this.client.post("/v1/onboarding_sessions", params)).data;
+	async create(params, opts) {
+		return (await this.client.post("/v1/onboarding_sessions", params, maybePublishableKey(opts))).data;
 	}
-	async getByAccount(accountId) {
-		return (await this.client.get("/v1/onboarding_sessions", { params: { account_id: accountId } })).data;
+	async getByAccount(accountId, opts) {
+		return (await this.client.get("/v1/onboarding_sessions", {
+			...maybePublishableKey(opts),
+			params: { account_id: accountId }
+		})).data;
 	}
 };
 //#endregion
@@ -338,8 +337,8 @@ var ChargeIntentsAPI = class {
 	async update(id, params) {
 		return (await this.client.patch(`/v1/charge_intents/${id}`, params)).data;
 	}
-	async get(id) {
-		return (await this.client.get(`/v1/charge_intents/${id}`)).data;
+	async get(id, opts) {
+		return (await this.client.get(`/v1/charge_intents/${id}`, maybePublishableKey(opts))).data;
 	}
 	async list(per_page, page) {
 		return (await this.client.get("/v1/charge_intents", { params: {
@@ -996,14 +995,14 @@ var ThreeDSAPI = class {
 	constructor(client) {
 		this.client = client;
 	}
-	async create(params) {
-		return (await this.client.post("/v1/3ds/intents", params)).data;
+	async create(params, opts) {
+		return (await this.client.post("/v1/3ds/intents", params, maybePublishableKey(opts))).data;
 	}
-	async get(id) {
-		return (await this.client.get(`/v1/3ds/intents/${id}`)).data;
+	async get(id, opts) {
+		return (await this.client.get(`/v1/3ds/intents/${id}`, maybePublishableKey(opts))).data;
 	}
-	async resend(id) {
-		return (await this.client.post(`/v1/3ds/intents/${id}/resend`)).data;
+	async resend(id, opts) {
+		return (await this.client.post(`/v1/3ds/intents/${id}/resend`, void 0, maybePublishableKey(opts))).data;
 	}
 };
 //#endregion
@@ -1048,8 +1047,8 @@ var TermsOfServiceAPI = class {
 	constructor(client) {
 		this.client = client;
 	}
-	async createToken() {
-		return (await this.client.post("/v1/terms_of_service", {})).data;
+	async createToken(opts) {
+		return (await this.client.post("/v1/terms_of_service", {}, maybePublishableKey(opts))).data;
 	}
 	async update(params) {
 		return (await this.client.patch("/v1/terms_of_service", params)).data;
@@ -1127,7 +1126,8 @@ var GeoComplianceAPI = class {
 //#region src/index.ts
 var FrameSDK = class {
 	constructor(config) {
-		const client = createApiClient(config);
+		this.onboardingSessionStore = createOnboardingSessionStore();
+		const client = createApiClient(config, this.onboardingSessionStore);
 		this.accounts = new AccountsAPI(client);
 		this.capabilities = new CapabilitiesAPI(client);
 		this.onboardingSessions = new OnboardingSessionsAPI(client);
@@ -1167,6 +1167,33 @@ var FrameSDK = class {
 		this.wallet = new WalletAPI(client);
 		this.geoCompliance = new GeoComplianceAPI(client);
 	}
+	/**
+	* Begin an onboarding session. While a session is active, every request sends
+	* `Authorization: Bearer <token>` (e.g. an `onb_sess_...` token), overriding
+	* the configured publishable/secret keys regardless of `usePublishableKey`.
+	* A per-request `authToken` (object client_secret) still takes precedence.
+	*
+	* Mirrors the native iOS `beginOnboardingSession`.
+	*/
+	setOnboardingSession(token) {
+		this.onboardingSessionStore.token = token;
+	}
+	/**
+	* End the active onboarding session, reverting auth to the configured
+	* publishable/secret keys.
+	*
+	* Safe-clear: when `token` is provided, the session is cleared only if it
+	* matches the currently active token. This mirrors Android's guarded
+	* teardown so a stale unmount cannot wipe a newer session. Omit `token` to
+	* force-clear unconditionally.
+	*
+	* @returns true if a session was cleared, false if the guard prevented it.
+	*/
+	clearOnboardingSession(token) {
+		if (token !== void 0 && this.onboardingSessionStore.token !== token) return false;
+		this.onboardingSessionStore.token = null;
+		return true;
+	}
 };
 //#endregion
 exports.FrameAPIError = FrameAPIError;