@safercity/sdk 0.1.2 → 0.2.0

package/README.md

@@ -2,6 +2,20 @@
 
 Official SaferCity API client for TypeScript/JavaScript.
 
+## What's New in v0.2.0
+
+- **User-Scoped Client** - The main client is now user-scoped (Stripe publishable key pattern). Admin operations moved to `ServerClient`.
+- **Panic Information** - Full CRUD for user panic profiles and emergency contacts.
+- **Proxy Enhancements** - Added allowlist/blocklist support for proxy endpoints.
+- **Automatic Scoping** - Client now tracks `userId` and automatically scopes requests.
+- **Path Alignment** - All SDK paths now match the latest API schema (singular `/v1/panic`, etc.).
+
+## What's New in v0.1.3
+
+- **OAuth endpoint path fix** - Fixed paths (`/oauth/*` → `/v1/oauth/*`)
+- **ServerClient domain helpers** - Added typed domain helpers to `ServerClient`
+- **Security hardening** - Removed `panics.list()` and `subscriptions.stats()` from client-side SDK (available on `ServerClient` only)
+
 ## Installation
 
 ```bash
@@ -40,10 +54,12 @@ const client = createSaferCityClient({
   baseUrl: 'https://api.safercity.com',
   token: externalAuthToken,
   tenantId: 'your-tenant-id',
+  userId: 'user-123', // optional, for auto-scoping
 });
 
-// Update token when it changes
+// Update token or user when they change
 client.setToken(newToken);
+client.setUserId(newUserId);
 ```
 
 ### Cookie Mode
@@ -54,6 +70,7 @@ Browser with `credentials: include`. For first-party web apps using session cook
 const client = createSaferCityClient({
   baseUrl: 'https://api.safercity.com',
   tenantId: 'your-tenant-id',
+  userId: 'user-123', // optional
 });
 ```
 
@@ -72,13 +89,12 @@ const client = createSaferCityClient({
 const { data: health } = await client.health.check();
 console.log('API Status:', health.status);
 
-// Get user
-const { data: user } = await client.users.get('user-123');
+// Get user (auto-resolves userId from client if not passed)
+const { data: user } = await client.users.get();
 console.log('User:', user);
 
-// Create panic
+// Create panic (userId is optional if set on client)
 const { data: panic } = await client.panics.create({
-  userId: 'user-123',
   latitude: -26.2041,
   longitude: 28.0473,
 });
@@ -104,7 +120,26 @@ const client = createServerClient({
 
 // All requests are automatically authenticated with OAuth tokens
 // Tokens are refreshed automatically before expiration
-const users = await client.get('/v1/users');
+const { data: users } = await client.users.list(); // Admin only
+const { data: panic } = await client.panics.create({
+  userId: 'user-123',
+  latitude: -26.2041,
+  longitude: 28.0473,
+});
+
+// ServerClient has ALL endpoints including admin-only ones:
+// - client.oauth.*
+// - client.tenants.*
+// - client.credentials.*
+// - client.users.list()
+// - client.users.delete()
+// - client.users.updateStatus()
+// - client.panics.list()
+// - client.subscriptions.stats()
+// - client.panicInformation.list()
+
+// Low-level requests still work too
+const response = await client.get('/v1/custom-endpoint');
 
 // Manual token control
 const token = await client.getAccessToken();
@@ -112,6 +147,8 @@ await client.refreshToken();
 client.clearTokens();
 ```
 
+> **Note**: The `ServerClient` includes `panics.list()` and `subscriptions.stats()` which are not available on the client-side SDK for security reasons.
+
 ### ServerClientConfig
 
 ```typescript
@@ -191,26 +228,15 @@ interface ProxyConfig {
   pathPrefix?: string;         // default: "/api/safercity"
   forwardHeaders?: string[];   // default: ["content-type", "accept", "x-request-id"]
   fetch?: typeof fetch;
+  allowedEndpoints?: EndpointPattern[]; // Explicit allowlist
+  blockedEndpoints?: EndpointPattern[]; // Explicit blocklist
 }
-```
-
-## OAuth Token Flow
 
-```typescript
-const client = createSaferCityClient({
-  baseUrl: 'https://api.safercity.com',
-});
-
-// Get access token
-const { data: tokens } = await client.oauth.token({
-  grant_type: 'client_credentials',
-  tenantId: 'your-tenant-id',
-});
-
-// Set token on client
-client.setToken(tokens.access_token);
+type EndpointPattern = string | { method?: string; path: string };
 ```
 
+Allowlist takes precedence over blocklist. Patterns match by path prefix (case-insensitive).
+
 ## Streaming (SSE)
 
 Stream real-time panic updates:
@@ -230,56 +256,51 @@ for await (const event of client.panics.streamUpdates('panic-123')) {
 - `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
+### Users (User-Scoped)
 - `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
+- `client.users.get(userId?)` - Get user by ID (defaults to client's `userId`)
+- `client.users.update(userId?, body)` - Update user (defaults to client's `userId`)
 
 ### Panics
 - `client.panics.create(body)` - Create panic
 - `client.panics.get(panicId, query?)` - Get panic
-- `client.panics.list(query?)` - List panics
 - `client.panics.updateLocation(panicId, body)` - Update location
 - `client.panics.cancel(panicId, body)` - Cancel panic
+- `client.panics.types(userId?)` - Get available panic types for a user
 - `client.panics.streamUpdates(panicId, options?)` - Stream updates (SSE)
 
+### Panic Information
+- `client.panicInformation.create(body)` - Create panic profile
+- `client.panicInformation.get(id)` - Get profile by ID
+- `client.panicInformation.getByUser(userId?)` - Get profile by user ID
+- `client.panicInformation.update(id, body)` - Update profile
+- `client.panicInformation.delete(id)` - Delete profile
+- `client.panicInformation.validateEligibility(userId?)` - Check if user is eligible for panic services
+
 ### Subscriptions
 - `client.subscriptions.listTypes()` - List subscription types
 - `client.subscriptions.create(body)` - Create subscription
-- `client.subscriptions.list(query?)` - List subscriptions
-- `client.subscriptions.stats()` - Get stats
+- `client.subscriptions.list(query?)` - List subscriptions for a user
+- `client.subscriptions.subscribeUser(body)` - Shorthand to subscribe a user
 
 ### 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
+- `client.notifications.bulkTrigger(body)` - Bulk trigger notifications
+- `client.notifications.getPreferences(userId?)` - Get user preferences
+- `client.notifications.updatePreferences(userId?, body)` - Update preferences
 
 ### Location Safety
-- `client.locationSafety.check(query)` - Check location safety
+- `client.locationSafety.check(body)` - Check location safety (POST)
+
+### Banner
+- `client.banner.get(body)` - Get crime banner data for a location
 
 ### Crimes
 - `client.crimes.list(query?)` - List crimes
 - `client.crimes.categories()` - Get crime categories
 - `client.crimes.types()` - Get crime types
+- `client.crimes.categoriesWithTypes()` - Get categories with nested types
 
 ## Error Handling