npm install @reaatech/media-pipeline-mcp-provider-core
# or
pnpm add @reaatech/media-pipeline-mcp-provider-core

import { MediaProvider, defineProvider, type ProviderInput, type ProviderOutput } from "@reaatech/media-pipeline-mcp-provider-core";
 
class MyCustomProvider extends MediaProvider {
  readonly name = "my-custom-provider";
  readonly supportedOperations = ["image.generate", "image.upscale"];
 
  constructor(private apiKey: string) {
    super();
  }
 
  async healthCheck() {
    try {
      const response = await fetch("https://api.example.com/health");
      return { healthy: response.ok, latency: 120 };
    } catch {
      return { healthy: false, error: "Connection refused" };
    }
  }
 
  async estimateCost(input: ProviderInput) {
    return { costUsd: 0.007, currency: "USD", estimatedDurationMs: 2000 };
  }
 
  async execute(input: ProviderInput): Promise<ProviderOutput> {
    const response = await fetch("https://api.example.com/generate", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ prompt: input.params.prompt, width: 1024, height: 1024 }),
    });
 
    const buffer = Buffer.from(await response.arrayBuffer());
 
    return {
      data: buffer,
      mimeType: "image/png",
      metadata: { width: 1024, height: 1024, model: "v2" },
      costUsd: 0.007,
      durationMs: 1500,
    };
  }
}

abstract class MediaProvider {
  abstract readonly name: string;
  abstract readonly supportedOperations: string[];
 
  abstract estimateCost(input: ProviderInput): Promise<CostEstimate>;
  abstract execute(input: ProviderInput): Promise<ProviderOutput>;
 
  // Optional lifecycle
  healthCheck?(): Promise<ProviderHealth>;
 
  // Built-in helpers
  setStorage(storage: ArtifactStore): void;
  executeWithRetry(input: ProviderInput): Promise<ProviderOutput>;
  executeWithCache(input: ProviderInput, cacheConfig?: CacheConfig): Promise<ProviderOutput>;
  generateArtifactId(): string;
  storeArtifact(data: Buffer | ReadableStream, type: ArtifactType, mimeType: string, metadata: Record<string, unknown>, sourceStep?: string): Promise<string>;
 
  // Caching internals
  protected computeCacheKey(input: ProviderInput, cacheConfig?: CacheConfig): string;
  protected defaultCacheConfigForOperation(input: ProviderInput): CacheConfig;
  protected canonicalJson(obj: unknown): string;
  protected isNonRetryableError(error: unknown): boolean;
 
  // Caching configuration
  static cacheConfig: ProviderCacheConfig;
}

function defineProvider<T extends MediaProvider>(
  providerClass: new (...args: unknown[]) => T,
): new (...args: unknown[]) => T;

interface ProviderInput {
  operation: string;
  params: Record<string, unknown>;
  config: Record<string, unknown>;
}

interface ProviderOutput {
  data: Buffer | ReadableStream;
  mimeType: string;
  metadata: Record<string, unknown>;
  costUsd?: number;
  durationMs?: number;
}

interface ProviderHealth {
  healthy: boolean;
  latency?: number;
  error?: string;
}

interface CostEstimate {
  costUsd: number;
  currency: string;
  breakdown?: Array<{ component: string; costUsd: number }>;
  estimatedDurationMs?: number;
}

interface ProviderCacheConfig {
  deterministicParams: string[];       // Only these params drive the cache key
  nonDeterministicParams: string[];   // These params are excluded from the key
  normalize: (inputs: Record<string, unknown>) => Record<string, unknown>;
}

class MyProvider extends MediaProvider {
  async safeExecute(operation: string, input: ProviderInput) {
    return this.executeWithCache(input, {
      mode: "use",
      ttlSeconds: 3600,
    });
  }
}

class MyProvider extends MediaProvider {
  async robustExecute(input: ProviderInput) {
    return this.executeWithRetry(input);
  }
}

class Router {
  constructor(ctx: RouterContext);
  route(config: RouteConfig, inputs: ProviderInput): Promise<{ decision: RouteDecision; output: ProviderOutput }>;
}

