SDK reference

Everything exported by @relay/sdk and @relay/sdk/server.

createRelay(options)

Creates a client. Pass an event map type to get typed track() calls.

client

import { createRelay, type PhotoEditEvents } from "@relay/sdk";

const relay = createRelay<PhotoEditEvents>({ publicKey, endpoint, attest });

Options

Option	Default	Description
publicKey	required	Your public key, pk_dev_… or pk_live_…
endpoint	required	The Relay API origin sent with your keys.
attest	required	Async function returning an attestation token from your backend. Called only after opt-in, or to resume one.
storage	localStorage	Where the decision is remembered. Never stores an identifier. null keeps it in memory.
flushIntervalMs	5000	How often queued events are sent.
maxBatchSize	20	Events per request. The server maximum is 50.
maxQueueSize	200	Further events are dropped and reported through onError.
maxRetries	3	Retries for network, 429 and 5xx failures. The batch keeps its idempotency key.
retryBaseMs	500	Base delay for exponential backoff, capped at 30 seconds.
fetch	global fetch	Inject your own for logging or tests.
onStateChange		Called with the new state whenever it changes.
onError		Called with a RelayError for dropped events and failed batches.

Client methods

Method	Returns	Description
init()	Promise<RelayState>	Restores an earlier decision. Makes no request unless the user opted in before.
presentConsent({ container? })	Promise<choice>	Shows the built-in dialog. Resolves to accepted, declined or dismissed.
getConsent()	Promise<ConsentPresentation>	Fetches consent copy and fields for a custom UI.
accept(presentation)	Promise<ConsentReceipt>	Records an opt-in from a custom UI.
decline(presentation?)	void	Records a decline. Sends nothing.
startSession()	ContributionSession \| null	Starts a sequenced session. null unless active.
flush()	Promise<void>	Sends queued events now.
withdraw()	Promise<void>	Stops collection, clears the queue and revokes tokens.
requestDeletion()	Promise<{ deletionRequestId, notice }>	Withdraws, then deletes stored contributions.
getState()	RelayState	The current state.
getReceipt()	ConsentReceipt \| null	The active consent receipt, if any.
queuedCount()	number	Events waiting to be sent.
destroy()	void	Stops timers and listeners.

Sessions

session.track(type, payload) queues an event with the session's sessionId and the next sequence. It returns false and stores nothing if the user is not opted in.

Delivery

Events are batched by size or interval. Each batch carries an idempotency key that retries reuse, so a batch is never stored twice. Network, 429 and 5xx failures retry with exponential backoff and honour Retry-After. An expired token triggers one re-attestation and a retry of the same batch.

createRelayServer(options)

For your backend. Takes secretKey, endpoint and an optional fetch.

Method	Description
attest({ subject })	Mints a single-use attestation for a signed-in user. Returns { attestationToken }.
withdraw({ subject })	Withdraws a user on their behalf.
requestDeletion({ subject })	Withdraws and deletes a user's contributions.