@ahoo-wang/fetcher-cosec 3.0.5 → 3.0.8

package/README.md

@@ -126,9 +126,15 @@ const fetcher = new Fetcher({
   baseURL: 'https://api.example.com',
 });
 
-// Create CoSec configurer with minimal required configuration
+// Create CoSec configurer with flexible configuration
 const configurer = new CoSecConfigurer({
   appId: 'your-app-id',
+
+  // Optional: Custom storage implementations
+  tokenStorage: new TokenStorage(),
+  deviceIdStorage: new DeviceIdStorage(),
+
+  // Optional: Token refresher (enables authentication interceptors)
   tokenRefresher: {
     refresh: async token => {
       // Implement your token refresh logic
@@ -149,6 +155,7 @@ const configurer = new CoSecConfigurer({
       };
     },
   },
+
   // Optional: Custom error handlers (only add interceptors if provided)
   onUnauthorized: exchange => {
     console.error('Unauthorized access:', exchange.request.url);
@@ -159,7 +166,7 @@ const configurer = new CoSecConfigurer({
     console.error('Forbidden access:', exchange.request.url);
     // Show permission error
     alert('You do not have permission to access this resource');
-  }
+  },
 });
 
 // Apply all CoSec interceptors with one call
@@ -171,9 +178,10 @@ const response = await fetcher.get('/protected-endpoint');
 
 ### Benefits of CoSecConfigurer
 
-- ✅ **One-line setup**: `configurer.applyTo(fetcher)` configures everything
-- ✅ **Minimal configuration**: Only `appId` and `tokenRefresher` are required
-- ✅ **Sensible defaults**: Automatic error handling and parameter names
+- ✅ **Flexible configuration**: Support for full auth setup or minimal CoSec headers only
+- ✅ **Custom storage**: Optional custom TokenStorage and DeviceIdStorage implementations
+- ✅ **Conditional interceptors**: Authentication interceptors only added when tokenRefresher is provided
+- ✅ **Error handler control**: Choose which error interceptors to add based on your needs
 - ✅ **Type-safe**: Full TypeScript support with intelligent defaults
 - ✅ **Backward compatible**: Original manual setup still works
 
@@ -235,6 +243,12 @@ The recommended way to configure CoSec authentication. Provides a simplified API
 ```typescript
 const configurer = new CoSecConfigurer({
   appId: 'your-app-id',
+
+  // Optional: Custom storage implementations
+  tokenStorage: new TokenStorage('custom-prefix'),
+  deviceIdStorage: new DeviceIdStorage('custom-prefix'),
+
+  // Optional: Token refresher (enables auth interceptors)
   tokenRefresher: {
     refresh: async token => {
       // Your token refresh implementation
@@ -244,6 +258,7 @@ const configurer = new CoSecConfigurer({
       };
     },
   },
+
   // Optional error handlers (interceptors only added if provided)
   onUnauthorized: exchange => {
     /* handle 401 */
@@ -251,21 +266,27 @@ const configurer = new CoSecConfigurer({
   onForbidden: async exchange => {
     /* handle 403 */
   },
-  tenantId: 'tenantId', // default: 'tenantId'
-  ownerId: 'ownerId', // default: 'ownerId'
 });
 
 configurer.applyTo(fetcher);
 ```
 
-**Automatically Configured Interceptors:**
+**Conditionally Configured Interceptors:**
+
+Always added:
+
+- `CoSecRequestInterceptor` - Adds CoSec headers (appId, deviceId, requestId)
+- `ResourceAttributionRequestInterceptor` - Adds tenant/owner path parameters
+
+Only when `tokenRefresher` is provided:
+
+- `AuthorizationRequestInterceptor` - Adds Bearer token authentication
+- `AuthorizationResponseInterceptor` - Handles token refresh on 401 responses
+
+Only when corresponding handlers are provided:
 
-- `CoSecRequestInterceptor` - Adds CoSec headers
-- `AuthorizationRequestInterceptor` - Adds Bearer token
-- `ResourceAttributionRequestInterceptor` - Adds tenant/owner parameters
-- `AuthorizationResponseInterceptor` - Handles token refresh
-- `UnauthorizedErrorInterceptor` - Handles 401 errors
-- `ForbiddenErrorInterceptor` - Handles 403 errors
+- `UnauthorizedErrorInterceptor` - Handles 401 unauthorized errors
+- `ForbiddenErrorInterceptor` - Handles 403 forbidden errors
 
 #### AuthorizationRequestInterceptor
 

package/README.zh-CN.md

@@ -126,9 +126,15 @@ const fetcher = new Fetcher({
   baseURL: 'https://api.example.com',
 });
 
-// 使用最少的必需配置创建 CoSec 配置器
+// 使用灵活的配置创建 CoSec 配置器
 const configurer = new CoSecConfigurer({
   appId: 'your-app-id',
+
+  // 可选：自定义存储实现
+  tokenStorage: new TokenStorage(),
+  deviceIdStorage: new DeviceIdStorage(),
+
+  // 可选：令牌刷新器（启用认证拦截器）
   tokenRefresher: {
     refresh: async token => {
       // 实现您的令牌刷新逻辑
@@ -149,6 +155,7 @@ const configurer = new CoSecConfigurer({
       };
     },
   },
+
   // 可选：自定义错误处理器（仅在提供时才添加拦截器）
   onUnauthorized: exchange => {
     console.error('未授权访问:', exchange.request.url);
@@ -159,7 +166,7 @@ const configurer = new CoSecConfigurer({
     console.error('禁止访问:', exchange.request.url);
     // 显示权限错误
     alert('您没有权限访问此资源');
-  }
+  },
 });
 
 // 使用一次调用应用所有 CoSec 拦截器
@@ -171,9 +178,10 @@ const response = await fetcher.get('/protected-endpoint');
 
 ### CoSecConfigurer 的优势
 
-- ✅ **一行设置**：`configurer.applyTo(fetcher)` 配置一切
-- ✅ **最小配置**：仅需要 `appId` 和 `tokenRefresher`
-- ✅ **合理的默认值**：自动错误处理和参数名称
+- ✅ **灵活配置**：支持完整认证设置或仅最小的 CoSec 头部
+- ✅ **自定义存储**：可选的自定义 TokenStorage 和 DeviceIdStorage 实现
+- ✅ **条件拦截器**：仅在提供 tokenRefresher 时才添加认证拦截器
+- ✅ **错误处理器控制**：根据需要选择添加哪些错误拦截器
 - ✅ **类型安全**：完整的 TypeScript 支持和智能默认值
 - ✅ **向后兼容**：原始手动设置仍然有效
 
@@ -235,6 +243,12 @@ interface JwtTokenManagerCapable {
 ```typescript
 const configurer = new CoSecConfigurer({
   appId: 'your-app-id',
+
+  // 可选：自定义存储实现
+  tokenStorage: new TokenStorage('custom-prefix'),
+  deviceIdStorage: new DeviceIdStorage('custom-prefix'),
+
+  // 可选：令牌刷新器（启用认证拦截器）
   tokenRefresher: {
     refresh: async token => {
       // 您的令牌刷新实现
@@ -244,6 +258,7 @@ const configurer = new CoSecConfigurer({
       };
     },
   },
+
   // 可选错误处理器（仅在提供时才添加拦截器）
   onUnauthorized: exchange => {
     /* 处理 401 */
@@ -251,21 +266,27 @@ const configurer = new CoSecConfigurer({
   onForbidden: async exchange => {
     /* 处理 403 */
   },
-  tenantId: 'tenantId', // 默认: 'tenantId'
-  ownerId: 'ownerId', // 默认: 'ownerId'
 });
 
 configurer.applyTo(fetcher);
 ```
 
-**自动配置的拦截器：**
+**条件配置的拦截器：**
+
+始终添加：
+
+- `CoSecRequestInterceptor` - 添加 CoSec 头部（appId、deviceId、requestId）
+- `ResourceAttributionRequestInterceptor` - 添加租户/所有者路径参数
+
+仅在提供 `tokenRefresher` 时添加：
+
+- `AuthorizationRequestInterceptor` - 添加 Bearer 令牌认证
+- `AuthorizationResponseInterceptor` - 处理 401 响应时的令牌刷新
+
+仅在提供相应处理器时添加：
 
-- `CoSecRequestInterceptor` - 添加 CoSec 头部
-- `AuthorizationRequestInterceptor` - 添加 Bearer 令牌
-- `ResourceAttributionRequestInterceptor` - 添加租户/所有者参数
-- `AuthorizationResponseInterceptor` - 处理令牌刷新
-- `UnauthorizedErrorInterceptor` - 处理 401 错误
-- `ForbiddenErrorInterceptor` - 处理 403 错误
+- `UnauthorizedErrorInterceptor` - 处理 401 未授权错误
+- `ForbiddenErrorInterceptor` - 处理 403 禁止错误
 
 #### AuthorizationRequestInterceptor
 

package/dist/cosecConfigurer.d.ts

@@ -3,24 +3,38 @@ import { DeviceIdStorage } from './deviceIdStorage';
 import { JwtTokenManager } from './jwtTokenManager';
 import { TokenRefresher } from './tokenRefresher';
 import { TokenStorage } from './tokenStorage';
+import { AppIdCapable, DeviceIdStorageCapable } from './types';
 /**
  * Simplified configuration interface for CoSec setup.
- * Only requires the essential configuration, with sensible defaults for everything else.
+ * Provides flexible configuration with sensible defaults for optional components.
  */
-export interface CoSecConfig {
+export interface CoSecConfig extends AppIdCapable, Partial<DeviceIdStorageCapable> {
     /**
      * Application ID to be sent in the CoSec-App-Id header.
      * This is required for identifying your application in the CoSec system.
      */
     appId: string;
+    /**
+     * Custom token storage implementation.
+     * If not provided, a default TokenStorage instance will be created.
+     * Useful for custom storage backends or testing scenarios.
+     */
+    tokenStorage?: TokenStorage;
+    /**
+     * Custom device ID storage implementation.
+     * If not provided, a default DeviceIdStorage instance will be created.
+     * Useful for custom device identification strategies or testing scenarios.
+     */
+    deviceIdStorage?: DeviceIdStorage;
     /**
      * Token refresher implementation for handling expired tokens.
-     * This is required to enable automatic token refresh functionality.
+     * If not provided, authentication interceptors will not be added.
+     * This enables CoSec configuration without full JWT authentication.
      */
-    tokenRefresher: TokenRefresher;
+    tokenRefresher?: TokenRefresher;
     /**
      * Callback function invoked when an unauthorized (401) response is detected.
-     * If not provided, defaults to throwing an error.
+     * If not provided, 401 errors will not be intercepted.
      */
     onUnauthorized?: (exchange: FetchExchange) => Promise<void> | void;
     /**
@@ -30,19 +44,24 @@ export interface CoSecConfig {
     onForbidden?: (exchange: FetchExchange) => Promise<void>;
 }
 /**
- * CoSecConfigurer provides a simplified way to configure all CoSec interceptors
+ * CoSecConfigurer provides a flexible way to configure CoSec interceptors
  * and dependencies with a single configuration object.
  *
- * This class automatically creates all necessary dependencies (TokenStorage, DeviceIdStorage,
- * JwtTokenManager) and configures all CoSec interceptors with sensible defaults.
+ * This class implements FetcherConfigurer and supports both full authentication
+ * setups and minimal CoSec header injection. It conditionally creates dependencies
+ * based on the provided configuration, allowing for different levels of integration.
+ *
+ * @implements {FetcherConfigurer}
  *
  * @example
+ * Full authentication setup with custom storage:
  * ```typescript
  * const configurer = new CoSecConfigurer({
  *   appId: 'my-app-001',
+ *   tokenStorage: new CustomTokenStorage(),
+ *   deviceIdStorage: new CustomDeviceStorage(),
  *   tokenRefresher: {
  *     refresh: async (token: CompositeToken) => {
- *       // Your token refresh logic here
  *       const response = await fetch('/api/auth/refresh', {
  *         method: 'POST',
  *         body: JSON.stringify({ refreshToken: token.refreshToken }),
@@ -54,6 +73,19 @@ export interface CoSecConfig {
  *       };
  *     },
  *   },
+ *   onUnauthorized: (exchange) => redirectToLogin(),
+ *   onForbidden: (exchange) => showPermissionError(),
+ * });
+ *
+ * configurer.applyTo(fetcher);
+ * ```
+ *
+ * @example
+ * Minimal setup with only CoSec headers (no authentication):
+ * ```typescript
+ * const configurer = new CoSecConfigurer({
+ *   appId: 'my-app-001',
+ *   // No tokenRefresher provided - authentication interceptors won't be added
  * });
  *
  * configurer.applyTo(fetcher);
@@ -61,27 +93,77 @@ export interface CoSecConfig {
  */
 export declare class CoSecConfigurer implements FetcherConfigurer {
     readonly config: CoSecConfig;
+    /**
+     * Token storage instance, either provided in config or auto-created.
+     */
     readonly tokenStorage: TokenStorage;
+    /**
+     * Device ID storage instance, either provided in config or auto-created.
+     */
     readonly deviceIdStorage: DeviceIdStorage;
-    readonly tokenManager: JwtTokenManager;
+    /**
+     * JWT token manager instance, only created if tokenRefresher is provided.
+     * When undefined, authentication interceptors will not be added.
+     */
+    readonly tokenManager?: JwtTokenManager;
     /**
      * Creates a new CoSecConfigurer instance with the provided configuration.
      *
-     * @param config - Simplified CoSec configuration
+     * This constructor conditionally creates dependencies based on the configuration:
+     * - TokenStorage and DeviceIdStorage are always created (using defaults if not provided)
+     * - JwtTokenManager is only created if tokenRefresher is provided
+     *
+     * @param config - CoSec configuration object
+     *
+     * @example
+     * ```typescript
+     * // Full setup with all dependencies
+     * const configurer = new CoSecConfigurer({
+     *   appId: 'my-app',
+     *   tokenRefresher: myTokenRefresher,
+     * });
+     *
+     * // Minimal setup with custom storage
+     * const configurer = new CoSecConfigurer({
+     *   appId: 'my-app',
+     *   tokenStorage: customStorage,
+     *   deviceIdStorage: customDeviceStorage,
+     * });
+     * ```
      */
     constructor(config: CoSecConfig);
     /**
-     * Applies all CoSec interceptors to the provided Fetcher instance.
+     * Applies CoSec interceptors to the provided Fetcher instance.
      *
-     * This method configures the following interceptors in the correct order:
+     * This method conditionally configures interceptors based on the provided configuration:
+     *
+     * Always added:
      * 1. CoSecRequestInterceptor - Adds CoSec headers (appId, deviceId, requestId)
-     * 2. AuthorizationRequestInterceptor - Adds Authorization header with Bearer token
-     * 3. ResourceAttributionRequestInterceptor - Adds tenant/owner path parameters
-     * 4. AuthorizationResponseInterceptor - Handles 401 responses with token refresh
-     * 5. UnauthorizedErrorInterceptor - Handles unauthorized errors
-     * 6. ForbiddenErrorInterceptor - Handles forbidden errors
+     * 2. ResourceAttributionRequestInterceptor - Adds tenant/owner path parameters
+     *
+     * Only when `tokenRefresher` is provided:
+     * 3. AuthorizationRequestInterceptor - Adds Bearer token authentication
+     * 4. AuthorizationResponseInterceptor - Handles token refresh on 401 responses
+     *
+     * Only when corresponding handlers are provided:
+     * 5. UnauthorizedErrorInterceptor - Handles 401 unauthorized errors
+     * 6. ForbiddenErrorInterceptor - Handles 403 forbidden errors
      *
      * @param fetcher - The Fetcher instance to configure
+     *
+     * @example
+     * ```typescript
+     * const fetcher = new Fetcher({ baseURL: '/api' });
+     * const configurer = new CoSecConfigurer({
+     *   appId: 'my-app',
+     *   tokenRefresher: myTokenRefresher,
+     *   onUnauthorized: handle401,
+     *   onForbidden: handle403,
+     * });
+     *
+     * configurer.applyTo(fetcher);
+     * // Now fetcher has all CoSec interceptors configured
+     * ```
      */
     applyTo(fetcher: Fetcher): void;
 }

package/dist/cosecConfigurer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cosecConfigurer.d.ts","sourceRoot":"","sources":["../src/cosecConfigurer.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAI/E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAE/B;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEnE;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,eAAgB,YAAW,iBAAiB;aAU3B,MAAM,EAAE,WAAW;IAT/C,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IAEvC;;;;OAIG;gBACyB,MAAM,EAAE,WAAW;IAY/C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CA0ChC"}
+{"version":3,"file":"cosecConfigurer.d.ts","sourceRoot":"","sources":["../src/cosecConfigurer.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAI/E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,YAAY,EAAE,OAAO,CAAC,sBAAsB,CAAC;IAChF;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;;OAIG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEnE;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,eAAgB,YAAW,iBAAiB;aA0C3B,MAAM,EAAE,WAAW;IAzC/C;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;gBACyB,MAAM,EAAE,WAAW;IAc/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CA0ChC"}

package/dist/deviceIdStorage.d.ts

@@ -1,12 +1,12 @@
 import { KeyStorage, KeyStorageOptions } from '@ahoo-wang/fetcher-storage';
 export declare const DEFAULT_COSEC_DEVICE_ID_KEY = "cosec-device-id";
-export interface DeviceIdStorageOptions extends KeyStorageOptions<string> {
+export interface DeviceIdStorageOptions extends Partial<KeyStorageOptions<string>> {
 }
 /**
  * Storage class for managing device identifiers.
  */
 export declare class DeviceIdStorage extends KeyStorage<string> {
-    constructor(options?: DeviceIdStorageOptions);
+    constructor({ key, eventBus, ...reset }?: DeviceIdStorageOptions);
     /**
      * Generate a new device ID.
      *

package/dist/deviceIdStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deviceIdStorage.d.ts","sourceRoot":"","sources":["../src/deviceIdStorage.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,UAAU,EAAE,iBAAiB,EAC9B,MAAM,4BAA4B,CAAC;AAGpC,eAAO,MAAM,2BAA2B,oBAAoB,CAAC;AAG7D,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB,CAAC,MAAM,CAAC;CACxE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,UAAU,CAAC,MAAM,CAAC;gBACzC,OAAO,GAAE,sBAGpB;IAID;;;;OAIG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;OAIG;IACH,WAAW,IAAI,MAAM;CAWtB"}
+{"version":3,"file":"deviceIdStorage.d.ts","sourceRoot":"","sources":["../src/deviceIdStorage.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,UAAU,EAAE,iBAAiB,EAC9B,MAAM,4BAA4B,CAAC;AAGpC,eAAO,MAAM,2BAA2B,oBAAoB,CAAC;AAG7D,MAAM,WAAW,sBAAuB,SAAQ,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;CACjF;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,UAAU,CAAC,MAAM,CAAC;gBACzC,EACE,GAAiC,EACjC,QAAyG,EACzG,GAAG,KAAK,EACT,GAAE,sBAA2B;IAI1C;;;;OAIG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;OAIG;IACH,WAAW,IAAI,MAAM;CAWtB"}