astro-tokenkit 1.0.6 → 1.0.8

package/README.md

@@ -19,51 +19,47 @@ pnpm add astro-tokenkit
 
 ## Quick Start
 
-### 1. Create your API Client
+### 1. Add the Integration
 
-```typescript
-// src/lib/api.ts
-import { createClient } from 'astro-tokenkit';
-
-export const api = createClient({
-  baseURL: 'https://api.yourserver.com',
-  auth: {
-    login: '/auth/login',
-    refresh: '/auth/refresh',
-    logout: '/auth/logout',
-  }
-});
-```
-
-### 2. Add the Integration
+Configure TokenKit in your `astro.config.mjs`. This sets the global configuration for the entire app.
 
 ```javascript
 // astro.config.mjs
 import { defineConfig } from 'astro/config';
 import { tokenKit } from 'astro-tokenkit';
-import { api } from './src/lib/api';
 
 export default defineConfig({
-  integrations: [tokenKit(api)],
+  integrations: [
+    tokenKit({
+      baseURL: 'https://api.yourserver.com',
+      auth: {
+        login: '/auth/login',
+        refresh: '/auth/refresh',
+      }
+    })
+  ],
 });
 ```
 
-### 3. Setup Middleware
+### 2. Setup Middleware
+
+Create `src/middleware.ts` to automatically handle context binding and token rotation. You can use the exported `api` singleton's middleware:
 
 ```typescript
 // src/middleware.ts
-import { defineMiddleware } from 'astro-tokenkit';
-import { api } from './lib/api';
+import { api } from 'astro-tokenkit';
 
-export const onRequest = defineMiddleware(api);
+export const onRequest = api.middleware();
 ```
 
-### 4. Use in Pages
+### 3. Use in Pages
+
+Now you can use the `api` client anywhere in your Astro pages or components without worrying about passing context.
 
 ```astro
 ---
 // src/pages/profile.astro
-import { api } from '../lib/api';
+import { api } from 'astro-tokenkit';
 
 // No need to pass context, it's handled by middleware!
 const user = await api.get('/me');
@@ -72,6 +68,40 @@ const user = await api.get('/me');
 <h1>Welcome, {user.name}</h1>
 ```
 
+### Global Configuration
+
+TokenKit supports a global configuration via the `tokenKit` integration or `setConfig`. All `ClientConfig` properties can be set globally.
+
+```typescript
+import { setConfig } from 'astro-tokenkit';
+
+setConfig({
+  baseURL: 'https://api.example.com',
+  auth: {
+    login: '/auth/login',
+    refresh: '/auth/refresh',
+  }
+});
+```
+
+### API Singleton
+
+The library exports a global `api` instance that is automatically synchronized with your configuration.
+
+- **Dynamic Sync**: If you update the configuration via `setConfig()`, the `api` instance immediately reflects these changes.
+- **Shared Manager**: The `api` instance uses a global `TokenManager` which ensures that token refreshes are synchronized across all requests (preventing race conditions).
+- **Middleware Integration**: Use `api.middleware()` for a seamless setup in Astro.
+
+If you need a specialized client with a different configuration, you can still create one:
+
+```typescript
+import { createClient } from 'astro-tokenkit';
+
+const specializedClient = createClient({
+  baseURL: 'https://another-api.com'
+});
+```
+
 ## Configuration
 
 ### Client Configuration
@@ -86,6 +116,7 @@ const user = await api.get('/me');
 | `interceptors`| `InterceptorsConfig` | Request/Response/Error interceptors. |
 | `context` | `AsyncLocalStorage` | External AsyncLocalStorage instance. |
 | `getContextStore`| `() => TokenKitContext`| Custom method to retrieve the context store. |
+| `runWithContext`| `Function`| Custom runner to bind context. |
 
 ### Auth Configuration
 
@@ -95,9 +126,19 @@ const user = await api.get('/me');
 | `refresh` | `string` | Endpoint path for token refresh (POST). |
 | `logout` | `string` | Endpoint path for logout (POST). |
 | `fields` | `FieldMapping` | Custom mapping for token fields in API responses. |
