@ume-group/contracts 0.2.1

package/openapi/includu.yaml

@@ -0,0 +1,621 @@
+openapi: 3.1.0
+info:
+  title: Includu API
+  description: |
+    Content creation and publishing API for the Includu video inclusion platform.
+
+    ## Authentication
+    All endpoints except `/api/published/:id` and `/api/preview/:id` are behind
+    Cloudflare Zero Trust (`@ume.group` email policy).
+
+    ## Base URL
+    Production: `https://includu-api.ume-group-as.workers.dev`
+  version: 1.0.0
+  contact:
+    name: uMe Group
+    url: https://ume.group
+  license:
+    name: Proprietary
+
+servers:
+  - url: https://includu-api.ume-group-as.workers.dev
+    description: Production
+
+tags:
+  - name: Health
+    description: Service health check
+  - name: Upload
+    description: Video upload to R2
+  - name: Projects
+    description: Project CRUD
+  - name: Publishing
+    description: Publish and unpublish projects
+  - name: Video
+    description: Video streaming from R2
+  - name: Preview
+    description: Temporary preview manifests
+
+paths:
+  # =========================================================================
+  # HEALTH
+  # =========================================================================
+
+  /api/health:
+    get:
+      tags: [Health]
+      summary: Health check
+      operationId: getHealth
+      responses:
+        '200':
+          description: Service is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+                  environment:
+                    type: string
+                  timestamp:
+                    type: string
+                    format: date-time
+
+  # =========================================================================
+  # UPLOAD
+  # =========================================================================
+
+  /api/upload:
+    post:
+      tags: [Upload]
+      summary: Simple video upload
+      description: Upload a video file directly to R2. For files >100MB, use multipart upload.
+      operationId: uploadVideo
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file:
+                  type: string
+                  format: binary
+      responses:
+        '200':
+          description: Upload successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  key:
+                    type: string
+                    description: R2 object key
+                  size:
+                    type: integer
+        '400':
+          description: No file provided
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+
+  /api/upload/multipart/init:
+    post:
+      tags: [Upload]
+      summary: Initialize multipart upload
+      operationId: initMultipartUpload
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [projectId, filename, contentType, size, type]
+              properties:
+                projectId:
+                  type: string
+                  format: uuid
+                filename:
+                  type: string
+                contentType:
+                  type: string
+                size:
+                  type: integer
+                type:
+                  type: string
+                  enum: [video, proxy]
+      responses:
+        '200':
+          description: Multipart upload initialized
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  key:
+                    type: string
+                  uploadId:
+                    type: string
+
+  /api/upload/multipart/part:
+    put:
+      tags: [Upload]
+      summary: Upload a part
+      operationId: uploadPart
+      parameters:
+        - name: key
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: uploadId
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: partNumber
+          in: query
+          required: true
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      responses:
+        '200':
+          description: Part uploaded
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  etag:
+                    type: string
+
+  /api/upload/multipart/complete:
+    post:
+      tags: [Upload]
+      summary: Complete multipart upload
+      operationId: completeMultipartUpload
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [key, uploadId, parts]
+              properties:
+                key:
+                  type: string
+                uploadId:
+                  type: string
+                parts:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      partNumber:
+                        type: integer
+                      etag:
+                        type: string
+      responses:
+        '200':
+          description: Upload completed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  key:
+                    type: string
+
+  # =========================================================================
+  # PROJECTS
+  # =========================================================================
+
+  /api/projects:
+    get:
+      tags: [Projects]
+      summary: List all projects
+      operationId: listProjects
+      responses:
+        '200':
+          description: Projects listed (sorted by updatedAt desc)
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Project'
+    post:
+      tags: [Projects]
+      summary: Create a new project
+      operationId: createProject
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name]
+              properties:
+                name:
+                  type: string
+                fps:
+                  type: number
+                  default: 24
+                duration:
+                  type: number
+                  default: 0
+                videoSource:
+                  $ref: '#/components/schemas/VideoSource'
+      responses:
+        '201':
+          description: Project created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+
+  /api/projects/by-clip:
+    get:
+      tags: [Projects]
+      summary: Find projects by VMS clip
+      operationId: getProjectsByClip
+      parameters:
+        - name: clipId
+          in: query
+          schema:
+            type: string
+        - name: hlsUrl
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Matching projects
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Project'
+
+  /api/projects/{id}:
+    get:
+      tags: [Projects]
+      summary: Get project by ID
+      operationId: getProject
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      responses:
+        '200':
+          description: Project found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '404':
+          description: Project not found
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+    put:
+      tags: [Projects]
+      summary: Update project
+      operationId: updateProject
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Project'
+      responses:
+        '200':
+          description: Project updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '404':
+          description: Project not found
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+    delete:
+      tags: [Projects]
+      summary: Delete project
+      description: Deletes project and associated R2 video files.
+      operationId: deleteProject
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      responses:
+        '200':
+          description: Project deleted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deleted:
+                    type: boolean
+        '404':
+          description: Project not found
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+
+  # =========================================================================
+  # PUBLISHING
+  # =========================================================================
+
+  /api/projects/{id}/publish:
+    post:
+      tags: [Publishing]
+      summary: Publish project
+      description: |
+        Creates an immutable published manifest with player links.
+        Generates a nanoid publishId.
+      operationId: publishProject
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      responses:
+        '200':
+          description: Project published
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/PublishedManifest'
+        '404':
+          description: Project not found
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+
+  /api/projects/{id}/published:
+    get:
+      tags: [Publishing]
+      summary: List published versions
+      operationId: listPublishedVersions
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      responses:
+        '200':
+          description: Published versions
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: 'shared/schemas.yaml#/components/schemas/PublishedManifest'
+
+  /api/published/by-clip:
+    get:
+      tags: [Publishing]
+      summary: Find latest published version by clip
+      operationId: getPublishedByClip
+      parameters:
+        - name: clipId
+          in: query
+          schema:
+            type: string
+        - name: hlsUrl
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Published manifest found
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/PublishedManifest'
+        '404':
+          description: No published version found
+
+  /api/published/{id}:
+    get:
+      tags: [Publishing]
+      summary: Get published manifest
+      description: Public endpoint — no authentication required.
+      operationId: getPublishedManifest
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Publish ID (nanoid)
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Published manifest
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/PublishedManifest'
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+    delete:
+      tags: [Publishing]
+      summary: Unpublish a version
+      operationId: unpublish
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Unpublished
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deleted:
+                    type: boolean
+
+  # =========================================================================
+  # PREVIEW
+  # =========================================================================
+
+  /api/preview:
+    post:
+      tags: [Preview]
+      summary: Create temporary preview
+      description: Creates a temporary preview manifest with a 30-minute TTL.
+      operationId: createPreview
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Project'
+      responses:
+        '200':
+          description: Preview created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  previewId:
+                    type: string
+                  url:
+                    type: string
+                    format: uri
+
+  /api/preview/{id}:
+    get:
+      tags: [Preview]
+      summary: Get preview manifest
+      description: Public endpoint. Previews expire after 30 minutes.
+      operationId: getPreview
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Preview manifest
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/PublishedManifest'
+        '404':
+          description: Preview expired or not found
+
+  # =========================================================================
+  # VIDEO STREAMING
+  # =========================================================================
+
+  /api/video/{key}:
+    get:
+      tags: [Video]
+      summary: Stream video from R2
+      description: Proxies video from R2 with CORS headers and caching.
+      operationId: streamVideo
+      parameters:
+        - name: key
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Video stream
+          content:
+            video/*:
+              schema:
+                type: string
+                format: binary
+        '404':
+          description: Video not found
+
+components:
+  parameters:
+    ProjectId:
+      name: id
+      in: path
+      required: true
+      description: Project UUID
+      schema:
+        type: string
+        format: uuid
+
+  schemas:
+    VideoSource:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [vms, local, r2]
+        vmsClipId:
+          type: string
+        vmsStreamUid:
+          type: string
+        vmsHlsUrl:
+          type: string
+        vmsTitle:
+          type: string
+
+    Project:
+      type: object
+      required:
+        - id
+        - name
+        - fps
+        - duration
+        - overlays
+        - createdAt
+        - updatedAt
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+        fps:
+          type: number
+          example: 24
+        duration:
+          type: number
+          description: Video duration in seconds
+        overlays:
+          type: array
+          items:
+            $ref: 'shared/schemas.yaml#/components/schemas/PublishedOverlay'
+        videoSource:
+          $ref: '#/components/schemas/VideoSource'
+        monetization:
+          type: object
+          properties:
+            enabled:
+              type: boolean