CmdCal

SDK API Reference

CmdCal V2 exposes a documented semantic protocol and a private render runtime.

Protocol Contract

The PresentationSpec contract is part of the public hosted runtime surface, but the workspace @paperjsx/protocol package is internal/private in this hardening pass. External users should treat the protocol as a wire contract and validate it in their own app or against the documented shape below.

PresentationSpecSchema

TYPESCRIPT
import { z } from "zod";

const PresentationSpecSchema = z.object({
  version: z.literal("2.0"),
  title: z.string(),
  accentColor: z.string().optional(),
  slides: z.array(z.unknown()),
});

PresentationSpec

TYPESCRIPT
interface PresentationSpec {
  version: "2.0";
  title: string;
  accentColor?: string;
  brand?: {
    brandPackId?: string;
    brandPackVersionId?: string;
  };
  slides: SlideSpec[];
}

SlideSpec

The first stable V2 slide/component set is:

  • title-body
  • kpi-grid
  • comparison-table
  • market-map
  • timeline
  • org-chart
  • waterfall
  • tombstone-grid

Example:

TYPESCRIPT
type PresentationSpec = {
  version: "2.0";
  title: string;
  accentColor?: string;
  slides: SlideSpec[];
};

const document: PresentationSpec = {
  version: "2.0",
  title: "Board Update",
  accentColor: "#2563EB",
  slides: [
    {
      slideType: "title-body",
      title: "Executive Summary",
      body: [
        "Revenue accelerated in Q2.",
        "The operating model is ready for rollout."
      ]
    },
    {
      slideType: "kpi-grid",
      title: "Core KPIs",
      items: [
        { label: "ARR", value: "$12.4M", trend: "up" },
        { label: "NRR", value: "118%", trend: "up" }
      ]
    }
  ]
};

JSON Schema

Use the documented PresentationSpec shape as the canonical contract for hosted runtime requests. The internal workspace package that produces JSON Schema is not a supported npm dependency in this phase.

Runtime Endpoints

The render runtime is API-only. The canonical flow is preflight -> render job -> poll job -> compare/approve.

POST /api/v2/preflight

TYPESCRIPT
{
  sourceSchema: "protocol_v2",
  brandPackId?: string,
  brandPackVersionId?: string,
  preflightPolicy?: {
    autoFix?: "off" | "suggest_only"
  },
  document: PresentationSpec
}

Returns:

  • data.job_id
  • data.job_url
  • data.quality_report
  • data.brand_compliance
  • data.policyResult
  • data.validationSummary
  • data.requested_validation_mode

policyResult is the canonical V2 guardrail decision. It includes:

  • allowedToRender
  • blocking
  • blockingCodes
  • blockingFindingCount
  • unsupportedModes
  • reasons
  • nextActions

If the requested validation mode is unsupported, /api/v2/preflight returns a durable blocked decision instead of pretending the mode ran successfully. The response stays on the same route and includes the job URL plus policyResult.

validationSummary records what actually ran versus what was deferred:

  • requestedMode
  • preflightExecutedModes
  • renderExecutedModes
  • executedModes
  • deferredModes
  • unsupportedModes
  • reason

POST /api/v2/render

TYPESCRIPT
{
  sourceSchema: "protocol_v2" | "agent_v1",
  mode?: "sync" | "async",
  approvalRequired?: boolean,
  brandPackId?: string,
  brandPackVersionId?: string,
  baselineJobId?: string,
  preflightPolicy?: {
    preflightOnly?: boolean,
    renderIfScoreAbove?: number,
    autoFix?: "off" | "suggest_only"
  },
  document: PresentationSpec
}

Returns:

  • sync mode: artifact URLs plus quality_report
  • sync mode also includes policyResult and validationSummary
  • async mode: job_id and job_url

For desktop_blocking, validationSummary makes the phase split explicit instead of implying that desktop validation ran during preflight. A successful render can show executedModes: ["structural", "desktop_blocking"] with a reason noting that desktop validation was deferred until render-backed execution.

GET /api/v2/jobs/:id

Returns the durable job record with:

  • artifacts and preview URLs
  • latest approval and approval history
  • diff summary
  • brand-pack metadata
  • preflight report summary

GET /api/v2/jobs/:id/diff

Returns:

  • deck-level diff summary
  • per-slide slides[]
  • currentPreviewUrl
  • baselinePreviewUrl
  • diffPreviewUrl
  • approval payload and package diff

Legacy Compatibility

Legacy AgentDocument inputs and the legacy generation route still exist for compatibility with V1 clients.

Use them only if you already depend on the legacy six-pattern authoring model. New integrations should use the documented PresentationSpec contract with the V2 runtime.