TypeScript SDK

@alienplatform/sdk is what the code you deploy imports at runtime: typed access to linked resources, plus commands, event handlers, and background tasks for Workers.

import { command, kv } from "@alienplatform/sdk"
import { z } from "zod"

const SummaryInput = z.object({ accountId: z.string() })

command("get-summary", SummaryInput, async ({ accountId }) => {
  const entry = await kv("cache").getJson<{ total: number }>(`summary:${accountId}`)
  return { accountId, total: entry?.value.total ?? 0 }
})

This page documents version 3.3.41. All @alienplatform/* packages release together with the same version number.

PackagesCopy Anchor Link

InstallCopy Anchor Link

npm install @alienplatform/sdk

The bindings ship as a native addon that wraps the same Rust core as the Python and Rust SDKs. Each binary is an optional dependency, @alienplatform/bindings-<target>. If the addon is missing, check that optional dependencies were installed, or install the matching package.

BindingsCopy Anchor Link

A binding is a typed client for a resource linked to the current workload. Call the factory with the resource ID from alien.ts:

import { storage } from "@alienplatform/sdk"

const files = storage("files") // matches new alien.Storage("files")

Factories do no I/O. The first method call reads the binding from the ALIEN_<NAME>_BINDING environment variable that Alien injects for each link, and throws BindingNotConfiguredError if the resource isn't linked to this workload.

Each resource page lists the options, limits, and platform mapping: Storage, KV, Queue, Vault, Postgres, Container, Sandbox, AI, Key.

The following code uses several bindings from one workload:

import { kv, postgres, queue, storage, vault } from "@alienplatform/sdk"
import { key } from "@alienplatform/bindings"

const files = storage("files")
const path = "reports/2026-10.json"
await files.put(path, Buffer.from("{}"), { condition: "absent" })
const { url } = await files.signedUrl({ method: "GET", path, expiresIn: 300 })

await kv("cache").setJson("user:42", { plan: "pro" }, { ttl: 60 })
await queue("jobs").send({ type: "reindex" })

const token = await vault("secrets").get("upstream-token")
const db = await postgres("db").connection()
const ciphertext = await key("records").encrypt(Buffer.from("private"))

AICopy Anchor Link

ai(name) returns an OpenAI-compatible client for an AI resource. An embedded gateway signs requests with the workload's cloud identity, for Amazon Bedrock, Vertex AI, or Azure AI Foundry. The code holds no API keys, and prompts stay in the customer's cloud.

import { ai } from "@alienplatform/sdk"

const llm = ai("llm")
const [model] = await llm.getAvailableModels()
const reply = await llm.chat.completions.create({
  model: model.id,
  messages: [{ role: "user", content: "Summarize this ticket." }],
})
console.log(reply.choices[0].message.content)

Pass stream: true to get an async iterable of chunks. To use another OpenAI-compatible client, call getAiConnection(name), which returns { baseURL, apiKey? }.

Worker handlersCopy Anchor Link

A Worker's entry module registers handlers as a side effect and default-exports an HTTP app (any object with a fetch method, such as a Hono app). Export nothing if the Worker has no HTTP endpoint.

import {
  kv,
  onCronEvent,
  onQueueMessage,
  onStorageEvent,
  queue,
  storage,
  waitUntil,
} from "@alienplatform/sdk"
import { Hono } from "hono"

const app = new Hono()
app.get("/health", c => c.json({ status: "ok" }))

const uploadsFilter = { prefix: "incoming/" }

onStorageEvent("uploads", async event => {
  if (event.eventType !== "created") return
  const object = await storage("uploads").get(event.objectKey)
  await queue("jobs").send({ key: event.objectKey, size: object.meta.size })
}, uploadsFilter)

onQueueMessage<{ key: string }>("jobs", async message => {
  waitUntil(kv("cache").set(`seen:${message.payload.key}`, "1", { ttl: 3600 }))
})

onCronEvent("nightly", async event => {
  console.log("ran at", event.timestamp)
})

export default app

You declare the trigger itself (which bucket, queue, or schedule invokes the Worker) on the Worker in alien.ts. See Worker.

Pass "*" as the bucket, queue, or schedule name to match all of them. Event handlers run only in Workers; Containers and Daemons don't receive events. Every on* function returns a function that removes the handler.

Commands from your backendCopy Anchor Link

@alienplatform/commands sends commands to a deployment and receives them in workloads that aren't Workers. It uses fetch only and has no native code.

import { CommandsClient } from "@alienplatform/commands"

const commands = await CommandsClient.forDeployment({
  deploymentId: "dep_0123456789abcdef",
  apiKey: process.env.ALIEN_API_KEY!,
})

const input = { accountId: "acct_1" }
const summary = await commands.invoke<{ total: number }>("get-summary", input, {
  timeoutMs: 30_000,
})

await commands.target("indexer").invoke("reindex", {})

invoke options: timeoutMs, deadline, idempotencyKey, targetResourceId, pollIntervalMs, maxPollIntervalMs, pollBackoff. Use target(resourceId) when more than one resource handles the same command name.

A Container or Daemon receives commands with a receiver, which reads its configuration from the environment variables Alien injects:

import { createCommandReceiver } from "@alienplatform/commands"
import { z } from "zod"

const ReindexInput = z.object({ full: z.boolean().default(false) })

const receiver = createCommandReceiver()

receiver.command("reindex", ReindexInput, async ({ full }) => {
  return { started: true, full }
})

await receiver.run()

Remote bindingsCopy Anchor Link

Bindings from @alienplatform/bindings lets your backend use a resource inside a customer's environment without running code there. The resource must be added with { remoteAccess: true } in alien.ts. See Remote bindings.

import { Bindings } from "@alienplatform/bindings"

const bindings = await Bindings.forRemoteCustomer({
  project: "acme",
  externalId: "customer-1",
  token: process.env.ALIEN_API_KEY!,
})
const reports = await bindings.storage("files").list("reports/")
await bindings.queue("jobs").send({ type: "reindex" })

externalId is your own ID for the customer (its external ID). Bindings.forRemoteDeployment({ deploymentId, token }) targets one deployment instead of a customer. A remote Bindings exposes storage, queue (send only), kv, key, sandbox, and ai(), which returns a short-lived lease with the provider endpoint and credentials.

ErrorsCopy Anchor Link

Binding errors extend AlienError and carry a machine-readable code, a retryable flag, and a context object, plus internal, httpStatusCode, and hint when the backend supplies them. Branch on code, and show the message or hint to people rather than parsing it. The SDK exports AlienError, BindingNotConfiguredError, BindingNotFoundError, InvalidBindingConfigError, AiTransportError, and AiUpstreamError.

NextCopy Anchor Link

• Resources: options and runtime API for each resource
• Commands: when to use commands and how delivery works
• Testing: deploy a stack from a test
• Python SDK