Opply Brain API

openapi: 3.2.0
info:
  title: Opply Brain API
  version: 0.0.0
tags:
- name: Brain
paths:
  /api/v1/brain/observe-progress/:
    post:
      operationId: api_v1_brain_observe_progress_create
      description: 'Single endpoint driving the brain unlock celebration lifecycle.


        The FE POSTs the current per-sector "above threshold?" map on

        every progress change. The BE compares each sector against the

        stored row in ``BrainSectorUnlockSeen`` and returns the list of

        sectors whose modal should now fire:


        - **No row exists yet** — first observation of this sector for

        this user. Create the row with ``resolved`` set to the current

        ``above_threshold``. If above on first observation we suppress

        the modal (resolved=True), because we have no way to know

        whether the buyer just crossed or has been above for months.

        No celebration in either case.

        - **Existing row, resolved=True** — done. Either we celebrated

        previously or we suppressed on first observation. Skip.

        - **Existing row, resolved=False, above_threshold=True** — the

        buyer was observed below threshold last time and is now above.

        THIS is the real crossing. Flip ``resolved`` to True and

        return the sector in ``celebrate``.

        - **Existing row, resolved=False, above_threshold=False** —

        still below. No state change.


        The whole thing runs in a savepoint so the unique-constraint

        race (two concurrent POSTs trying to create the same row)

        fails cleanly and we re-read the row on the second attempt.'
      summary: Observe per-sector progress and return sectors to celebrate
      tags:
      - Brain
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrainObserveProgressRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BrainObserveProgressRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BrainObserveProgressRequest'
        required: true
      security:
      - tokenAuth: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrainObserveProgressResponse'
          description: ''
components:
  schemas:
    BrainObserveProgressRequest:
      type: object
      description: 'Per-sector "above threshold?" observation submitted by the FE.


        The FE knows each sector''s unlock threshold (per

        ``BRAIN_SECTOR_UNLOCK`` in ``mocks/brain.ts``); the BE doesn''t

        care about the count itself, only the boolean "is the sector

        above its threshold right now?". This keeps the API agnostic

        to FE-side threshold tuning — we can move targets without a BE

        deploy.


        Unknown sector keys are ignored at the view level so newer FE

        builds that emit additional keys don''t 400 against an older API.'
      properties:
        sectors:
          type: object
          additionalProperties:
            type: boolean
          description: Map of brain sector key → whether the user is currently above the sector's unlock threshold. Keys outside the ``BrainSectorKey`` enum are silently ignored.
      required:
      - sectors
    CelebrateEnum:
      enum:
      - suppliers
      - ingredients
      - operations
      - commercials
      - compliance
      - financial
      - market
      type: string
      description: '* `suppliers` - Suppliers

        * `ingredients` - Ingredients

        * `operations` - Operations

        * `commercials` - Commercials

        * `compliance` - Compliance

        * `financial` - Financial

        * `market` - Market'
    BrainObserveProgressResponse:
      type: object
      description: 'Sectors whose unlock-celebration modal should be shown now.


        Returned in the order the server processed them; the FE queues

        them and surfaces one at a time. A sector appears here exactly

        once across all observations — the BE flips the row''s

        ``resolved`` flag in the same transaction.'
      properties:
        celebrate:
          type: array
          items:
            $ref: '#/components/schemas/CelebrateEnum'
          description: Brain sector keys whose unlock threshold was just observed to cross from below to above. Empty when nothing new fired.
      required:
      - celebrate
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"