openapi: 3.0.3
info:
  title: SwitchMall Public Statistics API
  version: 1.2.0
  description: Read-only public SwitchMall product reactions and merchant content view counts.
  contact:
    name: SwitchMall Developer Resources
    url: https://switchmall.ai/developers
externalDocs:
  description: SwitchMall Public API documentation
  url: https://switchmall.ai/developers/api
servers:
  - url: https://switchmall.ai
security: []
tags:
  - name: SwitchMall Products
    description: Read-only public information associated with SwitchMall product IDs.
  - name: SwitchMall Merchants
    description: Read-only product and offer view statistics associated with SwitchMall merchant IDs.
paths:
  /api/public/v1/products/{productId}/stats:
    get:
      operationId: getSwitchMallProductStats
      summary: Get SwitchMall product statistics
      description: Returns current view, like and dislike counts for a SwitchMall product ID. No authentication is required.
      security: []
      tags:
        - SwitchMall Products
      parameters:
        - name: productId
          in: path
          required: true
          description: Positive SwitchMall product ID.
          schema:
            type: integer
            format: int64
            minimum: 1
            maximum: 9007199254740991
          example: 1
      responses:
        "200":
          description: Current SwitchMall product statistics.
          headers:
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductStats"
              example:
                productId: 1
                viewsCount: 0
                likesCount: 0
                dislikesCount: 0
        "400":
          $ref: "#/components/responses/BadRequest"
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/public/v1/merchants/{merchantId}/stats:
    get:
      operationId: getSwitchMallMerchantStats
      summary: Get SwitchMall merchant view statistics
      description: Returns rolling 24-hour merchant totals, comparison with the latest previous 14:00 MSK snapshot, and per-product and per-offer view tables. No authentication is required.
      security: []
      tags:
        - SwitchMall Merchants
      parameters:
        - name: merchantId
          in: path
          required: true
          description: Positive integer merchant ID.
          schema:
            type: integer
            format: int64
            minimum: 1
            maximum: 9007199254740991
      responses:
        "200":
          description: Current merchant view statistics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantStats"
        "400":
          $ref: "#/components/responses/BadMerchantRequest"
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/ServerError"
components:
  schemas:
    ProductStats:
      type: object
      required:
        - productId
        - viewsCount
        - likesCount
        - dislikesCount
      properties:
        productId:
          type: integer
          format: int64
          minimum: 1
          maximum: 9007199254740991
          description: SwitchMall product ID supplied in the request path.
        viewsCount:
          type: integer
          minimum: 0
          description: Recorded product view events.
        likesCount:
          type: integer
          minimum: 0
          description: Current positive reactions.
        dislikesCount:
          type: integer
          minimum: 0
          description: Current negative reactions.
      additionalProperties: false
    MerchantContentView:
      type: object
      required: [id, name, viewsCount, userViewsCount, agentViewsCount]
      properties:
        id: { type: integer, format: int64, minimum: 1 }
        name: { type: string }
        viewsCount: { type: integer, minimum: 0 }
        userViewsCount: { type: integer, minimum: 0 }
        agentViewsCount: { type: integer, minimum: 0 }
      additionalProperties: false
    ActivityComparison:
      type: object
      required: [count, previousCount, changePercent]
      properties:
        count: { type: integer, minimum: 0 }
        previousCount: { type: integer, minimum: 0 }
        changePercent:
          type: number
          nullable: true
          description: Percentage change, or null when the baseline is zero and the current count is positive.
      additionalProperties: false
    MerchantViewComparisons:
      type: object
      required: [productViews, productUserViews, productAgentViews, offerViews, totalViews]
      properties:
        productViews: { $ref: "#/components/schemas/ActivityComparison" }
        productUserViews: { $ref: "#/components/schemas/ActivityComparison" }
        productAgentViews: { $ref: "#/components/schemas/ActivityComparison" }
        offerViews: { $ref: "#/components/schemas/ActivityComparison" }
        totalViews: { $ref: "#/components/schemas/ActivityComparison" }
      additionalProperties: false
    MerchantStats:
      type: object
      required: [merchantId, merchantName, productViewsCount, productUserViewsCount, productAgentViewsCount, offerViewsCount, totalViewsCount, comparisons, products, offers, period, scheduledAt]
      properties:
        merchantId: { type: integer, format: int64, minimum: 1 }
        merchantName: { type: string }
        productViewsCount: { type: integer, minimum: 0 }
        productUserViewsCount: { type: integer, minimum: 0 }
        productAgentViewsCount: { type: integer, minimum: 0 }
        offerViewsCount: { type: integer, minimum: 0 }
        totalViewsCount: { type: integer, minimum: 0 }
        comparisons: { $ref: "#/components/schemas/MerchantViewComparisons" }
        period: { type: string, enum: [24h] }
        comparisonDate:
          type: string
          format: date
          description: Date of the latest previous 14:00 MSK snapshot; omitted until a baseline exists.
        scheduledAt: { type: string, enum: ["14:00 MSK"] }
        products:
          type: array
          items: { $ref: "#/components/schemas/MerchantContentView" }
        offers:
          type: array
          items: { $ref: "#/components/schemas/MerchantContentView" }
      additionalProperties: false
    Error:
      type: object
      required:
        - error
        - code
        - message
        - resolution
      properties:
        error:
          type: string
          description: Backward-compatible human-readable error message.
        code:
          type: string
          description: Stable machine-readable error code.
          enum:
            - INVALID_PRODUCT_ID
            - INVALID_MERCHANT_ID
            - METHOD_NOT_ALLOWED
            - RATE_LIMIT_EXCEEDED
            - INTERNAL_ERROR
            - API_ROUTE_NOT_FOUND
        message:
          type: string
          description: Human-readable explanation of the failure.
        resolution:
          type: string
          description: Concrete guidance for correcting or retrying the request.
      additionalProperties: false
  responses:
    BadRequest:
      description: Invalid SwitchMall product ID.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadMerchantRequest:
      description: Invalid merchant ID.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: Merchant ID must be a positive integer
            code: INVALID_MERCHANT_ID
            message: Merchant ID must be a positive integer
            resolution: Provide a positive integer SwitchMall merchant ID in the URL path.
    MethodNotAllowed:
      description: Unsupported HTTP method.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: Method not allowed
            code: METHOD_NOT_ALLOWED
            message: Method not allowed
            resolution: Call this endpoint with GET or OPTIONS.
    TooManyRequests:
      description: Public rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds until another request may be attempted.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: Rate limit exceeded
            code: RATE_LIMIT_EXCEEDED
            message: Rate limit exceeded
            resolution: Wait for the Retry-After interval before retrying.
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: Internal server error
            code: INTERNAL_ERROR
            message: Internal server error
            resolution: Retry later or use the SwitchMall contact page if the problem continues.