@contractspec/example.voice-providers 1.57.0 → 1.59.0

package/dist/handlers/create-provider.js

@@ -1,32 +1,36 @@
+// @bun
+// src/handlers/create-provider.ts
 import { FalVoiceProvider } from "@contractspec/integration.providers-impls/impls/fal-voice";
 import { GradiumVoiceProvider } from "@contractspec/integration.providers-impls/impls/gradium-voice";
-
-//#region src/handlers/create-provider.ts
 function createVoiceProvider(input) {
-	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}`);
-	}
+  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}`);
+  }
 }
-
-//#endregion
-export { createVoiceProvider };
-//# sourceMappingURL=create-provider.js.map
+export {
+  createVoiceProvider
+};

package/dist/handlers/list-voices.d.ts

@@ -1,8 +1,4 @@
-import { VoiceProviderFactoryInput } from "./create-provider.js";
-import { Voice } from "@contractspec/lib.contracts/integrations/providers/voice";
-
-//#region src/handlers/list-voices.d.ts
-declare function listVoices(input: VoiceProviderFactoryInput): Promise<Voice[]>;
-//#endregion
-export { listVoices };
+import type { Voice } from '@contractspec/lib.contracts/integrations/providers/voice';
+import { type VoiceProviderFactoryInput } from './create-provider';
+export declare function listVoices(input: VoiceProviderFactoryInput): Promise<Voice[]>;
 //# sourceMappingURL=list-voices.d.ts.map

package/dist/handlers/list-voices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-voices.d.ts","names":[],"sources":["../../src/handlers/list-voices.ts"],"mappings":";;;;iBAOsB,UAAA,CACpB,KAAA,EAAO,yBAAA,GACN,OAAA,CAAQ,KAAA"}
+{"version":3,"file":"list-voices.d.ts","sourceRoot":"","sources":["../../src/handlers/list-voices.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0DAA0D,CAAC;AAEtF,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,UAAU,CAC9B,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,KAAK,EAAE,CAAC,CAGlB"}

package/dist/handlers/list-voices.js

@@ -1,10 +1,42 @@
-import { createVoiceProvider } from "./create-provider.js";
+// @bun
+// src/handlers/create-provider.ts
+import { FalVoiceProvider } from "@contractspec/integration.providers-impls/impls/fal-voice";
+import { GradiumVoiceProvider } from "@contractspec/integration.providers-impls/impls/gradium-voice";
+function createVoiceProvider(input) {
+  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}`);
+  }
+}
 
-//#region src/handlers/list-voices.ts
+// src/handlers/list-voices.ts
 async function listVoices(input) {
-	return createVoiceProvider(input).listVoices();
+  const provider = createVoiceProvider(input);
+  return provider.listVoices();
 }
-
-//#endregion
-export { listVoices };
-//# sourceMappingURL=list-voices.js.map
+export {
+  listVoices
+};

package/dist/handlers/synthesize.d.ts

@@ -1,11 +1,7 @@
-import { VoiceProviderFactoryInput } from "./create-provider.js";
-import { VoiceSynthesisInput, VoiceSynthesisResult } from "@contractspec/lib.contracts/integrations/providers/voice";
-
-//#region src/handlers/synthesize.d.ts
-interface SynthesizeVoiceInput extends VoiceProviderFactoryInput {
-  synthesis: VoiceSynthesisInput;
+import type { VoiceSynthesisInput, VoiceSynthesisResult } from '@contractspec/lib.contracts/integrations/providers/voice';
+import { type VoiceProviderFactoryInput } from './create-provider';
+export interface SynthesizeVoiceInput extends VoiceProviderFactoryInput {
+    synthesis: VoiceSynthesisInput;
 }
-declare function synthesizeVoice(input: SynthesizeVoiceInput): Promise<VoiceSynthesisResult>;
-//#endregion
-export { SynthesizeVoiceInput, synthesizeVoice };
+export declare function synthesizeVoice(input: SynthesizeVoiceInput): Promise<VoiceSynthesisResult>;
 //# sourceMappingURL=synthesize.d.ts.map

package/dist/handlers/synthesize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"synthesize.d.ts","names":[],"sources":["../../src/handlers/synthesize.ts"],"mappings":";;;;UAUiB,oBAAA,SAA6B,yBAAA;EAC5C,SAAA,EAAW,mBAAA;AAAA;AAAA,iBAGS,eAAA,CACpB,KAAA,EAAO,oBAAA,GACN,OAAA,CAAQ,oBAAA"}
+{"version":3,"file":"synthesize.d.ts","sourceRoot":"","sources":["../../src/handlers/synthesize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,0DAA0D,CAAC;AAElE,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,oBAAqB,SAAQ,yBAAyB;IACrE,SAAS,EAAE,mBAAmB,CAAC;CAChC;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAG/B"}

package/dist/handlers/synthesize.js

@@ -1,10 +1,42 @@
-import { createVoiceProvider } from "./create-provider.js";
+// @bun
+// src/handlers/create-provider.ts
+import { FalVoiceProvider } from "@contractspec/integration.providers-impls/impls/fal-voice";
+import { GradiumVoiceProvider } from "@contractspec/integration.providers-impls/impls/gradium-voice";
+function createVoiceProvider(input) {
+  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}`);
+  }
+}
 
