feat: add terminal-scoped transaction analytics

docs/openapi.yaml

@@ -172,6 +172,26 @@ paths:
         '503':
           $ref: '#/components/responses/DependencyUnavailable'
 
+  /analytics/terminals:
+    get:
+      tags: [Reporting periods]
+      operationId: listMerchantTerminals
+      summary: List terminals owned by the authenticated merchant
+      description: Returns display-safe terminal choices scoped exclusively from the authenticated server session.
+      parameters:
+        - $ref: '#/components/parameters/RequestIdHeader'
+      responses:
+        '200':
+          description: Merchant-owned terminal choices ordered by session volume.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TerminalList'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '503':
+          $ref: '#/components/responses/AnalyticsUnavailable'
+
   /analytics/runs:
     post:
       tags: [Analytics runs]
@@ -415,6 +435,25 @@ paths:
         - $ref: '#/components/parameters/DetailViewQuery'
         - $ref: '#/components/parameters/FailureStageQuery'
         - $ref: '#/components/parameters/TerminalIdQuery'
+        - name: status
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/SessionStatus'
+        - name: minAmountRial
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int64
+            minimum: 0
+        - name: maxAmountRial
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int64
+            minimum: 0
         - $ref: '#/components/parameters/CursorQuery'
         - $ref: '#/components/parameters/LimitQuery'
         - $ref: '#/components/parameters/RequestIdHeader'
@@ -445,6 +484,34 @@ paths:
         '503':
           $ref: '#/components/responses/AnalyticsUnavailable'
 
+  /analytics/sessions/{sessionId}:
+    get:
+      tags: [Analytics details]
+      operationId: getAnalyticsSession
+      summary: Get one merchant-owned payment session and attempt history
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema:
+            type: string
+            minLength: 8
+            maxLength: 128
+        - $ref: '#/components/parameters/RequestIdHeader'
+      responses:
+        '200':
+          description: Authorized merchant-owned session.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SessionDetail'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '404':
+          $ref: '#/components/responses/ResourceNotFound'
+        '503':
+          $ref: '#/components/responses/AnalyticsUnavailable'
+
   /analytics/session-details.csv:
     get:
       tags: [Analytics details]
@@ -1025,6 +1092,52 @@ components:
       properties:
         periodId:
           $ref: '#/components/schemas/PeriodId'
+        terminalId:
+          type: string
+          minLength: 1
+          maxLength: 128
+          pattern: '^[A-Za-z0-9._:-]+$'
+
+    Terminal:
+      type: object
+      additionalProperties: false
+      required: [terminalId, displayName, sessionCount, isDefault]
+      properties:
+        terminalId:
+          type: string
+          minLength: 1
+          maxLength: 128
+        displayName:
+          type: string
+          minLength: 1
+          maxLength: 80
+        sessionCount:
+          type: integer
+          format: int64
+          minimum: 0
+        isDefault:
+          type: boolean
+
+    TerminalList:
+      type: object
+      additionalProperties: false
+      required: [terminals]
+      properties:
+        terminals:
+          type: array
+          maxItems: 1000
+          items:
+            $ref: '#/components/schemas/Terminal'
+
+    AnalyticsScope:
+      type: object
+      additionalProperties: false
+      required: [terminalId]
+      properties:
+        terminalId:
+          type: [string, 'null']
+          minLength: 1
+          maxLength: 128
 
     RunId:
       type: string
@@ -1057,6 +1170,7 @@ components:
         - createdAt
         - updatedAt
         - eventsUrl
+        - scope
         - sections
       properties:
         runId:
@@ -1081,6 +1195,8 @@ components:
         eventsUrl:
           type: string
           format: uri-reference
+        scope:
+          $ref: '#/components/schemas/AnalyticsScope'
         sections:
           type: object
           additionalProperties: false
@@ -1246,6 +1362,7 @@ components:
         - paymentSuccessRate
         - verificationCompletionRate
         - comparisons
+        - paymentHistory
       properties:
         bankPaidSessions:
           allOf:
@@ -1265,6 +1382,32 @@ components:
             $ref: '#/components/schemas/PreviousPeriodComparison'
           propertyNames:
             enum: [bank_paid_sessions, bank_paid_amount_rial, payment_success_rate, verification_completion_rate]
+        paymentHistory:
+          type: array
+          maxItems: 93
+          items:
+            $ref: '#/components/schemas/PaymentHistoryPoint'
+
+    PaymentHistoryPoint:
+      type: object
+      additionalProperties: false
+      required: [localDate, totalSessions, bankPaidSessions, bankPaidAmountRial]
+      properties:
+        localDate:
+          type: string
+          format: date
+        totalSessions:
+          type: integer
+          format: int64
+          minimum: 0
+        bankPaidSessions:
+          type: integer
+          format: int64
+          minimum: 0
+        bankPaidAmountRial:
+          type: integer
+          format: int64
+          minimum: 0
 
     PaymentPerformanceData:
       type: object
@@ -1449,7 +1592,7 @@ components:
 
     DetailView:
       type: string
-      enum: [UNVERIFIED_PAID, FAILED, RETRIED]
+      enum: [ALL, UNVERIFIED_PAID, FAILED, RETRIED]
     FailureStage:
       type: string
       enum: [NO_ATTEMPT, REACHED_BANK, OTHER_OBSERVED]
@@ -1573,6 +1716,18 @@ components:
               oneOf:
                 - $ref: '#/components/schemas/FailureStage'
                 - type: 'null'
+            status:
+              oneOf:
+                - $ref: '#/components/schemas/SessionStatus'
+                - type: 'null'
+            minAmountRial:
+              type: [integer, 'null']
+              format: int64
+              minimum: 0
+            maxAmountRial:
+              type: [integer, 'null']
+              format: int64
+              minimum: 0
         items:
           type: array
           maxItems: 100