@mocart-io/api

Generated TypeScript SDK for the Mocart Public API — the read plane (products, assets, campaigns, creatives, deliveries) and the run plane (runs, presets). Full guides and reference: https://docs.mocart.io.

The npm scope @mocart was already taken by another publisher, so this package ships as @mocart-io/api under the mocart-io org instead of the plan's original @mocart/api.

Install

npm install @mocart-io/api

Zero runtime dependencies — the generated client embeds its own request/response core, so the only requirement is a fetch global (Node >=18, or any browser).

ESM only. This package ships "type": "module" with no CommonJS build or require export condition. import works from any ESM project (or a .mts/.mjs file, or a .ts file compiled with a Node16/NodeNext/Bundler moduleResolution) with no extra step. From a CommonJS project (a plain .ts/.js file with no "type": "module" in the nearest package.json), require() cannot load it — use a dynamic import() instead, which works from CommonJS too:

async function main(): Promise<void> {
  const { client, listProducts } = await import('@mocart-io/api');
  client.setConfig({ baseUrl: 'https://api.mocart.io/api/public/v1', auth: () => process.env.MOCART_API_KEY });
  const { data: products } = await listProducts({ query: { brandId: 'brand_...' } });
}

(A CommonJS project compiling with tsc to a module target older than ES2020 will down-level that import() back to a require(), which fails the same way — see scripts/ops/e2e-public-api.ts in this repo for the workaround that situation needs.)

Quickstart

import { client, listProducts, estimateRun, createRun, getRun } from '@mocart-io/api';

client.setConfig({
  baseUrl: 'https://api.mocart.io/api/public/v1',
  auth: () => process.env.MOCART_API_KEY,
});

const { data: products } = await listProducts({ query: { brandId: 'brand_...' } });

See https://docs.mocart.io/guides/quickstart for the full create-a-run flow, including Idempotency-Key and webhook signature verification.

Source of truth

This SDK is generated by @hey-api/openapi-ts from the repo's committed api-spec/openapi.json — never hand-edit anything under src/generated/, nor spec.lock.json. Regenerate with:

npm run generate

npm run sdk:check (repo root) does this in CI and fails the build if the committed output would change, so src/generated/ and package.json's version field always match the spec that shipped.

Versioning

The published version is api-spec/openapi.json's info.version field, kept in sync by scripts/sync-package-version.mjs as the last step of npm run generate. A spec version bump is therefore the only thing that bumps this package — there is no separate manual version step.

That same script writes spec.lock.json — { version, specSha256 }, the pair this generate run saw. npm run sdk:check (repo root) compares it against the committed one: a spec content change under an unchanged info.version fails the check (message names the exact fix — bump API_VERSION in src/modules/public-api/contract/openapi-document.ts) instead of silently regenerating a stale-but-same-numbered SDK that publish-sdk.sh would then skip republishing.

Publishing

Handled by scripts/deploy/publish-sdk.sh (repo root) as the LAST step of cloudbuild.yaml (after verify-sentry-mappings), gated on the target version not already existing on the npm registry — specifically an npm view --json E404 on that exact version; any other failure (network, auth, registry outage) refuses to publish rather than guessing. Never publish by hand outside that gate.