@contractspec/example.voice-providers 1.57.0

package/dist/run.js

@@ -0,0 +1,118 @@
+import { listVoices } from "./handlers/list-voices.js";
+import { synthesizeVoice } from "./handlers/synthesize.js";
+
+//#region src/run.ts
+async function runVoiceProvidersExampleFromEnv() {
+	const integrationKey = resolveIntegrationKey();
+	const mode = resolveMode();
+	const dryRun = process.env.CONTRACTSPEC_VOICE_DRY_RUN === "true";
+	const config = resolveConfig(integrationKey);
+	const text = process.env.CONTRACTSPEC_VOICE_TEXT ?? "Hello from ContractSpec voice providers example.";
+	const voiceId = process.env.CONTRACTSPEC_VOICE_ID;
+	if (dryRun) return {
+		integrationKey,
+		mode,
+		dryRun,
+		text,
+		voiceId,
+		config
+	};
+	const input = {
+		integrationKey,
+		secrets: { apiKey: resolveApiKey(integrationKey) },
+		config
+	};
+	const output = {
+		integrationKey,
+		mode,
+		dryRun
+	};
+	if (mode === "list" || mode === "both") output.voices = await listVoices(input);
+	if (mode === "synthesize" || mode === "both") {
+		const result = await synthesizeVoice({
+			...input,
+			synthesis: {
+				text,
+				voiceId
+			}
+		});
+		output.synthesis = {
+			format: result.format,
+			sampleRateHz: result.sampleRateHz,
+			bytes: result.audio.length,
+			url: result.url
+		};
+	}
+	return output;
+}
+function resolveMode() {
+	const raw = (process.env.CONTRACTSPEC_VOICE_MODE ?? "both").toLowerCase();
+	if (raw === "list" || raw === "synthesize" || raw === "both") return raw;
+	throw new Error(`Unsupported CONTRACTSPEC_VOICE_MODE: ${raw}. Use list, synthesize, or both.`);
+}
+function resolveIntegrationKey() {
+	const raw = (process.env.CONTRACTSPEC_VOICE_PROVIDER ?? "gradium").toLowerCase();
+	if (raw === "gradium") return "ai-voice.gradium";
+	if (raw === "fal") return "ai-voice.fal";
+	throw new Error(`Unsupported CONTRACTSPEC_VOICE_PROVIDER: ${raw}. Use gradium or fal.`);
+}
+function resolveApiKey(integrationKey) {
+	const shared = process.env.CONTRACTSPEC_VOICE_API_KEY;
+	if (shared) return shared;
+	const specific = integrationKey === "ai-voice.gradium" ? process.env.GRADIUM_API_KEY : process.env.FAL_KEY;
+	if (!specific) {
+		const envName = integrationKey === "ai-voice.gradium" ? "GRADIUM_API_KEY" : "FAL_KEY";
+		throw new Error(`Missing API key. Set CONTRACTSPEC_VOICE_API_KEY or ${envName}.`);
+	}
+	return specific;
+}
+function resolveConfig(integrationKey) {
+	if (integrationKey === "ai-voice.gradium") return {
+		defaultVoiceId: process.env.GRADIUM_DEFAULT_VOICE_ID,
+		region: process.env.GRADIUM_REGION === "eu" || process.env.GRADIUM_REGION === "us" ? process.env.GRADIUM_REGION : void 0,
+		baseUrl: process.env.GRADIUM_BASE_URL,
+		timeoutMs: parseOptionalInt(process.env.GRADIUM_TIMEOUT_MS),
+		outputFormat: parseGradiumOutputFormat(process.env.GRADIUM_OUTPUT_FORMAT)
+	};
+	return {
+		modelId: process.env.FAL_MODEL_ID,
+		defaultVoiceUrl: process.env.FAL_DEFAULT_VOICE_URL,
+		defaultExaggeration: parseOptionalNumber(process.env.FAL_DEFAULT_EXAGGERATION),
+		defaultTemperature: parseOptionalNumber(process.env.FAL_DEFAULT_TEMPERATURE),
+		defaultCfg: parseOptionalNumber(process.env.FAL_DEFAULT_CFG),
+		pollIntervalMs: parseOptionalInt(process.env.FAL_POLL_INTERVAL_MS)
+	};
+}
+function parseOptionalInt(value) {
+	if (!value) return void 0;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+function parseOptionalNumber(value) {
+	if (!value) return void 0;
+	const parsed = Number.parseFloat(value);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+function parseGradiumOutputFormat(value) {
+	if (!value) return void 0;
+	switch (value) {
+		case "wav":
+		case "pcm":
+		case "opus":
+		case "ulaw_8000":
+		case "alaw_8000":
+		case "pcm_16000":
+		case "pcm_24000": return value;
+		default: return;
+	}
+}
+runVoiceProvidersExampleFromEnv().then((result) => {
+	console.log(JSON.stringify(result, null, 2));
+}).catch((error) => {
+	console.error(error);
+	process.exitCode = 1;
+});
+
+//#endregion
+export { runVoiceProvidersExampleFromEnv };
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","names":[],"sources":["../src/run.ts"],"sourcesContent":["import { listVoices } from './handlers/list-voices';\nimport { synthesizeVoice } from './handlers/synthesize';\nimport type {\n  VoiceIntegrationKey,\n  VoiceProviderConfig,\n  VoiceProviderFactoryInput,\n} from './handlers/create-provider';\n\ntype VoiceMode = 'list' | 'synthesize' | 'both';\n\nexport async function runVoiceProvidersExampleFromEnv() {\n  const integrationKey = resolveIntegrationKey();\n  const mode = resolveMode();\n  const dryRun = process.env.CONTRACTSPEC_VOICE_DRY_RUN === 'true';\n  const config = resolveConfig(integrationKey);\n  const text =\n    process.env.CONTRACTSPEC_VOICE_TEXT ??\n    'Hello from ContractSpec voice providers example.';\n  const voiceId = process.env.CONTRACTSPEC_VOICE_ID;\n\n  if (dryRun) {\n    return {\n      integrationKey,\n      mode,\n      dryRun,\n      text,\n      voiceId,\n      config,\n    };\n  }\n\n  const input: VoiceProviderFactoryInput = {\n    integrationKey,\n    secrets: {\n      apiKey: resolveApiKey(integrationKey),\n    },\n    config,\n  };\n\n  const output: Record<string, unknown> = {\n    integrationKey,\n    mode,\n    dryRun,\n  };\n\n  if (mode === 'list' || mode === 'both') {\n    const voices = await listVoices(input);\n    output.voices = voices;\n  }\n\n  if (mode === 'synthesize' || mode === 'both') {\n    const result = await synthesizeVoice({\n      ...input,\n      synthesis: {\n        text,\n        voiceId,\n      },\n    });\n    output.synthesis = {\n      format: result.format,\n      sampleRateHz: result.sampleRateHz,\n      bytes: result.audio.length,\n      url: result.url,\n    };\n  }\n\n  return output;\n}\n\nfunction resolveMode(): VoiceMode {\n  const raw = (process.env.CONTRACTSPEC_VOICE_MODE ?? 'both').toLowerCase();\n  if (raw === 'list' || raw === 'synthesize' || raw === 'both') {\n    return raw;\n  }\n  throw new Error(\n    `Unsupported CONTRACTSPEC_VOICE_MODE: ${raw}. Use list, synthesize, or both.`\n  );\n}\n\nfunction resolveIntegrationKey(): VoiceIntegrationKey {\n  const raw = (\n    process.env.CONTRACTSPEC_VOICE_PROVIDER ?? 'gradium'\n  ).toLowerCase();\n  if (raw === 'gradium') return 'ai-voice.gradium';\n  if (raw === 'fal') return 'ai-voice.fal';\n  throw new Error(\n    `Unsupported CONTRACTSPEC_VOICE_PROVIDER: ${raw}. Use gradium or fal.`\n  );\n}\n\nfunction resolveApiKey(integrationKey: VoiceIntegrationKey): string {\n  const shared = process.env.CONTRACTSPEC_VOICE_API_KEY;\n  if (shared) return shared;\n\n  const specific =\n    integrationKey === 'ai-voice.gradium'\n      ? process.env.GRADIUM_API_KEY\n      : process.env.FAL_KEY;\n\n  if (!specific) {\n    const envName =\n      integrationKey === 'ai-voice.gradium' ? 'GRADIUM_API_KEY' : 'FAL_KEY';\n    throw new Error(\n      `Missing API key. Set CONTRACTSPEC_VOICE_API_KEY or ${envName}.`\n    );\n  }\n\n  return specific;\n}\n\nfunction resolveConfig(\n  integrationKey: VoiceIntegrationKey\n): VoiceProviderConfig {\n  if (integrationKey === 'ai-voice.gradium') {\n    const config: VoiceProviderConfig = {\n      defaultVoiceId: process.env.GRADIUM_DEFAULT_VOICE_ID,\n      region:\n        process.env.GRADIUM_REGION === 'eu' ||\n        process.env.GRADIUM_REGION === 'us'\n          ? process.env.GRADIUM_REGION\n          : undefined,\n      baseUrl: process.env.GRADIUM_BASE_URL,\n      timeoutMs: parseOptionalInt(process.env.GRADIUM_TIMEOUT_MS),\n      outputFormat: parseGradiumOutputFormat(process.env.GRADIUM_OUTPUT_FORMAT),\n    };\n    return config;\n  }\n\n  return {\n    modelId: process.env.FAL_MODEL_ID,\n    defaultVoiceUrl: process.env.FAL_DEFAULT_VOICE_URL,\n    defaultExaggeration: parseOptionalNumber(\n      process.env.FAL_DEFAULT_EXAGGERATION\n    ),\n    defaultTemperature: parseOptionalNumber(\n      process.env.FAL_DEFAULT_TEMPERATURE\n    ),\n    defaultCfg: parseOptionalNumber(process.env.FAL_DEFAULT_CFG),\n    pollIntervalMs: parseOptionalInt(process.env.FAL_POLL_INTERVAL_MS),\n  };\n}\n\nfunction parseOptionalInt(value: string | undefined): number | undefined {\n  if (!value) return undefined;\n  const parsed = Number.parseInt(value, 10);\n  return Number.isFinite(parsed) ? parsed : undefined;\n}\n\nfunction parseOptionalNumber(value: string | undefined): number | undefined {\n  if (!value) return undefined;\n  const parsed = Number.parseFloat(value);\n  return Number.isFinite(parsed) ? parsed : undefined;\n}\n\nfunction parseGradiumOutputFormat(\n  value: string | undefined\n): VoiceProviderConfig['outputFormat'] {\n  if (!value) return undefined;\n  switch (value) {\n    case 'wav':\n    case 'pcm':\n    case 'opus':\n    case 'ulaw_8000':\n    case 'alaw_8000':\n    case 'pcm_16000':\n    case 'pcm_24000':\n      return value;\n    default:\n      return undefined;\n  }\n}\n\nrunVoiceProvidersExampleFromEnv()\n  .then((result) => {\n    console.log(JSON.stringify(result, null, 2));\n  })\n  .catch((error) => {\n    console.error(error);\n    process.exitCode = 1;\n  });\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@contractspec/example.voice-providers",
+  "version": "1.57.0",
+  "description": "Voice provider example: Gradium and Fal text-to-speech integration patterns.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./connection.sample": "./dist/connection.sample.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/voice-providers.docblock": "./dist/docs/voice-providers.docblock.js",
+    "./example": "./dist/example.js",
+    "./handlers/create-provider": "./dist/handlers/create-provider.js",
+    "./handlers/list-voices": "./dist/handlers/list-voices.js",
+    "./handlers/synthesize": "./dist/handlers/synthesize.js",
+    "./run": "./dist/run.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/integration.providers-impls": "1.57.0",
+    "@contractspec/lib.contracts": "1.57.0"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.57.0",
+    "@contractspec/tool.typescript": "1.57.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/voice-providers.docblock": "./dist/docs/voice-providers.docblock.js",
+      "./example": "./dist/example.js",
+      "./connection.sample": "./dist/connection.sample.js",
+      "./handlers/create-provider": "./dist/handlers/create-provider.js",
+      "./handlers/list-voices": "./dist/handlers/list-voices.js",
+      "./handlers/synthesize": "./dist/handlers/synthesize.js",
+      "./run": "./dist/run.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/voice-providers"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/connection.sample.ts

@@ -0,0 +1,54 @@
+import type { IntegrationConnection } from '@contractspec/lib.contracts/integrations/connection';
+
+export const gradiumVoiceConnection: IntegrationConnection = {
+  meta: {
+    id: 'conn-gradium-voice-demo',
+    tenantId: 'acme-inc',
+    integrationKey: 'ai-voice.gradium',
+    integrationVersion: '1.0.0',
+    label: 'Gradium Voice',
+    environment: 'production',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  },
+  ownershipMode: 'byok',
+  config: {
+    defaultVoiceId: 'YTpq7expH9539ERJ',
+    region: 'eu',
+    outputFormat: 'wav',
+  },
+  secretProvider: 'vault',
+  secretRef: 'vault://integrations/acme-inc/conn-gradium-voice-demo',
+  status: 'connected',
+};
+
+export const falVoiceConnection: IntegrationConnection = {
+  meta: {
+    id: 'conn-fal-voice-demo',
+    tenantId: 'acme-inc',
+    integrationKey: 'ai-voice.fal',
+    integrationVersion: '1.0.0',
+    label: 'Fal Voice',
+    environment: 'production',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  },
+  ownershipMode: 'byok',
+  config: {
+    modelId: 'fal-ai/chatterbox/text-to-speech',
+    defaultVoiceUrl:
+      'https://storage.googleapis.com/chatterbox-demo-samples/prompts/male_rickmorty.mp3',
+    defaultExaggeration: 0.25,
+    defaultTemperature: 0.7,
+    defaultCfg: 0.5,
+    pollIntervalMs: 1000,
+  },
+  secretProvider: 'vault',
+  secretRef: 'vault://integrations/acme-inc/conn-fal-voice-demo',
+  status: 'connected',
+};
+
+export const voiceSampleConnections: IntegrationConnection[] = [
+  gradiumVoiceConnection,
+  falVoiceConnection,
+];

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './voice-providers.docblock';

package/src/docs/voice-providers.docblock.ts

@@ -0,0 +1,48 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const blocks: DocBlock[] = [
+  {
+    id: 'docs.examples.voice-providers',
+    title: 'Voice Providers (example)',
+    summary:
+      'Multi-provider voice integration example covering Gradium and Fal text-to-speech flows.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/voice-providers',
+    tags: ['voice', 'tts', 'gradium', 'fal', 'example'],
+    body:
+      '## What this example shows\n' +
+      '- Provider selection for `ai-voice.gradium` and `ai-voice.fal`.\n' +
+      '- Listing voice catalogs and synthesizing text into audio bytes.\n' +
+      '- Connection metadata patterns for BYOK secret references.\n\n' +
+      '## Secrets and config\n' +
+      '- `apiKey` for each provider.\n' +
+      '- Gradium config: `defaultVoiceId`, `region`, `outputFormat`.\n' +
+      '- Fal config: `modelId`, `defaultVoiceUrl`, synthesis tuning fields.\n\n' +
+      '## Guardrails\n' +
+      '- Keep API keys in secret providers only.\n' +
+      '- Prefer declarative provider config over hardcoded runtime options.\n' +
+      '- Keep synthesis side effects explicit for deterministic workflows.',
+  },
+  {
+    id: 'docs.examples.voice-providers.usage',
+    title: 'Voice Providers - Usage',
+    summary:
+      'How to wire provider factory and synthesis helpers in runtime code.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/voice-providers/usage',
+    tags: ['voice', 'usage'],
+    body:
+      '## Usage\n' +
+      '- Call `createVoiceProvider` with integration key, secrets, and config.\n' +
+      '- Use `listVoices` to expose voice choices in admin/config screens.\n' +
+      '- Use `synthesizeVoice` for message generation or workflow steps.\n\n' +
+      '## Notes\n' +
+      '- Fal uses an audio URL output; this example downloads bytes for a canonical result shape.\n' +
+      '- Gradium maps provider output formats into ContractSpec voice result conventions.',
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,32 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'voice-providers',
+    version: '1.0.0',
+    title: 'Voice Providers (Gradium and Fal)',
+    description:
+      'Multi-provider voice integration example for Gradium and Fal text-to-speech adapters.',
+    kind: 'integration',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.integrations'],
+    tags: ['voice', 'tts', 'gradium', 'fal', 'integrations'],
+  },
+  docs: {
+    rootDocId: 'docs.examples.voice-providers',
+    usageDocId: 'docs.examples.voice-providers.usage',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.voice-providers',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/handlers/create-provider.ts

@@ -0,0 +1,70 @@
+import { FalVoiceProvider } from '@contractspec/integration.providers-impls/impls/fal-voice';
+import { GradiumVoiceProvider } from '@contractspec/integration.providers-impls/impls/gradium-voice';
+import type { VoiceProvider } from '@contractspec/lib.contracts/integrations/providers/voice';
+
+export type VoiceIntegrationKey = 'ai-voice.gradium' | 'ai-voice.fal';
+
+export interface VoiceProviderSecrets {
+  apiKey: string;
+}
+
+export interface VoiceProviderConfig {
+  defaultVoiceId?: string;
+  region?: 'eu' | 'us';
+  baseUrl?: string;
+  timeoutMs?: number;
+  outputFormat?:
+    | 'wav'
+    | 'pcm'
+    | 'opus'
+    | 'ulaw_8000'
+    | 'alaw_8000'
+    | 'pcm_16000'
+    | 'pcm_24000';
+  modelId?: string;
+  defaultVoiceUrl?: string;
+  defaultExaggeration?: number;
+  defaultTemperature?: number;
+  defaultCfg?: number;
+  pollIntervalMs?: number;
+}
+
+export interface VoiceProviderFactoryInput {
+  integrationKey: VoiceIntegrationKey;
+  secrets: VoiceProviderSecrets;
+  config?: VoiceProviderConfig;
+}
+
+export function createVoiceProvider(
+  input: VoiceProviderFactoryInput
+): VoiceProvider {
+  const { integrationKey, secrets, config } = input;
+
+  if (!secrets.apiKey) {
+    throw new Error('Voice provider apiKey is required.');
+  }
+
+  switch (integrationKey) {
+    case 'ai-voice.gradium':
+      return new GradiumVoiceProvider({
+        apiKey: secrets.apiKey,
+        defaultVoiceId: config?.defaultVoiceId,
+        region: config?.region,
+        baseUrl: config?.baseUrl,
+        timeoutMs: config?.timeoutMs,
+        outputFormat: config?.outputFormat,
+      });
+    case 'ai-voice.fal':
+      return new FalVoiceProvider({
+        apiKey: secrets.apiKey,
+        modelId: config?.modelId,
+        defaultVoiceUrl: config?.defaultVoiceUrl,
+        defaultExaggeration: config?.defaultExaggeration,
+        defaultTemperature: config?.defaultTemperature,
+        defaultCfg: config?.defaultCfg,
+        pollIntervalMs: config?.pollIntervalMs,
+      });
+    default:
+      throw new Error(`Unsupported voice provider: ${integrationKey}`);
+  }
+}

package/src/handlers/list-voices.ts

@@ -0,0 +1,13 @@
+import type { Voice } from '@contractspec/lib.contracts/integrations/providers/voice';
+
+import {
+  createVoiceProvider,
+  type VoiceProviderFactoryInput,
+} from './create-provider';
+
+export async function listVoices(
+  input: VoiceProviderFactoryInput
+): Promise<Voice[]> {
+  const provider = createVoiceProvider(input);
+  return provider.listVoices();
+}

package/src/handlers/synthesize.ts

@@ -0,0 +1,20 @@
+import type {
+  VoiceSynthesisInput,
+  VoiceSynthesisResult,
+} from '@contractspec/lib.contracts/integrations/providers/voice';
+
+import {
+  createVoiceProvider,
+  type VoiceProviderFactoryInput,
+} from './create-provider';
+
+export interface SynthesizeVoiceInput extends VoiceProviderFactoryInput {
+  synthesis: VoiceSynthesisInput;
+}
+
+export async function synthesizeVoice(
+  input: SynthesizeVoiceInput
+): Promise<VoiceSynthesisResult> {
+  const provider = createVoiceProvider(input);
+  return provider.synthesize(input.synthesis);
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './handlers/create-provider';
+export * from './handlers/list-voices';
+export * from './handlers/synthesize';
+export * from './connection.sample';
+export { default as example } from './example';
+import './docs';

package/src/run.ts

@@ -0,0 +1,180 @@
+import { listVoices } from './handlers/list-voices';
+import { synthesizeVoice } from './handlers/synthesize';
+import type {
+  VoiceIntegrationKey,
+  VoiceProviderConfig,
+  VoiceProviderFactoryInput,
+} from './handlers/create-provider';
+
+type VoiceMode = 'list' | 'synthesize' | 'both';
+
+export async function runVoiceProvidersExampleFromEnv() {
+  const integrationKey = resolveIntegrationKey();
+  const mode = resolveMode();
+  const dryRun = process.env.CONTRACTSPEC_VOICE_DRY_RUN === 'true';
+  const config = resolveConfig(integrationKey);
+  const text =
+    process.env.CONTRACTSPEC_VOICE_TEXT ??
+    'Hello from ContractSpec voice providers example.';
+  const voiceId = process.env.CONTRACTSPEC_VOICE_ID;
+
+  if (dryRun) {
+    return {
+      integrationKey,
+      mode,
+      dryRun,
+      text,
+      voiceId,
+      config,
+    };
+  }
+
+  const input: VoiceProviderFactoryInput = {
+    integrationKey,
+    secrets: {
+      apiKey: resolveApiKey(integrationKey),
+    },
+    config,
+  };
+
+  const output: Record<string, unknown> = {
+    integrationKey,
+    mode,
+    dryRun,
+  };
+
+  if (mode === 'list' || mode === 'both') {
+    const voices = await listVoices(input);
+    output.voices = voices;
+  }
+
+  if (mode === 'synthesize' || mode === 'both') {
+    const result = await synthesizeVoice({
+      ...input,
+      synthesis: {
+        text,
+        voiceId,
+      },
+    });
+    output.synthesis = {
+      format: result.format,
+      sampleRateHz: result.sampleRateHz,
+      bytes: result.audio.length,
+      url: result.url,
+    };
+  }
+
+  return output;
+}
+
+function resolveMode(): VoiceMode {
+  const raw = (process.env.CONTRACTSPEC_VOICE_MODE ?? 'both').toLowerCase();
+  if (raw === 'list' || raw === 'synthesize' || raw === 'both') {
+    return raw;
+  }
+  throw new Error(
+    `Unsupported CONTRACTSPEC_VOICE_MODE: ${raw}. Use list, synthesize, or both.`
+  );
+}
+
+function resolveIntegrationKey(): VoiceIntegrationKey {
+  const raw = (
+    process.env.CONTRACTSPEC_VOICE_PROVIDER ?? 'gradium'
+  ).toLowerCase();
+  if (raw === 'gradium') return 'ai-voice.gradium';
+  if (raw === 'fal') return 'ai-voice.fal';
+  throw new Error(
+    `Unsupported CONTRACTSPEC_VOICE_PROVIDER: ${raw}. Use gradium or fal.`
+  );
+}
+
+function resolveApiKey(integrationKey: VoiceIntegrationKey): string {
+  const shared = process.env.CONTRACTSPEC_VOICE_API_KEY;
+  if (shared) return shared;
+
+  const specific =
+    integrationKey === 'ai-voice.gradium'
+      ? process.env.GRADIUM_API_KEY
+      : process.env.FAL_KEY;
+
+  if (!specific) {
+    const envName =
+      integrationKey === 'ai-voice.gradium' ? 'GRADIUM_API_KEY' : 'FAL_KEY';
+    throw new Error(
+      `Missing API key. Set CONTRACTSPEC_VOICE_API_KEY or ${envName}.`
+    );
+  }
+
+  return specific;
+}
+
+function resolveConfig(
+  integrationKey: VoiceIntegrationKey
+): VoiceProviderConfig {
+  if (integrationKey === 'ai-voice.gradium') {
+    const config: VoiceProviderConfig = {
+      defaultVoiceId: process.env.GRADIUM_DEFAULT_VOICE_ID,
+      region:
+        process.env.GRADIUM_REGION === 'eu' ||
+        process.env.GRADIUM_REGION === 'us'
+          ? process.env.GRADIUM_REGION
+          : undefined,
+      baseUrl: process.env.GRADIUM_BASE_URL,
+      timeoutMs: parseOptionalInt(process.env.GRADIUM_TIMEOUT_MS),
+      outputFormat: parseGradiumOutputFormat(process.env.GRADIUM_OUTPUT_FORMAT),
+    };
+    return config;
+  }
+
+  return {
+    modelId: process.env.FAL_MODEL_ID,
+    defaultVoiceUrl: process.env.FAL_DEFAULT_VOICE_URL,
+    defaultExaggeration: parseOptionalNumber(
+      process.env.FAL_DEFAULT_EXAGGERATION
+    ),
+    defaultTemperature: parseOptionalNumber(
+      process.env.FAL_DEFAULT_TEMPERATURE
+    ),
+    defaultCfg: parseOptionalNumber(process.env.FAL_DEFAULT_CFG),
+    pollIntervalMs: parseOptionalInt(process.env.FAL_POLL_INTERVAL_MS),
+  };
+}
+
+function parseOptionalInt(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function parseOptionalNumber(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function parseGradiumOutputFormat(
+  value: string | undefined
+): VoiceProviderConfig['outputFormat'] {
+  if (!value) return undefined;
+  switch (value) {
+    case 'wav':
+    case 'pcm':
+    case 'opus':
+    case 'ulaw_8000':
+    case 'alaw_8000':
+    case 'pcm_16000':
+    case 'pcm_24000':
+      return value;
+    default:
+      return undefined;
+  }
+}
+
+runVoiceProvidersExampleFromEnv()
+  .then((result) => {
+    console.log(JSON.stringify(result, null, 2));
+  })
+  .catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}