@contractspec/example.video-api-showcase 2.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,35 @@
+$ contractspec-bun-build prebuild
+$ bun run prebuild && bun run build:bundle && bun run build:types
+$ contractspec-bun-build prebuild
+$ contractspec-bun-build transpile
+[contractspec-bun-build] transpile target=bun root=src entries=6
+Bundled 6 modules in 17ms
+
+  ./build-api-video.js                 1.31 KB  (entry point)
+  ./index.js                           7.41 KB  (entry point)
+  docs/index.js                        2.94 KB  (entry point)
+  docs/video-api-showcase.docblock.js  2.94 KB  (entry point)
+  ./example.js                         0.98 KB  (entry point)
+  ./sample-specs.js                    2.22 KB  (entry point)
+
+[contractspec-bun-build] transpile target=node root=src entries=6
+Bundled 6 modules in 29ms
+
+  ./build-api-video.js                 1.31 KB  (entry point)
+  ./index.js                           7.40 KB  (entry point)
+  docs/index.js                        2.93 KB  (entry point)
+  docs/video-api-showcase.docblock.js  2.93 KB  (entry point)
+  ./example.js                         0.97 KB  (entry point)
+  ./sample-specs.js                    2.21 KB  (entry point)
+
+[contractspec-bun-build] transpile target=browser root=src entries=6
+Bundled 6 modules in 22ms
+
+  ./build-api-video.js                 1.31 KB  (entry point)
+  ./index.js                           7.40 KB  (entry point)
+  docs/index.js                        2.93 KB  (entry point)
+  docs/video-api-showcase.docblock.js  2.93 KB  (entry point)
+  ./example.js                         0.97 KB  (entry point)
+  ./sample-specs.js                    2.21 KB  (entry point)
+
+$ contractspec-bun-build types

package/.turbo/turbo-prebuild.log

@@ -0,0 +1 @@
+$ contractspec-bun-build prebuild

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @contractspec/example.video-api-showcase
+
+## 2.1.0
+
+### Minor Changes
+
+- ac88935: chore: add examples
+
+### Patch Changes
+
+- Updated dependencies [57e2819]
+  - @contractspec/lib.contracts-spec@2.1.1
+  - @contractspec/lib.contracts-integrations@2.1.1
+  - @contractspec/lib.video-gen@1.42.1

package/dist/browser/build-api-video.js

@@ -0,0 +1,41 @@
+// src/build-api-video.ts
+import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/design/layouts";
+import { resolveRenderConfig } from "@contractspec/lib.video-gen/renderers/config";
+var DEFAULT_FPS = 30;
+var DEFAULT_DURATION_FRAMES = 450;
+function buildApiVideo(spec, options) {
+  const fps = options?.fps ?? DEFAULT_FPS;
+  const durationInFrames = options?.durationInFrames ?? DEFAULT_DURATION_FRAMES;
+  return {
+    id: `api-video-${spec.specName.toLowerCase()}-${Date.now().toString(36)}`,
+    scenes: [
+      {
+        id: "scene-api-overview",
+        compositionId: "ApiOverview",
+        props: {
+          specName: spec.specName,
+          method: spec.method,
+          endpoint: spec.endpoint,
+          specCode: spec.specCode,
+          generatedOutputs: spec.generatedOutputs,
+          tagline: options?.tagline ?? "One spec. Every surface."
+        },
+        durationInFrames
+      }
+    ],
+    totalDurationInFrames: durationInFrames,
+    fps,
+    format: VIDEO_FORMATS.landscape
+  };
+}
+function buildRenderConfig(outputPath, preset = "standard") {
+  return resolveRenderConfig({ outputPath }, preset);
+}
+function buildApiVideoSuite(specs, options) {
+  return specs.map((spec) => buildApiVideo(spec, options));
+}
+export {
+  buildRenderConfig,
+  buildApiVideoSuite,
+  buildApiVideo
+};

package/dist/browser/docs/index.js

