@safercity/sdk-react 0.1.0 → 0.1.2

package/README.md

@@ -10,9 +10,31 @@ npm install @safercity/sdk-react @tanstack/react-query
 bun add @safercity/sdk-react @tanstack/react-query
 ```
 
-## Quick Start
+## Authentication Modes
 
-### 1. Wrap Your App with Provider
+The provider supports three authentication modes. Choose the one that fits your architecture:
+
+### Proxy Mode (Default - Most Secure)
+
+Client -> Your Backend -> SaferCity API. Your backend handles credentials.
+
+```tsx
+import { SaferCityProvider } from '@safercity/sdk-react';
+
+function App() {
+  return (
+    <SaferCityProvider mode="proxy" proxyBaseUrl="/api/safercity">
+      <YourApp />
+    </SaferCityProvider>
+  );
+}
+```
+
+Set up the proxy on your backend with `createNextHandler` or `createExpressMiddleware` from `@safercity/sdk`.
+
+### Direct Mode
+
+Client -> SaferCity API with an external auth token. For white-label apps using Clerk, Auth0, better-auth, etc.
 
 ```tsx
 import { SaferCityProvider } from '@safercity/sdk-react';
@@ -20,9 +42,10 @@ import { SaferCityProvider } from '@safercity/sdk-react';
 function App() {
   return (
     <SaferCityProvider
+      mode="direct"
       baseUrl="https://api.safercity.com"
-      token={userToken}
       tenantId="tenant-123"
+      getAccessToken={() => session?.accessToken}
     >
       <YourApp />
     </SaferCityProvider>
@@ -30,7 +53,84 @@ function App() {
 }
 ```
 
-### 2. Use Hooks in Components
+The provider automatically refreshes the token every 30 seconds by calling `getAccessToken`.
+
+### Cookie Mode
+
+Browser with `credentials: include`. For first-party web apps using session cookies.
+
+```tsx
+import { SaferCityProvider } from '@safercity/sdk-react';
+
+function App() {
+  return (
+    <SaferCityProvider mode="cookie" baseUrl="https://api.safercity.com">
+      <YourApp />
+    </SaferCityProvider>
+  );
+}
+```
+
+The provider automatically checks session status on mount via `/v1/auth/session/status`.
+
+### Legacy Mode
+
+For backward compatibility, you can still pass `baseUrl` and `token` directly without a `mode`:
+
+```tsx
+<SaferCityProvider baseUrl="https://api.safercity.com" token={userToken} tenantId="tenant-123">
+  <YourApp />
+</SaferCityProvider>
+```
+
+## Session Management (Cookie Mode)
+
+When using cookie mode, the provider exposes session management hooks:
+
+```tsx
+import { useSession, useSessionManager, useAuthMode } from '@safercity/sdk-react';
+
+function AuthStatus() {
+  const session = useSession();
+  const mode = useAuthMode(); // "proxy" | "direct" | "cookie"
+
+  if (session.isLoading) return <div>Loading...</div>;
+  if (session.error) return <div>Error: {session.error.message}</div>;
+
+  return <div>Authenticated: {session.isAuthenticated ? 'Yes' : 'No'}</div>;
+}
+
+function LoginButton() {
+  const { createSession, clearSession, refreshCsrf, isAuthenticated } = useSessionManager();
+
+  const handleLogin = async (externalToken: string) => {
+    await createSession(externalToken, 'tenant-123');
+  };
+
+  const handleLogout = async () => {
+    await clearSession();
+  };
+
+  return isAuthenticated
+    ? <button onClick={handleLogout}>Logout</button>
+    : <button onClick={() => handleLogin('...')}>Login</button>;
+}
+```
+
+### SessionState
+
+```typescript
+interface SessionState {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  userId?: string;
+  tenantId?: string;
+  expiresAt?: number;
+  error?: Error;
+}
+```
+
+## Using Hooks
 
 ```tsx
 import { useUsers, usePanics, useCreatePanic } from '@safercity/sdk-react';
@@ -68,32 +168,16 @@ function PanicButton({ userId }: { userId: string }) {
 }
 ```
 
-## Streaming Hook
-
-```tsx
-import { usePanicStream } from '@safercity/sdk-react';
-
-function PanicTracker({ panicId }: { panicId: string }) {
-  const { data, isConnected, error, events } = usePanicStream(panicId, {
-    keepHistory: true,
-    onEvent: (event) => console.log('Update:', event),
-  });
-  
-  if (error) return <div>Error: {error.message}</div>;
-  if (!isConnected) return <div>Connecting...</div>;
-  
-  return (
-    <div>
-      <p>Latest: {data?.data}</p>
-      <p>Total events: {events.length}</p>
-    </div>
-  );
-}
-```
-
 ## Available Hooks
 
-### Health & Auth
+### Provider Hooks
+- `useSaferCity()` - Full context (client, mode, session, session management)
+- `useSaferCityClient()` - SaferCity client instance
+- `useSession()` - Session state (cookie mode)
+- `useAuthMode()` - Current auth mode (`"proxy"` | `"direct"` | `"cookie"`)
+- `useSessionManager()` - Session management functions (cookie mode)
+
+### Health and Auth
 - `useHealthCheck()` - API health status
 - `useWhoAmI()` - Current auth context
 
@@ -126,12 +210,36 @@ function PanicTracker({ panicId }: { panicId: string }) {
 - `useCrimeCategories()` - Get crime categories
 - `useCrimeTypes()` - Get crime types
 
+## Streaming Hook
+
+```tsx
+import { usePanicStream } from '@safercity/sdk-react';
+
+function PanicTracker({ panicId }: { panicId: string }) {
+  const { data, isConnected, error, events } = usePanicStream(panicId, {
+    keepHistory: true,
+    onEvent: (event) => console.log('Update:', event),
+  });
+  
+  if (error) return <div>Error: {error.message}</div>;
+  if (!isConnected) return <div>Connecting...</div>;
+  
+  return (
+    <div>
+      <p>Latest: {data?.data}</p>
+      <p>Total events: {events.length}</p>
+    </div>
+  );
+}
+```
+
 ## Query Keys
 
 Use query keys for manual cache management:
 
 ```tsx
-import { saferCityKeys, useQueryClient } from '@safercity/sdk-react';
+import { saferCityKeys } from '@safercity/sdk-react';
+import { useQueryClient } from '@tanstack/react-query';
 
 function RefreshButton() {
   const queryClient = useQueryClient();
@@ -164,11 +272,7 @@ const queryClient = new QueryClient({
 
 function App() {
   return (
-    <SaferCityProvider
-      baseUrl="https://api.safercity.com"
-      token={token}
-      queryClient={queryClient}
-    >
+    <SaferCityProvider mode="proxy" proxyBaseUrl="/api/safercity" queryClient={queryClient}>
       <YourApp />
     </SaferCityProvider>
   );
@@ -184,7 +288,6 @@ function CustomComponent() {
   const client = useSaferCityClient();
   
   const customRequest = async () => {
-    // Use raw client for custom requests
     const response = await client._client.get('/custom-endpoint');
     return response.data;
   };

package/package.json

@@ -1,16 +1,11 @@
 {
   "name": "@safercity/sdk-react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React hooks and components for SaferCity SDK with TanStack Query integration",
   "license": "MIT",
   "author": {
     "name": "SaferCity"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/safercity/safercity-v2.git",
-    "directory": "packages/sdk/react"
-  },
   "keywords": ["safercity", "sdk", "react", "hooks", "tanstack-query"],
   "sideEffects": false,
   "type": "module",
@@ -41,8 +36,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@safercity/sdk": "workspace:*",
-    "@safercity/sdk-core": "workspace:*"
+    "@safercity/sdk": "^0.1.2",
+    "@safercity/sdk-core": "^0.1.2"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",