@bunbase-ae/js 1.0.0

package/src/admin.ts

@@ -0,0 +1,912 @@
+// AdminClient — typed access to all /admin/* endpoints.
+//
+// Accessible via client.admin when the BunBaseClient is initialized with
+// adminSecret, or when the authenticated user has the "admin" role.
+//
+// Sub-namespaces:
+//   client.admin.users       — user management
+//   client.admin.sessions    — session management
+//   client.admin.collections — collection + record + schema + index + FTS management
+//   client.admin.relations   — collection relations
+//   client.admin.storage     — files + buckets
+//   client.admin.settings    — server settings, email templates, config, audit
+//   client.admin.backups     — backup / restore
+//   client.admin.system      — health + stats
+
+import type { HttpClient } from "./http";
+
+// ─── Shared admin types ───────────────────────────────────────────────────────
+
+export interface AdminUser {
+  id: string;
+  email: string;
+  created_at: number;
+  updated_at: number;
+  is_verified: boolean;
+  session_count: number;
+  role: string | null;
+  metadata: Record<string, unknown>;
+}
+
+export interface AdminSession {
+  id: string;
+  user_id: string;
+  user_email: string | null;
+  expires_at: number;
+  created_at: number;
+  device_hint: string | null;
+}
+
+export interface AdminApiKey {
+  id: string;
+  name: string;
+  created_at: number;
+  last_used_at: number | null;
+}
+
+export interface ImpersonationResult {
+  access_token: string;
+  expires_in: number;
+  user_id: string;
+}
+
+export interface UpdateUserParams {
+  email?: string;
+  is_verified?: boolean;
+  role?: string | null;
+  metadata?: Record<string, unknown>;
+}
+
+export type AccessRule = "public" | "authenticated" | "owner" | "disabled" | { role: string };
+
+export interface CollectionRules {
+  read: AccessRule;
+  create: AccessRule;
+  update: AccessRule;
+  delete: AccessRule;
+}
+
+export interface AdminFieldRule {
+  field: string;
+  required?: boolean;
+  min?: number;
+  max?: number;
+  regex?: string;
+  enum?: unknown[];
+}
+
+export interface CollectionMeta {
+  name: string;
+  rules: CollectionRules;
+  field_rules: AdminFieldRule[];
+  created_at: number;
+  schema_version: number;
+  /** Webhook URL for async event delivery. Null means no webhook configured. */
+  webhook_url: string | null;
+  /** Whether an HMAC-SHA256 signing secret is configured. Secret value is write-only. */
+  has_webhook_secret: boolean;
+  /** Event filter. Null = all events. Array = only listed event types (create/update/delete). */
+  webhook_events: string[] | null;
+}
+
+export interface AdminRecord {
+  _id: string;
+  _created_at: number;
+  _updated_at: number;
+  _owner_id: string | null;
+  [key: string]: unknown;
+}
+
+export interface AdminListResult<T> {
+  items: T[];
+  total?: number;
+  /** @deprecated Present only when `page` was explicitly requested. */
+  page?: number;
+  limit: number;
+  /** Cursor for the next page. Null when no more pages or in non-keyset mode. */
+  next_cursor: string | null;
+}
+
+export interface ColumnInfo {
+  name: string;
+  type: string;
+  non_null_count: number | null;
+  is_system: boolean;
+}
+
+export interface CollectionStats {
+  row_count: number;
+  last_write: number | null;
+}
+
+export interface IndexInfo {
+  name: string;
+  column: string;
+  is_system: boolean;
+}
+
+export type RelationType = "one" | "many" | "many_via";
+export type RelationOnDelete = "none" | "cascade" | "set_null";
+
+export interface Relation {
+  id: string;
+  from_col: string;
+  from_field: string;
+  to_col: string;
+  type: RelationType;
+  via_col: string | null;
+  via_from: string | null;
+  via_to: string | null;
+  on_delete: RelationOnDelete;
+  created_at: number;
+}
+
+export interface CollectionIntrospection {
+  name: string;
+  columns: ColumnInfo[];
+  indexes: IndexInfo[];
+  relations: Relation[];
+  rules: CollectionRules;
+  field_rules: AdminFieldRule[];
+  fts_enabled: boolean;
+  webhook: {
+    url: string | null;
+    signing: boolean;
+    events: string[] | null;
+  };
+  stats: { row_count: number; last_write: number | null };
+  schema_version: number;
+  created_at: number;
+}
+
+export interface CreateRelationParams {
+  from_col: string;
+  from_field: string;
+  to_col: string;
+  type: RelationType;
+  via_col?: string;
+  via_from?: string;
+  via_to?: string;
+  on_delete?: RelationOnDelete;
+}
+
+export interface AdminStoredFile {
+  id: string;
+  key: string;
+  bucket: string;
+  filename: string | null;
+  collection: string | null;
+  record_id: string | null;
+  owner_id: string | null;
+  owner_email?: string | null;
+  size: number;
+  mime_type: string;
+  is_public: boolean;
+  created_at: number;
+}
+
+export type BucketAccessRule = "public" | "authenticated" | "owner" | "disabled";
+
+export interface StorageBucket {
+  name: string;
+  access_read: BucketAccessRule;
+  access_write: BucketAccessRule;
+  allowed_mimes: string[] | null;
+  max_size_bytes: number | null;
+  cdn_url: string | null;
+  created_at: number;
+}
+
+export interface ServerSettings {
+  auto_create_buckets?: boolean;
+  auto_create_collections?: boolean;
+  storage_cdn_url?: string;
+  maintenance_mode?: boolean;
+  log_level?: "debug" | "info" | "warn" | "error" | "off";
+  registration_open?: boolean;
+  single_session_mode?: boolean;
+  require_email_verification?: boolean;
+  lockout_max_attempts?: number;
+  lockout_duration_ms?: number;
+  access_token_ttl_seconds?: number;
+  refresh_token_ttl_days?: number;
+  auth_password_enabled?: boolean;
+  auth_magic_link_enabled?: boolean;
+  auth_totp_enabled?: boolean;
+  auth_oauth_enabled?: boolean;
+  auth_api_keys_enabled?: boolean;
+  oauth_github_client_id?: string;
+  oauth_github_client_secret?: string;
+  oauth_google_client_id?: string;
+  oauth_google_client_secret?: string;
+  oauth_oidc_issuer?: string;
+  oauth_oidc_client_id?: string;
+  oauth_oidc_client_secret?: string;
+  oauth_oidc_scopes?: string;
+  app_name?: string;
+  app_url?: string;
+  logo_url?: string;
+  support_email?: string;
+  primary_color?: string;
+  rate_limit_public_reads?: number;
+  rate_limit_auth?: number;
+  rate_limit_authenticated?: number;
+  rate_limit_admin?: number;
+  rate_limit_file_upload?: number;
+  email_provider?: "console" | "resend" | "smtp";
+  email_from?: string;
+  resend_api_key?: string;
+  smtp_host?: string;
+  smtp_port?: number;
+  smtp_user?: string;
+  smtp_pass?: string;
+  smtp_secure?: boolean;
+  backup_auto_enabled?: boolean;
+  backup_interval_minutes?: number;
+  backup_keep_recent_hours?: number;
+  backup_keep_daily_days?: number;
+  backup_compression_format?: "gzip" | "zstd";
+  backup_compression_level?: number;
+  backup_remote_type?: "none" | "s3" | "rsync";
+  backup_remote_s3_endpoint?: string;
+  backup_remote_s3_bucket?: string;
+  backup_remote_s3_prefix?: string;
+  backup_remote_s3_region?: string;
+  backup_remote_s3_access_key_id?: string;
+  backup_remote_s3_secret_access_key?: string;
+  backup_remote_rsync_dest?: string;
+  server_timezone?: string;
+  server_locale?: string;
+  access_log_max_rows?: number;
+  app_log_max_rows?: number;
+  access_log_max_age_days?: number;
+  app_log_max_age_days?: number;
+}
+
+export type TemplateName = "password_reset" | "email_verification" | "magic_link";
+
+export interface EmailTemplate {
+  subject: string;
+  html: string;
+  text: string;
+  is_default?: boolean;
+}
+
+export interface ConfigResponse {
+  effective: Record<string, string | null>;
+  overrides: Record<string, string | null>;
+}
+
+export interface SettingsAuditEntry {
+  id: string;
+  key: string;
+  old_value: unknown;
+  new_value: unknown;
+  changed_by: string;
+  changed_at: number;
+}
+
+export interface BackupFile {
+  filename: string;
+  size: number;
+  created_at: string;
+}
+
+export interface HealthResponse {
+  status: "ok" | "degraded";
+  version: string;
+  bun_version: string;
+  uptime_ms: number;
+  db: "ok" | "error";
+  db_provider: "sqlite" | "postgres";
+  redis: "ok" | "error" | "disabled";
+}
+
+export interface MinuteBucket {
+  minute: number;
+  requests: number;
+  errors: number;
+}
+
+export interface StatsResponse {
+  uptime_ms: number;
+  memory: { rss_mb: number; heap_used_mb: number };
+  pending_requests: number;
+  pending_websockets: number;
+  latency: { p50: number; p95: number; p99: number };
+  rpc: {
+    pending_high_water: number;
+    calls_by_method: Record<string, number>;
+  };
+  auth: {
+    outcomes: {
+      anonymous: number;
+      bearer_cache_hit: number;
+      bearer_cache_miss: number;
+      apikey_cache_hit: number;
+      apikey_cache_miss: number;
+    };
+  };
+  time_series: MinuteBucket[];
+}
+
+// ─── Sub-clients ──────────────────────────────────────────────────────────────
+
+class AdminUsersClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<AdminUser[]> {
+    const res = await this.http.request<{ items: AdminUser[] }>("GET", "/api/v1/admin/users");
+    return res.items;
+  }
+
+  async get(id: string): Promise<AdminUser> {
+    return this.http.request<AdminUser>("GET", `/api/v1/admin/users/${id}`);
+  }
+
+  async update(id: string, params: UpdateUserParams): Promise<AdminUser> {
+    return this.http.request<AdminUser>("PATCH", `/api/v1/admin/users/${id}`, { body: params });
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/admin/users/${id}`);
+  }
+
+  async setPassword(id: string, password: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("POST", `/api/v1/admin/users/${id}/set-password`, {
+      body: { password },
+    });
+  }
+
+  async listSessions(id: string): Promise<AdminSession[]> {
+    const res = await this.http.request<{ items: AdminSession[] }>(
+      "GET",
+      `/api/v1/admin/users/${id}/sessions`,
+    );
+    return res.items;
+  }
+
+  async listApiKeys(id: string): Promise<AdminApiKey[]> {
+    const res = await this.http.request<{ items: AdminApiKey[] }>(
+      "GET",
+      `/api/v1/admin/users/${id}/api-keys`,
+    );
+    return res.items;
+  }
+
+  async revokeApiKey(userId: string, keyId: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>(
+      "DELETE",
+      `/api/v1/admin/users/${userId}/api-keys/${keyId}`,
+    );
+  }
+
+  async impersonate(id: string): Promise<ImpersonationResult> {
+    return this.http.request<ImpersonationResult>("POST", `/api/v1/admin/users/${id}/impersonate`, {
+      body: {},
+    });
+  }
+}
+
+class AdminSessionsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<AdminSession[]> {
+    const res = await this.http.request<{ items: AdminSession[] }>("GET", "/api/v1/admin/sessions");
+    return res.items;
+  }
+
+  async revoke(id: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/admin/sessions/${id}`);
+  }
+
+  async purge(): Promise<{ purged: number }> {
+    return this.http.request<{ purged: number }>("POST", "/api/v1/admin/sessions/purge", {
+      body: {},
+    });
+  }
+}
+
+class AdminCollectionsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<CollectionMeta[]> {
+    const res = await this.http.request<{ items: CollectionMeta[] }>(
+      "GET",
+      "/api/v1/admin/collections",
+    );
+    return res.items;
+  }
+
+  async create(name: string, rules: CollectionRules): Promise<CollectionMeta> {
+    return this.http.request<CollectionMeta>("POST", "/api/v1/admin/collections", {
+      body: { name, rules },
+    });
+  }
+
+  async update(name: string, rules: CollectionRules): Promise<void> {
+    await this.http.request<{ ok: boolean }>("PATCH", `/api/v1/admin/collections/${name}`, {
+      body: { rules },
+    });
+  }
+
+  async setFieldRules(name: string, fieldRules: AdminFieldRule[]): Promise<void> {
+    await this.http.request<{ ok: boolean }>("PUT", `/api/v1/admin/collections/${name}/rules`, {
+      body: { field_rules: fieldRules },
+    });
+  }
+
+  /**
+   * Set or clear webhook URL, signing secret, and event filter.
+   * Each field follows omit/null/value semantics:
+   * - omitted: keep existing
+   * - null: clear (all events / no secret)
+   * - value: set new
+   */
+  async setWebhook(
+    name: string,
+    url: string | null,
+    opts?: { secret?: string | null; events?: string[] | null },
+  ): Promise<void> {
+    const body: Record<string, unknown> = { url };
+    if (opts?.secret !== undefined) body.secret = opts.secret;
+    if (opts?.events !== undefined) body.events = opts.events;
+    await this.http.request<{ ok: boolean; webhook_url: string | null; signing: boolean }>(
+      "PUT",
+      `/api/v1/admin/collections/${name}/webhook`,
+      { body },
+    );
+  }
+
+  async drop(name: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/admin/collections/${name}`);
+  }
+
+  async schema(name: string): Promise<ColumnInfo[]> {
+    const res = await this.http.request<{ columns: ColumnInfo[] }>(
+      "GET",
+      `/api/v1/admin/collections/${name}/schema`,
+    );
+    return res.columns;
+  }
+
+  async dropColumn(name: string, column: string): Promise<void> {
+    await this.http.request<{ dropped: boolean }>(
+      "DELETE",
+      `/api/v1/admin/collections/${name}/schema/${column}`,
+    );
+  }
+
+  async renameColumn(name: string, column: string, newName: string): Promise<void> {
+    await this.http.request<{ renamed: boolean }>(
+      "PATCH",
+      `/api/v1/admin/collections/${name}/schema/${column}`,
+      { body: { newName } },
+    );
+  }
+
+  async stats(name: string): Promise<CollectionStats> {
+    return this.http.request<CollectionStats>("GET", `/api/v1/admin/collections/${name}/stats`);
+  }
+
+  /** Full schema introspection — columns, indexes, relations, rules, FTS, webhook, stats. */
+  async introspect(name: string): Promise<CollectionIntrospection> {
+    return this.http.request<CollectionIntrospection>(
+      "GET",
+      `/api/v1/admin/collections/${name}/introspect`,
+    );
+  }
+
+  // ── Records ─────────────────────────────────────────────────────────────────
+
+  async listRecords(
+    collection: string,
+    opts: {
+      /** @deprecated Use `after` for keyset pagination. */
+      page?: number;
+      limit?: number;
+      after?: string;
+      sort?: string;
+      filter?: Record<string, string>;
+      includeDeleted?: boolean;
+      search?: string;
+    } = {},
+  ): Promise<AdminListResult<AdminRecord>> {
+    const params: Record<string, string> = {
+      limit: String(opts.limit ?? 50),
+    };
+    if (opts.after) params.after = opts.after;
+    else if (opts.page !== undefined) params.page = String(opts.page);
+    if (opts.sort) params.sort = opts.sort;
+    if (opts.includeDeleted) params.include_deleted = "true";
+    if (opts.search) params.search = opts.search;
+    if (opts.filter) Object.assign(params, opts.filter);
+    return this.http.request<AdminListResult<AdminRecord>>(
+      "GET",
+      `/api/v1/admin/collections/${collection}/records`,
+      { query: params },
+    );
+  }
+
+  async getRecord(collection: string, id: string): Promise<AdminRecord | null> {
+    try {
+      return await this.http.request<AdminRecord>(
+        "GET",
+        `/api/v1/admin/collections/${collection}/records/${id}`,
+      );
+    } catch {
+      return null;
+    }
+  }
+
+  async createRecord(collection: string, data: Record<string, unknown>): Promise<AdminRecord> {
+    return this.http.request<AdminRecord>(
+      "POST",
+      `/api/v1/admin/collections/${collection}/records`,
+      { body: data },
+    );
+  }
+
+  async updateRecord(
+    collection: string,
+    id: string,
+    patch: Record<string, unknown>,
+  ): Promise<AdminRecord> {
+    return this.http.request<AdminRecord>(
+      "PATCH",
+      `/api/v1/admin/collections/${collection}/records/${id}`,
+      { body: patch },
+    );
+  }
+
+  async deleteRecord(collection: string, id: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>(
+      "DELETE",
+      `/api/v1/admin/collections/${collection}/records/${id}`,
+    );
+  }
+
+  async restoreRecord(collection: string, id: string): Promise<AdminRecord> {
+    return this.http.request<AdminRecord>(
+      "POST",
+      `/api/v1/admin/collections/${collection}/records/${id}/restore`,
+      { body: {} },
+    );
+  }
+
+  // ── Indexes ──────────────────────────────────────────────────────────────────
+
+  async listIndexes(collection: string): Promise<IndexInfo[]> {
+    const res = await this.http.request<{ indexes: IndexInfo[] }>(
+      "GET",
+      `/api/v1/admin/collections/${collection}/indexes`,
+    );
+    return res.indexes;
+  }
+
+  async createIndex(collection: string, column: string): Promise<IndexInfo> {
+    return this.http.request<IndexInfo>("POST", `/api/v1/admin/collections/${collection}/indexes`, {
+      body: { column },
+    });
+  }
+
+  async dropIndex(collection: string, column: string): Promise<void> {
+    await this.http.request<{ dropped: boolean }>(
+      "DELETE",
+      `/api/v1/admin/collections/${collection}/indexes/${column}`,
+    );
+  }
+
+  // ── FTS ──────────────────────────────────────────────────────────────────────
+
+  async getFtsStatus(collection: string): Promise<{ exists: boolean }> {
+    return this.http.request<{ exists: boolean }>(
+      "GET",
+      `/api/v1/admin/collections/${collection}/fts`,
+    );
+  }
+
+  async createFts(collection: string): Promise<{ created: boolean; indexed?: number }> {
+    return this.http.request<{ created: boolean; indexed?: number }>(
+      "POST",
+      `/api/v1/admin/collections/${collection}/fts`,
+      { body: {} },
+    );
+  }
+
+  async dropFts(collection: string): Promise<void> {
+    await this.http.request("DELETE", `/api/v1/admin/collections/${collection}/fts`);
+  }
+}
+
+class AdminRelationsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<Relation[]> {
+    const res = await this.http.request<{ items: Relation[] }>("GET", "/api/v1/admin/relations");
+    return res.items;
+  }
+
+  async create(params: CreateRelationParams): Promise<Relation> {
+    return this.http.request<Relation>("POST", "/api/v1/admin/relations", { body: params });
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/admin/relations/${id}`);
+  }
+}
+
+class AdminStorageClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async listFiles(): Promise<AdminStoredFile[]> {
+    const res = await this.http.request<{ items: AdminStoredFile[] }>(
+      "GET",
+      "/api/v1/admin/storage",
+    );
+    return res.items;
+  }
+
+  async uploadFile(params: {
+    file: File | Blob;
+    filename?: string;
+    isPublic: boolean;
+    collection?: string;
+    bucket?: string;
+  }): Promise<AdminStoredFile> {
+    const form = new FormData();
+    form.append("file", params.file, params.filename);
+    form.append("is_public", params.isPublic ? "true" : "false");
+    if (params.collection) form.append("collection", params.collection);
+    if (params.bucket) form.append("bucket", params.bucket);
+    return this.http.request<AdminStoredFile>("POST", "/api/v1/admin/storage/upload", {
+      formData: form,
+    });
+  }
+
+  async deleteFile(id: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/admin/storage/${id}`);
+  }
+
+  async listBuckets(): Promise<StorageBucket[]> {
+    const res = await this.http.request<{ items: StorageBucket[] }>("GET", "/api/v1/admin/buckets");
+    return res.items;
+  }
+
+  async createBucket(params: {
+    name: string;
+    access_read: BucketAccessRule;
+    access_write: BucketAccessRule;
+    allowed_mimes?: string[] | null;
+    max_size_bytes?: number | null;
+    cdn_url?: string | null;
+  }): Promise<StorageBucket> {
+    return this.http.request<StorageBucket>("POST", "/api/v1/admin/buckets", { body: params });
+  }
+
+  async updateBucket(
+    name: string,
+    updates: Partial<Omit<StorageBucket, "name" | "created_at">>,
+  ): Promise<StorageBucket> {
+    return this.http.request<StorageBucket>("PATCH", `/api/v1/admin/buckets/${name}`, {
+      body: updates,
+    });
+  }
+
+  async deleteBucket(name: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/admin/buckets/${name}`);
+  }
+}
+
+class AdminSettingsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async get(): Promise<ServerSettings> {
+    return this.http.request<ServerSettings>("GET", "/api/v1/admin/settings");
+  }
+
+  async update(updates: Partial<ServerSettings>): Promise<ServerSettings> {
+    return this.http.request<ServerSettings>("PATCH", "/api/v1/admin/settings", { body: updates });
+  }
+
+  async testEmail(to: string): Promise<{ ok: boolean; error?: string }> {
+    return this.http.request<{ ok: boolean; error?: string }>(
+      "POST",
+      "/api/v1/admin/settings/test-email",
+      { body: { to } },
+    );
+  }
+
+  async restart(): Promise<{ ok: boolean }> {
+    return this.http.request<{ ok: boolean }>("POST", "/api/v1/admin/restart", { body: {} });
+  }
+
+  async getEmailTemplates(): Promise<Record<TemplateName, EmailTemplate>> {
+    return this.http.request<Record<TemplateName, EmailTemplate>>(
+      "GET",
+      "/api/v1/admin/email-templates",
+    );
+  }
+
+  async updateEmailTemplate(
+    name: TemplateName,
+    tpl: Omit<EmailTemplate, "is_default">,
+  ): Promise<{ ok: boolean; template: EmailTemplate }> {
+    return this.http.request<{ ok: boolean; template: EmailTemplate }>(
+      "PUT",
+      `/api/v1/admin/email-templates/${name}`,
+      { body: tpl },
+    );
+  }
+
+  async resetEmailTemplate(name: TemplateName): Promise<{ ok: boolean; template: EmailTemplate }> {
+    return this.http.request<{ ok: boolean; template: EmailTemplate }>(
+      "DELETE",
+      `/api/v1/admin/email-templates/${name}`,
+    );
+  }
+
+  async getConfig(): Promise<ConfigResponse> {
+    return this.http.request<ConfigResponse>("GET", "/api/v1/admin/config");
+  }
+
+  async updateConfig(
+    updates: Record<string, string | null>,
+  ): Promise<{ ok: boolean; overrides: Record<string, string | null> }> {
+    return this.http.request<{ ok: boolean; overrides: Record<string, string | null> }>(
+      "PATCH",
+      "/api/v1/admin/config",
+      { body: updates },
+    );
+  }
+
+  async getAudit(limit = 50, offset = 0): Promise<{ items: SettingsAuditEntry[]; total: number }> {
+    return this.http.request<{ items: SettingsAuditEntry[]; total: number }>(
+      "GET",
+      `/api/v1/admin/settings/audit?limit=${limit}&offset=${offset}`,
+    );
+  }
+
+  // Returns raw Response so the caller can trigger a browser file download.
+  async exportSettings(): Promise<Response> {
+    return this.http.requestRaw("GET", "/api/v1/admin/settings/export");
+  }
+
+  async importSettings(
+    settings: Record<string, unknown>,
+  ): Promise<{ ok: boolean; imported: number; settings: ServerSettings }> {
+    return this.http.request<{ ok: boolean; imported: number; settings: ServerSettings }>(
+      "POST",
+      "/api/v1/admin/settings/import",
+      { body: settings },
+    );
+  }
+}
+
+class AdminBackupsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<BackupFile[]> {
+    return this.http.request<BackupFile[]>("GET", "/api/v1/admin/backups");
+  }
+
+  async create(): Promise<BackupFile> {
+    return this.http.request<BackupFile>("POST", "/api/v1/admin/backups", { body: {} });
+  }
+
+  // Returns raw Response so the caller can trigger a browser file download.
+  async download(filename: string): Promise<Response> {
+    return this.http.requestRaw("GET", `/api/v1/admin/backups/${encodeURIComponent(filename)}`);
+  }
+
+  // Returns a full database snapshot as a raw Response (for the one-click download).
+  async snapshot(): Promise<Response> {
+    return this.http.requestRaw("POST", "/api/v1/admin/backup");
+  }
+
+  async delete(filename: string): Promise<void> {
+    await this.http.request("DELETE", `/api/v1/admin/backups/${encodeURIComponent(filename)}`);
+  }
+
+  async restore(filename: string): Promise<void> {
+    await this.http.request(
+      "POST",
+      `/api/v1/admin/backups/${encodeURIComponent(filename)}/restore`,
+      { body: {} },
+    );
+  }
+
+  async upload(file: File | Blob, filename?: string): Promise<BackupFile> {
+    const form = new FormData();
+    form.append("file", file, filename);
+    return this.http.request<BackupFile>("POST", "/api/v1/admin/backups/upload", {
+      formData: form,
+    });
+  }
+}
+
+class AdminSystemClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async health(): Promise<HealthResponse> {
+    return this.http.request<HealthResponse>("GET", "/api/v1/admin/health");
+  }
+
+  async stats(): Promise<StatsResponse> {
+    return this.http.request<StatsResponse>("GET", "/api/v1/admin/stats");
+  }
+}
+
+export interface WebhookLogRow {
+  id: number;
+  ts: number;
+  collection: string;
+  event: string;
+  url: string;
+  attempt: number;
+  success: number;
+  response_status: number | null;
+  error: string | null;
+  duration_ms: number;
+}
+
+class AdminLogsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async webhook(opts?: { limit?: number }): Promise<{ rows: WebhookLogRow[]; total: number }> {
+    const params: Record<string, string> = {};
+    if (opts?.limit) params.limit = String(opts.limit);
+    return this.http.request<{ rows: WebhookLogRow[]; total: number }>(
+      "GET",
+      "/api/v1/admin/logs/webhook",
+      { query: params },
+    );
+  }
+
+  async clearWebhook(): Promise<void> {
+    await this.http.request("DELETE", "/api/v1/admin/logs/webhook");
+  }
+}
+
+export interface MigrationStatus {
+  applied: Array<{ name: string; applied_at: number }>;
+  pending: string[];
+  auto_migrate: boolean;
+  db_provider: "sqlite" | "postgres";
+}
+
+class AdminMigrationsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async status(): Promise<MigrationStatus> {
+    return this.http.request<MigrationStatus>("GET", "/api/v1/admin/migrations");
+  }
+}
+
+// ─── Main AdminClient ─────────────────────────────────────────────────────────
+
+export class AdminClient {
+  readonly users: AdminUsersClient;
+  readonly sessions: AdminSessionsClient;
+  readonly collections: AdminCollectionsClient;
+  readonly relations: AdminRelationsClient;
+  readonly storage: AdminStorageClient;
+  readonly settings: AdminSettingsClient;
+  readonly backups: AdminBackupsClient;
+  readonly migrations: AdminMigrationsClient;
+  readonly logs: AdminLogsClient;
+  readonly system: AdminSystemClient;
+
+  constructor(http: HttpClient) {
+    this.users = new AdminUsersClient(http);
+    this.sessions = new AdminSessionsClient(http);
+    this.collections = new AdminCollectionsClient(http);
+    this.relations = new AdminRelationsClient(http);
+    this.storage = new AdminStorageClient(http);
+    this.settings = new AdminSettingsClient(http);
+    this.backups = new AdminBackupsClient(http);
+    this.migrations = new AdminMigrationsClient(http);
+    this.logs = new AdminLogsClient(http);
+    this.system = new AdminSystemClient(http);
+  }
+}