Skip to main content

SDKs

Two packages, one per language, both built on the public contract: the TypeScript API types are generated from its OpenAPI document, the Python result types are tested against its result schema, and a thin handwritten layer adds auth, retries and workflow results.

PythonTypeScript
Packageconstellation-space@constellationspace/client
Importimport constellation_spaceimport { Client } from "@constellationspace/client"
RuntimePython 3.11 or newer, standard library onlyNode 18 or newer, or a browser; no runtime dependencies
Bridge base classconstellation_space.bridges.template.BridgeBridge from @constellationspace/client/bridge (Node)

Both read CONSTELLATION_API_URL (default https://api.constellation.space) and CONSTELLATION_API_KEY, sent as x-api-key. The package installs as constellation-space and imports as constellation_space. Neither client sends the key over plain http except to this machine (localhost).

Install​

Both packages are on the public registries from the first public release of the connectors repository on, and ship as files with each release too:

pip install constellation-space # Python
pip install "constellation-space[lattice]" # with the Lattice bridge's extra
npm i @constellationspace/client # TypeScript

Pin the version you use. A bridge scaffolded with constellation bridge new pins the package released with the CLI by its hash for you. Offline, or for an air-gapped site, install the release files instead: pip install ./constellation_space-<version>-py3-none-any.whl or npm install ./constellationspace-client-<version>.tgz (see Downloads).

Python​

from constellation_space import results
from constellation_space.client import Client

client = Client() # CONSTELLATION_API_URL, CONSTELLATION_API_KEY
print(client.call("GET", "/account/state"))
for entry in client.results("my-mcs"):
for resource, items in results.unpack(entry["otlp"], "my-mcs", print):
for item in items:
print(entry["cursor"], item["entity"]["id"], results.action_state(item))
ModuleWhat it holds
constellation_space.clientClient(api_url=None, api_key=None, *, retries=3, backoff=0.5, timeout=60). call(method, path, body=None) makes any API call and returns the JSON. It retries a 429, a 5xx or a dropped connection with exponential backoff, honoring Retry-After, and raises ApiError otherwise. results(consumer, after="") yields every run after a cursor, oldest first, each joined whole across its pages.
constellation_space.client.ApiErrorstatus, body, and refusal: for a 401 or 403, why the key or plan was refused and how to fix it
constellation_space.resultsThe results protocol every bridge shares: action_state(item), unpacking a run's items, joining pages, delivery reports, and acting once per approval: action_key(item) (the result's decision_id, else entity.id|verb|to), acted_until(item) and Acted, the file of keys already acted on. SCHEMA is the item shape it reads, constellation.item/v2.
constellation_space.modelsTyped shapes of workflow results: Item, Entity, Action, Run, ActionState. They are TypedDicts: items stay plain dicts and nothing is checked at runtime.
constellation_space.bridges.templateBridge: subclass it, write apply(items, settings, run) and act(item, settings, run), call run_forever(). See Build a connector.
constellation_space.bridges.yamcsThe Yamcs bridge: python -m constellation_space.bridges.yamcs, or constellation bridge run yamcs
constellation_space.bridges.latticeThe Lattice bridge: python -m constellation_space.bridges.lattice, or constellation bridge run lattice

action_state(item) returns "advice", "approved", "pending", "rejected", or None for a plain forecast. Any status other than approved or rejected is "pending".

ExtraAddsFor
[lattice]sgp4The Lattice bridge's PUBLISH_SATELLITES, to place satellites as Constellation's pass engine does

The Yamcs bridge needs no extra.

Bridge(manifest="connector.json", *, client=None, cursor_file=None, poll_seconds=None) reads CURSOR_FILE and POLL_SECONDS when they are not given. Override load_cursor() and save_cursor(cursor) to keep the cursor in your own system, so a moved or rebuilt bridge resumes where it stopped. What it acted on is kept at CURSOR_FILE.acted, keyed by decision_id (see Safety rules). A first start, with no cursor, begins at the feed's newest run; BACKFILL=1 applies the whole history instead.

