@ume-group/contracts 0.2.1

package/README.md

@@ -0,0 +1,37 @@
+# @ume/contracts
+
+Shared TypeScript types and utilities for UME Group AS. This package defines the data contracts between Includu, Admetise, and the Player.
+
+> **Public repository.** This repo is intentionally public so Cloudflare Workers Builds (NGI) and CI can install `@ume-group/contracts` from GitHub Packages without authentication tokens. Verified 2026-03-29: contains only TypeScript type definitions and OpenAPI specifications — no secrets, API keys, or business logic. Any future EA audit should re-verify before adding sensitive content. See [EA audit session log](https://github.com/uMe-Group/ume-platform/blob/main/docs/session-logs/2026-03-29-npm-auth-fix-session.md).
+
+## Setup
+
+```bash
+npm run build    # Compile with tsc
+npm run dev      # Watch mode
+npm run test     # Run tests
+```
+
+## Exports
+
+```typescript
+import { type Project, type Overlay, type PublishedManifest } from '@ume/contracts';
+import { type Layer2Scene, type WebcamComposite } from '@ume/contracts/layer2';
+import { type ChromaKeySettings } from '@ume/contracts/segmentation';
+```
+
+## Publishing
+
+Published to GitHub Packages as `@ume-group/contracts`. Consuming repos use npm alias:
+```json
+"@ume/contracts": "npm:@ume-group/contracts@^0.1.0"
+```
+
+## Visibility Policy
+
+This repository and its npm package are **public**. This is a deliberate architectural decision:
+
+- **Rationale:** Eliminates npm auth token management across all Cloudflare Workers Builds and CI pipelines
+- **Prerequisite:** Repository must ONLY contain TypeScript types, OpenAPI specs, and test code — no secrets, credentials, or proprietary business logic
+- **Governance:** Any change adding sensitive content must first make the repo private and configure auth tokens per [ea-core-pm-documentation](https://github.com/Oss-Gruppen-AS/enterprise-continuum)
+- **Audit trail:** Decision made 2026-03-29 by Jørgen Scheel (CTO), documented in [session log](https://github.com/uMe-Group/ume-platform/blob/main/docs/session-logs/2026-03-29-npm-auth-fix-session.md)

package/dist/adserving.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Ad serving contracts for Admetise ↔ Includu Player
+ *
+ * Used by:
+ * - @ume/admetise (worker: builds and returns AdPods)
+ * - packages/player (fetches AdServeResponse, sends impression events)
+ */
+import type { AdSlotType } from './index';
+export interface AdServeRequest {
+    /** Includu publish ID */
+    publishId: string;
+    /** Viewer's ISO 3166-1 alpha-2 country code (e.g. "NO") */
+    viewerGeo?: string;
+    /** Device type for GAM targeting */
+    deviceType?: 'mobile' | 'tablet' | 'desktop' | 'ctv';
+    /**
+     * Random number for GAM frequency capping correlation.
+     * Generate once per player session: Math.floor(Math.random() * 1e10)
+     */
+    correlator?: number;
+    /** Content category for targeting (e.g. "entertainment", "sports") */
+    contentCategory?: string;
+    /** Video duration in seconds (for duration-based targeting) */
+    videoDuration?: number;
+    /** Page URL where player is embedded (for domain-based targeting) */
+    pageUrl?: string;
+}
+/**
+ * A single resolved ad break, ready for IMA SDK.
+ * The player receives a list of these at load time and passes adTagUrl to IMA.
+ */
+export interface AdPod {
+    /** Stable ID for tracking/billing (matches AdSlotMapping.id) */
+    id: string;
+    /** Source slot type */
+    slotType: AdSlotType;
+    /** Trigger in seconds from video start (preroll = 0, postroll = videoDuration) */
+    triggerTime?: number;
+    /** Or as percentage of video duration (0-100). One of triggerTime or triggerPercent. */
+    triggerPercent?: number;
+    /**
+     * Fully resolved GAM VAST URL. Pass directly to IMA SDK AdDisplayContainer.
+     * Includes: network code, ad unit path, custom targeting (Admetise billing keys),
+     * correlator, geo, and standard IMA params.
+     */
+    adTagUrl: string;
+    /** Maximum ad duration in seconds */
+    maxDuration?: number;
+    /** Normalized position for overlay ads (0–1) */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Display width in pixels (from AdSlotTemplate) */
+    width?: number;
+    /** Display height in pixels (from AdSlotTemplate) */
+    height?: number;
+    /**
+     * Admetise impression tracking URL.
+     * Player fires this as a GET request when IMA SDK confirms ad started.
+     * Format: https://studio.admetise.com/api/track?event=impression&podId=X&...
+     */
+    trackingUrl: string;
+}
+export interface AdServeResponse {
+    publishId: string;
+    pods: AdPod[];
+    /** ISO datetime when this was resolved (for cache TTL decisions) */
+    resolvedAt: string;
+    /** Echo of the request correlator */
+    correlator?: number;
+}
+export type AdEventType = 'impression' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'click' | 'skip';
+export interface AdImpressionEvent {
+    podId: string;
+    publishId: string;
+    eventType: AdEventType;
+    /** ISO 3166-1 alpha-2 (from viewer) */
+    geo?: string;
+    timestamp: string;
+}
+export type GamConnectionStatus = 'connected' | 'expired' | 'disconnected';
+export interface GamAuthStatus {
+    status: GamConnectionStatus;
+    networkCode?: string;
+    networkName?: string;
+    /** ISO datetime when the access token expires */
+    tokenExpiresAt?: string;
+    /** OAuth scopes granted */
+    scopes?: string[];
+}
+export interface GamAdUnit {
+    /** GAM ad unit ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Full ad unit hierarchy path, e.g. "/12345678/includu/preroll" */
+    adUnitPath: string;
+    /** Compatible slot types based on template/size */
+    compatibleSlotTypes?: AdSlotType[];
+}
+export type PodBuildStatus = 'pending' | 'building' | 'ready' | 'error';
+export interface PodStatusResponse {
+    podId: string;
+    status: PodBuildStatus;
+    /** Resolved pods (only when status is 'ready') */
+    pods?: AdPod[];
+    /** Error message (only when status is 'error') */
+    error?: string;
+    /** Suggested retry delay in milliseconds (only when pending/building) */
+    retryAfterMs?: number;
+}
+export interface TrackingEventRequest extends AdImpressionEvent {
+    /** Current playback position in seconds */
+    positionSeconds?: number;
+    /** Viewer's user agent string */
+    userAgent?: string;
+}
+export interface TrackingEventResponse {
+    accepted: boolean;
+    /** Unique event ID for deduplication */
+    eventId?: string;
+}
+export interface AdFormat {
+    /** Template ID (e.g. "preroll-15") */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description of the format */
+    description?: string;
+    /** Ad slot type */
+    type: AdSlotType;
+    /** Category for grouping */
+    category: 'video' | 'display' | 'companion';
+    /** Width in pixels (for display/companion) */
+    width?: number;
+    /** Height in pixels (for display/companion) */
+    height?: number;
+    /** Position for overlay ads */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+    /** Default duration in seconds */
+    duration?: number;
+    /** Maximum duration in seconds */
+    maxDuration?: number;
+    /** IAB standard size identifier */
+    iabSize?: string;
+    /** Whether this format is currently available */
+    active: boolean;
+}
+//# sourceMappingURL=adserving.d.ts.map

package/dist/adserving.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adserving.d.ts","sourceRoot":"","sources":["../src/adserving.ts"],"names":[],"mappings":"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"}

package/dist/adserving.js

@@ -0,0 +1,8 @@
+/**
+ * Ad serving contracts for Admetise ↔ Includu Player
+ *
+ * Used by:
+ * - @ume/admetise (worker: builds and returns AdPods)
+ * - packages/player (fetches AdServeResponse, sends impression events)
+ */
+export {};

package/dist/campaigns.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Campaign types for the Admetise ad platform
+ *
+ * Used by:
+ * - @ume/admetise (campaign management, ad serving)
+ * - @includu/editor (monetization panel, creator approval UI)
+ */
+export type CampaignStatus = 'draft' | 'pending_approval' | 'approved' | 'active' | 'paused' | 'ended';
+export type CampaignType = 'exclusive' | 'non_exclusive';
+export interface GeoTargeting {
+    /** ISO 3166-1 alpha-2 country codes (e.g., ["NO", "SE", "DK"]) */
+    countries?: string[];
+    /** Region/state identifiers */
+    regions?: string[];
+}
+export interface AdSlotReference {
+    /** Ad slot template ID (from AdSlotTemplate in @ume/contracts) */
+    templateId: string;
+    /** Optional override for max duration in seconds */
+    maxDuration?: number;
+}
+export interface ExclusiveCampaign {
+    id: string;
+    advertiserId: string;
+    title: string;
+    status: CampaignStatus;
+    type: CampaignType;
+    targeting: GeoTargeting;
+    /** Ad slot references for this campaign */
+    slots: AdSlotReference[];
+    /** GAM ad unit path for this exclusive (e.g. "/12345678/includu/exclusive-acme") */
+    gamAdUnitPath: string;
+    createdAt: string;
+    startsAt: string;
+    endsAt: string;
+}
+//# sourceMappingURL=campaigns.d.ts.map

package/dist/campaigns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaigns.d.ts","sourceRoot":"","sources":["../src/campaigns.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,kBAAkB,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AACvG,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,eAAe,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC5B,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC/B,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,YAAY,CAAC;IACxB,2CAA2C;IAC3C,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACf"}

package/dist/campaigns.js

@@ -0,0 +1,8 @@
+/**
+ * Campaign types for the Admetise ad platform
+ *
+ * Used by:
+ * - @ume/admetise (campaign management, ad serving)
+ * - @includu/editor (monetization panel, creator approval UI)
+ */
+export {};

package/dist/gausst.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Gausst Coordinate System Utilities
+ *
+ * Implements the coordinate system from Patent US8761580B2 and the
+ * legacy Gausst Maya plugin (gausstCamera.cpp).
+ *
+ * This system enables accurate camera matching between physical tracked
+ * cameras and virtual 3D scenes.
+ *
+ * Key features:
+ * - 35mm full-frame equivalent film gate (1.417" × 0.945")
+ * - FOV ↔ focal length conversion
+ * - Gausst rotation order: Tilt → Pan (negated) → Roll (negated)
+ * - Video plane sizing at distance
+ */
+export declare const GAUSST: {
+    readonly HORIZONTAL_APERTURE: 1.417;
+    readonly VERTICAL_APERTURE: 0.945;
+    readonly DEFAULT_FOCAL_LENGTH: 35;
+    readonly VIDEO_PLANE_DISTANCE: 500;
+    readonly DEFAULT_OVERSCAN: 1.3;
+    readonly DEG_TO_RAD: number;
+    readonly RAD_TO_DEG: number;
+    readonly MM_PER_INCH: 25.4;
+    readonly DEFAULT_CAMERA_POSITION: readonly [number, number, number];
+    readonly DEFAULT_FOV: 60;
+};
+/**
+ * Convert field of view (degrees) to focal length (mm)
+ *
+ * Formula from legacy gausstCamera.h:
+ *   focalLength = ((aperture / 2) / tan(fieldOfView / 2)) * 25.4
+ *
+ * @param fovDegrees - Horizontal field of view in degrees
+ * @param apertureInches - Horizontal film aperture in inches (default: 35mm equivalent)
+ * @returns Focal length in millimeters
+ *
+ * @example
+ * fovToFocalLength(60) // ≈ 31mm
+ * fovToFocalLength(90) // ≈ 18mm
+ * fovToFocalLength(45) // ≈ 43mm
+ */
+export declare function fovToFocalLength(fovDegrees: number, apertureInches?: number): number;
+/**
+ * Convert focal length (mm) to field of view (degrees)
+ *
+ * Inverse of fovToFocalLength
+ *
+ * @param focalLengthMM - Focal length in millimeters
+ * @param apertureInches - Horizontal film aperture in inches (default: 35mm equivalent)
+ * @returns Horizontal field of view in degrees
+ *
+ * @example
+ * focalLengthToFov(35) // ≈ 54.4°
+ * focalLengthToFov(50) // ≈ 39.6°
+ * focalLengthToFov(24) // ≈ 73.7°
+ */
+export declare function focalLengthToFov(focalLengthMM: number, apertureInches?: number): number;
+/**
+ * Convert Gausst rotation (tilt, pan, roll) to Euler angles for Three.js
+ *
+ * From legacy gausstCamera.cpp moveTheCamera():
+ * - Maya rotation order: tilt, pan, roll
+ * - Pan and Roll are NEGATED before application
+ * - Three.js equivalent: 'YXZ' Euler order
+ *
+ * @param tiltDeg - Tilt (pitch) in degrees - rotation around X axis
+ * @param panDeg - Pan (yaw) in degrees - rotation around Y axis (will be negated)
+ * @param rollDeg - Roll in degrees - rotation around Z axis (will be negated)
+ * @returns Object with euler values and order for Three.js
+ *
+ * @example
+ * const { x, y, z, order } = gausst RotationToEuler(10, 20, 5);
+ * mesh.rotation.set(x, y, z);
+ * mesh.rotation.order = order;
+ */
+export declare function gausstRotationToEuler(tiltDeg: number, panDeg: number, rollDeg: number): {
+    x: number;
+    y: number;
+    z: number;
+    order: 'YXZ';
+};
+/**
+ * Convert Three.js Euler angles back to Gausst rotation
+ *
+ * Inverse of gausst RotationToEuler - extracts tilt, pan, roll from Euler
+ * Assumes the object uses 'YXZ' rotation order
+ *
+ * @param x - Euler X rotation in radians
+ * @param y - Euler Y rotation in radians
+ * @param z - Euler Z rotation in radians
+ * @returns Gausst rotation as [tilt, pan, roll] in degrees
+ */
+export declare function eulerToGausstRotation(x: number, y: number, z: number): [number, number, number];
+/**
+ * Calculate video plane dimensions at a given distance from camera
+ *
+ * From legacy gausstCamera.cpp draw():
+ *   horizontalSize = videoPolygonDistance * horizontalFilmApertureValue * 25.4f / focalLengthValue;
+ *   verticalSize = videoPolygonDistance * verticalFilmApertureValue * 25.4f / focalLengthValue;
+ *
+ * @param distance - Distance from camera in world units
+ * @param focalLengthMM - Focal length in millimeters
+ * @param horizontalAperture - Horizontal film aperture in inches
+ * @param verticalAperture - Vertical film aperture in inches
+ * @returns Width and height of video plane at that distance
+ *
+ * @example
+ * // Video plane at 10m with 35mm lens
+ * const { width, height } = getVideoPlaneSize(10, 35);
+ * // width ≈ 10.27m, height ≈ 6.85m
+ */
+export declare function getVideoPlaneSize(distance: number, focalLengthMM: number, horizontalAperture?: number, verticalAperture?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Calculate video plane dimensions using FOV instead of focal length
+ *
+ * @param distance - Distance from camera in world units
+ * @param fovDegrees - Horizontal field of view in degrees
+ * @returns Width and height of video plane at that distance
+ */
+export declare function getVideoPlaneSizeFromFov(distance: number, fovDegrees: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Convert tracking packet position to world coordinates
+ *
+ * From legacy gausstCamera.cpp moveTheCamera():
+ *   Xpos = convert4bytesToFloat(&theBuffer[6]) / 1000;
+ *   (Position comes as mm × 100, divide by 1000 to get meters)
+ *
+ * @param packetValue - Raw value from tracking packet (mm × 100)
+ * @returns Position in meters
+ */
+export declare function trackingPacketToMeters(packetValue: number): number;
+/**
+ * Convert meters to tracking packet format
+ *
+ * @param meters - Position in meters
+ * @returns Raw value for tracking packet (mm × 100)
+ */
+export declare function metersToTrackingPacket(meters: number): number;
+/**
+ * Get the default aspect ratio from Gausst film gate
+ *
+ * @returns Aspect ratio (width / height)
+ */
+export declare function getGausstAspectRatio(): number;
+/**
+ * Calculate vertical FOV from horizontal FOV using Gausst aspect ratio
+ *
+ * @param horizontalFovDeg - Horizontal field of view in degrees
+ * @returns Vertical field of view in degrees
+ */
+export declare function horizontalToVerticalFov(horizontalFovDeg: number): number;
+/**
+ * Calculate horizontal FOV from vertical FOV using Gausst aspect ratio
+ *
+ * @param verticalFovDeg - Vertical field of view in degrees
+ * @returns Horizontal field of view in degrees
+ */
+export declare function verticalToHorizontalFov(verticalFovDeg: number): number;
+/**
+ * Apply Gausst rotation directly to a Three.js Object3D
+ *
+ * This is the primary function for setting rotation on 3D objects
+ * using the Gausst coordinate system.
+ *
+ * @param object - Three.js Object3D (mesh, camera, group, etc.)
+ * @param tiltDeg - Tilt (pitch) in degrees
+ * @param panDeg - Pan (yaw) in degrees
+ * @param rollDeg - Roll in degrees
+ *
+ * @example
+ * import * as THREE from 'three';
+ * const mesh = new THREE.Mesh(geometry, material);
+ * applyGausstRotation(mesh, 10, 45, 0); // 10° tilt, 45° pan
+ */
+export declare function applyGausstRotation(object: {
+    rotation: {
+        order: string;
+        set: (x: number, y: number, z: number) => void;
+    };
+}, tiltDeg: number, panDeg: number, rollDeg: number): void;
+/**
+ * Configure a Three.js PerspectiveCamera with Gausst parameters
+ *
+ * @param camera - Three.js PerspectiveCamera
+ * @param fovDegrees - Horizontal field of view in degrees
+ * @param position - Camera position [x, y, z] in meters
+ * @param lookAt - Look-at target [x, y, z] in meters
+ *
+ * @example
+ * const camera = new THREE.PerspectiveCamera();
+ * configureGausstCamera(camera, 60, [0, 1.6, 0], [0, 1.6, -10]);
+ */
+export declare function configureGausstCamera(camera: {
+    fov: number;
+    position: {
+        set: (x: number, y: number, z: number) => void;
+    };
+    lookAt: (x: number, y: number, z: number) => void;
+    updateProjectionMatrix: () => void;
+}, fovDegrees: number, position: [number, number, number], lookAt: [number, number, number]): void;
+/**
+ * Validate FOV is within reasonable bounds
+ *
+ * @param fovDegrees - Field of view to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidFov(fovDegrees: number): boolean;
+/**
+ * Validate focal length is within reasonable bounds
+ *
+ * @param focalLengthMM - Focal length to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidFocalLength(focalLengthMM: number): boolean;
+/**
+ * Clamp FOV to valid range
+ *
+ * @param fovDegrees - FOV to clamp
+ * @returns Clamped FOV
+ */
+export declare function clampFov(fovDegrees: number): number;
+/**
+ * Clamp rotation to reasonable range (-180 to 180)
+ *
+ * @param degrees - Rotation in degrees
+ * @returns Normalized rotation in -180 to 180 range
+ */
+export declare function normalizeRotation(degrees: number): number;
+//# sourceMappingURL=gausst.d.ts.map

package/dist/gausst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gausst.d.ts","sourceRoot":"","sources":["../src/gausst.ts"],"names":[],"mappings":"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"}