useDataRequest

useDataRequest() powers the GDPR data-request flow (Art. 15/20). The user clicks once; the hook posts the request and reflects the outcome through a status state machine, including the “you already have an open request” and “rate-limited” cases, without ever throwing.

When to use it

• Wire a “request my data” button in a privacy / settings screen (the prebuilt <DataRequest> component wraps this).

Usage

import { useDataRequest } from '@torii-js/torii-react';

function RequestData() {
  const { status, submit } = useDataRequest();

  if (status === 'submitted' || status === 'already-pending')
    return <p>Your data request is being processed.</p>;
  if (status === 'rate-limited') return <p>Please try again later.</p>;

  return (
    <button disabled={status === 'submitting'} onClick={() => submit()}>
      Request my data
    </button>
  );
}

Returns

Name	Type	Description
status	DataRequestView	Current view state: 'idle' | 'submitting' | 'submitted' | 'already-pending' | 'rate-limited' | 'error'.
pendingRequest	DataRequestRecord | null	The user’s open request, when one exists. Populated on mount so the UI can render “already requested” without a click.
error	ToriiError | null	Structured error (a ToriiError, not a localized string) when status is 'error', else null. Localize it yourself.
submit	() => Promise<void>	Submit a data request. Always resolves: the outcome is reflected in status, never thrown.

Notes

• Never throws: every outcome, including the 409 already-pending and 429 rate-limited responses, maps to a status value.
• Fulfilled out-of-band: an operator fulfils the request from the dashboard; the hook only tracks submission, not delivery.

TypeScript

import type {
  UseDataRequestReturn,
  DataRequestRecord,
  DataRequestView,
  ToriiError,
} from '@torii-js/torii-react';