@adobe/aio-commerce-lib-auth 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @adobe/aio-commerce-lib-auth
 
+## 0.3.0
+
+### Minor Changes
+
+- [#22](https://github.com/adobe/aio-commerce-sdk/pull/22) [`9885eee`](https://github.com/adobe/aio-commerce-sdk/commit/9885eee5849ba7939b2067d3357e677beced3774) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Changes include:
+  - Removed `try*` methods from public interface
+  - Added `assert` methods that throw if required configuration is not provided
+  - Cleaned up unused types to reduce bundle size
+
+### Patch Changes
+
+- Updated dependencies [[`9885eee`](https://github.com/adobe/aio-commerce-sdk/commit/9885eee5849ba7939b2067d3357e677beced3774)]:
+  - @adobe/aio-commerce-lib-core@0.3.0
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -11,29 +11,15 @@ This library provides a unified interface for authentication in Adobe Commerce A
 
 The library supports two main authentication providers:
 
-- **IMS Provider**: For authenticating users or services via Adobe Identity Management System (IMS) using OAuth2.
-  - Required Params
-    - AIO_COMMERCE_IMS_CLIENT_ID: string
-    - AIO_COMMERCE_IMS_CLIENT_SECRETS: string
-    - AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_ID: string
-    - AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_EMAIL: string
-    - AIO_COMMERCE_IMS_IMS_ORG_ID: string
-    - AIO_COMMERCE_IMS_ENV: string e.g `'prod'` or `'stage'`
-    - AIO_COMMERCE_IMS_SCOPES: string e.g `'["value1", "value2"]'`
-    - AIO_COMMERCE_IMS_CTX: string
-- **Integrations Provider**: For authenticating with Adobe Commerce integrations using OAuth 1.0a.
-  - Required params
-    - AIO_COMMERCE_INTEGRATIONS_CONSUMER_KEY: string
-    - AIO_COMMERCE_INTEGRATIONS_CONSUMER_SECRET: string
-    - AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN: string
-    - AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN_SECRET: string
+- **IMS Provider**: For authenticating users or services via Adobe Identity Management System (IMS) using OAuth2
+- **Integrations Provider**: For authenticating with Adobe Commerce integrations using OAuth 1.0a
 
 These providers abstract the complexity of authentication, making it easy to obtain and use access tokens in your App Builder applications.
 
 ## Installation
 
 ```shell
-npm install @adobe/aio-commerce-lib-auth
+pnpm install @adobe/aio-commerce-lib-auth
 ```
 
 ## Usage
@@ -42,86 +28,111 @@ In your App Builder application, you can use the library to authenticate users o
 
 ### IMS Provider
 
-In the runtime action you can generate an access token using the IMS Provider:
-
 ```typescript
-import { tryGetImsAuthProvider } from "@adobe/aio-commerce-lib-auth";
-import { isErr, unwrap } from "@adobe/aio-commerce-lib-core";
+import {
+  assertImsAuthParams,
+  getImsAuthProvider,
+} from "@adobe/aio-commerce-lib-auth";
 
-export const main = async function (params: Record<string, unknown>) {
-  const result = tryGetImsAuthProvider(params); // Validate parameters and get the integration auth provider
-
-  if (isErr(result)) {
-    const { error } = result;
-    return {
-      statusCode: 400,
-      body: {
-        error: `Unable to get IMS Auth Provider ${error.message}`,
-      },
-    };
-  }
+import { CommerceSdkValidationError } from "@adobe/aio-commerce-lib-core";
 
-  const imsAuthProvider = unwrap(result);
-  const headersResult = imsAuthProvider.getHeaders();
-
-  if (isErr(headersResult)) {
-    const { error } = result;
-    return {
-      statusCode: 400,
-      body: {
-        error: `Unable to get auth headers for IMS Auth Provider ${error.message}`,
-      },
-    };
+export const main = async function (params: Record<string, unknown>) {
+  try {
+    // Validate parameters and get the IMS auth provider
+    assertImsAuthParams(params);
+    const imsAuthProvider = getImsAuthProvider(params);
+
+    const token = await imsAuthProvider.getAccessToken();
+    const headers = await imsAuthProvider.getHeaders();
+
+    // Use headers in your API calls
+    // business logic e.g requesting orders
+    return { statusCode: 200 };
+  } catch (error) {
+    if (error instanceof CommerceSdkValidationError) {
+      return {
+        statusCode: 400,
+        body: {
+          error: `Invalid IMS configuration: ${error.message}`,
+        },
+      };
+    }
+    throw error;
   }
-
-  // business logic e.g requesting orders
-  return { statusCode: 200 };
 };
 ```
 
 ### Integrations Provider
 
-In the runtime action you can generate an access token using the Integrations Provider:
-
 ```typescript
-import { tryGetIntegrationAuthProvider } from "@adobe/aio-commerce-lib-auth";
-import { isErr, unwrapErr, unwrap } from "@adobe/aio-commerce-lib-core";
+import {
+  assertIntegrationAuthParams,
+  getIntegrationAuthProvider,
+} from "@adobe/aio-commerce-lib-auth";
+
+import { CommerceSdkValidationError } from "@adobe/aio-commerce-lib-core";
 
 export const main = async function (params: Record<string, unknown>) {
-  const result = tryGetIntegrationAuthProvider(params); // Validate parameters and get the integration auth provider
-
-  if (isErr(result)) {
-    const { error } = result;
-    return {
-      statusCode: 400,
-      body: {
-        error: `Unable to get Integration Auth Provider ${error.message}`,
-      },
-    };
+  try {
+    // Validate parameters and get the integration auth provider
+    assertIntegrationAuthParams(params);
+    const integrationsAuth = getIntegrationAuthProvider(params);
+
+    // Get OAuth headers for API requests
+    const headers = integrationsAuth.getHeaders(
+      "GET",
+      "http://localhost/rest/V1/orders",
+    );
+
+    // Use headers in your API calls
+    // business logic e.g requesting orders
+    return { statusCode: 200 };
+  } catch (error) {
+    if (error instanceof CommerceSdkValidationError) {
+      return {
+        statusCode: 400,
+        body: {
+          error: `Invalid Integration configuration: ${error.message}`,
+        },
+      };
+    }
+    throw error;
   }
+};
+```
 
-  const integrationsAuth = unwrap(result);
-  const headersResult = integrationsAuth.getHeaders(
-    "GET",
-    "http://localhost/rest/V1/orders",
-  );
-
-  if (isErr(headersResult)) {
-    const { error } = result;
-    return {
-      statusCode: 400,
-      body: {
-        error: `Unable to get auth headers for Integration Auth Provider ${error.message}`,
-      },
-    };
-  }
+## Error Handling
 
-  // business logic e.g requesting orders
+The library uses validation to ensure all required parameters are provided and correctly formatted. When validation fails, a `CommerceSdkValidationError` is thrown with detailed information about what went wrong.
 
-  return { statusCode: 200 };
-};
+```typescript
+import { CommerceSdkValidationError } from "@adobe/aio-commerce-lib-core/error";
+
+try {
+  assertImsAuthParams({
+    clientId: "valid-id",
+    // Missing required fields
+  });
+} catch (error) {
+  if (error instanceof CommerceSdkValidationError) {
+    console.error(error.display());
+    // Output:
+    // Invalid ImsAuthProvider configuration
+    // ├── Schema validation error at clientSecrets → Expected at least one client secret for IMS auth
+    // ├── Schema validation error at technicalAccountId → Expected a non-empty string value for the IMS auth parameter technicalAccountId
+    // └── Schema validation error at technicalAccountEmail → Expected a valid email format for technicalAccountEmail
+  }
+}
 ```
 
+## Best Practices
+
+1. **Always validate parameters** - Use the `assert*` functions before creating providers
+2. **Handle errors gracefully** - Catch and properly handle validation and authentication errors
+3. **Store credentials securely** - Use environment variables or secure configuration management
+4. **Cache tokens when possible** - The IMS provider handles token lifecycle internally
+5. **Use TypeScript** - Leverage the full type safety provided by the library
+
 ## Contributing
 
 This package is part of the Adobe Commerce SDK monorepo. See the [Contributing Guide](https://github.com/adobe/aio-commerce-sdk/blob/main/.github/CONTRIBUTING.md) and [Development Guide](https://github.com/adobe/aio-commerce-sdk/blob/main/.github/DEVELOPMENT.md) for development setup and guidelines.

package/dist/cjs/index.cjs

@@ -21,41 +21,58 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const __adobe_aio_commerce_lib_core_result = __toESM(require("@adobe/aio-commerce-lib-core/result"));
+const __adobe_aio_commerce_lib_core_error = __toESM(require("@adobe/aio-commerce-lib-core/error"));
 const __adobe_aio_lib_ims = __toESM(require("@adobe/aio-lib-ims"));
 const valibot = __toESM(require("valibot"));
 const node_crypto = __toESM(require("node:crypto"));
 const oauth_1_0a = __toESM(require("oauth-1.0a"));
 
 //#region source/lib/ims-auth/schema.ts
+/**
+* Creates a validation schema for a required IMS auth string parameter.
+* @param name The name of the parameter for error messages.
+* @returns A validation pipeline that ensures the parameter is a non-empty string.
+*/
 const imsAuthParameter = (name) => (0, valibot.pipe)((0, valibot.string)(`Expected a string value for the IMS auth parameter ${name}`), (0, valibot.nonEmpty)(`Expected a non-empty string value for the IMS auth parameter ${name}`));
-const jsonStringArray = (name) => {
-	const jsonStringArraySchema = (0, valibot.message)((0, valibot.pipe)((0, valibot.string)(`Expected a string value for the IMS auth parameter ${name}`), (0, valibot.nonEmpty)(`Expected a non-empty string value for the IMS auth parameter ${name}`), (0, valibot.parseJson)()), `An error occurred while parsing the JSON string array parameter ${name}`);
-	return (0, valibot.pipe)(jsonStringArraySchema, (0, valibot.array)((0, valibot.string)(), `Expected a stringified JSON array value for the IMS auth parameter ${name}`));
+/**
+* Creates a validation schema for an IMS auth string array parameter.
+* @param name The name of the parameter for error messages.
+* @returns A validation pipeline that ensures the parameter is an array of strings.
+*/
+const stringArray = (name) => {
+	return (0, valibot.pipe)((0, valibot.array)((0, valibot.string)(), `Expected a stringified JSON array value for the IMS auth parameter ${name}`));
 };
 /** The environments accepted by the IMS auth service. */
 const IMS_AUTH_ENV = {
 	PROD: "prod",
 	STAGE: "stage"
 };
+/** Validation schema for IMS auth environment values. */
 const ImsAuthEnvSchema = (0, valibot.enum)(IMS_AUTH_ENV);
 /** Defines the schema to validate the necessary parameters for the IMS auth service. */
 const ImsAuthParamsSchema = (0, valibot.object)({
-	AIO_COMMERCE_IMS_CLIENT_ID: imsAuthParameter("AIO_COMMERCE_IMS_CLIENT_ID"),
-	AIO_COMMERCE_IMS_CLIENT_SECRETS: jsonStringArray("AIO_COMMERCE_IMS_CLIENT_SECRETS"),
-	AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_ID: imsAuthParameter("AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_ID"),
-	AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_EMAIL: imsAuthParameter("AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_EMAIL"),
-	AIO_COMMERCE_IMS_IMS_ORG_ID: imsAuthParameter("AIO_COMMERCE_IMS_IMS_ORG_ID"),
-	AIO_COMMERCE_IMS_ENV: (0, valibot.pipe)((0, valibot.optional)(ImsAuthEnvSchema, IMS_AUTH_ENV.PROD)),
-	AIO_COMMERCE_IMS_CTX: (0, valibot.pipe)((0, valibot.optional)((0, valibot.string)(), "aio-commerce-sdk-creds")),
-	AIO_COMMERCE_IMS_SCOPES: jsonStringArray("AIO_COMMERCE_IMS_SCOPES")
+	clientId: imsAuthParameter("clientId"),
+	clientSecrets: (0, valibot.pipe)(stringArray("clientSecrets"), (0, valibot.minLength)(1, "Expected at least one client secret for IMS auth")),
+	technicalAccountId: imsAuthParameter("technicalAccountId"),
+	technicalAccountEmail: (0, valibot.pipe)((0, valibot.string)("Expected a string value for the IMS auth parameter technicalAccountEmail"), (0, valibot.email)("Expected a valid email format for technicalAccountEmail")),
+	imsOrgId: imsAuthParameter("imsOrgId"),
+	environment: (0, valibot.pipe)((0, valibot.optional)(ImsAuthEnvSchema, IMS_AUTH_ENV.PROD)),
+	context: (0, valibot.pipe)((0, valibot.optional)((0, valibot.string)(), "aio-commerce-sdk-creds")),
+	scopes: (0, valibot.pipe)(stringArray("scopes"), (0, valibot.minLength)(1, "Expected at least one scope for IMS auth"))
 });
 
 //#endregion
 //#region source/lib/ims-auth/provider.ts
-function snakeCaseImsAuthConfig(config) {
+/**
+* Converts IMS auth configuration properties to snake_case format.
+* @param config The IMS auth configuration with camelCase properties.
+* @returns The configuration with snake_case properties.
+*/
+function toImsAuthConfig(config) {
 	return {
-		...config,
+		scopes: config.scopes,
+		env: config?.environment ?? "prod",
+		context: config.context,
 		client_id: config.clientId,
 		client_secrets: config.clientSecrets,
 		technical_account_id: config.technicalAccountId,
@@ -63,90 +80,112 @@ function snakeCaseImsAuthConfig(config) {
 		ims_org_id: config.imsOrgId
 	};
 }
-function makeImsAuthValidationError(message, issues) {
-	return {
-		_tag: "ImsAuthValidationError",
-		message,
-		issues
-	};
-}
-function makeImsAuthError(message, error) {
-	return {
-		_tag: "ImsAuthError",
-		message,
-		error
-	};
-}
-function fromParams$1(params) {
-	return {
-		clientId: params.AIO_COMMERCE_IMS_CLIENT_ID,
-		clientSecrets: params.AIO_COMMERCE_IMS_CLIENT_SECRETS,
-		technicalAccountId: params.AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_ID,
-		technicalAccountEmail: params.AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_EMAIL,
-		imsOrgId: params.AIO_COMMERCE_IMS_IMS_ORG_ID,
-		scopes: params.AIO_COMMERCE_IMS_SCOPES,
-		environment: params.AIO_COMMERCE_IMS_ENV,
-		context: params.AIO_COMMERCE_IMS_CTX
-	};
-}
-async function tryGetAccessToken(contextName) {
-	try {
-		const accessToken = await (0, __adobe_aio_lib_ims.getToken)(contextName, {});
-		return (0, __adobe_aio_commerce_lib_core_result.ok)(accessToken);
-	} catch (error) {
-		return (0, __adobe_aio_commerce_lib_core_result.err)(makeImsAuthError("Failed to retrieve IMS access token", error));
-	}
+/**
+* Asserts the provided configuration for an Adobe IMS authentication provider. {@link ImsAuthParams}
+* {@link ImsAuthProvider}
+* @param config {Record<PropertyKey, unknown>} The configuration to validate.
+* @throws {CommerceSdkValidationError} If the configuration is invalid.
+* @example
+* ```typescript
+* const config = {
+*   clientId: "your-client-id",
+*   clientSecrets: ["your-client-secret"],
+*   technicalAccountId: "your-technical-account-id",
+*   technicalAccountEmail: "your-account@example.com",
+*   imsOrgId: "your-ims-org-id@AdobeOrg",
+*   scopes: ["AdobeID", "openid"],
+*   environment: "prod", // or "stage"
+*   context: "my-app-context"
+* };
+*
+* // This will validate the config and throw if invalid
+* assertImsAuthParams(config);
+*```
+* @example
+* ```typescript
+* // Example of a failing assert:
+* try {
+*   assertImsAuthParams({
+*     clientId: "valid-client-id",
+*     // Missing required fields like clientSecrets, technicalAccountId, etc.
+*   });
+* } catch (error) {
+*   console.error(error.message); // "Invalid ImsAuthProvider configuration"
+*   console.error(error.issues); // Array of validation issues
+* }
+* ```
+*/
+function assertImsAuthParams(config) {
+	const result = (0, valibot.safeParse)(ImsAuthParamsSchema, config);
+	if (!result.success) throw new __adobe_aio_commerce_lib_core_error.CommerceSdkValidationError("Invalid ImsAuthProvider configuration", { issues: result.issues });
 }
 /**
 * Creates an {@link ImsAuthProvider} based on the provided configuration.
-* @param config The configuration for the IMS Auth Provider.
+* @param config An {@link ImsAuthParams} parameter that contains the configuration for the IMS auth provider.
 * @returns An {@link ImsAuthProvider} instance that can be used to get access token and auth headers.
+* @example
+* ```typescript
+* const config = {
+*   clientId: "your-client-id",
+*   clientSecrets: ["your-client-secret"],
+*   technicalAccountId: "your-technical-account-id",
+*   technicalAccountEmail: "your-account@example.com",
+*   imsOrgId: "your-ims-org-id@AdobeOrg",
+*   scopes: ["AdobeID", "openid"],
+*   environment: "prod",
+*   context: "my-app-context"
+* };
+*
+* const authProvider = getImsAuthProvider(config);
+*
+* // Get access token
+* const token = await authProvider.getAccessToken();
+* console.log(token); // "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
+*
+* // Get headers for API requests
+* const headers = await authProvider.getHeaders();
+* console.log(headers);
+* // {
+* //   Authorization: "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+* //   "x-api-key": "your-client-id"
+* // }
+*
+* // Use headers in API calls
+* const response = await fetch('https://api.adobe.io/some-endpoint', {
+*   headers: await authProvider.getHeaders()
+* });
+* ```
 */
-function getImsAuthProvider(config) {
+function getImsAuthProvider(authParams) {
 	const getAccessToken = async () => {
-		const snakeCasedConfig = snakeCaseImsAuthConfig(config);
-		await __adobe_aio_lib_ims.context.set(config.context, snakeCasedConfig);
-		return tryGetAccessToken(config.context);
+		const imsAuthConfig = toImsAuthConfig(authParams);
+		await __adobe_aio_lib_ims.context.set(authParams.context, imsAuthConfig);
+		return (0, __adobe_aio_lib_ims.getToken)(authParams.context, {});
 	};
 	const getHeaders = async () => {
-		const result = await getAccessToken();
-		return (0, __adobe_aio_commerce_lib_core_result.map)(result, (accessToken) => ({
+		const accessToken = await getAccessToken();
+		return {
 			Authorization: `Bearer ${accessToken}`,
-			"x-api-key": config.clientId
-		}));
+			"x-api-key": authParams.clientId
+		};
 	};
 	return {
 		getAccessToken,
 		getHeaders
 	};
 }
-/**
-* Tries to create an {@link ImsAuthProvider} based on the provided parameters.
-* @param params The parameters required to create the IMS Auth Provider.
-* @returns An {@link ImsAuthProvider} instance that can be used to get access token and auth headers.
-*/
-function tryGetImsAuthProvider(params) {
-	const validation = (0, valibot.safeParse)(ImsAuthParamsSchema, params);
-	if (!validation.success) return (0, __adobe_aio_commerce_lib_core_result.err)(makeImsAuthValidationError("Failed to validate the provided IMS parameters", validation.issues));
-	return (0, __adobe_aio_commerce_lib_core_result.ok)(getImsAuthProvider(fromParams$1(validation.output)));
-}
 
 //#endregion
 //#region source/lib/integration-auth/schema.ts
 /**
-* The HTTP methods supported by Commerce.
-* This is used to determine which headers to include in the signing of the authorization header.
+* Creates a validation schema for a required Commerce Integration string parameter.
+* @param name The name of the parameter for error messages.
+* @returns A validation pipeline that ensures the parameter is a non-empty string.
 */
-const AllowedHttpMethod = [
-	"GET",
-	"POST",
-	"PUT",
-	"PATCH",
-	"DELETE"
-];
-const HttpMethodSchema = (0, valibot.picklist)(AllowedHttpMethod);
 const integrationAuthParameter = (name) => (0, valibot.pipe)((0, valibot.string)(`Expected a string value for the Commerce Integration parameter ${name}`), (0, valibot.nonEmpty)(`Expected a non-empty string value for the Commerce Integration parameter ${name}`));
+/** Validation schema for the Adobe Commerce endpoint base URL. */
 const BaseUrlSchema = (0, valibot.pipe)((0, valibot.string)("Expected a string for the Adobe Commerce endpoint"), (0, valibot.nonEmpty)("Expected a non-empty string for the Adobe Commerce endpoint"), (0, valibot.url)("Expected a valid url for the Adobe Commerce endpoint"));
+/** Validation schema that accepts either a URL string or URL instance and normalizes to string. */
 const UrlSchema = (0, valibot.pipe)((0, valibot.union)([BaseUrlSchema, (0, valibot.instance)(URL)]), (0, valibot.transform)((url) => {
 	if (url instanceof URL) return url.toString();
 	return url;
@@ -156,73 +195,98 @@ const UrlSchema = (0, valibot.pipe)((0, valibot.union)([BaseUrlSchema, (0, valib
 * This is used to validate the parameters passed to the Commerce Integration provider.
 */
 const IntegrationAuthParamsSchema = (0, valibot.nonOptional)((0, valibot.object)({
-	AIO_COMMERCE_INTEGRATIONS_CONSUMER_KEY: integrationAuthParameter("AIO_COMMERCE_INTEGRATIONS_CONSUMER_KEY"),
-	AIO_COMMERCE_INTEGRATIONS_CONSUMER_SECRET: integrationAuthParameter("AIO_COMMERCE_INTEGRATIONS_CONSUMER_SECRET"),
-	AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN: integrationAuthParameter("AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN"),
-	AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN_SECRET: integrationAuthParameter("AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN_SECRET")
+	consumerKey: integrationAuthParameter("consumerKey"),
+	consumerSecret: integrationAuthParameter("consumerSecret"),
+	accessToken: integrationAuthParameter("accessToken"),
+	accessTokenSecret: integrationAuthParameter("accessTokenSecret")
 }));
 
 //#endregion
 //#region source/lib/integration-auth/provider.ts
-function makeIntegrationAuthValidationError(message, issues) {
-	return {
-		_tag: "IntegrationAuthValidationError",
-		message,
-		issues
-	};
-}
-function fromParams(params) {
-	return {
-		consumerKey: params.AIO_COMMERCE_INTEGRATIONS_CONSUMER_KEY,
-		consumerSecret: params.AIO_COMMERCE_INTEGRATIONS_CONSUMER_SECRET,
-		accessToken: params.AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN,
-		accessTokenSecret: params.AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN_SECRET
-	};
+/**
+* Asserts the provided configuration for an Adobe Commerce integration authentication provider. {@link IntegrationAuthParams}
+* {@link IntegrationAuthProvider}
+* @param config {Record<PropertyKey, unknown>} The configuration to validate.
+* @throws {CommerceSdkValidationError} If the configuration is invalid.
+* @example
+* ```typescript
+* const config = {
+*   consumerKey: "your-consumer-key",
+*   consumerSecret: "your-consumer-secret",
+*   accessToken: "your-access-token",
+*   accessTokenSecret: "your-access-token-secret"
+* };
+*
+* // This will validate the config and throw if invalid
+* assertIntegrationAuthParams(config);
+* ```
+* @example
+* ```typescript
+* // Example of a failing assert:
+* try {
+*   assertIntegrationAuthParams({
+*     consumerKey: "valid-consumer-key",
+*     // Missing required fields like consumerSecret, accessToken, accessTokenSecret
+*   });
+* } catch (error) {
+*   console.error(error.message); // "Invalid IntegrationAuthProvider configuration"
+*   console.error(error.issues); // Array of validation issues
+* }
+* ```
+*/
+function assertIntegrationAuthParams(config) {
+	const result = (0, valibot.safeParse)(IntegrationAuthParamsSchema, config);
+	if (!result.success) throw new __adobe_aio_commerce_lib_core_error.CommerceSdkValidationError("Invalid IntegrationAuthProvider configuration", { issues: result.issues });
 }
 /**
 * Creates an {@link IntegrationAuthProvider} based on the provided configuration.
-* @param config The configuration for the integration.
+* @param config {IntegrationAuthParams} The configuration for the integration.
 * @returns An {@link IntegrationAuthProvider} instance that can be used to get auth headers.
+* @example
+* ```typescript
+* const config = {
+*   consumerKey: "your-consumer-key",
+*   consumerSecret: "your-consumer-secret",
+*   accessToken: "your-access-token",
+*   accessTokenSecret: "your-access-token-secret"
+* };
+*
+* const authProvider = getIntegrationAuthProvider(config);
+*
+* // Get OAuth headers for a REST API call
+* const headers = authProvider.getHeaders("GET", "https://your-store.com/rest/V1/products");
+* console.log(headers); // { Authorization: "OAuth oauth_consumer_key=..., oauth_signature=..." }
+*
+* // Can also be used with URL objects
+* const url = new URL("https://your-store.com/rest/V1/customers");
+* const postHeaders = authProvider.getHeaders("POST", url);
+* ```
 */
-function getIntegrationAuthProvider(config) {
+function getIntegrationAuthProvider(authParams) {
 	const oauth = new oauth_1_0a.default({
 		consumer: {
-			key: config.consumerKey,
-			secret: config.consumerSecret
+			key: authParams.consumerKey,
+			secret: authParams.consumerSecret
 		},
 		signature_method: "HMAC-SHA256",
 		hash_function: (baseString, key) => node_crypto.default.createHmac("sha256", key).update(baseString).digest("base64")
 	});
 	const oauthToken = {
-		key: config.accessToken,
-		secret: config.accessTokenSecret
+		key: authParams.accessToken,
+		secret: authParams.accessTokenSecret
 	};
-	const getHeaders = (method, url) => {
-		const uriValidation = (0, valibot.safeParse)(UrlSchema, url);
-		if (!uriValidation.success) return (0, __adobe_aio_commerce_lib_core_result.err)(makeIntegrationAuthValidationError("Failed to validate the provided Adobe Commerce URL", uriValidation.issues));
-		const finalUrl = uriValidation.output;
-		const headers = oauth.toHeader(oauth.authorize({
-			url: finalUrl,
+	return { getHeaders: (method, url) => {
+		const urlString = url instanceof URL ? url.toString() : url;
+		return oauth.toHeader(oauth.authorize({
+			url: urlString,
 			method
 		}, oauthToken));
-		return (0, __adobe_aio_commerce_lib_core_result.ok)(headers);
-	};
-	return { getHeaders };
-}
-/**
-* Tries to create an {@link IntegrationAuthProvider} based on the provided parameters.
-* @param params The parameters required for integration authentication.
-* @returns An {@link IntegrationAuthProvider} instance that can be used to get auth headers.
-*/
-function tryGetIntegrationAuthProvider(params) {
-	const validation = (0, valibot.safeParse)(IntegrationAuthParamsSchema, params);
-	if (!validation.success) return (0, __adobe_aio_commerce_lib_core_result.err)(makeIntegrationAuthValidationError("Failed to validate the provided integration parameters", validation.issues));
-	return (0, __adobe_aio_commerce_lib_core_result.ok)(getIntegrationAuthProvider(fromParams(validation.output)));
+	} };
 }
 
 //#endregion
 exports.IMS_AUTH_ENV = IMS_AUTH_ENV;
+exports.assertImsAuthParams = assertImsAuthParams;
+exports.assertIntegrationAuthParams = assertIntegrationAuthParams;
 exports.getImsAuthProvider = getImsAuthProvider;
-exports.getIntegrationAuthProvider = getIntegrationAuthProvider;
-exports.tryGetImsAuthProvider = tryGetImsAuthProvider;
-exports.tryGetIntegrationAuthProvider = tryGetIntegrationAuthProvider;
+exports.getIntegrationAuthProvider = getIntegrationAuthProvider;