@epilot/sdk 2.8.3 → 2.8.4

package/definitions/blueprint-manifest.json

@@ -41,6 +41,10 @@
     {
       "name": "Patches",
       "description": "Manage blueprint patches for mass rollouts"
+    },
+    {
+      "name": "Uniqueness Criteria",
+      "description": "Configure per-org field sets used to match existing resources during install"
     }
   ],
   "security": [
@@ -2964,6 +2968,118 @@
         }
       }
     },
+    "/v3/blueprint-manifest/blueprints/{blueprint_id}/deployments/{job_id}:restore": {
+      "post": {
+        "operationId": "restoreBlueprintDeploymentV3",
+        "summary": "Restore a specific deployment by job_id",
+        "description": "Roll a deployment back to its pre-install state. Two phases:\n\n  1. Upsert — re-applies the captured payloads via snapshot-api's\n     `:restore` (server-side; runs config-engine.apply with captured\n     target ids pre-seeded). Skipped for pure-create deployments\n     whose snapshot was empty.\n  2. Delete sweep — for lineage rows of this blueprint instance not\n     present in the snapshot's captured set, deletes the live\n     resource via the type's adapter. Co-ownership / drift /\n     no-delete-capability skip the entry with the corresponding\n     reason.\n\nResolves `(blueprint_id, job_id)` to the entry in\n`Blueprint.deployments[]` and reads its `snapshot_id` and\n`destination_blueprint_id` — the caller never needs to handle\nsnapshot ids directly.\n\nAsync — returns 202 with a job id. Poll the job to track progress.\nThe per-instance lock (`installation_status === 'IN_PROGRESS'`)\nrejects concurrent installs or restores with 409.\n",
+        "tags": [
+          "Blueprints"
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "blueprint_id",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/BlueprintID"
+            }
+          },
+          {
+            "in": "path",
+            "name": "job_id",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/BlueprintJobID"
+            }
+          }
+        ],
+        "responses": {
+          "202": {
+            "description": "Restore job started",
+            "headers": {
+              "Location": {
+                "description": "URL to poll the job",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "job_id": {
+                      "$ref": "#/components/schemas/BlueprintJobID"
+                    },
+                    "blueprint_instance_id": {
+                      "$ref": "#/components/schemas/BlueprintID"
+                    },
+                    "snapshot_id": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Deployment has no snapshot, or the snapshot is not in a `completed` state."
+          },
+          "404": {
+            "description": "Blueprint not found, or no deployment with the given job_id on this blueprint."
+          },
+          "409": {
+            "description": "Another install or restore is in flight for this blueprint instance."
+          }
+        }
+      }
+    },
+    "/v3/blueprint-manifest/blueprints/{blueprint_id}/deployments/{job_id}/restore-preview": {
+      "get": {
+        "operationId": "getRestorePreview",
+        "summary": "Predicted outcome of reverting a deployment",
+        "description": "Computes what would happen if the user triggered a restore on this\ndeployment, without performing any writes. The forecast uses the\nsnapshot's captured resources (when present) plus the current lineage\nstate plus per-adapter gates (co-ownership, no-delete-capability,\nheuristic-match, drift when wired).\n\nIdempotent and side-effect free. Safe to call repeatedly. The result\nmay shift between calls if operators edit destination resources or\nanother blueprint adopts a shared resource in the meantime.\n",
+        "tags": [
+          "Blueprints"
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "blueprint_id",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/BlueprintID"
+            }
+          },
+          {
+            "in": "path",
+            "name": "job_id",
+            "required": true,
+            "description": "The install job whose deployment is being previewed.",
+            "schema": {
+              "$ref": "#/components/schemas/BlueprintJobID"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Predicted outcome. `failed`-action items are absent here — the\npreview can't forecast errors.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RestoreOutcome"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Blueprint or deployment not found."
+          }
+        }
+      }
+    },
     "/v3/blueprint-manifest/blueprints/{blueprint_id}/lineage": {
       "get": {
         "operationId": "getBlueprintLineageV3",
@@ -3006,10 +3122,184 @@
           }
         }
       }
