openapi: 3.0.3
info:
  title: PlugEmDash Public Catalog API
  description: |
    Read-only JSON for published marketplace listings. No authentication.
    All listing data is approved and published plugins only.
  version: 1.0.0
servers:
  - url: /
paths:
  /api/catalog:
    get:
      summary: Catalog index (links and hints)
      operationId: publicCatalogIndex
      responses:
        "200":
          description: JSON index
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/catalog/packages:
    get:
      summary: Paginated package listings
      operationId: publicCatalogPackagesList
      parameters:
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
        - name: sort
          in: query
          schema:
            type: string
            enum: [publicActivityAt, name, featured]
        - name: npm
          in: query
          description: Exact npm package name (e.g. @scope/pkg)
          schema: { type: string }
      responses:
        "200":
          description: Paginated packages
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "404":
          description: npm filter set but package not in catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
  /api/catalog/packages/{slug}:
    get:
      summary: Single listing by slug
      operationId: publicCatalogPackageBySlug
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Package detail JSON
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "404":
          description: Not found or not publicly listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
