@awsmbiz/inbis-api-client 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,747 @@
+import { Client, FetchOptions, FetchResponse } from "openapi-fetch";
+import { AuthClient } from "better-auth/client";
+import { AdminClientOptions, adminClient } from "better-auth/client/plugins";
+import { MediaType, PathsWithMethod } from "openapi-typescript-helpers";
+/** A permission declared in the app's code (`GET /api/admin/permissions`). */
+interface AdminPermission {
+  /** Dotted name, e.g. `notes.read`. */
+  name: string;
+  description: string;
+}
+/** A role (`GET /api/admin/roles`). */
+interface AdminRole {
+  id: string;
+  name: string;
+  description: string | null;
+  /** Declared in code: read-only (`409 SYSTEM_ROLE_IMMUTABLE`). */
+  system: boolean;
+  /** Permission names the role grants itself. */
+  permissions: string[];
+  /** IDs of the roles whose permissions this role also grants. */
+  inherits: string[];
+  /** Users assigned this role directly. */
+  userCount: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+/** A custom role's fields: all of them to create one, any of them to change one. */
+interface AdminRoleInput {
+  /** 1–64 characters, unique among roles ignoring case. */
+  name: string;
+  /** Up to 500 characters; `null` or `""` for none. */
+  description?: string | null;
+  permissions: readonly string[];
+  inherits?: readonly string[];
+}
+/** A role a user holds directly (`GET /api/admin/users/:userId/roles`). */
+interface AdminUserRole {
+  id: string;
+  name: string;
+  system: boolean;
+  assignedAt: Date;
+  /** The admin who assigned it, when known. */
+  assignedBy: string | null;
+}
+interface Init {
+  signal?: AbortSignal;
+}
+/** Role admin calls. Reads need the admin policy; changes also a recent sign-in (`403 SESSION_NOT_FRESH`). */
+interface RoleAdminClient {
+  permissions: {
+    list(init?: Init): Promise<{
+      items: AdminPermission[];
+    }>;
+  };
+  roles: {
+    /** System roles first, then by name. */
+    list(init?: Init): Promise<{
+      items: AdminRole[];
+    }>;
+    /** `404 ROLE_NOT_FOUND`. */
+    get(roleId: string, init?: Init): Promise<AdminRole>;
+    /**
+     * Refusals: `422 VALIDATION_FAILED` (`details.issues[{ path, message }]`), `422 UNKNOWN_PERMISSION`,
+     * `422 UNKNOWN_ROLE`, `422 ROLE_INHERITANCE_CYCLE`, `409 ROLE_NAME_TAKEN`.
+     */
+    create(input: AdminRoleInput): Promise<AdminRole>;
+    /** As `create`, plus `409 SYSTEM_ROLE_IMMUTABLE` and `404 ROLE_NOT_FOUND`. */
+    update(roleId: string, changes: Partial<AdminRoleInput>): Promise<AdminRole>;
+    /** Its assignments go with it. `409 ROLE_INHERITED` while another role inherits it, `409 SYSTEM_ROLE_IMMUTABLE`. */
+    delete(roleId: string): Promise<void>;
+  };
+  /** A user's directly assigned roles. Assigning and removing are idempotent and return the user's roles. */
+  userRoles: {
+    list(userId: string, init?: Init): Promise<{
+      items: AdminUserRole[];
+    }>;
+    /** `404 ROLE_NOT_FOUND` / `404 USER_NOT_FOUND`. */
+    assign(userId: string, roleId: string): Promise<{
+      items: AdminUserRole[];
+    }>;
+    unassign(userId: string, roleId: string): Promise<{
+      items: AdminUserRole[];
+    }>;
+  };
+}
+/** The admin dashboard's counts (`GET /api/admin/auth-stats`). */
+interface AuthAdminStats {
+  totalUsers: number;
+  /** Users active in the last 7 days (signed in, per the audit trail; or with a session used, without one). */
+  activeUsers7d: number;
+  /** Invitations neither accepted, revoked nor expired. */
+  pendingInvitations: number;
+  /** Failed sign-ins in the last 24 hours. */
+  failedSignIns24h: number;
+  generatedAt: Date;
+}
+/** One audit event (`GET /api/admin/audit-events`). */
+interface AuditEvent {
+  id: string;
+  /** Dotted action name, e.g. `auth.sign_in.failed`. */
+  action: string;
+  actorId: string | null;
+  /** e.g. `user:<id>`. */
+  subjectId: string | null;
+  occurredAt: Date;
+  requestId: string | null;
+  metadata: Record<string, unknown> | null;
+}
+/** Audit timeline filters and paging. `from` is inclusive, `to` exclusive. */
+interface AuditEventsQuery {
+  action?: string;
+  /** User ID of the actor. */
+  actor?: string;
+  /** e.g. `user:<id>`. */
+  subject?: string;
+  from?: Date;
+  to?: Date;
+  /** 1–200, default 50. */
+  limit?: number;
+  cursor?: string;
+}
+/** A user as the admin directory lists them (`GET /api/admin/users`). */
+interface AdminUserSummary {
+  id: string;
+  name: string;
+  email: string;
+  /** `email` is a phone-only user's placeholder, not an address: never show it as one. */
+  emailIsPlaceholder: boolean;
+  emailVerified: boolean;
+  phoneNumber: string | null;
+  role: "admin" | "user";
+  /** Banned now (an expired ban reads `false`). */
+  banned: boolean;
+  banReason: string | null;
+  /** When the ban ends; `null` for a permanent ban or no ban. */
+  banExpires: Date | null;
+  twoFactorEnabled: boolean;
+  createdAt: Date;
+}
+/** A way a user can sign in. */
+interface AdminUserSignInMethod {
+  kind: "password" | "phone" | "passkey" | "social";
+  /** `credential`, `phone-number`, `passkey`, or the OAuth provider's ID. */
+  providerId: string;
+  /** A passkey's name or the phone number, when there is one. */
+  label: string | null;
+  createdAt: Date | null;
+}
+/** One user in full (`GET /api/admin/users/:userId`). */
+interface AdminUserDetail extends AdminUserSummary {
+  phoneNumberVerified: boolean;
+  signInMethods: AdminUserSignInMethod[];
+  updatedAt: Date;
+}
+/** The directory's search, filters (all apply at once), sort and offset paging. */
+interface AdminUsersQuery {
+  /** Name, email or phone number contains this, ignoring case. */
+  search?: string;
+  role?: "admin" | "user";
+  banned?: boolean;
+  twoFactor?: boolean;
+  emailVerified?: boolean;
+  /** Default `createdAt` (newest first). */
+  sort?: "createdAt" | "name" | "email";
+  direction?: "asc" | "desc";
+  /** 1–100, default 25. */
+  limit?: number;
+  offset?: number;
+}
+interface AdminUsersPage {
+  users: AdminUserSummary[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+/** The admin routes, including the role admin API (`mountRoleAdmin` from `@awsmbiz/inbis-access-control/hono`). */
+interface AdminRoutesClient extends RoleAdminClient {
+  /** The dashboard counts. Administrators only. */
+  stats(init?: {
+    signal?: AbortSignal;
+  }): Promise<AuthAdminStats>;
+  auditEvents: {
+    /** Newest first. Pass the previous page's `nextCursor` as `cursor`, with the same filters. */
+    list(query?: AuditEventsQuery, init?: {
+      signal?: AbortSignal;
+    }): Promise<{
+      items: AuditEvent[];
+      nextCursor: string | null;
+    }>;
+  };
+  /** The user directory (`mountAuthUsers` from `@awsmbiz/inbis-auth/hono`). Administrators only. */
+  users: {
+    list(query?: AdminUsersQuery, init?: {
+      signal?: AbortSignal;
+    }): Promise<AdminUsersPage>;
+    /** `404 USER_NOT_FOUND` for an unknown ID. */
+    get(userId: string, init?: {
+      signal?: AbortSignal;
+    }): Promise<AdminUserDetail>;
+    /**
+     * Removes the user's authenticator and backup codes and signs them out
+     * everywhere (lost authenticator); audited. Needs a recent sign-in
+     * (`403 SESSION_NOT_FRESH`: wrap it in `withStepUp`); `400 CANNOT_RESET_OWN_TWO_FACTOR`
+     * for the caller's own account; `404 USER_NOT_FOUND`.
+     */
+    resetTwoFactor(userId: string): Promise<{
+      sessionsRevoked: number;
+    }>;
+  };
+}
+interface ApiClientOptions {
+  /** Origin of the API (e.g. `https://app.example.com`). Defaults to the page's own origin. */
+  baseUrl?: string;
+  /** Custom `fetch` (tests, SSR). */
+  fetch?: (request: Request) => Promise<Response>;
+  /** Headers sent with every call. */
+  headers?: Record<string, string>;
+}
+/**
+ * A typed client for an app's routes; `Paths` is the `paths` type
+ * `openapi-typescript` generates. Failed calls reject with an {@link ApiError}
+ * (so `data` is set whenever a call resolves).
+ */
+type ApiClient<Paths extends object> = Client<Paths>;
+/** Creates the typed client for the app's routes (see the README for generating `Paths`). */
+export declare function createApiClient<Paths extends object>(options?: ApiClientOptions): ApiClient<Paths>;
+/**
+ * One error type for every failed call: app routes (the platform envelope
+ * `{ error: { code, message, requestId, details? } }`) and auth routes
+ * (Better Auth's `{ code, message, details? }`).
+ */
+/** Codes the platform returns that callers commonly branch on. Any other server code passes through as is. */
+export declare const API_ERROR_CODES: {
+  /** No response: offline, DNS, CORS or the server is unreachable (`status` 0). */
+  readonly NETWORK_ERROR: "NETWORK_ERROR";
+  /** Sign in again with one of `details.allowedMethods` (see {@link ApiError.requirement}). */
+  readonly STEP_UP_REQUIRED: "STEP_UP_REQUIRED";
+  /** Complete two-factor authentication (or enrol an authenticator) to continue. */
+  readonly TWO_FACTOR_REQUIRED: "TWO_FACTOR_REQUIRED";
+  /** The action needs a recent sign-in. */
+  readonly SESSION_NOT_FRESH: "SESSION_NOT_FRESH";
+  /** The session has ended. */
+  readonly SESSION_EXPIRED: "SESSION_EXPIRED";
+  /** A settings change would leave no administrator able to use the admin area. */
+  readonly ADMIN_LOCKOUT: "ADMIN_LOCKOUT";
+  /** The runtime auth settings changed since they were loaded (a stale-version conflict). */
+  readonly SETTINGS_VERSION_CONFLICT: "SETTINGS_VERSION_CONFLICT";
+  readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+  readonly RATE_LIMITED: "RATE_LIMITED";
+  readonly UNAUTHORIZED: "UNAUTHORIZED";
+  readonly FORBIDDEN: "FORBIDDEN";
+  readonly NOT_FOUND: "NOT_FOUND";
+  readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+  /** A failed response without a recognisable code. */
+  readonly REQUEST_FAILED: "REQUEST_FAILED";
+};
+/**
+ * What a route asks of the session before it can be used: complete 2FA, or
+ * sign in again with one of `allowedMethods`.
+ */
+type AccessRequirement = {
+  kind: "two-factor";
+} | {
+  kind: "step-up";
+  allowedMethods: string[];
+};
+declare const API_ERROR: unique symbol;
+interface ApiErrorOptions {
+  status: number;
+  code: string;
+  message: string;
+  requestId?: string | null;
+  details?: unknown;
+  cause?: unknown;
+}
+/** A failed call. `code` is stable and machine-readable; `message` is safe to show. */
+export declare class ApiError extends Error {
+  /** HTTP status; `0` when no response arrived (`NETWORK_ERROR`). */
+  readonly status: number;
+  readonly code: string;
+  /** The server's request ID (app routes), for support and logs. */
+  readonly requestId: string | null;
+  /** Extra caller-safe information from the server, e.g. `{ allowedMethods }` or validation issues. */
+  readonly details: unknown;
+  readonly [API_ERROR] = true;
+  constructor(options: ApiErrorOptions);
+  /** The server could not be reached. */
+  get isNetworkError(): boolean;
+  /**
+   * A stale-version conflict: someone else changed the resource since it was
+   * loaded (`409` with a `…VERSION_CONFLICT` code, e.g. `SETTINGS_VERSION_CONFLICT`).
+   * Reload and let the user reapply their change.
+   */
+  get isVersionConflict(): boolean;
+  /** What the session needs before retrying (`TWO_FACTOR_REQUIRED` / `STEP_UP_REQUIRED`), else `null`. */
+  get requirement(): AccessRequirement | null;
+  /** Reads a failed response's body (either error shape). Consumes the body. */
+  static fromResponse(response: Response): Promise<ApiError>;
+  /** Builds the error from a status and a parsed body (either error shape, or anything else). */
+  static fromBody(status: number, body: unknown): ApiError;
+  /** No response arrived. */
+  static network(cause?: unknown): ApiError;
+}
+/** True for any {@link ApiError}, including instances from another copy of this package. */
+export declare function isApiError(value: unknown): value is ApiError;
+type RegistrationMode = "open" | "invite-only" | "admin-only" | "closed";
+type AuthMethodName = "password" | "phone-otp";
+type BreachedPasswordCheck = "fail-open" | "off";
+interface RateLimitRule {
+  /** Seconds. */
+  window: number;
+  max: number;
+}
+type RateLimitKey = "default" | "signIn" | "passwordReset" | "otp" | "twoFactor";
+/** Resolved, secret-free settings (`effective` and `appConfig` of {@link AuthSettingsView}). Durations in seconds. */
+interface AuthSettingsSnapshot {
+  registration: {
+    mode: RegistrationMode;
+    requireEmailVerification: boolean;
+  };
+  methods: {
+    emailPassword: boolean;
+    phoneOtp: boolean;
+  };
+  /** `null` when email + password is off in the app config. `maxLength` is read-only. */
+  password: {
+    minLength: number;
+    maxLength: number;
+    breachedCheck: BreachedPasswordCheck;
+  } | null;
+  policies: {
+    admin: {
+      allowedMethods: AuthMethodName[];
+      twoFactor: "required";
+    };
+    user: {
+      twoFactor: "optional" | "required";
+    };
+  };
+  sessions: {
+    admin: {
+      idle: number;
+      max: number;
+      freshAge: number;
+    };
+    user: {
+      expiresIn: number;
+      freshAge: number;
+      rememberMe: boolean;
+    };
+  };
+  rateLimit: Partial<Record<RateLimitKey, RateLimitRule>>;
+  /** `null` when phone OTP is off in the app config. */
+  phoneOtp: {
+    perNumberLimit: RateLimitRule;
+    perIpLimit: RateLimitRule;
+    dailySmsCap: number;
+  } | null;
+}
+/** The stored overrides: they can only narrow the app config. Absent means "as the app config says". */
+interface RuntimeAuthSettings {
+  registration?: {
+    mode?: RegistrationMode;
+    requireEmailVerification?: boolean;
+  };
+  methods?: {
+    emailPassword?: boolean;
+    phoneOtp?: boolean;
+  };
+  password?: {
+    minLength?: number;
+    breachedCheck?: BreachedPasswordCheck;
+  };
+  policies?: {
+    admin?: {
+      allowedMethods?: AuthMethodName[];
+    };
+    user?: {
+      twoFactor?: "optional" | "required";
+    };
+  };
+  sessions?: {
+    admin?: {
+      idle?: number;
+      max?: number;
+      freshAge?: number;
+    };
+    user?: {
+      expiresIn?: number;
+      freshAge?: number;
+      rememberMe?: boolean;
+    };
+  };
+  rateLimit?: Partial<Record<RateLimitKey, RateLimitRule>>;
+  phoneOtp?: {
+    perNumberLimit?: RateLimitRule;
+    perIpLimit?: RateLimitRule;
+    dailySmsCap?: number;
+  };
+}
+/** A JSON merge patch of {@link RuntimeAuthSettings}: `null` removes an override (back to the app config). */
+type AuthSettingsPatch = { [K in keyof RuntimeAuthSettings]?: { [F in keyof NonNullable<RuntimeAuthSettings[K]>]?: unknown; } | null; };
+/** `GET /api/admin/auth-settings`. */
+interface AuthSettingsView {
+  /** Send it back with a change; a stale one is refused with `409 SETTINGS_VERSION_CONFLICT`. */
+  version: number;
+  updatedAt: string | null;
+  updatedBy: string | null;
+  overrides: RuntimeAuthSettings;
+  /** What applies now. */
+  effective: AuthSettingsSnapshot;
+  /** The app config: the widest each setting can be. */
+  appConfig: AuthSettingsSnapshot;
+}
+/** One method or service in `GET /api/admin/auth-providers/status`. Never a secret. */
+interface AuthProviderStatus {
+  id: string;
+  kind: "method" | "service";
+  /** On in the app config (for services: its secret or sender is present). */
+  configured: boolean;
+  /** On now, after the runtime settings. */
+  enabled: boolean;
+}
+interface AuthSettingsAdminClient {
+  get(): Promise<AuthSettingsView>;
+  /**
+   * Changes the overrides. Refusals: `409 SETTINGS_VERSION_CONFLICT` (`isVersionConflict`),
+   * `422 INVALID_SETTINGS` (`details.issues[{ path, code, message }]`), `422 ADMIN_LOCKOUT`
+   * (`details.paths` names the settings that cause it), `403 TWO_FACTOR_NOT_ENROLLED`,
+   * `403 SESSION_NOT_FRESH`.
+   */
+  update(input: {
+    version: number;
+    settings: AuthSettingsPatch;
+  }): Promise<AuthSettingsView>;
+}
+interface AuthProvidersAdminClient {
+  status(): Promise<{
+    items: AuthProviderStatus[];
+  }>;
+}
+interface AuthAdminClientOptions {
+  /** Origin of the API. Defaults to the page's own origin. */
+  baseURL?: string;
+  /** Must match the server's `app.basePath`. Default `/api/auth`. */
+  basePath?: string;
+  /** Where the app mounts the admin app routes (stats, audit events, auth settings, provider status). Default `/api/admin`. */
+  adminPath?: string;
+  /** Custom `fetch` (tests, SSR). */
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+/** Better Auth's browser client with the admin plugin; methods resolve to data or reject with an {@link ApiError}. */
+type BetterAuthAdminClient = AuthClient<{
+  plugins: [ReturnType<typeof adminClient<AdminClientOptions>>];
+  fetchOptions: {
+    throw: true;
+  };
+}>;
+type InvitationStatus = "pending" | "accepted" | "revoked" | "expired";
+/** An invitation as the admin API returns it (never its token). Dates are revived by Better Auth's client. */
+interface Invitation {
+  id: string;
+  kind: string;
+  /** Exactly one of `email` and `phoneNumber` is set. */
+  email: string | null;
+  phoneNumber: string | null;
+  role: "admin" | "user";
+  status: InvitationStatus;
+  expiresAt: Date;
+  createdAt: Date;
+  invitedBy: string | null;
+  acceptedAt: Date | null;
+  acceptedUserId: string | null;
+  revokedAt: Date | null;
+}
+/** `@awsmbiz/inbis-auth`'s invitation admin endpoints. Refusals reject with an {@link ApiError}. */
+interface InvitationsAdminClient {
+  /**
+   * Invites by email or by phone (E.164), as `role` (default `user`). Errors include
+   * `INVALID_EMAIL`, `INVALID_PHONE_NUMBER`, `USER_ALREADY_EXISTS` and `INVITATION_ALREADY_PENDING`.
+   */
+  create(input: {
+    email: string;
+    role?: "admin" | "user";
+  } | {
+    phoneNumber: string;
+    role?: "admin" | "user";
+  }): Promise<{
+    invitation: Invitation;
+  }>;
+  /**
+   * Newest first. Pass the previous page's `nextCursor` as `cursor`, `status` for only
+   * invitations with that status (`INVALID_INVITATION_STATUS` for anything else) and
+   * `role` for only those inviting as that role (`INVALID_ROLE` for anything else).
+   */
+  list(input?: {
+    limit?: number;
+    cursor?: string;
+    status?: InvitationStatus;
+    role?: "admin" | "user";
+  }): Promise<{
+    items: Invitation[];
+    nextCursor: string | null;
+  }>;
+  /** Sends a fresh link; the expiry restarts. `INVITATION_NOT_PENDING` once accepted or revoked. */
+  resend(input: {
+    invitationId: string;
+  }): Promise<{
+    invitation: Invitation;
+  }>;
+  /** `INVITATION_NOT_PENDING` once accepted or revoked. */
+  revoke(input: {
+    invitationId: string;
+  }): Promise<{
+    invitation: Invitation;
+  }>;
+}
+/** Who a new user is: an email address, or a phone number (E.164; a phone-only user signs in with codes). */
+type CreateUserInput = {
+  name: string;
+  role?: "admin" | "user";
+  /** Email users only. Without one, the user sets a password with "Forgot password". */
+  password?: string;
+} & ({
+  email: string;
+  phoneNumber?: never;
+} | {
+  phoneNumber: string;
+  email?: never;
+});
+/** A created user, as Better Auth's admin plugin returns it (dates revived). */
+interface CreatedUser {
+  id: string;
+  name: string;
+  email: string;
+  role?: string | null;
+  createdAt: Date;
+}
+/**
+ * Admin user actions that `@awsmbiz/inbis-auth` adds to Better Auth's admin plugin.
+ * The rest (set role, ban, unban, revoke every session, remove) are on
+ * `admin`. Refusals reject with an {@link ApiError}.
+ */
+interface UserActionsAdminClient {
+  /**
+   * Creates a user by email or by phone number. Errors include
+   * `USER_ALREADY_EXISTS`, `INVALID_PHONE_NUMBER`, `PHONE_COUNTRY_NOT_ALLOWED`
+   * and `PHONE_SIGN_IN_UNAVAILABLE`.
+   */
+  create(input: CreateUserInput): Promise<{
+    user: CreatedUser;
+  }>;
+  /**
+   * Signs a user out of one session, by the session's ID (the listing never
+   * carries session tokens). `404 SESSION_NOT_FOUND` once it has ended.
+   */
+  revokeSession(input: {
+    userId: string;
+    sessionId: string;
+  }): Promise<{
+    success: boolean;
+  }>;
+}
+/**
+ * Auth admin calls: Better Auth's admin plugin, `@awsmbiz/inbis-auth`'s invitation
+ * endpoints, and the admin app routes (`stats`, `auditEvents`).
+ */
+interface AuthAdminClient extends AdminRoutesClient {
+  /** Better Auth's admin plugin (`listUsers`, `createUser`, `setRole`, `banUser`, `unbanUser`, …). */
+  admin: BetterAuthAdminClient["admin"];
+  invitations: InvitationsAdminClient;
+  /** User actions beyond Better Auth's: create by phone number, revoke a session by ID. */
+  userActions: UserActionsAdminClient;
+  /** Runtime auth settings (`GET`/`PATCH /api/admin/auth-settings`). */
+  settings: AuthSettingsAdminClient;
+  /** Method and provider status (`GET /api/admin/auth-providers/status`). */
+  providers: AuthProvidersAdminClient;
+}
+/** Creates the client for auth admin endpoints. */
+export declare function createAuthAdminClient(options?: AuthAdminClientOptions): AuthAdminClient;
+/** Anything that can invalidate queries by key prefix (TanStack's `QueryClient`). */
+interface QueryInvalidator {
+  invalidateQueries(filters: {
+    queryKey: readonly unknown[];
+  }): Promise<unknown>;
+}
+/** Invalidates every query whose key starts with one of `keys`. */
+export declare function invalidateQueries(queryClient: QueryInvalidator, ...keys: (readonly unknown[])[]): Promise<void>;
+/** The key of an app-route query: `["api", path]`, or `["api", path, params]`. */
+export declare function apiQueryKey<Path extends string>(path: Path): readonly ["api", Path];
+export declare function apiQueryKey<Path extends string, Params>(path: Path, params: Params): readonly ["api", Path, Params];
+/** Invalidates every query of the given app-route paths (any params), or of all app routes when none is given. */
+export declare function invalidateApi(queryClient: QueryInvalidator, ...paths: string[]): Promise<void>;
+type GetOperation<P, Path> = Path extends keyof P ? P[Path] extends {
+  get: infer Operation extends Record<string | number, unknown>;
+} ? Operation : never : never;
+type GetInit<P, Path> = FetchOptions<GetOperation<P, Path>>;
+type GetData<P, Path, Init> = NonNullable<FetchResponse<GetOperation<P, Path>, Init, MediaType>["data"]>;
+type RequiredKeysOf<T> = { [K in keyof T]-?: object extends Pick<T, K> ? never : K; }[keyof T];
+type InitParam<Init> = RequiredKeysOf<Init> extends never ? [Init?] : [Init];
+interface ApiQueryOptions<Key extends readonly unknown[], Data> {
+  queryKey: Key;
+  queryFn: (context: {
+    signal: AbortSignal;
+  }) => Promise<Data>;
+}
+/**
+ * Query options for a `GET` app route: keyed by path and `params` (see
+ * {@link apiQueryKey}), failing with an `ApiError`:
+ * `useQuery(apiQueryOptions(api, "/v1/notes/{id}", { params: { path: { id } } }))`.
+ */
+export declare function apiQueryOptions<P extends object, Path extends PathsWithMethod<P, "get"> & string, Init extends GetInit<P, Path>>(client: ApiClient<P>, path: Path, ...[init]: InitParam<Init>): ApiQueryOptions<readonly ["api", Path] | readonly ["api", Path, unknown], GetData<P, Path, Init>>;
+type Admin = AuthAdminClient["admin"];
+/** Better Auth's `listUsers` query (search, filter, sort, `limit`/`offset`). */
+type ListUsersQuery = NonNullable<Parameters<Admin["listUsers"]>[0]>["query"];
+interface ListInvitationsQuery {
+  limit?: number;
+  cursor?: string;
+  status?: InvitationStatus;
+  role?: "admin" | "user";
+}
+/**
+ * Query keys for auth admin data. Invalidate `users()` after any change to a
+ * user (it covers lists, details and sessions), `invitations()` after any
+ * invitation change, `stats()` after anything the dashboard counts, or `all`
+ * for everything.
+ */
+export declare const authAdminKeys: {
+  all: readonly ["auth-admin"];
+  users: () => readonly ["auth-admin", "users"];
+  userList: (query: ListUsersQuery) => readonly ["auth-admin", "users", "list", {
+    searchValue?: string | undefined;
+    searchField?: "name" | "email" | undefined;
+    searchOperator?: "contains" | "starts_with" | "ends_with" | undefined;
+    limit?: string | number | undefined;
+    offset?: string | number | undefined;
+    sortBy?: string | undefined;
+    sortDirection?: "asc" | "desc" | undefined;
+    filterField?: string | undefined;
+    filterValue?: string | number | boolean | string[] | number[] | undefined;
+    filterOperator?: "in" | "contains" | "starts_with" | "ends_with" | "lte" | "eq" | "ne" | "lt" | "gt" | "gte" | "not_in" | undefined;
+  }];
+  user: (userId: string) => readonly ["auth-admin", "users", "detail", string];
+  userSessions: (userId: string) => readonly ["auth-admin", "users", "detail", string, "sessions"];
+  /** The admin directory (`users.list`: combined filters). */
+  userDirectory: (query: AdminUsersQuery) => readonly ["auth-admin", "users", "directory", AdminUsersQuery];
+  /** One user's profile, sign-in methods and 2FA status (`users.get`). */
+  userProfile: (userId: string) => readonly ["auth-admin", "users", "detail", string, "profile"];
+  invitations: () => readonly ["auth-admin", "invitations"];
+  invitationList: (query: ListInvitationsQuery) => readonly ["auth-admin", "invitations", "list", ListInvitationsQuery];
+  settings: () => readonly ["auth-admin", "settings"];
+  providerStatus: () => readonly ["auth-admin", "providers", "status"];
+  stats: () => readonly ["auth-admin", "stats"];
+  auditEvents: () => readonly ["auth-admin", "audit-events"];
+  auditEventList: (query: AuditEventsQuery) => readonly ["auth-admin", "audit-events", "list", AuditEventsQuery];
+  /** The declared permission catalogue (`permissions.list`). */
+  permissions: () => readonly ["auth-admin", "permissions"];
+  /** Every role query: invalidate after a role change or an assignment (it changes `userCount`). */
+  roles: () => readonly ["auth-admin", "roles"];
+  roleList: () => readonly ["auth-admin", "roles", "list"];
+  role: (roleId: string) => readonly ["auth-admin", "roles", "detail", string];
+  /** A user's assigned roles (`userRoles.list`); covered by `users()`. */
+  userRoles: (userId: string) => readonly ["auth-admin", "users", "detail", string, "roles"];
+};
+/** Query options for auth admin data, keyed by {@link authAdminKeys}. */
+export declare function authAdminQueries(auth: AuthAdminClient): {
+  userList: (query: ListUsersQuery) => {
+    queryKey: readonly ["auth-admin", "users", "list", {
+      searchValue?: string | undefined;
+      searchField?: "name" | "email" | undefined;
+      searchOperator?: "contains" | "starts_with" | "ends_with" | undefined;
+      limit?: string | number | undefined;
+      offset?: string | number | undefined;
+      sortBy?: string | undefined;
+      sortDirection?: "asc" | "desc" | undefined;
+      filterField?: string | undefined;
+      filterValue?: string | number | boolean | string[] | number[] | undefined;
+      filterOperator?: "in" | "contains" | "starts_with" | "ends_with" | "lte" | "eq" | "ne" | "lt" | "gt" | "gte" | "not_in" | undefined;
+    }];
+    queryFn: ({ signal }: {
+      signal: AbortSignal;
+    }) => Promise<{
+      users: import("better-auth/plugins").UserWithRole[];
+      total: number;
+    }>;
+  };
+  user: (userId: string) => {
+    queryKey: readonly ["auth-admin", "users", "detail", string];
+    queryFn: ({ signal }: {
+      signal: AbortSignal;
+    }) => Promise<import("better-auth/plugins").UserWithRole>;
+  };
+  userSessions: (userId: string) => {
+    queryKey: readonly ["auth-admin", "users", "detail", string, "sessions"];
+    queryFn: ({ signal }: {
+      signal: AbortSignal;
+    }) => Promise<{
+      sessions: import("better-auth/plugins").SessionWithImpersonatedBy[];
+    }>;
+  };
+  userDirectory: (query: AdminUsersQuery) => {
+    queryKey: readonly ["auth-admin", "users", "directory", AdminUsersQuery];
+    queryFn: ({ signal }: {
+      signal: AbortSignal;
+    }) => Promise<AdminUsersPage>;
+  };
+  userProfile: (userId: string) => {
+    queryKey: readonly ["auth-admin", "users", "detail", string, "profile"];
+    queryFn: ({ signal }: {
+      signal: AbortSignal;
+    }) => Promise<AdminUserDetail>;
+  };
+  invitationList: (query: ListInvitationsQuery) => {
+    queryKey: readonly ["auth-admin", "invitations", "list", ListInvitationsQuery];
+    queryFn: () => Promise<{
+      items: Invitation[];
+      nextCursor: string | null;
+    }>;
+  };
+  settings: () => {
+    queryKey: readonly ["auth-admin", "settings"];
+    queryFn: () => Promise<AuthSettingsView>;
+  };
+  providerStatus: () => {
+    queryKey: readonly ["auth-admin", "providers", "status"];
+    queryFn: () => Promise<{
+      items: AuthProviderStatus[];
+    }>;
+  };
+  stats: () => {
+    queryKey: readonly ["auth-admin", "stats"];
+    queryFn: ({ signal }: {
+      signal: AbortSignal;
+    }) => Promise<AuthAdminStats>;
+  };
+  auditEventList: (query: AuditEventsQuery) => {
+    queryKey: readonly ["auth-admin", "audit-events", "list", AuditEventsQuery];
+    queryFn: ({ signal }: {
+      signal: AbortSignal;
+    }) => Promise<{
+      items: AuditEvent[];
+      nextCursor: string | null;
+    }>;
+  };
+};
+export type { AccessRequirement, AdminPermission, AdminRole, AdminRoleInput, AdminRoutesClient, AdminUserDetail, AdminUserRole, AdminUserSignInMethod, AdminUserSummary, AdminUsersPage, AdminUsersQuery, ApiClient, ApiClientOptions, ApiErrorOptions, ApiQueryOptions, AuditEvent, AuditEventsQuery, AuthAdminClient, AuthAdminClientOptions, AuthAdminStats, AuthMethodName, AuthProviderStatus, AuthProvidersAdminClient, AuthSettingsAdminClient, AuthSettingsPatch, AuthSettingsSnapshot, AuthSettingsView, BetterAuthAdminClient, BreachedPasswordCheck, CreateUserInput, CreatedUser, Invitation, InvitationStatus, InvitationsAdminClient, ListInvitationsQuery, ListUsersQuery, QueryInvalidator, RateLimitKey, RateLimitRule, RegistrationMode, RoleAdminClient, RuntimeAuthSettings, UserActionsAdminClient };
+//# sourceMappingURL=index.d.ts.map