@graph8/sdk 0.303.0 → 0.357.0

package/docs/api/workspaceBackup.d.ts

@@ -0,0 +1,324 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.workspaceBackup` (Workspace backup): 7 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_workspace_backup_api_workspace_backup_post">;
+ *
+ * Reference with examples: workspaceBackup.md
+ */
+/* eslint-disable */
+
+/** `g8.api.workspaceBackup.<member>` -> the operationId it calls. */
+export interface WorkspaceBackupMembers {
+  createWorkspaceBackupApi: "create_workspace_backup_api_workspace_backup_post";
+  createWorkspaceRestoreApi: "create_workspace_restore_api_workspace_restore_post";
+  downloadWorkspaceBackupApi: "download_workspace_backup_api_workspace_backup__backup_id__download_get";
+  getWorkspaceBackupApi: "get_workspace_backup_api_workspace_backup__backup_id__get";
+  getWorkspaceRestoreApi: "get_workspace_restore_api_workspace_restore__restore_id__get";
+  listWorkspaceBackupsApi: "list_workspace_backups_api_workspace_backup_get";
+  listWorkspaceRestoresApi: "list_workspace_restores_api_workspace_restore_get";
+}
+
+/** Input and output of every `g8.api.workspaceBackup` operation, keyed by operationId. */
+export interface WorkspaceBackupOperations {
+  /**
+   * POST /workspace/backup
+   * Create Workspace Backup Api
+   * tier: write · scope: objects:export
+   */
+  create_workspace_backup_api_workspace_backup_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_BackupJobResponse_;
+  };
+  /**
+   * POST /workspace/restore
+   * Create Workspace Restore Api
+   * tier: write · scope: objects:restore
+   */
+  create_workspace_restore_api_workspace_restore_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RestoreCreate;
+  };
+    output: ApiResponse_RestoreJobResponse_;
+  };
+  /**
+   * GET /workspace/backup/{backup_id}/download
+   * Download Workspace Backup Api
+   * tier: read · scope: objects:export
+   */
+  download_workspace_backup_api_workspace_backup__backup_id__download_get: {
+    input: {
+    path: {
+      backup_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_BackupDownloadResponse_;
+  };
+  /**
+   * GET /workspace/backup/{backup_id}
+   * Get Workspace Backup Api
+   * tier: read · scope: objects:export
+   */
+  get_workspace_backup_api_workspace_backup__backup_id__get: {
+    input: {
+    path: {
+      backup_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_BackupJobResponse_;
+  };
+  /**
+   * GET /workspace/restore/{restore_id}
+   * Get Workspace Restore Api
+   * tier: read · scope: objects:restore
+   */
+  get_workspace_restore_api_workspace_restore__restore_id__get: {
+    input: {
+    path: {
+      restore_id: string;
+    };
+    query?: {
+      conflict_offset?: number;
+      conflict_limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RestoreJobResponse_;
+  };
+  /**
+   * GET /workspace/backup
+   * List Workspace Backups Api
+   * tier: read · scope: objects:export
+   */
+  list_workspace_backups_api_workspace_backup_get: {
+    input: {
+    query?: {
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_BackupJobListResponse_;
+  };
+  /**
+   * GET /workspace/restore
+   * List Workspace Restores Api
+   * tier: read · scope: objects:restore
+   */
+  list_workspace_restores_api_workspace_restore_get: {
+    input: {
+    query?: {
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RestoreJobListResponse_;
+  };
+}
+
+// 15 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_BackupDownloadResponse_ {
+  data: BackupDownloadResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_BackupJobListResponse_ {
+  data: BackupJobListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_BackupJobResponse_ {
+  data: BackupJobResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_RestoreJobListResponse_ {
+  data: RestoreJobListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_RestoreJobResponse_ {
+  data: RestoreJobResponse;
+  pagination?: PaginationMeta | null;
+}
+
+/** A link to the archive (NDJSON, ``application/x-ndjson``) valid until ``expires_at`` (a few minutes). */
+export interface BackupDownloadResponse {
+  archive_bytes?: number | null;
+  archive_sha256?: string | null;
+  expires_at: string;
+  filename: string;
+  format_version?: number | null;
+  url: string;
+}
+
+export interface BackupJobListResponse {
+  backups: Array<BackupJobResponse>;
+  limit: number;
+  offset: number;
+  /** False while backup storage is not configured: starting a backup would answer 503. */
+  storage_configured?: boolean;
+  total: number;
+}
+
+/**
+ * A workspace backup: ``complete`` (made by a workspace administrator: every object, field, grant and report) or
+ * ``restricted`` (exactly what the requester could read). The archive is deleted 14 days after ``created_at``.
+ */
+export interface BackupJobResponse {
+  archive_bytes?: number | null;
+  archive_sha256?: string | null;
+  completed_at?: string | null;
+  /** Rows per archive section. */
+  counts?: Record<string, number>;
+  created_at: string;
+  download_available?: boolean;
+  error_code?: string | null;
+  expires_at?: string | null;
+  format_version?: number | null;
+  /** Whether the archive holds record history (who changed what). Null until the backup has run (and for a backup made before this was recorded). */
+  history?: ("included" | "omitted") | null;
+  /** Why history was left out: ``audit_permission_required`` (the requester lacks objects:audit) or ``audit_log_switched_off`` (the audit log is off for this workspace). Null when included or unknown. */
+  history_reason?: ("audit_permission_required" | "audit_log_switched_off") | null;
+  id: string;
+  /** ``restricted_backup``: made with restricted access, so it cannot be restored. */
+  not_restorable_reason?: ("restricted_backup" | "expired" | "not_completed") | null;
+  requested_by: BackupRequester;
+  /** Only a complete backup can be restored. */
+  restorable?: boolean;
+  scope?: ("complete" | "restricted") | null;
+  started_at?: string | null;
+  status: "pending" | "running" | "completed" | "failed" | "expired";
+}
+
+/**
+ * Who asked. ``name`` and ``kind`` are shown to a workspace administrator only (anyone else lists only their own
+ * jobs and reads ``is_you``); ``name`` is the member's display name, None for an API key or an unknown member.
+ */
+export interface BackupRequester {
+  is_you: boolean;
+  kind?: ("member" | "api_key") | null;
+  name?: string | null;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
+}
+
+/**
+ * One receipt line: the refused item (section and id; for a field error the field slug), a stable code, why it was
+ * refused and what fixes it. Never a value from the archive.
+ */
+export interface RestoreConflict {
+  code: string;
+  field?: string | null;
+  fix?: string;
+  id?: string | null;
+  section: string;
+  why?: string;
+}
+
+/**
+ * Restore one completed backup of THIS workspace, by id. A record or report that is missing is added; one that
+ * exists is UPDATED to the backup's values where they differ, through the same checks as an edit (an archived record
+ * the backup holds live is unarchived). Objects, fields, relationships, process lists, grants and links are only
+ * added. Nothing that exists is ever deleted or archived.
+ *
+ * ``dry_run`` defaults to true: every step and check runs and is rolled back, and the counts say exactly what a
+ * restore would add, update and leave unchanged. A real restore must send ``dry_run: false``.
+ */
+export interface RestoreCreate {
+  backup_id: string;
+  /** True (the default) writes nothing; send false to restore. */
+  dry_run?: boolean;
+}
+
+/** Restores, newest first (each without its receipt: read one restore for that). */
+export interface RestoreJobListResponse {
+  limit: number;
+  offset: number;
+  restores: Array<RestoreJobResponse>;
+  total: number;
+}
+
+export interface RestoreJobResponse {
+  backup_id?: string | null;
+  completed_at?: string | null;
+  conflict_count?: number;
+  conflict_offset?: number;
+  /** One page of the receipt. */
+  conflicts?: Array<RestoreConflict>;
+  /** More conflicts happened than the receipt keeps (the first 5,000); conflict_count is exact. */
+  conflicts_truncated?: boolean;
+  /** Per archive section. A dry run's counts are what the restore would do now. */
+  counts?: Record<string, SectionCounts>;
+  created_at: string;
+  dry_run: boolean;
+  error_code?: string | null;
+  /** The run's last sign of life; while running, ``counts`` are its progress at that moment. */
+  heartbeat_at?: string | null;
+  id: string;
+  /** What a restore adds, updates and never touches, in one sentence. */
+  note?: string;
+  requested_by?: BackupRequester | null;
+  scope?: ("complete" | "restricted") | null;
+  started_at?: string | null;
+  status: "pending" | "running" | "completed" | "failed" | "expired";
+  /** ``counts`` summed over every section. */
+  totals?: SectionCounts;
+}
+
+/**
+ * What a restore did (or, for a dry run, would do) with one archive section. Every row of the section is counted
+ * exactly once: ``created + updated + unchanged + conflicts + skipped`` is the section's rows in the backup.
+ */
+export interface SectionCounts {
+  conflicts?: number;
+  /** Not in the workspace by id: added. */
+  created?: number;
+  /** Not restored by design (e.g. schema from a restricted archive). */
+  skipped?: number;
+  /** In the workspace by id and left exactly as it is: it already holds the backup's values, or its section is only added. */
+  unchanged?: number;
+  /** In the workspace by id with other values: written back to the backup's values (records and reports only; every other section is only added, so this stays 0 there). */
+  updated?: number;
+}