@ahoo-wang/fetcher-cosec 3.0.3 → 3.0.6

package/README.md

@@ -26,6 +26,7 @@ This package provides seamless integration between the Fetcher HTTP client and t
 - **⚡ Performance Optimized**: Minimal overhead with connection pooling and caching
 - **🛠️ TypeScript First**: Complete type definitions with strict type safety
 - **🔌 Pluggable Architecture**: Modular design for easy integration and customization
+- **⚙️ Simplified Configuration**: One-line setup with `CoSecConfigurer` for minimal configuration overhead
 
 ## 🚀 Quick Start
 
@@ -112,6 +113,78 @@ fetcher.interceptors.response.use(
 );
 ```
 
+## 🚀 Simplified Setup (Recommended)
+
+For a much simpler setup experience, use the `CoSecConfigurer` class which automatically handles all the complex dependency creation and interceptor configuration:
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { CoSecConfigurer } from '@ahoo-wang/fetcher-cosec';
+
+// Create a Fetcher instance
+const fetcher = new Fetcher({
+  baseURL: 'https://api.example.com',
+});
+
+// Create CoSec configurer with flexible configuration
+const configurer = new CoSecConfigurer({
+  appId: 'your-app-id',
+
+  // Optional: Custom storage implementations
+  tokenStorage: new TokenStorage('my-app-tokens'),
+  deviceIdStorage: new DeviceIdStorage('my-app-devices'),
+
+  // Optional: Token refresher (enables authentication interceptors)
+  tokenRefresher: {
+    refresh: async token => {
+      // Implement your token refresh logic
+      const response = await fetch('/api/auth/refresh', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refreshToken: token.refreshToken }),
+      });
+
+      if (!response.ok) {
+        throw new Error('Token refresh failed');
+      }
+
+      const tokens = await response.json();
+      return {
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+      };
+    },
+  },
+
+  // Optional: Custom error handlers (only add interceptors if provided)
+  onUnauthorized: exchange => {
+    console.error('Unauthorized access:', exchange.request.url);
+    // Redirect to login or handle as needed
+    window.location.href = '/login';
+  },
+  onForbidden: async exchange => {
+    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
+configurer.applyTo(fetcher);
+
+// Now you can use the fetcher with full CoSec authentication
+const response = await fetcher.get('/protected-endpoint');
+```
+
+### Benefits of CoSecConfigurer
+
+- ✅ **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
+
 ## 🔧 Configuration
 
 ### CoSecOptions Interface
@@ -163,6 +236,58 @@ The interceptor automatically adds the following headers to requests:
 
 ### Core Classes
 
+#### CoSecConfigurer
+
+The recommended way to configure CoSec authentication. Provides a simplified API that automatically creates and configures all necessary interceptors and dependencies.
+
+```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
+      return {
+        accessToken: 'new-access-token',
+        refreshToken: 'new-refresh-token',
+      };
+    },
+  },
+
+  // Optional error handlers (interceptors only added if provided)
+  onUnauthorized: exchange => {
+    /* handle 401 */
+  },
+  onForbidden: async exchange => {
+    /* handle 403 */
+  },
+});
+
+configurer.applyTo(fetcher);
+```
+
+**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:
+
+- `UnauthorizedErrorInterceptor` - Handles 401 unauthorized errors
+- `ForbiddenErrorInterceptor` - Handles 403 forbidden errors
+
 #### AuthorizationRequestInterceptor
 
 Automatically adds CoSec authentication headers to outgoing HTTP requests.

package/README.zh-CN.md

@@ -26,6 +26,7 @@
 - **⚡ 性能优化**：最小开销，支持连接池和缓存
 - **🛠️ TypeScript 优先**：完整类型定义，严格类型安全
 - **🔌 可插拔架构**：模块化设计，易于集成和定制
+- **⚙️ 简化配置**：使用 `CoSecConfigurer` 的一行设置，最小化配置开销
 
 ## 🚀 快速开始
 
@@ -112,6 +113,78 @@ fetcher.interceptors.response.use(
 );
 ```
 
+## 🚀 简化设置（推荐）
+
+为了获得更简单的设置体验，请使用 `CoSecConfigurer` 类，它会自动处理所有复杂的依赖创建和拦截器配置：
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { CoSecConfigurer } from '@ahoo-wang/fetcher-cosec';
+
+// 创建 Fetcher 实例
+const fetcher = new Fetcher({
+  baseURL: 'https://api.example.com',
+});
+
+// 使用灵活的配置创建 CoSec 配置器
+const configurer = new CoSecConfigurer({
+  appId: 'your-app-id',
+
+  // 可选：自定义存储实现
+  tokenStorage: new TokenStorage('my-app-tokens'),
+  deviceIdStorage: new DeviceIdStorage('my-app-devices'),
+
+  // 可选：令牌刷新器（启用认证拦截器）
+  tokenRefresher: {
+    refresh: async token => {
+      // 实现您的令牌刷新逻辑
+      const response = await fetch('/api/auth/refresh', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refreshToken: token.refreshToken }),
+      });
+
+      if (!response.ok) {
+        throw new Error('Token refresh failed');
+      }
+
+      const tokens = await response.json();
+      return {
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+      };
+    },
+  },
+
+  // 可选：自定义错误处理器（仅在提供时才添加拦截器）
+  onUnauthorized: exchange => {
+    console.error('未授权访问:', exchange.request.url);
+    // 重定向到登录或根据需要处理
+    window.location.href = '/login';
+  },
+  onForbidden: async exchange => {
+    console.error('禁止访问:', exchange.request.url);
+    // 显示权限错误
+    alert('您没有权限访问此资源');
+  },
+});
+
+// 使用一次调用应用所有 CoSec 拦截器
+configurer.applyTo(fetcher);
+
+// 现在您可以使用具有完整 CoSec 认证的 fetcher
+const response = await fetcher.get('/protected-endpoint');
+```
+
+### CoSecConfigurer 的优势
+
+- ✅ **灵活配置**：支持完整认证设置或仅最小的 CoSec 头部
+- ✅ **自定义存储**：可选的自定义 TokenStorage 和 DeviceIdStorage 实现
+- ✅ **条件拦截器**：仅在提供 tokenRefresher 时才添加认证拦截器
+- ✅ **错误处理器控制**：根据需要选择添加哪些错误拦截器
+- ✅ **类型安全**：完整的 TypeScript 支持和智能默认值
+- ✅ **向后兼容**：原始手动设置仍然有效
+
 ## 🔧 配置
 
 ### CoSecOptions 接口
