next-sanctum 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,508 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Error types for next-sanctum. All failures are normalized to `SanctumError`
+ * so consumers can handle them consistently (see plan §10: errors must not leak).
+ */
+type SanctumErrorKind = "config" | "network" | "unauthorized" | "forbidden" | "csrf" | "validation" | "http" | "unknown";
+interface SanctumErrorOptions {
+    kind: SanctumErrorKind;
+    status?: number;
+    /** The already-parsed response body (JSON when possible). */
+    data?: unknown;
+    cause?: unknown;
+}
+/** Base error for all module failures. */
+declare class SanctumError extends Error {
+    readonly kind: SanctumErrorKind;
+    readonly status?: number;
+    readonly data?: unknown;
+    constructor(message: string, options: SanctumErrorOptions);
+}
+/** Invalid configuration — fail-fast on init (see resolveConfig). */
+declare class ConfigError extends SanctumError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * HTTP 422 from Laravel. Exposes field errors (`{ field: string[] }`) so
+ * consumers can map them to their forms.
+ */
+declare class ValidationError extends SanctumError {
+    readonly errors: Record<string, string[]>;
+    constructor(message: string, errors: Record<string, string[]>, data?: unknown);
+}
+
+/**
+ * Public & internal type surface of next-sanctum.
+ * TypeScript-first, generic User model, no public `any`.
+ */
+
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/** Authentication mode. `cookie` = CSRF/SPA (default), `token` = Bearer. */
+type AuthMode = "cookie" | "token";
+/** 0 silent · 1 error · 2 warn · 3 info (default) · 4 debug · 5 verbose. */
+type LogLevel = 0 | 1 | 2 | 3 | 4 | 5;
+/** Generic user shape; consumers cast it via the generic on the client/hook. */
+type SanctumUser = Record<string, unknown>;
+interface TwoFactorEndpoints {
+    challenge: string;
+    enable: string;
+    confirm: string;
+    disable: string;
+    qrCode: string;
+    secretKey: string;
+    recoveryCodes: string;
+}
+interface PasskeyEndpoints {
+    loginOptions: string;
+    login: string;
+    confirmOptions: string;
+    confirm: string;
+    registerOptions: string;
+    register: string;
+    /** Base path; the passkey id is appended (`${delete}/${id}`). */
+    delete: string;
+}
+interface SessionEndpoints {
+    list: string;
+    logoutOthers: string;
+    logout: string;
+}
+interface SanctumEndpoints {
+    csrf: string;
+    login: string;
+    logout: string;
+    user: string;
+    register: string;
+    forgotPassword: string;
+    resetPassword: string;
+    emailVerificationNotification: string;
+    /** Base path for completing verification; `/{id}/{hash}` is appended. */
+    verifyEmail: string;
+    confirmPassword: string;
+    confirmedPasswordStatus: string;
+    profileInformation: string;
+    updatePassword: string;
+    twoFactor: TwoFactorEndpoints;
+    passkeys: PasskeyEndpoints;
+    sessions: SessionEndpoints;
+}
+interface TwoFactorFeature {
+    /** Require a code confirmation step after enabling (default true). */
+    confirm?: boolean;
+    /** Require password confirmation before managing 2FA (default true). */
+    confirmPassword?: boolean;
+}
+interface PasskeysFeature {
+    confirmPassword?: boolean;
+}
+interface FeatureFlags {
+    registration?: boolean;
+    resetPasswords?: boolean;
+    emailVerification?: boolean;
+    updateProfileInformation?: boolean;
+    updatePasswords?: boolean;
+    twoFactorAuthentication?: boolean | TwoFactorFeature;
+    passkeys?: boolean | PasskeysFeature;
+    /** v1.1 — not yet implemented. */
+    deviceSessions?: boolean;
+}
+interface CsrfConfig {
+    cookie: string;
+    header: string;
+}
+interface RedirectConfig {
+    onLogin: string;
+    onLogout: string;
+    onAuthOnly: string;
+    onGuestOnly: string;
+    keepRequestedRoute: boolean;
+}
+interface SanctumEventMap<TUser = SanctumUser> {
+    init: {
+        user: TUser | null;
+    };
+    login: {
+        user: TUser;
+    };
+    logout: Record<string, never>;
+    refresh: {
+        user: TUser | null;
+    };
+    "two-factor-required": Record<string, never>;
+    error: {
+        error: SanctumError;
+    };
+    redirect: {
+        to: string;
+        reason: string;
+    };
+    request: {
+        url: string;
+        init: RequestInit;
+    };
+    response: {
+        url: string;
+        response: Response;
+    };
+}
+type SanctumEventName = keyof SanctumEventMap;
+type SanctumEventHandler<TUser = SanctumUser, K extends SanctumEventName = SanctumEventName> = (payload: SanctumEventMap<TUser>[K]) => void;
+type RequestInterceptor = (request: Request) => Request | Promise<Request>;
+type ResponseInterceptor = (response: Response, request: Request) => Response | Promise<Response>;
+interface Interceptors {
+    request?: RequestInterceptor[];
+    response?: ResponseInterceptor[];
+}
+/** Bearer token storage interface (token mode). Swappable. */
+interface SanctumTokenStorage {
+    get(): Promise<string | null> | string | null;
+    set(token: string): Promise<void> | void;
+    remove(): Promise<void> | void;
+}
+/** Config provided by the consumer. Only `baseUrl` is required. */
+interface SanctumConfig {
+    baseUrl: string;
+    mode?: AuthMode;
+    /** App origin for the Referer header (default: window.location.origin when available). */
+    origin?: string;
+    features?: FeatureFlags;
+    endpoints?: DeepPartial<SanctumEndpoints>;
+    csrf?: Partial<CsrfConfig>;
+    redirect?: Partial<RedirectConfig>;
+    logLevel?: LogLevel;
+    /** Fetch the user on init (default true). */
+    initialRequest?: boolean;
+    /** Retry once on a CSRF failure (419). Defaults to true for cookie mode. */
+    retryOnCsrfMismatch?: boolean;
+    /** Token storage (token mode). Default MemoryStorage. */
+    storage?: SanctumTokenStorage;
+    interceptors?: Interceptors;
+    /** Lifecycle event handlers (a declarative alternative to emitter.on). */
+    events?: Partial<{
+        [K in SanctumEventName]: SanctumEventHandler<SanctumUser, K>;
+    }>;
+    /** When a request returns 401: clear state + redirect to this path (false = don't). */
+    redirectIfUnauthenticated?: string | false;
+    /** Custom fetch implementation (default: globalThis.fetch). */
+    fetch?: typeof fetch;
+}
+/** Config after resolveConfig: all defaults filled in. */
+interface ResolvedSanctumConfig {
+    baseUrl: string;
+    mode: AuthMode;
+    origin: string | undefined;
+    features: Required<Omit<FeatureFlags, "twoFactorAuthentication" | "passkeys">> & {
+        twoFactorAuthentication: false | Required<TwoFactorFeature>;
+        passkeys: false | Required<PasskeysFeature>;
+    };
+    endpoints: SanctumEndpoints;
+    csrf: CsrfConfig;
+    redirect: RedirectConfig;
+    logLevel: LogLevel;
+    initialRequest: boolean;
+    retryOnCsrfMismatch: boolean;
+    storage: SanctumTokenStorage | undefined;
+    interceptors: Required<Interceptors>;
+    events: Partial<{
+        [K in SanctumEventName]: SanctumEventHandler<SanctumUser, K>;
+    }>;
+    redirectIfUnauthenticated: string | false;
+    fetch: typeof fetch;
+}
+interface LoginCredentials {
+    email?: string;
+    /** Supports backends that use `username` (config/fortify.php). */
+    username?: string;
+    password: string;
+    remember?: boolean;
+    [key: string]: unknown;
+}
+/** Discriminated login result — consumers MUST check `status` (so 2FA isn't missed). */
+type LoginResult<TUser = SanctumUser> = {
+    status: "authenticated";
+    user: TUser;
+} | {
+    status: "two-factor-required";
+};
+interface TwoFactorChallengePayload {
+    code?: string;
+    recovery_code?: string;
+}
+interface RegisterPayload {
+    name?: string;
+    email?: string;
+    username?: string;
+    password?: string;
+    password_confirmation?: string;
+    [key: string]: unknown;
+}
+interface ForgotPasswordPayload {
+    email: string;
+    [key: string]: unknown;
+}
+/** Params from a Fortify email-verification link (`/email/verify/{id}/{hash}?expires&signature`). */
+interface VerifyEmailPayload {
+    id: string | number;
+    hash: string;
+    expires: string | number;
+    signature: string;
+}
+interface ResetPasswordPayload {
+    token: string;
+    email: string;
+    password: string;
+    password_confirmation: string;
+    [key: string]: unknown;
+}
+interface ConfirmPasswordPayload {
+    password: string;
+}
+interface UpdatePasswordPayload {
+    current_password: string;
+    password: string;
+    password_confirmation: string;
+    [key: string]: unknown;
+}
+
+interface SanctumRequestInit extends Omit<RequestInit, "body"> {
+    body?: BodyInit | null;
+    /** Shortcut: serialize to JSON + set content-type automatically. */
+    json?: unknown;
+}
+
+interface SanctumClient {
+    readonly config: ResolvedSanctumConfig;
+    /** Ensure the CSRF cookie is present (cookie mode). No-op in token mode. */
+    ensureCsrf(force?: boolean): Promise<void>;
+    /** Authenticated request → raw Response. Throws SanctumError on non-2xx. */
+    raw(path: string, init?: SanctumRequestInit): Promise<Response>;
+    /** Authenticated request → parsed JSON body. */
+    request<T>(path: string, init?: SanctumRequestInit): Promise<T>;
+}
+
+interface SanctumProviderProps<TUser = SanctumUser> {
+    config: SanctumConfig;
+    /**
+     * User prefetched on the server (getUser()). Seeds state to avoid hydration mismatch.
+     * `undefined` = not prefetched (fetched on the client when initialRequest is enabled);
+     * `null` = the server confirmed the user is not logged in.
+     */
+    initialUser?: TUser | null;
+    children: ReactNode;
+}
+declare function SanctumProvider<TUser = SanctumUser>({ config, initialUser, children, }: SanctumProviderProps<TUser>): react.JSX.Element;
+
+interface UseAuthResult<TUser = SanctumUser> {
+    user: TUser | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    login: (credentials: LoginCredentials) => Promise<LoginResult<TUser>>;
+    logout: () => Promise<void>;
+    refresh: () => Promise<TUser | null>;
+    register: (payload: RegisterPayload) => Promise<void>;
+    forgotPassword: (payload: ForgotPasswordPayload) => Promise<void>;
+    resetPassword: (payload: ResetPasswordPayload) => Promise<void>;
+    confirmPassword: (payload: ConfirmPasswordPayload) => Promise<void>;
+    confirmedPasswordStatus: () => Promise<boolean>;
+    updatePassword: (payload: UpdatePasswordPayload) => Promise<void>;
+    updateProfile: (payload: Record<string, unknown>) => Promise<void>;
+    resendEmailVerification: () => Promise<void>;
+    verifyEmail: (payload: VerifyEmailPayload) => Promise<void>;
+}
+/** Authentication & account state and actions (login, register, password, profile, email verification). */
+declare function useAuth<TUser = SanctumUser>(): UseAuthResult<TUser>;
+
+/** Reactive user (null when not authenticated). Cast via the generic. */
+declare function useUser<TUser = SanctumUser>(): TUser | null;
+
+interface UseApiOptions extends SanctumRequestInit {
+    /** Run automatically on mount / when the path changes (default true). */
+    enabled?: boolean;
+}
+interface UseApiResult<T> {
+    data: T | undefined;
+    error: SanctumError | null;
+    isLoading: boolean;
+    refetch: () => Promise<void>;
+}
+/**
+ * Authenticated fetch on the client. Minimal but sufficient for most cases;
+ * SWR/TanStack Query adapters can be built on top of `useSanctumContext().client`.
+ */
+declare function useApi<T = unknown>(path: string, options?: UseApiOptions): UseApiResult<T>;
+
+/**
+ * The authenticated HTTP client for imperative requests — i.e. CRUD beyond auth
+ * (create/update/delete or on-demand reads). `client.request<T>(path, { method, json })`
+ * returns parsed JSON; `client.raw(...)` returns the Response. It automatically attaches
+ * CSRF (cookie mode) or Bearer (token mode), the base URL, and credentials.
+ */
+declare function useClient(): SanctumClient;
+
+interface ResourceClient<T = unknown, TList = T[]> {
+    /** `GET {base}` */
+    list(init?: SanctumRequestInit): Promise<TList>;
+    /** `GET {base}/{id}` */
+    get(id: string | number, init?: SanctumRequestInit): Promise<T>;
+    /** `POST {base}` */
+    create(data: unknown, init?: SanctumRequestInit): Promise<T>;
+    /** `PUT {base}/{id}` */
+    update(id: string | number, data: unknown, init?: SanctumRequestInit): Promise<T>;
+    /** `PATCH {base}/{id}` */
+    patch(id: string | number, data: unknown, init?: SanctumRequestInit): Promise<T>;
+    /** `DELETE {base}/{id}` */
+    delete(id: string | number, init?: SanctumRequestInit): Promise<void>;
+}
+/**
+ * A typed REST resource over the authenticated client — convenience sugar for CRUD.
+ * Credentials (CSRF/cookie or Bearer) are attached automatically. `TList` defaults to
+ * `T[]`; set it (e.g. `{ data: T[]; meta: … }`) for paginated Laravel resources.
+ *
+ * ```ts
+ * const posts = useResource<Post>("/api/posts")
+ * await posts.list()             // GET    /api/posts
+ * await posts.create({ title })  // POST   /api/posts
+ * await posts.update(1, { title })// PUT   /api/posts/1
+ * await posts.delete(1)          // DELETE /api/posts/1
+ * ```
+ */
+declare function useResource<T = unknown, TList = T[]>(basePath: string): ResourceClient<T, TList>;
+
+interface UseMutationOptions<TData, TVars> {
+    /** Runs just before the request. Return `false` to cancel it. */
+    onBefore?: (vars: TVars) => boolean | void | Promise<boolean | void>;
+    onSuccess?: (data: TData, vars: TVars) => void;
+    onError?: (error: SanctumError, vars: TVars) => void;
+    /** Always runs after success or error (not when cancelled in onBefore). */
+    onFinish?: (vars: TVars) => void;
+}
+interface UseMutationResult<TData, TVars> {
+    /** Fire-and-forget (rejections are swallowed; read them from `error`). */
+    mutate: (vars: TVars) => void;
+    /** Awaitable; resolves with the data or throws the SanctumError. */
+    mutateAsync: (vars: TVars) => Promise<TData>;
+    isPending: boolean;
+    error: SanctumError | null;
+    data: TData | undefined;
+    reset: () => void;
+}
+/**
+ * A lightweight mutation hook (Inertia-style lifecycle) for imperative requests —
+ * pair it with `useClient` / `useResource`. Manages `isPending` / `error` / `data`
+ * and fires `onBefore` / `onSuccess` / `onError` / `onFinish`.
+ *
+ * ```tsx
+ * const { request } = useClient()
+ * const create = useMutation(
+ *   (vars: { title: string }) => request<Post>("/api/posts", { method: "POST", json: vars }),
+ *   { onSuccess: (post) => toast("Created"), onError: (e) => toast(e.message) },
+ * )
+ * <button disabled={create.isPending} onClick={() => create.mutate({ title })}>Save</button>
+ * ```
+ */
+declare function useMutation<TData = unknown, TVars = void>(mutationFn: (vars: TVars) => Promise<TData>, options?: UseMutationOptions<TData, TVars>): UseMutationResult<TData, TVars>;
+
+interface TwoFactorApi {
+    /** Complete the 2FA login (`POST /two-factor-challenge`, code / recovery_code). */
+    challenge(payload: TwoFactorChallengePayload): Promise<void>;
+    /** Enable 2FA (`POST /user/two-factor-authentication`). Requires password confirmation. */
+    enable(): Promise<void>;
+    /** Confirm 2FA with a code (`POST /user/confirmed-two-factor-authentication`). */
+    confirm(code: string): Promise<void>;
+    /** Disable 2FA (`DELETE /user/two-factor-authentication`). */
+    disable(): Promise<void>;
+    /** QR code SVG (`GET /user/two-factor-qr-code`). */
+    getQrCode(): Promise<{
+        svg: string;
+    }>;
+    /** Secret key (`GET /user/two-factor-secret-key`). */
+    getSecretKey(): Promise<{
+        secretKey: string;
+    }>;
+    /** Recovery codes (`GET /user/two-factor-recovery-codes`). */
+    getRecoveryCodes(): Promise<string[]>;
+    /** Regenerate recovery codes (`POST /user/two-factor-recovery-codes`). */
+    regenerateRecoveryCodes(): Promise<void>;
+}
+
+/**
+ * Two-factor API (Fortify): challenge during login + management (enable/confirm/disable,
+ * QR, recovery codes). `challenge()` automatically refreshes the identity on success.
+ */
+declare function useTwoFactor(): TwoFactorApi;
+
+interface PasskeyRegistration {
+    id: string;
+    name: string;
+}
+interface PasskeysApi {
+    /** Whether the browser supports passkeys (WebAuthn). */
+    isSupported(): Promise<boolean>;
+    /** Register a new passkey for the authenticated user. */
+    register(name: string): Promise<PasskeyRegistration>;
+    /** Passwordless login via passkey (auto-refreshes identity on success). */
+    login(): Promise<void>;
+    /** Confirm the session password via passkey. */
+    confirmPassword(): Promise<void>;
+    /** Delete a passkey (`DELETE /user/passkeys/{id}`). */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Passkeys API (interop with @laravel/passkeys). `login()` automatically refreshes
+ * the identity on success. Requires the `@laravel/passkeys` package in the consumer.
+ */
+declare function usePasskeys(): PasskeysApi;
+
+/** In-memory token storage (lost on reload). Default for token mode. */
+declare class MemoryStorage implements SanctumTokenStorage {
+    private token;
+    get(): string | null;
+    set(token: string): void;
+    remove(): void;
+}
+
+/** Token storage in localStorage. OPT-IN — vulnerable to XSS (see PRD §12). */
+declare class LocalStorage implements SanctumTokenStorage {
+    private readonly key;
+    constructor(key?: string);
+    private warnOnce;
+    get(): string | null;
+    set(token: string): void;
+    remove(): void;
+}
+
+interface CookieStorageOptions {
+    name?: string;
+    /** Cookie lifetime (seconds). Default 14 days. */
+    maxAge?: number;
+    /** Default `Strict` for a credential cookie. */
+    sameSite?: "Lax" | "Strict" | "None";
+    secure?: boolean;
+    path?: string;
+}
+/**
+ * Cookie-based token storage written by the client. NOTE: cookies written by
+ * JS CANNOT be HttpOnly. For true HttpOnly, set the cookie via a Route Handler/Server
+ * Action and then attach the Bearer on the server (catch-all proxy). This storage is for
+ * simple persistence, NOT a replacement for HttpOnly.
+ */
+declare class CookieTokenStorage implements SanctumTokenStorage {
+    private readonly name;
+    private readonly maxAge;
+    private readonly sameSite;
+    private readonly secure;
+    private readonly path;
+    constructor(options?: CookieStorageOptions);
+    private warnOnce;
+    get(): string | null;
+    set(token: string): void;
+    remove(): void;
+}
+
+export { ConfigError, CookieTokenStorage, LocalStorage, MemoryStorage, SanctumError, SanctumProvider, ValidationError, useApi, useAuth, useClient, useMutation, usePasskeys, useResource, useTwoFactor, useUser };
+export type { AuthMode, ConfirmPasswordPayload, CookieStorageOptions, FeatureFlags, ForgotPasswordPayload, Interceptors, LogLevel, LoginCredentials, LoginResult, PasskeyRegistration, PasskeysApi, RegisterPayload, RequestInterceptor, ResetPasswordPayload, ResourceClient, ResponseInterceptor, SanctumClient, SanctumConfig, SanctumEndpoints, SanctumErrorKind, SanctumProviderProps, SanctumRequestInit, SanctumTokenStorage, SanctumUser, TwoFactorApi, TwoFactorChallengePayload, UpdatePasswordPayload, UseApiOptions, UseApiResult, UseAuthResult, UseMutationOptions, UseMutationResult, VerifyEmailPayload };