@ume-group/contracts 0.2.1

package/openapi/admetise.yaml

@@ -0,0 +1,632 @@
+openapi: 3.1.0
+info:
+  title: Admetise API
+  description: |
+    Ad serving and campaign management API for the Admetise monetization platform.
+
+    ## Authentication
+    All endpoints are behind Cloudflare Zero Trust (`@ume.group` email policy).
+    The pod serving endpoints (`/api/v1/pods/*`) will be made public at launch.
+
+    ## Versioning
+    Cross-product boundary endpoints use `/api/v1/` prefix.
+    Internal studio endpoints use `/api/` (unversioned).
+  version: 1.0.0
+  contact:
+    name: uMe Group
+    url: https://ume.group
+  license:
+    name: Proprietary
+
+servers:
+  - url: https://studio.admetise.com
+    description: Production
+
+tags:
+  - name: Health
+    description: Service health check
+  - name: Campaigns
+    description: Campaign CRUD (Studio UI)
+  - name: Pods
+    description: Ad pod serving (Player integration)
+  - name: Tracking
+    description: Impression and event tracking
+  - name: Formats
+    description: Supported ad formats
+  - name: GAM
+    description: Google Ad Manager integration
+
+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
+
+  # =========================================================================
+  # CAMPAIGNS (existing, implemented)
+  # =========================================================================
+
+  /api/campaigns:
+    get:
+      tags: [Campaigns]
+      summary: List all campaigns
+      operationId: listCampaigns
+      responses:
+        '200':
+          description: Campaigns listed
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ExclusiveCampaign'
+    post:
+      tags: [Campaigns]
+      summary: Create a campaign
+      operationId: createCampaign
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [advertiserId, title, gamAdUnitPath, startsAt, endsAt]
+              properties:
+                advertiserId:
+                  type: string
+                title:
+                  type: string
+                gamAdUnitPath:
+                  type: string
+                startsAt:
+                  type: string
+                  format: date-time
+                endsAt:
+                  type: string
+                  format: date-time
+                budget:
+                  type: object
+                  properties:
+                    totalBudget:
+                      type: number
+                    currency:
+                      type: string
+                      default: NOK
+                targeting:
+                  type: object
+                  properties:
+                    geo:
+                      type: object
+                      properties:
+                        countries:
+                          type: array
+                          items:
+                            type: string
+      responses:
+        '201':
+          description: Campaign created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ExclusiveCampaign'
+        '400':
+          description: Missing required fields
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+
+  /api/campaigns/{id}:
+    get:
+      tags: [Campaigns]
+      summary: Get campaign by ID
+      operationId: getCampaign
+      parameters:
+        - $ref: '#/components/parameters/CampaignId'
+      responses:
+        '200':
+          description: Campaign found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ExclusiveCampaign'
+        '404':
+          description: Campaign not found
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+    put:
+      tags: [Campaigns]
+      summary: Update campaign
+      operationId: updateCampaign
+      parameters:
+        - $ref: '#/components/parameters/CampaignId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ExclusiveCampaign'
+      responses:
+        '200':
+          description: Campaign updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ExclusiveCampaign'
+        '404':
+          description: Campaign not found
+    delete:
+      tags: [Campaigns]
+      summary: Delete campaign
+      operationId: deleteCampaign
+      parameters:
+        - $ref: '#/components/parameters/CampaignId'
+      responses:
+        '204':
+          description: Campaign deleted
+        '404':
+          description: Campaign not found
+
+  # =========================================================================
+  # PODS (planned — issue #6)
+  # =========================================================================
+
+  /api/v1/pods/request:
+    post:
+      tags: [Pods]
+      summary: Request an ad pod
+      description: |
+        Player calls this at load time to get a resolved ad schedule.
+        Returns a list of AdPod objects with fully-built GAM VAST URLs.
+      operationId: requestPod
+      x-status: planned
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AdServeRequest'
+      responses:
+        '200':
+          description: Ad pod resolved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdServeResponse'
+        '404':
+          description: No matching campaigns or publish ID not found
+
+  /api/v1/pods/{podId}:
+    get:
+      tags: [Pods]
+      summary: Get pod build status
+      description: |
+        Poll this endpoint if the initial pod request returns a pending status.
+        Used for async VAST resolution when GAM needs extra processing time.
+      operationId: getPodStatus
+      x-status: planned
+      parameters:
+        - name: podId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Pod status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PodStatusResponse'
+        '404':
+          description: Pod not found
+
+  # =========================================================================
+  # TRACKING (planned — issue #6)
+  # =========================================================================
+
+  /api/v1/tracking/event:
+    post:
+      tags: [Tracking]
+      summary: Track ad event
+      description: |
+        Player fires this when IMA SDK reports an ad event (impression, quartile, click, etc.).
+        Used for Admetise-side billing and analytics.
+      operationId: trackEvent
+      x-status: planned
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TrackingEventRequest'
+      responses:
+        '200':
+          description: Event tracked
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TrackingEventResponse'
+        '400':
+          description: Invalid event data
+          content:
+            application/json:
+              schema:
+                $ref: 'shared/schemas.yaml#/components/schemas/Error'
+
+  # =========================================================================
+  # FORMATS (planned — issue #6)
+  # =========================================================================
+
+  /api/v1/formats:
+    get:
+      tags: [Formats]
+      summary: List supported ad formats
+      description: |
+        Returns the available ad format templates.
+        Used by Studio UI for campaign setup and by Player for rendering hints.
+      operationId: listFormats
+      x-status: planned
+      responses:
+        '200':
+          description: Available formats
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/AdFormat'
+
+  # =========================================================================
+  # GAM (planned — issue #6)
+  # =========================================================================
+
+  /api/v1/gam/status:
+    get:
+      tags: [GAM]
+      summary: Get GAM connection status
+      description: Returns the current OAuth connection state for Google Ad Manager.
+      operationId: getGamStatus
+      x-status: planned
+      responses:
+        '200':
+          description: GAM connection status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GamAuthStatus'
+
+  /api/v1/gam/ad-units:
+    get:
+      tags: [GAM]
+      summary: List GAM ad units
+      description: Fetches ad units from the connected GAM network for slot mapping.
+      operationId: listGamAdUnits
+      x-status: planned
+      responses:
+        '200':
+          description: Ad units from GAM
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/GamAdUnit'
+        '401':
+          description: GAM not connected
+
+components:
+  parameters:
+    CampaignId:
+      name: id
+      in: path
+      required: true
+      description: Campaign UUID
+      schema:
+        type: string
+        format: uuid
+
+  schemas:
+    ExclusiveCampaign:
+      type: object
+      required:
+        - id
+        - advertiserId
+        - title
+        - status
+        - gamAdUnitPath
+        - startsAt
+        - endsAt
+        - createdAt
+        - updatedAt
+      properties:
+        id:
+          type: string
+          format: uuid
+        advertiserId:
+          type: string
+        title:
+          type: string
+        status:
+          type: string
+          enum: [draft, pending_review, active, paused, completed, cancelled]
+        gamAdUnitPath:
+          type: string
+        startsAt:
+          type: string
+          format: date-time
+        endsAt:
+          type: string
+          format: date-time
+        budget:
+          type: object
+          properties:
+            totalBudget:
+              type: number
+            spent:
+              type: number
+            currency:
+              type: string
+        targeting:
+          type: object
+          properties:
+            geo:
+              type: object
+              properties:
+                countries:
+                  type: array
+                  items:
+                    type: string
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    AdServeRequest:
+      type: object
+      required:
+        - publishId
+      properties:
+        publishId:
+          type: string
+          description: Includu publish ID
+        viewerGeo:
+          type: string
+          description: ISO 3166-1 alpha-2 country code
+          example: "NO"
+        deviceType:
+          type: string
+          enum: [mobile, tablet, desktop, ctv]
+        correlator:
+          type: number
+          description: Random number for GAM frequency capping
+        contentCategory:
+          type: string
+          description: Content category for targeting
+        videoDuration:
+          type: number
+          description: Video duration in seconds
+        pageUrl:
+          type: string
+          format: uri
+          description: Page URL where player is embedded
+
+    AdServeResponse:
+      type: object
+      required:
+        - publishId
+        - pods
+        - resolvedAt
+      properties:
+        publishId:
+          type: string
+        pods:
+          type: array
+          items:
+            $ref: '#/components/schemas/AdPod'
+        resolvedAt:
+          type: string
+          format: date-time
+        correlator:
+          type: number
+
+    AdPod:
+      type: object
+      required:
+        - id
+        - slotType
+        - adTagUrl
+        - trackingUrl
+      properties:
+        id:
+          type: string
+        slotType:
+          type: string
+          enum: [preroll, midroll, postroll, overlay, companion]
+        triggerTime:
+          type: number
+        triggerPercent:
+          type: number
+        adTagUrl:
+          type: string
+          format: uri
+          description: Fully resolved GAM VAST URL
+        maxDuration:
+          type: integer
+        position:
+          type: object
+          properties:
+            x:
+              type: number
+            y:
+              type: number
+        width:
+          type: integer
+        height:
+          type: integer
+        trackingUrl:
+          type: string
+          format: uri
+
+    PodStatusResponse:
+      type: object
+      required:
+        - podId
+        - status
+      properties:
+        podId:
+          type: string
+        status:
+          type: string
+          enum: [pending, building, ready, error]
+          description: Pod build status
+        pods:
+          type: array
+          description: Resolved pods (only when status is ready)
+          items:
+            $ref: '#/components/schemas/AdPod'
+        error:
+          type: string
+          description: Error message (only when status is error)
+        retryAfterMs:
+          type: integer
+          description: Suggested retry delay in milliseconds (only when pending/building)
+
+    TrackingEventRequest:
+      type: object
+      required:
+        - podId
+        - publishId
+        - eventType
+        - timestamp
+      properties:
+        podId:
+          type: string
+        publishId:
+          type: string
+        eventType:
+          type: string
+          enum: [impression, firstQuartile, midpoint, thirdQuartile, complete, click, skip]
+        geo:
+          type: string
+          description: ISO 3166-1 alpha-2
+        timestamp:
+          type: string
+          format: date-time
+        positionSeconds:
+          type: number
+          description: Current playback position in seconds
+        userAgent:
+          type: string
+          description: Viewer's user agent string
+
+    TrackingEventResponse:
+      type: object
+      required:
+        - accepted
+      properties:
+        accepted:
+          type: boolean
+        eventId:
+          type: string
+          description: Unique event ID for deduplication
+
+    AdFormat:
+      type: object
+      required:
+        - id
+        - name
+        - type
+        - category
+        - active
+      properties:
+        id:
+          type: string
+          example: "preroll-15"
+        name:
+          type: string
+          example: "Standard Preroll (15s)"
+        description:
+          type: string
+        type:
+          type: string
+          enum: [preroll, midroll, postroll, overlay, companion]
+        category:
+          type: string
+          enum: [video, display, companion]
+        width:
+          type: integer
+        height:
+          type: integer
+        position:
+          type: string
+          enum: [top-left, top-right, bottom-left, bottom-right, center]
+        duration:
+          type: integer
+        maxDuration:
+          type: integer
+        iabSize:
+          type: string
+          example: "300x250"
+        active:
+          type: boolean
+
+    GamAuthStatus:
+      type: object
+      required:
+        - status
+      properties:
+        status:
+          type: string
+          enum: [connected, expired, disconnected]
+        networkCode:
+          type: string
+        networkName:
+          type: string
+        tokenExpiresAt:
+          type: string
+          format: date-time
+        scopes:
+          type: array
+          items:
+            type: string
+
+    GamAdUnit:
+      type: object
+      required:
+        - id
+        - name
+        - adUnitPath
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        adUnitPath:
+          type: string
+          example: "/12345678/includu/preroll"
+        compatibleSlotTypes:
+          type: array
+          items:
+            type: string
+            enum: [preroll, midroll, postroll, overlay, companion]