@safercity/sdk-react 0.0.1 → 0.1.1

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/dist/index.cjs

@@ -6,20 +6,187 @@ var reactQuery = require('@tanstack/react-query');
 var jsxRuntime = require('react/jsx-runtime');
 
 var SaferCityContext = react.createContext(null);
-function SaferCityProvider({
-  children,
-  queryClient: externalQueryClient,
-  ...clientOptions
-}) {
-  const client = react.useMemo(
-    () => sdk.createSaferCityClient(clientOptions),
-    // Only recreate if baseUrl or tenantId changes
-    // Token updates should use client.setToken()
-    [clientOptions.baseUrl, clientOptions.tenantId]
-  );
-  react.useMemo(() => {
-    client.setToken(clientOptions.token);
-  }, [client, clientOptions.token]);
+function isProxyMode(props) {
+  return !("mode" in props) || props.mode === "proxy" || props.mode === void 0;
+}
+function isDirectMode(props) {
+  return "mode" in props && props.mode === "direct";
+}
+function isCookieMode(props) {
+  return "mode" in props && props.mode === "cookie";
+}
+function isLegacyMode(props) {
+  return "baseUrl" in props && "token" in props && !("mode" in props);
+}
+function SaferCityProvider(props) {
+  const { children, queryClient: externalQueryClient } = props;
+  const mode = react.useMemo(() => {
+    if (isDirectMode(props)) return "direct";
+    if (isCookieMode(props)) return "cookie";
+    return "proxy";
+  }, [props]);
+  const [session, setSession] = react.useState({
+    isAuthenticated: false,
+    isLoading: mode === "cookie"
+  });
+  const client = react.useMemo(() => {
+    if (isLegacyMode(props)) {
+      return sdk.createSaferCityClient({
+        baseUrl: props.baseUrl,
+        token: props.token,
+        tenantId: props.tenantId,
+        fetch: props.fetch,
+        timeout: props.timeout,
+        headers: props.headers
+      });
+    }
+    if (isProxyMode(props)) {
+      const proxyBaseUrl = props.proxyBaseUrl ?? "/api/safercity";
+      return sdk.createSaferCityClient({
+        baseUrl: proxyBaseUrl
+      });
+    }
+    if (isDirectMode(props)) {
+      return sdk.createSaferCityClient({
+        baseUrl: props.baseUrl,
+        tenantId: props.tenantId
+      });
+    }
+    if (isCookieMode(props)) {
+      return sdk.createSaferCityClient({
+        baseUrl: props.baseUrl,
+        tenantId: props.tenantId,
+        headers: {
+          // Note: cookies are sent automatically with fetch credentials: 'include'
+        }
+      });
+    }
+    throw new Error("Invalid SaferCityProvider configuration");
+  }, [props]);
+  const directModeTokenGetter = isDirectMode(props) ? props.getAccessToken : null;
+  react.useEffect(() => {
+    if (!directModeTokenGetter) return;
+    let isMounted = true;
+    const updateToken = async () => {
+      const token = await directModeTokenGetter();
+      if (isMounted) {
+        client.setToken(token);
+      }
+    };
+    updateToken();
+    const interval = setInterval(updateToken, 3e4);
+    return () => {
+      isMounted = false;
+      clearInterval(interval);
+    };
+  }, [client, directModeTokenGetter]);
+  react.useEffect(() => {
+    if (mode !== "cookie") return;
+    if (!isCookieMode(props)) return;
+    let isMounted = true;
+    const checkSession = async () => {
+      try {
+        const response = await fetch(`${props.baseUrl}/v1/auth/session/status`, {
+          credentials: "include"
+        });
+        if (!isMounted) return;
+        if (response.ok) {
+          const data = await response.json();
+          setSession({
+            isAuthenticated: data.authenticated,
+            isLoading: false,
+            userId: data.userId,
+            tenantId: data.tenantId,
+            expiresAt: data.expiresAt
+          });
+        } else {
+          setSession({
+            isAuthenticated: false,
+            isLoading: false
+          });
+        }
+      } catch (error) {
+        if (!isMounted) return;
+        setSession({
+          isAuthenticated: false,
+          isLoading: false,
+          error: error instanceof Error ? error : new Error("Session check failed")
+        });
+      }
+    };
+    checkSession();
+    return () => {
+      isMounted = false;
+    };
+  }, [mode, props]);
+  const createSession = react.useCallback(async (token, tenantId) => {
+    if (mode !== "cookie" || !isCookieMode(props)) {
+      throw new Error("createSession is only available in cookie mode");
+    }
+    setSession((prev) => ({ ...prev, isLoading: true, error: void 0 }));
+    try {
+      const response = await fetch(`${props.baseUrl}/v1/auth/session`, {
+        method: "POST",
+        credentials: "include",
+        headers: {
+          "Content-Type": "application/json",
+          ...tenantId && { "X-Tenant-ID": tenantId }
+        },
+        body: JSON.stringify({ token, tenantId })
+      });
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.message || "Failed to create session");
+      }
+      const data = await response.json();
+      setSession({
+        isAuthenticated: true,
+        isLoading: false,
+        expiresAt: data.expiresAt,
+        tenantId
+      });
+    } catch (error) {
+      setSession({
+        isAuthenticated: false,
+        isLoading: false,
+        error: error instanceof Error ? error : new Error("Failed to create session")
+      });
+      throw error;
+    }
+  }, [mode, props]);
+  const clearSession = react.useCallback(async () => {
+    if (mode !== "cookie" || !isCookieMode(props)) {
+      throw new Error("clearSession is only available in cookie mode");
+    }
+    try {
+      await fetch(`${props.baseUrl}/v1/auth/session/logout`, {
+        method: "POST",
+        credentials: "include"
+      });
+    } finally {
+      setSession({
+        isAuthenticated: false,
+        isLoading: false
+      });
+    }
+  }, [mode, props]);
+  const refreshCsrf = react.useCallback(async () => {
+    if (mode !== "cookie" || !isCookieMode(props)) {
+      throw new Error("refreshCsrf is only available in cookie mode");
+    }
+    try {
+      const response = await fetch(`${props.baseUrl}/v1/auth/session/refresh`, {
+        method: "POST",
+        credentials: "include"
+      });
+      if (response.ok) {
+        const data = await response.json();
+        return data.csrfToken;
+      }
+    } catch {
+    }
+    return void 0;
+  }, [mode, props]);
   const queryClient = react.useMemo(
     () => externalQueryClient ?? new reactQuery.QueryClient({
       defaultOptions: {
@@ -38,7 +205,14 @@ function SaferCityProvider({
     }),
     [externalQueryClient]
   );
-  const contextValue = react.useMemo(() => ({ client }), [client]);
+  const contextValue = react.useMemo(() => ({
+    client,
+    mode,
+    session,
+    createSession,
+    clearSession,
+    refreshCsrf
+  }), [client, mode, session, createSession, clearSession, refreshCsrf]);
   return /* @__PURE__ */ jsxRuntime.jsx(reactQuery.QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsxRuntime.jsx(SaferCityContext.Provider, { value: contextValue, children }) });
 }
 function useSaferCity() {
@@ -53,6 +227,23 @@ function useSaferCity() {
 function useSaferCityClient() {
   return useSaferCity().client;
 }
+function useSession() {
+  return useSaferCity().session;
+}
+function useAuthMode() {
+  return useSaferCity().mode;
+}
+function useSessionManager() {
+  const { createSession, clearSession, refreshCsrf, session } = useSaferCity();
+  return {
+    session,
+    createSession,
+    clearSession,
+    refreshCsrf,
+    isAuthenticated: session.isAuthenticated,
+    isLoading: session.isLoading
+  };
+}
 var saferCityKeys = {
   all: ["safercity"],
   // Health
@@ -471,6 +662,7 @@ function useStream(createStream, options = {}) {
 
 exports.SaferCityProvider = SaferCityProvider;
 exports.saferCityKeys = saferCityKeys;
+exports.useAuthMode = useAuthMode;
 exports.useCancelPanic = useCancelPanic;
 exports.useCreatePanic = useCreatePanic;
 exports.useCreateSubscription = useCreateSubscription;
@@ -486,6 +678,8 @@ exports.usePanicStream = usePanicStream;
 exports.usePanics = usePanics;
 exports.useSaferCity = useSaferCity;
 exports.useSaferCityClient = useSaferCityClient;
+exports.useSession = useSession;
+exports.useSessionManager = useSessionManager;
 exports.useStream = useStream;
 exports.useSubscriptionStats = useSubscriptionStats;
 exports.useSubscriptionTypes = useSubscriptionTypes;