interface RouterContext {
  estimateCost(candidate: RouteCandidate, inputs: ProviderInput): Promise<CostEstimate>;
  health(candidate: RouteCandidate): Promise<{ healthy: boolean; latencyMs?: number; queueDepth?: number }>;
  execute(candidate: RouteCandidate, inputs: ProviderInput, signal: AbortSignal): Promise<ProviderOutput>;
  expectedDurationMs?(candidate: RouteCandidate, inputs: ProviderInput): number | undefined;
  queueMs?(candidate: RouteCandidate): Promise<number | undefined>;
}

class RouterNoCandidatesError extends Error {
  readonly code = "ROUTER_NO_CANDIDATES";
}
 
class RouterAllCandidatesFailedError extends Error {
  readonly code = "ROUTER_ALL_CANDIDATES_FAILED";
  readonly rejections: RouteRejection[];
}
 
class RouterFastestIneligibleError extends Error {
  readonly code = "ROUTER_FASTEST_INELIGIBLE";
  readonly ineligibleCandidates: RouteCandidate[];
}

interface WebhookPayload {
  jobId: string;
  status: "completed" | "failed" | "progress";
  output?: unknown;
  pct?: number;
  error?: { code: string; message: string };
}

type MeshFormat = "glb" | "fbx" | "obj" | "usdz" | "ply";
 
interface MeshGenInput {
  prompt?: string;
  sourceArtifactId?: string;
  format: MeshFormat;
  polyBudget?: number;
  topology?: "quads" | "tris";
  texture?: TextureConfig;
  animated?: boolean;
}
 
interface TextureConfig {
  enabled: boolean;
  pbr?: boolean;
  resolution?: 512 | 1024 | 2048 | 4096;
  unwrap?: "auto" | "preserve-source";
}
 
interface MeshOutput {
  artifactId: string;
  format: MeshFormat;
  polyCount: number;
  hasTextures: boolean;
  hasAnimation: boolean;
  bboxMeters?: { x: number; y: number; z: number };
}

interface MediaProviderLike {
  readonly name: string;
  readonly supportedOperations: string[];
  estimateCost(input: ProviderInput): Promise<CostEstimate>;
  execute(input: ProviderInput): Promise<ProviderOutput>;
  healthCheck?(): Promise<ProviderHealth>;
  supportsStreaming?: ReadonlySet<string>;
  supportsWebhooks?: boolean;
  webhookSignatureKey?(): Promise<string>;
  parseWebhookPayload?(headers: Record<string, string>, body: string): Promise<WebhookPayload>;
}

class OpenAIImageProvider extends MediaProvider {
  readonly name = "openai-image";
  readonly supportedOperations = ["image.generate"];
 
  static cacheConfig: ProviderCacheConfig = {
    deterministicParams: ["prompt", "size", "n"],
    nonDeterministicParams: ["seed"],
    normalize: (inputs) => {
      const out: Record<string, unknown> = {};
      for (const [k, v] of Object.entries(inputs)) {
        out[k] = typeof v === "string" ? v.trim().replace(/\s+/g, " ") : v;
      }
      return out;
    },
  };
 
  async estimateCost(input: ProviderInput) {
    return { costUsd: 0.04, currency: "USD" };
  }
 
  async execute(input: ProviderInput): Promise<ProviderOutput> {
    // ... implementation
  }
}

const router = new Router({
  estimateCost: async (candidate, inputs) => {
    return { costUsd: candidate.provider === "stability" ? 0.007 : 0.04, currency: "USD" };
  },
  health: async (candidate) => ({
    healthy: true,
    latencyMs: candidate.model === "sd3" ? 1200 : 2000,
  }),
  execute: async (candidate, inputs, signal) => {
    const provider = getProvider(candidate.provider);
    return provider.execute(inputs);
  },
});
 
const { decision, output } = await router.route(
  {
    strategy: "cheapest-acceptable",
    candidates: [
      { provider: "stability", model: "sd3", maxUsd: 0.05 },
      { provider: "openai", model: "dall-e-3", maxUsd: 0.08 },
    ],
    timeoutMs: 30000,
  },
  { operation: "image.generate", params: { prompt: "sunset" }, config: {} },
);
 
console.log(decision.selected.provider); // "stability"
console.log(decision.reason); // "cheapest-acceptable: lowest cost among healthy candidates"

const { decision, output } = await router.route(
  {
    strategy: "fastest",
    candidates: [
      { provider: "fal", model: "flux-pro-1.1" },
      { provider: "replicate", model: "sdxl" },
    ],
  },
  { operation: "image.generate", params: { prompt: "cat" }, config: {} },
);
// Both candidates are raced; the first to complete wins