openapi: 3.1.0
info:
  title: Descrybe plan feature permissions (session API)
  version: "1.0.0"
  description: >
    Dashboard/admin session endpoints for plan ∩ global feature permissions.
    Not part of the public /api/v1 OpenAPI document.
paths:
  /api/billing/capabilities:
    get:
      operationId: getBillingCapabilities
      tags: [billing]
      security: [{ sessionCookie: [] }]
      summary: Effective plan ∩ global feature matrix for the active company
      responses:
        "200":
          description: Capabilities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Capabilities"
        "401":
          $ref: "#/components/responses/Error"
  /api/admin/plans/{planID}/features:
    parameters:
      - $ref: "#/components/parameters/PlanID"
    get:
      operationId: adminGetPlanFeatures
      tags: [admin]
      security: [{ sessionCookie: [], platformAdmin: [] }]
      summary: Plan feature overrides + resolved plan_allows matrix
      responses:
        "200":
          description: Plan features
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlanFeaturesView"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
    put:
      operationId: adminPutPlanFeatures
      tags: [admin]
      security: [{ sessionCookie: [], platformAdmin: [] }]
      summary: Replace plan feature overrides
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlanFeaturesUpdate"
      responses:
        "200":
          description: Updated plan features
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlanFeaturesView"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
  /api/admin/plans/{planID}/features/enable-all:
    parameters:
      - $ref: "#/components/parameters/PlanID"
    post:
      operationId: adminEnableAllPlanFeatures
      tags: [admin]
      security: [{ sessionCookie: [], platformAdmin: [] }]
      summary: Enable every registry feature on the plan (custom packages)
      responses:
        "200":
          description: Updated plan features
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlanFeaturesView"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
  /api/admin/feature-gates:
    get:
      operationId: adminGetFeatureGates
      tags: [admin]
      security: [{ sessionCookie: [], platformAdmin: [] }]
      summary: Global section and feature master switches
      responses:
        "200":
          description: Feature gates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureGatesView"
        "403":
          $ref: "#/components/responses/Error"
    put:
      operationId: adminPutFeatureGates
      tags: [admin]
      security: [{ sessionCookie: [], platformAdmin: [] }]
      summary: Partial upsert of global gates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeatureGatesUpdate"
      responses:
        "200":
          description: Updated gates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureGatesView"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
  /api/admin/feature-gates/sections/{section}:
    parameters:
      - name: section
        in: path
        required: true
        schema:
          type: string
          enum: [shell, dashboard, catalog, feeds, stores, processing, marketing, integrations, billing, settings, support, capabilities]
    put:
      operationId: adminPutFeatureGateSection
      tags: [admin]
      security: [{ sessionCookie: [], platformAdmin: [] }]
      summary: Enable or disable a section for ALL plans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SectionGateUpdate"
      responses:
        "200":
          description: Updated gates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureGatesView"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
components:
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
    platformAdmin:
      type: http
      scheme: bearer
      description: Requires users.is_platform_admin (session-derived; bearer shown for tooling only)
  parameters:
    PlanID:
      name: planID
      in: path
      required: true
      schema:
        type: integer
        format: int64
        minimum: 1
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error:
                type: string
  schemas:
    Capabilities:
      type: object
      properties:
        plan_id: { type: integer, format: int64 }
        plan_name: { type: string }
        is_custom: { type: boolean }
        has_active_plan: { type: boolean }
        features:
          type: object
          additionalProperties: { type: boolean }
        sections:
          type: object
          additionalProperties: { type: boolean }
        disabled_features:
          type: array
          items: { type: string }
        feature_etag: { type: string }
        entitlements:
          type: object
          additionalProperties: true
    PlanFeaturesView:
      type: object
      properties:
        plan_id: { type: integer, format: int64 }
        plan_name: { type: string }
        is_custom: { type: boolean }
        features:
          type: object
          additionalProperties: { type: boolean }
        resolved_features:
          type: object
          additionalProperties: { type: boolean }
    PlanFeaturesUpdate:
      type: object
      required: [features]
      properties:
        features:
          type: object
          additionalProperties: { type: boolean }
    FeatureGatesView:
      type: object
      properties:
        sections:
          type: object
          additionalProperties: { type: boolean }
        features:
          type: object
          additionalProperties: { type: boolean }
    FeatureGatesUpdate:
      type: object
      properties:
        sections:
          type: object
          additionalProperties: { type: boolean }
        features:
          type: object
          additionalProperties: { type: boolean }
    SectionGateUpdate:
      type: object
      required: [enabled]
      properties:
        enabled: { type: boolean }