@safercity/sdk 0.1.0 → 0.1.2

package/README.md

@@ -12,6 +12,51 @@ bun add @safercity/sdk
 yarn add @safercity/sdk
 ```
 
+## Authentication Modes
+
+The SDK supports three authentication modes for different deployment scenarios:
+
+### Proxy Mode (Default - Most Secure)
+
+Client -> Your Backend -> SaferCity API. Your backend adds tenant credentials, keeping secrets out of the client.
+
+```typescript
+import { createSaferCityClient } from '@safercity/sdk';
+
+// Client-side: requests go through your proxy
+const client = createSaferCityClient({
+  baseUrl: '/api/safercity',
+});
+```
+
+Set up the proxy on your backend (see [Proxy Middleware](#proxy-middleware) below).
+
+### Direct Mode
+
+Client -> SaferCity API with an external user token. For white-label apps using external auth (Clerk, Auth0, better-auth).
+
+```typescript
+const client = createSaferCityClient({
+  baseUrl: 'https://api.safercity.com',
+  token: externalAuthToken,
+  tenantId: 'your-tenant-id',
+});
+
+// Update token when it changes
+client.setToken(newToken);
+```
+
+### Cookie Mode
+
+Browser with `credentials: include`. For first-party web apps using session cookies.
+
+```typescript
+const client = createSaferCityClient({
+  baseUrl: 'https://api.safercity.com',
+  tenantId: 'your-tenant-id',
+});
+```
+
 ## Quick Start
 
 ```typescript
