@epilot/sdk 2.7.1 → 2.8.0-rc.0

package/docs/configuration-hub.md

@@ -32,6 +32,13 @@ const { data } = await configurationHubClient.listConfigTypes(...)
 - [`getIndex`](#getindex)
 - [`rebuildIndex`](#rebuildindex)
 
+**Sync**
+- [`createSyncJob`](#createsyncjob)
+- [`listSyncJobs`](#listsyncjobs)
+- [`getSyncJob`](#getsyncjob)
+- [`retrySyncJob`](#retrysyncjob)
+- [`listSyncJobResources`](#listsyncjobresources)
+
 **Schemas**
 - [`ResourceType`](#resourcetype)
 - [`ConfigTypeInfo`](#configtypeinfo)
@@ -41,6 +48,19 @@ const { data } = await configurationHubClient.listConfigTypes(...)
 - [`IndexRebuildResponse`](#indexrebuildresponse)
 - [`IndexStatusResponse`](#indexstatusresponse)
 - [`ErrorResponse`](#errorresponse)
+- [`SyncJobStatus`](#syncjobstatus)
+- [`SyncDirection`](#syncdirection)
+- [`SyncPhase`](#syncphase)
+- [`SyncJobResourceStatus`](#syncjobresourcestatus)
+- [`SyncJobRequest`](#syncjobrequest)
+- [`SyncJobRetryRequest`](#syncjobretryrequest)
+- [`SyncJobCounts`](#syncjobcounts)
+- [`SyncJobEvent`](#syncjobevent)
+- [`SyncJobBatch`](#syncjobbatch)
+- [`SyncJob`](#syncjob)
+- [`SyncJobListResponse`](#syncjoblistresponse)
+- [`SyncJobResource`](#syncjobresource)
+- [`SyncJobResourceListResponse`](#syncjobresourcelistresponse)
 
 ### `listConfigTypes`
 
@@ -118,6 +138,13 @@ const { data } = await client.listConfigs({
       "aliases": ["string"],
       "purposes": ["string"],
       "link": "https://example.com/path",
+      "active": true,
+      "blueprints": [
+        {
+          "id": "string",
+          "title": "string"
+        }
+      ],
       "metadata": {}
     }
   ]
@@ -162,6 +189,13 @@ const { data } = await client.getConfigDependencies({
       "aliases": ["string"],
       "purposes": ["string"],
       "link": "https://example.com/path",
+      "active": true,
+      "blueprints": [
+        {
+          "id": "string",
+          "title": "string"
+        }
+      ],
       "metadata": {}
     }
   ]
@@ -204,6 +238,13 @@ const { data } = await client.getConfigUsedBy({
       "aliases": ["string"],
       "purposes": ["string"],
       "link": "https://example.com/path",
+      "active": true,
+      "blueprints": [
+        {
+          "id": "string",
+          "title": "string"
+        }
+      ],
       "metadata": {}
     }
   ]
@@ -242,6 +283,349 @@ const { data } = await client.getIndex()
 
 ---
 
+### `createSyncJob`
+
+Create a new cross-org sync job. The job is enqueued for asynchronous execution
+by the worker Lambda; the response returns the persisted job header with status
+`pending`.
+
+`POST /v1/configs/sync-jobs`
+
+```ts
+const { data } = await client.createSyncJob(
+  null,
+  {
+    source_org_id: 'string',
+    target_org_id: 'string',
+    target_auth_token: 'string',
+    name: 'string',
+    dry_run: false,
+    include_dependencies: true,
+    resources: [
+      {
+        type: 'string',
+        id: 'string'
+      }
+    ]
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "string",
+  "name": "string",
+  "status": "pending",
+  "direction": "push",
+  "source_org_id": "string",
+  "target_org_id": "string",
+  "dry_run": true,
+  "counts": {
+    "total": 0,
+    "pending": 0,
+    "in_progress": 0,
+    "succeeded": 0,
+    "failed": 0,
+    "skipped_unchanged": 0
+  },
+  "current_phase": "phase_0",
+  "current_batch": {
+    "index": 0,
+    "of": 0,
+    "level": 0
+  },
+  "started_at": "1970-01-01T00:00:00.000Z",
+  "finished_at": "1970-01-01T00:00:00.000Z",
+  "events": [
+    {
+      "seq": 0,
+      "ts": "1970-01-01T00:00:00.000Z",
+      "phase": "phase_0",
+      "type": "string",
+      "source_id": "string",
+      "target_id": "string",
+      "status": "pending",
+      "message": "string",
+      "error": "string"
+    }
+  ],
+  "errors_sample": [
+    {
+      "type": "string",
+      "source_id": "string",
+      "error": "string"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `listSyncJobs`
+
+List sync jobs scoped to the caller's organization, paginated with an opaque
+cursor. Defaults to most-recent first.
+
+`GET /v1/configs/sync-jobs`
+
+```ts
+const { data } = await client.listSyncJobs({
+  cursor: 'example',
+  size: 1,
+  status: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "next_cursor": "string",
+  "results": [
+    {
+      "id": "string",
+      "name": "string",
+      "status": "pending",
+      "direction": "push",
+      "source_org_id": "string",
+      "target_org_id": "string",
+      "dry_run": true,
+      "counts": {
+        "total": 0,
+        "pending": 0,
+        "in_progress": 0,
+        "succeeded": 0,
+        "failed": 0,
+        "skipped_unchanged": 0
+      },
+      "current_phase": "phase_0",
+      "current_batch": {
+        "index": 0,
+        "of": 0,
+        "level": 0
+      },
+      "started_at": "1970-01-01T00:00:00.000Z",
+      "finished_at": "1970-01-01T00:00:00.000Z",
+      "events": [
+        {
+          "seq": 0,
+          "ts": "1970-01-01T00:00:00.000Z",
+          "phase": "phase_0",
+          "type": "string",
+          "source_id": "string",
+          "target_id": "string",
+          "status": "pending",
+          "message": "string",
+          "error": "string"
+        }
+      ],
+      "errors_sample": [
+        {
+          "type": "string",
+          "source_id": "string",
+          "error": "string"
+        }
+      ]
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `getSyncJob`
+
+Fetch a single sync job by ID. Returns the job header, counts summary,
+current phase pointer, and the latest activity events. Frontend polls this
+endpoint with a ramping interval.
+
+`GET /v1/configs/sync-jobs/{id}`
+
+```ts
+const { data } = await client.getSyncJob({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "string",
+  "name": "string",
+  "status": "pending",
+  "direction": "push",
+  "source_org_id": "string",
+  "target_org_id": "string",
+  "dry_run": true,
+  "counts": {
+    "total": 0,
+    "pending": 0,
+    "in_progress": 0,
+    "succeeded": 0,
+    "failed": 0,
+    "skipped_unchanged": 0
+  },
+  "current_phase": "phase_0",
+  "current_batch": {
+    "index": 0,
+    "of": 0,
+    "level": 0
+  },
+  "started_at": "1970-01-01T00:00:00.000Z",
+  "finished_at": "1970-01-01T00:00:00.000Z",
+  "events": [
+    {
+      "seq": 0,
+      "ts": "1970-01-01T00:00:00.000Z",
+      "phase": "phase_0",
+      "type": "string",
+      "source_id": "string",
+      "target_id": "string",
+      "status": "pending",
+      "message": "string",
+      "error": "string"
+    }
+  ],
+  "errors_sample": [
+    {
+      "type": "string",
+      "source_id": "string",
+      "error": "string"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `retrySyncJob`
+
+Retry the failed resources from a prior sync job. Creates a new job whose
+scope is the failed `(type, source_id)` set of the original job and enqueues
+it for execution. Optionally accepts inline paylo
+
+`POST /v1/configs/sync-jobs/{id}/retry`
+
+```ts
+const { data } = await client.retrySyncJob(
+  {
+    id: '123e4567-e89b-12d3-a456-426614174000',
+  },
+  {
+    payload_overrides: {}
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "string",
+  "name": "string",
+  "status": "pending",
+  "direction": "push",
+  "source_org_id": "string",
+  "target_org_id": "string",
+  "dry_run": true,
+  "counts": {
+    "total": 0,
+    "pending": 0,
+    "in_progress": 0,
+    "succeeded": 0,
+    "failed": 0,
+    "skipped_unchanged": 0
+  },
+  "current_phase": "phase_0",
+  "current_batch": {
+    "index": 0,
+    "of": 0,
+    "level": 0
+  },
+  "started_at": "1970-01-01T00:00:00.000Z",
+  "finished_at": "1970-01-01T00:00:00.000Z",
+  "events": [
+    {
+      "seq": 0,
+      "ts": "1970-01-01T00:00:00.000Z",
+      "phase": "phase_0",
+      "type": "string",
+      "source_id": "string",
+      "target_id": "string",
+      "status": "pending",
+      "message": "string",
+      "error": "string"
+    }
+  ],
+  "errors_sample": [
+    {
+      "type": "string",
+      "source_id": "string",
+      "error": "string"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `listSyncJobResources`
+
+List the per-resource rows for a sync job. Supports filtering by status
+(e.g. `failed`) and cursor pagination. Used by the failures table and the
+dry-run plan view in the frontend.
+
+`GET /v1/configs/sync-jobs/{id}/resources`
+
+```ts
+const { data } = await client.listSyncJobResources({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  cursor: 'example',
+  size: 1,
+  status: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "next_cursor": "string",
+  "results": [
+    {
+      "type": "string",
+      "source_id": "string",
+      "target_id": "string",
+      "status": "pending",
+      "phase": "phase_0",
+      "attempt": 0,
+      "error": "string",
+      "updated_at": "1970-01-01T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
 ### `rebuildIndex`
 
 Rebuild the configuration index for the caller's organization.
@@ -314,6 +698,11 @@ type ConfigNode = {
   aliases?: string[]
   purposes?: string[]
   link?: string // uri
+  active?: boolean
+  blueprints?: Array<{
+    id: string
+    title: string
+  }>
   metadata?: Record<string, unknown>
 }
 ```
@@ -339,6 +728,11 @@ type ConfigListResponse = {
     aliases?: string[]
     purposes?: string[]
     link?: string // uri
+    active?: boolean
+    blueprints?: Array<{
+      id: { ... }
+      title: { ... }
+    }>
     metadata?: Record<string, unknown>
   }>
 }
@@ -362,6 +756,11 @@ type ConfigDependenciesResponse = {
     aliases?: string[]
     purposes?: string[]
     link?: string // uri
+    active?: boolean
+    blueprints?: Array<{
+      id: { ... }
+      title: { ... }
+    }>
     metadata?: Record<string, unknown>
   }>
 }
@@ -402,3 +801,264 @@ type ErrorResponse = {
   error: string
 }
 ```
+
+### `SyncJobStatus`
+
+Lifecycle status of a sync job. See `docs/sync/INTERFACES.md` for state
+transitions.
+
+
+```ts
+type SyncJobStatus = "pending" | "in_progress" | "succeeded" | "partial" | "failed" | "cancelled"
+```
+
+### `SyncDirection`
+
+Direction of the sync, derived from the source/target pane selection in the
+configuration hub UI.
+
+
+```ts
+type SyncDirection = "push" | "pull"
+```
+
+### `SyncPhase`
+
+Three-phase orchestrator phase. `phase_0` fetches source payloads,
+`phase_a` creates/matches with topological batches, `phase_a5` resolves
+derived references, `phase_b` patches with the full ID map, `finalize`
+runs cycle-breaking finalizers.
+
+
+```ts
+type SyncPhase = "phase_0" | "phase_a" | "phase_a5" | "phase_b" | "finalize"
+```
+
+### `SyncJobResourceStatus`
+
+Per-resource status. `would_*` values are produced by dry-run jobs.
+
+
+```ts
+type SyncJobResourceStatus = "pending" | "in_progress" | "created" | "patched" | "skipped" | "would_create" | "would_patch" | "would_skip_unchanged" | "would_match_heuristic" | "failed"
+```
+
+### `SyncJobRequest`
+
+Request body for `createSyncJob`. `target_auth_token` is the destination
+org's auth token and MUST NOT be persisted or logged — it is `writeOnly`.
+
+
+```ts
+type SyncJobRequest = {
+  source_org_id: string
+  target_org_id: string
+  target_auth_token: string
+  name?: string
+  dry_run?: boolean
+  include_dependencies?: boolean
+  resources: Array<{
+    type: string
+    id: string
+  }>
+}
+```
+
+### `SyncJobRetryRequest`
+
+Optional body for `retrySyncJob`. Defaults to retrying every failed
+resource of the original job.
+
+
+```ts
+type SyncJobRetryRequest = {
+  payload_overrides?: Record<string, unknown>
+}
+```
+
+### `SyncJobCounts`
+
+Aggregate counters by resource status.
+
+```ts
+type SyncJobCounts = {
+  total: number
+  pending: number
+  in_progress: number
+  succeeded: number
+  failed: number
+  skipped_unchanged: number
+}
+```
+
+### `SyncJobEvent`
+
+Activity-log entry surfaced to the frontend. Backed by the op-log rows in
+the index table (`SYNC#`<jobId>`#OP#`<seq>``).
+
+
+```ts
+type SyncJobEvent = {
+  seq: number
+  ts: string // date-time
+  phase?: "phase_0" | "phase_a" | "phase_a5" | "phase_b" | "finalize"
+  type?: string
+  source_id?: string
+  target_id?: string
+  status: "pending" | "in_progress" | "created" | "patched" | "skipped" | "would_create" | "would_patch" | "would_skip_unchanged" | "would_match_heuristic" | "failed"
+  message?: string
+  error?: string
+}
+```
+
+### `SyncJobBatch`
+
+Position within the current topological batch for the active phase.
+
+```ts
+type SyncJobBatch = {
+  index: number
+  of: number
+  level: number
+}
+```
+
+### `SyncJob`
+
+Sync job header as surfaced by `getSyncJob` and the create response. The
+canonical persistence shape is described in `docs/sync/INTERFACES.md`.
+
+
+```ts
+type SyncJob = {
+  id: string
+  name?: string
+  status: "pending" | "in_progress" | "succeeded" | "partial" | "failed" | "cancelled"
+  direction: "push" | "pull"
+  source_org_id: string
+  target_org_id: string
+  dry_run: boolean
+  counts: {
+    total: number
+    pending: number
+    in_progress: number
+    succeeded: number
+    failed: number
+    skipped_unchanged: number
+  }
+  current_phase?: "phase_0" | "phase_a" | "phase_a5" | "phase_b" | "finalize"
+  current_batch?: {
+    index: number
+    of: number
+    level: number
+  }
+  started_at: string // date-time
+  finished_at?: string // date-time
+  events?: Array<{
+    seq: number
+    ts: string // date-time
+    phase?: "phase_0" | "phase_a" | "phase_a5" | "phase_b" | "finalize"
+    type?: string
+    source_id?: string
+    target_id?: string
+    status: "pending" | "in_progress" | "created" | "patched" | "skipped" | "would_create" | "would_patch" | "would_skip_unchanged" | "would_match_heuristic" | "failed"
+    message?: string
+    error?: string
+  }>
+  errors_sample?: Array<{
+    type: string
+    source_id: string
+    error: string
+  }>
+}
+```
+
+### `SyncJobListResponse`
+
+Cursor-paginated list of sync jobs.
+
+```ts
+type SyncJobListResponse = {
+  next_cursor?: string
+  results: Array<{
+    id: string
+    name?: string
+    status: "pending" | "in_progress" | "succeeded" | "partial" | "failed" | "cancelled"
+    direction: "push" | "pull"
+    source_org_id: string
+    target_org_id: string
+    dry_run: boolean
+    counts: {
+      total: { ... }
+      pending: { ... }
+      in_progress: { ... }
+      succeeded: { ... }
+      failed: { ... }
+      skipped_unchanged: { ... }
+    }
+    current_phase?: "phase_0" | "phase_a" | "phase_a5" | "phase_b" | "finalize"
+    current_batch?: {
+      index: { ... }
+      of: { ... }
+      level: { ... }
+    }
+    started_at: string // date-time
+    finished_at?: string // date-time
+    events?: Array<{
+      seq: { ... }
+      ts: { ... }
+      phase?: { ... }
+      type?: { ... }
+      source_id?: { ... }
+      target_id?: { ... }
+      status: { ... }
+      message?: { ... }
+      error?: { ... }
+    }>
+    errors_sample?: Array<{
+      type: { ... }
+      source_id: { ... }
+      error: { ... }
+    }>
+  }>
+}
+```
+
+### `SyncJobResource`
+
+Per-resource row backed by `SyncResourcesTable`. See
+`docs/sync/INTERFACES.md` for the DDB shape.
+
+
+```ts
+type SyncJobResource = {
+  type: string
+  source_id: string
+  target_id?: string
+  status: "pending" | "in_progress" | "created" | "patched" | "skipped" | "would_create" | "would_patch" | "would_skip_unchanged" | "would_match_heuristic" | "failed"
+  phase: "phase_0" | "phase_a" | "phase_a5" | "phase_b" | "finalize"
+  attempt: number
+  error?: string
+  updated_at: string // date-time
+}
+```
+
+### `SyncJobResourceListResponse`
+
+Cursor-paginated list of sync job resources.
+
+```ts
+type SyncJobResourceListResponse = {
+  next_cursor?: string
+  results: Array<{
+    type: string
+    source_id: string
+    target_id?: string
+    status: "pending" | "in_progress" | "created" | "patched" | "skipped" | "would_create" | "would_patch" | "would_skip_unchanged" | "would_match_heuristic" | "failed"
+    phase: "phase_0" | "phase_a" | "phase_a5" | "phase_b" | "finalize"
+    attempt: number
+    error?: string
+    updated_at: string // date-time
+  }>
+}
+```