@contractspec/example.video-api-showcase 2.1.0

package/dist/node/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/node/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/sample-specs.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare const createUserSpec: ApiSpecDefinition;
+/**
+ * ListTransactions -- financial transaction listing.
+ */
+export declare const listTransactionsSpec: ApiSpecDefinition;
+/**
+ * SendNotification -- push notification dispatch.
+ */
+export declare const sendNotificationSpec: ApiSpecDefinition;

package/dist/sample-specs.js

@@ -0,0 +1,104 @@
+// @bun
+// 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/package.json

@@ -0,0 +1,145 @@
+{
+  "name": "@contractspec/example.video-api-showcase",
+  "version": "2.1.0",
+  "description": "Generate API documentation videos from contract spec definitions using the ApiOverview composition.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.js",
+      "node": "./dist/node/index.js",
+      "browser": "./dist/browser/index.js",
+      "default": "./dist/index.js"
+    },
+    "./build-api-video": {
+      "types": "./dist/build-api-video.d.ts",
+      "bun": "./dist/build-api-video.js",
+      "node": "./dist/node/build-api-video.js",
+      "browser": "./dist/browser/build-api-video.js",
+      "default": "./dist/build-api-video.js"
+    },
+    "./docs": {
+      "types": "./dist/docs/index.d.ts",
+      "bun": "./dist/docs/index.js",
+      "node": "./dist/node/docs/index.js",
+      "browser": "./dist/browser/docs/index.js",
+      "default": "./dist/docs/index.js"
+    },
+    "./docs/index": {
+      "types": "./dist/docs/index.d.ts",
+      "bun": "./dist/docs/index.js",
+      "node": "./dist/node/docs/index.js",
+      "browser": "./dist/browser/docs/index.js",
+      "default": "./dist/docs/index.js"
+    },
+    "./docs/video-api-showcase.docblock": {
+      "types": "./dist/docs/video-api-showcase.docblock.d.ts",
+      "bun": "./dist/docs/video-api-showcase.docblock.js",
+      "node": "./dist/node/docs/video-api-showcase.docblock.js",
+      "browser": "./dist/browser/docs/video-api-showcase.docblock.js",
+      "default": "./dist/docs/video-api-showcase.docblock.js"
+    },
+    "./example": {
+      "types": "./dist/example.d.ts",
+      "bun": "./dist/example.js",
+      "node": "./dist/node/example.js",
+      "browser": "./dist/browser/example.js",
+      "default": "./dist/example.js"
+    },
+    "./sample-specs": {
+      "types": "./dist/sample-specs.d.ts",
+      "bun": "./dist/sample-specs.js",
+      "node": "./dist/node/sample-specs.js",
+      "browser": "./dist/browser/sample-specs.js",
+      "default": "./dist/sample-specs.js"
+    }
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun run prebuild && bun run build:bundle && bun run build:types",
+    "build:bundle": "contractspec-bun-build transpile",
+    "build:types": "contractspec-bun-build types",
+    "dev": "contractspec-bun-build dev",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test --pass-with-no-tests",
+    "prebuild": "contractspec-bun-build prebuild",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@contractspec/lib.contracts-spec": "2.1.1",
+    "@contractspec/lib.contracts-integrations": "2.1.1",
+    "@contractspec/lib.video-gen": "1.42.1"
+  },
+  "devDependencies": {
+    "@contractspec/tool.typescript": "2.1.0",
+    "@contractspec/tool.bun": "2.1.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "bun": "./dist/index.js",
+        "node": "./dist/node/index.js",
+        "browser": "./dist/browser/index.js",
+        "default": "./dist/index.js"
+      },
+      "./build-api-video": {
+        "types": "./dist/build-api-video.d.ts",
+        "bun": "./dist/build-api-video.js",
+        "node": "./dist/node/build-api-video.js",
+        "browser": "./dist/browser/build-api-video.js",
+        "default": "./dist/build-api-video.js"
+      },
+      "./docs": {
+        "types": "./dist/docs/index.d.ts",
+        "bun": "./dist/docs/index.js",
+        "node": "./dist/node/docs/index.js",
+        "browser": "./dist/browser/docs/index.js",
+        "default": "./dist/docs/index.js"
+      },
+      "./docs/index": {
+        "types": "./dist/docs/index.d.ts",
+        "bun": "./dist/docs/index.js",
+        "node": "./dist/node/docs/index.js",
+        "browser": "./dist/browser/docs/index.js",
+        "default": "./dist/docs/index.js"
+      },
+      "./docs/video-api-showcase.docblock": {
+        "types": "./dist/docs/video-api-showcase.docblock.d.ts",
+        "bun": "./dist/docs/video-api-showcase.docblock.js",
+        "node": "./dist/node/docs/video-api-showcase.docblock.js",
+        "browser": "./dist/browser/docs/video-api-showcase.docblock.js",
+        "default": "./dist/docs/video-api-showcase.docblock.js"
+      },
+      "./example": {
+        "types": "./dist/example.d.ts",
+        "bun": "./dist/example.js",
+        "node": "./dist/node/example.js",
+        "browser": "./dist/browser/example.js",
+        "default": "./dist/example.js"
+      },
+      "./sample-specs": {
+        "types": "./dist/sample-specs.d.ts",
+        "bun": "./dist/sample-specs.js",
+        "node": "./dist/node/sample-specs.js",
+        "browser": "./dist/browser/sample-specs.js",
+        "default": "./dist/sample-specs.js"
+      }
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/video-api-showcase"
+  },
+  "homepage": "https://contractspec.io"
+}