@dynamic-labs-sdk/client 1.17.1 → 1.19.0

package/dist/{updateAuthFromVerifyResponse-CElYpi97.cjs → updateAuthFromVerifyResponse-pgYXvDvj.cjs}

@@ -1,9 +1,9 @@
-const require_isMfaRequiredForAction = require('./isMfaRequiredForAction-Btejc5g3.cjs');
+const require_isMfaRequiredForAction = require('./isMfaRequiredForAction-BuvyBN_r.cjs');
 let _dynamic_labs_sdk_api_core = require("@dynamic-labs/sdk-api-core");
 
 //#region package.json
 var name = "@dynamic-labs-sdk/client";
-var version = "1.17.1";
+var version = "1.19.0";
 var dependencies = {
 	"@dynamic-labs-sdk/assert-package-version": "workspace:*",
 	"@dynamic-labs-wallet/browser-wallet-client": "1.0.46",
@@ -109,6 +109,17 @@ let numOfInitializedClients = 0;
 *
 * If more than one instance of DynamicClient was initialized, you should not use this function.
 * Instead, you should pass the client instance you stored to the function that needs it.
+*
+* @example
+* ```ts
+* const client = getDefaultClient();
+* console.log('User:', client.user);
+* ```
+*
+* @returns The default DynamicClient instance.
+* @throws ClientNotFoundError If no client has been initialized yet.
+* @see createDynamicClient
+* @see initializeClient
 * @notInstrumented
 */
 const getDefaultClient = () => {
@@ -137,8 +148,28 @@ const MFA_TOKEN_HEADER = "x-mfa-auth-token";
 const SESSION_PUBLIC_KEY_HEADER = "x-dyn-session-public-key";
 const DYNAMIC_SDK_API_VERSION = dependencies["@dynamic-labs/sdk-api-core"];
 const DYNAMIC_SDK_SESSION_ID_HEADER = "x-dyn-session-id";
+/**
+* Reports the runtime platform (`web` or `react-native`) to the Dynamic API.
+*
+* Named `x-dynamic-platform` (not `x-dyn-*`) to match the header the legacy
+* webview-controller already sends, so the backend receives a consistent
+* platform signal across SDK generations.
+*/
+const DYNAMIC_PLATFORM_HEADER = "x-dynamic-platform";
 const CLIENT_SDK_NAME = "ClientSDK";
 
+//#endregion
+//#region src/utils/getPlatform/getPlatform.ts
+/**
+* Returns the platform the SDK is running on.
+*
+* This is the web implementation — the React Native bundler resolves
+* `getPlatform.native.ts` instead when building for React Native, which
+* returns `'react-native'`.
+* @notInstrumented
+*/
+const getPlatform = () => "web";
+
 //#endregion
 //#region src/utils/randomString/randomString.ts
 const DEFAULT_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
@@ -257,7 +288,17 @@ const getSessionKeys = (client) => {
 //#region src/errors/APIError/APIError.ts
 var APIError = class APIError extends BaseError {
 	status;
-	constructor(message, code, status) {
+	/**
+	* The `payload` object from the API error response body, when present.
+	*
+	* Some error responses carry structured context beyond the `error`/`code`
+	* pair (e.g. `merge_accounts_confirmation` returns the field-level merge
+	* conflicts under `payload.mergeConflicts`). It is preserved here so that
+	* downstream error mappers can surface that context as typed errors instead
+	* of discarding it.
+	*/
+	payload;
+	constructor(message, code, status, payload) {
 		super({
 			cause: null,
 			code,
@@ -266,13 +307,15 @@ var APIError = class APIError extends BaseError {
 			shortMessage: message
 		});
 		this.status = status;
+		this.payload = payload;
 	}
 	static async fromResponse(response) {
 		try {
 			const errorBody = await response.clone().json();
 			if (errorBody && "error" in errorBody && typeof errorBody.error === "string") {
 				const errorCode = "code" in errorBody && typeof errorBody.code === "string" ? errorBody.code : "unknown_error";
-				return new APIError(errorBody.error, errorCode, response.status);
+				const payload = "payload" in errorBody && typeof errorBody.payload === "object" && errorBody.payload !== null ? errorBody.payload : void 0;
+				return new APIError(errorBody.error, errorCode, response.status, payload);
 			}
 			return null;
 		} catch {
@@ -545,6 +588,7 @@ const createApiClient = (options = {}, client) => {
 		headers: {
 			"Content-Type": "application/json",
 			[DYNAMIC_API_VERSION_HEADER]: `API/${DYNAMIC_SDK_API_VERSION}`,
+			[DYNAMIC_PLATFORM_HEADER]: getPlatform(),
 			[DYNAMIC_REQUEST_ID_HEADER]: randomString({ length: 50 }),
 			[DYNAMIC_SDK_SESSION_ID_HEADER]: core.sdkSessionId,
 			[DYNAMIC_SDK_VERSION_HEADER]: `${CLIENT_SDK_NAME}/${version}`,
@@ -617,6 +661,28 @@ const fetchAndStoreNonces = async (client) => {
 	return fetchPromise;
 };
 
+//#endregion
+//#region src/utils/getSecureCookieAttribute/getSecureCookieAttribute.ts
+/**
+* Returns the cookie `Secure` attribute suffix (`'; Secure'`) when the current
+* document is running in a secure context, or an empty string otherwise.
+*
+* The `Secure` attribute prevents the browser from ever transmitting the cookie
+* over an unencrypted `http://` connection, which mitigates cleartext token
+* capture (CWE-614). It is intentionally omitted on insecure/localhost dev,
+* because browsers reject `Secure` cookies set over `http://` and that would
+* silently break local testing.
+*
+* Used when building the Dynamic auth JWT cookie string so the attribute is
+* applied consistently on both the write (sign-in/refresh) and clear (logout)
+* paths.
+*
+* @notInstrumented
+*/
+const getSecureCookieAttribute = () => {
+	return Boolean(globalThis.window?.isSecureContext) || globalThis.location?.protocol === "https:" ? "; Secure" : "";
+};
+
 //#endregion
 //#region src/utils/setCookie/setCookie.ts
 /**
@@ -635,10 +701,25 @@ const setCookie = (cookie) => {
 * This function allows you to listen for various events emitted by the Dynamic client,
 * such as authentication state changes, wallet connections, and more.
 *
+* @example
+* ```ts
+* const unsubscribe = onEvent({
+*   event: 'walletAdded',
+*   listener: ({ walletAccount }) => {
+*     console.log('Wallet added:', walletAccount.address);
+*   },
+* });
+*
+* // Later: clean up
+* unsubscribe();
+* ```
+*
 * @param params.event - The event name to listen for.
 * @param params.listener - The callback function to execute when the event is fired.
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
 * @returns A function that can be called to remove the listener.
+* @see offEvent
+* @see onceEvent
 * @notInstrumented
 * @hook Event listeners are error-prone to wire up by hand with useEffect.
 */
@@ -655,9 +736,16 @@ const onEvent = ({ event, listener }, client = getDefaultClient()) => {
 * This function unsubscribes a previously registered event listener
 * from the specified Dynamic client event.
 *
+* @example
+* ```ts
+* offEvent({ event: 'walletAdded', listener: myListener });
+* ```
+*
 * @param params.event - The event name to remove the listener from.
 * @param params.listener - The callback function to remove.
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
+* @see onEvent
+* @see onceEvent
 * @notInstrumented
 */
 const offEvent = ({ event, listener }, client = getDefaultClient()) => {
@@ -670,10 +758,22 @@ const offEvent = ({ event, listener }, client = getDefaultClient()) => {
 * This function listens for an event that will automatically remove itself
 * after being triggered once.
 *
+* @example
+* ```ts
+* onceEvent({
+*   event: 'logout',
+*   listener: () => {
+*     console.log('User logged out');
+*   },
+* });
+* ```
+*
 * @param params.event - The event name to listen for.
 * @param params.listener - The callback function to execute when the event is fired.
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
 * @returns A function that can be called to remove the listener before it fires.
+* @see onEvent
+* @see offEvent
 * @notInstrumented
 * @hook Event listeners are error-prone to wire up by hand with useEffect.
 */
@@ -995,8 +1095,18 @@ const getWalletAccountsFromState = ({ unverifiedWalletAccounts, user }, client)
 * You can differentiate between verified and unverified wallet accounts by
 * checking the `verifiedCredentialId` property.
 *
+* @example
+* ```ts
+* const wallets = getWalletAccounts();
+* const verified = wallets.filter((walletAccount) =>
+*   isWalletAccountVerified({ walletAccount }),
+* );
+* ```
+*
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
 * @returns An array of wallet accounts associated with the session.
+* @see isWalletAccountVerified
+* @see verifyWalletAccount
 * @notInstrumented
 * @hook Exposed as a hook so consumers get the reactive list of wallet accounts.
 */
@@ -1215,18 +1325,6 @@ const getOperatingSystem = () => {
 	}
 };
 
-//#endregion
-//#region src/utils/getPlatform/getPlatform.ts
-/**
-* Returns the platform the SDK is running on.
-*
-* This is the web implementation — the React Native bundler resolves
-* `getPlatform.native.ts` instead when building for React Native, which
-* returns `'react-native'`.
-* @notInstrumented
-*/
-const getPlatform = () => "web";
-
 //#endregion
 //#region src/utils/getUserAgent/getUserAgent.ts
 /**
@@ -1417,193 +1515,170 @@ const scrubParameters = ({ piiFields, redactAll, value }) => {
 	});
 };
 
-//#endregion
-//#region src/services/instrumentation/instrumentFunction/extractParams/extractParams.ts
-/**
-* Normalises the raw positional arguments of an instrumented function call
-* into a flat `Record<string, unknown>` suitable for structured logging.
-*
-* ## Why this is needed
-*
-* Instrumented functions are wrapped with `(...args: unknown[])`, so their
-* parameters arrive as an array. Logging a raw array loses the semantic names
-* of each argument. This function recovers a named representation:
-*
-* - **No arguments** → `{}`
-* - **Single plain-object argument** → that object is returned as-is, because
-*   SDK functions follow the single-object-parameter convention, so the object
-*   already carries named keys (`{ amount, to }`, etc.).
-* - **Everything else** (multiple args, a single primitive, a single array) →
-*   each value is indexed as `arg0`, `arg1`, …
-*
-* ## Why arrays are NOT treated as plain objects
-*
-* `typeof [] === 'object'` and `[] !== null`, so without the `Array.isArray`
-* guard a single-array argument would be returned as-is. That would produce
-* an object with numeric string keys (`{ '0': ..., '1': ... }`), which is
-* misleading and inconsistent with how multi-arg calls are handled. Instead,
-* arrays fall through to the indexed `arg0` path.
-* @notInstrumented
-*/
-const extractParams = (args) => {
-	if (args.length === 0) return {};
-	if (args.length === 1 && typeof args[0] === "object" && args[0] !== null && !Array.isArray(args[0])) return args[0];
-	const result = {};
-	for (let i = 0; i < args.length; i++) result[`arg${i}`] = args[i];
-	return result;
-};
-
-//#endregion
-//#region src/services/instrumentation/instrumentFunction/scrubResolvedValue/scrubResolvedValue.ts
-/**
-* Scrubs a resolved return value of any type before logging it.
-* Routes through `scrubParameters` by wrapping the value so that strings,
-* arrays, Dates, Errors, and all other types are handled identically to
-* nested object fields.
-* @notInstrumented
-*/
-const scrubResolvedValue = ({ piiFields, redactAll, value }) => scrubParameters({
-	piiFields,
-	redactAll,
-	value: { result: value }
-}).result;
-
 //#endregion
 //#region src/services/instrumentation/instrumentFunction/instrumentFunction.ts
-const serializeError = (error) => {
-	if (error instanceof Error) return {
-		message: error.message,
-		name: error.name,
-		stack: error.stack
+const toErrorFields = (error) => {
+	if (error instanceof BaseError) return {
+		errorCode: error.code,
+		errorName: error.name
 	};
+	if (error instanceof Error) return { errorName: error.name };
+	return { errorName: "UnknownError" };
+};
+const buildContext = (core) => {
+	const state = core.state.get();
 	return {
-		message: String(error),
-		name: "UnknownError"
+		environmentId: core.environmentId,
+		operatingSystem: getOperatingSystem(),
+		platform: getPlatform(),
+		registeredExtensionKeys: Array.from(core.extensions),
+		sdkSessionId: core.sdkSessionId,
+		sdkVersion: core.version,
+		tokenSessionId: state.token ? extractSessionId(state.token) : null,
+		userAgent: getUserAgent(),
+		userId: state.user?.id ?? null
 	};
 };
 /**
+* Runs an explicit payload selector and scrubs its output. Returns `undefined`
+* when there is no selector. Selector (and scrub) errors are swallowed so a
+* faulty selector can never break the wrapped function or fabricate a
+* 'rejected' event — instrumentation stays purely observational. The swallowed
+* error is surfaced on the `debug` logger so internal devs can still spot a
+* broken selector without it ever reaching a transport.
+*/
+const safeSelect = ({ functionName, logger, piiFields, selector, value }) => {
+	if (!selector) return;
+	try {
+		return scrubParameters({
+			piiFields,
+			value: selector(value)
+		});
+	} catch (error) {
+		logger.debug(`[instrumentFunction] payload selector for "${functionName}" threw; emitting event without payload`, error);
+		return;
+	}
+};
+/**
 * Wraps a function so that each invocation emits a structured
 * `FunctionInstrumentationEvent` at three lifecycle points:
 *
-* - **started** — immediately before the function body executes, with the
-*   PII-scrubbed call parameters.
+* - **started** — immediately before the function body executes.
 * - **resolved** — after the function (or its returned Promise) settles
-*   successfully, with the PII-scrubbed return value.
+*   successfully, with the call duration.
 * - **rejected** — if the function throws synchronously or its returned
-*   Promise rejects.
+*   Promise rejects, with the duration and the error's class name/code.
+*
+* Events carry only the safe envelope (function name, phase, timing, error
+* class, SDK/runtime metadata, identifiers). **Raw arguments and return values
+* are never captured.** A function that needs additional fields supplies
+* `selectors` that build an explicit, primitive-only {@link SafePayload} — the
+* only path from arguments/return value into a log.
 *
 * The original return value (or thrown error) is always forwarded to the
-* caller unchanged — instrumentation is purely observational.
+* caller unchanged — instrumentation is purely observational, and a throwing
+* selector cannot change that.
+*
+* ## Providing selectors
 *
-* ## Usage
+* A function opts into a payload by supplying selectors that map its arguments
+* (`started`) and/or its awaited return value (`resolved`) to a primitive-only
+* {@link SafePayload}. Pick individual known-safe fields — never spread a whole
+* object, which is exactly what the model prevents.
 *
 * ```ts
 * const transfer = instrumentFunction({
 *   fn: rawTransfer,
 *   functionName: 'transfer',
 *   getCore: () => core,
+*   selectors: {
+*     // `args` is the argument tuple the wrapped function was called with.
+*     started: ([{ chainId, amount }]) => ({ amount, chainId }),
+*     // `result` is the awaited return value (never the Promise).
+*     resolved: ({ txHash }) => ({ txHash }),
+*   },
 * });
-*
-* // When called, three events are emitted automatically:
-* await transfer({ amount: 1, to: '0xabc' });
 * ```
 *
+* A selector that throws (or whose output fails scrubbing) is swallowed: the
+* event is still emitted without a payload, and the error is logged at `debug`.
+*
 * ## How functions are wrapped
 *
-* `instrumentFunction` is not called manually in application code. Instead,
-* the esbuild instrumentation plugin (`tools/instrumentation-plugin`) injects
-* it at build time: any exported function annotated with `@instrumented` in its
-* JSDoc is automatically wrapped by the plugin during the build step.
-* The plugin strips the original `export`, renames the function, and re-exports
-* it under the original name via `instrumentFunction(...)` — so the public API
-* is unchanged and no call sites need to be updated.
+* `instrumentFunction` is not called manually in application code. The esbuild
+* instrumentation plugin (`tools/instrumentation-plugin`) injects it at build
+* time for any exported function annotated with `@instrumented` in its JSDoc.
 *
 * ## Opting out
 *
-* Instrumentation is skipped entirely when:
-* - `getCore()` returns `undefined` (SDK not initialised), or
-* - `core.instrumentation.config.enabled` is `false`.
-*
-* In both cases the original function is called directly with no overhead.
-*
-* ## PII scrubbing
-*
-* All string values whose key appears in `piiFields` are replaced with
-* `"[redacted]"` before events are emitted. Pass `redactAll: true` to redact
-* every field, regardless of key name.
+* Instrumentation is skipped entirely when `getCore()` returns `undefined`
+* (SDK not initialised) or when `core.instrumentation.config.enabled` is
+* `false`; in both cases the original function is called directly.
 * @notInstrumented
 */
-const instrumentFunction = ({ fn, functionName, getCore: getCore$1, redactAll }) => {
+const instrumentFunction = ({ fn, functionName, getCore: getCore$1, selectors }) => {
 	const wrapped = (...args) => {
 		const core = getCore$1();
-		if (!core) return fn(...args);
-		if (!core.instrumentation.config.enabled) return fn(...args);
-		const instrumentation = core.instrumentation;
-		const state = core.state.get();
-		const baseEvent = {
-			environmentId: core.environmentId,
-			functionName,
-			operatingSystem: getOperatingSystem(),
-			parameters: scrubParameters({
-				piiFields: instrumentation.config.piiFields,
-				redactAll,
-				value: extractParams(args)
-			}),
-			platform: getPlatform(),
-			registeredExtensionKeys: Array.from(core.extensions),
-			sdkSessionId: core.sdkSessionId,
-			sdkVersion: core.version,
-			status: "info",
-			tokenSessionId: state.token ? extractSessionId(state.token) : null,
-			userAgent: getUserAgent(),
-			userId: state.user?.id ?? null
+		if (!core?.instrumentation.config.enabled) return fn(...args);
+		const { instrumentation, logger } = core;
+		const { piiFields } = instrumentation.config;
+		const base = {
+			...buildContext(core),
+			functionName
 		};
+		const startedAt = Date.now();
 		instrumentation.logFunction({
-			...baseEvent,
+			...base,
+			payload: safeSelect({
+				functionName,
+				logger,
+				piiFields,
+				selector: selectors?.started,
+				value: args
+			}),
 			phase: "started",
+			status: "info",
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
-		try {
-			const result = fn(...args);
-			if (result instanceof Promise) return result.then((value) => {
-				instrumentation.logFunction({
-					...baseEvent,
-					phase: "resolved",
-					resolvedValue: scrubResolvedValue({
-						piiFields: instrumentation.config.piiFields,
-						redactAll,
-						value
-					}),
-					timestamp: (/* @__PURE__ */ new Date()).toISOString()
-				});
-				return value;
-			}).catch((error) => {
-				instrumentation.logFunction({
-					...baseEvent,
-					phase: "rejected",
-					rejectedError: serializeError(error),
-					timestamp: (/* @__PURE__ */ new Date()).toISOString()
-				});
-				throw error;
-			});
+		const emitResolved = (value) => {
 			instrumentation.logFunction({
-				...baseEvent,
-				phase: "resolved",
-				resolvedValue: scrubResolvedValue({
-					piiFields: instrumentation.config.piiFields,
-					redactAll,
-					value: result
+				...base,
+				durationMs: Date.now() - startedAt,
+				payload: safeSelect({
+					functionName,
+					logger,
+					piiFields,
+					selector: selectors?.resolved,
+					value
 				}),
+				phase: "resolved",
+				status: "info",
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			return result;
-		} catch (error) {
+		};
+		const emitRejected = (error) => {
 			instrumentation.logFunction({
-				...baseEvent,
+				...base,
+				...toErrorFields(error),
+				durationMs: Date.now() - startedAt,
 				phase: "rejected",
-				rejectedError: serializeError(error),
+				status: "error",
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
+		};
+		try {
+			const result = fn(...args);
+			if (result instanceof Promise) return result.then((value) => {
+				emitResolved(value);
+				return value;
+			}, (error) => {
+				emitRejected(error);
+				throw error;
+			});
+			emitResolved(result);
+			return result;
+		} catch (error) {
+			emitRejected(error);
 			throw error;
 		}
 	};
@@ -1648,6 +1723,7 @@ const getWalletAccountsHash = (state, client) => getWalletAccountsFromState(stat
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
 * @returns True if the user needs additional MFA authentication, false otherwise.
 * @notInstrumented
+* @hook Exposed as a hook so consumers reactively know when MFA is still required, updated when the user changes.
 */
 const isUserMissingMfaAuth = (client = getDefaultClient()) => {
 	const user = client.user;
@@ -1893,7 +1969,7 @@ const updateAuthFromVerifyResponse = ({ response }, client) => {
 	* programmatically because Redcoast won't set the cookie via headers. We set the cookie programmatically
 	* so customers can access the cookie from document.cookie consistently between sandbox and live environments.
 	*/
-	if (minifiedJwt && isCookieEnabled(client)) setCookie(`${DYNAMIC_AUTH_COOKIE_NAME}=${minifiedJwt}; expires=${sessionExpiresAt.toUTCString()}; path=/; SameSite=Lax`);
+	if (minifiedJwt && isCookieEnabled(client)) setCookie(`${DYNAMIC_AUTH_COOKIE_NAME}=${minifiedJwt}; expires=${sessionExpiresAt.toUTCString()}; path=/; SameSite=Lax${getSecureCookieAttribute()}`);
 	checkAndRaiseWalletAccountsChangedEvent({ previousState }, client);
 	if (!previousState.user && Boolean(newState.user)) initializeWaasClientsForEagerRecovery(client);
 };
@@ -2175,6 +2251,12 @@ Object.defineProperty(exports, 'getPlatform', {
     return getPlatform;
   }
 });
+Object.defineProperty(exports, 'getSecureCookieAttribute', {
+  enumerable: true,
+  get: function () {
+    return getSecureCookieAttribute;
+  }
+});
 Object.defineProperty(exports, 'getSessionKeys', {
   enumerable: true,
   get: function () {
@@ -2337,4 +2419,4 @@ Object.defineProperty(exports, 'version', {
     return version;
   }
 });
-//# sourceMappingURL=updateAuthFromVerifyResponse-CElYpi97.cjs.map
+//# sourceMappingURL=updateAuthFromVerifyResponse-pgYXvDvj.cjs.map