@@ -0,0 +1,66 @@
+// src/docs/video-api-showcase.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var blocks = [
+  {
+    id: "docs.examples.video-api-showcase",
+    title: "Video API Showcase (example)",
+    summary: "Spec-driven example: build API overview videos directly from contract spec metadata using manual VideoProject construction.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/video-api-showcase",
+    tags: ["video", "api", "spec-driven", "example"],
+    body: `## What this example shows
+
+- Manually constructing a \`VideoProject\` from contract spec metadata (name, method, endpoint, code, outputs).
+- Using the \`ApiOverview\` composition to visualize how a spec generates multiple API surfaces.
+- Configuring render settings with quality presets (\`draft\`, \`standard\`, \`high\`).
+- Building video scenes with explicit composition IDs and props.
+
+## Key concepts
+
+- **Spec-to-Video**: Contract spec metadata (name, method, endpoint, code snippet) becomes the input props for the \`ApiOverview\` composition.
+- **Manual project construction**: Instead of using \`VideoGenerator\`, this example builds the \`VideoProject\` directly -- useful when you know exactly which composition and props to use.
+- **Render configuration**: Shows how to use \`resolveRenderConfig()\` with quality presets for different output needs.
+
+## Notes
+
+- This approach is ideal when the video structure is known ahead of time (e.g., always an API overview).
+- For dynamic scene planning from content briefs, use \`VideoGenerator\` instead (see the video-marketing-clip example).
+`
+  },
+  {
+    id: "docs.examples.video-api-showcase.usage",
+    title: "Video API Showcase -- Usage",
+    summary: "How to generate API overview videos from contract spec definitions.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/video-api-showcase/usage",
+    tags: ["video", "api", "usage"],
+    body: `## Usage
+
+\`\`\`ts
+import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
+import { createUserSpec, listTransactionsSpec } from "@contractspec/example.video-api-showcase/sample-specs";
+
+// Build a video project for a single API spec
+const project = buildApiVideo(createUserSpec);
+
+console.log(project.scenes[0].compositionId); // "ApiOverview"
+console.log(project.format);                   // { type: "landscape", width: 1920, height: 1080 }
+
+// Build with custom duration and tagline
+const custom = buildApiVideo(listTransactionsSpec, {
+  durationInFrames: 600,
+  tagline: "From spec to production in seconds.",
+});
+\`\`\`
+
+## Guardrails
+
+- The \`specCode\` field should be a concise snippet (10-20 lines) for readability in the video.
+- Generated outputs list should contain 3-8 items for optimal visual layout.
+- Tagline should be short (under 40 characters) to fit within the composition frame.
+`
+  }
+];
+registerDocBlocks(blocks);

package/dist/browser/docs/video-api-showcase.docblock.js

@@ -0,0 +1,66 @@
+// src/docs/video-api-showcase.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var blocks = [
+  {
+    id: "docs.examples.video-api-showcase",
+    title: "Video API Showcase (example)",
+    summary: "Spec-driven example: build API overview videos directly from contract spec metadata using manual VideoProject construction.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/video-api-showcase",
+    tags: ["video", "api", "spec-driven", "example"],
+    body: `## What this example shows
+
+- Manually constructing a \`VideoProject\` from contract spec metadata (name, method, endpoint, code, outputs).
+- Using the \`ApiOverview\` composition to visualize how a spec generates multiple API surfaces.
+- Configuring render settings with quality presets (\`draft\`, \`standard\`, \`high\`).
+- Building video scenes with explicit composition IDs and props.
+
+## Key concepts
+
+- **Spec-to-Video**: Contract spec metadata (name, method, endpoint, code snippet) becomes the input props for the \`ApiOverview\` composition.
+- **Manual project construction**: Instead of using \`VideoGenerator\`, this example builds the \`VideoProject\` directly -- useful when you know exactly which composition and props to use.
+- **Render configuration**: Shows how to use \`resolveRenderConfig()\` with quality presets for different output needs.
+
+## Notes
+
+- This approach is ideal when the video structure is known ahead of time (e.g., always an API overview).
+- For dynamic scene planning from content briefs, use \`VideoGenerator\` instead (see the video-marketing-clip example).
+`
+  },
+  {
+    id: "docs.examples.video-api-showcase.usage",
+    title: "Video API Showcase -- Usage",
+    summary: "How to generate API overview videos from contract spec definitions.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/video-api-showcase/usage",
+    tags: ["video", "api", "usage"],
+    body: `## Usage
+
+\`\`\`ts
+import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
+import { createUserSpec, listTransactionsSpec } from "@contractspec/example.video-api-showcase/sample-specs";
+
+// Build a video project for a single API spec
+const project = buildApiVideo(createUserSpec);
+
+console.log(project.scenes[0].compositionId); // "ApiOverview"
+console.log(project.format);                   // { type: "landscape", width: 1920, height: 1080 }
+
+// Build with custom duration and tagline
+const custom = buildApiVideo(listTransactionsSpec, {
+  durationInFrames: 600,
+  tagline: "From spec to production in seconds.",
+});
+\`\`\`
+
+## Guardrails
+
+- The \`specCode\` field should be a concise snippet (10-20 lines) for readability in the video.
+- Generated outputs list should contain 3-8 items for optimal visual layout.
+- Tagline should be short (under 40 characters) to fit within the composition frame.
+`
+  }
+];
+registerDocBlocks(blocks);

