@epilot/sdk 2.8.2 → 2.8.4

package/docs/snapshot.md

@@ -0,0 +1,561 @@
+# Snapshot API
+
+- **Base URL:** `https://snapshot.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/snapshot](https://docs.epilot.io/api/snapshot)
+
+## Usage
+
+```ts
+import { epilot } from '@epilot/sdk'
+
+epilot.authorize(() => '<token>')
+const { data } = await epilot.snapshot.createSnapshot(...)
+```
+
+### Tree-shakeable import
+
+```ts
+import { getClient, authorize } from '@epilot/sdk/snapshot'
+
+const snapshotClient = getClient()
+authorize(snapshotClient, () => '<token>')
+const { data } = await snapshotClient.createSnapshot(...)
+```
+
+## Operations
+
+**Snapshots**
+- [`createSnapshot`](#createsnapshot)
+- [`listSnapshots`](#listsnapshots)
+- [`getSnapshot`](#getsnapshot)
+- [`deleteSnapshot`](#deletesnapshot)
+- [`restoreSnapshot`](#restoresnapshot)
+- [`listSnapshotResources`](#listsnapshotresources)
+- [`getSnapshotResource`](#getsnapshotresource)
+- [`listDependencies`](#listdependencies)
+
+**Schemas**
+- [`Error`](#error)
+- [`ResourceRef`](#resourceref)
+- [`SnapshotResourceSummary`](#snapshotresourcesummary)
+- [`SnapshotResourceList`](#snapshotresourcelist)
+- [`SnapshotResourceDetail`](#snapshotresourcedetail)
+- [`CreateSnapshotRequest`](#createsnapshotrequest)
+- [`CreateSnapshotResponse`](#createsnapshotresponse)
+- [`RestoreSnapshotRequest`](#restoresnapshotrequest)
+- [`RestoreSnapshotResponse`](#restoresnapshotresponse)
+- [`Snapshot`](#snapshot)
+- [`Operation`](#operation)
+- [`SkippedResource`](#skippedresource)
+- [`CallerIdentity`](#calleridentity)
+
+### `createSnapshot`
+
+Create a new snapshot of the given resources. Async — returns immediately
+with a snapshot ID; client polls `getSnapshot` until `create.status`
+moves from `in_progress` to `completed` or `failed`.
+
+`POST /v1/snapshots`
+
+```ts
+const { data } = await client.createSnapshot(
+  null,
+  {
+    name: 'string',
+    description: 'string',
+    trigger: 'manual',
+    blueprint_instance_id: 'string',
+    resources: [
+      {
+        type: 'string',
+        id: 'string'
+      }
+    ]
+  },
+)
+```
+
+---
+
+### `listSnapshots`
+
+List snapshots for the caller's organization, newest first.
+
+`GET /v1/snapshots`
+
+```ts
+const { data } = await client.listSnapshots({
+  cursor: 'example',
+  size: 1,
+  resource: ['...'],
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "page_size": 0,
+  "cursor": "string",
+  "results": [
+    {
+      "id": "string",
+      "org_id": "string",
+      "name": "string",
+      "description": "string",
+      "trigger": "manual",
+      "blueprint_instance_id": "string",
+      "resource_counts": {},
+      "create": {
+        "type": "create",
+        "started_at": "1970-01-01T00:00:00.000Z",
+        "completed_at": "1970-01-01T00:00:00.000Z",
+        "status": "in_progress",
+        "error": "string",
+        "triggered_by": {
+          "name": "string",
+          "user_id": "string",
+          "token_id": "string"
+        },
+        "skipped": [
+          {
+            "lineage_id": "string",
+            "reason": "modified"
+          }
+        ]
+      },
+      "restores": [
+        {
+          "type": "create",
+          "started_at": "1970-01-01T00:00:00.000Z",
+          "completed_at": "1970-01-01T00:00:00.000Z",
+          "status": "in_progress",
+          "error": "string",
+          "triggered_by": {
+            "name": "string",
+            "user_id": "string",
+            "token_id": "string"
+          },
+          "skipped": [
+            {
+              "lineage_id": "string",
+              "reason": "modified"
+            }
+          ]
+        }
+      ],
+      "matched_count": 0
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `getSnapshot`
+
+Fetch a snapshot's metadata. Poll this endpoint to track create/restore progress.
+
+`GET /v1/snapshots/{id}`
+
+```ts
+const { data } = await client.getSnapshot({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "string",
+  "org_id": "string",
+  "name": "string",
+  "description": "string",
+  "trigger": "manual",
+  "blueprint_instance_id": "string",
+  "resource_counts": {},
+  "create": {
+    "type": "create",
+    "started_at": "1970-01-01T00:00:00.000Z",
+    "completed_at": "1970-01-01T00:00:00.000Z",
+    "status": "in_progress",
+    "error": "string",
+    "triggered_by": {
+      "name": "string",
+      "user_id": "string",
+      "token_id": "string"
+    },
+    "skipped": [
+      {
+        "lineage_id": "string",
+        "reason": "modified"
+      }
+    ]
+  },
+  "restores": [
+    {
+      "type": "create",
+      "started_at": "1970-01-01T00:00:00.000Z",
+      "completed_at": "1970-01-01T00:00:00.000Z",
+      "status": "in_progress",
+      "error": "string",
+      "triggered_by": {
+        "name": "string",
+        "user_id": "string",
+        "token_id": "string"
+      },
+      "skipped": [
+        {
+          "lineage_id": "string",
+          "reason": "modified"
+        }
+      ]
+    }
+  ],
+  "matched_count": 0
+}
+```
+
+</details>
+
+---
+
+### `deleteSnapshot`
+
+Delete a snapshot's metadata and S3 manifest.
+
+`DELETE /v1/snapshots/{id}`
+
+```ts
+const { data } = await client.deleteSnapshot({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+---
+
+### `restoreSnapshot`
+
+Restore a snapshot to the org. Async — returns immediately; client polls
+`getSnapshot` until the latest entry in `restores` moves from
+`in_progress` to one of `completed | partial | failed`.
+
+`POST /v1/snapshots/{id}:restore`
+
+```ts
+const { data } = await client.restoreSnapshot(
+  {
+    id: '123e4567-e89b-12d3-a456-426614174000',
+  },
+  {
+    mode: 'overwrite'
+  },
+)
+```
+
+---
+
+### `listSnapshotResources`
+
+List the resources captured in this snapshot. Returns lightweight
+identity fields per resource — payloads are fetched via the
+single-resource endpoint when needed.
+
+`GET /v1/snapshots/{id}/resources`
+
+```ts
+const { data } = await client.listSnapshotResources({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "resources": [
+    {
+      "lineage_id": "string",
+      "target_id": "string",
+      "type": "string",
+      "name": "string"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `getSnapshotResource`
+
+Fetch one captured resource with its full payload. For UI views
+that diff the captured state against the current destination.
+
+`GET /v1/snapshots/{id}/resources/{lineage_id}`
+
+```ts
+const { data } = await client.getSnapshotResource({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  lineage_id: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "lineage_id": "string",
+  "target_id": "string",
+  "type": "string",
+  "name": "string",
+  "captured": {}
+}
+```
+
+</details>
+
+---
+
+### `listDependencies`
+
+Walk the dependency tree for a set of resources and return the full
+transitive closure, topologically sorted.
+
+`POST /v1/snapshots:list-dependencies`
+
+```ts
+const { data } = await client.listDependencies(
+  null,
+  {
+    resources: [
+      {
+        type: 'string',
+        id: 'string'
+      }
+    ]
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "dependencies": [
+    {
+      "type": "string",
+      "id": "string"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+## Schemas
+
+### `Error`
+
+```ts
+type Error = {
+  status: number
+  error: string
+}
+```
+
+### `ResourceRef`
+
+```ts
+type ResourceRef = {
+  type: string
+  id: string
+}
+```
+
+### `SnapshotResourceSummary`
+
+Lightweight identity for a captured resource. Returned by
+`listSnapshotResources`; the full payload is fetched separately via
+`getSnapshotResource` when needed.
+
+
+```ts
+type SnapshotResourceSummary = {
+  lineage_id: string
+  target_id: string
+  type: string
+  name?: string
+}
+```
+
+### `SnapshotResourceList`
+
+```ts
+type SnapshotResourceList = {
+  resources: Array<{
+    lineage_id: string
+    target_id: string
+    type: string
+    name?: string
+  }>
+}
+```
+
+### `SnapshotResourceDetail`
+
+A single captured resource with its full payload. The identity fields
+match `SnapshotResourceSummary`; the `captured` payload is the
+pre-install state at snapshot time.
+
+
+```ts
+type SnapshotResourceDetail = {
+  lineage_id: string
+  target_id: string
+  type: string
+  name?: string
+  captured: Record<string, unknown>
+}
+```
+
+### `CreateSnapshotRequest`
+
+```ts
+type CreateSnapshotRequest = {
+  name: string
+  description?: string
+  trigger?: "manual" | "sync" | "blueprint_install"
+  blueprint_instance_id?: string
+  resources: Array<{
+    type: string
+    id: string
+  }>
+}
+```
+
+### `CreateSnapshotResponse`
+
+```ts
+type CreateSnapshotResponse = {
+  id: string
+  name: string
+  status: "creating"
+  created_at: string // date-time
+}
+```
+
+### `RestoreSnapshotRequest`
+
+```ts
+type RestoreSnapshotRequest = {
+  mode?: "overwrite" | "preserve_edits"
+}
+```
+
+### `RestoreSnapshotResponse`
+
+```ts
+type RestoreSnapshotResponse = {
+  id: string
+  status: "restoring"
+}
+```
+
+### `Snapshot`
+
+```ts
+type Snapshot = {
+  id: string
+  org_id: string
+  name: string
+  description?: string
+  trigger: "manual" | "sync" | "blueprint_install"
+  blueprint_instance_id?: string
+  resource_counts: Record<string, number>
+  create: {
+    type: "create" | "restore"
+    started_at: string // date-time
+    completed_at?: string // date-time
+    status: "in_progress" | "completed" | "partial" | "failed"
+    error?: string
+    triggered_by: {
+      name: { ... }
+      user_id?: { ... }
+      token_id?: { ... }
+    }
+    skipped?: Array<{
+      lineage_id: { ... }
+      reason: { ... }
+    }>
+  }
+  restores: Array<{
+    type: "create" | "restore"
+    started_at: string // date-time
+    completed_at?: string // date-time
+    status: "in_progress" | "completed" | "partial" | "failed"
+    error?: string
+    triggered_by: {
+      name: { ... }
+      user_id?: { ... }
+      token_id?: { ... }
+    }
+    skipped?: Array<{
+      lineage_id: { ... }
+      reason: { ... }
+    }>
+  }>
+  matched_count?: number
+}
+```
+
+### `Operation`
+
+```ts
+type Operation = {
+  type: "create" | "restore"
+  started_at: string // date-time
+  completed_at?: string // date-time
+  status: "in_progress" | "completed" | "partial" | "failed"
+  error?: string
+  triggered_by: {
+    name: string
+    user_id?: string
+    token_id?: string
+  }
+  skipped?: Array<{
+    lineage_id: string
+    reason: "modified" | "co_owned"
+  }>
+}
+```
+
+### `SkippedResource`
+
+```ts
+type SkippedResource = {
+  lineage_id: string
+  reason: "modified" | "co_owned"
+}
+```
+
+### `CallerIdentity`
+
+```ts
+type CallerIdentity = {
+  name: string
+  user_id?: string
+  token_id?: string
+}
+```