@cotrackpro/sdk

The typed TypeScript client for the CoTrackPro platform. One place for transport, auth, typed API resources, and MCP/artifact bindings — consumed by the CLI and every cotrackpro* repo, and built to be lifted into cotrackpro-foundations and published.

Why this exists

Before the SDK, each repo (and the CLI) hand-rolled fetch, bearer auth, org-scoping, retries, and an ad-hoc error model. The SDK collapses that into a single, well-tested surface that runs anywhere fetch exists — Node, edge, browser, and agent/IDE hosts such as Google Antigravity.

Quick start

import { createClient, StaticTokenProvider } from "@cotrackpro/sdk";

const cp = createClient({
  baseUrl: "https://api.cotrackpro.com",
  org: "acme",
  auth: new StaticTokenProvider(process.env.COTRACKPRO_TOKEN!),
});

const me = await cp.whoami();
const orgs = await cp.orgs.list();
const pkgs = await cp.packages.list();

Auth providers

Pick the provider that matches your runtime — the rest of the SDK is identical:

| Provider | Use case | | --- | --- | | StaticTokenProvider | API keys / env tokens — CI, agents, Antigravity | | CallbackTokenProvider | Read a token lazily from a keychain / store (the CLI) | | DeviceFlowProvider | Browser device-flow sign-in (CLI, desktop, IDE) | | AnonymousProvider | Unauthenticated endpoints (health, device start) |

MCP / artifacts

@cotrackpro/sdk/mcp exposes typed bindings over the CoTrackPro MCP server plus a generated registry of all platform artifacts:

import {
  ARTIFACTS, ARTIFACT_NAMES, type ArtifactName,
  ROLES, WORKFLOWS, SCENARIOS, PROMPT_MODULES,
  searchArtifactsLocal, CotrackproToolset,
} from "@cotrackpro/sdk/mcp";

ARTIFACTS["parenting-plan-draft"].dataSensitivity; // "confidential"
ROLES["cotrackpro-judge"].airtableRoleNames;       // ["Judge", ...]
searchArtifactsLocal("incident");                  // offline fuzzy search, ranked

// In an MCP-capable host (Claude runtime, Antigravity), pass a tool-call fn:
const cp = new CotrackproToolset((name, args) => host.callTool(`cotrackpro.${name}`, args));
const artifacts = await cp.listArtifacts();

Offline, typed, generated registries (no network/auth): ARTIFACTS, ROLES, WORKFLOWS, SCENARIOS, PROMPT_MODULES — each with an id union, a Record<Id, Meta>, and an ids array (current counts live in the generated catalog.v1.json). searchArtifactsLocal ranks matches over the artifact registry.

Regenerating artifact types

The registries are generated from snapshots of the MCP catalog (schemas/*.index.json, synced via the MCP list_* tools):

npm run codegen   # artifacts + roles/workflows/scenarios/prompt-modules -> src/mcp/*.generated.ts

To also generate field-level interfaces, drop per-artifact JSON Schemas (from the MCP get_artifact_schema tool) into schemas/full/<name>.json and re-run codegen.

Custom parameter sets (@cotrackpro/sdk/params)

User-authored parameter sets — custom typed field schemas — share one source of truth across the CLI (cotrackpro params) and the portal builder:

import { fieldsToSchema, validateValues, renderMarkdown, type ParamSet } from "@cotrackpro/sdk/params";

const set: ParamSet = { title: "Incident", dataSensitivity: "confidential", fields: [/* ... */] };
const schema = fieldsToSchema(set);                 // canonical JSON Schema (Draft 2020-12)
const { valid, errors } = validateValues(set, vals); // value validation (no ajv)
const doc = renderMarkdown(set, vals);              // filled markdown document

The module's core is import-free (no node:/external deps) so its compiled output loads directly in the browser — the portal builder imports the very same convert/validate/render logic. FIELD_TYPES/FIELD_TYPE_LIST is the single declarative registry that drives the converter, both validators, the renderer, and the builder's widgets. schemaToInterface (Node-only, in params/codegen.ts) compiles a set to a TypeScript interface and is shared with scripts/gen-artifacts.ts.

The parameter-set format is intentionally the same shared shape the CoTrackPro Intervention Builder uses to author items/templates — one format, two entry points (offline CLI/portal convenience vs. the Builder's governed authoring path). See ../docs/strategy/three-surfaces.md for the rationale and the producer→contract→consumer model.

Testing

npm test          # from the repo root — runs the SDK unit tests via vitest