@ahoo-wang/fetcher-cosec 3.0.2 → 3.0.5

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,70 @@ 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 minimal required configuration
+const configurer = new CoSecConfigurer({
+  appId: 'your-app-id',
+  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
+
+- ✅ **One-line setup**: `configurer.applyTo(fetcher)` configures everything
+- ✅ **Minimal configuration**: Only `appId` and `tokenRefresher` are required
+- ✅ **Sensible defaults**: Automatic error handling and parameter names
+- ✅ **Type-safe**: Full TypeScript support with intelligent defaults
+- ✅ **Backward compatible**: Original manual setup still works
+
 ## 🔧 Configuration
 
 ### CoSecOptions Interface
@@ -163,6 +228,45 @@ 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',
+  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 */
+  },
+  tenantId: 'tenantId', // default: 'tenantId'
+  ownerId: 'ownerId', // default: 'ownerId'
+});
+
+configurer.applyTo(fetcher);
+```
+
+**Automatically Configured Interceptors:**
+
+- `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
+
 #### AuthorizationRequestInterceptor
 
 Automatically adds CoSec authentication headers to outgoing HTTP requests.

package/README.zh-CN.md

@@ -26,6 +26,7 @@
 - **⚡ 性能优化**：最小开销，支持连接池和缓存
 - **🛠️ TypeScript 优先**：完整类型定义，严格类型安全
 - **🔌 可插拔架构**：模块化设计，易于集成和定制
+- **⚙️ 简化配置**：使用 `CoSecConfigurer` 的一行设置，最小化配置开销
 
 ## 🚀 快速开始
 
@@ -112,6 +113,70 @@ 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',
+  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 的优势
+
+- ✅ **一行设置**：`configurer.applyTo(fetcher)` 配置一切
+- ✅ **最小配置**：仅需要 `appId` 和 `tokenRefresher`
+- ✅ **合理的默认值**：自动错误处理和参数名称
+- ✅ **类型安全**：完整的 TypeScript 支持和智能默认值
+- ✅ **向后兼容**：原始手动设置仍然有效
+
 ## 🔧 配置
 
 ### CoSecOptions 接口
@@ -163,6 +228,45 @@ interface JwtTokenManagerCapable {
 
 ### 核心类
 
+#### CoSecConfigurer
+
+配置 CoSec 认证的推荐方式。提供简化的 API，自动创建和配置所有必要的拦截器和依赖项。
+
+```typescript
+const configurer = new CoSecConfigurer({
+  appId: 'your-app-id',
+  tokenRefresher: {
+    refresh: async token => {
+      // 您的令牌刷新实现
+      return {
+        accessToken: 'new-access-token',
+        refreshToken: 'new-refresh-token',
+      };
+    },
+  },
+  // 可选错误处理器（仅在提供时才添加拦截器）
+  onUnauthorized: exchange => {
+    /* 处理 401 */
+  },
+  onForbidden: async exchange => {
+    /* 处理 403 */
+  },
+  tenantId: 'tenantId', // 默认: 'tenantId'
+  ownerId: 'ownerId', // 默认: 'ownerId'
+});
+
+configurer.applyTo(fetcher);
+```
+
+**自动配置的拦截器：**
+
+- `CoSecRequestInterceptor` - 添加 CoSec 头部
+- `AuthorizationRequestInterceptor` - 添加 Bearer 令牌
+- `ResourceAttributionRequestInterceptor` - 添加租户/所有者参数
+- `AuthorizationResponseInterceptor` - 处理令牌刷新
+- `UnauthorizedErrorInterceptor` - 处理 401 错误
+- `ForbiddenErrorInterceptor` - 处理 403 错误
+
 #### AuthorizationRequestInterceptor
 
 自动向传出 HTTP 请求添加 CoSec 认证头部。

package/dist/cosecConfigurer.d.ts

@@ -0,0 +1,88 @@
+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.
+ * Only requires the essential configuration, with sensible defaults for everything else.
+ */
+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;
+    /**
+     * Token refresher implementation for handling expired tokens.
+     * This is required to enable automatic token refresh functionality.
+     */
+    tokenRefresher: TokenRefresher;
+    /**
+     * Callback function invoked when an unauthorized (401) response is detected.
+     * If not provided, defaults to throwing an error.
+     */
+    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 simplified way to configure all 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.
+ *
+ * @example
+ * ```typescript
+ * const configurer = new CoSecConfigurer({
+ *   appId: 'my-app-001',
+ *   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 }),
+ *       });
+ *       const newTokens = await response.json();
+ *       return {
+ *         accessToken: newTokens.accessToken,
+ *         refreshToken: newTokens.refreshToken,
+ *       };
+ *     },
+ *   },
+ * });
+ *
+ * configurer.applyTo(fetcher);
+ * ```
+ */
+export declare class CoSecConfigurer implements FetcherConfigurer {
+    readonly config: CoSecConfig;
+    readonly tokenStorage: TokenStorage;
+    readonly deviceIdStorage: DeviceIdStorage;
+    readonly tokenManager: JwtTokenManager;
+    /**
+     * Creates a new CoSecConfigurer instance with the provided configuration.
+     *
+     * @param config - Simplified CoSec configuration
+     */
+    constructor(config: CoSecConfig);
+    /**
+     * Applies all CoSec interceptors to the provided Fetcher instance.
+     *
+     * This method configures the following interceptors in the correct order:
+     * 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
+     *
+     * @param fetcher - The Fetcher instance to configure
+     */
+    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;;;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"}

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"}