TypeScript​

import { Client, ConstellationError, actionState } from "@constellationspace/client";

const client = new Client(); // CONSTELLATION_API_KEY, CONSTELLATION_API_URL in Node
for await (const entry of client.results({ consumer: "my-mcs", pollMs: 15_000 })) {
for (const { items, run } of entry.parts) {
for (const item of items) console.log(run.workflow, item.entity.id, actionState(item));
}
}

Client​

new Client({ apiKey, baseUrl, retries: 4, retryDelayMs: 500, timeoutMs: 60_000, fetch, log }). Every option is optional; in a browser, pass apiKey and baseUrl. timeoutMs bounds each attempt. The client never sends the key over plain http except to this machine.

MethodWhat it does
request(method, path, { query, body })Any API call. Returns the parsed JSON. Retries a 429, a 5xx or a network failure with exponential backoff, honoring Retry-After.
results({ after, consumer, pollMs, signal })An async iterator over the workflow runs' results after after, oldest first, each joined whole: { cursor, parts: [{ resource, items, settings, run }] }. It ends when there are no more, unless pollMs is set: then it keeps waiting for new runs until you stop iterating or signal aborts. A run in an item shape it does not read is skipped and logged.
resultsPage({ after, consumer, limit, pageRecords })One page of results, raw
checkIn(manifest), report(consumer, cursor, applied, target)What a bridge sends; Bridge calls them for you

actionState​

actionState(item) returns "advice", "approved", "pending", "rejected", or null for a plain forecast. Any status other than approved or rejected is "pending", so an item a reader does not understand is never taken for a forecast or an instruction.

Errors​

A failed call throws ConstellationError with status, body, code (the API's machine error) and detail. refused is true for a 401 or 403, which asking again does not clear. Its message says what to fix:

codeMeaningdetail
plan_requiredThe account's plan does not include this; upgrade on the Billing pageplan, the plan that does, and feature
insufficient_scopeThe key lacks a scoperequired
live_key_requiredA test key was used where a live one is needed
unknown_cursorA page was asked for of a run Constellation no longer holds; pull from your last cursor

See Errors and limits for every code.

Bridge​

Bridge from @constellationspace/client/bridge runs in Node. Subclass it, implement apply(items, settings, run) and act(item, settings, run), and call run(signal?). A refused key or plan rejects run() with the ConstellationError; any other failure is logged and retried.

new MyBridge({ manifest, client, store, pollMs, backfill, conformanceLog, log }). store is a CursorStore:

interface CursorStore {
load(): Promise<string>;
save(cursor: string): Promise<void>;
acted(): Promise<Map<string, string>>; // key to when it may be forgotten ("" for never)
saveActed(acted: Map<string, string>): Promise<void>;
}

The bridge keys what it acted on with actionKey(item): the result's decision_id, else entity.id|verb|to. A standing approval is acted on once and a re-approval again. Each key maps to actedUntil(item), 7 days (KEEP_ACTED_MS) past the latest of the item's times, its action's deadline and the time it acted, and the bridge drops keys past it. A first start begins at the feed's newest run; backfill: true, or BACKFILL=1, applies the whole history instead. The default FileCursorStore keeps the cursor at CURSOR_FILE and the acted keys at CURSOR_FILE.acted, one line per key: the key, a tab, and its time. MemoryCursorStore is for tests.

The package also exports the Result and ResultsEntry types, SCHEMA, PAGE_RECORDS, DEFAULT_API_URL, the helpers plain, unpack and whole, and the generated paths and components types from the OpenAPI document.

Go​

Go bridges use the results package of the CLI's own module, github.com/constellationhq/connectors/cli/results: results.NewBridge(manifest), then set Apply and Act and call RunForever(). It keeps the cursor at CURSOR_FILE and what it acted on at CURSOR_FILE.acted, keyed and pruned as the Python and TypeScript bridges do, and starts at the feed's newest run unless BACKFILL=1. constellation bridge new NAME --lang go writes one.