Expo / React Native

The Expo SDK (@fivexer/expo) is the worker-facing mobile layer. The base @fivexer/sdk already works in Expo because it is zero-dependency and only needs fetch; this package adds SecureStore session persistence, a live WebSocket queue, React hooks, push notifications, and location updates.

Install

bash
npx expo install @fivexer/expo @fivexer/sdk expo-secure-store expo-notifications expo-location expo-constants react

Scope

This package is worker-portal only. It logs in with a worker id + PIN and uses a scoped wt_... token. Never embed a workspace sk_... API key in a mobile app.

Quickstart

tsx
import { FivexerWorkerProvider, ExpoFivexerWorker, useWorkerSession, useQueue } from '@fivexer/expo';

const worker = new ExpoFivexerWorker({ baseUrl: 'https://api.fivexer.com' });

function App() {
    return (
        <FivexerWorkerProvider worker={worker}>
            <WorkerScreen />
        </FivexerWorkerProvider>
    );
}

function WorkerScreen() {
    const { session, login, logout, loading } = useWorkerSession();
    const { taskIds } = useQueue();

    if (loading) return <Text>Resuming…</Text>;
    if (!session) {
        return <Button title="Log in" onPress={() => login({ workspaceId: 'ws_...', workerId: 'w_...', pin: '1234' })} />;
    }

    return (
        <View>
            <Text>Hello, {session.workerId}</Text>
            <Text>Queue: {taskIds.length} tasks</Text>
            <Button title="Log out" onPress={logout} />
        </View>
    );
}

Hooks

• useWorkerSession() — session, realtime connection status, login, logout, refreshSession.
• useQueue() — live task queue; refreshes automatically on task.matched and other lifecycle events.
• useShift() — the worker's shift state and the switch that changes it. Workers are created off shift, so an app that never calls setAvailable(true) correctly receives no work; surface this control prominently.
• useTaskDetail(taskId) — rich task detail for a task assigned to the worker.
• useBreaks() — today's breaks and completed-task count.
• useTeamPresence() — read-only view of who is working vs on break.
• useMetricsToday() — completed tasks, break time, working time.

Push notifications

tsx
import { registerForPushNotificationsAsync } from '@fivexer/expo';

async function enablePush(worker: ExpoFivexerWorker) {
    const registration = await registerForPushNotificationsAsync(worker);
    if (!registration) return; // permission denied
    // call registration.unregister() on logout
}

The platform sends a push when a task is matched to this worker. Tapping the notification is handled by your app's expo-notifications response listener.

Location updates

tsx
import { startLocationUpdatesAsync } from '@fivexer/expo';

async function enableLocation(worker: ExpoFivexerWorker) {
    const { remove } = await startLocationUpdatesAsync(worker, { intervalMs: 30_000 });
    // call remove() when the shift ends
}

Updates are throttled client-side and the server rate-limits them to avoid churn on the matching data plane.

Realtime connection

The provider opens a WebSocket to /realtime?token=wt_... when the app is in the foreground and a session exists. It reconnects with backoff after network errors and pauses while the app is backgrounded to save battery.

Custom storage

For tests or non-standard environments you can pass a SecureStoreBackend:

ts
const worker = new ExpoFivexerWorker({
    baseUrl: 'https://api.fivexer.com',
    storage: myAsyncKeyValueStore,
});