@shipeasy/openapi 3.2.0 → 3.4.0

package/spec/components/schemas/connectors.yaml

@@ -204,7 +204,7 @@ CreateCursorTriggerRequest:
     opsKey:
       type: string
       minLength: 1
-      description: Restricted Shipeasy ops key, injected into the run as `SHIPEASY_CLI_TOKEN` via the launch envVars (secret). Encrypted; never returned.
+      description: Restricted Shipeasy ops key (secret). Sent as the Bearer for the Shipeasy MCP server handed to each run inline — never in the prompt text or the run env. Encrypted; never returned.
     enabled:
       type: boolean
       default: true
@@ -308,33 +308,82 @@ ClaudeTriggerConfig:
     - routineId
   additionalProperties: false
   description: Non-secret config for a Claude trigger.
+CursorTriggerRepo:
+  type: object
+  properties:
+    url:
+      type: string
+      format: uri
+      description: "Repo the cloud agent runs against, e.g. `https://github.com/owner/repo`."
+    startingRef:
+      type: string
+      minLength: 1
+      description: "Optional branch this repo's runs start from. Omit for the repo's default branch."
+  required:
+    - url
+  additionalProperties: false
+  description: One repo a trigger runs against, with the branch its runs start from.
 CursorTriggerConfig:
   type: object
   properties:
     repoUrl:
       type: string
       format: uri
-      description: Repo the cloud agent runs against, e.g. `https://github.com/owner/repo`. Idempotency key for the connector.
+      description: "**First** repo the cloud agent runs against, e.g. `https://github.com/owner/repo`. Idempotency key for the connector, and always a mirror of `repos[0].url` when `repos` is supplied."
     startingRef:
       type: string
       minLength: 1
-      description: Optional git ref the run starts from.
+      description: Optional git ref the run starts from. Mirrors `repos[0].startingRef`. Pinned onto the Cursor agent at creation, so changing it provisions a replacement agent.
+    repos:
+      type: array
+      minItems: 1
+      items:
+        $ref: "#/CursorTriggerRepo"
+      description: "Every repo this trigger runs against, each with its own starting branch — Cursor launches ONE agent across the whole set. Omit for a single-repo trigger, which is then described by `repoUrl`/`startingRef` alone; when supplied, the first entry must match them. Changing the set re-provisions the agent (its repos are pinned at creation)."
     projectId:
       type: string
       minLength: 1
       description: Shipeasy project id the run targets.
+    agentId:
+      type: string
+      minLength: 1
+      description: "Server-managed. The reusable Cursor cloud agent (`bc-…`) Shipeasy provisions once at connect and then starts every run on. A supplied value is ignored on create; if Cursor stops recognising the id (404), the next fire provisions a replacement and stores it here."
+    fireText:
+      type: string
+      minLength: 1
+      description: "Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block."
   required:
     - repoUrl
     - projectId
   additionalProperties: false
   description: Non-secret config for a Cursor trigger.
+CopilotTriggerRepo:
+  type: object
+  properties:
+    owner:
+      type: string
+      minLength: 1
+      description: GitHub repo owner.
+    repo:
+      type: string
+      minLength: 1
+      description: GitHub repo name.
+    baseRef:
+      type: string
+      minLength: 1
+      description: "Optional base ref this repo's agent task branches from. Omit for the repo's default branch."
+  required:
+    - owner
+    - repo
+  additionalProperties: false
+  description: One repo a Copilot trigger runs against, with the base branch its tasks branch from.
 CopilotTriggerConfig:
   type: object
   properties:
     owner:
       type: string
       minLength: 1
-      description: GitHub repo owner. Together with `repo` forms the connector's idempotency key (`owner/repo`).
+      description: "**First** GitHub repo owner. Together with `repo` forms the connector's idempotency key (`owner/repo`), and both mirror `repos[0]` when `repos` is supplied."
     repo:
       type: string
       minLength: 1
@@ -342,11 +391,21 @@ CopilotTriggerConfig:
     baseRef:
       type: string
       minLength: 1
-      description: Optional base ref the agent branches from.
+      description: Optional base ref the agent branches from. Mirrors `repos[0].baseRef`.
+    repos:
+      type: array
+      minItems: 1
+      items:
+        $ref: "#/CopilotTriggerRepo"
+      description: "Every repo this trigger runs against, each with its own base branch. GitHub's agent-tasks API is per-repo, so ONE fire starts one task per entry. Omit for a single-repo trigger, which is then described by `owner`/`repo`/`baseRef` alone; when supplied, the first entry must match them."
     projectId:
       type: string
       minLength: 1
       description: Shipeasy project id the run targets.
+    fireText:
+      type: string
+      minLength: 1
+      description: "Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block."
   required:
     - owner
     - repo
@@ -368,6 +427,10 @@ JulesTriggerConfig:
       type: string
       minLength: 1
       description: Shipeasy project id the run targets.
+    fireText:
+      type: string
+      minLength: 1
+      description: "Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block."
   required:
     - source
     - projectId
@@ -452,7 +515,7 @@ UpdateCursorTriggerRequest:
     - provider
     - config
   additionalProperties: false
-  description: "Per-provider PATCH body for editing an existing `cursor_trigger` connector. `config` replaces the stored config wholesale; `name` and either credential are optional (a supplied credential rotates just that key)."
+  description: "Per-provider PATCH body for editing an existing `cursor_trigger` connector. `config` replaces the stored config wholesale, except for the server-managed keys: the provisioned `agentId` is carried over (and dropped, so a replacement agent is provisioned, when `repoUrl`/`startingRef` change), as is the last-run pointer. `name` and either credential are optional (a supplied credential rotates just that key)."
 UpdateCopilotTriggerRequest:
   type: object
   properties:

package/spec/components/schemas/events.yaml

