@ume-group/contracts 0.2.1

package/openapi/integration.yaml

@@ -0,0 +1,372 @@
+openapi: 3.1.0
+info:
+  title: Includu-Admetise Integration API
+  description: |
+    API contracts for integration between Includu (content creation) and Admetise (monetization) platforms.
+
+    ## Overview
+    - Includu publishes content with ad slot definitions
+    - Admetise imports content and fills ad slots with campaigns
+    - Both platforms share analytics events
+
+    ## Authentication
+    - Public endpoints: Published manifests (read-only)
+    - Internal endpoints: Cloudflare service bindings (no external auth)
+    - Authenticated endpoints: Bearer token (platform-specific)
+  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: Includu API (Production)
+  - url: https://studio.admetise.com
+    description: Admetise API (Production)
+
+tags:
+  - name: Includu
+    description: Content creation and publishing
+  - name: Admetise
+    description: Monetization and ad serving
+  - name: Analytics
+    description: Unified event tracking
+
+paths:
+  # ============================================
+  # INCLUDU ENDPOINTS
+  # ============================================
+
+  /api/published/{publishId}:
+    get:
+      tags:
+        - Includu
+      summary: Get published manifest
+      description: |
+        Retrieves a published content manifest by its publish ID.
+        This endpoint is public and can be called by Admetise to import content.
+      operationId: getPublishedManifest
+      parameters:
+        - name: publishId
+          in: path
+          required: true
+          description: Unique publish identifier (nanoid)
+          schema:
+            type: string
+            example: "abc123xyz"
+      responses:
+        '200':
+          description: Published manifest retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PublishedManifest'
+        '404':
+          description: Published content not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  # ============================================
+  # ADMETISE ENDPOINTS
+  # ============================================
+
+  /api/configs/import:
+    post:
+      tags:
+        - Admetise
+      summary: Import content from Includu
+      description: |
+        Creates a new PlayerConfig by importing a published manifest from Includu.
+        Maps Includu ad slots to Admetise ad zones.
+      operationId: importFromIncludu
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ImportRequest'
+      responses:
+        '201':
+          description: Content imported successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ImportResponse'
+        '400':
+          description: Invalid request or Includu content not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  # ============================================
+  # ANALYTICS ENDPOINTS
+  # ============================================
+
+  /api/analytics/track:
+    post:
+      tags:
+        - Analytics
+      summary: Track analytics event
+      description: |
+        Records a unified analytics event from either platform.
+        Events are attributed to both Includu content and Admetise campaigns.
+      operationId: trackEvent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AnalyticsEvent'
+      responses:
+        '200':
+          description: Event tracked successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  eventId:
+                    type: string
+                    example: "evt_abc123"
+        '400':
+          description: Invalid event data
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /api/analytics/creator/{publishId}:
+    get:
+      tags:
+        - Analytics
+      summary: Get creator analytics
+      description: |
+        Retrieves analytics for a specific published content.
+        Used by Includu to show creators their earnings and engagement.
+      operationId: getCreatorAnalytics
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: publishId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: startDate
+          in: query
+          schema:
+            type: string
+            format: date
+        - name: endDate
+          in: query
+          schema:
+            type: string
+            format: date
+      responses:
+        '200':
+          description: Analytics retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreatorAnalytics'
+        '401':
+          description: Authentication required
+        '403':
+          description: Not authorized to view this content's analytics
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+  schemas:
+    # Shared types — canonical definitions in shared/schemas.yaml
+    AdSlot:
+      $ref: 'shared/schemas.yaml#/components/schemas/AdSlot'
+    AdZone:
+      $ref: 'shared/schemas.yaml#/components/schemas/AdZone'
+    PublishedManifest:
+      $ref: 'shared/schemas.yaml#/components/schemas/PublishedManifest'
+    PublishedOverlay:
+      $ref: 'shared/schemas.yaml#/components/schemas/PublishedOverlay'
+    Error:
+      $ref: 'shared/schemas.yaml#/components/schemas/Error'
+
+    # ============================================
+    # ADMETISE TYPES
+    # ============================================
+
+    ImportRequest:
+      type: object
+      description: Request to import Includu content
+      required:
+        - includuPublishId
+      properties:
+        includuPublishId:
+          type: string
+          description: Includu publish ID to import
+          example: "abc123xyz"
+        name:
+          type: string
+          description: Optional name override
+        campaignId:
+          type: string
+          description: Campaign to associate with imported content
+        adTagOverrides:
+          type: object
+          description: Override ad tags by slot type
+          additionalProperties:
+            type: string
+          example:
+            preroll: "https://pubads.g.doubleclick.net/..."
+
+    ImportResponse:
+      type: object
+      description: Result of content import
+      required:
+        - configId
+        - name
+        - contentUrl
+        - adZones
+      properties:
+        configId:
+          type: string
+          description: Created PlayerConfig ID
+        name:
+          type: string
+        contentUrl:
+          type: string
+          format: uri
+          description: HLS stream URL from Includu
+        sourcePublishId:
+          type: string
+          description: Original Includu publish ID
+        adZones:
+          type: array
+          items:
+            $ref: '#/components/schemas/AdZone'
+        createdAt:
+          type: string
+          format: date-time
+
+    # ============================================
+    # ANALYTICS TYPES
+    # ============================================
+
+    AnalyticsEvent:
+      type: object
+      description: Unified analytics event
+      required:
+        - eventType
+        - source
+      properties:
+        eventType:
+          type: string
+          enum:
+            # Includu events
+            - overlayView
+            - overlayClick
+            - ctaClick
+            # Admetise events
+            - impression
+            - adStart
+            - adFirstQuartile
+            - adMidpoint
+            - adThirdQuartile
+            - adComplete
+            - adClick
+            - adSkip
+            - adError
+            # Playback events
+            - playbackStart
+            - playbackPause
+            - playbackComplete
+        source:
+          type: string
+          enum:
+            - includu
+            - admetise
+        publishId:
+          type: string
+          description: Includu content ID (for attribution)
+        configId:
+          type: string
+          description: Admetise config ID
+        zoneId:
+          type: string
+          description: Ad zone or overlay ID
+        sessionId:
+          type: string
+          description: Viewer session ID
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Event-specific metadata
+
+    CreatorAnalytics:
+      type: object
+      description: Analytics summary for content creator
+      properties:
+        publishId:
+          type: string
+        period:
+          type: object
+          properties:
+            start:
+              type: string
+              format: date
+            end:
+              type: string
+              format: date
+        metrics:
+          type: object
+          properties:
+            views:
+              type: integer
+              description: Total video views
+            overlayClicks:
+              type: integer
+              description: Clicks on creator overlays
+            ctaClicks:
+              type: integer
+              description: CTA button clicks
+            adImpressions:
+              type: integer
+              description: Ad impressions served
+            adClicks:
+              type: integer
+              description: Clicks on ads
+            estimatedRevenue:
+              type: number
+              description: Estimated earnings in USD
+        breakdown:
+          type: array
+          items:
+            type: object
+            properties:
+              date:
+                type: string
+                format: date
+              views:
+                type: integer
+              revenue:
+                type: number
+

