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

package/dist/cjs/index.d.cts

@@ -1,88 +1,227 @@
-import { ErrorType, Result } from "@adobe/aio-commerce-lib-core/result";
-import { ValidationErrorType } from "@adobe/aio-commerce-lib-core/validation";
-import * as valibot25 from "valibot";
-import { InferInput, InferIssue, InferOutput } from "valibot";
-import * as url5 from "url";
+/**
+ * @license
+ * 
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import * as valibot21 from "valibot";
+import { InferOutput } from "valibot";
 
 //#region source/lib/ims-auth/schema.d.ts
+/** The environments accepted by the IMS auth service. */
 declare const IMS_AUTH_ENV: {
   readonly PROD: "prod";
   readonly STAGE: "stage";
 };
-declare const ImsAuthEnvSchema: valibot25.EnumSchema<{
+/** Validation schema for IMS auth environment values. */
+declare const ImsAuthEnvSchema: valibot21.EnumSchema<{
   readonly PROD: "prod";
   readonly STAGE: "stage";
 }, undefined>;
-declare const ImsAuthParamsSchema: valibot25.ObjectSchema<{
-  readonly AIO_COMMERCE_IMS_CLIENT_ID: valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_CLIENT_SECRETS: valibot25.SchemaWithPipe<readonly [valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>, valibot25.ParseJsonAction<string, undefined, undefined>]>, valibot25.ArraySchema<valibot25.StringSchema<undefined>, `Expected a stringified JSON array value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_ID: valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_EMAIL: valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_IMS_ORG_ID: valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_ENV: valibot25.SchemaWithPipe<readonly [valibot25.OptionalSchema<valibot25.EnumSchema<{
+/** Defines the schema to validate the necessary parameters for the IMS auth service. */
+declare const ImsAuthParamsSchema: valibot21.ObjectSchema<{
+  readonly clientId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly clientSecrets: valibot21.SchemaWithPipe<readonly [valibot21.SchemaWithPipe<readonly [valibot21.ArraySchema<valibot21.StringSchema<undefined>, `Expected a stringified JSON array value for the IMS auth parameter ${string}`>]>, valibot21.MinLengthAction<string[], 1, "Expected at least one client secret for IMS auth">]>;
+  readonly technicalAccountId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly technicalAccountEmail: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<"Expected a string value for the IMS auth parameter technicalAccountEmail">, valibot21.EmailAction<string, "Expected a valid email format for technicalAccountEmail">]>;
+  readonly imsOrgId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly environment: valibot21.SchemaWithPipe<readonly [valibot21.OptionalSchema<valibot21.EnumSchema<{
     readonly PROD: "prod";
     readonly STAGE: "stage";
   }, undefined>, "prod">]>;
-  readonly AIO_COMMERCE_IMS_CTX: valibot25.SchemaWithPipe<readonly [valibot25.OptionalSchema<valibot25.StringSchema<undefined>, "aio-commerce-sdk-creds">]>;
-  readonly AIO_COMMERCE_IMS_SCOPES: valibot25.SchemaWithPipe<readonly [valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>, valibot25.ParseJsonAction<string, undefined, undefined>]>, valibot25.ArraySchema<valibot25.StringSchema<undefined>, `Expected a stringified JSON array value for the IMS auth parameter ${string}`>]>;
+  readonly context: valibot21.SchemaWithPipe<readonly [valibot21.OptionalSchema<valibot21.StringSchema<undefined>, "aio-commerce-sdk-creds">]>;
+  readonly scopes: valibot21.SchemaWithPipe<readonly [valibot21.SchemaWithPipe<readonly [valibot21.ArraySchema<valibot21.StringSchema<undefined>, `Expected a stringified JSON array value for the IMS auth parameter ${string}`>]>, valibot21.MinLengthAction<string[], 1, "Expected at least one scope for IMS auth">]>;
 }, undefined>;
+/** Defines the parameters for the IMS auth service. */
 type ImsAuthParams = InferOutput<typeof ImsAuthParamsSchema>;
+/** Defines the environments accepted by the IMS auth service. */
 type ImsAuthEnv = InferOutput<typeof ImsAuthEnvSchema>;
 //#endregion
 //#region source/lib/ims-auth/provider.d.ts
-type ImsAccessToken = string;
+/** Defines the header keys used for IMS authentication. */
 type ImsAuthHeader = "Authorization" | "x-api-key";
+/** Defines the headers required for IMS authentication. */
 type ImsAuthHeaders = Record<ImsAuthHeader, string>;
-type ImsAuthValidationError = ValidationErrorType<"ImsAuthValidationError", InferIssue<typeof ImsAuthParamsSchema>[]>;
-type ImsAuthError<TError = unknown> = ErrorType<"ImsAuthError", {
-  message: string;
-  error: TError;
-}>;
-interface ImsAuthConfig {
-  clientId: string;
-  clientSecrets: string[];
-  technicalAccountId: string;
-  technicalAccountEmail: string;
-  imsOrgId: string;
-  scopes: string[];
-  environment: ImsAuthEnv;
-  context: string;
-}
+/** Defines an authentication provider for Adobe IMS. */
 interface ImsAuthProvider {
-  getAccessToken: () => Promise<Result<ImsAccessToken, ImsAuthError>>;
-  getHeaders: () => Promise<Result<ImsAuthHeaders, ImsAuthError>>;
+  getAccessToken: () => Promise<string>;
+  getHeaders: () => Promise<ImsAuthHeaders>;
 }
-declare function getImsAuthProvider(config: ImsAuthConfig): ImsAuthProvider;
-declare function tryGetImsAuthProvider(params: InferInput<typeof ImsAuthParamsSchema>): Result<ImsAuthProvider, ImsAuthValidationError>;
+/**
+ * Asserts the provided configuration for an {@link ImsAuthProvider}.
+ * @param config 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
+ * }
+ * ```
+ */
+declare function assertImsAuthParams(config: Record<PropertyKey, unknown>): asserts config is ImsAuthParams;
+/**
+ * Creates an {@link ImsAuthProvider} based on the provided configuration.
+ * @param authParams An {@link ImsAuthParams} parameter that contains the configuration for the {@link ImsAuthProvider}.
+ * @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()
+ * });
+ * ```
+ */
+declare function getImsAuthProvider(authParams: ImsAuthParams): {
+  getAccessToken: () => Promise<string>;
+  getHeaders: () => Promise<{
+    Authorization: string;
+    "x-api-key": string;
+  }>;
+};
 //#endregion
 //#region source/lib/integration-auth/schema.d.ts
-declare const HttpMethodSchema: valibot25.PicklistSchema<readonly ["GET", "POST", "PUT", "PATCH", "DELETE"], undefined>;
-type HttpMethodInput = InferInput<typeof HttpMethodSchema>;
-declare const UrlSchema: valibot25.SchemaWithPipe<readonly [valibot25.UnionSchema<[valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<"Expected a string for the Adobe Commerce endpoint">, valibot25.NonEmptyAction<string, "Expected a non-empty string for the Adobe Commerce endpoint">, valibot25.UrlAction<string, "Expected a valid url for the Adobe Commerce endpoint">]>, valibot25.InstanceSchema<typeof url5.URL, undefined>], undefined>, valibot25.TransformAction<string | url5.URL, string>]>;
-type AdobeCommerceUri = InferInput<typeof UrlSchema>;
-declare const IntegrationAuthParamsSchema: valibot25.NonOptionalSchema<valibot25.ObjectSchema<{
-  readonly AIO_COMMERCE_INTEGRATIONS_CONSUMER_KEY: valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly AIO_COMMERCE_INTEGRATIONS_CONSUMER_SECRET: valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN: valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN_SECRET: valibot25.SchemaWithPipe<readonly [valibot25.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot25.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+/**
+ * The HTTP methods supported by Commerce.
+ * This is used to determine which headers to include in the signing of the authorization header.
+ */
+type HttpMethodInput = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** Validation schema that accepts either a URL string or URL instance and normalizes to string. */
+
+/**
+ * The schema for the Commerce Integration parameters.
+ * This is used to validate the parameters passed to the Commerce Integration provider.
+ */
+declare const IntegrationAuthParamsSchema: valibot21.NonOptionalSchema<valibot21.ObjectSchema<{
+  readonly consumerKey: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly consumerSecret: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly accessToken: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly accessTokenSecret: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
 }, undefined>, undefined>;
-type IntegrationAuthParams = InferInput<typeof IntegrationAuthParamsSchema>;
+/** Defines the parameters required for Commerce Integration authentication. */
+type IntegrationAuthParams = InferOutput<typeof IntegrationAuthParamsSchema>;
 //#endregion
 //#region source/lib/integration-auth/provider.d.ts
+/** Defines the header key used for Commerce Integration authentication. */
 type IntegrationAuthHeader = "Authorization";
+/** Defines the headers required for Commerce Integration authentication. */
 type IntegrationAuthHeaders = Record<IntegrationAuthHeader, string>;
-interface IntegrationConfig {
-  consumerKey: string;
-  consumerSecret: string;
-  accessToken: string;
-  accessTokenSecret: string;
-}
-type ValidationIssues = InferIssue<typeof IntegrationAuthParamsSchema>[] | InferIssue<typeof UrlSchema>[];
-type IntegrationAuthError = ValidationErrorType<"IntegrationAuthValidationError", ValidationIssues>;
+/** Represents a URL for Adobe Commerce endpoints, accepting either string or URL object. */
+type AdobeCommerceUrl = string | URL;
+/** Defines an authentication provider for Adobe Commerce integrations. */
 interface IntegrationAuthProvider {
-  getHeaders: (method: HttpMethodInput, url: AdobeCommerceUri) => Result<IntegrationAuthHeaders, IntegrationAuthError>;
+  getHeaders: (method: HttpMethodInput, url: AdobeCommerceUrl) => IntegrationAuthHeaders;
 }
-declare function getIntegrationAuthProvider(config: IntegrationConfig): IntegrationAuthProvider;
-declare function tryGetIntegrationAuthProvider(params: IntegrationAuthParams): Result<IntegrationAuthProvider, IntegrationAuthError>;
+/**
+ * Asserts the provided configuration for an Adobe Commerce {@link IntegrationAuthProvider}.
+ * @param config 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
+ * }
+ * ```
+ */
+declare function assertIntegrationAuthParams(config: Record<PropertyKey, unknown>): asserts config is IntegrationAuthParams;
+/**
+ * Creates an {@link IntegrationAuthProvider} based on the provided configuration.
+ * @param authParams 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);
+ * ```
+ */
+declare function getIntegrationAuthProvider(authParams: IntegrationAuthParams): IntegrationAuthProvider;
 //#endregion
-export { IMS_AUTH_ENV, ImsAuthConfig, ImsAuthEnv, ImsAuthError, ImsAuthParams, ImsAuthProvider, IntegrationAuthError, IntegrationAuthParams, IntegrationAuthProvider, IntegrationConfig, getImsAuthProvider, getIntegrationAuthProvider, tryGetImsAuthProvider, tryGetIntegrationAuthProvider };
+export { IMS_AUTH_ENV, type ImsAuthEnv, type ImsAuthParams, type ImsAuthProvider, type IntegrationAuthParams, type IntegrationAuthProvider, assertImsAuthParams, assertIntegrationAuthParams, getImsAuthProvider, getIntegrationAuthProvider };

package/dist/es/index.d.ts

@@ -1,88 +1,227 @@
-import { ErrorType, Result } from "@adobe/aio-commerce-lib-core/result";
-import * as valibot0 from "valibot";
-import { InferInput, InferIssue, InferOutput } from "valibot";
-import { ValidationErrorType } from "@adobe/aio-commerce-lib-core/validation";
-import * as url39 from "url";
+/**
+ * @license
+ * 
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import * as valibot21 from "valibot";
+import { InferOutput } from "valibot";
 
 //#region source/lib/ims-auth/schema.d.ts
+/** The environments accepted by the IMS auth service. */
 declare const IMS_AUTH_ENV: {
   readonly PROD: "prod";
   readonly STAGE: "stage";
 };
-declare const ImsAuthEnvSchema: valibot0.EnumSchema<{
+/** Validation schema for IMS auth environment values. */
+declare const ImsAuthEnvSchema: valibot21.EnumSchema<{
   readonly PROD: "prod";
   readonly STAGE: "stage";
 }, undefined>;
-declare const ImsAuthParamsSchema: valibot0.ObjectSchema<{
-  readonly AIO_COMMERCE_IMS_CLIENT_ID: valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_CLIENT_SECRETS: valibot0.SchemaWithPipe<readonly [valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>, valibot0.ParseJsonAction<string, undefined, undefined>]>, valibot0.ArraySchema<valibot0.StringSchema<undefined>, `Expected a stringified JSON array value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_ID: valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_TECHNICAL_ACCOUNT_EMAIL: valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_IMS_ORG_ID: valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly AIO_COMMERCE_IMS_ENV: valibot0.SchemaWithPipe<readonly [valibot0.OptionalSchema<valibot0.EnumSchema<{
+/** Defines the schema to validate the necessary parameters for the IMS auth service. */
+declare const ImsAuthParamsSchema: valibot21.ObjectSchema<{
+  readonly clientId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly clientSecrets: valibot21.SchemaWithPipe<readonly [valibot21.SchemaWithPipe<readonly [valibot21.ArraySchema<valibot21.StringSchema<undefined>, `Expected a stringified JSON array value for the IMS auth parameter ${string}`>]>, valibot21.MinLengthAction<string[], 1, "Expected at least one client secret for IMS auth">]>;
+  readonly technicalAccountId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly technicalAccountEmail: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<"Expected a string value for the IMS auth parameter technicalAccountEmail">, valibot21.EmailAction<string, "Expected a valid email format for technicalAccountEmail">]>;
+  readonly imsOrgId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly environment: valibot21.SchemaWithPipe<readonly [valibot21.OptionalSchema<valibot21.EnumSchema<{
     readonly PROD: "prod";
     readonly STAGE: "stage";
   }, undefined>, "prod">]>;
-  readonly AIO_COMMERCE_IMS_CTX: valibot0.SchemaWithPipe<readonly [valibot0.OptionalSchema<valibot0.StringSchema<undefined>, "aio-commerce-sdk-creds">]>;
-  readonly AIO_COMMERCE_IMS_SCOPES: valibot0.SchemaWithPipe<readonly [valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>, valibot0.ParseJsonAction<string, undefined, undefined>]>, valibot0.ArraySchema<valibot0.StringSchema<undefined>, `Expected a stringified JSON array value for the IMS auth parameter ${string}`>]>;
+  readonly context: valibot21.SchemaWithPipe<readonly [valibot21.OptionalSchema<valibot21.StringSchema<undefined>, "aio-commerce-sdk-creds">]>;
+  readonly scopes: valibot21.SchemaWithPipe<readonly [valibot21.SchemaWithPipe<readonly [valibot21.ArraySchema<valibot21.StringSchema<undefined>, `Expected a stringified JSON array value for the IMS auth parameter ${string}`>]>, valibot21.MinLengthAction<string[], 1, "Expected at least one scope for IMS auth">]>;
 }, undefined>;
+/** Defines the parameters for the IMS auth service. */
 type ImsAuthParams = InferOutput<typeof ImsAuthParamsSchema>;
+/** Defines the environments accepted by the IMS auth service. */
 type ImsAuthEnv = InferOutput<typeof ImsAuthEnvSchema>;
 //#endregion
 //#region source/lib/ims-auth/provider.d.ts
-type ImsAccessToken = string;
+/** Defines the header keys used for IMS authentication. */
 type ImsAuthHeader = "Authorization" | "x-api-key";
+/** Defines the headers required for IMS authentication. */
 type ImsAuthHeaders = Record<ImsAuthHeader, string>;
-type ImsAuthValidationError = ValidationErrorType<"ImsAuthValidationError", InferIssue<typeof ImsAuthParamsSchema>[]>;
-type ImsAuthError<TError = unknown> = ErrorType<"ImsAuthError", {
-  message: string;
-  error: TError;
-}>;
-interface ImsAuthConfig {
-  clientId: string;
-  clientSecrets: string[];
-  technicalAccountId: string;
-  technicalAccountEmail: string;
-  imsOrgId: string;
-  scopes: string[];
-  environment: ImsAuthEnv;
-  context: string;
-}
+/** Defines an authentication provider for Adobe IMS. */
 interface ImsAuthProvider {
-  getAccessToken: () => Promise<Result<ImsAccessToken, ImsAuthError>>;
-  getHeaders: () => Promise<Result<ImsAuthHeaders, ImsAuthError>>;
+  getAccessToken: () => Promise<string>;
+  getHeaders: () => Promise<ImsAuthHeaders>;
 }
-declare function getImsAuthProvider(config: ImsAuthConfig): ImsAuthProvider;
-declare function tryGetImsAuthProvider(params: InferInput<typeof ImsAuthParamsSchema>): Result<ImsAuthProvider, ImsAuthValidationError>;
+/**
+ * Asserts the provided configuration for an {@link ImsAuthProvider}.
+ * @param config 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
+ * }
+ * ```
+ */
+declare function assertImsAuthParams(config: Record<PropertyKey, unknown>): asserts config is ImsAuthParams;
+/**
+ * Creates an {@link ImsAuthProvider} based on the provided configuration.
+ * @param authParams An {@link ImsAuthParams} parameter that contains the configuration for the {@link ImsAuthProvider}.
+ * @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()
+ * });
+ * ```
+ */
+declare function getImsAuthProvider(authParams: ImsAuthParams): {
+  getAccessToken: () => Promise<string>;
+  getHeaders: () => Promise<{
+    Authorization: string;
+    "x-api-key": string;
+  }>;
+};
 //#endregion
 //#region source/lib/integration-auth/schema.d.ts
-declare const HttpMethodSchema: valibot0.PicklistSchema<readonly ["GET", "POST", "PUT", "PATCH", "DELETE"], undefined>;
-type HttpMethodInput = InferInput<typeof HttpMethodSchema>;
-declare const UrlSchema: valibot0.SchemaWithPipe<readonly [valibot0.UnionSchema<[valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<"Expected a string for the Adobe Commerce endpoint">, valibot0.NonEmptyAction<string, "Expected a non-empty string for the Adobe Commerce endpoint">, valibot0.UrlAction<string, "Expected a valid url for the Adobe Commerce endpoint">]>, valibot0.InstanceSchema<typeof url39.URL, undefined>], undefined>, valibot0.TransformAction<string | url39.URL, string>]>;
-type AdobeCommerceUri = InferInput<typeof UrlSchema>;
-declare const IntegrationAuthParamsSchema: valibot0.NonOptionalSchema<valibot0.ObjectSchema<{
-  readonly AIO_COMMERCE_INTEGRATIONS_CONSUMER_KEY: valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly AIO_COMMERCE_INTEGRATIONS_CONSUMER_SECRET: valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN: valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly AIO_COMMERCE_INTEGRATIONS_ACCESS_TOKEN_SECRET: valibot0.SchemaWithPipe<readonly [valibot0.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot0.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+/**
+ * The HTTP methods supported by Commerce.
+ * This is used to determine which headers to include in the signing of the authorization header.
+ */
+type HttpMethodInput = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** Validation schema that accepts either a URL string or URL instance and normalizes to string. */
+
+/**
+ * The schema for the Commerce Integration parameters.
+ * This is used to validate the parameters passed to the Commerce Integration provider.
+ */
+declare const IntegrationAuthParamsSchema: valibot21.NonOptionalSchema<valibot21.ObjectSchema<{
+  readonly consumerKey: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly consumerSecret: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly accessToken: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly accessTokenSecret: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
 }, undefined>, undefined>;
-type IntegrationAuthParams = InferInput<typeof IntegrationAuthParamsSchema>;
+/** Defines the parameters required for Commerce Integration authentication. */
+type IntegrationAuthParams = InferOutput<typeof IntegrationAuthParamsSchema>;
 //#endregion
 //#region source/lib/integration-auth/provider.d.ts
+/** Defines the header key used for Commerce Integration authentication. */
 type IntegrationAuthHeader = "Authorization";
+/** Defines the headers required for Commerce Integration authentication. */
 type IntegrationAuthHeaders = Record<IntegrationAuthHeader, string>;
-interface IntegrationConfig {
-  consumerKey: string;
-  consumerSecret: string;
-  accessToken: string;
-  accessTokenSecret: string;
-}
-type ValidationIssues = InferIssue<typeof IntegrationAuthParamsSchema>[] | InferIssue<typeof UrlSchema>[];
-type IntegrationAuthError = ValidationErrorType<"IntegrationAuthValidationError", ValidationIssues>;
+/** Represents a URL for Adobe Commerce endpoints, accepting either string or URL object. */
+type AdobeCommerceUrl = string | URL;
+/** Defines an authentication provider for Adobe Commerce integrations. */
 interface IntegrationAuthProvider {
-  getHeaders: (method: HttpMethodInput, url: AdobeCommerceUri) => Result<IntegrationAuthHeaders, IntegrationAuthError>;
+  getHeaders: (method: HttpMethodInput, url: AdobeCommerceUrl) => IntegrationAuthHeaders;
 }
-declare function getIntegrationAuthProvider(config: IntegrationConfig): IntegrationAuthProvider;
-declare function tryGetIntegrationAuthProvider(params: IntegrationAuthParams): Result<IntegrationAuthProvider, IntegrationAuthError>;
+/**
+ * Asserts the provided configuration for an Adobe Commerce {@link IntegrationAuthProvider}.
+ * @param config 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
+ * }
+ * ```
+ */
+declare function assertIntegrationAuthParams(config: Record<PropertyKey, unknown>): asserts config is IntegrationAuthParams;
+/**
+ * Creates an {@link IntegrationAuthProvider} based on the provided configuration.
+ * @param authParams 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);
+ * ```
+ */
+declare function getIntegrationAuthProvider(authParams: IntegrationAuthParams): IntegrationAuthProvider;
 //#endregion
-export { IMS_AUTH_ENV, ImsAuthConfig, ImsAuthEnv, ImsAuthError, ImsAuthParams, ImsAuthProvider, IntegrationAuthError, IntegrationAuthParams, IntegrationAuthProvider, IntegrationConfig, getImsAuthProvider, getIntegrationAuthProvider, tryGetImsAuthProvider, tryGetIntegrationAuthProvider };
+export { IMS_AUTH_ENV, type ImsAuthEnv, type ImsAuthParams, type ImsAuthProvider, type IntegrationAuthParams, type IntegrationAuthProvider, assertImsAuthParams, assertIntegrationAuthParams, getImsAuthProvider, getIntegrationAuthProvider };