TypeScript SDK

@altnautica/plugin-sdk (v1.3.0, GPL-3.0-or-later) is the GCS-half SDK: the package a plugin’s Mission Control side imports. A plugin’s GCS half always uses it; its agent half uses the Python SDK or the Rust SDK. The SDK hides the postMessage envelope and gives you a typed PluginContext.

Install

The package is not published to npm. Develop your plugin inside the altnautica/ADOSExtensions monorepo as a pnpm workspace member; the scaffolder pins the SDK to workspace:^ against the in-tree packages/plugin-sdk. Your first plugin walks through the clone and scaffold flow. The package ships ESM only, with no runtime dependencies, and four entry points:

Import	What it holds
`@altnautica/plugin-sdk`	`definePlugin`, the context, the client, the parameter helpers and the types.
`@altnautica/plugin-sdk/harness`	`createPluginHarness`, the synthetic host for unit tests.
`@altnautica/plugin-sdk/inline`	The types for a first-party `gcs.isolation: inline` module.
`@altnautica/plugin-sdk/esbuild`	`inlineSharedExternals()`, the esbuild plugin an inline module builds with.

`definePlugin`

The single entry point:

import { definePlugin } from "@altnautica/plugin-sdk";

definePlugin({
  id: "com.example.my-plugin",
  version: "1.0.0",
  locale: { "hello.title": "Hello" },
  async mount(ctx, info) {
    // wire up subscriptions, render the panel
  },
  async unmount(ctx, info) {
    // optional teardown
  },
});

mount is called once the bundle loads. A throw is not reported to the host, so catch errors and render your own error state. info is { id, version } from your definePlugin call. Before Mission Control destroys the frame it asks the plugin to unmount and waits up to 500 ms; keep unmount short and do not rely on it to persist state. See Lifecycle. definePlugin returns a PluginInstance with info, ctx and an unmount() you can call for your own teardown.

`PluginContext`

The argument the SDK hands to mount:

interface PluginContext {
  client: PluginClient;
  telemetry: {
    subscribe<T>(topic: string, handler: (args: T) => void): Promise<() => void>;
  };
  perception: {
    readTier(): Promise<PerceptionTierInfo>;
    subscribeDetections(handler: (batch: PerceptionDetectionBatch) => void): Promise<() => void>;
    readSessionHealth(): Promise<PerceptionSessionHealth>;
  };
  command: {
    send(command: string, args?: unknown): Promise<unknown>;
  };
  notifications: {
    publish(payload: NotificationPayload): Promise<unknown>;
  };
  recording: {
    mark(payload: RecordingMark): Promise<unknown>;
  };
  mission: {
    read(missionId: string): Promise<unknown>;
    write(update: MissionUpdate): Promise<unknown>;
  };
  config: {
    onChange<T>(handler: (next: T) => void): () => void;
  };
  events: {
    subscribe<T>(topic: string, handler: (args: T) => void): () => void;
    listen<T>(topic: string, handler: (args: T) => void): Promise<() => void>;
    publish(topic: string, payload: unknown): Promise<unknown>;
  };
  records: PluginRecordsApi;
  theme: {
    onChange(handler: (vars: Record<string, string>) => void): () => void;
  };
  i18n: {
    t(key: string, params?: Record<string, string | number>): string;
  };
}

command.send and mission.write wait for the operator’s decision rather than a fixed deadline. A denial, a command the host does not allow, or a rate limit rejects with a HostError whose code is refused. events.subscribe reads one-way host pushes (video-overlay host props, an agent plugin’s state read-back) and needs no grant. events.listen and events.publish use the GCS plugin bus between installed plugin panels and need event.subscribe and event.publish. records reads and writes the plugin’s own cloud collection: list(opts), get(collection, key), put(collection, key, data) and remove(collection, key). definePlugin builds the context for you. To build one by hand (in a test, for example), use createPluginContext:

import { createPluginContext } from "@altnautica/plugin-sdk";

const ctx = createPluginContext({ locale: { "hello.title": "Hello" } });
await ctx.telemetry.subscribe("battery", (s) => store.ingest(s));

Wrappers and the bridge methods they call

Each wrapper delegates to one PluginClient call. The wire methods and their capabilities are on GCS bridge methods.

