@epilot/cli 0.1.150 → 0.1.152

package/definitions/journey.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Journey API",
     "description": "API to configure journeys",
-    "version": "1.4.3"
+    "version": "1.5.0"
   },
   "security": [
     {
@@ -117,7 +117,7 @@
           {
             "name": "version",
             "in": "query",
-            "description": "DynamoDB version to fetch. `0` (default) is the live row; positive integers are historical snapshots created on each save. Note: this is distinct from the `revisions` counter on the row body.\n",
+            "description": "Revision row to read. `0` (default) is the journey record, the published version every customer receives; a positive integer `n` reads revision row `n` (used by config-engine for history reads). Distinct from the `revisions` counter on the body, which is the legacy change counter of the published version. Versioning metadata is only available via `publish-state`.\n",
             "required": false,
             "schema": {
               "type": "integer",
@@ -207,6 +207,309 @@
         }
       }
     },
+    "/v1/journey/configuration/{id}/revisions": {
+      "post": {
+        "operationId": "createJourneyRevision",
+        "summary": "createJourneyRevision",
+        "description": "Creates a revision: an immutable copy of the complete journey configuration, identified by `revision_id`. Nothing customers receive changes; the revision only becomes the published version when it is published. The payload is complete and is not merged against the journey record or the previous revision. The entity datasource set of the revision is stored separately through the datasources API under the same `revision_id`.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n",
+        "tags": [
+          "Journeys"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "Journey ID",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "509cdffe-424f-457a-95c2-9708c304ce77"
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Complete journey configuration for the revision",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/JourneyRevisionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Revision created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/JourneyRevisionSummary"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid payload"
+          },
+          "403": {
+            "description": "No permission to edit the journey"
+          },
+          "404": {
+            "description": "Journey versioning not enabled for the organization, or journey not found"
+          },
+          "409": {
+            "description": "`parent_revision_id` is not the latest revision: the journey was saved since the editor loaded it. The body carries the current latest revision.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/JourneyRevisionConflict"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "listJourneyRevisions",
+        "summary": "listJourneyRevisions",
+        "description": "Lists the journey's revision history, newest first. Metadata only, no configuration payload. `is_published` says whether a revision is the published version right now, which is a different question from `published_at`, which records the last time it was published.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n",
+        "tags": [
+          "Journeys"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "Journey ID",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "509cdffe-424f-457a-95c2-9708c304ce77"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Maximum number of revisions to return",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 25
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "description": "Opaque pagination cursor, taken from a previous response's `next_cursor`",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Revision history",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/JourneyRevisionList"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid query parameters"
+          },
+          "403": {
+            "description": "No permission to edit the journey"
+          },
+          "404": {
+            "description": "Journey versioning not enabled for the organization, or journey not found"
+          }
+        }
+      }
+    },
+    "/v1/journey/configuration/{id}/revisions/{revision_id}": {
+      "get": {
+        "operationId": "getJourneyRevision",
+        "summary": "getJourneyRevision",
+        "description": "Returns one revision with its full configuration, in the shape the builder holds a journey in, so it can be loaded straight into the editor as unsaved changes. Reading a revision changes nothing; a client persists it, if at all, by posting it back to `POST .../revisions`.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n",
+        "tags": [
+          "Journeys"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "Journey ID",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "509cdffe-424f-457a-95c2-9708c304ce77"
+            }
+          },
+          {
+            "name": "revision_id",
+            "in": "path",
+            "description": "Revision ID, as returned in a revision summary",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "example": "42"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The revision with its configuration",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/JourneyRevision"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "No permission to edit the journey"
+          },
+          "404": {
+            "description": "Journey versioning not enabled for the organization, or journey or revision not found"
+          }
+        }
+      }
+    },
+    "/v1/journey/configuration/{id}/publish": {
+      "post": {
+        "operationId": "publishJourneyRevision",
+        "summary": "publishJourneyRevision",
+        "description": "Makes one revision the published version, the one customers receive, in a single transaction: the revision's configuration is copied onto the journey record, its datasource set onto the published datasources, and `name`, `description`, `published_at` and `published_by` are stamped onto the revision. Any revision can be published, old or new, so publishing an older revision is the rollback.\n\n`name` is generated server-side when omitted, so every published revision carries one; an omitted name never replaces a name a previous publish already set. `settings.isActive` is never changed by a publish.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n",
+        "tags": [
+          "Journeys"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "Journey ID",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "509cdffe-424f-457a-95c2-9708c304ce77"
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "The revision to publish",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PublishRevisionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Revision published",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PublishResult"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid payload"
+          },
+          "403": {
+            "description": "No permission to edit the journey"
+          },
+          "404": {
+            "description": "Journey versioning not enabled for the organization, or journey or revision not found"
+          },
+          "409": {
+            "description": "The journey record changed between read and publish, please try again"
+          }
+        }
+      }
+    },
+    "/v1/journey/configuration/{id}/publish-state": {
+      "get": {
+        "operationId": "getJourneyPublishState",
+        "summary": "getJourneyPublishState",
+        "description": "Answers which revision is the published version without paging through the history. A journey that has not adopted versioning yet returns `200` with `published_revision_id: null`, not `404`.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n",
+        "tags": [
+          "Journeys"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "Journey ID",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "509cdffe-424f-457a-95c2-9708c304ce77"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Publish state",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/JourneyPublishState"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "No permission to edit the journey"
+          },
+          "404": {
+            "description": "Journey versioning not enabled for the organization, or journey not found"
+          }
+        }
+      }
+    },
     "/v1/journey/configuration/{id}/environment": {
       "get": {
         "operationId": "getJourneyEnvironment",
@@ -829,7 +1132,7 @@
           {
             "name": "version",
             "in": "query",
-            "description": "DynamoDB version to fetch. `0` (default) is the live row; positive integers are historical snapshots created on each save. Note: this is distinct from the `revisions` counter on the row body.\n",
+            "description": "Revision row to read. `0` (default) is the journey record, the published version every customer receives; a positive integer `n` reads revision row `n` (used by config-engine for history reads). Distinct from the `revisions` counter on the body, which is the legacy change counter of the published version. Versioning metadata is only available via `publish-state`.\n",
             "required": false,
             "schema": {
               "type": "integer",
@@ -2555,10 +2858,12 @@
             "type": "string"
           },
           "version": {
-            "type": "number"
+            "type": "number",
+            "description": "Revision row number of this item. `0` is the journey record, the published version.\n"
           },
           "revisions": {
-            "type": "number"
+            "type": "number",
+            "description": "Legacy change counter of the published version, kept for compatibility: bumped whenever the published version changes and used for optimistic concurrency on `PUT`, by submissions (`journey_context.journey_revision`) and by save-and-continue. Saving a revision never changes it. Versioning metadata is only available via `publish-state`.\n"
           }
         },
         "required": [
@@ -2568,6 +2873,219 @@
           "revisions"
         ]
       },
+      "JourneyRevisionRequest": {
+        "description": "The complete journey configuration a revision is created from, same shape as the `PUT` body. Server-managed attributes of the journey record (`revisions`, `version`, publish metadata) are ignored.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/JourneyCreationRequest"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "parent_revision_id": {
+                "type": "string",
+                "description": "The revision the editor started from. When present and not the latest revision the save is rejected with `409`; absent skips the check.\n",
+                "example": "41"
+              },
+              "based_on_revision_id": {
+                "type": "string",
+                "description": "Provenance, not configuration: the revision that was loaded into the editor before this save, when it was an older one.\n",
+                "example": "37"
+              },
+              "mapping_config_version": {
+                "type": "number",
+                "description": "Version of the entity-mapping config stored alongside this revision. Publishing the revision points the journey's automation at it.\n",
+                "example": 12
+              }
+            }
+          }
+        ]
+      },
+      "PublishRevisionRequest": {
+        "type": "object",
+        "required": [
+          "revision_id"
+        ],
+        "properties": {
+          "revision_id": {
+            "type": "string",
+            "example": "42"
+          },
+          "name": {
+            "type": "string",
+            "maxLength": 255,
+            "description": "Name stamped onto the revision being published. Optional: when omitted the server generates one, so every revision that has ever been published carries a name. An omitted name never replaces a name a previous publish already set; an explicit one does.\n",
+            "example": "Summer campaign"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 8000,
+            "description": "Optional description stamped onto the revision at publish time"
+          }
+        }
+      },
+      "JourneyRevisionSummary": {
+        "type": "object",
+        "required": [
+          "revision_id",
+          "created_at",
+          "is_published"
+        ],
+        "properties": {
+          "revision_id": {
+            "type": "string",
+            "description": "Opaque identifier of the revision. Moves on every save.",
+            "example": "42"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "created_by": {
+            "type": "string",
+            "description": "User id of the author. Absent for revisions recorded from writes without a user, e.g. blueprint installs.\n"
+          },
+          "name": {
+            "type": "string",
+            "description": "Set at publish time only, so present if and only if this revision has been published at least once.\n",
+            "example": "Summer campaign"
+          },
+          "description": {
+            "type": "string"
+          },
+          "published_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The last time this revision was published. Not the same question as `is_published`: a revision that was the published version yesterday still carries a `published_at`.\n"
+          },
+          "is_published": {
+            "type": "boolean",
+            "description": "Whether this revision is the published version right now."
+          },
+          "mapping_config_version": {
+            "type": "number",
+            "description": "Version of the entity-mapping config stored alongside this revision.",
+            "example": 12
+          }
+        }
+      },
+      "JourneyRevisionList": {
+        "type": "object",
+        "required": [
+          "results"
+        ],
+        "properties": {
+          "results": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/JourneyRevisionSummary"
+            }
+          },
+          "next_cursor": {
+            "type": "string",
+            "description": "Opaque cursor to pass back as `cursor` to fetch the next page. Absent when the client has reached the end of the history.\n"
+          }
+        }
+      },
+      "JourneyRevision": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/JourneyRevisionSummary"
+          },
+          {
+            "type": "object",
+            "required": [
+              "configuration"
+            ],
+            "properties": {
+              "configuration": {
+                "description": "The journey configuration as it was saved in this revision, in the shape the builder holds a journey in.\n",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/Journey"
+                  }
+                ]
+              }
+            }
+          }
+        ]
+      },
+      "JourneyRevisionConflict": {
+        "type": "object",
+        "required": [
+          "message",
+          "latest_revision"
+        ],
+        "properties": {
+          "message": {
+            "type": "string",
+            "example": "The journey has been saved since your editor loaded it"
+          },
+          "latest_revision": {
+            "$ref": "#/components/schemas/JourneyRevisionSummary"
+          }
+        }
+      },
+      "JourneyPublishState": {
+        "type": "object",
+        "required": [
+          "journey_id",
+          "published_revision_id"
+        ],
+        "properties": {
+          "journey_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "published_revision_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "An explicit `null` means the journey has not adopted versioning yet: it exists, customers receive its journey record, and no revision is the published version.\n",
+            "example": "42"
+          },
+          "published_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "published_by": {
+            "type": "string"
+          }
+        }
+      },
+      "PublishResult": {
+        "type": "object",
+        "required": [
+          "revision_id",
+          "name",
+          "published_at",
+          "post_publish_warnings"
+        ],
+        "properties": {
+          "revision_id": {
+            "type": "string",
+            "example": "42"
+          },
+          "name": {
+            "type": "string",
+            "description": "The name now on the revision: the one sent in the request, the one a previous publish set when this request omitted `name`, or the server-generated default.\n",
+            "example": "Summer campaign"
+          },
+          "published_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "published_by": {
+            "type": "string"
+          },
+          "post_publish_warnings": {
+            "type": "array",
+            "description": "Names any best-effort side effect that failed after the publish itself succeeded, e.g. the journey entity sync, so a caller can say \"published, but the entity did not update\".\n",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
       "JourneyValidationResponse": {
         "type": "object",
         "properties": {
@@ -3035,6 +3553,9 @@
   "servers": [
     {
       "url": "https://journey-config.sls.epilot.io"
+    },
+    {
+      "url": "https://journey-config.dev.sls.epilot.io"
     }
   ]
 }