+    },
+    "/v1/blueprint-manifest/uniqueness-criteria": {
+      "get": {
+        "operationId": "listUniquenessCriteria",
+        "summary": "listUniquenessCriteria",
+        "description": "List all custom uniqueness criteria configured for the caller's organization.\nThese overrides are applied during install (V2 and V3) when matching incoming\nresources against existing ones in the destination org, replacing the default\nper-resource-type field set with the caller's chosen fields (AND-combined).\n",
+        "tags": [
+          "Uniqueness Criteria"
+        ],
+        "responses": {
+          "200": {
+            "description": "All configured criteria for the org",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/UniquenessCriteria"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/blueprint-manifest/uniqueness-criteria/{resource_type}": {
+      "parameters": [
+        {
+          "in": "path",
+          "required": true,
+          "name": "resource_type",
+          "schema": {
+            "$ref": "#/components/schemas/UniquenessCriteriaResourceType"
+          }
+        }
+      ],
+      "get": {
+        "operationId": "getUniquenessCriteria",
+        "summary": "getUniquenessCriteria",
+        "description": "Get the configured uniqueness criteria for a specific resource type, if any.",
+        "tags": [
+          "Uniqueness Criteria"
+        ],
+        "responses": {
+          "200": {
+            "description": "Configured criteria for the resource type",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UniquenessCriteria"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No custom criteria configured (defaults will be used)"
+          }
+        }
+      },
+      "put": {
+        "operationId": "putUniquenessCriteria",
+        "summary": "putUniquenessCriteria",
+        "description": "Set or replace the uniqueness criteria for a resource type. The provided fields\nmust be valid attributes on the resource's schema (the UI typically loads the\nschema to populate options). All listed fields are AND-combined during matching.\n",
+        "tags": [
+          "Uniqueness Criteria"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "fields"
+                ],
+                "properties": {
+                  "fields": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Stored criteria",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UniquenessCriteria"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid resource type or field list"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteUniquenessCriteria",
+        "summary": "deleteUniquenessCriteria",
+        "description": "Remove the custom criteria for a resource type, reverting to the default fields.",
+        "tags": [
+          "Uniqueness Criteria"
+        ],
+        "responses": {
+          "204": {
+            "description": "Criteria deleted (defaults will be used)"
+          }
+        }
+      }
     }
   },
   "components": {
     "schemas": {
+      "UniquenessCriteriaResourceType": {
+        "type": "string",
+        "description": "Resource type for which custom uniqueness criteria can be configured.",
+        "enum": [
+          "emailtemplate",
+          "product",
+          "price",
+          "tax",
+          "coupon",
+          "product_recommendation",
+          "file",
+          "document_template",
+          "schema",
+          "taxonomy",
+          "notification_template",
+          "family",
+          "permission",
+          "journey"
+        ]
+      },
+      "UniquenessCriteria": {
+        "type": "object",
+        "required": [
+          "org_id",
+          "resource_type",
+          "fields",
+          "updated_at"
+        ],
+        "properties": {
+          "org_id": {
+            "type": "string"
+          },
+          "resource_type": {
+            "$ref": "#/components/schemas/UniquenessCriteriaResourceType"
+          },
+          "fields": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            }
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_by": {
+            "type": "string"
+          }
+        }
+      },
       "LineageEntry": {
         "type": "object",
         "properties": {
@@ -3292,6 +3582,104 @@
                     "PARTIAL_SUCCESS",
                     "FAILED"
                   ]
+                },
+                "restore_details": {
+                  "type": "object",
+                  "description": "Restore lifecycle metadata for this deployment.",
+                  "properties": {
+                    "has_revertible_changes": {
+                      "type": "boolean",
+                      "description": "Whether this sync changed destination resources in a way that can\nbe reverted. `false` means the sync completed without create,\nupdate, internal-update, or delete impacts, so there is no revert\naction to offer.\n"
+                    },
+                    "resource_impact_summary": {
+                      "type": "object",
+                      "description": "Counts of resource impact values from the V3 apply result.",
+                      "properties": {
+                        "create": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
+                        "update": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
+                        "internal_update": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
+                        "delete": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
+                        "no_op": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
+                        "ignored": {
+                          "type": "integer",
+                          "minimum": 0
+                        }
+                      }
+                    },
+                    "last_restore_job_id": {
+                      "type": "string",
+                      "description": "BlueprintInstallationJob id of the most recent restore that ran\nagainst this deployment. Used by the FE to keep the restore-status\nbadge visible across page reloads. Frontends poll this job to\nrender the latest restore outcome.\n"
+                    },
+                    "last_restore_at": {
+                      "type": "string",
+                      "format": "date-time",
+                      "description": "Timestamp of the most recent restore that ran against this\ndeployment. Stamped when the restore sweep finishes. Used by the\nFE to show when a sync was reverted.\n"
+                    },
+                    "last_restored_by": {
+                      "type": "object",
+                      "description": "Identity of the caller who triggered the most recent restore.\nStamped when the restore sweep finishes. Used by the FE to show\nwho reverted a sync.\n",
+                      "properties": {
+                        "name": {
+                          "type": "string",
+                          "description": "Display name (email or token name) of the restorer."
+                        },
+                        "user_id": {
+                          "type": "string",
+                          "description": "User id of the restorer, when triggered by a user."
+                        }
+                      }
+                    },
+                    "status": {
+                      "type": "string",
+                      "description": "Computed server-side from `(job_id, restore_details.last_restore_job_id, installation_status)`.\n`available` when the deployment is restorable but has no prior\nrestore (including pure-create deployments without `snapshot_id`,\nreverted via sweep-only);\n`in_progress` while an install or restore is running on this\nblueprint instance;\n`restored` / `partially_restored` / `restore_failed` reflect the\nterminal status of the job referenced by `last_restore_job_id`;\n`unavailable` means there is no revert action, for example\nmalformed deployment rows missing `job_id` or no-change syncs.\n",
+                      "enum": [
+                        "available",
+                        "in_progress",
+                        "restored",
+                        "partially_restored",
+                        "restore_failed",
+                        "unavailable"
+                      ]
+                    }
+                  }
+                },
+                "has_revertible_changes": {
+                  "type": "boolean",
+                  "deprecated": true,
+                  "description": "Deprecated. Use `restore_details.has_revertible_changes`.\n"
+                },
+                "last_restore_job_id": {
+                  "type": "string",
+                  "deprecated": true,
+                  "description": "Deprecated. Use `restore_details.last_restore_job_id`.\n"
+                },
+                "restore_status": {
+                  "type": "string",
+                  "deprecated": true,
+                  "description": "Deprecated. Use `restore_details.status`.\n",
+                  "enum": [
+                    "available",
+                    "in_progress",
+                    "restored",
+                    "partially_restored",
+                    "restore_failed",
+                    "unavailable"
+                  ]
                 }
               }
             }
@@ -3884,6 +4272,12 @@
           {
             "type": "object",
             "properties": {
+              "job_type": {
+                "type": "string",
+                "enum": [
+                  "export"
+                ]
+              },
               "blueprint_id": {
                 "$ref": "#/components/schemas/BlueprintID"
               },
@@ -3911,6 +4305,12 @@
           {
             "type": "object",
             "properties": {
+              "job_type": {
+                "type": "string",
+                "enum": [
+                  "install"
+                ]
+              },
               "source_blueprint_id": {
                 "$ref": "#/components/schemas/BlueprintID"
               },
@@ -3970,6 +4370,64 @@
           }
         ]
       },
+      "BlueprintRestoreJob": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/CommonBlueprintJobFields"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "job_type": {
+                "type": "string",
+                "enum": [
+                  "restore"
+                ]
+              },
+              "destination_blueprint_id": {
+                "$ref": "#/components/schemas/BlueprintID"
+              },
+              "destination_org_id": {
+                "type": "string"
+              },
+              "install_job_id": {
+                "type": "string",
+                "nullable": true,
+                "description": "The install job whose deployment is being reverted. Maps back\nto the entry in `Blueprint.deployments[]`.\n"
+              },
+              "snapshot_id": {
+                "type": "string",
+                "nullable": true,
+                "description": "The snapshot driving Phase 1 of the restore. Null for sweep-only\nrestores (pure-create deployments with no captured manifest).\n"
+              },
+              "sync_engine": {
+                "type": "string",
+                "enum": [
+                  "v3"
+                ]
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "IN_PROGRESS",
+                  "SUCCESS",
+                  "PARTIAL_SUCCESS",
+                  "FAILED"
+                ]
+              },
+              "restore_result": {
+                "nullable": true,
+                "description": "Absent while the job is still IN_PROGRESS.",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/RestoreOutcome"
+                  }
+                ]
+              }
+            }
+          }
+        ]
+      },
       "V3ResourceProgressEntry": {
         "type": "object",
         "required": [
@@ -4009,6 +4467,84 @@
           }
         }
       },