Wrapper	Bridge method	Capability
`ctx.telemetry.subscribe(topic, h)`	`telemetry.subscribe`	`telemetry.subscribe.<topic>`
`ctx.perception.readTier()`	`perception.read`	`perception.read`
`ctx.perception.subscribeDetections(h)`	`perception.subscribe`	`perception.subscribe`
`ctx.perception.readSessionHealth()`	`perception.health`	`perception.read`
`ctx.command.send(command, args)`	`command.send`	`command.send`, or `vision.track.designate` for `vision.designate`
`ctx.notifications.publish(payload)`	`notification.publish`	`ui.slot.notification-channel`
`ctx.recording.mark(payload)`	`recording.mark`	`recording.write`
`ctx.mission.read(id)`	`mission.read`	`mission.read`
`ctx.mission.write(update)`	`mission.write`	`mission.write`
`ctx.events.listen(topic, h)`	`events.subscribe`	`event.subscribe`
`ctx.events.publish(topic, payload)`	`events.publish`	`event.publish`
`ctx.records.list/get/put/remove`	`records.list/get/put/remove`	`cloud.records`
`ctx.config.onChange(h)`	host-pushed `config.changed`	none
`ctx.theme.onChange(h)`	host-pushed `theme.changed`	none

For any other method, call ctx.client.request(method, capability, args).

`PluginClient`

The lower-level RPC client:

import { PluginClient } from "@altnautica/plugin-sdk";

const client = new PluginClient();
const result = await client.request<{ ok: boolean }>(
  "telemetry.subscribe",
  "telemetry.subscribe.battery",
  { topic: "battery" },
  { timeoutMs: 3000 },
);

request(method, capability, args, options?): send a request and await the response. Default timeout 5 s.
on(method, handler): subscribe to host-pushed events.
subscribeTelemetry(topic, handler): does both the subscribe request and the telemetry.<topic> listener.
dispose(): tear down listeners and reject in-flight requests.

The client caches the capability token Mission Control pushes on the capability.token event (CAPABILITY_TOKEN_EVENT), so token rotation needs no plugin code. A request the host refuses with capability_denied:token_missing is held and sent again once the first token arrives. The capability argument is typed with the CapabilityId union of every known id.

`HostError`

Thrown when the host returns an error envelope:

import { HostError } from "@altnautica/plugin-sdk";

try {
  await ctx.command.send("land");
} catch (err) {
  if (err instanceof HostError && err.code === "permission_denied") {
    // show a banner
  } else {
    throw err;
  }
}

Branch on code; the message is for humans. The codes are listed on GCS bridge methods.

Other exports

contributesModel: an identity helper that types a contributes literal (editor autocomplete and a compile-time shape check) and returns it unchanged, for manifest fixtures and codegen.
validateValue, clampValue, inferWidget, resolveBinding, defaultFor, PARAMETER_WIDGETS, PARAMETER_BINDINGS: the parameter schema helpers. See Parameter schema.
createWindowTransport, MemoryTransport: the transports under PluginClient.
PROTOCOL_VERSION, TELEMETRY_TOPICS and the envelope, telemetry, perception, records and contribution types.

Test harness

import { createPluginHarness } from "@altnautica/plugin-sdk/harness";

const harness = createPluginHarness({
  grantedCapabilities: ["telemetry.subscribe.battery"],
  mount: async (ctx) => {
    await ctx.telemetry.subscribe("battery", (s) => store.ingest(s));
  },
});

await harness.start();
harness.pushTelemetry("battery", mockSample);
expect(harness.calls.map((c) => c.method)).toContain("telemetry.subscribe");
await harness.teardown();

The harness:

mounts the plugin against an in-memory transport (no real iframe);
records every request in harness.calls, with harness.notifications and harness.recordingMarks as shortcuts;
pushes host traffic with pushTelemetry, pushEvent, pushConfig, pushTheme and pushPerceptionDetection, and stubs reads with stubPerceptionTier and stubPerceptionHealth;
simulates host failures with failNext(method, code, message);
gates calls by capability like the bridge: a telemetry subscription needs its topic grant (telemetry.subscribe.<topic>), and a ui.slot.* RPC needs that slot’s capability.

Building the bundle

The SDK has no build step of its own. The create-ados-plugin templates use esbuild:

esbuild src/plugin.ts --bundle --format=esm --target=es2022 --outfile=plugin.bundle.js --minify

Run from gcs/, the output is gcs/plugin.bundle.js, the path the manifest’s gcs.entrypoint names. The bundle is not hashed in the manifest; the archive signature covers it.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

Install

`definePlugin`

`PluginContext`

Wrappers and the bridge methods they call

`PluginClient`

`HostError`

Other exports

Test harness

Building the bundle

Next steps

Your first plugin

GCS bridge methods

​Install

​definePlugin

​PluginContext

​Wrappers and the bridge methods they call

​PluginClient

​HostError

​Other exports

​Test harness

​Building the bundle

​Next steps

Your first plugin

GCS bridge methods

Install

`definePlugin`

`PluginContext`

Wrappers and the bridge methods they call

`PluginClient`

`HostError`

Other exports

Test harness

Building the bundle

Next steps