API Evangelist enhancements for Friendbuy Merchant Analytics API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for Friendbuy Merchant Analytics API
  version: 1.0.0
extends: openapi/friendbuy-analytics-api-openapi.yml
x-generated: '2026-08-13'
x-method: generated
x-source: >-
  Enhancements derived from the API Evangelist artifacts in this repository
  (conventions/, errors/, asyncapi/, lifecycle/, authentication/,
  data-model/, rate-limits/), themselves read from
  https://developers.friendbuy.com. This overlay is never applied to the
  source document; it records what API Evangelist knows that the
  specification does not carry.
actions:
- target: $.info
  update:
    x-apievangelist-provider: friendbuy
    x-apievangelist-artifacts:
      conventions: conventions/friendbuy-conventions.yml
      errors: errors/friendbuy-problem-types.yml
      webhooks: asyncapi/friendbuy-webhooks.yml
      lifecycle: lifecycle/friendbuy-lifecycle.yml
      authentication: authentication/friendbuy-authentication.yml
      data_model: data-model/friendbuy-data-model.yml
      rate_limits: rate-limits/friendbuy-rate-limits.yml
    x-agent-notes:
      idempotency: >-
        Not supported. Friendbuy documents no idempotency key for any write
        operation, so a blind retry can double-count a conversion or
        double-credit a loyalty ledger.
      credentials: >-
        Account key and secret are issued by Friendbuy (Developer Center in
        the Retailer App). There is no self-serve signup, no sandbox and no
        test-mode key prefix.
- target: $.info
  update:
    x-lifecycle:
      versioning: uri-path
      current: v1
      status_page: https://friendbuy.statuspage.io
      deprecation_policy: null
- target: $.components.schemas.Error
  update:
    x-error-envelope:
      rfc9457: false
      properties: [error, message, code, reference]
      statuses: [400, 401, 404, 422, 429, 500]
      note: >-
        Flat proprietary envelope, confirmed live against https://mapi.fbot.me
        on 2026-08-13. `reference` is the value to quote to Friendbuy support.
- target: $.paths['/analytics/widget-views'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/shares'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/clicks'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/account-sign-ups'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/purchases'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/distributed-advocate-rewards'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/distributed-friend-incentives'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/rewards/referral'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/email-captures'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.
- target: $.paths['/analytics/email-metrics'].get
  update:
    x-pagination:
      style: opaque-cursor
      request: [fromDate, toDate, pageSize, pageToken]
      response: nextPageToken
      note: >-
        When pageToken is supplied, fromDate, toDate and pageSize are derived
        from the token and must not be resent.