@authaz/next 0.0.1 → 1.0.1

package/CLAUDE.md

@@ -1,118 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is the **Authaz SDK for JavaScript/TypeScript**, providing authentication and user management for the Authaz platform. The SDK supports Universal Login flow with OAuth2/OIDC, PKCE, and secure session management.
-
-## Development Commands
-
-### Building
-```bash
-npm run build              # Build using tsdown (outputs to dist/)
-npm run prepare           # Build script (runs on npm install)
-```
-
-### Testing
-```bash
-npm test                  # Run Jest tests
-npm run test:watch       # Run tests in watch mode
-npm run test:coverage    # Run tests with coverage report (80% threshold)
-```
-
-### Linting
-```bash
-npm run lint             # Check code with ESLint
-npm run lint:fix         # Fix linting issues automatically
-```
-
-### Releasing
-```bash
-npm run release          # Build and create patch release
-npm run release:patch    # Bump patch version and push with tags
-npm run release:minor    # Bump minor version and push with tags
-npm run release:major    # Bump major version and push with tags
-```
-
-## Architecture Overview
-
-### Core Service Structure
-
-The SDK follows a **layered service architecture**:
-
-1. **ApiService** (`src/api.ts`) - Main entry point that orchestrates child services
-   - Initializes configuration via `createConfig()`
-   - Delegates to specialized services: `UserApiService`, `UniversalLoginApiService`
-   - Provides high-level methods: `getMe()`, `getUniversalLoginUrl()`, `getUniversalLoginAccessToken()`
-
-2. **BaseApiService** (`src/shared/base-api.ts`) - Abstract base class for all API services
-   - Manages authentication tokens (API token, CSRF token, Session token)
-   - Initializes on construction: fetches CSRF token → gets API token (client credentials grant)
-   - Updates Axios instances with tokens via `updateAxiosTokens()`
-   - Provides two Axios instances: `apiAxiosInstance` (for API calls) and `universalLoginAxiosInstance` (for OAuth flow)
-
-3. **Specialized Services** (extend BaseApiService)
-   - `UserApiService` (`src/general/user/api.ts`) - User profile operations
-   - `UniversalLoginApiService` (`src/flows/universal-login/api.ts`) - OAuth2/OIDC Universal Login flow
-
-### HTTP Client Layer
-
-**AuthazAxiosInstance** (`src/shared/axios-instance.ts`) - Wraps Axios with automatic token injection
-- Request interceptor adds: `X-Client-Authorization`, `X-CSRF-Token`, `X-Session-Token` headers
-- Tokens are updated via `updateTokens()` method
-- All HTTP methods (get, post, put, delete, patch) return typed responses
-
-### Configuration System
-
-**Config** (`src/config.ts`) - Environment-aware configuration
-- Detects production vs development via `NODE_ENV`
-- Production defaults: `api.authaz.com`, `authaz.com`
-- Development defaults: `localhost:5138`
-- Validates required fields: `clientId`, `clientSecret`, `organizationId`, `redirectUri`, `tenantId`
-
-### Type System
-
-The SDK uses a **dual-type approach**:
-
-1. **Raw HTTP Types** (`src/http-types.ts`) - Direct server responses (e.g., `RawApiTokenResponse`, `RawUserProfileResponse`)
-2. **Processed Types** (`src/types.ts` + flow-specific types) - SDK-transformed responses with status codes
-
-Exported via namespace: `import type * as HttpTypes from "@authaz/sdk"`
-
-### Universal Login Flow
-
-OAuth2/OIDC with PKCE implementation (`src/flows/universal-login/api.ts`):
-1. `redirectToLogin()` - Generates PKCE challenge, state parameter, and authorization URL
-2. `getUniversalLoginAccessToken()` - Exchanges authorization code for access/refresh tokens
-3. Uses Web Crypto API for SHA-256 hashing and secure random generation
-
-## Key Implementation Details
-
-### Token Management
-- All services extend `BaseApiService` which handles 3-token system: API token (client credentials), CSRF token, Session token
-- Tokens are automatically injected into requests via Axios interceptors
-- Base service constructor chains: get CSRF → get API token → update Axios instances
-
-### Build Configuration
-- Uses `tsdown` for bundling (not tsc)
-- Output: ESM format only, with TypeScript declarations
-- External dependencies: Next.js, React, routing libraries (not bundled)
-- Tree-shaking enabled for optimal bundle size
-
-### Testing Setup
-- Jest with ts-jest preset
-- 80% coverage threshold required (branches, functions, lines, statements)
-- Test files: `**/__tests__/**/*.ts` or `**/*.{spec,test}.ts`
-
-### Peer Dependencies
-- Next.js >=13.0.0
-- nookies >=2.5.2 (for cookie management in Next.js)
-
-## Important Notes
-
-- The SDK is designed for Next.js applications (see peer dependencies)
-- Environment detection relies on `process.env.NODE_ENV`
-- All API calls use `withCredentials: true` for cookie handling
-- PKCE implementation uses `S256` method (SHA-256)
-- Session management utilities are exported but implementation is in `src/utils/session.ts`