@@ -40,21 +85,116 @@ const { data: panic } = await client.panics.create({
 console.log('Panic created:', panic.id);
 ```
 
-## Authentication
+## Server Client
 
-### JWT Token
+For backend applications that need automatic OAuth token management:
 
 ```typescript
-const client = createSaferCityClient({
-  baseUrl: 'https://api.safercity.com',
-  token: jwtToken, // Your JWT token
+import { createServerClient } from '@safercity/sdk';
+
+const client = createServerClient({
+  auth: {
+    clientId: process.env.SAFERCITY_CLIENT_ID!,
+    clientSecret: process.env.SAFERCITY_CLIENT_SECRET!,
+    tenantId: 'tenant-123', // optional
+  },
+  baseUrl: 'https://api.safercity.com', // default
+  timeout: 30000,
 });
 
-// Update token later
-client.setToken(newToken);
+// All requests are automatically authenticated with OAuth tokens
+// Tokens are refreshed automatically before expiration
+const users = await client.get('/v1/users');
+
+// Manual token control
+const token = await client.getAccessToken();
+await client.refreshToken();
+client.clearTokens();
 ```
 
-### OAuth Token Flow
+### ServerClientConfig
+
+```typescript
+interface ServerClientConfig {
+  baseUrl?: string;           // default: "https://api.safercity.com"
+  auth: OAuthCredentials;     // { clientId, clientSecret, tenantId? }
+  tokenStore?: TokenStorage;  // custom token storage (default: in-memory)
+  timeout?: number;           // default: 30000
+  fetch?: typeof fetch;       // custom fetch implementation
+}
+```
+
+## Proxy Middleware
+
+Proxy middleware hides your SaferCity credentials from the client. The client sends requests to your backend, which forwards them to SaferCity with proper authentication.
+
+### Next.js App Router
+
+```typescript
+// app/api/safercity/[...path]/route.ts
+import { createNextHandler } from '@safercity/sdk';
+
+const handler = createNextHandler({
+  clientId: process.env.SAFERCITY_CLIENT_ID!,
+  clientSecret: process.env.SAFERCITY_CLIENT_SECRET!,
+  tenantId: 'tenant-123', // optional, can also come from request header
+});
+
+export { handler as GET, handler as POST, handler as PUT, handler as DELETE, handler as PATCH };
+```
+
+### Express
+
+```typescript
+import express from 'express';
+import { createExpressMiddleware } from '@safercity/sdk';
+
+const app = express();
+
+app.use(
+  '/api/safercity',
+  createExpressMiddleware({
+    clientId: process.env.SAFERCITY_CLIENT_ID!,
+    clientSecret: process.env.SAFERCITY_CLIENT_SECRET!,
+  })
+);
+```
+
+### Generic Handler
+
+```typescript
+import { createProxyHandler } from '@safercity/sdk';
+
+const proxy = createProxyHandler({
+  clientId: process.env.SAFERCITY_CLIENT_ID!,
+  clientSecret: process.env.SAFERCITY_CLIENT_SECRET!,
+});
+
+// Use with any framework
+const response = await proxy({
+  method: 'GET',
+  path: '/v1/users',
+  headers: {},
+  query: { limit: '10' },
+});
+```
+
+### ProxyConfig
+
+```typescript
+interface ProxyConfig {
+  clientId: string;
+  clientSecret: string;
+  baseUrl?: string;            // default: "https://api.safercity.com"
+  tenantId?: string;           // optional, can be extracted from request
+  tokenStore?: TokenStorage;   // custom token storage
+  pathPrefix?: string;         // default: "/api/safercity"
+  forwardHeaders?: string[];   // default: ["content-type", "accept", "x-request-id"]
+  fetch?: typeof fetch;
+}
+```
+
+## OAuth Token Flow
 
 ```typescript
 const client = createSaferCityClient({
@@ -88,16 +228,29 @@ for await (const event of client.panics.streamUpdates('panic-123')) {
 
 ### Authentication
 - `client.auth.whoami()` - Get current auth context
+- `client.auth.check()` - Check if authenticated (optional auth)
+
+### OAuth
 - `client.oauth.token(body)` - Get access token
 - `client.oauth.refresh(body)` - Refresh token
 - `client.oauth.introspect(body)` - Introspect token
 - `client.oauth.revoke(body)` - Revoke token
 
+### Tenants
+- `client.tenants.create(body)` - Create a new tenant
+- `client.tenants.list(query?)` - List tenants
+
+### Credentials
+- `client.credentials.setup(body)` - Exchange setup token for credentials
+- `client.credentials.list()` - List credentials
+- `client.credentials.revoke(credentialId)` - Revoke credential
+
 ### Users
 - `client.users.create(body)` - Create user
 - `client.users.list(query?)` - List users
 - `client.users.get(userId)` - Get user by ID
 - `client.users.update(userId, body)` - Update user
+- `client.users.updateStatus(userId, body)` - Update user status
 - `client.users.delete(userId)` - Delete user
 
 ### Panics
@@ -106,7 +259,7 @@ for await (const event of client.panics.streamUpdates('panic-123')) {
 - `client.panics.list(query?)` - List panics
 - `client.panics.updateLocation(panicId, body)` - Update location
 - `client.panics.cancel(panicId, body)` - Cancel panic
-- `client.panics.streamUpdates(panicId)` - Stream updates (SSE)
+- `client.panics.streamUpdates(panicId, options?)` - Stream updates (SSE)
 
 ### Subscriptions
 - `client.subscriptions.listTypes()` - List subscription types
@@ -114,6 +267,12 @@ for await (const event of client.panics.streamUpdates('panic-123')) {
 - `client.subscriptions.list(query?)` - List subscriptions
 - `client.subscriptions.stats()` - Get stats
 
+### Notifications
+- `client.notifications.createSubscriber(body)` - Create subscriber
+- `client.notifications.trigger(body)` - Trigger notification
+- `client.notifications.getPreferences(userId)` - Get user preferences
+- `client.notifications.updatePreferences(userId, body)` - Update preferences
+
 ### Location Safety
 - `client.locationSafety.check(query)` - Check location safety
 

package/package.json

@@ -1,16 +1,11 @@
 {
   "name": "@safercity/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Official SaferCity API client for TypeScript/JavaScript",
   "license": "MIT",
   "author": {
     "name": "SaferCity"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/safercity/safercity-v2.git",
-    "directory": "packages/sdk/client"
-  },
   "keywords": ["safercity", "api", "sdk", "typescript", "client"],
   "sideEffects": false,
   "type": "module",
@@ -42,7 +37,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@safercity/sdk-core": "workspace:*"
+    "@safercity/sdk-core": "^0.1.2"
   },
   "devDependencies": {
     "@hey-api/client-fetch": "^0.6.0",