Auth hooks and rate limits

The auth module exports hooks and small helpers for custom authentication screens. They use the active @ovok/core client and must run below OvokProvider.

useSession

import { useSession } from "@ovok/native";

const {
  status,
  isAuthenticated,
  profile,
  sessions,
  loading,
  error,
  refresh,
  refreshSessions,
  logout,
  revokeSessions,
} = useSession({
  sessions: true,
  refreshOnForeground: true,
});

Options

Option	Type	Default	Description
sessions	boolean	true	Fetch server-side sessions during refresh
refreshOnForeground	boolean	true	Refresh when the app becomes active

Result

Field	Description
status	loading, authenticated, or signed-out
isAuthenticated	true only when status is authenticated
profile	The active profile while authenticated; otherwise undefined
sessions	Normalized server sessions, or an empty array when disabled/signed out
loading	Whether the initial or current refresh is loading
error	The last refresh error, when one occurred
refresh()	Refresh profile and, when enabled, sessions
refreshSessions()	Refresh sessions without replacing profile state
logout()	Calls the core client's logout and publishes a session-change event
revokeSessions(option)	Revokes current, other, all, or a backend-defined option, then refreshes

useSession refreshes after another mounted auth flow publishes a session change. Mounted useSession hooks share the same client-keyed profile/session store, so mounting multiple consumers does not start duplicate initial profile requests. It does not store credentials or decide whether an authenticated user can access an application route.

Headless authentication actions

Use these hooks when building a custom auth screen instead of the SDK's form UI. Each exposes status, loading, error, reset(), and an async run() action. Successful actions update the shared session store.

import { useSignIn, useSignOut } from "@ovok/native";

function CustomSignIn() {
  const signIn = useSignIn({ type: "Patient", tenantCode: "clinic" });
  const signOut = useSignOut();

  return (
    <Button
      title={signIn.loading ? "Signing in…" : "Sign in"}
      onPress={() => signIn.run({ email, password })}
    />
  );
}

• useSignIn({ type: "Patient", tenantCode }) or useSignIn({ type: "Practitioner", tenantCode? }) performs password sign-in and returns an MFA verification action when required.
• useSocialSignIn({ provider: "google", internalId, googleIosClientId, googleWebClientId }) or { provider: "apple", internalId } handles the platform sign-in flow and saves the resulting session.
• useSignOut() clears the SDK session and also signs out of Google when that provider is configured.
• useDeleteAccount({ days?, wipe? }) requests account deletion and then clears the active SDK and Google sessions.

The hooks expose loading and error state but do not render UI or navigate. Handle errors and the post-auth destination in the host application.

useRateLimitCooldown

const remainingMs = useRateLimitCooldown(rateLimitUntil);

Pass the absolute millisecond timestamp from Formik status. The hook returns the remaining milliseconds, updates once per second while active, and returns 0 when the timestamp is missing or expired.

Rate-limit helpers

import {
  DEFAULT_RATE_LIMIT_RETRY_MS,
  getRateLimitDetails,
  setRateLimitFormError,
} from "@ovok/native";

getRateLimitDetails(error) recognizes the SDK's code: "rate_limit" shape and HTTP 429 responses, including error.response.status. It returns { messageKey: "auth.rate-limit", retryAfterMs }, using DEFAULT_RATE_LIMIT_RETRY_MS (60_000) when the error does not provide a positive retryAfterMs. It returns undefined for unrelated errors.

setRateLimitFormError(error, formikHelpers) applies the returned cooldown as status.rateLimitUntil, sets the Formik submit field error to the translation key, and returns the details. It also returns undefined for unrelated errors.