@@ -163,6 +236,58 @@ interface JwtTokenManagerCapable {
 
 ### 核心类
 
+#### CoSecConfigurer
+
+配置 CoSec 认证的推荐方式。提供简化的 API，自动创建和配置所有必要的拦截器和依赖项。
+
+```typescript
+const configurer = new CoSecConfigurer({
+  appId: 'your-app-id',
+
+  // 可选：自定义存储实现
+  tokenStorage: new TokenStorage('custom-prefix'),
+  deviceIdStorage: new DeviceIdStorage('custom-prefix'),
+
+  // 可选：令牌刷新器（启用认证拦截器）
+  tokenRefresher: {
+    refresh: async token => {
+      // 您的令牌刷新实现
+      return {
+        accessToken: 'new-access-token',
+        refreshToken: 'new-refresh-token',
+      };
+    },
+  },
+
+  // 可选错误处理器（仅在提供时才添加拦截器）
+  onUnauthorized: exchange => {
+    /* 处理 401 */
+  },
+  onForbidden: async exchange => {
+    /* 处理 403 */
+  },
+});
+
+configurer.applyTo(fetcher);
+```
+
+**条件配置的拦截器：**
+
+始终添加：
+
+- `CoSecRequestInterceptor` - 添加 CoSec 头部（appId、deviceId、requestId）
+- `ResourceAttributionRequestInterceptor` - 添加租户/所有者路径参数
+
+仅在提供 `tokenRefresher` 时添加：
+
+- `AuthorizationRequestInterceptor` - 添加 Bearer 令牌认证
+- `AuthorizationResponseInterceptor` - 处理 401 响应时的令牌刷新
+
+仅在提供相应处理器时添加：
+
+- `UnauthorizedErrorInterceptor` - 处理 401 未授权错误
+- `ForbiddenErrorInterceptor` - 处理 403 禁止错误
+
 #### AuthorizationRequestInterceptor
 
 自动向传出 HTTP 请求添加 CoSec 认证头部。

package/dist/cosecConfigurer.d.ts

@@ -0,0 +1,169 @@
+import { Fetcher, FetcherConfigurer, FetchExchange } from '@ahoo-wang/fetcher';
+import { DeviceIdStorage } from './deviceIdStorage';
+import { JwtTokenManager } from './jwtTokenManager';
+import { TokenRefresher } from './tokenRefresher';
+import { TokenStorage } from './tokenStorage';
+/**
+ * Simplified configuration interface for CoSec setup.
+ * Provides flexible configuration with sensible defaults for optional components.
+ */
+export interface CoSecConfig {
+    /**
+     * 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.
+     * If not provided, authentication interceptors will not be added.
+     * This enables CoSec configuration without full JWT authentication.
+     */
+    tokenRefresher?: TokenRefresher;
+    /**
+     * Callback function invoked when an unauthorized (401) response is detected.
+     * If not provided, 401 errors will not be intercepted.
+     */
+    onUnauthorized?: (exchange: FetchExchange) => Promise<void> | void;
+    /**
+     * Callback function invoked when a forbidden (403) response is detected.
+     * If not provided, 403 errors will not be intercepted.
+     */
+    onForbidden?: (exchange: FetchExchange) => Promise<void>;
+}
+/**
+ * CoSecConfigurer provides a flexible way to configure CoSec interceptors
+ * and dependencies with a single configuration object.
+ *
+ * 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) => {
+ *       const response = await fetch('/api/auth/refresh', {
+ *         method: 'POST',
+ *         body: JSON.stringify({ refreshToken: token.refreshToken }),
+ *       });
+ *       const newTokens = await response.json();
+ *       return {
+ *         accessToken: newTokens.accessToken,
+ *         refreshToken: newTokens.refreshToken,
+ *       };
+ *     },
+ *   },
+ *   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);
+ * ```
+ */
+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;
+    /**
+     * 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.
+     *
+     * 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 CoSec interceptors to the provided Fetcher instance.
+     *
+     * This method conditionally configures interceptors based on the provided configuration:
+     *
+     * Always added:
+     * 1. CoSecRequestInterceptor - Adds CoSec headers (appId, deviceId, requestId)
+     * 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;
+}
+//# sourceMappingURL=cosecConfigurer.d.ts.map

package/dist/cosecConfigurer.d.ts.map

@@ -0,0 +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;;;;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/index.d.ts

@@ -1,5 +1,6 @@
 export * from './authorizationRequestInterceptor';
 export * from './authorizationResponseInterceptor';
+export * from './cosecConfigurer';
 export * from './cosecRequestInterceptor';
 export * from './deviceIdStorage';
 export * from './idGenerator';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,yCAAyC,CAAC;AACxD,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,yCAAyC,CAAC;AACxD,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC"}