@contractspec/example.video-api-showcase 2.1.0

package/src/build-api-video.ts

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// Build API Video -- Construct a VideoProject from contract spec metadata
+// ---------------------------------------------------------------------------
+
+import type { VideoProject } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+import { VIDEO_FORMATS } from '@contractspec/lib.video-gen/design/layouts';
+import { resolveRenderConfig } from '@contractspec/lib.video-gen/renderers/config';
+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';
+
+const DEFAULT_FPS = 30;
+const DEFAULT_DURATION_FRAMES = 450; // 15 seconds
+
+/** 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 function buildApiVideo(
+  spec: ApiSpecDefinition,
+  options?: BuildApiVideoOptions
+): VideoProject {
+  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,
+  };
+}
+
+/**
+ * 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 function buildRenderConfig(
+  outputPath: string,
+  preset: QualityPreset = 'standard'
+): RenderConfig {
+  return resolveRenderConfig({ outputPath }, preset);
+}
+
+/**
+ * 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 function buildApiVideoSuite(
+  specs: ApiSpecDefinition[],
+  options?: BuildApiVideoOptions
+): VideoProject[] {
+  return specs.map((spec) => buildApiVideo(spec, options));
+}

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './video-api-showcase.docblock';

package/src/docs/video-api-showcase.docblock.ts

@@ -0,0 +1,70 @@
+import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts-spec/docs';
+
+const blocks: DocBlock[] = [
+  {
+    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/src/example.ts

@@ -0,0 +1,32 @@
+import { defineExample } from '@contractspec/lib.contracts-spec';
+
+const 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 },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './sample-specs';
+export * from './build-api-video';
+
+export { default as example } from './example';
+
+import './docs';

package/src/sample-specs.ts

@@ -0,0 +1,129 @@
+// ---------------------------------------------------------------------------
+// Sample Contract Spec Definitions for API Video Generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Spec metadata used to build API overview videos.
+ * Maps directly to ApiOverviewProps.
+ */
+export interface ApiSpecDefinition {
+  /** Contract spec name (e.g., "CreateUser") */
+  specName: string;
+  /** HTTP method */
+  method: string;
+  /** Endpoint path */
+  endpoint: string;
+  /** Contract spec code snippet */
+  specCode: string;
+  /** Generated output surfaces */
+  generatedOutputs: string[];
+}
+
+/**
+ * CreateUser -- user registration endpoint.
+ */
+export const createUserSpec: ApiSpecDefinition = {
+  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',
+  ],
+};
+
+/**
+ * ListTransactions -- financial transaction listing.
+ */
+export const listTransactionsSpec: ApiSpecDefinition = {
+  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',
+  ],
+};
+
+/**
+ * SendNotification -- push notification dispatch.
+ */
+export const sendNotificationSpec: ApiSpecDefinition = {
+  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',
+  ],
+};

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"
+  }
+}

package/tsdown.config.js

@@ -0,0 +1,3 @@
+import { moduleLibrary } from '@contractspec/tool.bun';
+
+export default { ...moduleLibrary };