package/dist/browser/example.js

@@ -0,0 +1,33 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts-spec";
+var example = defineExample({
+  meta: {
+    key: "video-api-showcase",
+    version: "1.0.0",
+    title: "Video API Showcase",
+    description: "Generate API documentation videos from contract spec definitions using the ApiOverview composition.",
+    kind: "script",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["video", "api", "documentation", "spec-driven"]
+  },
+  docs: {
+    rootDocId: "docs.examples.video-api-showcase",
+    usageDocId: "docs.examples.video-api-showcase.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.video-api-showcase",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ["markdown"] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/browser/index.js

@@ -0,0 +1,241 @@
+// src/build-api-video.ts
+import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/design/layouts";
+import { resolveRenderConfig } from "@contractspec/lib.video-gen/renderers/config";
+var DEFAULT_FPS = 30;
+var DEFAULT_DURATION_FRAMES = 450;
+function buildApiVideo(spec, options) {
+  const fps = options?.fps ?? DEFAULT_FPS;
+  const durationInFrames = options?.durationInFrames ?? DEFAULT_DURATION_FRAMES;
+  return {
+    id: `api-video-${spec.specName.toLowerCase()}-${Date.now().toString(36)}`,
+    scenes: [
+      {
+        id: "scene-api-overview",
+        compositionId: "ApiOverview",
+        props: {
+          specName: spec.specName,
+          method: spec.method,
+          endpoint: spec.endpoint,
+          specCode: spec.specCode,
+          generatedOutputs: spec.generatedOutputs,
+          tagline: options?.tagline ?? "One spec. Every surface."
+        },
+        durationInFrames
+      }
+    ],
+    totalDurationInFrames: durationInFrames,
+    fps,
+    format: VIDEO_FORMATS.landscape
+  };
+}
+function buildRenderConfig(outputPath, preset = "standard") {
+  return resolveRenderConfig({ outputPath }, preset);
+}
+function buildApiVideoSuite(specs, options) {
+  return specs.map((spec) => buildApiVideo(spec, options));
+}
+
+// src/docs/video-api-showcase.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var blocks = [
+  {
+    id: "docs.examples.video-api-showcase",
+    title: "Video API Showcase (example)",
+    summary: "Spec-driven example: build API overview videos directly from contract spec metadata using manual VideoProject construction.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/video-api-showcase",
+    tags: ["video", "api", "spec-driven", "example"],
+    body: `## What this example shows
+
+- Manually constructing a \`VideoProject\` from contract spec metadata (name, method, endpoint, code, outputs).
+- Using the \`ApiOverview\` composition to visualize how a spec generates multiple API surfaces.
+- Configuring render settings with quality presets (\`draft\`, \`standard\`, \`high\`).
+- Building video scenes with explicit composition IDs and props.
+
+## Key concepts
+
+- **Spec-to-Video**: Contract spec metadata (name, method, endpoint, code snippet) becomes the input props for the \`ApiOverview\` composition.
+- **Manual project construction**: Instead of using \`VideoGenerator\`, this example builds the \`VideoProject\` directly -- useful when you know exactly which composition and props to use.
+- **Render configuration**: Shows how to use \`resolveRenderConfig()\` with quality presets for different output needs.
+
+## Notes
+
+- This approach is ideal when the video structure is known ahead of time (e.g., always an API overview).
+- For dynamic scene planning from content briefs, use \`VideoGenerator\` instead (see the video-marketing-clip example).
+`
+  },
+  {
+    id: "docs.examples.video-api-showcase.usage",
+    title: "Video API Showcase -- Usage",
+    summary: "How to generate API overview videos from contract spec definitions.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/video-api-showcase/usage",
+    tags: ["video", "api", "usage"],
+    body: `## Usage
+
+\`\`\`ts
+import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
+import { createUserSpec, listTransactionsSpec } from "@contractspec/example.video-api-showcase/sample-specs";
+
+// Build a video project for a single API spec
+const project = buildApiVideo(createUserSpec);
+
+console.log(project.scenes[0].compositionId); // "ApiOverview"
+console.log(project.format);                   // { type: "landscape", width: 1920, height: 1080 }
+
+// Build with custom duration and tagline
+const custom = buildApiVideo(listTransactionsSpec, {
+  durationInFrames: 600,
+  tagline: "From spec to production in seconds.",
+});
+\`\`\`
+
+## Guardrails
+
+- The \`specCode\` field should be a concise snippet (10-20 lines) for readability in the video.
+- Generated outputs list should contain 3-8 items for optimal visual layout.
+- Tagline should be short (under 40 characters) to fit within the composition frame.
+`
+  }
+];
+registerDocBlocks(blocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts-spec";
+var example = defineExample({
+  meta: {
+    key: "video-api-showcase",
+    version: "1.0.0",
+    title: "Video API Showcase",
+    description: "Generate API documentation videos from contract spec definitions using the ApiOverview composition.",
+    kind: "script",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["video", "api", "documentation", "spec-driven"]
+  },
+  docs: {
+    rootDocId: "docs.examples.video-api-showcase",
+    usageDocId: "docs.examples.video-api-showcase.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.video-api-showcase",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ["markdown"] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+
+// src/sample-specs.ts
+var createUserSpec = {
+  specName: "CreateUser",
+  method: "POST",
+  endpoint: "/api/users",
+  specCode: `export const createUser = defineCommand({
+  meta: {
+    name: "CreateUser",
+    version: "1.0.0",
+    stability: "Stable",
+  },
+  io: {
+    input: z.object({
+      email: z.string().email(),
+      name: z.string(),
+      role: z.enum(["admin", "user"]),
+    }),
+    output: z.object({
+      id: z.string().uuid(),
+      email: z.string(),
+      createdAt: z.date(),
+    }),
+  },
+});`,
+  generatedOutputs: [
+    "REST Endpoint",
+    "GraphQL Mutation",
+    "Prisma Model",
+    "TypeScript SDK",
+    "MCP Tool",
+    "OpenAPI Spec"
+  ]
+};
+var listTransactionsSpec = {
+  specName: "ListTransactions",
+  method: "GET",
+  endpoint: "/api/transactions",
+  specCode: `export const listTransactions = defineQuery({
+  meta: {
+    name: "ListTransactions",
+    version: "1.0.0",
+    stability: "Stable",
+  },
+  io: {
+    input: z.object({
+      accountId: z.string().uuid(),
+      from: z.date().optional(),
+      to: z.date().optional(),
+      limit: z.number().default(50),
+    }),
+    output: z.object({
+      transactions: z.array(transactionSchema),
+      total: z.number(),
+      hasMore: z.boolean(),
+    }),
+  },
+});`,
+  generatedOutputs: [
+    "REST Endpoint",
+    "GraphQL Query",
+    "Prisma Query",
+    "TypeScript SDK",
+    "OpenAPI Spec"
+  ]
+};
+var sendNotificationSpec = {
+  specName: "SendNotification",
+  method: "POST",
+  endpoint: "/api/notifications",
+  specCode: `export const sendNotification = defineCommand({
+  meta: {
+    name: "SendNotification",
+    version: "1.0.0",
+    stability: "Beta",
+  },
+  io: {
+    input: z.object({
+      userId: z.string().uuid(),
+      channel: z.enum(["push", "email", "sms"]),
+      title: z.string(),
+      body: z.string(),
+    }),
+    output: z.object({
+      notificationId: z.string().uuid(),
+      deliveredAt: z.date().nullable(),
+      status: z.enum(["sent", "failed", "queued"]),
+    }),
+  },
+});`,
+  generatedOutputs: [
+    "REST Endpoint",
+    "GraphQL Mutation",
+    "TypeScript SDK",
+    "MCP Tool",
+    "OpenAPI Spec",
+    "Event Schema"
+  ]
+};
+export {
+  sendNotificationSpec,
+  listTransactionsSpec,
+  example_default as example,
+  createUserSpec,
+  buildRenderConfig,
+  buildApiVideoSuite,
+  buildApiVideo
+};

package/dist/browser/sample-specs.js

@@ -0,0 +1,103 @@
+// src/sample-specs.ts
+var createUserSpec = {
+  specName: "CreateUser",
+  method: "POST",
+  endpoint: "/api/users",
+  specCode: `export const createUser = defineCommand({
+  meta: {
+    name: "CreateUser",
+    version: "1.0.0",
+    stability: "Stable",
+  },
+  io: {
+    input: z.object({
+      email: z.string().email(),
+      name: z.string(),
+      role: z.enum(["admin", "user"]),
+    }),
+    output: z.object({
+      id: z.string().uuid(),
+      email: z.string(),
+      createdAt: z.date(),
+    }),
+  },
+});`,
+  generatedOutputs: [
+    "REST Endpoint",
+    "GraphQL Mutation",
+    "Prisma Model",
+    "TypeScript SDK",
+    "MCP Tool",
+    "OpenAPI Spec"
+  ]
+};
+var listTransactionsSpec = {
+  specName: "ListTransactions",
+  method: "GET",
+  endpoint: "/api/transactions",
+  specCode: `export const listTransactions = defineQuery({
+  meta: {
+    name: "ListTransactions",
+    version: "1.0.0",
+    stability: "Stable",
+  },
+  io: {
+    input: z.object({
+      accountId: z.string().uuid(),
+      from: z.date().optional(),
+      to: z.date().optional(),
+      limit: z.number().default(50),
+    }),
+    output: z.object({
+      transactions: z.array(transactionSchema),
+      total: z.number(),
+      hasMore: z.boolean(),
+    }),
+  },
+});`,
+  generatedOutputs: [
+    "REST Endpoint",
+    "GraphQL Query",
+    "Prisma Query",
+    "TypeScript SDK",
+    "OpenAPI Spec"
+  ]
+};
+var sendNotificationSpec = {
+  specName: "SendNotification",
+  method: "POST",
+  endpoint: "/api/notifications",
+  specCode: `export const sendNotification = defineCommand({
+  meta: {
+    name: "SendNotification",
+    version: "1.0.0",
+    stability: "Beta",
+  },
+  io: {
+    input: z.object({
+      userId: z.string().uuid(),
+      channel: z.enum(["push", "email", "sms"]),
+      title: z.string(),
+      body: z.string(),
+    }),
+    output: z.object({
+      notificationId: z.string().uuid(),
+      deliveredAt: z.date().nullable(),
+      status: z.enum(["sent", "failed", "queued"]),
+    }),
+  },
+});`,
+  generatedOutputs: [
+    "REST Endpoint",
+    "GraphQL Mutation",
+    "TypeScript SDK",
+    "MCP Tool",
+    "OpenAPI Spec",
+    "Event Schema"
+  ]
+};
+export {
+  sendNotificationSpec,
+  listTransactionsSpec,
+  createUserSpec
+};

package/dist/build-api-video.d.ts

@@ -0,0 +1,53 @@
+import type { VideoProject } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+import type { QualityPreset } from '@contractspec/lib.video-gen/renderers/config';
+import type { RenderConfig } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+import type { ApiSpecDefinition } from './sample-specs';
+/** Options for building an API showcase video. */
+export interface BuildApiVideoOptions {
+    /** Duration in frames. Default: 450 (15s at 30fps). */
+    durationInFrames?: number;
+    /** Tagline shown at the end. */
+    tagline?: string;
+    /** FPS. Default: 30. */
+    fps?: number;
+}
+/**
+ * Build a VideoProject from a contract spec definition.
+ *
+ * This demonstrates manual project construction using the ApiOverview
+ * composition -- useful when you know the exact video structure.
+ *
+ * @example
+ * ```ts
+ * import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
+ * import { createUserSpec } from "@contractspec/example.video-api-showcase/sample-specs";
+ *
+ * const project = buildApiVideo(createUserSpec);
+ * // project.scenes[0].compositionId === "ApiOverview"
+ * ```
+ */
+export declare function buildApiVideo(spec: ApiSpecDefinition, options?: BuildApiVideoOptions): VideoProject;
+/**
+ * Build a render configuration for the API video.
+ *
+ * Demonstrates using quality presets to configure rendering.
+ *
+ * @example
+ * ```ts
+ * const config = buildRenderConfig("out/api-overview.mp4", "high");
+ * // config.crf === 12, config.codec === "h264"
+ * ```
+ */
+export declare function buildRenderConfig(outputPath: string, preset?: QualityPreset): RenderConfig;
+/**
+ * Build video projects for multiple specs at once.
+ *
+ * @example
+ * ```ts
+ * import { createUserSpec, listTransactionsSpec } from "./sample-specs";
+ *
+ * const projects = buildApiVideoSuite([createUserSpec, listTransactionsSpec]);
+ * // projects.length === 2
+ * ```
+ */
+export declare function buildApiVideoSuite(specs: ApiSpecDefinition[], options?: BuildApiVideoOptions): VideoProject[];