@crvouga/mockingbird-service-posthog 1.8.0 → 2.1.0

package/openapi.yaml

@@ -0,0 +1,1017 @@
+openapi: 3.1.0
+info:
+  title: PostHog feature flags, capture and management API (Mockingbird subset)
+  description: |
+    Stateful mock subset of PostHog: remote flag evaluation (`/flags` v2 and the legacy
+    `/decide` shape), remote config, event capture (`/batch/`, `/e/`, `/i/v0/e/`), session
+    recording intake, the posthog-js asset and survey endpoints, and the slice of the
+    management API our tooling and crons call (feature-flag list/create/patch, HogQL query).
+    Hand-authored from the wire shapes of posthog-node 5.52.2 / @posthog/core 1.54.0,
+    posthog-js 1.433.2 and our own raw fetches.
+
+    Paths are written without the trailing slash PostHog uses; the mock answers both
+    (`/flags/?v=2` from the SDKs and `/flags?v=2` from the EMR frontend's raw fetch).
+    Capture and flag bodies may arrive gzip-compressed (`Content-Encoding: gzip`, or raw gzip
+    bytes from posthog-js), base64 (`data=` form bodies), or as plain JSON; the contract
+    declares the decoded JSON.
+  version: "1"
+  x-mockingbird-upstream:
+    note: >-
+      Hand-authored from @posthog/core posthog-core-stateless (getFlags, sendBatch,
+      getRemoteConfig, getSurveysStateless), posthog-js request.ts / posthog-featureflags.ts,
+      and the consumer's posthog-server.adapter.ts, posthog-server.ts (EMR frontend),
+      website-posthog-purchase.sink.ts, posthog-hogql.client.ts and feature-flags-cli.
+servers:
+  - url: https://us.i.posthog.com
+paths:
+  /flags:
+    post:
+      operationId: EvaluateFlags
+      description: |
+        Remote flag evaluation. `v=2` (what every current SDK sends) answers the `flags` detail
+        map; no `v` or `v=1` answers the legacy `featureFlags`/`featureFlagPayloads` maps.
+        `config=true` adds the remote-config fields. The project key is `token` (SDKs) or
+        `api_key` (the EMR frontend's raw fetch).
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/Version"
+        - $ref: "#/components/parameters/Config"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FlagsRequest"
+      responses:
+        "200":
+          description: Evaluated flags
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FlagsResponse"
+        "400":
+          description: Malformed body or missing distinct_id
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: No project API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "429":
+          description: Rate limited (fault preset flags_429)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "500":
+          description: Server error (fault preset flags_5xx)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /decide:
+    post:
+      operationId: Decide
+      description: |
+        The legacy endpoint (the Python client sends `POST /decide/?v=3` with
+        `{api_key, distinct_id}`). `v` < 4 answers the legacy maps; `v=4` the `flags` map.
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/Version"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FlagsRequest"
+      responses:
+        "200":
+          description: Evaluated flags (legacy shape)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FlagsResponse"
+        "400":
+          description: Malformed body or missing distinct_id
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: No project API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "429":
+          description: Rate limited (fault preset flags_429)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "500":
+          description: Server error (fault preset flags_5xx)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /array/{token}/config:
+    parameters:
+      - $ref: "#/components/parameters/TokenPath"
+    get:
+      operationId: GetRemoteConfig
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        "200":
+          description: Remote config (posthog-react-native, @posthog/core)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RemoteConfig"
+  /array/{token}/config.js:
+    parameters:
+      - $ref: "#/components/parameters/TokenPath"
+    get:
+      operationId: GetRemoteConfigScript
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        "200":
+          description: >-
+            Remote config as a script that sets `window._POSTHOG_REMOTE_CONFIG[token]`
+            (posthog-js)
+          content:
+            application/javascript:
+              schema:
+                type: string
+  /batch:
+    post:
+      operationId: CaptureBatch
+      description: "posthog-node and posthog-react-native flushes (Content-Encoding: gzip)."
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/BatchRequest"
+      responses:
+        "200":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CaptureResponse"
+        "400":
+          description: Malformed body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: No project API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "500":
+          description: Server error (fault)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /e:
+    post:
+      operationId: CaptureEvent
+      description: One event, an array of events, or `{api_key, batch}` (posthog-js).
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CaptureRequest"
+      responses:
+        "200":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CaptureResponse"
+        "400":
+          description: Malformed body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: No project API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "500":
+          description: Server error (fault)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /i/v0/e:
+    post:
+      operationId: CaptureEventV0
+      description: >-
+        The capture endpoint remote config advertises (`analytics.endpoint`); also our backend's
+        website purchase sink (`{api_key, event, distinct_id, timestamp, uuid, properties}`).
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CaptureRequest"
+      responses:
+        "200":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CaptureResponse"
+        "400":
+          description: Malformed body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: No project API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "500":
+          description: Server error (fault)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /s:
+    post:
+      operationId: CaptureRecording
+      description: Session-recording snapshots; counted, never stored.
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CaptureRequest"
+      responses:
+        "200":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CaptureResponse"
+  /static/recorder.js:
+    get:
+      operationId: GetRecorderScript
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        "200":
+          description: The session recorder bundle (an inert script here)
+          content:
+            application/javascript:
+              schema:
+                type: string
+  /static/{version}/recorder.js:
+    parameters:
+      - name: version
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+    get:
+      operationId: GetVersionedRecorderScript
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        "200":
+          description: The versioned session recorder bundle (an inert script here)
+          content:
+            application/javascript:
+              schema:
+                type: string
+  /api/surveys:
+    get:
+      operationId: ListSurveys
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/TokenQuery"
+      responses:
+        "200":
+          description: No surveys
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [surveys]
+                properties:
+                  surveys:
+                    type: array
+                    maxItems: 0
+        "401":
+          description: No project API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /api/web_experiments:
+    get:
+      operationId: ListWebExperiments
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/TokenQuery"
+      responses:
+        "200":
+          description: No web experiments
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [experiments]
+                properties:
+                  experiments:
+                    type: array
+                    maxItems: 0
+        "401":
+          description: No project API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /api/projects/{projectId}/feature_flags:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+    get:
+      operationId: ListFeatureFlags
+      security:
+        - bearerAuth: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            minimum: 0
+            maximum: 1000
+      responses:
+        "200":
+          description: One page of flags (feature-flags-cli follows `next`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FeatureFlagPage"
+        "401":
+          description: No personal API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+    post:
+      operationId: CreateFeatureFlag
+      security:
+        - bearerAuth: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateFeatureFlagBody"
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FeatureFlag"
+        "400":
+          description: Invalid, or the key already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: No personal API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /api/projects/{projectId}/feature_flags/{flagId}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - name: flagId
+        in: path
+        required: true
+        description: >-
+          The flag's numeric id. The mock also accepts the flag key (how self-parity walks
+          reference flags they created, since resource identities are strings).
+        schema:
+          type: string
+          x-mockingbird-resource-ref:
+            type: feature_flag
+            missing: "999999"
+    patch:
+      operationId: UpdateFeatureFlag
+      security:
+        - bearerAuth: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateFeatureFlagBody"
+      responses:
+        "200":
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FeatureFlag"
+        "400":
+          description: Invalid
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: No personal API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "404":
+          description: No such flag
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /api/projects/{projectId}/query:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+    post:
+      operationId: RunQuery
+      description: >-
+        HogQL (the marketing-metrics crons). Answers canned results set with
+        `PUT /__admin/settings {"queryResults": [...]}`; `{results: []}` otherwise.
+      security:
+        - bearerAuth: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QueryRequest"
+      responses:
+        "200":
+          description: Query results
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/QueryResponse"
+        "400":
+          description: Not a HogQL query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: No personal API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    Version:
+      name: v
+      in: query
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 4
+    Config:
+      name: config
+      in: query
+      schema:
+        type: string
+        enum: ["true", "false"]
+    TokenPath:
+      name: token
+      in: path
+      required: true
+      schema:
+        type: string
+        pattern: "^[A-Za-z0-9_-]{1,64}$"
+    TokenQuery:
+      name: token
+      in: query
+      required: true
+      schema:
+        type: string
+        pattern: "^[A-Za-z0-9_-]{1,64}$"
+    ProjectId:
+      name: projectId
+      in: path
+      required: true
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 999999999
+  schemas:
+    ErrorBody:
+      type: object
+      required: [type, code, detail]
+      properties:
+        type:
+          type: string
+        code:
+          type: string
+        detail:
+          type: string
+        attr:
+          type: ["string", "null"]
+    FlagsRequest:
+      type: object
+      required: [distinct_id]
+      properties:
+        token:
+          type: string
+          pattern: "^[A-Za-z0-9_-]{1,64}$"
+        api_key:
+          type: string
+          pattern: "^[A-Za-z0-9_-]{1,64}$"
+        distinct_id:
+          type: string
+          minLength: 1
+          maxLength: 64
+        groups:
+          type: object
+        person_properties:
+          type: object
+          properties:
+            email:
+              type: string
+              maxLength: 120
+        group_properties:
+          type: object
+        $device_id:
+          type: string
+          maxLength: 64
+        $anon_distinct_id:
+          type: string
+          maxLength: 64
+        evaluation_contexts:
+          type: array
+          maxItems: 5
+          items:
+            type: string
+            maxLength: 40
+        evaluation_runtime:
+          type: string
+          enum: [server, client, all]
+        flag_keys_to_evaluate:
+          type: array
+          maxItems: 10
+          items:
+            type: string
+            maxLength: 64
+        geoip_disable:
+          type: boolean
+        disable_flags:
+          type: boolean
+    FlagDetail:
+      type: object
+      required: [key, enabled, variant, reason, metadata]
+      properties:
+        key:
+          type: string
+        enabled:
+          type: boolean
+        variant:
+          type: ["string", "null"]
+        failed:
+          type: boolean
+        reason:
+          type: object
+          required: [code, description]
+          properties:
+            code:
+              type: string
+            condition_index:
+              type: ["integer", "null"]
+            description:
+              type: string
+        metadata:
+          type: object
+          required: [id, version]
+          properties:
+            id:
+              type: integer
+            version:
+              type: integer
+            description:
+              type: ["string", "null"]
+            payload:
+              type: string
+              description: The payload as a JSON string.
+    FlagsResponse:
+      type: object
+      required: [errorsWhileComputingFlags]
+      properties:
+        flags:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/FlagDetail"
+        featureFlags:
+          type: object
+          additionalProperties:
+            type: ["boolean", "string"]
+        featureFlagPayloads:
+          type: object
+          additionalProperties:
+            type: string
+        errorsWhileComputingFlags:
+          type: boolean
+        quotaLimited:
+          type: array
+          items:
+            type: string
+        requestId:
+          type: string
+          x-mockingbird-volatile:
+            kind: id
+        evaluatedAt:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        config:
+          type: object
+        supportedCompression:
+          type: array
+          items:
+            type: string
+        sessionRecording:
+          oneOf:
+            - type: boolean
+            - type: object
+    RemoteConfig:
+      type: object
+      required: [token, supportedCompression, hasFeatureFlags, analytics, sessionRecording]
+      properties:
+        token:
+          type: string
+        supportedCompression:
+          type: array
+          items:
+            type: string
+        hasFeatureFlags:
+          type: boolean
+        analytics:
+          type: object
+          required: [endpoint]
+          properties:
+            endpoint:
+              type: string
+        sessionRecording:
+          oneOf:
+            - type: boolean
+            - type: object
+              required: [endpoint]
+              properties:
+                endpoint:
+                  type: string
+        surveys:
+          type: boolean
+        heatmaps:
+          type: boolean
+        siteApps:
+          type: array
+    CapturedEventBody:
+      type: object
+      required: [event]
+      properties:
+        event:
+          type: string
+          minLength: 1
+          maxLength: 64
+        distinct_id:
+          type: string
+          minLength: 1
+          maxLength: 64
+        properties:
+          type: object
+        timestamp:
+          type: string
+          format: date-time
+        uuid:
+          type: string
+          format: uuid
+    BatchRequest:
+      type: object
+      required: [api_key, batch]
+      properties:
+        api_key:
+          type: string
+          pattern: "^[A-Za-z0-9_-]{1,64}$"
+        batch:
+          type: array
+          maxItems: 5
+          items:
+            $ref: "#/components/schemas/CapturedEventBody"
+        sent_at:
+          type: string
+          format: date-time
+    CaptureRequest:
+      type: object
+      required: [api_key, event]
+      properties:
+        api_key:
+          type: string
+          pattern: "^[A-Za-z0-9_-]{1,64}$"
+        event:
+          type: string
+          minLength: 1
+          maxLength: 64
+        distinct_id:
+          type: string
+          minLength: 1
+          maxLength: 64
+        properties:
+          type: object
+        timestamp:
+          type: string
+          format: date-time
+        uuid:
+          type: string
+          format: uuid
+    CaptureResponse:
+      type: object
+      required: [status]
+      properties:
+        status:
+          oneOf:
+            - type: string
+            - type: integer
+    FeatureFlag:
+      type: object
+      required: [id, key, name, active, filters]
+      properties:
+        id:
+          type: integer
+        key:
+          type: string
+          x-mockingbird-resource:
+            type: feature_flag
+            identity: true
+        name:
+          type: string
+        active:
+          type: boolean
+        deleted:
+          type: boolean
+        created_at:
+          type: string
+          x-mockingbird-volatile:
+            kind: timestamp
+        updated_at:
+          type: string
+          x-mockingbird-volatile:
+            kind: timestamp
+        version:
+          type: integer
+        filters:
+          type: object
+          required: [groups]
+          properties:
+            groups:
+              type: array
+              items:
+                type: object
+            multivariate:
+              oneOf:
+                - type: "null"
+                - type: object
+            payloads:
+              type: object
+    FeatureFlagPage:
+      type: object
+      required: [count, next, previous, results]
+      properties:
+        count:
+          type: integer
+        next:
+          type: ["string", "null"]
+          x-mockingbird-volatile:
+            kind: url
+        previous:
+          type: ["string", "null"]
+          x-mockingbird-volatile:
+            kind: url
+        results:
+          type: array
+          items:
+            $ref: "#/components/schemas/FeatureFlag"
+    FlagGroup:
+      type: object
+      properties:
+        properties:
+          type: array
+          maxItems: 2
+          items:
+            type: object
+            required: [key, value]
+            properties:
+              key:
+                type: string
+                enum: [distinct_id, email]
+              type:
+                type: string
+                enum: [person]
+              operator:
+                type: string
+                enum: [exact]
+              value:
+                type: array
+                maxItems: 3
+                items:
+                  type: string
+                  minLength: 1
+                  maxLength: 40
+        rollout_percentage:
+          type: integer
+          minimum: 0
+          maximum: 100
+        variant:
+          type: ["string", "null"]
+          maxLength: 20
+    FlagFilters:
+      type: object
+      properties:
+        groups:
+          type: array
+          maxItems: 3
+          items:
+            $ref: "#/components/schemas/FlagGroup"
+        payloads:
+          type: object
+          properties:
+            "true":
+              type: string
+              maxLength: 200
+    CreateFeatureFlagBody:
+      type: object
+      required: [key]
+      properties:
+        key:
+          type: string
+          pattern: "^[A-Za-z0-9_-]{1,64}$"
+        name:
+          type: string
+          maxLength: 120
+        active:
+          type: boolean
+        filters:
+          $ref: "#/components/schemas/FlagFilters"
+    UpdateFeatureFlagBody:
+      type: object
+      properties:
+        name:
+          type: string
+          maxLength: 120
+        active:
+          type: boolean
+        deleted:
+          type: boolean
+        filters:
+          $ref: "#/components/schemas/FlagFilters"
+    QueryRequest:
+      type: object
+      required: [query]
+      properties:
+        query:
+          type: object
+          required: [kind, query]
+          properties:
+            kind:
+              type: string
+              enum: [HogQLQuery]
+            query:
+              type: string
+              minLength: 1
+              maxLength: 500
+    QueryResponse:
+      type: object
+      required: [results]
+      properties:
+        results:
+          type: array
+          items:
+            type: array
+        columns:
+          type: array
+          items:
+            type: string
+        is_cached:
+          type: boolean