authfort-client 0.0.1

package/CLAUDE.md

@@ -0,0 +1,45 @@
+# AuthFort Client — AI Reference
+
+## Commands (User Runs These)
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+```
+
+## Structure
+
+```
+client/
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── index.ts              # Public API exports
+    ├── types.ts              # TypeScript interfaces
+    ├── client.ts             # createAuthClient factory
+    ├── token-manager.ts      # Token lifecycle (refresh, dedup)
+    ├── react/index.ts        # React hooks (useAuth)
+    ├── vue/index.ts          # Vue composables
+    └── svelte/index.ts       # Svelte stores
+```
+
+## Purpose
+
+TypeScript SDK for frontend apps. Handles:
+- Token storage and retrieval
+- Proactive refresh (30s before expiry)
+- Refresh promise deduplication (concurrent calls share one refresh)
+- 401 retry (for immediate role invalidation)
+- Auth state management (authenticated/unauthenticated/loading)
+
+## Constraints
+
+- **No server-side code** — this is a client-side SDK
+- **Framework-agnostic core** — React/Vue/Svelte are optional exports
+- **Never store tokens insecurely** — httponly cookies for web, secure storage guidance for mobile

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "authfort-client",
+  "version": "0.0.1",
+  "description": "TypeScript client SDK for AuthFort authentication",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
+    },
+    "./vue": {
+      "import": "./dist/vue/index.js",
+      "types": "./dist/vue/index.d.ts"
+    },
+    "./svelte": {
+      "import": "./dist/svelte/index.js",
+      "types": "./dist/svelte/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/client.ts

@@ -0,0 +1,10 @@
+/**
+ * AuthFort client factory — creates an auth client instance.
+ */
+
+import type { AuthClientConfig, AuthClient } from './types';
+
+export function createAuthClient(_config: AuthClientConfig): AuthClient {
+  // TODO: Implement in Phase 4
+  throw new Error('Not yet implemented');
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * AuthFort Client — TypeScript SDK for AuthFort authentication.
+ *
+ * Handles token lifecycle, proactive refresh, and authenticated requests.
+ */
+
+export { createAuthClient } from './client';
+export type { AuthClientConfig, AuthClient, AuthState, AuthUser } from './types';

package/src/react/index.ts

@@ -0,0 +1,5 @@
+/**
+ * React hooks for AuthFort.
+ *
+ * Provides useAuth() and useSession() hooks.
+ */

package/src/svelte/index.ts

@@ -0,0 +1,3 @@
+/**
+ * Svelte stores for AuthFort.
+ */

package/src/token-manager.ts

@@ -0,0 +1,8 @@
+/**
+ * Token lifecycle manager.
+ *
+ * Handles:
+ * - Proactive refresh (before expiry)
+ * - Single refresh promise deduplication
+ * - Token storage
+ */

package/src/types.ts

@@ -0,0 +1,51 @@
+/** Configuration for creating an AuthFort client. */
+export interface AuthClientConfig {
+  /** Base URL of the auth server (e.g., "https://myapp.com/auth") */
+  baseUrl: string;
+
+  /** Token delivery mode */
+  tokenMode?: 'cookie' | 'bearer' | 'both';
+
+  /** Seconds before expiry to trigger proactive refresh (default: 30) */
+  refreshBuffer?: number;
+}
+
+/** Authentication state */
+export type AuthState = 'authenticated' | 'unauthenticated' | 'loading';
+
+/** Authenticated user data */
+export interface AuthUser {
+  id: string;
+  email: string;
+  name?: string;
+  roles: string[];
+  emailVerified: boolean;
+  avatarUrl?: string;
+}
+
+/** Auth client interface */
+export interface AuthClient {
+  /** Get a valid access token (refreshes if needed) */
+  getToken(): Promise<string>;
+
+  /** Make an authenticated fetch request (auto-attaches token, handles 401 retry) */
+  fetch(url: string, options?: RequestInit): Promise<Response>;
+
+  /** Get current user data */
+  getUser(): Promise<AuthUser>;
+
+  /** Sign up with email and password */
+  signUp(data: { email: string; password: string; name?: string }): Promise<AuthUser>;
+
+  /** Sign in with email and password */
+  signIn(data: { email: string; password: string }): Promise<AuthUser>;
+
+  /** Sign in with OAuth provider (redirects) */
+  signInWithProvider(provider: string): void;
+
+  /** Sign out */
+  signOut(): Promise<void>;
+
+  /** Subscribe to auth state changes */
+  onAuthStateChange(callback: (state: AuthState) => void): () => void;
+}

package/src/vue/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Vue composables for AuthFort.
+ *
+ * Provides useAuth() and useSession() composables.
+ */

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}