package/openapi/shared/schemas.yaml

@@ -0,0 +1,227 @@
+# Shared OpenAPI schemas used across Includu and Admetise specs
+# Single source of truth — referenced via $ref from product specs
+
+components:
+  schemas:
+    Error:
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          type: string
+          description: Error message
+        code:
+          type: string
+          description: Error code
+        details:
+          type: object
+          additionalProperties: true
+
+    AdSlot:
+      type: object
+      description: Ad placement slot defined by content creator
+      required:
+        - id
+        - type
+      properties:
+        id:
+          type: string
+          description: Unique slot identifier
+          example: "slot_preroll_1"
+        type:
+          type: string
+          enum: [preroll, midroll, postroll, overlay, companion]
+          description: Type of ad placement
+        position:
+          type: string
+          enum: [top-left, top-right, bottom-left, bottom-right, center]
+          description: Position for overlay/companion slots
+        width:
+          type: integer
+          description: Slot width in pixels
+          example: 300
+        height:
+          type: integer
+          description: Slot height in pixels
+          example: 250
+        triggerFrame:
+          type: integer
+          description: Frame number for midroll trigger
+          example: 1440
+        triggerPercent:
+          type: number
+          description: Percentage of video for midroll trigger
+          minimum: 0
+          maximum: 100
+          example: 50
+        maxDuration:
+          type: integer
+          description: Maximum ad duration in seconds
+          example: 30
+        required:
+          type: boolean
+          description: Whether this slot must be filled
+          default: false
+
+    AdZone:
+      type: object
+      description: Ad zone in Admetise (mapped from AdSlot)
+      required:
+        - id
+        - type
+        - enabled
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum: [preroll, midroll, postroll, overlay, companion]
+        enabled:
+          type: boolean
+        position:
+          type: string
+          enum: [top-left, top-right, bottom-left, bottom-right, center]
+        width:
+          type: integer
+        height:
+          type: integer
+        triggerTime:
+          type: number
+          description: Trigger time in seconds (converted from frames)
+        triggerPercent:
+          type: number
+
+    PublishedOverlay:
+      type: object
+      description: Overlay defined by content creator
+      required:
+        - id
+        - type
+        - startFrame
+        - endFrame
+        - position
+        - content
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum: [text, emoji, shape, image, cta, sprite-sequence, video]
+        startFrame:
+          type: integer
+        endFrame:
+          type: integer
+        position:
+          type: object
+          properties:
+            x:
+              type: number
+              description: X position as percentage (0-100)
+            y:
+              type: number
+              description: Y position as percentage (0-100)
+            width:
+              type: number
+            height:
+              type: number
+        animation:
+          type: object
+          properties:
+            fadeIn:
+              type: integer
+            fadeOut:
+              type: integer
+            opacity:
+              type: number
+        content:
+          type: object
+          description: Type-specific content data
+
+    PublishedManifest:
+      type: object
+      description: Immutable published content manifest
+      required:
+        - publishId
+        - name
+        - video
+        - fps
+        - overlays
+      properties:
+        publishId:
+          type: string
+          description: Unique publish identifier
+          example: "abc123xyz"
+        name:
+          type: string
+          description: Content name
+          example: "My Awesome Video"
+        video:
+          type: object
+          required:
+            - hlsUrl
+            - duration
+          properties:
+            hlsUrl:
+              type: string
+              format: uri
+              description: HLS stream URL
+            duration:
+              type: number
+              description: Video duration in seconds
+            thumbnail:
+              type: string
+              format: uri
+            aspectRatio:
+              type: string
+              example: "16:9"
+        fps:
+          type: number
+          description: Frames per second
+          example: 24
+        overlays:
+          type: array
+          items:
+            $ref: '#/components/schemas/PublishedOverlay'
+        monetization:
+          type: object
+          description: Monetization configuration
+          properties:
+            enabled:
+              type: boolean
+              default: false
+            adSlots:
+              type: array
+              items:
+                $ref: '#/components/schemas/AdSlot'
+            revenueShare:
+              type: number
+              minimum: 0
+              maximum: 100
+              example: 70
+        branding:
+          type: object
+          properties:
+            logo:
+              type: string
+              format: uri
+            accentColor:
+              type: string
+              pattern: '^#[0-9A-Fa-f]{6}$'
+            showPoweredBy:
+              type: boolean
+              default: true
+        links:
+          type: object
+          properties:
+            player:
+              type: string
+              format: uri
+            embed:
+              type: string
+              format: uri
+            embedCode:
+              type: string
+            participate:
+              type: string
+              format: uri

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ume-group/contracts",
+  "version": "0.2.1",
+  "description": "Cross-brand API contracts for Includu and Admetise",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./layer2": {
+      "types": "./dist/layer2/index.d.ts",
+      "import": "./dist/layer2/index.js"
+    },
+    "./segmentation": {
+      "types": "./dist/segmentation/index.d.ts",
+      "import": "./dist/segmentation/index.js"
+    },
+    "./webcam": {
+      "types": "./dist/webcam/index.d.ts",
+      "import": "./dist/webcam/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uMe-Group/ume-contracts.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "openapi"
+  ],
+  "dependencies": {
+    "@mediapipe/tasks-vision": "^0.10.32"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.0"
+  }
+}