@safercity/sdk-core 0.1.0 → 0.1.2

package/README.md

@@ -10,15 +10,111 @@ Core utilities for SaferCity SDK including fetch abstraction, streaming support,
 npm install @safercity/sdk-core
 ```
 
+## What's New in v0.1.0
+
+- **Auth Mode Types** - Three authentication modes: proxy, direct, and cookie
+- **Token Manager** - Server-side OAuth token management with automatic refresh and request deduplication
+- **Token Storage** - Pluggable token storage interface with in-memory default
+
 ## Features
 
-- **Type definitions** - Common types for API requests/responses
-- **Authentication utilities** - Token management, JWT parsing
+- **Type definitions** - Common types for API requests/responses and auth mode configuration
+- **Authentication utilities** - Token management, JWT parsing, OAuth token lifecycle
 - **Streaming/SSE support** - Cross-platform Server-Sent Events
 - **Base HTTP client** - Fetch wrapper with timeout and error handling
 
 ## Usage
 
+### Auth Mode Types
+
+The SDK supports three authentication modes for different deployment scenarios:
+
+```typescript
+import type {
+  AuthMode,
+  ProxyModeConfig,
+  DirectModeConfig,
+  CookieModeConfig,
+  ClientModeConfig,
+} from '@safercity/sdk-core';
+```
+
+| Mode | Flow | Best For |
+|------|------|----------|
+| `"proxy"` | Client -> Your Backend -> SaferCity API | Production web apps (most secure) |
+| `"direct"` | Client -> SaferCity API with external token | White-label apps with external auth (Clerk, Auth0, better-auth) |
+| `"cookie"` | Browser with `credentials: include` | First-party web apps using session cookies |
+
+```typescript
+// Proxy mode (default) - backend adds tenant credentials
+const proxyConfig: ProxyModeConfig = {
+  mode: 'proxy',
+  proxyBaseUrl: '/api/safercity', // defaults to "/api/safercity"
+};
+
+// Direct mode - external auth provider supplies the token
+const directConfig: DirectModeConfig = {
+  mode: 'direct',
+  baseUrl: 'https://api.safercity.com',
+  tenantId: 'tenant-123',
+  getAccessToken: () => session?.accessToken,
+};
+
+// Cookie mode - session cookies sent automatically
+const cookieConfig: CookieModeConfig = {
+  mode: 'cookie',
+  baseUrl: 'https://api.safercity.com',
+  tenantId: 'tenant-123', // optional, can come from cookie
+};
+```
+
+### Token Manager
+
+Server-side OAuth token management with automatic refresh and concurrent request deduplication:
+
+```typescript
+import { TokenManager, MemoryTokenStorage } from '@safercity/sdk-core';
+
+const tokenManager = new TokenManager({
+  credentials: {
+    clientId: process.env.SAFERCITY_CLIENT_ID!,
+    clientSecret: process.env.SAFERCITY_CLIENT_SECRET!,
+    tenantId: 'tenant-123', // optional
+  },
+  baseUrl: 'https://api.safercity.com',
+  refreshBuffer: 60000, // refresh 1 minute before expiry (default)
+  storage: new MemoryTokenStorage(), // default, or provide custom
+});
+
+// Get token (auto-refreshes if expired, dedupes concurrent calls)
+const token = await tokenManager.getToken();
+
+// Force refresh (useful for error recovery)
+const freshToken = await tokenManager.forceRefresh();
+
+// Check state
+tokenManager.hasToken(); // boolean
+tokenManager.clear();    // remove stored tokens
+```
+
+### Token Storage
+
+Implement the `TokenStorage` interface for custom persistence:
+
+```typescript
+import type { TokenStorage, AuthTokens } from '@safercity/sdk-core';
+
+// Built-in: MemoryTokenStorage (default, no persistence)
+import { MemoryTokenStorage } from '@safercity/sdk-core';
+
+// Custom implementation
+class MyTokenStorage implements TokenStorage {
+  get(): AuthTokens | null { /* ... */ }
+  set(tokens: AuthTokens): void { /* ... */ }
+  clear(): void { /* ... */ }
+}
+```
+
 ### Stream Adapters
 
 ```typescript
@@ -116,6 +212,27 @@ interface SaferCityConfig {
 }
 ```
 
+### AuthTokens
+
+```typescript
+interface AuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenType: string;
+}
+```
+
+### OAuthCredentials
+
+```typescript
+interface OAuthCredentials {
+  clientId: string;
+  clientSecret: string;
+  tenantId?: string;
+}
+```
+
 ### ServerSentEvent
 
 ```typescript

package/package.json

@@ -1,16 +1,11 @@
 {
   "name": "@safercity/sdk-core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Core utilities for SaferCity SDK - fetch abstraction, streaming, and authentication",
   "license": "MIT",
   "author": {
     "name": "SaferCity"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/safercity/safercity-v2.git",
-    "directory": "packages/sdk/core"
-  },
   "keywords": ["safercity", "sdk", "core", "streaming", "sse"],
   "sideEffects": false,
   "type": "module",