Opply Brain API

openapi: 3.0.3
info:
  title: Opply Activity Feed 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.\n\nThe FE POSTs the current per-sector \"above threshold?\" map on\nevery progress change. The BE compares each sector against the\nstored row in ``BrainSectorUnlockSeen`` and returns the list of\nsectors whose modal should now fire:\n\n- **No row exists yet** — first observation of this sector for\n  this user. Create the row with ``resolved`` set to the current\n  ``above_threshold``. If above on first observation we suppress\n  the modal (resolved=True), because we have no way to know\n  whether the buyer just crossed or has been above for months.\n  No celebration in either case.\n- **Existing row, resolved=True** — done. Either we celebrated\n  previously or we suppressed on first observation. Skip.\n- **Existing row, resolved=False, above_threshold=True** — the\n  buyer was observed below threshold last time and is now above.\n  THIS is the real crossing. Flip ``resolved`` to True and\n  return the sector in ``celebrate``.\n- **Existing row, resolved=False, above_threshold=False** —\n  still below. No state change.\n\nThe whole thing runs in a savepoint so the unique-constraint\nrace (two concurrent POSTs trying to create the same row)\nfails 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:
    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'
    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
    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"