-//#region src/handlers/synthesize.ts
+// src/handlers/synthesize.ts
 async function synthesizeVoice(input) {
-	return createVoiceProvider(input).synthesize(input.synthesis);
+  const provider = createVoiceProvider(input);
+  return provider.synthesize(input.synthesis);
 }
-
-//#endregion
-export { synthesizeVoice };
-//# sourceMappingURL=synthesize.js.map
+export {
+  synthesizeVoice
+};

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { falVoiceConnection, gradiumVoiceConnection, voiceSampleConnections } from "./connection.sample.js";
-import example from "./example.js";
-import { VoiceIntegrationKey, VoiceProviderConfig, VoiceProviderFactoryInput, VoiceProviderSecrets, createVoiceProvider } from "./handlers/create-provider.js";
-import { listVoices } from "./handlers/list-voices.js";
-import { SynthesizeVoiceInput, synthesizeVoice } from "./handlers/synthesize.js";
-export { SynthesizeVoiceInput, VoiceIntegrationKey, VoiceProviderConfig, VoiceProviderFactoryInput, VoiceProviderSecrets, createVoiceProvider, example, falVoiceConnection, gradiumVoiceConnection, listVoices, synthesizeVoice, voiceSampleConnections };
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,QAAQ,CAAC"}

package/dist/index.js

@@ -1,8 +1,172 @@
-import { falVoiceConnection, gradiumVoiceConnection, voiceSampleConnections } from "./connection.sample.js";
-import example from "./example.js";
-import { createVoiceProvider } from "./handlers/create-provider.js";
-import { listVoices } from "./handlers/list-voices.js";
-import { synthesizeVoice } from "./handlers/synthesize.js";
-import "./docs/index.js";
-
-export { createVoiceProvider, example, falVoiceConnection, gradiumVoiceConnection, listVoices, synthesizeVoice, voiceSampleConnections };
+// @bun
+// src/connection.sample.ts
+var gradiumVoiceConnection = {
+  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"
+};
+var falVoiceConnection = {
+  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"
+};
+var voiceSampleConnections = [
+  gradiumVoiceConnection,
+  falVoiceConnection
+];
+
+// src/docs/voice-providers.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+` + "- Provider selection for `ai-voice.gradium` and `ai-voice.fal`.\n" + `- Listing voice catalogs and synthesizing text into audio bytes.
+` + `- Connection metadata patterns for BYOK secret references.
+
+` + `## Secrets and config
+` + "- `apiKey` for each provider.\n" + "- Gradium config: `defaultVoiceId`, `region`, `outputFormat`.\n" + "- Fal config: `modelId`, `defaultVoiceUrl`, synthesis tuning fields.\n\n" + `## Guardrails
+` + `- Keep API keys in secret providers only.
+` + `- Prefer declarative provider config over hardcoded runtime options.
+` + "- 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
+` + "- 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
+` + `- Fal uses an audio URL output; this example downloads bytes for a canonical result shape.
+` + "- Gradium maps provider output formats into ContractSpec voice result conventions."
+  }
+];
+registerDocBlocks(blocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+
+// src/handlers/create-provider.ts
+import { FalVoiceProvider } from "@contractspec/integration.providers-impls/impls/fal-voice";
+import { GradiumVoiceProvider } from "@contractspec/integration.providers-impls/impls/gradium-voice";
+function createVoiceProvider(input) {
+  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}`);
+  }
+}
+
+// src/handlers/list-voices.ts
+async function listVoices(input) {
+  const provider = createVoiceProvider(input);
+  return provider.listVoices();
+}
+
+// src/handlers/synthesize.ts
+async function synthesizeVoice(input) {
+  const provider = createVoiceProvider(input);
+  return provider.synthesize(input.synthesis);
+}
+export {
+  voiceSampleConnections,
+  synthesizeVoice,
+  listVoices,
+  gradiumVoiceConnection,
+  falVoiceConnection,
+  example_default as example,
+  createVoiceProvider
+};

