REST client

Available from @codespar/sdk 0.12.0, which is not on npm yet. The published version today is 0.11.0, and it has no cs.api; 0.12.0 is on the main branch of codespar-core. The examples below are not compiled against the installed package for that reason.

cs.api reaches every operation the API publishes at https://api.codespar.dev/openapi.json. No method on it is written by hand: the document is committed in the core as openapi-snapshot.json, the types under src/generated/ are produced from it with openapi-typescript, and the client is typed by path and method. A path that does not declare the method does not compile, a missing required path parameter or body field does not compile, and the result is the documented 2xx shape.

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });

// Documented 2xx data, or a thrown CodesparApiError.
const wallets = await cs.api.get("/v1/wallets");

// Every documented status as a value, discriminated on `status`.
const payment = await cs.api.response("post", "/v1/wallets/{id}/execute", {
  path: { id: "wlt_0000000000000000" },
  body: {
    amount: 1,
    currency: "BRL",
    recipient: "recipient@example.com",
    description: "Example payment",
    mandate_id: "mnd_0000000000000000",
  },
});
if (payment.status === 402) {
  console.log("approval needed", payment.data);
}

Calls

Two verbs and five shorthands, all on cs.api:

options carries path, query, header and body exactly as the document declares them, required where the document says so, plus the per-call timeout (milliseconds) and signal. When every option is optional the argument itself is optional. The path values are URL-encoded and expanded into the template before the request; a missing one throws before anything is sent. Operations documented as text/event-stream resolve to the raw Response once headers arrive; the body stays bound to signal, not to timeout.

Errors follow the rest of the SDK: a non-2xx from request is a CodesparApiError with status, code and body; a network failure is the same class with status: 0; a timeout is a TimeoutError.

The client only knows what the document says. A parameter a route accepts but does not declare is not typed here, and the fix is in the document, not in the package.

ApiClient

The class behind cs.api. new ApiClient({ baseUrl, apiKey, projectId?, timeout }) builds one with its own credentials; ApiClient.operations() lists every { method, path } it can reach, in document order. The x-codespar-project header is sent when projectId is set, the same way the session client does it.

createApiClient

createApiClient(config) returns a new ApiClient without a CodeSpar instance, for code that only ever talks REST. Same ApiClientConfig as the constructor.

API_OPERATIONS

The generated table the client dispatches from: one { method, path, body, accept } row per operation, where body and accept are the request and response content types the document declares. It is exported for tooling that wants to enumerate the surface; the client refuses a method/path pair that is not in it with an error naming the pair.

The types that go with these are exported too: ApiPaths, ApiPath, ApiMethod, ApiOperation, ApiRequestOptions, ApiRequestBody, ApiResponse, ApiSuccess, ApiOperationRef, ApiPathsFor and ApiComponents (the document's components), for typing a wrapper around the client.

Operations by group

213 operations across 54 groups, the same groups as the HTTP reference. Each page shows the typed call for every operation and links to the HTTP reference section that carries the parameter tables and response shapes.

Versions: @codespar/sdk 0.11.0 on npm, 0.12.0 on main; the client exists from 0.12.0.