@thinkai/tai-api-contract 2.1.0 → 2.2.1

package/openapi/openapi.yaml

@@ -6,7 +6,6 @@ info:
     Contract surface for the Performance Intelligence Platform backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
     Legacy tenant-scoped routes (`/tenants/{tenantId}/...`, `/me/tenants`) were removed from runtime.
-    Admin routes use `/admin/...` and require role `admin`.
     Legacy HTTP routes that exist on the server but are not listed here (for example
     `PUT /workspaces/{workspaceId}/dashboard-settings`) remain supported for existing PIP clients;
     prefer OpenAPI-documented equivalents where available. Removal will be coordinated with ThinkAI releases.
@@ -31,8 +30,6 @@ tags:
     description: Squad and projects (§6)
   - name: Notifications
     description: Notifications (§7)
-  - name: AdminReviewer
-    description: Admin review queue (§8)
   - name: AIStrategy
     description: AI strategy recommendations (§9)
   - name: Journey
@@ -365,6 +362,15 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/DashboardProductivityDto"
+        "400":
+          description: Invalid query parameters
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
         "401":
           $ref: "#/components/responses/Unauthorized"
 
@@ -377,10 +383,10 @@ paths:
         - $ref: "#/components/parameters/WorkspaceId"
         - name: bucket
           in: query
-          schema: { type: string, enum: [day, week, month] }
+          schema: { type: string, enum: [day, week, month], default: week }
         - name: limit
           in: query
-          schema: { type: integer, minimum: 1 }
+          schema: { type: integer, minimum: 1, maximum: 52, default: 8 }
         - name: scope
           in: query
           schema:
@@ -402,167 +408,17 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/DashboardProductivityHistoryDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-
-  /admin/reviews:
-    get:
-      tags: [AdminReviewer]
-      summary: Admin review queue
-      operationId: listAdminReviews
-      parameters:
-        - name: status
-          in: query
-          schema: { type: string }
-        - name: priority
-          in: query
-          schema: { type: string }
-        - name: reviewer
-          in: query
-          schema: { type: string }
-      responses:
-        "200":
-          description: Queue and reviewer list
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/AdminDashboardDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-
-  /admin/reviews/{id}:
-    get:
-      tags: [AdminReviewer]
-      summary: Single review submission
-      operationId: getAdminReview
-      parameters:
-        - $ref: "#/components/parameters/ReviewId"
-      responses:
-        "200":
-          description: Review detail
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ReviewSubmissionDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-    patch:
-      tags: [AdminReviewer]
-      summary: Update review metadata
-      operationId: patchAdminReview
-      parameters:
-        - $ref: "#/components/parameters/ReviewId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/PatchAdminReviewBodyDto"
-      responses:
-        "200":
-          description: Updated review
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ReviewSubmissionDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-
-  /admin/reviews/{id}/sections/{sectionId}/comments:
-    post:
-      tags: [AdminReviewer]
-      summary: Add section comment
-      operationId: postAdminReviewComment
-      parameters:
-        - $ref: "#/components/parameters/ReviewId"
-        - $ref: "#/components/parameters/SectionId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/AdminCommentBodyDto"
-      responses:
-        "200":
-          description: Created comment
+        "400":
+          description: Invalid query parameters
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/CommentDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-
-  /admin/reviews/{id}/sections/{sectionId}/decision:
-    put:
-      tags: [AdminReviewer]
-      summary: Set section decision
-      operationId: putAdminReviewSectionDecision
-      parameters:
-        - $ref: "#/components/parameters/ReviewId"
-        - $ref: "#/components/parameters/SectionId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/SectionDecisionBodyDto"
-      responses:
-        "204":
-          description: Saved
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-
-  /admin/reviews/{id}/pricing:
-    put:
-      tags: [AdminReviewer]
-      summary: Update pricing lines
-      operationId: putAdminReviewPricing
-      parameters:
-        - $ref: "#/components/parameters/ReviewId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/PricingUpdateBodyDto"
-      responses:
-        "204":
-          description: Saved
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-
-  /admin/reviews/{id}/deployment:
-    put:
-      tags: [AdminReviewer]
-      summary: Update deployment plan
-      operationId: putAdminReviewDeployment
-      parameters:
-        - $ref: "#/components/parameters/ReviewId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/DeploymentPlanDto"
-      responses:
-        "204":
-          description: Saved
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
         "401":
           $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
 
   /workspaces/{workspaceId}/company-profile:
     get:
