@codespar/api-types

A standalone npm package (@codespar/api-types) that defines the wire contract between api.codespar.dev and any client. Every request body and response shape is declared once, as a Zod schema, and the matching TypeScript type is inferred from it.

npm install @codespar/api-types

Why it exists

For most users, you should never need this package directly — @codespar/sdk and codespar (Python) wrap the API and expose typed methods. The shapes here are what those SDKs use under the hood.

You do want this package if you're:

• Building a raw HTTP client against api.codespar.dev (no SDK)
• Writing a wrapper in another language (Go, Rust, Ruby...) and need authoritative shapes to mirror
• Adding runtime validation at your application's edge (parse incoming responses with Zod and fail loud on contract drift)

It's also the package you read first when someone asks "what's the shape of ConnectionRow?" — instead of digging through SDK source.

What's in it

Every module exports both the Zod schema (FooSchema) and the inferred TypeScript type (Foo) — import whichever side you need.

Example — runtime validation at the fetch boundary

The most concrete value comes from parsing responses with the schema, so contract drift fails loud at the seam instead of silently rendering wrong data:

import { ListApiKeysResponseSchema, type ApiKeyRow } from "@codespar/api-types";

async function listApiKeys(token: string): Promise<ApiKeyRow[]> {
  const res = await fetch("https://api.codespar.dev/v1/api-keys", {
    headers: { authorization: `Bearer ${token}` },
  });
  const raw = await res.json();

  // Throws ZodError if the backend response shape ever drifts.
  // Beats discovering it as a missing field 200ms later in your UI.
  const parsed = ListApiKeysResponseSchema.parse(raw);
  return parsed.keys;
}

This pattern is exactly what the dashboard does in its Server Actions — every backend response gets safeParse'd at the boundary.

Example — type-only usage

If you're using fetch directly but trust the shape, type-only imports work too:

import type { ApiKeyRow, CreatedApiKey } from "@codespar/api-types";

const res = await fetch("/v1/api-keys", { method: "POST", body: JSON.stringify({ name: "ci" }) });
const created: CreatedApiKey = await res.json();
console.log(created.full_key); // typed as string

The import type form means zero runtime cost — Zod schemas don't ship to your bundle. Only import { ... } (no type keyword) brings the runtime validators in.

Date fields

Every timestamp field on the wire is a string (ISO-8601 with offset), not a JS Date. Fastify on the backend serializes Date objects to strings before sending; the schemas mirror that exactly:

TimestampSchema = z.string().datetime({ offset: true })

If you need Date objects in your application, parse them on your side:

const apiKey = ApiKeyRowSchema.parse(raw);
const createdAt = new Date(apiKey.created_at); // ISO string -> Date

Versioning

• The package mirrors the /v1/* REST surface of api.codespar.dev.
• Additive changes (new field, new endpoint schema) → minor bump (0.1.0 → 0.2.0).
• Breaking changes (field removed, type narrowed) → major bump (0.1.0 → 1.0.0), shipped alongside a matching backend release.

The api.codespar.dev/v1 surface itself is versioned via the /v1 path prefix. A /v2 would ship as a separate path with a parallel @codespar/api-types-v2 package, not as a breaking bump in 0.x.

Source

• npm: @codespar/api-types
• GitHub: codespar/codespar-core/tree/main/packages/api-types
• License: MIT

The package source is < 500 lines of TypeScript. If you want to grok the entire wire contract in one sitting, reading packages/api-types/src/ is the fastest path.

Next steps