vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/aiGen/providers/types.d.ts

@@ -1,22 +1,98 @@
-import { ETextGenModels, EVideoGenModels } from "../../../globals/aiModels";
+import { EImageGenModelKey, EMusicGenModels, ESfxGenModels, ETextGenModels, EVideoGenModels } from "../../../globals/aiModels";
 import { EVideoSceneStatus, TVideoJobTask } from "../../../globals/types";
 import { EVideoMode } from "../types";
+import type { CameraControl } from "../canonicalAdapters/cameraControl.types";
+import type { MultiShot } from "../canonicalAdapters/multiShot.types";
 export interface VideoGenerationParams {
     prompt?: string;
     modelKey: EVideoGenModels;
+    /** End-user ID — required by some providers for compliance tagging (e.g. ByteDance KYC). */
+    userId?: string;
     resolution?: string;
     aspectRatio?: string;
     dimensions?: string;
     duration?: number;
+    mode?: EVideoMode;
+    type?: "text-to-video" | "image-to-video" | "video-to-video";
+    /**
+     * Granular endpoint selector when a provider offers multiple sub-endpoints
+     * for the same model (e.g. Pixverse: text/image/transition/extend/effect;
+     * Sora 2: generate/extension/edit; Kling: t2v/i2v/motion-control). Falls
+     * back to inferring from `type` and presence of input fields.
+     */
+    endpoint?: "text-to-video" | "image-to-video" | "video-to-video" | "reference-to-video" | "extend" | "transition" | "effect" | "edit" | "extension" | "motion-control";
     inputVideoUrl?: string;
     inputImageUrl?: string;
+    /** Last-frame image (Veo lastFrame, Kling image_tail, Pixverse last_frame, Wan media[].last_frame). */
+    lastFrameImageUrl?: string;
+    /** Audio used to drive lip-sync / talking-head (Kling avatar, Wan S2V, Veo audio_url). */
     inputAudioUrl?: string;
-    mode?: EVideoMode;
-    type?: "text-to-video" | "image-to-video" | "video-to-video";
+    /**
+     * Duration of inputAudioUrl in milliseconds. Required for Kling lip-sync to set
+     * `sound_end_time` correctly (Kling rejects end_time > actual audio duration).
+     * If omitted, defaults to 60 000 ms (60 s max).
+     */
+    audioDurationMs?: number;
+    /**
+     * Reference images for character/scene/style consistency or character-to-video.
+     * Limits vary per provider (Veo 3.1 ≤3, Runway Gen-4 ≤3, ByteDance r2v ≤9, MiniMax S2V 1).
+     */
+    referenceImageUrls?: string[];
+    /** Reference videos (ByteDance r2v ≤3, combined 2–15s). */
+    referenceVideoUrls?: string[];
+    /** Reference audio clips (ByteDance r2v ≤3, combined ≤15s). */
+    referenceAudioUrls?: string[];
     audio?: boolean;
     negativePrompt?: string;
     multiClip?: boolean;
-    userId?: string;
+    seed?: number;
+    /** CFG / guidance scale (Kling 0.0–1.0, default 0.5). */
+    cfgScale?: number;
+    /** Disable / replace native watermark (Pixverse `water_mark`, Wan `watermark`). */
+    watermark?: boolean;
+    /** Provider-side prompt rewrite toggle (MiniMax `prompt_optimizer`, Wan `prompt_extend`). */
+    promptOptimizer?: boolean;
+    /** MiniMax Hailuo fast-pretreatment flag. */
+    fastPretreatment?: boolean;
+    motionMode?: "normal" | "fast";
+    style?: string;
+    templateId?: string;
+    soundEffect?: {
+        switch: boolean;
+        content?: string;
+    };
+    lipSync?: {
+        switch: boolean;
+        ttsContent?: string;
+        ttsSpeakerId?: string;
+    };
+    thinkingType?: "enabled" | "disabled" | "auto";
+    cameraControl?: CameraControl;
+    /** Static-area lock mask (Kling I2V — area to keep still). */
+    staticMaskUrl?: string;
+    /** Motion-brush regions (Kling I2V, ≤6 regions, each `{maskUrl, trajectories}`). */
+    dynamicMasks?: Array<{
+        maskUrl: string;
+        trajectories: Array<{
+            x: number;
+            y: number;
+        }>;
+    }>;
+    multiShot?: MultiShot;
+    /** Google Veo / Imagen — `allow_all` (text only) / `allow_adult` / `dont_allow`. */
+    personGeneration?: "allow_all" | "allow_adult" | "dont_allow";
+    /** Runway content moderation. */
+    publicFigureThreshold?: "auto" | "low";
+    callbackUrl?: string;
+    /** Provider-side idempotency / dedupe key (Kling `external_task_id`, ByteDance `end_user_id`). */
+    externalTaskId?: string;
+    endUserId?: string;
+    /**
+     * Prior provider-internal task id, used by extend endpoints (Kling, Pixverse)
+     * which take their own task id rather than an arbitrary URL. Pair with
+     * `endpoint: "extend"`.
+     */
+    sourceTaskId?: string;
 }
 export interface VideoGenerationResult {
     status: EVideoSceneStatus.TRIGGERED;
@@ -41,17 +117,198 @@ export interface TextGenerationParams {
 export interface TextGenerationResult {
     text: string;
 }
+/**
+ * Stock asset search (Pexels, Pixabay, Storyblocks).
+ * Returns ranked candidates rather than a single asset; the agent picks
+ * which one to use based on duration / aspect / visual fit.
+ */
+export interface StockSearchParams {
+    query: string;
+    /** "video" | "image" | "music". */
+    kind: "video" | "image" | "music";
+    aspectRatio?: string;
+    /** Min duration in seconds (videos / music). */
+    minDurationSec?: number;
+    /** Max duration in seconds (videos / music). */
+    maxDurationSec?: number;
+    /** Page size. Provider-specific cap. */
+    perPage?: number;
+    /** Result page (1-based). Pexels uses this for pagination. */
+    page?: number;
+    /** Pexels: "large"|"medium"|"small" — minimum size bucket. */
+    size?: "large" | "medium" | "small";
+    /** Pexels images: dominant colour filter. */
+    color?: string;
+    /** Pexels: BCP-47 locale (e.g. "en-US", "ja-JP"). */
+    locale?: string;
+    /** Pexels videos: server-side min width/height. */
+    minWidth?: number;
+    minHeight?: number;
+}
+export interface StockAsset {
+    id: string;
+    url: string;
+    thumbnailUrl?: string;
+    width?: number;
+    height?: number;
+    durationSec?: number;
+    source: string;
+    attribution?: {
+        name: string;
+        url?: string;
+    };
+    /**
+     * Provider-specific "use" / download-tracking endpoint that MUST be hit
+     * once the asset is actually used in a render. Unsplash requires this per
+     * their API guidelines; ignored by providers that don't need it.
+     */
+    trackingUrl?: string;
+}
+export interface StockSearchResult {
+    assets: StockAsset[];
+    /** Total results available, if provider reports it. */
+    totalAvailable?: number;
+}
+/**
+ * Image generation (text-to-image, image-to-image, instruction edit).
+ * Used by T1 (image+motion) and T2 (image-to-video) tier strategies, and
+ * exposed as a first-class user feature via `/v1/image/generate` (provider-expansion branch).
+ */
+export interface ImageGenerationParams {
+    prompt: string;
+    modelKey: EImageGenModelKey | string;
+    aspectRatio?: string;
+    dimensions?: string;
+    /** Single-image input (legacy; prefer `inputImageUrls` for new code). */
+    inputImageUrl?: string;
+    /**
+     * Multi-image references. Per-provider caps:
+     *   OpenAI edits ≤16, Seedream edit ≤10, Nano Banana ≤14 (Banana 2/Pro),
+     *   Qwen edit 1–3, MiniMax subject_reference 1.
+     */
+    inputImageUrls?: string[];
+    /** Pixel mask for OpenAI edits — PNG with alpha; transparent area = edit region. */
+    maskImageUrl?: string;
+    negativePrompt?: string;
+    seed?: number;
+    /** Number of images to generate (n / sampleCount / numberOfImages). */
+    numImages?: number;
+    /** OpenAI gpt-image quality tier. */
+    quality?: "low" | "medium" | "high" | "auto";
+    /** OpenAI gpt-image background — `transparent` not on gpt-image-2. */
+    background?: "opaque" | "transparent" | "auto";
+    outputFormat?: "png" | "jpeg" | "webp";
+    /** 0–100, jpeg/webp only. */
+    outputCompression?: number;
+    /** Google. */
+    personGeneration?: "allow_all" | "allow_adult" | "dont_allow";
+    /** MiniMax / Alibaba prompt-rewrite toggle. */
+    promptOptimizer?: boolean;
+    /** Wan / Qwen — disable native watermark. */
+    watermark?: boolean;
+    /** Seedream / Nano Banana — `auto_2K` | `2K` | `4K` | `1K` | `512px`. */
+    imageSize?: string;
+    responseFormat?: "url" | "base64";
+    safetyChecker?: boolean;
+    /** Idempotency key — provider returns same image for same key. */
+    idempotencyKey?: string;
+}
+export interface ImageGenerationResult {
+    /** First (or only) image. Convenience field; check `imageUrls` for multi-output. */
+    imageUrl: string;
+    /** All generated images when `numImages > 1`. */
+    imageUrls?: string[];
+    width?: number;
+    height?: number;
+    /** Seed actually used (echoed back when provider generated one). */
+    seed?: number;
+    /** Provider-side request id for tracing. */
+    providerRequestId?: string;
+}
+/**
+ * Music generation (text-to-music with optional lyrics + style reference).
+ * Sync — providers return audio in a single API roundtrip (no polling).
+ * Used at /v1/music/generate.
+ */
+export interface MusicGenerationParams {
+    modelKey: EMusicGenModels;
+    /** Style / mood description (e.g. "uplifting cinematic orchestral"). */
+    prompt: string;
+    /** Lyrics with optional [verse]/[chorus] structure tags. */
+    lyrics?: string;
+    /** Style reference audio URL (provider must support it). */
+    referenceAudioUrl?: string;
+    /** Audio length in seconds (provider-clamped). */
+    duration?: number;
+    /** Output filename used when uploading to Storage (no extension). */
+    outputFilename: string;
+    /** Sample rate hint (Hz). MiniMax accepts 16000/24000/32000/44100. */
+    sampleRate?: number;
+    /** Bitrate hint (bps). MiniMax accepts 32000/64000/128000/256000. */
+    bitrate?: number;
+}
+export interface MusicGenerationResult {
+    /** Public Storage URL of the generated audio. */
+    audioUrl: string;
+    /** Audio length in seconds (when reported by provider). */
+    durationSec?: number;
+    /** Provider-side request id for tracing. */
+    providerRequestId?: string;
+    mimeType: string;
+    extension: string;
+}
+/**
+ * Sound-effects generation (text-to-sfx). Sync — providers return audio in
+ * a single API roundtrip. Used at /v1/sfx/generate.
+ */
+export interface SfxGenerationParams {
+    modelKey: ESfxGenModels;
+    /** Description of the desired sound (e.g. "thunder rumble", "glass shatter"). */
+    prompt: string;
+    /** Output filename used when uploading to Storage (no extension). */
+    outputFilename: string;
+    /** Audio length in seconds (provider-clamped; ElevenLabs allows 0.5–22). */
+    durationSec?: number;
+    /** ElevenLabs prompt-influence 0–1 (higher = more literal interpretation). */
+    promptInfluence?: number;
+    /** ElevenLabs loop flag for seamless looping (default false). */
+    loop?: boolean;
+}
+export interface SfxGenerationResult {
+    /** Public Storage URL of the generated audio. */
+    audioUrl: string;
+    /** Audio length in seconds (when reported by provider). */
+    durationSec?: number;
+    /** Provider-side request id for tracing. */
+    providerRequestId?: string;
+    mimeType: string;
+    extension: string;
+}
 export interface CreditUsageParams {
-    modelKey: EVideoGenModels | ETextGenModels;
+    modelKey: EVideoGenModels | ETextGenModels | EImageGenModelKey | EMusicGenModels | ESfxGenModels;
     mode?: EVideoMode;
     duration?: number;
     resolution?: string;
     dimensions?: string;
     aspectRatio?: string;
     inputType?: "text" | "image" | "video";
-    hasInputVideo?: boolean;
     outputType?: "text" | "image" | "video";
     audio?: boolean;
     multiClip?: boolean;
+    /** Image-gen — number of images requested. */
+    numImages?: number;
+    /** Image-gen — quality tier (gpt-image scales price 4×–15×). */
+    quality?: string;
+    /** Bytedance Seedance 2.0 — pricing differs when a video is used as input. */
+    hasInputVideo?: boolean;
+    /**
+     * Bytedance Seedance 2.0 / 2.0-fast — duration (seconds) of the input clip
+     * for ref-to-video / video-to-video calls. ByteDance bills tokens on
+     * (input_duration + output_duration), so this MUST be supplied for V2V/R2V
+     * or the call under-bills proportional to input length.
+     */
+    inputVideoDurationSec?: number;
+    /** Image-gen — output resolution tier (e.g. Google nano-banana-pro "1K"/"2K"/"4K"). */
+    imageSize?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/services/aiGen/providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/aiGen/providers/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACd,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,eAAe,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;IAE7D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,iBAAiB,CAAC,SAAS,CAAC;IACpC,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CAEvB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,eAAe,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CAMzB;AAED,MAAM,WAAW,oBAAoB;IAEnC,KAAK,EAAE,GAAG,CAAC;IACX,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAAC;IAC3C,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACvC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/aiGen/providers/types.ts"],"names":[],"mappings":"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"}

package/lib/services/aiGen/providers/unsplash/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./unsplash.service";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/aiGen/providers/unsplash/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/unsplash/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/lib/services/aiGen/providers/unsplash/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./unsplash.service"), exports);

package/lib/services/aiGen/providers/unsplash/unsplash.service.d.ts

@@ -0,0 +1,16 @@
+import { BaseAiGenProviderService } from "../baseAiGenProvider.service";
+import { CreditUsageParams, StockSearchParams, StockSearchResult } from "../types";
+export declare class UnsplashProviderService extends BaseAiGenProviderService {
+    private readonly accessKey;
+    searchStock(params: StockSearchParams): Promise<StockSearchResult>;
+    /**
+     * Fire the Unsplash download-tracking endpoint. MUST be called once when
+     * an Unsplash photo is committed to a render (per their API guidelines).
+     * Errors swallowed — failure to ping doesn't break the user's render.
+     */
+    pingDownload(trackingUrl: string): Promise<void>;
+    /** Free assets — registers as 0 credits regardless of model. */
+    getCreditUsed(_params: CreditUsageParams): number;
+    private aspectToOrientation;
+}
+//# sourceMappingURL=unsplash.service.d.ts.map

package/lib/services/aiGen/providers/unsplash/unsplash.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsplash.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/unsplash/unsplash.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AA0DlB,qBAAa,uBAAwB,SAAQ,wBAAwB;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuD;IAE3E,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA+DxE;;;;OAIG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD,gEAAgE;IAChE,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM;IAIjD,OAAO,CAAC,mBAAmB;CAQ5B"}

package/lib/services/aiGen/providers/unsplash/unsplash.service.js

@@ -0,0 +1,131 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsplashProviderService = void 0;
+const axios_1 = __importDefault(require("axios"));
+const apiUsageCounter_service_1 = require("../../../apiUsageCounter.service");
+const baseAiGenProvider_service_1 = require("../baseAiGenProvider.service");
+/**
+ * Unsplash image-search provider (T0 — free).
+ *
+ * Photos-only. Pairs with Pexels for image queries; we race both and merge
+ * results so the agent picks from a wider catalog. Video and music queries
+ * delegate to other providers.
+ *
+ * Auth: `Authorization: Client-ID {access_key}` header (no OAuth needed for
+ * read endpoints). Free dev tier: 50 req/h; 1000 req/h after production
+ * approval (see https://unsplash.com/documentation#rate-limiting).
+ *
+ * Attribution: Unsplash guidelines require attributing the photographer and
+ * Unsplash (e.g. "Photo by {name} on Unsplash") wherever the photo appears.
+ * We surface `attribution.{name,url}` so the producer UI / finished video
+ * watermark can render the credit.
+ *
+ * Download tracking: when an Unsplash photo is actually used in a render,
+ * the API requires a fire-and-forget GET to `links.download_location`. We
+ * pass that through as `StockAsset.trackingUrl`; callers fire it via
+ * `pingDownload()` at scene-commit time.
+ */
+const UNSPLASH_SEARCH_URL = "https://api.unsplash.com/search/photos";
+// 10s per-call cap so the agent executor stays responsive when Unsplash is
+// slow — the search_stock cascade can drop us cleanly.
+const UNSPLASH_TIMEOUT_MS = 10000;
+// Cap below 1000 req/h × 24h × 30d = ~720k theoretical max; the realistic
+// cap is the per-hour throttle. We set a conservative monthly upper bound
+// to surface runaway usage early. Override via env if needed.
+const UNSPLASH_MONTHLY_CAP = Number(process.env.UNSPLASH_MONTHLY_CAP ?? 50000);
+class UnsplashProviderService extends baseAiGenProvider_service_1.BaseAiGenProviderService {
+    constructor() {
+        super(...arguments);
+        this.accessKey = process.env.UNSPLASH_ACCESS_KEY;
+    }
+    async searchStock(params) {
+        if (!this.accessKey) {
+            throw new Error("UNSPLASH_ACCESS_KEY not set — unsplash provider cannot search");
+        }
+        if (params.kind !== "image") {
+            // Photos-only. Caller falls back to the appropriate provider.
+            return { assets: [] };
+        }
+        const allowed = await apiUsageCounter_service_1.ApiUsageCounterService.tryConsume({
+            provider: "unsplash",
+            monthlyCap: UNSPLASH_MONTHLY_CAP,
+        });
+        if (!allowed) {
+            throw new Error(`UNSPLASH_RATE_LIMITED: monthly cap of ${UNSPLASH_MONTHLY_CAP} exceeded — back off`);
+        }
+        const perPage = Math.min(params.perPage ?? 15, 30); // Unsplash caps at 30
+        try {
+            const { data } = await axios_1.default.get(UNSPLASH_SEARCH_URL, {
+                headers: { Authorization: `Client-ID ${this.accessKey}` },
+                timeout: UNSPLASH_TIMEOUT_MS,
+                params: {
+                    query: params.query,
+                    per_page: perPage,
+                    page: params.page ?? 1,
+                    orientation: this.aspectToOrientation(params.aspectRatio),
+                    color: params.color, // black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue
+                },
+            });
+            return {
+                assets: data.results.map((p) => ({
+                    id: `unsplash-${p.id}`,
+                    url: p.urls.regular,
+                    thumbnailUrl: p.urls.small,
+                    width: p.width,
+                    height: p.height,
+                    source: "unsplash",
+                    attribution: {
+                        name: p.user.name,
+                        url: p.user.links?.html,
+                    },
+                    trackingUrl: p.links.download_location,
+                })),
+                totalAvailable: data.total,
+            };
+        }
+        catch (err) {
+            if (err?.response?.status === 429) {
+                throw new Error("UNSPLASH_RATE_LIMITED: 429 from Unsplash API — back off");
+            }
+            if (err?.code === "ECONNABORTED" || /timeout/i.test(err?.message ?? "")) {
+                throw new Error(`UNSPLASH_TIMEOUT: request timed out after ${UNSPLASH_TIMEOUT_MS}ms`);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Fire the Unsplash download-tracking endpoint. MUST be called once when
+     * an Unsplash photo is committed to a render (per their API guidelines).
+     * Errors swallowed — failure to ping doesn't break the user's render.
+     */
+    async pingDownload(trackingUrl) {
+        if (!this.accessKey || !trackingUrl)
+            return;
+        try {
+            await axios_1.default.get(trackingUrl, {
+                headers: { Authorization: `Client-ID ${this.accessKey}` },
+                timeout: 5000,
+            });
+        }
+        catch {
+            // Intentional — ToS-required best-effort signal, not a hard dependency.
+        }
+    }
+    /** Free assets — registers as 0 credits regardless of model. */
+    getCreditUsed(_params) {
+        return 0;
+    }
+    aspectToOrientation(aspect) {
+        if (!aspect)
+            return undefined;
+        if (aspect === "9:16" || aspect === "4:5")
+            return "portrait";
+        if (aspect === "1:1")
+            return "squarish";
+        return "landscape";
+    }
+}
+exports.UnsplashProviderService = UnsplashProviderService;

package/lib/services/analytics.service.js

@@ -118,9 +118,7 @@ exports.AnalyticsService = AnalyticsService;
  * map key under `failuresByCode`. Empty/undefined collapses to `unknown`.
  */
 function sanitizeCodeKey(code) {
-    if (code == null || code === "")
+    if (!code)
         return "unknown";
-    // Defensive: providers occasionally return numeric codes (e.g. Google's
-    // gRPC status codes). Coerce to string before regex-replacing.
-    return String(code).replace(/[.\/~*[\]]/g, "_");
+    return code.replace(/[.\/~*[\]]/g, "_");
 }

package/lib/services/apiUsageCounter.service.d.ts

@@ -0,0 +1,20 @@
+export interface ConsumeOptions {
+    /** Provider key, e.g. "pexels" or "jamendo". One doc per provider per month. */
+    provider: string;
+    /** Hard monthly cap. Below this the call is allowed. */
+    monthlyCap: number;
+    /** Optional: how many calls this consumes. Defaults to 1. */
+    count?: number;
+}
+export declare class ApiUsageCounterService {
+    /**
+     * Atomically increments the monthly counter for `provider` and returns
+     * whether the call is allowed (i.e. the *new* total is ≤ monthlyCap).
+     *
+     * Fails open on Firestore error — the call goes through and we log.
+     */
+    static tryConsume(opts: ConsumeOptions): Promise<boolean>;
+    /** Read-only — used by ops dashboards / soft-cap warnings. */
+    static getUsed(provider: string): Promise<number>;
+}
+//# sourceMappingURL=apiUsageCounter.service.d.ts.map

package/lib/services/apiUsageCounter.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiUsageCounter.service.d.ts","sourceRoot":"","sources":["../../src/services/apiUsageCounter.service.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,sBAAsB;IACjC;;;;;OAKG;WACU,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAiC/D,8DAA8D;WACjD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAexD"}

package/lib/services/apiUsageCounter.service.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiUsageCounterService = void 0;
+const firebase_1 = require("../libs/firebase");
+const logger_1 = require("../utils/logger");
+/**
+ * Cheap monthly-call counter for free-tier external APIs (Pexels, Jamendo,
+ * Mubert, etc.). Lives at `apiUsage/{provider}-{YYYY-MM}` — one doc per
+ * provider per month — so a single transactional increment per call is the
+ * hottest write the system needs. Reset cost is zero (new month = new doc).
+ *
+ * `tryConsume()` is fail-open: any Firestore error returns `true` so a
+ * transient outage doesn't take down provider calls. Wrong direction on
+ * over-spend is preferable to false outages on these free tiers.
+ *
+ * Wired into providers right before their external HTTP call. The provider
+ * is responsible for throwing a `*_RATE_LIMITED` error so upstream can swap
+ * to a fallback provider.
+ */
+const COLLECTION = "apiUsage";
+function currentMonthKey() {
+    const d = new Date();
+    const y = d.getUTCFullYear();
+    const m = String(d.getUTCMonth() + 1).padStart(2, "0");
+    return `${y}-${m}`;
+}
+function docId(provider) {
+    return `${provider}-${currentMonthKey()}`;
+}
+class ApiUsageCounterService {
+    /**
+     * Atomically increments the monthly counter for `provider` and returns
+     * whether the call is allowed (i.e. the *new* total is ≤ monthlyCap).
+     *
+     * Fails open on Firestore error — the call goes through and we log.
+     */
+    static async tryConsume(opts) {
+        const ref = firebase_1.firestore.collection(COLLECTION).doc(docId(opts.provider));
+        const count = opts.count ?? 1;
+        try {
+            const allowed = await firebase_1.firestore.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                const used = (snap.data()?.used ?? 0) + count;
+                if (used > opts.monthlyCap) {
+                    // Don't write — leave the counter as-is so the next reset is clean.
+                    return false;
+                }
+                tx.set(ref, {
+                    used: firebase_1.FieldValue.increment(count),
+                    cap: opts.monthlyCap,
+                    updatedAt: firebase_1.FieldValue.serverTimestamp(),
+                }, { merge: true });
+                return true;
+            });
+            return allowed;
+        }
+        catch (err) {
+            // Fail open: prefer over-spend to false outages on free tiers.
+            logger_1.logger.error("apiUsageCounter: tryConsume fail-open", {
+                provider: opts.provider,
+                err: err instanceof Error ? err.stack ?? err.message : String(err),
+            });
+            return true;
+        }
+    }
+    /** Read-only — used by ops dashboards / soft-cap warnings. */
+    static async getUsed(provider) {
+        try {
+            const snap = await firebase_1.firestore
+                .collection(COLLECTION)
+                .doc(docId(provider))
+                .get();
+            return snap.data()?.used ?? 0;
+        }
+        catch (err) {
+            logger_1.logger.error("apiUsageCounter: getUsed failed", {
+                provider,
+                err: err instanceof Error ? err.stack ?? err.message : String(err),
+            });
+            return 0;
+        }
+    }
+}
+exports.ApiUsageCounterService = ApiUsageCounterService;