overlay: 1.0.0
info:
  title: API Evangelist enhancements for the konfetti Store API
  version: 1.0.0
  x-generated: '2026-07-19'
  x-method: generated
  x-source: >-
    Generated by the API Evangelist enrichment pipeline. Captures the
    annotations we add on top of openapi/konfetti-store-openapi.yml — the
    provenance warning, the cross-links to the conventions/errors/lifecycle
    artifacts, and the per-operation stability flags observed during probing.
    The base description is never mutated; apply this overlay to get the
    annotated view.
extends: ../openapi/konfetti-store-openapi.yml
actions:
  - target: $.info
    description: >-
      Flag the whole description as observational, not provider-published, and
      link the companion artifacts.
    update:
      x-apievangelist-provenance:
        method: derived
        derived_from:
          - live probes of https://api.gokonfetti.com/v1 on 2026-07-19
          - publicly served gokonfetti.com Nuxt bundles under /_nuxt3/*.js
        provider_published_spec: false
        warning: >-
          konfetti publishes no OpenAPI document, no developer portal and no
          API terms of use. This is an undocumented internal interface that may
          change without notice.
      x-apievangelist-artifacts:
        conventions: conventions/konfetti-conventions.yml
        errors: errors/konfetti-problem-types.yml
        authentication: authentication/konfetti-authentication.yml
        data_model: data-model/konfetti-data-model.yml
        lifecycle: lifecycle/konfetti-lifecycle.yml
        conformance: conformance/konfetti-conformance.yml
        components: components/konfetti-components.yml

  - target: $.servers[0]
    description: Record what was actually observed about the production host.
    update:
      x-observed:
        date: '2026-07-19'
        protocol: HTTP/2
        stack: Apiato on Laravel behind AWS API Gateway
        request_id_header: apigw-requestid

  - target: $.paths['/v1/store/events'].get
    description: Record the catalog scale measured at probe time.
    update:
      x-observed:
        status: 200
        total_records: 7605
        default_page_size: 10
        measured_on: '2026-07-19'

  - target: $.paths['/v1/store/events/{permalink}'].get
    description: Warn that the bare id is not a valid lookup key.
    update:
      x-lookup-key-warning: >-
        Events resolve by PERMALINK (slug-with-id). Passing the bare
        six-character id returns 404.

  - target: $.paths['/v1/store/events/{id}/add-ons'].get
    description: Flag the operation as unstable — it returned 500 when probed.
    update:
      x-stability: unstable
      x-observed:
        status: 500
        measured_on: '2026-07-19'
        note: Probed against a live experience with a valid permalink.

  - target: $.paths['/v1/store/events/{id}/calendar'].get
    description: Flag the operation as unstable — it returned 500 when probed.
    update:
      x-stability: unstable
      x-observed:
        status: 500
        measured_on: '2026-07-19'

  - target: $.paths['/v1/checkout/orders'].get
    description: Warn about the 302-instead-of-401 authentication failure mode.
    update:
      x-auth-failure-mode: >-
        Unauthenticated requests receive a 302 redirect to
        https://api.gokonfetti.com/login, not a 401. Disable redirect-following
        or you will parse an HTML login page as JSON.

  - target: $.paths['/v1/user/profile'].get
    description: Warn about the 302-instead-of-401 authentication failure mode.
    update:
      x-auth-failure-mode: >-
        Unauthenticated requests receive a 302 redirect to
        https://api.gokonfetti.com/login, not a 401.

  - target: $.paths['/v1/oauth/token'].post
    description: Record that no client registration path exists for third parties.
    update:
      x-third-party-access: >-
        konfetti publishes no client registration process, grant-type list or
        scope reference, and no RFC 8414 metadata document. Third parties
        cannot obtain a token through any documented route.

  - target: $.components.schemas.Money
    description: Make the minor-units-as-string trap explicit.
    update:
      x-integration-note: >-
        `amount` is minor units (cents) serialized as a STRING, not a number.
        Parse it as an integer and divide by 100; never treat it as a float or
        as a major-unit value.

  - target: $.components.schemas.Error
    description: State plainly that this is not RFC 9457.
    update:
      x-not-rfc9457: >-
        This is a bespoke Apiato envelope served as application/json. konfetti
        does not support application/problem+json. 5xx responses may return
        HTML rather than this schema — check content-type before parsing.