bff for callbacks

interface/api/callbacks/archive.yaml

@@ -0,0 +1,38 @@
+get:
+  tags: [Callbacks]
+  summary: Archive/unarchive callback subscription
+  description: Sets callback archive state by `callbacks_ref` and required `archived` query parameter.
+  operationId: callbacksArchive
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+    - $ref: ../parameters/callbacks_ref.yaml#/components/parameters/CallbacksRef
+    - name: archived
+      in: query
+      required: true
+      description: Target archive value to set on the callback.
+      schema:
+        type: boolean
+    - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
+  responses:
+    '200':
+      description: Archive state updated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/bodies/callback.yaml

@@ -0,0 +1,9 @@
+components:
+  requestBodies:
+    CallbackBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/callback.yaml#/components/schemas/CallbackRequest
+

interface/api/callbacks/create.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [Callbacks]
+  summary: Create callback subscription
+  description: Creates callback subscription for the organization identified by `org_ref`.
+  operationId: callbacksCreate
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+  requestBody:
+    $ref: ./bodies/callback.yaml#/components/requestBodies/CallbackBody
+  responses:
+    '201':
+      description: Callback created
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/list.yaml

@@ -0,0 +1,34 @@
+get:
+  tags: [Callbacks]
+  summary: List callback subscriptions
+  description: Lists callbacks for the given organization context.
+  operationId: callbacksList
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+    - $ref: ../parameters/limit.yaml#/components/parameters/Limit
+    - $ref: ../parameters/offset.yaml#/components/parameters/Offset
+    - $ref: ../parameters/archived.yaml#/components/parameters/Archived
+  responses:
+    '200':
+      description: Callback list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/object.yaml

@@ -0,0 +1,65 @@
+get:
+  tags: [Callbacks]
+  summary: Get callback subscription
+  description: Returns callback subscription by `callbacks_ref`.
+  operationId: callbacksGet
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/callbacks_ref.yaml#/components/parameters/CallbacksRef
+  responses:
+    '200':
+      description: Callback data
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+
+delete:
+  tags: [Callbacks]
+  summary: Delete callback subscription
+  description: Deletes callback by reference.
+  operationId: callbacksDelete
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/callbacks_ref.yaml#/components/parameters/CallbacksRef
+    - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
+  responses:
+    '200':
+      description: Callback deleted
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/request/callback.yaml

@@ -0,0 +1,5 @@
+components:
+  schemas:
+    CallbackRequest:
+      $ref: ../../../models/callback/callback.yaml#/components/schemas/Callback
+

interface/api/callbacks/response/callback.yaml

@@ -0,0 +1,19 @@
+components:
+  schemas:
+    CallbacksAuthData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - callbacks
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        callbacks:
+          type: array
+          items:
+            $ref: ../../../models/callback/callback.yaml#/components/schemas/Callback
+        generatedSigningSecret:
+          type: string
+          nullable: true
+

interface/api/callbacks/rotate_secret.yaml

@@ -0,0 +1,32 @@
+post:
+  tags: [Callbacks]
+  summary: Rotate callback signing secret
+  description: Generates and stores a new HMAC secret for the callback in Vault and returns it once.
+  operationId: callbacksRotateSecret
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/callbacks_ref.yaml#/components/parameters/CallbacksRef
+  responses:
+    '200':
+      description: Callback secret rotated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/update.yaml

@@ -0,0 +1,32 @@
+put:
+  tags: [Callbacks]
+  summary: Update callback subscription
+  description: Updates callback subscription fields.
+  operationId: callbacksUpdate
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/callback.yaml#/components/requestBodies/CallbackBody
+  responses:
+    '200':
+      description: Callback updated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/parameters/callbacks_ref.yaml

@@ -0,0 +1,10 @@
+components:
+  parameters:
+    CallbacksRef:
+      name: callbacks_ref
+      in: path
+      required: true
+      description: Callback subscription reference (Mongo ObjectId, 24 hex chars).
+      schema:
+        $ref: ../../models/objectid.yaml#/components/schemas/ObjectId
+