@shipeasy/openapi 1.5.0 → 2.1.0

package/spec/paths/gate-templates.yaml

@@ -0,0 +1,263 @@
+/api/admin/gates/templates:
+  get:
+    operationId: listGateTemplates
+    summary: List gate templates
+    description: |-
+      Returns the merged targeting-rule template catalog — read-only **built-ins first** (the `@team`/`@owner` audience aliases, country, email-domain, region presets, …), then this project's **customer** templates. Each item carries a `rules: [{ attr, op, value }]` definition; the alias templates carry a symbol value (`email in ["@team"]`) that the SDK expands to the resolved email list at rebuild.
+
+      **Turn "launch X in country Y" into a gated flag:** list templates (optionally with `query`), take the matching template's `rules`, substitute the concrete value(s), and pass them as the `rules` arg of `release_flags_create`.
+
+      The catalog is small and bounded, so the full merged set is returned in one page — this endpoint is **not** paginated (`next_cursor` is always `null`; there are no `limit`/`cursor` params).
+    tags:
+      - Templates
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: query
+        in: query
+        required: false
+        description: Case-insensitive substring filter over each template's `name` + `description`. Omit to return the whole catalog.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: List gate templates
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gate-templates.yaml#/ListGateTemplatesResponse
+            example:
+              data:
+                - id: country
+                  name: Country is
+                  description: Target by ISO country code (resolve from GeoIP at the SDK edge before evaluating).
+                  category: condition
+                  auto: true
+                  builtin: true
+                  iconKey: globe
+                  rules:
+                    - attr: country
+                      op: in
+                      value:
+                        - DE
+                        - FR
+                        - IT
+                  createdAt: null
+                  updatedAt: null
+              next_cursor: null
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: createGateTemplate
+    summary: Create a gate template
+    description: |-
+      Creates a per-project (customer) targeting-rule template. Built-ins are read-only and cannot be created here. Returns `409` if a template with this `name` already exists in the project.
+    tags:
+      - Templates
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/gate-templates.yaml#/CreateGateTemplateRequest
+          examples:
+            enterpriseBeta:
+              summary: Save an "enterprise plan" condition
+              value:
+                name: Enterprise beta
+                description: Our enterprise plan on the beta ring.
+                category: condition
+                rules:
+                  - attr: plan
+                    op: eq
+                    value: enterprise
+    responses:
+      "201":
+        description: Create a gate template
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gate-templates.yaml#/CreateGateTemplateResponse
+            example:
+              id: gtpl_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: Enterprise beta
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - ALREADY_EXISTS
+      - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - name
+/api/admin/gates/templates/{id}:
+  get:
+    operationId: getGateTemplate
+    summary: Get one gate template
+    description: Returns a single template by its `id` — a built-in slug (`country`) or a customer `gtpl_…` id.
+    tags:
+      - Templates
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Built-in slug (`country`) or customer template id (`gtpl_…`).
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Get one gate template
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gate-templates.yaml#/GateTemplate
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: get
+      positional:
+        - id
+  patch:
+    operationId: updateGateTemplate
+    summary: Update a gate template
+    description: |-
+      Partial update of a **customer** template. `rules` replaces the list wholesale. Returns `409` if `id` names a read-only built-in template.
+    tags:
+      - Templates
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Customer template id (`gtpl_…`) or its `name`.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/gate-templates.yaml#/UpdateGateTemplateRequest
+          examples:
+            rename:
+              summary: Rename + retarget
+              value:
+                name: Enterprise GA
+                rules:
+                  - attr: plan
+                    op: in
+                    value:
+                      - enterprise
+                      - enterprise_trial
+    responses:
+      "200":
+        description: Update a gate template
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gate-templates.yaml#/UpdateGateTemplateResponse
+            example:
+              id: gtpl_01j7w8a1b2c3d4e5f6g7h8i9j0
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - READ_ONLY
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
+  delete:
+    operationId: deleteGateTemplate
+    summary: Delete a gate template
+    description: |-
+      Soft-deletes (archives) a **customer** template. Returns `409` if `id` names a read-only built-in template.
+    tags:
+      - Templates
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Customer template id (`gtpl_…`) or its `name`.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Delete a gate template
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gate-templates.yaml#/DeleteGateTemplateResponse
+            example:
+              ok: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - READ_ONLY
+    x-cli:
+      name: archive
+      positional:
+        - id