+| `parseLogin` | `Function` | Custom parser for login response: `(body: any) => TokenBundle`. |
+| `parseRefresh`| `Function` | Custom parser for refresh response: `(body: any) => TokenBundle`. |
+| `injectToken` | `Function` | Custom token injection: `(token: string) => string` (default: Bearer). |
 | `cookies` | `CookieConfig` | Configuration for auth cookies. |
 | `policy` | `RefreshPolicy` | Strategy for when to trigger token refresh. |
 
+### Login Options
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `ctx` | `TokenKitContext` | Optional Astro context. |
+| `onLogin` | `Function` | Callback after successful login: `(bundle, body, ctx) => void`. |
+
 ## Advanced Usage
 
 ### Manual Context
@@ -128,7 +169,12 @@ const api = createClient({
 
 ```typescript
 // In an API route or server-side component
-await api.login({ username, password });
+await api.login({ username, password }, {
+  onLogin: (bundle, body, ctx) => {
+    // Post-login logic (e.g., sync session to another store)
+    console.log('User logged in!', bundle.sessionPayload);
+  }
+});
 
 await api.logout();
 ```

package/dist/auth/manager.d.ts

@@ -1,4 +1,4 @@
-import type { TokenBundle, Session, AuthConfig, TokenKitContext } from '../types';
+import type { TokenBundle, Session, AuthConfig, TokenKitContext, OnLoginCallback } from '../types';
 /**
  * Token Manager handles all token operations
  */
@@ -10,7 +10,7 @@ export declare class TokenManager {
     /**
      * Perform login
      */
-    login(ctx: TokenKitContext, credentials: any): Promise<TokenBundle>;
+    login(ctx: TokenKitContext, credentials: any, onLogin?: OnLoginCallback): Promise<TokenBundle>;
     /**
      * Perform token refresh
      */

package/dist/auth/manager.js

@@ -52,7 +52,7 @@ export class TokenManager {
     /**
      * Perform login
      */
-    login(ctx, credentials) {
+    login(ctx, credentials, onLogin) {
         return __awaiter(this, void 0, void 0, function* () {
             const url = this.baseURL + this.config.login;
             const response = yield fetch(url, {
@@ -79,8 +79,8 @@ export class TokenManager {
             // Store in cookies
             storeTokens(ctx, bundle, this.config.cookies);
             // Call onLogin callback if provided
-            if (this.config.onLogin) {
-                yield this.config.onLogin(bundle, body, ctx);
+            if (onLogin) {
+                yield onLogin(bundle, body, ctx);
             }
             return bundle;
         });

package/dist/client/client.d.ts

@@ -1,14 +1,27 @@
-import type { ClientConfig, RequestConfig, RequestOptions, Session, TokenKitContext } from '../types';
+import type { ClientConfig, RequestConfig, RequestOptions, Session, TokenKitContext, TokenKitConfig, LoginOptions } from '../types';
 import { TokenManager } from '../auth/manager';
-import { type ContextOptions } from './context';
 /**
  * API Client
  */
 export declare class APIClient {
-    tokenManager?: TokenManager;
-    private config;
-    contextOptions: ContextOptions;
-    constructor(config: ClientConfig);
+    private customConfig?;
+    private _localTokenManager?;
+    private _lastUsedAuth?;
+    private _lastUsedBaseURL?;
+    constructor(config?: Partial<TokenKitConfig>);
+    /**
+     * Get current configuration (merged with global)
+     */
+    get config(): ClientConfig;
+    /**
+     * Get token manager
+     */
+    get tokenManager(): TokenManager | undefined;
+    /**
+     * Get middleware for context binding and automatic token rotation.
+     * This middleware uses the global configuration.
+     */
+    middleware(): import("astro").MiddlewareHandler;
     /**
      * GET request
      */
@@ -52,7 +65,7 @@ export declare class APIClient {
     /**
      * Login
      */
-    login(credentials: any, ctx?: TokenKitContext): Promise<void>;
+    login(credentials: any, options?: LoginOptions | TokenKitContext): Promise<void>;
     /**
      * Logout
      */
@@ -67,6 +80,15 @@ export declare class APIClient {
     getSession(ctx?: TokenKitContext): Session | null;
 }
 /**
- * Create API client
+ * Global API client instance.
+ *
+ * This client is automatically synchronized with the global configuration
+ * set via the Astro integration or setConfig().
+ */
+export declare const api: APIClient;
+/**
+ * Create API client.
+ *
+ * If no configuration is provided, it returns the global `api` singleton.
  */
-export declare function createClient(config: ClientConfig): APIClient;
+export declare function createClient(config?: Partial<TokenKitConfig>): APIClient;

package/dist/client/client.js

@@ -10,22 +10,60 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { APIError, AuthError, NetworkError, TimeoutError } from '../types';
 import { TokenManager } from '../auth/manager';
-import { getContext } from './context';
+import { getContextStore } from './context';
 import { calculateDelay, shouldRetry, sleep } from '../utils/retry';
+import { getConfig, getTokenManager } from '../config';
+import { createMiddleware } from '../middleware';
 /**
  * API Client
  */
 export class APIClient {
     constructor(config) {
-        this.config = config;
-        this.contextOptions = {
-            context: config.context,
-            getContextStore: config.getContextStore,
-        };
-        // Initialize token manager if auth is configured
-        if (config.auth) {
-            this.tokenManager = new TokenManager(config.auth, config.baseURL);
+        this.customConfig = config;
+    }
+    /**
+     * Get current configuration (merged with global)
+     */
+    get config() {
+        // Merge global config with custom config
+        const globalConfig = getConfig();
+        // If no custom config, return global config directly
+        if (!this.customConfig)
+            return globalConfig;
+        // Merge custom config on top of global config
+        return Object.assign(Object.assign({}, globalConfig), this.customConfig);
+    }
+    /**
+     * Get token manager
+     */
+    get tokenManager() {
+        const config = this.config;
+        if (!config.auth)
+            return undefined;
+        const globalConfig = getConfig();
+        const globalManager = getTokenManager();
+        // Reuse global manager if it matches our configuration
+        if (globalManager &&
+            config.auth === globalConfig.auth &&
+            config.baseURL === globalConfig.baseURL) {
+            return globalManager;
+        }
+        // Otherwise create/reuse a local manager for this client
+        if (!this._localTokenManager ||
+            this._lastUsedAuth !== config.auth ||
+            this._lastUsedBaseURL !== config.baseURL) {
+            this._localTokenManager = new TokenManager(config.auth, config.baseURL);
+            this._lastUsedAuth = config.auth;
+            this._lastUsedBaseURL = config.baseURL;
         }
+        return this._localTokenManager;
+    }
+    /**
+     * Get middleware for context binding and automatic token rotation.
+     * This middleware uses the global configuration.
+     */
+    middleware() {
+        return createMiddleware();
     }
     /**
      * GET request
@@ -75,7 +113,7 @@ export class APIClient {
      */
     request(config) {
         return __awaiter(this, void 0, void 0, function* () {
-            const ctx = getContext(config.ctx, this.contextOptions);
+            const ctx = getContextStore(config.ctx);
             let attempt = 0;
             let lastError;
             while (true) {
@@ -245,13 +283,23 @@ export class APIClient {
     /**
      * Login
      */
-    login(credentials, ctx) {
+    login(credentials, options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.tokenManager) {
                 throw new Error('Auth is not configured for this client');
             }
-            const context = getContext(ctx, this.contextOptions);
-            yield this.tokenManager.login(context, credentials);
+            let ctx;
+            let onLogin;
+            if (options && 'cookies' in options) {
+                ctx = options;
+            }
+            else if (options) {
+                const opt = options;
+                ctx = opt.ctx;
+                onLogin = opt.onLogin;
+            }
+            const context = getContextStore(ctx);
+            yield this.tokenManager.login(context, credentials, onLogin);
         });
     }
     /**
@@ -262,7 +310,7 @@ export class APIClient {
             if (!this.tokenManager) {
                 throw new Error('Auth is not configured for this client');
             }
-            const context = getContext(ctx, this.contextOptions);
+            const context = getContextStore(ctx);
             yield this.tokenManager.logout(context);
         });
     }
@@ -272,7 +320,7 @@ export class APIClient {
     isAuthenticated(ctx) {
         if (!this.tokenManager)
             return false;
-        const context = getContext(ctx, this.contextOptions);
+        const context = getContextStore(ctx);
         return this.tokenManager.isAuthenticated(context);
     }
     /**
@@ -281,13 +329,24 @@ export class APIClient {
     getSession(ctx) {
         if (!this.tokenManager)
             return null;
-        const context = getContext(ctx, this.contextOptions);
+        const context = getContextStore(ctx);
         return this.tokenManager.getSession(context);
     }
 }
 /**
- * Create API client
+ * Global API client instance.
+ *
+ * This client is automatically synchronized with the global configuration
+ * set via the Astro integration or setConfig().
+ */
+export const api = new APIClient();
+/**
+ * Create API client.
+ *
+ * If no configuration is provided, it returns the global `api` singleton.
  */
 export function createClient(config) {
+    if (!config)
+        return api;
     return new APIClient(config);
 }

package/dist/client/context-shared.d.ts

@@ -10,8 +10,8 @@ export declare function setSharedContextStorage(storage: AsyncLocalStorage<any>,
 /**
  * Get context from shared storage
  */
-export declare function getContext(explicitCtx?: TokenKitContext): TokenKitContext;
+export declare function getContextStore(explicitCtx?: TokenKitContext): TokenKitContext;
 /**
  * Bind context (only needed if not using shared storage)
  */
-export declare function bindContext<T>(ctx: TokenKitContext, fn: () => T): T;
+export declare function runWithContext<T>(ctx: TokenKitContext, fn: () => T): T;

package/dist/client/context-shared.js

@@ -1,4 +1,5 @@
 // packages/astro-tokenkit/src/client/context-shared.ts
+import { getConfig } from '../config';
 /**
  * OPTION: Share AsyncLocalStorage with other libraries
  *
@@ -32,10 +33,17 @@ export function setSharedContextStorage(storage, key = 'astro') {
 /**
  * Get context from shared storage
  */
-export function getContext(explicitCtx) {
+export function getContextStore(explicitCtx) {
     if (explicitCtx) {
         return explicitCtx;
     }
+    const config = getConfig();
+    const getStore = config.getContextStore;
+    if (getStore) {
+        const ctx = getStore();
+        if (ctx)
+            return ctx;
+    }
     if (sharedStorage && contextKey) {
         const store = sharedStorage.getStore();
         const ctx = store === null || store === void 0 ? void 0 : store[contextKey];
@@ -44,13 +52,19 @@ export function getContext(explicitCtx) {
         }
     }
     throw new Error('Astro context not found. Either:\n' +
-        '1. Pass context explicitly: api.get("/path", { ctx: Astro })\n' +
-        '2. Configure shared storage: setSharedContextStorage(storage, "key")');
+        '1. Use api.middleware() to bind context automatically, or\n' +
+        '2. Pass context explicitly: api.get("/path", { ctx: Astro })\n' +
+        '3. Configure shared storage: setSharedContextStorage(storage, "key")');
 }
 /**
  * Bind context (only needed if not using shared storage)
  */
-export function bindContext(ctx, fn) {
+export function runWithContext(ctx, fn) {
+    const config = getConfig();
+    const runner = config.runWithContext;
+    if (runner) {
+        return runner(ctx, fn);
+    }
     if (sharedStorage && contextKey) {
         const currentStore = sharedStorage.getStore() || {};
         return sharedStorage.run(Object.assign(Object.assign({}, currentStore), { [contextKey]: ctx }), fn);

package/dist/client/context.d.ts

@@ -1,21 +1,13 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import type { TokenKitContext } from '../types';
-/**
- * Configuration for context handling
- */
-export interface ContextOptions {
-    context?: AsyncLocalStorage<any>;
-    getContextStore?: () => TokenKitContext | undefined | null;
-}
 /**
  * Bind Astro context for the current async scope
  */
-export declare function bindContext<T>(ctx: TokenKitContext, fn: () => T, options?: ContextOptions): T;
+export declare function runWithContext<T>(ctx: TokenKitContext, fn: () => T): T;
 /**
  * Get current Astro context (from middleware binding or explicit)
  */
-export declare function getContext(explicitCtx?: TokenKitContext, options?: ContextOptions): TokenKitContext;
+export declare function getContextStore(explicitCtx?: TokenKitContext): TokenKitContext;
 /**
  * Check if context is available
  */
-export declare function hasContext(explicitCtx?: TokenKitContext, options?: ContextOptions): boolean;
+export declare function hasContext(explicitCtx?: TokenKitContext): boolean;

package/dist/client/context.js

@@ -1,23 +1,31 @@
 // packages/astro-tokenkit/src/client/context.ts
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { getConfig } from '../config';
 /**
  * Async local storage for Astro context
  */
-const defaultContextStorage = new AsyncLocalStorage();
+const als = new AsyncLocalStorage();
 /**
  * Bind Astro context for the current async scope
  */
-export function bindContext(ctx, fn, options) {
-    const storage = (options === null || options === void 0 ? void 0 : options.context) || defaultContextStorage;
-    return storage.run(ctx, fn);
+export function runWithContext(ctx, fn) {
+    const config = getConfig();
+    const runner = config.runWithContext;
+    if (runner) {
+        return runner(ctx, fn);
+    }
+    return als.run(ctx, fn);
 }
 /**
  * Get current Astro context (from middleware binding or explicit)
  */
-export function getContext(explicitCtx, options) {
-    const store = (options === null || options === void 0 ? void 0 : options.getContextStore)
-        ? options.getContextStore()
-        : ((options === null || options === void 0 ? void 0 : options.context) || defaultContextStorage).getStore();
+export function getContextStore(explicitCtx) {
+    const config = getConfig();
+    const getStore = config.getContextStore;
+    const context = config.context || als;
+    const store = getStore
+        ? getStore()
+        : context.getStore();
     const ctx = explicitCtx || store;
     if (!ctx) {
         throw new Error('Astro context not found. Either:\n' +
@@ -29,9 +37,12 @@ export function getContext(explicitCtx, options) {
 /**
  * Check if context is available
  */
-export function hasContext(explicitCtx, options) {
-    const store = (options === null || options === void 0 ? void 0 : options.getContextStore)
-        ? options.getContextStore()
-        : ((options === null || options === void 0 ? void 0 : options.context) || defaultContextStorage).getStore();
+export function hasContext(explicitCtx) {
+    const config = getConfig();
+    const getStore = config.getContextStore;
+    const context = config.context || als;
+    const store = getStore
+        ? getStore()
+        : context.getStore();
     return !!(explicitCtx || store);
 }

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+import type { TokenKitConfig } from "./types";
+import { TokenManager } from "./auth/manager";
+/**
+ * Internal config with defaults applied
+ */
+export interface ResolvedConfig extends TokenKitConfig {
+    baseURL: string;
+}
+/**
+ * Set configuration
+ */
+export declare function setConfig(userConfig: TokenKitConfig): void;
+/**
+ * Get current configuration
+ */
+export declare function getConfig(): ResolvedConfig;
+/**
+ * Get global token manager
+ */
+export declare function getTokenManager(): TokenManager | undefined;
+/**
+ * Set global token manager (mainly for testing)
+ */
+export declare function setTokenManager(manager: TokenManager | undefined): void;

package/dist/config.js

@@ -0,0 +1,37 @@
+// packages/astro-tokenkit/src/config.ts
+import { TokenManager } from "./auth/manager";
+let config = {
+    runWithContext: undefined,
+    getContextStore: undefined,
+    baseURL: "",
+};
+let tokenManager;
+/**
+ * Set configuration
+ */
+export function setConfig(userConfig) {
+    // Store validated config
+    config = Object.assign(Object.assign({}, config), userConfig);
+    // Re-initialize global token manager if auth changed
+    if (config.auth) {
+        tokenManager = new TokenManager(config.auth, config.baseURL);
+    }
+}
+/**
+ * Get current configuration
+ */
+export function getConfig() {
+    return config;
+}
+/**
+ * Get global token manager
+ */
+export function getTokenManager() {
+    return tokenManager;
+}
+/**
+ * Set global token manager (mainly for testing)
+ */
+export function setTokenManager(manager) {
+    tokenManager = manager;
+}