@casfa/client 0.0.1

package/README.md

@@ -0,0 +1,201 @@
+# @casfa/client
+
+CASFA client library with unified authorization strategies.
+
+## Installation
+
+```bash
+bun add @casfa/client
+```
+
+## Overview
+
+A stateful client that manages the three-tier token hierarchy:
+
+1. **User JWT** - OAuth login token, highest authority
+2. **Delegate Token** - Re-delegation token, can issue child tokens
+3. **Access Token** - Data access token, used for CAS operations
+
+## Quick Start
+
+```typescript
+import { createClient } from '@casfa/client';
+
+const client = createClient({
+  baseUrl: 'https://api.casfa.example.com',
+  onAuthRequired: async () => {
+    // Handle authentication (e.g., redirect to login)
+  },
+  onTokenChange: (state) => {
+    // Persist token state
+    localStorage.setItem('casfa-tokens', JSON.stringify(state));
+  },
+});
+
+// Initialize with stored tokens
+const stored = localStorage.getItem('casfa-tokens');
+if (stored) {
+  client.tokens.restore(JSON.parse(stored));
+}
+```
+
+## Features
+
+### OAuth Authentication
+
+```typescript
+// Start OAuth flow
+const { authUrl, state, codeVerifier } = await client.oauth.startAuth({
+  redirectUri: 'https://myapp.com/callback',
+});
+
+// Handle callback
+const tokens = await client.oauth.handleCallback({
+  code: authCode,
+  codeVerifier,
+  redirectUri: 'https://myapp.com/callback',
+});
+```
+
+### Token Management
+
+```typescript
+// Check token status
+const hasValidTokens = client.tokens.hasValidTokens();
+const userToken = client.tokens.getUserToken();
+const delegateToken = client.tokens.getDelegateToken();
+const accessToken = client.tokens.getAccessToken();
+
+// Refresh tokens
+await client.tokens.refresh();
+
+// Clear all tokens (logout)
+client.tokens.clear();
+```
+
+### Depot Operations
+
+```typescript
+// List depots
+const depots = await client.depots.list();
+
+// Create depot
+const depot = await client.depots.create({
+  name: 'my-depot',
+  description: 'My storage depot',
+});
+
+// Get depot info
+const info = await client.depots.get(depotId);
+```
+
+### Ticket Operations
+
+```typescript
+// Create access ticket
+const ticket = await client.tickets.create({
+  depotId: 'depot:...',
+  permissions: ['read', 'write'],
+  expiresIn: 3600,
+});
+
+// List tickets
+const tickets = await client.tickets.list({ depotId: 'depot:...' });
+
+// Revoke ticket
+await client.tickets.revoke(ticketId);
+```
+
+### Node Operations (CAS)
+
+```typescript
+// Read node data
+const data = await client.nodes.get('node:abc123...');
+
+// Put node data
+const key = await client.nodes.put(data);
+
+// Check if node exists
+const exists = await client.nodes.has('node:abc123...');
+
+// Prepare upload (for large files)
+const { uploadUrl } = await client.nodes.prepare({
+  size: fileSize,
+  hash: computedHash,
+});
+```
+
+## Configuration
+
+```typescript
+interface ClientConfig {
+  // Required
+  baseUrl: string;
+  
+  // Callbacks
+  onAuthRequired?: () => void | Promise<void>;
+  onTokenChange?: (state: TokenState) => void;
+  
+  // Optional storage provider (for CAS operations)
+  storage?: StorageProvider;
+  
+  // Timeouts and retries
+  timeout?: number;
+  retries?: number;
+}
+```
+
+## Token Store
+
+The client includes a sophisticated token store that handles:
+
+- Automatic token refresh before expiry
+- Token hierarchy validation
+- Issuer chain tracking
+- Concurrent refresh protection
+
+```typescript
+import {
+  createTokenStore,
+  createRefreshManager,
+  isTokenValid,
+  isTokenExpiringSoon,
+} from '@casfa/client';
+
+// Create standalone token store
+const store = createTokenStore();
+
+// Create refresh manager
+const refreshManager = createRefreshManager(store, {
+  refreshThreshold: 5 * 60 * 1000, // 5 minutes before expiry
+});
+```
+
+## API Module
+
+For advanced usage, access the raw API functions:
+
+```typescript
+import { api } from '@casfa/client';
+
+// Direct API calls
+const result = await api.createTicket(baseUrl, token, params);
+```
+
+## Types
+
+```typescript
+import type {
+  CasfaClient,
+  ClientConfig,
+  ClientError,
+  TokenState,
+  StoredUserToken,
+  StoredDelegateToken,
+  StoredAccessToken,
+} from '@casfa/client';
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,201 @@
+# @casfa/client
+
+CASFA 客户端库，提供统一的授权策略。
+
+## 安装
+
+```bash
+bun add @casfa/client
+```
+
+## 概述
+
+一个有状态的客户端，管理三层令牌体系：
+
+1. **用户 JWT** - OAuth 登录令牌，最高权限
+2. **委托令牌（Delegate Token）** - 可再委托的令牌，能够签发子令牌
+3. **访问令牌（Access Token）** - 数据访问令牌，用于 CAS 操作
+
+## 快速开始
+
+```typescript
+import { createClient } from '@casfa/client';
+
+const client = createClient({
+  baseUrl: 'https://api.casfa.example.com',
+  onAuthRequired: async () => {
+    // 处理认证（例如跳转到登录页面）
+  },
+  onTokenChange: (state) => {
+    // 持久化令牌状态
+    localStorage.setItem('casfa-tokens', JSON.stringify(state));
+  },
+});
+
+// 使用已保存的令牌初始化
+const stored = localStorage.getItem('casfa-tokens');
+if (stored) {
+  client.tokens.restore(JSON.parse(stored));
+}
+```
+
+## 功能特性
+
+### OAuth 认证
+
+```typescript
+// 发起 OAuth 流程
+const { authUrl, state, codeVerifier } = await client.oauth.startAuth({
+  redirectUri: 'https://myapp.com/callback',
+});
+
+// 处理回调
+const tokens = await client.oauth.handleCallback({
+  code: authCode,
+  codeVerifier,
+  redirectUri: 'https://myapp.com/callback',
+});
+```
+
+### 令牌管理
+
+```typescript
+// 检查令牌状态
+const hasValidTokens = client.tokens.hasValidTokens();
+const userToken = client.tokens.getUserToken();
+const delegateToken = client.tokens.getDelegateToken();
+const accessToken = client.tokens.getAccessToken();
+
+// 刷新令牌
+await client.tokens.refresh();
+
+// 清除所有令牌（登出）
+client.tokens.clear();
+```
+
+### Depot 操作
+
+```typescript
+// 列出 depot
+const depots = await client.depots.list();
+
+// 创建 depot
+const depot = await client.depots.create({
+  name: 'my-depot',
+  description: 'My storage depot',
+});
+
+// 获取 depot 信息
+const info = await client.depots.get(depotId);
+```
+
+### Ticket 操作
+
+```typescript
+// 创建访问 ticket
+const ticket = await client.tickets.create({
+  depotId: 'depot:...',
+  permissions: ['read', 'write'],
+  expiresIn: 3600,
+});
+
+// 列出 ticket
+const tickets = await client.tickets.list({ depotId: 'depot:...' });
+
+// 撤销 ticket
+await client.tickets.revoke(ticketId);
+```
+
+### 节点操作（CAS）
+
+```typescript
+// 读取节点数据
+const data = await client.nodes.get('node:abc123...');
+
+// 写入节点数据
+const key = await client.nodes.put(data);
+
+// 检查节点是否存在
+const exists = await client.nodes.has('node:abc123...');
+
+// 准备上传（用于大文件）
+const { uploadUrl } = await client.nodes.prepare({
+  size: fileSize,
+  hash: computedHash,
+});
+```
+
+## 配置
+
+```typescript
+interface ClientConfig {
+  // 必需
+  baseUrl: string;
+  
+  // 回调函数
+  onAuthRequired?: () => void | Promise<void>;
+  onTokenChange?: (state: TokenState) => void;
+  
+  // 可选的存储提供者（用于 CAS 操作）
+  storage?: StorageProvider;
+  
+  // 超时和重试
+  timeout?: number;
+  retries?: number;
+}
+```
+
+## 令牌存储
+
+客户端包含一个完善的令牌存储，支持：
+
+- 过期前自动刷新令牌
+- 令牌层级校验
+- 签发链追踪
+- 并发刷新保护
+
+```typescript
+import {
+  createTokenStore,
+  createRefreshManager,
+  isTokenValid,
+  isTokenExpiringSoon,
+} from '@casfa/client';
+
+// 创建独立的令牌存储
+const store = createTokenStore();
+
+// 创建刷新管理器
+const refreshManager = createRefreshManager(store, {
+  refreshThreshold: 5 * 60 * 1000, // 过期前 5 分钟刷新
+});
+```
+
+## API 模块
+
+如需高级用法，可直接访问底层 API 函数：
+
+```typescript
+import { api } from '@casfa/client';
+
+// 直接调用 API
+const result = await api.createTicket(baseUrl, token, params);
+```
+
+## 类型
+
+```typescript
+import type {
+  CasfaClient,
+  ClientConfig,
+  ClientError,
+  TokenState,
+  StoredUserToken,
+  StoredDelegateToken,
+  StoredAccessToken,
+} from '@casfa/client';
+```
+
+## 许可证
+
+MIT

package/dist/api/index.d.ts

@@ -0,0 +1,3 @@
+export { a as CognitoConfig, C as CommitDepotResponse, D as DelegateTokenParams, L as ListDepotsResponse, b as ListTicketsResponse, c as ListTokensParams, d as ListTokensResponse, N as NodeUploadResult, S as SubmitTicketResponse, T as TokenResponse, U as UserInfo, e as approveAuthRequest, f as commitDepot, g as createAuthRequest, h as createDepot, j as createTicket, k as createToken, l as delegateToken, m as deleteDepot, n as exchangeCode, o as fetchServiceInfo, p as getAuthRequest, q as getDepot, r as getMe, s as getNode, t as getNodeMetadata, u as getOAuthConfig, v as getTicket, w as getToken, x as healthCheck, y as listDepots, z as listTickets, A as listTokens, B as login, E as pollAuthRequest, F as prepareNodes, G as putNode, H as refresh, I as rejectAuthRequest, J as revokeToken, K as submitTicket, M as tokenResponseToStoredUserToken, O as updateDepot } from '../index-cPO-6GxE.js';
+import '@casfa/protocol';
+import '../types/index.js';