@@ -680,6 +536,143 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/integrations/github/install-url:
+    post:
+      tags: [Integrations]
+      summary: Create GitHub App installation URL
+      operationId: postGithubInstallUrl
+      description: >
+        Creates a GitHub App installation URL scoped to the workspace and caller.
+        Body is optional; when omitted, defaults to `/phase-a/p3` return path.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GithubInstallUrlRequestDto"
+      responses:
+        "200":
+          description: Installation URL + signed state
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubInstallUrlResponseDto"
+        "400":
+          description: Request validation failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /integrations/github/callback:
+    get:
+      tags: [Integrations]
+      summary: GitHub App installation callback
+      operationId: getGithubInstallCallback
+      description: >
+        Public callback endpoint used by GitHub App installation flow.
+        Resolves and consumes install state, persists workspace installation linkage,
+        then redirects to configured SPA origin with status markers.
+      parameters:
+        - name: state
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: installation_id
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: setup_action
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        "302":
+          description: Redirect to ThinkAI SPA return path with GitHub connection status
+        "501":
+          description: Workspace store not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: SPA origin configuration missing
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /integrations/github/webhook:
+    post:
+      tags: [Integrations]
+      summary: GitHub App webhook receiver
+      operationId: postGithubWebhook
+      description: >
+        Public webhook endpoint that verifies `X-Hub-Signature-256` and updates or
+        removes workspace GitHub integration/cache state for installation events.
+      parameters:
+        - name: X-Hub-Signature-256
+          in: header
+          required: true
+          schema:
+            type: string
+        - name: X-GitHub-Event
+          in: header
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+      responses:
+        "200":
+          description: Webhook accepted
+        "400":
+          description: Invalid payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          description: Invalid webhook signature
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Workspace store not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Missing GitHub webhook secret or GitHub App configuration
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/ai-readiness:
     get:
       tags: [AIReadiness]
@@ -1311,18 +1304,6 @@ components:
       required: true
       schema:
         type: string
-    ReviewId:
-      name: id
-      in: path
-      required: true
-      schema:
-        type: string
-    SectionId:
-      name: sectionId
-      in: path
-      required: true
-      schema:
-        type: string
     NotificationId:
       name: id
       in: path
@@ -1471,6 +1452,11 @@ components:
       properties:
         workspaceId:
           type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+          description: Response generation time (RFC 3339).
         windowStart:
           type: string
           format: date-time
@@ -1488,8 +1474,14 @@ components:
 
     DashboardProductivityHistoryDto:
       type: object
-      required: [buckets]
+      required: [workspaceId, bucket, buckets]
       properties:
+        workspaceId:
+          type: string
+          format: uuid
+        bucket:
+          type: string
+          enum: [day, week, month]
         buckets:
           type: array
           items:
@@ -1653,6 +1645,29 @@ components:
           format: date-time
           nullable: true
 
+    GithubInstallUrlRequestDto:
+      type: object
+      additionalProperties: false
+      properties:
+        returnPath:
+          type: string
+          pattern: '^/[A-Za-z0-9/_\-\?\=&]*$'
+          maxLength: 256
+
+    GithubInstallUrlResponseDto:
+      type: object
+      additionalProperties: false
+      required: [url, state]
+      properties:
+        url:
+          type: string
+          format: uri
+          maxLength: 2048
+        state:
+          type: string
+          minLength: 16
+          maxLength: 128
+
     AIReadinessDto:
       type: object
       required:
@@ -2186,200 +2201,6 @@ components:
         total:
           type: integer
 
