SDK utilities

These utilities support the resource operations documented under API.

Typed inputs and results

Method inputs and results are exported by openship. Derive a specific operation's types when writing a reusable integration:

import type { ProjectOperations } from "openship";

type CreateProjectInput = Parameters<ProjectOperations["create"]>[0];
type Project = Awaited<ReturnType<ProjectOperations["get"]>>;

export async function createProject(input: CreateProjectInput): Promise<Project> {
  return ship.projects.create(input);
}

Do not import internal repository packages. The public package exports the operation types, contracts, and SDK errors. ? in an operation table marks an optional argument.

Pagination

iteratePages() works with named list methods that return { data, total?, page?, perPage? }:

import { iteratePages } from "openship";

for await (const project of iteratePages((page) => ship.projects.list(page), { perPage: 50 })) {
  console.log(project.id, project.name);
}

Pass signal to stop iteration. Methods that return a plain array do not need this helper. Access is checked by the underlying list operation on every page.

Deployment helpers

Use ship.deployment(id) for a handle, or pass an operations object directly:

import { createDeploymentHandle, waitForDeployment, consumeDeploymentEvents } from "openship";

const handle = createDeploymentHandle(ship.deployments, "dep_123");
const status = await handle.status();
console.log(status.deploymentStatus);

export async function waitForRelease(deploymentId: string) {
  return waitForDeployment(ship.deployments, deploymentId, { timeoutMs: 120_000 });
}

export async function printBuildLogs(deploymentId: string, signal: AbortSignal) {
  return consumeDeploymentEvents(ship.deployments.events(deploymentId, { signal }), (event) => {
    if (event.log) process.stdout.write(event.log);
  });
}

createDeploymentHandle() exposes id, get, status, wait, events, cancel, respond, and rollback. It does not own an installation. See deployment outcomes and decisions.

Compose normalization

normalizeComposeServices(document, baseDirectory) converts normalized Compose JSON, such as docker compose config --format json, into the input expected by services.sync().

import { normalizeComposeServices } from "openship";

const services = normalizeComposeServices(
  {
    services: { cache: { image: "redis:7" } },
  },
  "/absolute/path/to/project",
);

await ship.services.sync("proj_123", { services });

It validates unsupported mount, build, and namespace settings. Parse YAML and resolve Compose interpolation before calling this helper. See services.

HTTP transport

Only a remote OpenshipClient exposes http. Use it for documented endpoints without a named SDK method:

import type { OpenshipClient } from "openship";

export async function readImageCatalog(client: OpenshipClient) {
  return client.http.request("/images");
}

http.request<T>(path, init?) parses the JSON response body; T is your assertion, not runtime validation. http.raw(path, init?) returns a Response. http.events(path, options?) reads an SSE stream, and http.url(path) constructs an API URL. These helpers retain the client's URL, credential, and scope restrictions. They do not add native support to an HTTP-only feature.

For error handling, see SDK errors.