package/docs/ENVIRONMENT-CONFIG.md

@@ -1,171 +0,0 @@
-# Environment Configuration - Authaz SDK
-
-The SDK now automatically detects the environment (development or production) and applies the appropriate configurations.
-
-## 🔧 How It Works
-
-The `DEFAULT_CONFIG` now reads from environment variables first, with fallback based on `NODE_ENV`:
-
-### 📋 Environment Variables (Priority)
-- `AUTHAZ_API_URL` - API URL
-- `AUTHAZ_DOMAIN` - Authaz Domain
-- `AUTHAZ_UNIVERSAL_LOGIN_URL` - Universal Login URL
-
-### 🏠 Development (Fallback)
-- **When**: `NODE_ENV !== 'production'` and environment variables are not defined
-- **URLs**:
-  - `baseUrl`: `http://localhost:5138/api`
-  - `universalLoginUrl`: `http://localhost:5138`
-  - `authazDomain`: `http://localhost:5138`
-
-### 🚀 Production (Fallback)
-- **When**: `NODE_ENV === 'production'` and environment variables are not defined
-- **URLs**:
-  - `baseUrl`: `https://api.authaz.com`
-  - `universalLoginUrl`: `https://authaz.com`
-  - `authazDomain`: `https://authaz.com`
-
-## 💻 Practical Usage
-
-### Automatic Configuration (Recommended)
-```typescript
-import { ApiService } from 'authaz-sdk-js'
-
-// URLs are automatically detected based on environment
-const authazClient = new ApiService({
-  clientId: 'your-client-id',
-  clientSecret: 'your-client-secret',
-  authPoolId: 'your-auth-pool-id',
-  organizationId: 'your-organization-id',
-  redirectUri: 'your-redirect-uri'
-  // baseUrl, authazDomain and universalLoginUrl are set automatically
-})
-```
-
-### Manual Override (Optional)
-```typescript
-// You can still override URLs if needed
-const authazClient = new ApiService({
-  clientId: 'your-client-id',
-  clientSecret: 'your-client-secret',
-  authPoolId: 'your-auth-pool-id',
-  organizationId: 'your-organization-id',
-  redirectUri: 'your-redirect-uri',
-  baseUrl: 'https://api-custom.authaz.com', // Manual override
-  authazDomain: 'https://custom.authaz.com'
-})
-```
-
-## 🌍 Environment Detection
-
-### Node.js (Backend)
-```javascript
-// Development
-process.env.NODE_ENV = 'development' // or undefined
-
-// Production
-process.env.NODE_ENV = 'production'
-```
-
-### Browser (Frontend)
-```javascript
-// Development
-window.location.hostname = 'localhost' // or '127.0.0.1'
-
-// Production
-window.location.hostname = 'myapp.com' // any domain that is not localhost
-```
-
-## 🔍 Debug
-
-To verify which environment was detected, you can check in the console:
-
-```typescript
-import { DEFAULT_CONFIG } from 'authaz-sdk-js'
-
-console.log('Detected configuration:', DEFAULT_CONFIG)
-// Development: { baseUrl: 'http://localhost:5138/api', ... }
-// Production: { baseUrl: 'https://api.authaz.com', ... }
-```
-
-## 📝 Complete Example
-
-```typescript
-// authaz.config.ts
-import { ApiService } from 'authaz-sdk-js'
-
-export const createAuthazClient = () => {
-  return new ApiService({
-    clientId: process.env.NEXT_PUBLIC_CLIENT_ID!,
-    clientSecret: process.env.CLIENT_SECRET!,
-    authPoolId: process.env.NEXT_PUBLIC_AUTH_POOL_ID!,
-    organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!,
-    redirectUri: process.env.NEXT_PUBLIC_REDIRECT_URI!
-    // URLs are automatically set based on environment
-  })
-}
-
-// In development: will use localhost:5138
-// In production: will use api.authaz.com
-```
-
-## ⚙️ Environment Variables
-
-### Development (.env.local)
-```env
-NODE_ENV=development
-
-# Authaz URLs (optional - uses localhost if not defined)
-AUTHAZ_API_URL=http://localhost:5138/api
-AUTHAZ_DOMAIN=http://localhost:5138
-AUTHAZ_UNIVERSAL_LOGIN_URL=http://localhost:5138
-
-# Credentials
-NEXT_PUBLIC_CLIENT_ID=dev-client-id
-CLIENT_SECRET=dev-client-secret
-NEXT_PUBLIC_AUTH_POOL_ID=dev-auth-pool
-NEXT_PUBLIC_ORGANIZATION_ID=dev-org-id
-NEXT_PUBLIC_REDIRECT_URI=http://localhost:3000/auth/callback
-```
-
-### Production (.env.production)
-```env
-NODE_ENV=production
-
-# Authaz URLs (optional - uses api.authaz.com if not defined)
-AUTHAZ_API_URL=https://api.authaz.com
-AUTHAZ_DOMAIN=https://authaz.com
-AUTHAZ_UNIVERSAL_LOGIN_URL=https://authaz.com
-
-# Credentials
-NEXT_PUBLIC_CLIENT_ID=prod-client-id
-CLIENT_SECRET=prod-client-secret
-NEXT_PUBLIC_AUTH_POOL_ID=prod-auth-pool
-NEXT_PUBLIC_ORGANIZATION_ID=prod-org-id
-NEXT_PUBLIC_REDIRECT_URI=https://myapp.com/auth/callback
-```
-
-### Staging/Custom (.env.staging)
-```env
-NODE_ENV=staging
-
-# Custom URLs
-AUTHAZ_API_URL=https://api-staging.authaz.com
-AUTHAZ_DOMAIN=https://staging.authaz.com
-AUTHAZ_UNIVERSAL_LOGIN_URL=https://staging.authaz.com
-
-# Credentials
-NEXT_PUBLIC_CLIENT_ID=staging-client-id
-CLIENT_SECRET=staging-client-secret
-NEXT_PUBLIC_AUTH_POOL_ID=staging-auth-pool
-NEXT_PUBLIC_ORGANIZATION_ID=staging-org-id
-NEXT_PUBLIC_REDIRECT_URI=https://staging.myapp.com/auth/callback
-```
-
-## ✅ Advantages
-
-1. **Automatic**: No need to manually configure URLs
-2. **Safe**: Prevents using development URLs in production
-3. **Simple**: Just configure credentials, URLs are automatic
-4. **Flexible**: Still allows manual override when needed
-5. **Compatible**: Works in both Node.js and Browser