-    ReviewQueueItemDto:
-      type: object
-      required: [id, client, project, workflows, submittedAt, reviewer, status, priority]
-      properties:
-        id:
-          type: string
-        client:
-          type: string
-        project:
-          type: string
-        workflows:
-          type: array
-          items:
-            type: string
-            enum: [greenfield, brownfield]
-        submittedAt:
-          type: string
-          format: date-time
-        reviewer:
-          type: string
-          nullable: true
-        status:
-          type: string
-          enum: [pending, in_review, approved, changes_requested]
-        priority:
-          type: string
-          enum: [high, medium, low]
-
-    AdminDashboardDto:
-      type: object
-      required: [queue, reviewers]
-      properties:
-        queue:
-          type: array
-          items:
-            $ref: "#/components/schemas/ReviewQueueItemDto"
-        reviewers:
-          type: array
-          items:
-            type: string
-
-    PatchAdminReviewBodyDto:
-      type: object
-      properties:
-        status:
-          type: string
-          enum: [pending, in_review, approved, changes_requested]
-        reviewer:
-          type: string
-        priority:
-          type: string
-          enum: [high, medium, low]
-
-    CommentDto:
-      type: object
-      required: [id, sectionId, author, text, timestamp]
-      properties:
-        id:
-          type: string
-        sectionId:
-          type: string
-        author:
-          type: string
-        text:
-          type: string
-        timestamp:
-          type: string
-          format: date-time
-
-    AdminCommentBodyDto:
-      type: object
-      required: [text]
-      properties:
-        text:
-          type: string
-
-    SectionDecisionBodyDto:
-      type: object
-      required: [decision]
-      properties:
-        decision:
-          type: string
-          enum: [pending, approved, changes_requested, rejected]
-
-    PricingLineDto:
-      type: object
-      required: [id, label, rate, hours]
-      properties:
-        id:
-          type: string
-        label:
-          type: string
-        rate:
-          type: number
-        hours:
-          type: number
-
-    PricingUpdateBodyDto:
-      type: object
-      required: [items]
-      properties:
-        items:
-          type: array
-          items:
-            type: object
-            required: [id, rate, hours]
-            properties:
-              id:
-                type: string
-              rate:
-                type: number
-              hours:
-                type: number
-
-    DeploymentPlanDto:
-      type: object
-      required: [startDate, endDate, milestones]
-      properties:
-        startDate:
-          type: string
-        endDate:
-          type: string
-        milestones:
-          type: array
-          items:
-            type: string
-
-    ReviewSectionDto:
-      type: object
-      required: [id, label, detail, decision, comments]
-      properties:
-        id:
-          type: string
-        label:
-          type: string
-        detail:
-          type: string
-        decision:
-          type: string
-          enum: [pending, approved, changes_requested, rejected]
-        comments:
-          type: array
-          items:
-            $ref: "#/components/schemas/CommentDto"
-
-    ReviewSubmissionDto:
-      type: object
-      required:
-        - id
-        - client
-        - project
-        - workflows
-        - status
-        - isResubmission
-        - context
-        - sections
-        - pricing
-        - deployment
-      properties:
-        id:
-          type: string
-        client:
-          type: string
-        project:
-          type: string
-        workflows:
-          type: array
-          items:
-            type: string
-            enum: [greenfield, brownfield]
-        status:
-          type: string
-          enum: [pending, in_review, approved, changes_requested]
-        isResubmission:
-          type: boolean
-        context:
-          type: array
-          items:
-            type: object
-            required: [text]
-            properties:
-              text:
-                type: string
-        sections:
-          type: array
-          items:
-            $ref: "#/components/schemas/ReviewSectionDto"
-        pricing:
-          type: array
-          items:
-            $ref: "#/components/schemas/PricingLineDto"
-        deployment:
-          $ref: "#/components/schemas/DeploymentPlanDto"
-
     EffectiveTaskRowDto:
       type: object
       required: [id, name, summary, source]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "private": false,
   "type": "module",
   "main": "dist/index.js",