Skip to content

TypeScript SDK

The TypeScript SDK at packages/ts/skynet-sdk/ gives you typed bindings to the Skynet REST API, a coordinate-math library, and shared schemas generated from the public API's OpenAPI document.

Status

The SDK lives in the monorepo and is consumed in-tree by the website (apps/website-react/, apps/website/) and by SkyNode (apps/sky-node-desktop/gui/, gui-react/). It is not currently published to npm — to use it outside the monorepo, you either copy the package or install from a local checkout.

If you need a stable public package, flag it; promoting the SDK to npm is a small lift but currently in-tree consumers move faster than external publishes would allow.

Installing in-tree

From any other npm workspace in the repo:

// package.json of the consuming app
{
  "dependencies": {
    "skynet-sdk": "*"
  }
}

The repo's root workspaces config wires it up.

What's in it

The top-level entry point at packages/ts/skynet-sdk/src/index.ts re-exports:

API clients

One client class per resource family:

  • OrganizationsApi, UsersApi, MeApi
  • ObservationsApi, ObservationRequestsApi, ObservationResultsApi
  • ObservingAccountsApi, ObservingAccessApi, TargetsApi
  • SitesApi, ObservatoriesApi, TelescopesApi, DevicesApi
  • FilesApi, LogEntriesApi, InvitationsApi, GroupsApi, PublicApi

All clients wrap Client — the underlying HTTP client with authentication, error mapping, and the openapi-fetch typed wrapper.

import { Client, ObservationsApi } from 'skynet-sdk';

const client = new Client({ baseUrl: '/v1', token: '<access-token>' });
const observations = new ObservationsApi(client);

const page = await observations.list({ owner_id: 42 });

Generated OpenAPI types

openapi.ts is generated from public-api's /openapi.json by tools/generate/update-api-schemas.mjs. It defines the typed paths, parameters, and responses the clients use under the hood.

To regenerate after changing public-api endpoints:

node tools/generate/update-api-schemas.mjs

(Requires public-api running locally on http://127.0.0.1:5001.)

Schemas

schemas.ts mirrors the Python skynet_sdk.schemas module. Hand-authored types for things that don't round-trip cleanly through openapi-typescript plus type narrowing helpers for the polymorphic resources (Device, Instrument, ObservationRequest, ObservationTask, Target, Position, Path, BrightnessModel, …).

Graphs

graphs.ts — helpers for working with the graph API (the dict-of-resources shape — see apps/public-api/GRAPH_API_TRACKER.md for the design notes).

Role permissions

role-permissions.ts — RBAC helpers for evaluating "can this user do X on this resource" on the client without round-tripping to the server.

Coordinate math

coords/ is exported under the skynet-sdk/coords sub-path:

import { equatorialToHorizontal, julianDate } from 'skynet-sdk/coords';

What's there:

  • jd.ts — Julian-date utilities.
  • transforms.ts — coordinate-frame transformations.
  • precession.ts — precession of equinoxes.
  • separation.ts — angular separation calculations.
  • slalib.ts — SLA-library style helpers.
  • sun.ts, sidereal.ts — solar position, local sidereal time.
  • units.ts — unit conversions.

These work in the browser and Node — no native deps.

Authentication

The Client takes either:

  • A bearer token (the typical case for personal-token integrations).
  • An async token provider — useful when you're managing refresh yourself.

For OAuth refresh handling and personal-token issuance, see Auth.

Conventions

  • camelCase wire format. The Python API is configured with fastapi_camelcase so JSON bodies and query strings use camelCase; the generated TS types match. The Python models internally use snake_case (Pydantic aliases handle the conversion).
  • Pagination. Paginated endpoints return a Page<T> envelope (items, total, page, size, pages). See Conventions.
  • Errors. HTTP errors come back via the Client's error envelope; Client rejects non-2xx with a typed error you can switch on.

Building from source

# from the repo root
npm install
npm run build --workspace=skynet-sdk

The build outputs to packages/ts/skynet-sdk/dist/ for the main entry and exposes src/coords/ directly (no compile step for the coords sub-path).