package/docs/README-AXIOS-INSTANCE.md

@@ -1,276 +0,0 @@
-# Authaz SDK - Axios Instance
-
-## Overview
-
-The SDK now uses a custom Axios instance that automatically adds the necessary authentication tokens (`ApiToken` and `CsrfToken`) to the headers of all requests.
-
-## Architecture
-
-### AuthazAxiosInstance
-
-The `AuthazAxiosInstance` class manages an Axios instance with configured interceptors:
-
-```typescript
-import { AuthazAxiosInstance } from './shared/axios-instance';
-
-// Create an instance with base URL
-const axiosInstance = new AuthazAxiosInstance('https://api.authaz.com');
-
-// Update tokens
-axiosInstance.updateTokens(apiToken, csrfToken);
-
-// Make requests that automatically include tokens
-const data = await axiosInstance.get('/users');
-const response = await axiosInstance.post('/auth/login', { email, password });
-```
-
-### Automatic Interceptors
-
-The Axios instance includes interceptors that:
-
-1. **Request Interceptor**: Automatically adds headers:
-   - `X-Client-Authorization: Bearer {apiToken}`
-   - `X-CSRF-Token: {csrfToken}`
-
-2. **Response Interceptor**: Handles errors consistently
-
-### Integration with BaseApiService
-
-The `BaseApiService` class now includes an instance of `AuthazAxiosInstance`:
-
-```typescript
-export abstract class BaseApiService {
-  protected axiosInstance: AuthazAxiosInstance;
-
-  constructor(...) {
-    this.axiosInstance = new AuthazAxiosInstance(baseUrl);
-    // ...
-  }
-
-  // Method to update tokens in the axios instance
-  protected updateAxiosTokens(): void {
-    this.axiosInstance.updateTokens(this.ApiToken, this.CsrfToken);
-  }
-}
-```
-
-## Benefits
-
-1. **Automation**: No longer necessary to manually add authentication headers
-2. **Consistency**: All services inherit the same authentication configuration
-3. **Maintainability**: Changes to authentication logic are centralized
-4. **Type Safety**: Full TypeScript support with generic types
-
-## Usage in Services
-
-### Before (with fetch)
-
-```typescript
-const response = await fetch(`${this.baseUrl}/auth/login`, {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'X-Client-Authorization': `Bearer ${apiToken}`,
-    'X-CSRF-Token': csrfToken,
-  },
-  body: JSON.stringify({ email, password }),
-});
-```
-
-### After (with axios instance)
-
-```typescript
-const data = await this.axiosInstance.post<LoginResponse>(
-  '/auth/login',
-  { email, password }
-);
-```
-
-## Available Methods
-
-The Axios instance offers convenient methods:
-
-- `get<T>(url, config?)`: GET requests
-- `post<T>(url, data?, config?)`: POST requests
-- `put<T>(url, data?, config?)`: PUT requests
-- `delete<T>(url, config?)`: DELETE requests
-- `patch<T>(url, data?, config?)`: PATCH requests
-
-## Token Updates
-
-Tokens are automatically updated when:
-
-1. CSRF token is obtained via `getCsrfToken()`
-2. API token is obtained via `getApiToken()`
-3. Both are updated in the axios instance via `updateAxiosTokens()`
-
-## Error Handling
-
-The Axios instance includes consistent error handling:
-
-```typescript
-try {
-  const data = await this.axiosInstance.post('/auth/login', credentials);
-  return { status: 'success', data };
-} catch (error) {
-  const axiosError = error as { response?: { status: number; data?: unknown } };
-
-  if (axiosError.response?.status === 401) {
-    return { status: 'error', message: 'Unauthorized' };
-  }
-
-  return { status: 'error', message: 'Internal error' };
-}
-```
-
-## Migration
-
-To migrate existing services:
-
-1. Remove manual `fetch` calls
-2. Replace with calls to `this.axiosInstance`
-3. Remove manual addition of authentication headers
-4. Update error handling to use Axios structure
-
-## Complete Example
-
-```typescript
-export class MyApiService extends BaseApiService {
-  public async getUserData(userId: string): Promise<UserData> {
-    try {
-      // Ensure tokens are up to date
-      await this.getApiToken();
-
-      // Make request - headers are added automatically
-      const data = await this.axiosInstance.get<UserData>(`/users/${userId}`);
-
-      return data;
-    } catch (error: unknown) {
-      const axiosError = error as { response?: { status: number } };
-
-      if (axiosError.response?.status === 404) {
-        throw new Error('User not found');
-      }
-
-      throw new Error('Error fetching user data');
-    }
-  }
-}
-```
-
-# AuthazAxiosInstance - Per-Request Cookies
-
-This document explains how to use request-specific cookies in `AuthazAxiosInstance`.
-
-## Configuration
-
-The `AuthazAxiosInstance` now supports request-specific cookies through the `cookies` property in the configuration.
-
-## Interface
-
-```typescript
-interface AuthazRequestConfig extends AxiosRequestConfig {
-  cookies?: Record<string, string>;
-}
-```
-
-## Usage Examples
-
-### 1. GET Request with cookies
-
-```typescript
-const axiosInstance = new AuthazAxiosInstance('https://api.example.com');
-
-// GET request with specific cookies
-const response = await axiosInstance.get('/users', {
-  cookies: {
-    'sessionId': 'abc123',
-    'userId': 'user456'
-  }
-});
-```
-
-### 2. POST Request with cookies
-
-```typescript
-// POST request with cookies
-const response = await axiosInstance.post('/login', {
-  email: 'user@example.com',
-  password: 'password123'
-}, {
-  cookies: {
-    'sessionId': 'new-session-123',
-    'theme': 'dark'
-  }
-});
-```
-
-### 3. PUT Request with cookies
-
-```typescript
-// PUT request with cookies
-const response = await axiosInstance.put('/users/123', {
-  name: 'John Doe',
-  email: 'john@example.com'
-}, {
-  cookies: {
-    'sessionId': 'abc123',
-    'lastUpdate': Date.now().toString()
-  }
-});
-```
-
-### 4. DELETE Request with cookies
-
-```typescript
-// DELETE request with cookies
-const response = await axiosInstance.delete('/users/123', {
-  cookies: {
-    'sessionId': 'abc123',
-    'action': 'delete'
-  }
-});
-```
-
-### 5. PATCH Request with cookies
-
-```typescript
-// PATCH request with cookies
-const response = await axiosInstance.patch('/users/123', {
-  name: 'Jane Doe'
-}, {
-  cookies: {
-    'sessionId': 'abc123',
-    'updateType': 'name'
-  }
-});
-```
-
-## Advantages
-
-1. **Flexibility**: Each request can have its own cookies
-2. **Isolation**: Cookies from one request don't affect others
-3. **Control**: Allows granular control over cookies per operation
-4. **Security**: Prevents cookie leakage between different contexts
-
-## Global Tokens
-
-API and CSRF tokens continue to be configured globally:
-
-```typescript
-// Configure global tokens
-axiosInstance.updateTokens('api-token-123', 'csrf-token-456');
-
-// Or individually
-axiosInstance.updateApiToken('api-token-123');
-axiosInstance.updateCsrfToken('csrf-token-456');
-```
-
-## Interceptor
-
-The interceptor automatically:
-1. Adds API token if configured
-2. Adds CSRF token if configured
-3. Adds request-specific cookies if configured
-
-All headers are added automatically in each request.