astro-tokenkit

v1.0.17

Published

10 days ago

A powerful API client for Astro with automatic token rotation, session management, and seamless context integration.

0High
0Medium
0Low

oamm

astro astro-integration auth token jwt api-client refresh-token middleware

Astro TokenKit

A powerful, type-safe API client for Astro with automatic token rotation, session management, and seamless context integration.

Features

🚀 Built for Astro: Deep integration with Astro's middleware and context.
🔄 Automatic Token Rotation: Handles access and refresh tokens automatically behind the scenes.
🔒 Secure by Default: Uses HttpOnly cookies for token storage.
🧩 Flexible Context: Supports both internal AsyncLocalStorage and external context management.
🛠 Type-Safe: Built with TypeScript for a first-class developer experience.
📡 Powerful Interceptors: Easily add custom logic for requests, responses, and errors.

Installation

pnpm add astro-tokenkit

Quick Start

1. Add the Integration

Configure TokenKit in your astro.config.mjs. This sets the global configuration for the entire app.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { tokenKit } from 'astro-tokenkit';

export default defineConfig({
  integrations: [
    tokenKit({
      baseURL: 'https://api.yourserver.com',
      auth: {
        login: '/auth/login',
        refresh: '/auth/refresh',
      }
    })
  ],
});

2. Setup Middleware

Create src/middleware.ts to automatically handle context binding and token rotation. You can use the exported api singleton's middleware:

// src/middleware.ts
import { api } from 'astro-tokenkit';

export const onRequest = api.middleware();

3. Use in Pages

Now you can use the api client anywhere in your Astro pages or components without worrying about passing context.

---
// src/pages/profile.astro
import { api } from 'astro-tokenkit';

// Request methods return an APIResponse object
const { data: 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.

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:

import { createClient } from 'astro-tokenkit';

const specializedClient = createClient({
  baseURL: 'https://another-api.com'
});

Configuration

Client Configuration

Auth Configuration

Login Options

Request Auth Overrides

When calling api.get(), api.post(), etc., you can override auth configuration (e.g., for multi-tenancy). Headers provided in the request options are automatically propagated to any automatic token refresh operations:

await api.get('/data', {
  headers: { 'x-tenant-name': 'lynx' },
  auth: {
    data: { extra_refresh_param: 'value' }
  }
});

Advanced Usage

Manual Context

If you prefer not to use middleware, you can bind the Astro context manually for a specific scope:

import { runWithContext } from 'astro-tokenkit';

const { data } = await runWithContext(Astro, () => api.get('/data'));

Interceptors

const api = createClient({
  baseURL: '...',
  interceptors: {
    request: [
      (config, ctx) => {
        config.headers = { ...config.headers, 'X-Custom': 'Value' };
        return config;
      }
    ]
  }
});

Login and Logout

// In an API route or server-side component
const { data: bundle } = 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);
  },
  onError: (error, ctx) => {
    // Handle error (e.g., log it or perform cleanup)
    console.error('Login failed:', error.message);
  }
});

await api.logout();

Using Promises (.then, .catch, .finally)

All API methods return a Promise that resolves to an APIResponse object. You can use traditional promise chaining:

// Example with GET request
api.get('/me')
  .then(({ data: user, status }) => {
    console.log(`User ${user.name} fetched with status ${status}`);
  })
  .catch(err => {
    console.error('Failed to fetch user:', err.message);
  })
  .finally(() => {
    console.log('Request finished');
  });

// Example with login
api.login(credentials)
  .then(({ data: token }) => {
    console.log('Successfully logged in!', token.accessToken);
  })
  .catch(err => {
    if (err instanceof AuthError) {
      console.error('Authentication failed:', err.message);
    } else {
      console.error('An unexpected error occurred:', err.message);
    }
  })
  .finally(() => {
    // E.g. stop loading state
  });

Note: Since all methods return an APIResponse object, you can use destructuring in .then() to access the data directly, which allows for clean syntax like .then(({ data: token }) => ... ).