@safercity/sdk-react

React hooks and components for SaferCity SDK with TanStack Query integration.

Installation

npm install @safercity/sdk-react @tanstack/react-query
# or
bun add @safercity/sdk-react @tanstack/react-query

Quick Start

1. Wrap Your App with Provider

import { SaferCityProvider } from '@safercity/sdk-react';

function App() {
  return (
    <SaferCityProvider
      baseUrl="https://api.safercity.com"
      token={userToken}
      tenantId="tenant-123"
    >
      <YourApp />
    </SaferCityProvider>
  );
}

2. Use Hooks in Components

import { useUsers, usePanics, useCreatePanic } from '@safercity/sdk-react';

function Dashboard() {
  const { data: users, isLoading } = useUsers();
  const { data: panics } = usePanics({ status: 'active' });
  
  if (isLoading) return <div>Loading...</div>;
  
  return (
    <div>
      <h1>Users: {users?.data.users.length}</h1>
      <h1>Active Panics: {panics?.data.panics.length}</h1>
    </div>
  );
}

function PanicButton({ userId }: { userId: string }) {
  const createPanic = useCreatePanic();
  
  const handlePanic = () => {
    createPanic.mutate({
      userId,
      latitude: -26.2041,
      longitude: 28.0473,
    });
  };
  
  return (
    <button onClick={handlePanic} disabled={createPanic.isPending}>
      {createPanic.isPending ? 'Creating...' : 'Trigger Panic'}
    </button>
  );
}

Streaming Hook

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

• useHealthCheck() - API health status
• useWhoAmI() - Current auth context

Users

• useUsers(filters?) - List users
• useUser(userId) - Get user by ID
• useCreateUser() - Create user mutation
• useUpdateUser() - Update user mutation
• useDeleteUser() - Delete user mutation

Panics

• usePanics(filters?) - List panics
• usePanic(panicId, query?) - Get panic by ID
• useCreatePanic() - Create panic mutation
• useUpdatePanicLocation() - Update location mutation
• useCancelPanic() - Cancel panic mutation
• usePanicStream(panicId, options?) - Stream panic updates

Subscriptions

• useSubscriptionTypes() - List subscription types
• useSubscriptions(filters?) - List subscriptions
• useSubscriptionStats() - Get statistics
• useCreateSubscription() - Create subscription mutation

Location Safety

• useLocationSafety(lat, lng, radius?) - Check location safety

Crimes

• useCrimes(filters?) - List crimes
• useCrimeCategories() - Get crime categories
• useCrimeTypes() - Get crime types

Query Keys

Use query keys for manual cache management:

import { saferCityKeys, useQueryClient } from '@safercity/sdk-react';

function RefreshButton() {
  const queryClient = useQueryClient();
  
  const refresh = () => {
    // Invalidate all user queries
    queryClient.invalidateQueries({ queryKey: saferCityKeys.users() });
    
    // Invalidate specific user
    queryClient.invalidateQueries({ queryKey: saferCityKeys.usersDetail('user-123') });
  };
  
  return <button onClick={refresh}>Refresh</button>;
}

Custom QueryClient

import { SaferCityProvider } from '@safercity/sdk-react';
import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
    },
  },
});

function App() {
  return (
    <SaferCityProvider
      baseUrl="https://api.safercity.com"
      token={token}
      queryClient={queryClient}
    >
      <YourApp />
    </SaferCityProvider>
  );
}

Access Raw Client

import { useSaferCityClient } from '@safercity/sdk-react';

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;
  };
}

License

MIT