package/dist/node/connection.sample.js

@@ -0,0 +1,55 @@
+// src/connection.sample.ts
+var gradiumVoiceConnection = {
+  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"
+};
+var falVoiceConnection = {
+  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"
+};
+var voiceSampleConnections = [
+  gradiumVoiceConnection,
+  falVoiceConnection
+];
+export {
+  voiceSampleConnections,
+  gradiumVoiceConnection,
+  falVoiceConnection
+};

package/dist/node/docs/index.js

@@ -0,0 +1,36 @@
+// src/docs/voice-providers.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+` + "- Provider selection for `ai-voice.gradium` and `ai-voice.fal`.\n" + `- Listing voice catalogs and synthesizing text into audio bytes.
+` + `- Connection metadata patterns for BYOK secret references.
+
+` + `## Secrets and config
+` + "- `apiKey` for each provider.\n" + "- Gradium config: `defaultVoiceId`, `region`, `outputFormat`.\n" + "- Fal config: `modelId`, `defaultVoiceUrl`, synthesis tuning fields.\n\n" + `## Guardrails
+` + `- Keep API keys in secret providers only.
+` + `- Prefer declarative provider config over hardcoded runtime options.
+` + "- 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
+` + "- 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
+` + `- Fal uses an audio URL output; this example downloads bytes for a canonical result shape.
+` + "- Gradium maps provider output formats into ContractSpec voice result conventions."
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/docs/voice-providers.docblock.js

@@ -0,0 +1,36 @@
+// src/docs/voice-providers.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+` + "- Provider selection for `ai-voice.gradium` and `ai-voice.fal`.\n" + `- Listing voice catalogs and synthesizing text into audio bytes.
+` + `- Connection metadata patterns for BYOK secret references.
+
+` + `## Secrets and config
+` + "- `apiKey` for each provider.\n" + "- Gradium config: `defaultVoiceId`, `region`, `outputFormat`.\n" + "- Fal config: `modelId`, `defaultVoiceUrl`, synthesis tuning fields.\n\n" + `## Guardrails
+` + `- Keep API keys in secret providers only.
+` + `- Prefer declarative provider config over hardcoded runtime options.
+` + "- 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
+` + "- 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
+` + `- Fal uses an audio URL output; this example downloads bytes for a canonical result shape.
+` + "- Gradium maps provider output formats into ContractSpec voice result conventions."
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/example.js

@@ -0,0 +1,33 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/node/handlers/create-provider.js

@@ -0,0 +1,35 @@
+// src/handlers/create-provider.ts
+import { FalVoiceProvider } from "@contractspec/integration.providers-impls/impls/fal-voice";
+import { GradiumVoiceProvider } from "@contractspec/integration.providers-impls/impls/gradium-voice";
+function createVoiceProvider(input) {
+  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}`);
+  }
+}
+export {
+  createVoiceProvider
+};

package/dist/node/handlers/list-voices.js

@@ -0,0 +1,41 @@
+// src/handlers/create-provider.ts
+import { FalVoiceProvider } from "@contractspec/integration.providers-impls/impls/fal-voice";
+import { GradiumVoiceProvider } from "@contractspec/integration.providers-impls/impls/gradium-voice";
+function createVoiceProvider(input) {
+  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}`);
+  }
+}
+
+// src/handlers/list-voices.ts
+async function listVoices(input) {
+  const provider = createVoiceProvider(input);
+  return provider.listVoices();
+}
+export {
+  listVoices
+};