@@ -33,7 +33,8 @@ ListEventsResponse:
               type: string
               minLength: 1
               maxLength: 64
-              description: Property key, e.g. `amount` or `plan`.
+              pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+              description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
             type:
               type: string
               enum:
@@ -49,11 +50,14 @@ ListEventsResponse:
               default: ""
               description: Human-readable description of the property.
               type: string
+            pending:
+              description: "`true` when this property was DISCOVERED in live traffic rather than declared. Nothing is recorded for it yet — a property is written to Analytics Engine only once it owns a column, and a column is allocated when an admin declares the property (include it in a `PATCH .../events/{id}` body). Approval is a gate rather than a formality: columns are finite and permanently reserved, so auto-allocating them from customer payload keys would exhaust an event's schema irreversibly."
+              type: boolean
           required:
             - name
             - type
           additionalProperties: false
-          description: One typed property declared on a catalogued event.
+          description: One typed property on a catalogued event — declared by an admin, or discovered in traffic and awaiting declaration.
         description: Typed properties declared on the event.
       pending:
         type: integer
@@ -106,7 +110,8 @@ GetEventResponse:
             type: string
             minLength: 1
             maxLength: 64
-            description: Property key, e.g. `amount` or `plan`.
+            pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+            description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
           type:
             type: string
             enum:
@@ -122,11 +127,14 @@ GetEventResponse:
             default: ""
             description: Human-readable description of the property.
             type: string
+          pending:
+            description: "`true` when this property was DISCOVERED in live traffic rather than declared. Nothing is recorded for it yet — a property is written to Analytics Engine only once it owns a column, and a column is allocated when an admin declares the property (include it in a `PATCH .../events/{id}` body). Approval is a gate rather than a formality: columns are finite and permanently reserved, so auto-allocating them from customer payload keys would exhaust an event's schema irreversibly."
+            type: boolean
         required:
           - name
           - type
         additionalProperties: false
-        description: One typed property declared on a catalogued event.
+        description: One typed property on a catalogued event — declared by an admin, or discovered in traffic and awaiting declaration.
       description: Typed properties declared on the event.
     pending:
       type: integer
@@ -150,8 +158,8 @@ CreateEventRequest:
   properties:
     name:
       type: string
-      pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_\-.]{0,127}$
-      description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 128 chars. Immutable after create — this is the handle metric queries reference.
+      pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_\-.]{0,49}$
+      description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 50 characters. The cap is the Analytics Engine index budget — 96 bytes total, less a 36-byte project UUID and a separator — and the API has always enforced 50 while this spec advertised 128. The charset is ASCII, so characters and bytes are the same count. Immutable after create — this is the handle metric queries reference.
     folder:
       $ref: ./common.yaml#/Folder
     description:
@@ -168,7 +176,8 @@ CreateEventRequest:
             type: string
             minLength: 1
             maxLength: 64
-            description: Property key, e.g. `amount` or `plan`.
+            pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+            description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
           type:
             type: string
             enum:
@@ -225,7 +234,8 @@ UpdateEventRequest:
             type: string
             minLength: 1
             maxLength: 64
-            description: Property key, e.g. `amount` or `plan`.
+            pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+            description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
           type:
             type: string
             enum:
@@ -276,7 +286,8 @@ ApproveEventRequest:
             type: string
             minLength: 1
             maxLength: 64
-            description: Property key, e.g. `amount` or `plan`.
+            pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+            description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
           type:
             type: string
             enum:

package/spec/components/schemas/keys.yaml

@@ -60,6 +60,11 @@ KeyRecord:
         - type: string
         - type: "null"
       description: Human label for the key. `null` for unnamed dashboard mints; programmatic mints auto-name themselves.
+    description:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Free-text note recording what the key is for (the service that holds it, the rotation owner, the ticket it was minted under). Display only — `null` unless someone set it via `PATCH /api/admin/keys/{id}`.
     scopes:
       anyOf:
         - type: array
@@ -72,6 +77,14 @@ KeyRecord:
         - type: string
         - type: "null"
       description: Last 4 characters of the raw token, so the dashboard mask is matchable against the held key. `null` for keys minted before this column.
+    origin:
+      type: string
+      enum:
+        - cli
+        - mobile
+        - dashboard
+        - api
+      description: Where the key was minted. `cli` (a signed-in CLI session from device auth), `mobile` (a mobile app login), `dashboard` (the "New API key" dialog) or `api` (minted with another key — CLI, MCP, agents). Set at mint time; keys that predate the column were backfilled from their label, defaulting to `dashboard`.
   required:
     - id
     - type
@@ -81,8 +94,34 @@ KeyRecord:
     - expires_at
     - created_by_email
     - name
+    - description
     - scopes
     - last4
+    - origin
+  additionalProperties: false
+UpdateKeyRequest:
+  type: object
+  description: |-
+    Body for `PATCH /api/admin/keys/{id}`. Only the key's **label** is editable — `name` and `description`.
+
+    Everything that gives a key its authority (`type`, `env`, `scopes`, `expires_at`) is fixed at mint: those are the isolation boundary the worker derives the read env and permissions from, so changing them would silently re-point a credential that is already deployed. Rotate instead — mint a replacement and revoke the old key.
+
+    Omitted fields are left untouched; send `null` to clear one.
+  properties:
+    name:
+      anyOf:
+        - type: string
+          minLength: 1
+          maxLength: 160
+        - type: "null"
+      description: New human label, or `null` to clear it. Same 160-char budget as create — provenance labels are composed, not typed.
+    description:
+      anyOf:
+        - type: string
+          minLength: 1
+          maxLength: 500
+        - type: "null"
+      description: New free-text note, or `null` to clear it.
   additionalProperties: false
 CreateKeyRequest:
   type: object