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.
| Python | TypeScript | |
|---|---|---|
| Package | constellation-space | @constellationspace/client |
| Import | import constellation_space | import { Client } from "@constellationspace/client" |
| Runtime | Python 3.11 or newer, standard library only | Node 18 or newer, or a browser; no runtime dependencies |
| Bridge base class | constellation_space.bridges.template.Bridge | Bridge 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))
| Module | What it holds |
|---|---|
constellation_space.client | Client(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.ApiError | status, body, and refusal: for a 401 or 403, why the key or plan was refused and how to fix it |
constellation_space.results | The 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.models | Typed 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.template | Bridge: subclass it, write apply(items, settings, run) and act(item, settings, run), call run_forever(). See Build a connector. |
constellation_space.bridges.yamcs | The Yamcs bridge: python -m constellation_space.bridges.yamcs, or constellation bridge run yamcs |
constellation_space.bridges.lattice | The 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".
| Extra | Adds | For |
|---|---|---|
[lattice] | sgp4 | The 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.
| Method | What 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:
code | Meaning | detail |
|---|---|---|
plan_required | The account's plan does not include this; upgrade on the Billing page | plan, the plan that does, and feature |
insufficient_scope | The key lacks a scope | required |
live_key_required | A test key was used where a live one is needed | |
unknown_cursor | A 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.