SDK Reference

Generated from src/index.ts.

Contents

• Factory (1)
• API Client (3)
• Auth (52)
• Community (41)
• Webhooks (9)
• Push Notifications (4)
• Realtime (8)
• Core Types (12)

All exports (alphabetical)

Export	Kind	Source	Description
ApiError	class	src/api/error.ts	HTTP error thrown by Snapshot API clients for non-success responses.
AssetRef	interface	src/community/types.ts	Reference to an uploaded asset (image, audio, video, file).
AUTH_QUERY_KEY	variable	src/routing/loaders.ts	Stable query key under which useUser() and the route guards cache the authenticated user. Exported so apps can invalidate, seed, or read the cache directly (e.g. after a profile update or server-side state change that should force a refresh).
AuthContract	interface	src/auth/contract.ts	Full auth contract used by createSnapshot() to build auth URLs and requests.
AuthContractConfig	interface	src/auth/contract.ts	Partial auth contract overrides.
AuthEndpoints	interface	src/auth/contract.ts	Relative auth endpoint paths used by Snapshot’s built-in auth hooks.
AuthErrorConfig	interface	src/types.ts	Optional configuration for auth error formatting.
AuthErrorContext	typealias	src/types.ts	Auth UI contexts that can provide custom error messaging.
AuthHeaders	interface	src/auth/contract.ts	Header names Snapshot sends for session and CSRF-aware auth requests.
AuthUser	interface	src/types.ts	Minimal authenticated user shape returned by Snapshot auth hooks.
BanBody	interface	src/community/types.ts	Request body for creating a user ban.
BanCheckResponse	interface	src/community/types.ts	Result returned when checking whether a user is banned.
BanResponse	interface	src/community/types.ts	Ban record returned by moderation endpoints.
communityContract	variable	src/community/contract.ts	Built-in route contract for Snapshot community APIs.
CommunityHooks	typealias	src/community/hooks.ts	Hook surface returned by createCommunityHooks().
communityKeys	variable	src/community/hooks.ts	Query key helpers for the community API surface. SSR loaders can seed the QueryClient under these keys so loader-seeded keys and hook-read keys stay aligned.
CommunityNotification	interface	src/types.ts	Normalized notification shape used by useCommunityNotifications().
CommunityNotificationType	typealias	src/types.ts	Community notification types surfaced by Snapshot’s notification helpers.
CommunitySearchParams	interface	src/community/types.ts	Search parameters accepted by the community search hooks.
ContactData	interface	src/community/types.ts	Contact card sidecar.
ContainerResponse	interface	src/community/types.ts	Community container returned by the community API.
ContentFormat	typealias	src/community/types.ts	Storage format hint for body text.
createAuthErrorFormatter	function	src/auth/error-format.ts	Create a reusable auth error formatter with shared formatting rules.
CreateContainerBody	interface	src/community/types.ts	Request body for creating a community container.
CreateReplyBody	interface	src/community/types.ts	Request body for creating a reply.
CreateReplyBodyExtended	interface	src/community/types.ts	Extended create-reply body — accepts optional sidecar fields the server may overwrite with parsed content metadata.
createSnapshot	function	src/create-snapshot.tsx	Create a per-instance Snapshot runtime from code-first bootstrap config. Builds per-instance API, auth, realtime, community, and webhook hooks from explicit TypeScript config.
CreateThreadBody	interface	src/community/types.ts	Request body for creating a thread in a container.
CreateThreadBodyExtended	interface	src/community/types.ts	Request body for creating a thread (extended). Optional sidecar fields can be set client-side; the server may overwrite them with parsed content metadata when its parseBody middleware runs. Treat client-supplied values as advisory.
CreateWebhookEndpointBody	interface	src/webhooks/types.ts	Request body for creating a webhook endpoint.
defaultContract	function	src/auth/contract.ts	Create the built-in auth contract for a given API base URL.
DeleteAccountBody	interface	src/types.ts	Request body for deleting the current account.
EmbedData	interface	src/community/types.ts	Resolved link-preview metadata for a URL referenced in content.
ForgotPasswordBody	interface	src/types.ts	Request body for the forgot-password endpoint.
formatAuthError	function	src/auth/error-format.ts	Format a raw auth ApiError into the message shown to application code.
getRegisteredClient	function	src/api/client.ts	Look up a previously registered custom client factory.
isMfaChallenge	function	src/types.ts	Narrow a login result to the MFA challenge branch.
ListParams	interface	src/community/types.ts	Shared page-based pagination parameters.
ListWebhookDeliveriesParams	interface	src/webhooks/types.ts	Parameters for listing deliveries for a single webhook endpoint.
ListWebhookEndpointsParams	interface	src/webhooks/types.ts	Page-based pagination parameters for listing webhook endpoints.
LocationData	interface	src/community/types.ts	Geo coordinate sidecar.
LoginBody	interface	src/types.ts	Credentials posted to the login endpoint.
LoginResponse	interface	src/types.ts	Raw login response shape from slingshot (includes MFA fields)
LoginResult	typealias	src/types.ts	useLogin resolves to either a user or an MFA challenge
LoginVars	typealias	src/types.ts	Login variables accepted by useLogin().
LogoutVars	interface	src/types.ts	Logout options accepted by useLogout().
mergeContract	function	src/auth/contract.ts	Merge a partial auth contract override with the built-in defaults.
MfaChallenge	interface	src/types.ts	Returned by useLogin when mfaRequired is true
MfaDisableBody	interface	src/types.ts	Request body for disabling MFA.
MfaEmailOtpDisableBody	interface	src/types.ts	Request body for disabling email OTP MFA.
MfaEmailOtpEnableResponse	interface	src/types.ts	Response returned when email OTP MFA setup begins.
MfaEmailOtpVerifySetupBody	interface	src/types.ts	Request body for confirming email OTP MFA setup.
MfaMethod	typealias	src/types.ts	MFA method identifiers supported by Snapshot’s auth contract.
MfaMethodsResponse	interface	src/types.ts	Response listing the enabled MFA methods for the current user.
MfaRecoveryCodesBody	interface	src/types.ts	Request body for regenerating recovery codes.
MfaRecoveryCodesResponse	interface	src/types.ts	Recovery codes returned by the auth API.
MfaResendBody	interface	src/types.ts	Request body for resending an MFA challenge.
MfaSetupResponse	interface	src/types.ts	Setup payload returned when provisioning TOTP MFA.
MfaVerifyBody	interface	src/types.ts	Request body for verifying an MFA challenge.
MfaVerifySetupBody	interface	src/types.ts	Verification body for confirming an MFA setup flow.
MfaVerifySetupResponse	interface	src/types.ts	Response returned after successful MFA setup verification.
NotificationResponse	interface	src/community/types.ts	Notification record returned by community notification endpoints.
OAuthExchangeBody	interface	src/types.ts	Request body for exchanging an OAuth callback code.
OAuthExchangeResponse	interface	src/types.ts	Tokens returned after a successful OAuth exchange.
OAuthProvider	typealias	src/types.ts	OAuth provider identifier used by auth URL helpers and OAuth hooks.
PaginatedResponse	interface	src/community/types.ts	Type definition exported by the Snapshot UI runtime.
PasskeyLoginBody	interface	src/types.ts	Request body for completing a passkey login.
PasskeyLoginOptionsBody	interface	src/types.ts	Request body for retrieving passkey login options.
PasskeyLoginOptionsResponse	interface	src/types.ts	Response returned when beginning a passkey login flow.
PasskeyLoginVars	typealias	src/types.ts	Passkey login variables accepted by usePasskeyLogin().
PushState	typealias	src/push/hook.ts	High-level browser push subscription state reported by usePushNotifications().
QuotePreview	interface	src/community/types.ts	Snapshot of a quoted message for inline display.
ReactionBody	interface	src/community/types.ts	Request body for adding/removing an emoji reaction. Sent to POST /community/threads/:id/reactions, etc.
ReactionResponse	interface	src/community/types.ts	Reaction record returned by the read endpoints — full shape with userId, type, and createdAt. Mirrors the slingshot-community Reaction entity. The list hooks (useThreadReactions, useReplyReactions) return arrays of this type. Consumers gating UI on “is this MY reaction” read userId.
RefreshTokenBody	interface	src/types.ts	Request body for refreshing auth tokens.
RefreshTokenResponse	interface	src/types.ts	Token refresh response returned by the auth API.
RegisterBody	interface	src/types.ts	Registration payload posted to the register endpoint.
registerClient	function	src/api/client.ts	Register a named custom client factory.
RegisterVars	typealias	src/types.ts	Registration variables accepted by useRegister().
ReplyListParams	interface	src/community/types.ts	List parameters for fetching replies in a specific thread.
ReplyResponse	interface	src/community/types.ts	Reply record returned by the community API. Fields mirror the slingshot-community Reply entity. JSON sidecars are typed against slingshot-core’s content types.
ReportBody	interface	src/community/types.ts	Request body for filing a community moderation report.
ReportResponse	interface	src/community/types.ts	Report record returned by moderation endpoints.
RequestOptions	interface	src/types.ts	Optional overrides for individual API client requests.
ResendVerificationBody	interface	src/types.ts	Request body for sending a new verification email.
ResetPasswordBody	interface	src/types.ts	Request body for completing a password reset flow.
ResolveReportBody	interface	src/community/types.ts	Request body for resolving a moderation report.
SearchResponse	interface	src/community/types.ts	Search results returned by the thread and reply search endpoints.
SendResult	typealias	src/ws/manager.ts	Outcome of writing a frame. - "sent" — written to an OPEN socket this instant. - "queued" — the socket was not OPEN (connecting / reconnecting), so the frame was buffered and WILL be flushed, in order, the moment the socket opens. It has NOT reached the server yet. - "dropped" — the manager is destroyed, or the caller opted out of queueing (a frame that is reconstructed on reconnect anyway), so the frame was discarded. A caller that needs to know its write is not yet delivered (e.g. a game input that must not report “sent” until the server confirms) can read this — a "queued" result is an explicit “deferred, not delivered” signal. Note that even "sent" is not proof of delivery: a frame written to an OPEN socket can still be lost in a half-open connection. Only an application-level ack proves the server received it.
Session	interface	src/types.ts	Active session metadata returned by session-management hooks.
SetPasswordBody	interface	src/types.ts	Request body for setting or rotating an account password.
SnapshotAuthConfig	interface	src/types.ts	Code-first auth configuration for createSnapshot().
SnapshotCacheConfig	interface	src/types.ts	TanStack Query cache defaults used by Snapshot’s built-in hooks.
SnapshotConfig	interface	src/types.ts	Bootstrap configuration for createSnapshot().
SnapshotInstance	interface	src/types.ts	Runtime surface returned by createSnapshot().
SnapshotMfaConfig	interface	src/types.ts	MFA settings forwarded to the MFA setup endpoint.
SnapshotOAuthProviderConfig	interface	src/types.ts	OAuth provider settings used by getOAuthUrl() and getLinkUrl().
SnapshotSessionConfig	interface	src/types.ts	User-session storage settings for token auth mode.
SnapshotWebAuthnConfig	interface	src/types.ts	WebAuthn relying-party settings forwarded to WebAuthn registration.
SnapshotWebSocketConfig	interface	src/types.ts	WebSocket settings for Snapshot’s built-in realtime hooks.
SocketHook	interface	src/types.ts	Realtime websocket control surface returned by useSocket().
SseConfig	interface	src/types.ts	SSE configuration. Each key is an endpoint path that must start with /__sse/. The value is per-endpoint options. One EventSource is created per endpoint. reconnectOnLogin: whether to reconnect all endpoints on login success (default true).
SseConnectionStatus	typealias	src/sse/manager.ts	Lifecycle state of a managed SSE connection.
SseEndpointConfig	interface	src/types.ts	Per-endpoint SSE behavior configuration.
SseEventHookResult	interface	src/types.ts	Return type of useSseEvent(endpoint, event)
SseHookResult	interface	src/types.ts	Return type of useSSE(endpoint)
SystemEventData	interface	src/community/types.ts	System message payload (room renames, member joins, etc.).
TestWebhookBody	interface	src/webhooks/types.ts	Request body for sending a test delivery through a webhook endpoint.
ThreadListParams	interface	src/community/types.ts	List parameters for fetching threads in a specific container.
ThreadResponse	interface	src/community/types.ts	Thread record returned by the community API. Fields mirror the slingshot-community Thread entity. JSON sidecar fields (mentions, attachments, embeds, …) are typed against slingshot-core’s content types and re-exported above for direct use.
TokenStorage	interface	src/auth/storage.ts	Per-instance token storage used by Snapshot auth flows.
UpdateContainerBody	interface	src/community/types.ts	Request body for updating a community container.
UpdateReplyBody	interface	src/community/types.ts	Request body for updating an existing reply.
UpdateThreadBody	interface	src/community/types.ts	Request body for updating or moderating a thread. Field names match the entity (pinned / locked).
UpdateWebhookEndpointBody	interface	src/webhooks/types.ts	Request body for updating a webhook endpoint.
UseCommunityNotificationsOpts	interface	src/types.ts	Options for the community notifications hook.
UseCommunityNotificationsResult	interface	src/types.ts	Return shape of useCommunityNotifications().
usePushNotifications	function	src/push/hook.ts	Standalone hook for Web Push subscription management. No dependency on Snapshot’s SSE or auth infrastructure. CSRF: /__push/* routes are CSRF-exempt by design. No CSRF header is sent. Auth: requests use credentials: ‘include’ (cookie auth). Service worker setup: copy sw.js from node_modules/@lastshotlabs/snapshot/dist/sw.js to your project’s public/sw.js, OR use snapshot init which scaffolds it automatically.
UsePushNotificationsOpts	interface	src/push/hook.ts	Push notification subscription options.
UsePushNotificationsResult	interface	src/push/hook.ts	Return shape of usePushNotifications().
VerifyEmailBody	interface	src/types.ts	Request body for confirming email verification.
VoiceMetadata	interface	src/community/types.ts	Voice-message-specific metadata (transcript, waveform peaks).
WebAuthnCredential	interface	src/types.ts	Registered WebAuthn credential metadata.
WebAuthnRegisterBody	interface	src/types.ts	Request body for registering a WebAuthn credential.
WebAuthnRegisterOptionsResponse	interface	src/types.ts	Response returned when requesting WebAuthn registration options.
WebhookDeliveryResponse	interface	src/webhooks/types.ts	Delivery record returned for a webhook endpoint event attempt.
WebhookEndpointResponse	interface	src/webhooks/types.ts	Webhook endpoint record returned by the webhook API.
WebhookHooks	typealias	src/webhooks/hooks.ts	Hook surface returned by createWebhookHooks().
webhooksContract	variable	src/webhooks/contract.ts	Built-in route contract for Snapshot webhook APIs.
WebSocketManager	class	src/ws/manager.ts	Per-instance WebSocket connection manager.

Factory

Export	Kind	Description
createSnapshot	function	Create a per-instance Snapshot runtime from code-first bootstrap config. Builds per-instance API, auth, realtime, community, and webhook hooks from explicit TypeScript config.

Details

createSnapshot<TWSEvents extends Record<string, unknown> = Record<string, unknown>>(config: SnapshotConfig) => SnapshotInstance<TWSEvents>

Create a per-instance Snapshot runtime from code-first bootstrap config.

Builds per-instance API, auth, realtime, community, and webhook hooks from explicit TypeScript config.

Parameters:

Name	Description
config	Code-first Snapshot runtime config

Returns: A fully initialized snapshot instance

Example:

import { createSnapshot } from '@lastshotlabs/snapshot';

const snap = createSnapshot({
  apiUrl: 'https://api.example.com',
});

// Use hooks in your React components
function App() {
  const { user } = snap.useUser();
  return user ? <div>Hello {user.email}</div> : <LoginForm />;
}

---

API Client

Export	Kind	Description
ApiError	class	HTTP error thrown by Snapshot API clients for non-success responses.
getRegisteredClient	function	Look up a previously registered custom client factory.
registerClient	function	Register a named custom client factory.

Details

getRegisteredClient(name: string) => ClientFactory | undefined

Look up a previously registered custom client factory.

Parameters:

Name	Description
name	Registered client factory name

Returns: The registered factory when found

---

registerClient(name: string, factory: ClientFactory) => void

Register a named custom client factory.

Parameters:

Name	Description
name	Client factory name
factory	Factory that creates an ApiClient-like instance

---

Auth

Export	Kind	Description
AuthContract	interface	Full auth contract used by createSnapshot() to build auth URLs and requests.
AuthContractConfig	interface	Partial auth contract overrides.
AuthEndpoints	interface	Relative auth endpoint paths used by Snapshot’s built-in auth hooks.
AuthErrorConfig	interface	Optional configuration for auth error formatting.
AuthErrorContext	typealias	Auth UI contexts that can provide custom error messaging.
AuthHeaders	interface	Header names Snapshot sends for session and CSRF-aware auth requests.
AuthUser	interface	Minimal authenticated user shape returned by Snapshot auth hooks.
createAuthErrorFormatter	function	Create a reusable auth error formatter with shared formatting rules.
defaultContract	function	Create the built-in auth contract for a given API base URL.
DeleteAccountBody	interface	Request body for deleting the current account.
ForgotPasswordBody	interface	Request body for the forgot-password endpoint.
formatAuthError	function	Format a raw auth ApiError into the message shown to application code.
LoginBody	interface	Credentials posted to the login endpoint.
LoginResponse	interface	Raw login response shape from slingshot (includes MFA fields)
LoginResult	typealias	useLogin resolves to either a user or an MFA challenge
LoginVars	typealias	Login variables accepted by useLogin().
LogoutVars	interface	Logout options accepted by useLogout().
mergeContract	function	Merge a partial auth contract override with the built-in defaults.
MfaChallenge	interface	Returned by useLogin when mfaRequired is true
MfaDisableBody	interface	Request body for disabling MFA.
MfaEmailOtpDisableBody	interface	Request body for disabling email OTP MFA.
MfaEmailOtpEnableResponse	interface	Response returned when email OTP MFA setup begins.
MfaEmailOtpVerifySetupBody	interface	Request body for confirming email OTP MFA setup.
MfaMethod	typealias	MFA method identifiers supported by Snapshot’s auth contract.
MfaMethodsResponse	interface	Response listing the enabled MFA methods for the current user.
MfaRecoveryCodesBody	interface	Request body for regenerating recovery codes.
MfaRecoveryCodesResponse	interface	Recovery codes returned by the auth API.
MfaResendBody	interface	Request body for resending an MFA challenge.
MfaSetupResponse	interface	Setup payload returned when provisioning TOTP MFA.
MfaVerifyBody	interface	Request body for verifying an MFA challenge.
MfaVerifySetupBody	interface	Verification body for confirming an MFA setup flow.
MfaVerifySetupResponse	interface	Response returned after successful MFA setup verification.
OAuthExchangeBody	interface	Request body for exchanging an OAuth callback code.
OAuthExchangeResponse	interface	Tokens returned after a successful OAuth exchange.
OAuthProvider	typealias	OAuth provider identifier used by auth URL helpers and OAuth hooks.
PasskeyLoginBody	interface	Request body for completing a passkey login.
PasskeyLoginOptionsBody	interface	Request body for retrieving passkey login options.
PasskeyLoginOptionsResponse	interface	Response returned when beginning a passkey login flow.
PasskeyLoginVars	typealias	Passkey login variables accepted by usePasskeyLogin().
RefreshTokenBody	interface	Request body for refreshing auth tokens.
RefreshTokenResponse	interface	Token refresh response returned by the auth API.
RegisterBody	interface	Registration payload posted to the register endpoint.
RegisterVars	typealias	Registration variables accepted by useRegister().
ResendVerificationBody	interface	Request body for sending a new verification email.
ResetPasswordBody	interface	Request body for completing a password reset flow.
Session	interface	Active session metadata returned by session-management hooks.
SetPasswordBody	interface	Request body for setting or rotating an account password.
TokenStorage	interface	Per-instance token storage used by Snapshot auth flows.
VerifyEmailBody	interface	Request body for confirming email verification.
WebAuthnCredential	interface	Registered WebAuthn credential metadata.
WebAuthnRegisterBody	interface	Request body for registering a WebAuthn credential.
WebAuthnRegisterOptionsResponse	interface	Response returned when requesting WebAuthn registration options.

Details

createAuthErrorFormatter(config?: AuthErrorConfig | undefined) => (error: ApiError, context: AuthErrorContext) => string

Create a reusable auth error formatter with shared formatting rules.

Example:

const format = createAuthErrorFormatter({ verbose: false });
const message = format(apiError, 'login');

---

defaultContract(apiUrl: string) => AuthContract

Create the built-in auth contract for a given API base URL.

---

formatAuthError(error: ApiError, context: AuthErrorContext, config?: AuthErrorConfig | undefined) => string

Format a raw auth ApiError into the message shown to application code.

Example:

const message = formatAuthError(apiError, 'login');

// With custom config
const message = formatAuthError(apiError, 'register', {
  verbose: true,
  messages: { register: 'Registration failed.' },
});

---

mergeContract(apiUrl: string, partial?: AuthContractConfig | undefined) => AuthContract

Merge a partial auth contract override with the built-in defaults.

Parameters:

Name	Description
apiUrl	Base API URL used to derive absolute auth URLs
partial	Partial contract override from code-first auth config

Returns: The merged auth contract

---

Community

Export	Kind	Description
AssetRef	interface	Reference to an uploaded asset (image, audio, video, file).
BanBody	interface	Request body for creating a user ban.
BanCheckResponse	interface	Result returned when checking whether a user is banned.
BanResponse	interface	Ban record returned by moderation endpoints.
communityContract	variable	Built-in route contract for Snapshot community APIs.
CommunityHooks	typealias	Hook surface returned by createCommunityHooks().
communityKeys	variable	Query key helpers for the community API surface. SSR loaders can seed the QueryClient under these keys so loader-seeded keys and hook-read keys stay aligned.
CommunityNotification	interface	Normalized notification shape used by useCommunityNotifications().
CommunityNotificationType	typealias	Community notification types surfaced by Snapshot’s notification helpers.
CommunitySearchParams	interface	Search parameters accepted by the community search hooks.
ContactData	interface	Contact card sidecar.
ContainerResponse	interface	Community container returned by the community API.
ContentFormat	typealias	Storage format hint for body text.
CreateContainerBody	interface	Request body for creating a community container.
CreateReplyBody	interface	Request body for creating a reply.
CreateReplyBodyExtended	interface	Extended create-reply body — accepts optional sidecar fields the server may overwrite with parsed content metadata.
CreateThreadBody	interface	Request body for creating a thread in a container.
CreateThreadBodyExtended	interface	Request body for creating a thread (extended). Optional sidecar fields can be set client-side; the server may overwrite them with parsed content metadata when its parseBody middleware runs. Treat client-supplied values as advisory.
EmbedData	interface	Resolved link-preview metadata for a URL referenced in content.
ListParams	interface	Shared page-based pagination parameters.
LocationData	interface	Geo coordinate sidecar.
NotificationResponse	interface	Notification record returned by community notification endpoints.
PaginatedResponse	interface	Type definition exported by the Snapshot UI runtime.
QuotePreview	interface	Snapshot of a quoted message for inline display.
ReactionBody	interface	Request body for adding/removing an emoji reaction. Sent to POST /community/threads/:id/reactions, etc.
ReactionResponse	interface	Reaction record returned by the read endpoints — full shape with userId, type, and createdAt. Mirrors the slingshot-community Reaction entity. The list hooks (useThreadReactions, useReplyReactions) return arrays of this type. Consumers gating UI on “is this MY reaction” read userId.
ReplyListParams	interface	List parameters for fetching replies in a specific thread.
ReplyResponse	interface	Reply record returned by the community API. Fields mirror the slingshot-community Reply entity. JSON sidecars are typed against slingshot-core’s content types.
ReportBody	interface	Request body for filing a community moderation report.
ReportResponse	interface	Report record returned by moderation endpoints.
ResolveReportBody	interface	Request body for resolving a moderation report.
SearchResponse	interface	Search results returned by the thread and reply search endpoints.
SystemEventData	interface	System message payload (room renames, member joins, etc.).
ThreadListParams	interface	List parameters for fetching threads in a specific container.
ThreadResponse	interface	Thread record returned by the community API. Fields mirror the slingshot-community Thread entity. JSON sidecar fields (mentions, attachments, embeds, …) are typed against slingshot-core’s content types and re-exported above for direct use.
UpdateContainerBody	interface	Request body for updating a community container.
UpdateReplyBody	interface	Request body for updating an existing reply.
UpdateThreadBody	interface	Request body for updating or moderating a thread. Field names match the entity (pinned / locked).
UseCommunityNotificationsOpts	interface	Options for the community notifications hook.
UseCommunityNotificationsResult	interface	Return shape of useCommunityNotifications().
VoiceMetadata	interface	Voice-message-specific metadata (transcript, waveform peaks).

Webhooks

Export	Kind	Description
CreateWebhookEndpointBody	interface	Request body for creating a webhook endpoint.
ListWebhookDeliveriesParams	interface	Parameters for listing deliveries for a single webhook endpoint.
ListWebhookEndpointsParams	interface	Page-based pagination parameters for listing webhook endpoints.
TestWebhookBody	interface	Request body for sending a test delivery through a webhook endpoint.
UpdateWebhookEndpointBody	interface	Request body for updating a webhook endpoint.
WebhookDeliveryResponse	interface	Delivery record returned for a webhook endpoint event attempt.
WebhookEndpointResponse	interface	Webhook endpoint record returned by the webhook API.
WebhookHooks	typealias	Hook surface returned by createWebhookHooks().
webhooksContract	variable	Built-in route contract for Snapshot webhook APIs.

Push Notifications

Export	Kind	Description
PushState	typealias	High-level browser push subscription state reported by usePushNotifications().
usePushNotifications	function	Standalone hook for Web Push subscription management. No dependency on Snapshot’s SSE or auth infrastructure. CSRF: /__push/* routes are CSRF-exempt by design. No CSRF header is sent. Auth: requests use credentials: ‘include’ (cookie auth). Service worker setup: copy sw.js from node_modules/@lastshotlabs/snapshot/dist/sw.js to your project’s public/sw.js, OR use snapshot init which scaffolds it automatically.
UsePushNotificationsOpts	interface	Push notification subscription options.
UsePushNotificationsResult	interface	Return shape of usePushNotifications().

Details

usePushNotifications(opts?: UsePushNotificationsOpts | undefined) => UsePushNotificationsResult

Standalone hook for Web Push subscription management. No dependency on Snapshot’s SSE or auth infrastructure.

CSRF: /__push/* routes are CSRF-exempt by design. No CSRF header is sent. Auth: requests use credentials: ‘include’ (cookie auth).

Service worker setup: copy sw.js from node_modules/@lastshotlabs/snapshot/dist/sw.js to your project’s public/sw.js, OR use snapshot init which scaffolds it automatically.

Example:

const { state, subscribe, unsubscribe } = usePushNotifications();

// With custom options
const { state, subscribe, unsubscribe } = usePushNotifications({
  vapidPublicKey: 'BEl62i...',
  subscribeUrl: '/api/push/subscribe',
});

---

Realtime

Export	Kind	Description
SendResult	typealias	Outcome of writing a frame. - "sent" — written to an OPEN socket this instant. - "queued" — the socket was not OPEN (connecting / reconnecting), so the frame was buffered and WILL be flushed, in order, the moment the socket opens. It has NOT reached the server yet. - "dropped" — the manager is destroyed, or the caller opted out of queueing (a frame that is reconstructed on reconnect anyway), so the frame was discarded. A caller that needs to know its write is not yet delivered (e.g. a game input that must not report “sent” until the server confirms) can read this — a "queued" result is an explicit “deferred, not delivered” signal. Note that even "sent" is not proof of delivery: a frame written to an OPEN socket can still be lost in a half-open connection. Only an application-level ack proves the server received it.
SocketHook	interface	Realtime websocket control surface returned by useSocket().
SseConfig	interface	SSE configuration. Each key is an endpoint path that must start with /__sse/. The value is per-endpoint options. One EventSource is created per endpoint. reconnectOnLogin: whether to reconnect all endpoints on login success (default true).
SseConnectionStatus	typealias	Lifecycle state of a managed SSE connection.
SseEndpointConfig	interface	Per-endpoint SSE behavior configuration.
SseEventHookResult	interface	Return type of useSseEvent(endpoint, event)
SseHookResult	interface	Return type of useSSE(endpoint)
WebSocketManager	class	Per-instance WebSocket connection manager.

Core Types

Export	Kind	Description
AUTH_QUERY_KEY	variable	Stable query key under which useUser() and the route guards cache the authenticated user. Exported so apps can invalidate, seed, or read the cache directly (e.g. after a profile update or server-side state change that should force a refresh).
isMfaChallenge	function	Narrow a login result to the MFA challenge branch.
RequestOptions	interface	Optional overrides for individual API client requests.
SnapshotAuthConfig	interface	Code-first auth configuration for createSnapshot().
SnapshotCacheConfig	interface	TanStack Query cache defaults used by Snapshot’s built-in hooks.
SnapshotConfig	interface	Bootstrap configuration for createSnapshot().
SnapshotInstance	interface	Runtime surface returned by createSnapshot().
SnapshotMfaConfig	interface	MFA settings forwarded to the MFA setup endpoint.
SnapshotOAuthProviderConfig	interface	OAuth provider settings used by getOAuthUrl() and getLinkUrl().
SnapshotSessionConfig	interface	User-session storage settings for token auth mode.
SnapshotWebAuthnConfig	interface	WebAuthn relying-party settings forwarded to WebAuthn registration.
SnapshotWebSocketConfig	interface	WebSocket settings for Snapshot’s built-in realtime hooks.

Details

isMfaChallenge(result: LoginResult) => result is MfaChallenge

Narrow a login result to the MFA challenge branch.

---

SnapshotConfig (interface)

Bootstrap configuration for createSnapshot().

Members:

Name	Type	Description
apiUrl	string	API base URL for this snapshot instance.
bearerToken	string | undefined	Static API credential. Not a user session token. Do not use in browser deployments - emits a runtime warning in browser contexts.
auth	SnapshotAuthConfig | undefined	Auth contract, session, OAuth, MFA, and WebAuthn settings.
cache	SnapshotCacheConfig | undefined	Query cache defaults used by Snapshot’s built-in hooks.
ws	SnapshotWebSocketConfig | undefined	WebSocket settings for useSocket, useRoom, and useRoomEvent.
sse	SseConfig | undefined	Server-sent event settings for useSSE and useSseEvent.
loginPath	string | undefined	Path the protectedBeforeLoad guard redirects to when the user is unauthenticated.
homePath	string | undefined	Path the guestBeforeLoad guard redirects to when an authenticated user lands on a guest-only screen.
mfaPath	string | undefined	Path used when a login or passkey flow requires MFA.

Example:

const snap = createSnapshot({
  apiUrl: 'https://api.example.com',
});

---

SnapshotInstance (interface)

Runtime surface returned by createSnapshot().

Members:

Name	Type	Description
bootstrap	{ bearerToken?: string | undefined; }	Bootstrap values used to create this snapshot instance.
useUser	() => { user: AuthUser | null; isLoading: boolean; isError: boolean; }	Fetch the current authenticated user. Returns null when logged out.
useLogin	() => UseMutationResult<LoginResult, ApiError, LoginVars>	Post credentials and log in. Returns an MFA challenge instead of a user when MFA is required.
useLogout	() => UseMutationResult<void, ApiError, void | LogoutVars>	Clear the session, tokens, and query cache. Navigates to the login route on success.
useRegister	() => UseMutationResult<AuthUser, ApiError, RegisterVars>	Create a new account. Auto-logs in on success when the backend allows it.
useForgotPassword	() => UseMutationResult<void, ApiError, ForgotPasswordBody>	Send a password-reset email to the given address.
useSocket	() => SocketHook<TWSEvents>	Open and manage a WebSocket connection. Returns connection state and send/close helpers.
useRoom	(room: string) => { isSubscribed: boolean; }	Subscribe to a WebSocket room. Returns whether the subscription is active.
useRoomEvent	<T>(room: string, event: string, handler: (data: T) => void) => void	Listen for a specific event on a WebSocket room. The handler fires on each matching message.
useTheme	() => { theme: "light" | "dark"; toggle: () => void; set: (t: "light" | "dark...	Read and toggle the current color theme (light/dark).
usePendingMfaChallenge	() => MfaChallenge | null	Read the pending MFA challenge set by a login that returned mfaRequired: true.
useMfaVerify	() => UseMutationResult<AuthUser, ApiError, Omit<MfaVerifyBody, "mfaToken">>	Verify an MFA code against the pending challenge. Resolves to the authenticated user on success.
useMfaSetup	() => UseMutationResult<MfaSetupResponse, ApiError, void>	Begin TOTP MFA provisioning. Returns a secret and QR URI for authenticator apps.
useMfaVerifySetup	() => UseMutationResult<MfaVerifySetupResponse, ApiError, MfaVerifySetupBody>	Confirm TOTP MFA setup by verifying a code from the authenticator app.
useMfaDisable	() => UseMutationResult<{ message: string; }, ApiError, MfaDisableBody>	Disable MFA for the current user. Requires a valid code or recovery code.
useMfaRecoveryCodes	() => UseMutationResult<MfaRecoveryCodesResponse, ApiError, MfaRecoveryCodesB...	Regenerate MFA recovery codes. Returns the new codes.
useMfaEmailOtpEnable	() => UseMutationResult<MfaEmailOtpEnableResponse, ApiError, void>	Begin email OTP MFA enrollment. Sends a verification code to the user’s email.
useMfaEmailOtpVerifySetup	() => UseMutationResult<MfaVerifySetupResponse, ApiError, MfaEmailOtpVerifySe...	Confirm email OTP MFA setup by verifying the emailed code.
useMfaEmailOtpDisable	() => UseMutationResult<{ message: string; }, ApiError, MfaEmailOtpDisableBody>	Disable email OTP MFA for the current user.
useMfaResend	() => UseMutationResult<{ message: string; }, ApiError, MfaResendBody>	Resend the MFA challenge code (email OTP or SMS).
useMfaMethods	() => { methods: MfaMethod[] | null; isLoading: boolean; isError: boolean; }	List MFA methods currently enabled for the authenticated user.
isMfaChallenge	(result: LoginResult) => result is MfaChallenge	Type-narrowing guard: returns true when a login result is an MFA challenge.
useResetPassword	() => UseMutationResult<{ message: string; }, ApiError, ResetPasswordBody>	Complete a password reset using the token from the reset email.
useVerifyEmail	() => UseMutationResult<{ message: string; }, ApiError, VerifyEmailBody>	Confirm the user’s email address using a verification token.
useResendVerification	() => UseMutationResult<{ message: string; }, ApiError, ResendVerificationBody>	Request a new verification email for the current user.
useSetPassword	() => UseMutationResult<{ message: string; }, ApiError, SetPasswordBody>	Set or rotate the account password. Requires the current password or a reset token.
useDeleteAccount	() => UseMutationResult<void, ApiError, void | DeleteAccountBody>	Schedule the current account for deletion.
useCancelDeletion	() => UseMutationResult<{ message: string; }, ApiError, void>	Cancel a pending account deletion before the grace period expires.
useRefreshToken	() => UseMutationResult<RefreshTokenResponse, ApiError, void | RefreshTokenBody>	Refresh the current access and refresh tokens.
useSessions	() => { sessions: Session[]; isLoading: boolean; isError: boolean; }	List all active sessions for the authenticated user.
useRevokeSession	() => UseMutationResult<void, ApiError, string>	Revoke a session by its ID. Logs out that device.
useOAuthExchange	(opts?: { navigateOnSuccess?: boolean | undefined; } | undefined) => UseMutat...	Exchange an OAuth callback code for session tokens. Called after the provider redirects back. Pass { navigateOnSuccess: false } to suppress the default navigate to homePath and let the caller decide where to go after the exchange completes (e.g. an admin callback that needs to verify a permission grant before navigating).
useOAuthUnlink	() => UseMutationResult<void, ApiError, OAuthProvider>	Remove an OAuth provider link from the current account.
getOAuthUrl	(provider: OAuthProvider, opts?: { returnTo?: string | undefined; } | undefin...	Build the redirect URL for starting an OAuth login flow with the given provider. Pass opts.returnTo to override the api’s default post-login redirect with a per-flow target — used when a secondary origin (admin app, embedded surface) shares the same OAuth client but needs the callback delivered to its own origin.
getLinkUrl	(provider: OAuthProvider) => string	Build the redirect URL for linking an OAuth provider to the current account.
useWebAuthnRegisterOptions	() => UseMutationResult<WebAuthnRegisterOptionsResponse, ApiError, void>	Request WebAuthn registration options (challenge, relying party info) from the server.
useWebAuthnRegister	() => UseMutationResult<{ message: string; }, ApiError, WebAuthnRegisterBody>	Complete WebAuthn credential registration with the attestation response from the authenticator.
useWebAuthnCredentials	() => { credentials: WebAuthnCredential[]; isLoading: boolean; isError: boole...	List all registered WebAuthn credentials for the current user.
useWebAuthnRemoveCredential	() => UseMutationResult<{ message: string; }, ApiError, string>	Remove a registered WebAuthn credential by its ID.
useWebAuthnDisable	() => UseMutationResult<{ message: string; }, ApiError, void>	Disable WebAuthn for the current user and remove all registered credentials.
usePasskeyLoginOptions	() => UseMutationResult<PasskeyLoginOptionsResponse, ApiError, PasskeyLoginOp...	Request passkey login options (challenge) from the server to start a passwordless login.
usePasskeyLogin	() => UseMutationResult<LoginResult, ApiError, PasskeyLoginVars>	Complete a passkey login with the assertion response from the authenticator.
formatAuthError	(error: ApiError, context: AuthErrorContext) => string	Format an API error into a user-facing auth error message using optional per-context overrides.
useSSE	(endpoint: string) => SseHookResult	Connect to a server-sent events endpoint. Returns connection status and a close function.
useSseEvent	<T = unknown>(endpoint: string, event: string) => SseEventHookResult<T>	Subscribe to a named event on an SSE endpoint. Returns the latest payload and connection status.
onSseEvent	(endpoint: string, event: string, handler: (payload: unknown) => void) => () ...	Register a callback for a named SSE event. Returns an unsubscribe function.
useCommunityNotifications	(opts?: UseCommunityNotificationsOpts | undefined) => UseCommunityNotificatio...	Subscribe to real-time community notifications via SSE. Requires an /__sse/notifications endpoint.
useContainers	(params?: ListParams | undefined) => UseQueryResult<PaginatedResponse<Contain...	List community containers with optional pagination.
useContainer	(containerId: string) => UseQueryResult<ContainerResponse, ApiError>	Fetch a single container by ID.
useCreateContainer	() => UseMutationResult<ContainerResponse, ApiError, CreateContainerBody, unk...	Create a new community container.
useUpdateContainer	() => UseMutationResult<ContainerResponse, ApiError, { containerId: string; }...	Update a container’s metadata.
useDeleteContainer	() => UseMutationResult<void, ApiError, { containerId: string; }, unknown>	Delete a container and its contents.
useContainerThreads	({ containerId, ...params }: ThreadListParams) => UseQueryResult<PaginatedRes...	List threads in a container with pagination and optional filters.
useContainerThread	(threadId: string) => UseQueryResult<ThreadResponse, ApiError>	Fetch a single thread by ID.
useCreateThread	() => UseMutationResult<ThreadResponse, ApiError, { containerId: string; } & ...	Create a new thread in a container.
useUpdateThread	() => UseMutationResult<ThreadResponse, ApiError, { threadId: string; contain...	Update a thread’s content or metadata.
useDeleteThread	() => UseMutationResult<void, ApiError, { threadId: string; containerId: stri...	Delete a thread.
usePublishThread	() => UseMutationResult<ThreadResponse, ApiError, { threadId: string; contain...	Publish a draft thread, making it visible to other users.
useLockThread	() => UseMutationResult<ThreadResponse, ApiError, { threadId: string; contain...	Lock a thread to prevent new replies.
useUnlockThread	() => UseMutationResult<ThreadResponse, ApiError, { threadId: string; contain...	Unlock a thread so replies can be posted again.
usePinThread	() => UseMutationResult<ThreadResponse, ApiError, { threadId: string; contain...	Pin a thread to the top of its container.
useUnpinThread	() => UseMutationResult<ThreadResponse, ApiError, { threadId: string; contain...	Unpin a previously pinned thread.
useThreadReplies	({ threadId, ...params }: ReplyListParams) => UseQueryResult<PaginatedRespons...	List replies in a thread with pagination.
useReply	(replyId: string) => UseQueryResult<ReplyResponse, ApiError>	Fetch a single reply by ID.
useCreateReply	() => UseMutationResult<ReplyResponse, ApiError, { threadId: string; } & Crea...	Post a new reply to a thread.
useUpdateReply	() => UseMutationResult<ReplyResponse, ApiError, { replyId: string; threadId:...	Update a reply’s content.
useDeleteReply	() => UseMutationResult<void, ApiError, { replyId: string; threadId: string; ...	Delete a reply.
useThreadReactions	(threadId: string) => UseQueryResult<ReactionResponse[], ApiError>	List reactions on a thread.
useReplyReactions	(replyId: string) => UseQueryResult<ReactionResponse[], ApiError>	List reactions on a reply.
useAddThreadReaction	() => UseMutationResult<void, ApiError, { threadId: string; containerId: stri...	Add an emoji reaction to a thread.
useRemoveThreadReaction	() => UseMutationResult<void, ApiError, { reactionId: string; threadId: strin...	Remove an emoji reaction from a thread.
useAddReplyReaction	() => UseMutationResult<void, ApiError, { replyId: string; threadId: string; ...	Add an emoji reaction to a reply.
useRemoveReplyReaction	() => UseMutationResult<void, ApiError, { reactionId: string; replyId: string...	Remove an emoji reaction from a reply.
useContainerMembers	(containerId: string, params?: ListParams | undefined) => UseQueryResult<Memb...	List members of a container with pagination.
useContainerModerators	(containerId: string, params?: ListParams | undefined) => UseQueryResult<Memb...	List moderators of a container.
useContainerOwners	(containerId: string, params?: ListParams | undefined) => UseQueryResult<Memb...	List owners of a container.
useAddMember	() => UseMutationResult<MemberRecord, ApiError, { containerId: string; userId...	Add a user as a member of a container.
useRemoveMember	() => UseMutationResult<void, ApiError, { containerId: string; userId: string...	Remove a member from a container.
useAssignModerator	() => UseMutationResult<void, ApiError, { containerId: string; userId: string...	Promote a member to moderator.
useRemoveModerator	() => UseMutationResult<void, ApiError, { containerId: string; userId: string...	Remove moderator role from a user.
useAssignOwner	() => UseMutationResult<void, ApiError, { containerId: string; userId: string...	Promote a member to owner.
useRemoveOwner	() => UseMutationResult<void, ApiError, { containerId: string; userId: string...	Remove owner role from a user.
useNotifications	(params?: ListParams | undefined) => UseQueryResult<PaginatedResponse<Notific...	List notifications for the current user with pagination.
useNotificationsUnreadCount	() => UseQueryResult<{ count: number; }, ApiError>	Get the count of unread notifications.
useMarkAllNotificationsSeen	() => UseMutationResult<void, ApiError, void, unknown>	Clear the notification badge without marking rows read.
useMarkNotificationRead	() => UseMutationResult<void, ApiError, { notificationId: string; }, unknown>	Mark a single notification as read.
useMarkAllNotificationsRead	() => UseMutationResult<void, ApiError, void, unknown>	Mark all notifications as read.
useDismissNotification	() => UseMutationResult<void, ApiError, { notificationId: string; }, unknown>	Dismiss a notification owned by the current user.
useReports	(params?: ListParams | undefined) => UseQueryResult<PaginatedResponse<ReportR...	List moderation reports with pagination.
useReport	(reportId: string) => UseQueryResult<ReportResponse, ApiError>	Fetch a single report by ID.
useCreateReport	() => UseMutationResult<ReportResponse, ApiError, ReportBody, unknown>	File a moderation report against a thread or reply.
useResolveReport	() => UseMutationResult<ReportResponse, ApiError, { reportId: string; } & Res...	Resolve a moderation report with an action (e.g., warn, delete).
useDismissReport	() => UseMutationResult<ReportResponse, ApiError, { reportId: string; }, unkn...	Dismiss a moderation report without taking action.
useBans	(params?: ListParams | undefined) => UseQueryResult<PaginatedResponse<BanResp...	List banned users with pagination.
useCheckBan	(userId: string, containerId?: string | undefined) => UseQueryResult<BanCheck...	Check whether a specific user is banned.
useCreateBan	() => UseMutationResult<BanResponse, ApiError, BanBody, unknown>	Ban a user from a container or globally.
useRemoveBan	() => UseMutationResult<void, ApiError, { banId: string; userId: string; }, u...	Remove a ban, restoring the user’s access.
useSearchThreads	(params: CommunitySearchParams & { q: string; }) => UseQueryResult<SearchResp...	Full-text search across threads.
useSearchReplies	(params: CommunitySearchParams & { q: string; }) => UseQueryResult<SearchResp...	Full-text search across replies.
useWebhookEndpoints	() => UseQueryResult<WebhookEndpointResponse[], ApiError>	List webhook endpoints with pagination.
useWebhookEndpoint	(endpointId: string) => UseQueryResult<WebhookEndpointResponse, ApiError>	Fetch a single webhook endpoint by ID.
useCreateWebhookEndpoint	() => UseMutationResult<WebhookEndpointResponse, ApiError, CreateWebhookEndpo...	Create a new webhook endpoint.
useUpdateWebhookEndpoint	() => UseMutationResult<WebhookEndpointResponse, ApiError, { endpointId: stri...	Update an existing webhook endpoint’s URL, events, or status.
useDeleteWebhookEndpoint	() => UseMutationResult<void, ApiError, { endpointId: string; }, unknown>	Delete a webhook endpoint.
useWebhookDeliveries	({ endpointId, page, pageSize, }: ListWebhookDeliveriesParams) => UseQueryRes...	List delivery attempts for a webhook endpoint.
useWebhookDelivery	(deliveryId: string) => UseQueryResult<WebhookDeliveryResponse, ApiError>	Fetch a single delivery record by ID.
useTestWebhookEndpoint	() => UseMutationResult<void, ApiError, { endpointId: string; } & TestWebhook...	Send a test delivery through a webhook endpoint.
api	ApiClient	Low-level API client bound to this snapshot instance.
tokenStorage	TokenStorage	Token storage used for session persistence (access + refresh tokens).
queryClient	QueryClient	TanStack Query client shared across all hooks in this snapshot instance.
useWebSocketManager	() => WebSocketManager<TWSEvents> | null	Access the WebSocket connection manager. Returns null when WebSocket is not configured.
protectedBeforeLoad	(ctx: { context: { queryClient: QueryClient; }; }) => Promise<void>	Low-level route guard that redirects unauthenticated users to the login page. Prefer protect() — it returns a typed { beforeLoad } fragment that slots into createFileRoute(...)({...}) without a caller cast.
guestBeforeLoad	(ctx: { context: { queryClient: QueryClient; }; }) => Promise<void>	Low-level route guard that redirects authenticated users away from guest-only pages. Prefer guest() — it returns a typed { beforeLoad } fragment that slots into createFileRoute(...)({...}) without a caller cast.
protect	() => { beforeLoad: never; }	Route fragment factory for protected (auth-required) routes.
guest	() => { beforeLoad: never; }	Route fragment factory for guest-only (logged-out) routes. Mirror of protect().
setNavigator	(nav: ((to: string, opts: { replace?: boolean | undefined; }) => void) | null...	Register a router-aware navigator. Auth hooks (useLogout, useDeleteAccount, OAuth/MFA flows) call this for post-mutation redirects so the router actually transitions instead of falling through to pushState + popstate (which TanStack Router ignores). Pass null to clear.
QueryProvider	FC<{ children: ReactNode; }>	React provider that wraps children with the TanStack QueryClientProvider for this instance.

---