JavaScript SDK

The SateAIs JavaScript/TypeScript SDK (@sateais/sdk) is a typed, zero-dependency client for the SateAIs API. It ships both ESM and CommonJS builds with bundled type definitions, and runs on Node.js and modern runtimes with a global fetch.


Package	`@sateais/sdk` (npm)
Node.js	≥ 18
Dependencies	None (uses global `fetch`)
Modules	ESM + CommonJS, types bundled

GitHubspaceshiftinc/sateais-js

npm@sateais/sdk

Installation

npm install @sateais/sdk

// ESM / TypeScript
import { Client } from "@sateais/sdk";

// CommonJS
const { Client } = require("@sateais/sdk");

Authentication

Create an API key in the SateAIs API Console (see Authentication).

Get your free API keyYou get 500 free API credits every month during the beta. No credit card required.

The client resolves it from the first available source, in order:

The apiKey option passed to new Client(...).
The SATEAIS_API_KEY environment variable.

import { Client } from "@sateais/sdk";

// 1. Explicit option
const client = new Client({ apiKey: "sk_live_xxxxx" });

// 2. From SATEAIS_API_KEY (recommended)
const client = new Client();

If no key can be resolved, the first request throws an AuthenticationError.

Keep your key secret

Never ship sk_live_ keys in client-side bundles or commit them to source control. Keep keys server-side, in SATEAIS_API_KEY.

Creating a client

const client = new Client({
  apiKey: process.env.SATEAIS_API_KEY, // falls back to env automatically
  baseUrl: "https://api.spcsft.com/api/v1", // default
  timeoutMs: 30_000, // per-request timeout (default 30s)
  fetch: globalThis.fetch, // custom fetch implementation (optional)
});

Option	Type	Default	Description
`apiKey`	`string`	`SATEAIS_API_KEY`	API key. Falls back to the environment variable.
`baseUrl`	`string`	`https://api.spcsft.com/api/v1`	API base URL. Trailing slashes are removed.
`timeoutMs`	`number`	`30_000`	Per-request timeout in milliseconds (via `AbortController`).
`fetch`	`typeof fetch`	global `fetch`	Custom fetch implementation for testing or non-standard runtimes.

Your first detection

import { Client } from "@sateais/sdk";

const client = new Client();

// Submit a job
const job = await client.analyze.ship({ scene_id: "S1A_IW_GRDH_..." });
console.log(job.job_id, job.status); // "...", "pending"

// Poll until completion and fetch the GeoJSON
const result = await client.jobs.wait(job.job_id, {
  intervalMs: 30_000,
  onPoll: (j) => console.log(j.status),
});
console.log(result.features.length, "ships detected");

Handling errors

All SDK errors inherit from SateaisError. API responses map to typed subclasses that mirror the API error codes:

import {
  Client,
  RateLimitError,
  JobFailedError,
  InsufficientCreditsError,
} from "@sateais/sdk";

const client = new Client();

try {
  const job = await client.analyze.timeseries({
    polygon: "POLYGON((...))",
    date_start: "2026-01-01",
    date_end: "2026-05-01",
  });
  const result = await client.jobs.wait(job.job_id, { timeoutMs: 3_600_000 });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.error("Top up credits in the Console");
  } else if (err instanceof RateLimitError) {
    console.error("Rate limited — back off and retry");
  } else if (err instanceof JobFailedError) {
    console.error("Job failed:", err.errorCode, err.errorMessage);
  } else {
    throw err;
  }
}