@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 (133), ROLES (18), WORKFLOWS (5), SCENARIOS (9), PROMPT_MODULES (12) — each with an id union, a Record<Id, Meta>, and an ids array. 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