@safercity/sdk 0.2.1 → 0.3.1

package/README.md

@@ -2,6 +2,20 @@
 
 Official SaferCity API client for TypeScript/JavaScript.
 
+## What's New in v0.3.1
+
+- **Simplified Return Types** - Domain methods now return the API response body directly instead of wrapping in `ApiResponse<T>`. For example, `client.health.check()` returns `Promise<{ status: string; timestamp: string }>` directly. No more `result.data.data.id` — just `result.data.id`.
+- **Strongly Typed Errors** - All SDK methods throw `SaferCityApiError` on non-2xx responses with typed `status`, `error`, `message`, and `details` fields. Error handling is unchanged from v0.3.0.
+- **Low-Level Access Preserved** - `client._client.get()` and `ServerClient.get()` still return the full `ApiResponse<T>` with `{ data, status, headers }` for cases where you need HTTP metadata.
+
+## What's New in v0.3.0
+
+- **Typed SDK via OpenAPI Codegen** - All request/response types are now auto-generated from the API's OpenAPI spec using `@hey-api/openapi-ts`. This guarantees 1:1 type alignment between the SDK and API — no more manual type mismatches.
+- **Re-exported Generated Types** - All generated API types (request bodies, response shapes, error types) are re-exported from `@safercity/sdk` for direct use in your application.
+- **Correct Field Names** - Request bodies now use the exact API field names (`emailAddress` not `email`, `panicType` not `panicTypeId`, `phoneNumber` not `phone`).
+- **Simplified Return Types** - Domain methods now return the API response body directly instead of wrapping in `ApiResponse<T>`. Access `result.data.id` instead of `result.data.data.id`.
+- **Richer Response Types** - Response types now include the full API response structure (e.g., `{ success: boolean; data: {...}; message?: string }`).
+
 ## 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`.
@@ -86,19 +100,22 @@ const client = createSaferCityClient({
 });
 
 // Health check
-const { data: health } = await client.health.check();
+const health = await client.health.check();
 console.log('API Status:', health.status);
 
 // Get user (auto-resolves userId from client if not passed)
-const { data: user } = await client.users.get();
-console.log('User:', user);
+const user = await client.users.get();
+console.log('User:', user.data.firstName);
 
 // Create panic (userId is optional if set on client)
-const { data: panic } = await client.panics.create({
+const panic = await client.panics.create({
+  userId: 'user-123',
+  panicType: 'emergency',
   latitude: -26.2041,
   longitude: 28.0473,
 });
-console.log('Panic created:', panic.id);
+
+console.log('Panic created:', panic.data.id);
 ```
 
 ## Server Client
@@ -120,13 +137,15 @@ const client = createServerClient({
 
 // All requests are automatically authenticated with OAuth tokens
 // Tokens are refreshed automatically before expiration
-const { data: users } = await client.users.list(); // Admin only
-const { data: panic } = await client.panics.create({
+const users = await client.users.list(); // Admin only
+const panic = await client.panics.create({
   userId: 'user-123',
+  panicType: 'emergency',
   latitude: -26.2041,
   longitude: 28.0473,
 });
 
+
 // ServerClient has ALL endpoints including admin-only ones:
 // - client.oauth.*
 // - client.tenants.*
@@ -257,9 +276,9 @@ for await (const event of client.panics.streamUpdates('panic-123')) {
 - `client.auth.check()` - Check if authenticated (optional auth)
 
 ### Users (User-Scoped)
-- `client.users.create(body)` - Create user
+- `client.users.create(body)` - Create user (`emailAddress`, `firstName`, `lastName`, `phoneNumber?`, `password?`)
 - `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`)
+- `client.users.update(userId?, body)` - Update user (`emailAddress?`, `firstName?`, `lastName?`, `phoneNumber?`, `password?`)
 
 ### Panics
 - `client.panics.create(body)` - Create panic
@@ -270,7 +289,7 @@ for await (const event of client.panics.streamUpdates('panic-123')) {
 - `client.panics.streamUpdates(panicId, options?)` - Stream updates (SSE)
 
 ### Panic Information
-- `client.panicInformation.create(body)` - Create panic profile
+- `client.panicInformation.create(body)` - Create panic profile (`userId`, `phoneNumber`, `firstName`, `lastName`, `idNumber`, `duressCode`, `emergencyContacts?`)
 - `client.panicInformation.get(id)` - Get profile by ID
 - `client.panicInformation.getByUser(userId?)` - Get profile by user ID
 - `client.panicInformation.update(id, body)` - Update profile
@@ -281,7 +300,7 @@ for await (const event of client.panics.streamUpdates('panic-123')) {
 - `client.subscriptions.listTypes()` - List subscription types
 - `client.subscriptions.create(body)` - Create subscription
 - `client.subscriptions.list(query?)` - List subscriptions for a user
-- `client.subscriptions.subscribeUser(body)` - Shorthand to subscribe a user
+- `client.subscriptions.subscribeUser(body)` - Shorthand to subscribe a user (`userId`, `isPremium`, `startDate?`, `endDate?`, `notes?`)
 
 ### Notifications
 - `client.notifications.createSubscriber(body)` - Create subscriber
@@ -331,6 +350,40 @@ const client = createSaferCityClient({
 });
 ```
 
+## Type Generation
+
+The SDK types are auto-generated from the API's OpenAPI specification using `@hey-api/openapi-ts`.
+
+### Regenerating Types
+
+If the API schema changes, regenerate the types:
+
+```bash
+# Start the API server locally first
+bun run dev
+
+# Fetch the latest OpenAPI spec and regenerate types
+bun run -C packages/sdk/client generate:all
+
+# Or step by step:
+bun run -C packages/sdk/client fetch:openapi  # Fetches from http://localhost:3000/openapi
+bun run -C packages/sdk/client generate        # Generates types from openapi.json
+```
+
+### Using Generated Types
+
+All generated types are re-exported from `@safercity/sdk`:
+
+```typescript
+import type {
+  UserCreateBody,
+  PanicCreatedResponse,
+  CreatePanicBody,
+  GetV1UsersByUserIdResponse,
+  PanicInformationResponse,
+} from '@safercity/sdk';
+```
+
 ## Related Packages
 
 - `@safercity/sdk-react` - React hooks with TanStack Query