+      "RestoreOutcomeItem": {
+        "type": "object",
+        "required": [
+          "lineage_id",
+          "type",
+          "action"
+        ],
+        "properties": {
+          "lineage_id": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string",
+            "nullable": true
+          },
+          "target_id": {
+            "type": "string",
+            "nullable": true
+          },
+          "action": {
+            "type": "string",
+            "description": "On `restore-preview`: the action the restore would take.\nOn `restore_result`: the action that was applied.\n`failed` only appears on `restore_result`.\n",
+            "enum": [
+              "restore",
+              "delete",
+              "skip",
+              "failed"
+            ]
+          },
+          "reason": {
+            "type": "string",
+            "nullable": true,
+            "description": "Only set when `action == skip`.",
+            "enum": [
+              "modified",
+              "co_owned",
+              "delete_unsupported",
+              "heuristic_match"
+            ]
+          },
+          "last_synced_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "Only set when `reason == modified`. From the lineage row's last install write."
+          },
+          "current_updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "Only set when `reason == modified`. From the destination resource's current state."
+          },
+          "error_message": {
+            "type": "string",
+            "nullable": true,
+            "description": "Only set when `action == failed`."
+          }
+        }
+      },
+      "RestoreOutcome": {
+        "type": "object",
+        "properties": {
+          "snapshot_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "The snapshot driving Phase 1 of the restore. Null/absent for\nsweep-only restores (pure-create deployments with no captured\nmanifest).\n"
+          },
+          "resources": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RestoreOutcomeItem"
+            }
+          }
+        }
+      },
       "BlueprintJob": {
         "oneOf": [
           {
@@ -4017,6 +4553,9 @@
           {
             "$ref": "#/components/schemas/BlueprintInstallationJob"
           },
+          {
+            "$ref": "#/components/schemas/BlueprintRestoreJob"
+          },
           {
             "$ref": "#/components/schemas/BlueprintDependenciesSyncJob"
           },
@@ -4026,7 +4565,18 @@
           {
             "$ref": "#/components/schemas/BlueprintVerificationJob"
           }
-        ]
+        ],
+        "discriminator": {
+          "propertyName": "job_type",
+          "mapping": {
+            "export": "#/components/schemas/BlueprintExportJob",
+            "install": "#/components/schemas/BlueprintInstallationJob",
+            "restore": "#/components/schemas/BlueprintRestoreJob",
+            "dependencies_sync": "#/components/schemas/BlueprintDependenciesSyncJob",
+            "validate": "#/components/schemas/BlueprintValidateJob",
+            "verification": "#/components/schemas/BlueprintVerificationJob"
+          }
+        }
       },
       "BlueprintDependenciesSyncJob": {
         "allOf": [
@@ -4036,6 +4586,12 @@
           {
             "type": "object",
             "properties": {
+              "job_type": {
+                "type": "string",
+                "enum": [
+                  "dependencies_sync"
+                ]
+              },
               "blueprint_id": {
                 "$ref": "#/components/schemas/BlueprintID"
               },
@@ -4060,6 +4616,12 @@
           {
             "type": "object",
             "properties": {
+              "job_type": {
+                "type": "string",
+                "enum": [
+                  "validate"
+                ]
+              },
               "blueprint_id": {
                 "$ref": "#/components/schemas/BlueprintID"
               },
@@ -4094,6 +4656,12 @@
           {
             "type": "object",
             "properties": {
+              "job_type": {
+                "type": "string",
+                "enum": [
+                  "verification"
+                ]
+              },
               "source_org_id": {
                 "type": "string"
               },
@@ -4111,6 +4679,7 @@
                 "enum": [
                   "IN_PROGRESS",
                   "SUCCESS",
+                  "PARTIAL_SUCCESS",
                   "FAILED"
                 ]
               },
@@ -4142,6 +4711,7 @@
             "enum": [
               "IN_PROGRESS",
               "SUCCESS",
+              "PARTIAL_SUCCESS",
               "FAILED"
             ]
           },

package/definitions/snapshot-runtime.json

@@ -1 +1 @@
-{"s":"https://snapshot.sls.epilot.io","o":[["createSnapshot","post","/v1/snapshots",null,1],["listSnapshots","get","/v1/snapshots",[["cursor","q"],["size","q"],["resource","q"]]],["getSnapshot","get","/v1/snapshots/{id}"],["deleteSnapshot","delete","/v1/snapshots/{id}"],["restoreSnapshot","post","/v1/snapshots/{id}:restore"],["listSnapshotResources","get","/v1/snapshots/{id}/resources"],["getSnapshotResource","get","/v1/snapshots/{id}/resources/{lineage_id}"],["listDependencies","post","/v1/snapshots:list-dependencies",null,1]],"v":"3.0.3","pp":{"/v1/snapshots/{id}":[["id","p",true]],"/v1/snapshots/{id}:restore":[["id","p",true]],"/v1/snapshots/{id}/resources":[["id","p",true]],"/v1/snapshots/{id}/resources/{lineage_id}":[["id","p",true],["lineage_id","p",true]]}}
+{"s":"https://snapshot.sls.epilot.io","o":[["createSnapshot","post","/v1/snapshots",null,1],["listSnapshots","get","/v1/snapshots",[["cursor","q"],["size","q"],["resource","q"]]],["getSnapshot","get","/v1/snapshots/{id}"],["deleteSnapshot","delete","/v1/snapshots/{id}"],["restoreSnapshot","post","/v1/snapshots/{id}:restore",null,1],["listSnapshotResources","get","/v1/snapshots/{id}/resources"],["getSnapshotResource","get","/v1/snapshots/{id}/resources/{lineage_id}"],["listDependencies","post","/v1/snapshots:list-dependencies",null,1]],"v":"3.0.3","pp":{"/v1/snapshots/{id}":[["id","p",true]],"/v1/snapshots/{id}:restore":[["id","p",true]],"/v1/snapshots/{id}/resources":[["id","p",true]],"/v1/snapshots/{id}/resources/{lineage_id}":[["id","p",true],["lineage_id","p",true]]}}