maritime-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,287 @@
+interface MaritimeClientOptions {
+    /**
+     * Maritime API key (`mk_...`). Defaults to the `MARITIME_API_KEY` env var.
+     * Mint one from the dashboard (Settings → API keys) or `maritime keys create`.
+     */
+    apiKey?: string;
+    /** API base URL. Defaults to `MARITIME_API_URL` or `https://api.maritime.sh`. */
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 60_000). */
+    timeout?: number;
+    /** Retries on network errors and 5xx/429 responses (default 2). */
+    maxRetries?: number;
+    /** Inject a custom fetch (tests, proxies, non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+    /** Extra headers sent on every request. */
+    defaultHeaders?: Record<string, string>;
+}
+interface RequestOptions {
+    method: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+    /** Override retry behaviour for a single call (e.g. non-idempotent POST). */
+    idempotent?: boolean;
+}
+/**
+ * Thin transport: auth header, JSON encode/decode, typed errors, and bounded
+ * retry with exponential backoff on transient failures. No dependencies —
+ * uses the runtime's global `fetch` (Node 18+, Bun, Deno, browsers, edge).
+ */
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    constructor(options?: MaritimeClientOptions);
+    private buildUrl;
+    request<T>(opts: RequestOptions): Promise<T>;
+    private backoff;
+    private parseBody;
+    private safeDetail;
+}
+
+/** Framework/template ids accepted by Maritime. Any string is allowed (the API
+ * is the source of truth) but these are the common ones with editor help. */
+type Template = 'openclaw' | 'openclaw_identity' | 'openclaw_browser' | 'maritime' | 'hermes' | 'hermes_identity' | 'zeroclaw' | (string & {});
+type Tier = 'smart' | 'extended' | 'always_on';
+type AgentStatus = 'sleeping' | 'active' | 'deploying' | 'error' | 'stopped';
+/** One env var to seed at create time. */
+interface EnvVarInput {
+    key: string;
+    value: string;
+    /** Encrypt at rest + mask in reads. Defaults to true. */
+    secret?: boolean;
+}
+interface CreateAgentParams {
+    /** Unique (per account) agent name. */
+    name: string;
+    /** Template/framework. Strongly recommended — a bare framework yields a broken
+     * placeholder image. Defaults to `openclaw` in {@link AgentsResource.provision}. */
+    template?: Template;
+    /** Your own id for this agent (e.g. your end-customer id). Filterable later. */
+    externalId?: string;
+    description?: string;
+    /** Plain-English persona / system prompt. */
+    instructions?: string;
+    tier?: Tier;
+    /** Seed env vars (API keys, config). Secrets are encrypted at rest. */
+    env?: EnvVarInput[];
+    /** Per-agent resource overrides (else the tier default applies). */
+    memMb?: number;
+    vcpus?: number;
+    /** Idle seconds before auto-sleep. 0 = always-on. */
+    idleTtlSeconds?: number;
+    diskGb?: number;
+    /** GitHub repo to build from instead of a template image. */
+    githubRepo?: string;
+    /** Explicit Docker image (advanced; usually use `template`). */
+    imageName?: string;
+}
+interface Agent {
+    id: string;
+    name: string;
+    description: string | null;
+    externalId: string | null;
+    framework: string;
+    tier: Tier;
+    status: AgentStatus;
+    publicUrl?: string | null;
+    invocationCount: number;
+    totalComputeSeconds: number;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+interface EnvVar {
+    key: string;
+    value: string;
+    isSecret: boolean;
+}
+interface LogEntry {
+    id: string;
+    level: string;
+    message: string;
+    source?: string | null;
+    timestamp: string | null;
+}
+interface ChatResult {
+    /** The agent's reply, or null if delivery failed (see `error`). */
+    response: string | null;
+    error?: string;
+}
+interface ListAgentsParams {
+    /** Exact-match filter on the caller-supplied external id. */
+    externalId?: string;
+    /** Exact-match filter on agent name. */
+    name?: string;
+}
+interface ChatOptions {
+    conversationId?: string;
+}
+type ApiKeyScope = 'provision' | 'deploy' | 'secrets' | 'manage' | (string & {});
+interface CreateApiKeyParams {
+    name: string;
+    /** Defaults to a full-access key. Pass a narrower set to restrict it. */
+    scopes?: ApiKeyScope[];
+    /** Expiry in days from now. Omit for a non-expiring key. */
+    expiresInDays?: number;
+}
+interface ApiKey {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    scopes: string[];
+    isActive: boolean;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+}
+interface CreatedApiKey extends ApiKey {
+    /** The full key — shown once. Store it now. */
+    rawKey: string;
+}
+
+/** Operations on Maritime agents. Access via `maritime.agents`. */
+declare class AgentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Create a new agent and kick off its deploy. */
+    create(params: CreateAgentParams): Promise<Agent>;
+    /**
+     * Get-or-create an agent by `externalId` — the idempotent entry point for a
+     * "one agent per end-customer" flow. If an agent with that external id
+     * already exists it is returned; otherwise a new one is created. Safe to call
+     * on every sign-in.
+     */
+    provision(params: CreateAgentParams & {
+        externalId: string;
+    }): Promise<Agent>;
+    /** Fetch a single agent by id. */
+    get(agentId: string): Promise<Agent>;
+    /** List agents, optionally filtered by `externalId` or `name`. */
+    list(params?: ListAgentsParams): Promise<Agent[]>;
+    /**
+     * Send a message to an agent and wait for its reply. Sleeping serverless
+     * agents auto-wake. Returns `{ response }` (or `{ response: null, error }`
+     * if delivery failed — Maritime does not surface that as an HTTP error).
+     */
+    chat(agentId: string, message: string, opts?: ChatOptions): Promise<ChatResult>;
+    /** Start / wake an agent. */
+    start(agentId: string): Promise<Agent>;
+    /** Stop an agent (container stopped, state preserved). */
+    stop(agentId: string): Promise<Agent>;
+    /** Put an agent to sleep (serverless snapshot; cheapest resting state). */
+    sleep(agentId: string): Promise<Agent>;
+    /** Restart an agent. */
+    restart(agentId: string): Promise<Agent>;
+    /** Delete an agent and all its resources (container, volume, network). */
+    delete(agentId: string): Promise<void>;
+    /** List an agent's env vars (secret values are masked). */
+    listEnv(agentId: string): Promise<EnvVar[]>;
+    /**
+     * Set (upsert) an env var. Secrets are encrypted at rest. Changes reach a
+     * running container after {@link reloadEnv} or a restart.
+     */
+    setEnv(agentId: string, key: string, value: string, opts?: {
+        secret?: boolean;
+    }): Promise<EnvVar>;
+    /** Delete an env var. */
+    deleteEnv(agentId: string, key: string): Promise<void>;
+    /** Hot-reload env vars into the running container (falls back to restart). */
+    reloadEnv(agentId: string): Promise<Agent>;
+    /** Fetch recent log entries for an agent. */
+    logs(agentId: string, opts?: {
+        limit?: number;
+        level?: string;
+    }): Promise<LogEntry[]>;
+    private lifecycle;
+}
+
+/**
+ * Manage API keys (`mk_...`) programmatically. Access via `maritime.keys`.
+ *
+ * Minting a key requires the caller's own key to carry the `manage` scope (or
+ * be a dashboard session). Hand a narrower-scoped key to a subsystem that only
+ * needs part of the surface — e.g. a `deploy`-scoped key for a worker that only
+ * chats to agents.
+ */
+declare class KeysResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Mint a new key. The raw key is returned once — store it immediately. */
+    create(params: CreateApiKeyParams): Promise<CreatedApiKey>;
+    /** List the caller's keys (raw values are never returned again). */
+    list(): Promise<ApiKey[]>;
+    /** Revoke a key by id. */
+    revoke(keyId: string): Promise<void>;
+}
+
+/** Base class for every error the SDK throws. Catch this to catch them all. */
+declare class MaritimeError extends Error {
+    constructor(message: string);
+}
+/** The request never reached Maritime (DNS, connection refused, timeout, …). */
+declare class MaritimeConnectionError extends MaritimeError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/** Maritime returned a non-2xx response. Subclassed by status below. */
+declare class MaritimeAPIError extends MaritimeError {
+    readonly status: number;
+    readonly detail: string;
+    /** Value of the `x-request-id` response header, when present. */
+    readonly requestId?: string;
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 401 / 403 — bad or insufficiently-scoped API key. */
+declare class MaritimeAuthError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 402 — the account wallet needs funding before this action can proceed. */
+declare class MaritimePaymentRequiredError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 404 — the agent (or other resource) does not exist or is not yours. */
+declare class MaritimeNotFoundError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 409 — a uniqueness conflict (e.g. an agent with that name already exists). */
+declare class MaritimeConflictError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 429 — rate limited. */
+declare class MaritimeRateLimitError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+
+/**
+ * The Maritime client. Provision and drive AI agents on Maritime's serverless
+ * infrastructure from your own backend.
+ *
+ * ```ts
+ * import { Maritime } from 'maritime-sdk'
+ *
+ * const maritime = new Maritime({ apiKey: process.env.MARITIME_API_KEY })
+ *
+ * // When YOUR user signs up, give them their own agent (idempotent):
+ * const agent = await maritime.agents.provision({
+ *   externalId: `customer_${userId}`,
+ *   name: `assistant-${userId}`,
+ *   template: 'openclaw',
+ * })
+ *
+ * const { response } = await maritime.agents.chat(agent.id, 'Hello!')
+ * ```
+ */
+declare class Maritime {
+    readonly agents: AgentsResource;
+    readonly keys: KeysResource;
+    /** The underlying transport — escape hatch for endpoints not yet wrapped. */
+    readonly http: HttpClient;
+    constructor(options?: MaritimeClientOptions);
+}
+
+export { type Agent, type AgentStatus, type ApiKey, type ApiKeyScope, type ChatOptions, type ChatResult, type CreateAgentParams, type CreateApiKeyParams, type CreatedApiKey, type EnvVar, type EnvVarInput, type ListAgentsParams, type LogEntry, Maritime, MaritimeAPIError, MaritimeAuthError, type MaritimeClientOptions, MaritimeConflictError, MaritimeConnectionError, MaritimeError, MaritimeNotFoundError, MaritimePaymentRequiredError, MaritimeRateLimitError, type Template, type Tier, Maritime as default };

package/dist/index.d.ts

@@ -0,0 +1,287 @@
+interface MaritimeClientOptions {
+    /**
+     * Maritime API key (`mk_...`). Defaults to the `MARITIME_API_KEY` env var.
+     * Mint one from the dashboard (Settings → API keys) or `maritime keys create`.
+     */
+    apiKey?: string;
+    /** API base URL. Defaults to `MARITIME_API_URL` or `https://api.maritime.sh`. */
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 60_000). */
+    timeout?: number;
+    /** Retries on network errors and 5xx/429 responses (default 2). */
+    maxRetries?: number;
+    /** Inject a custom fetch (tests, proxies, non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+    /** Extra headers sent on every request. */
+    defaultHeaders?: Record<string, string>;
+}
+interface RequestOptions {
+    method: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+    /** Override retry behaviour for a single call (e.g. non-idempotent POST). */
+    idempotent?: boolean;
+}
+/**
+ * Thin transport: auth header, JSON encode/decode, typed errors, and bounded
+ * retry with exponential backoff on transient failures. No dependencies —
+ * uses the runtime's global `fetch` (Node 18+, Bun, Deno, browsers, edge).
+ */
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    constructor(options?: MaritimeClientOptions);
+    private buildUrl;
+    request<T>(opts: RequestOptions): Promise<T>;
+    private backoff;
+    private parseBody;
+    private safeDetail;
+}
+
+/** Framework/template ids accepted by Maritime. Any string is allowed (the API
+ * is the source of truth) but these are the common ones with editor help. */
+type Template = 'openclaw' | 'openclaw_identity' | 'openclaw_browser' | 'maritime' | 'hermes' | 'hermes_identity' | 'zeroclaw' | (string & {});
+type Tier = 'smart' | 'extended' | 'always_on';
+type AgentStatus = 'sleeping' | 'active' | 'deploying' | 'error' | 'stopped';
+/** One env var to seed at create time. */
+interface EnvVarInput {
+    key: string;
+    value: string;
+    /** Encrypt at rest + mask in reads. Defaults to true. */
+    secret?: boolean;
+}
+interface CreateAgentParams {
+    /** Unique (per account) agent name. */
+    name: string;
+    /** Template/framework. Strongly recommended — a bare framework yields a broken
+     * placeholder image. Defaults to `openclaw` in {@link AgentsResource.provision}. */
+    template?: Template;
+    /** Your own id for this agent (e.g. your end-customer id). Filterable later. */
+    externalId?: string;
+    description?: string;
+    /** Plain-English persona / system prompt. */
+    instructions?: string;
+    tier?: Tier;
+    /** Seed env vars (API keys, config). Secrets are encrypted at rest. */
+    env?: EnvVarInput[];
+    /** Per-agent resource overrides (else the tier default applies). */
+    memMb?: number;
+    vcpus?: number;
+    /** Idle seconds before auto-sleep. 0 = always-on. */
+    idleTtlSeconds?: number;
+    diskGb?: number;
+    /** GitHub repo to build from instead of a template image. */
+    githubRepo?: string;
+    /** Explicit Docker image (advanced; usually use `template`). */
+    imageName?: string;
+}
+interface Agent {
+    id: string;
+    name: string;
+    description: string | null;
+    externalId: string | null;
+    framework: string;
+    tier: Tier;
+    status: AgentStatus;
+    publicUrl?: string | null;
+    invocationCount: number;
+    totalComputeSeconds: number;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+interface EnvVar {
+    key: string;
+    value: string;
+    isSecret: boolean;
+}
+interface LogEntry {
+    id: string;
+    level: string;
+    message: string;
+    source?: string | null;
+    timestamp: string | null;
+}
+interface ChatResult {
+    /** The agent's reply, or null if delivery failed (see `error`). */
+    response: string | null;
+    error?: string;
+}
+interface ListAgentsParams {
+    /** Exact-match filter on the caller-supplied external id. */
+    externalId?: string;
+    /** Exact-match filter on agent name. */
+    name?: string;
+}
+interface ChatOptions {
+    conversationId?: string;
+}
+type ApiKeyScope = 'provision' | 'deploy' | 'secrets' | 'manage' | (string & {});
+interface CreateApiKeyParams {
+    name: string;
+    /** Defaults to a full-access key. Pass a narrower set to restrict it. */
+    scopes?: ApiKeyScope[];
+    /** Expiry in days from now. Omit for a non-expiring key. */
+    expiresInDays?: number;
+}
+interface ApiKey {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    scopes: string[];
+    isActive: boolean;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+}
+interface CreatedApiKey extends ApiKey {
+    /** The full key — shown once. Store it now. */
+    rawKey: string;
+}
+
+/** Operations on Maritime agents. Access via `maritime.agents`. */
+declare class AgentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Create a new agent and kick off its deploy. */
+    create(params: CreateAgentParams): Promise<Agent>;
+    /**
+     * Get-or-create an agent by `externalId` — the idempotent entry point for a
+     * "one agent per end-customer" flow. If an agent with that external id
+     * already exists it is returned; otherwise a new one is created. Safe to call
+     * on every sign-in.
+     */
+    provision(params: CreateAgentParams & {
+        externalId: string;
+    }): Promise<Agent>;
+    /** Fetch a single agent by id. */
+    get(agentId: string): Promise<Agent>;
+    /** List agents, optionally filtered by `externalId` or `name`. */
+    list(params?: ListAgentsParams): Promise<Agent[]>;
+    /**
+     * Send a message to an agent and wait for its reply. Sleeping serverless
+     * agents auto-wake. Returns `{ response }` (or `{ response: null, error }`
+     * if delivery failed — Maritime does not surface that as an HTTP error).
+     */
+    chat(agentId: string, message: string, opts?: ChatOptions): Promise<ChatResult>;
+    /** Start / wake an agent. */
+    start(agentId: string): Promise<Agent>;
+    /** Stop an agent (container stopped, state preserved). */
+    stop(agentId: string): Promise<Agent>;
+    /** Put an agent to sleep (serverless snapshot; cheapest resting state). */
+    sleep(agentId: string): Promise<Agent>;
+    /** Restart an agent. */
+    restart(agentId: string): Promise<Agent>;
+    /** Delete an agent and all its resources (container, volume, network). */
+    delete(agentId: string): Promise<void>;
+    /** List an agent's env vars (secret values are masked). */
+    listEnv(agentId: string): Promise<EnvVar[]>;
+    /**
+     * Set (upsert) an env var. Secrets are encrypted at rest. Changes reach a
+     * running container after {@link reloadEnv} or a restart.
+     */
+    setEnv(agentId: string, key: string, value: string, opts?: {
+        secret?: boolean;
+    }): Promise<EnvVar>;
+    /** Delete an env var. */
+    deleteEnv(agentId: string, key: string): Promise<void>;
+    /** Hot-reload env vars into the running container (falls back to restart). */
+    reloadEnv(agentId: string): Promise<Agent>;
+    /** Fetch recent log entries for an agent. */
+    logs(agentId: string, opts?: {
+        limit?: number;
+        level?: string;
+    }): Promise<LogEntry[]>;
+    private lifecycle;
+}
+
+/**
+ * Manage API keys (`mk_...`) programmatically. Access via `maritime.keys`.
+ *
+ * Minting a key requires the caller's own key to carry the `manage` scope (or
+ * be a dashboard session). Hand a narrower-scoped key to a subsystem that only
+ * needs part of the surface — e.g. a `deploy`-scoped key for a worker that only
+ * chats to agents.
+ */
+declare class KeysResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Mint a new key. The raw key is returned once — store it immediately. */
+    create(params: CreateApiKeyParams): Promise<CreatedApiKey>;
+    /** List the caller's keys (raw values are never returned again). */
+    list(): Promise<ApiKey[]>;
+    /** Revoke a key by id. */
+    revoke(keyId: string): Promise<void>;
+}
+
+/** Base class for every error the SDK throws. Catch this to catch them all. */
+declare class MaritimeError extends Error {
+    constructor(message: string);
+}
+/** The request never reached Maritime (DNS, connection refused, timeout, …). */
+declare class MaritimeConnectionError extends MaritimeError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/** Maritime returned a non-2xx response. Subclassed by status below. */
+declare class MaritimeAPIError extends MaritimeError {
+    readonly status: number;
+    readonly detail: string;
+    /** Value of the `x-request-id` response header, when present. */
+    readonly requestId?: string;
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 401 / 403 — bad or insufficiently-scoped API key. */
+declare class MaritimeAuthError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 402 — the account wallet needs funding before this action can proceed. */
+declare class MaritimePaymentRequiredError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 404 — the agent (or other resource) does not exist or is not yours. */
+declare class MaritimeNotFoundError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 409 — a uniqueness conflict (e.g. an agent with that name already exists). */
+declare class MaritimeConflictError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+/** 429 — rate limited. */
+declare class MaritimeRateLimitError extends MaritimeAPIError {
+    constructor(status: number, detail: string, requestId?: string);
+}
+
+/**
+ * The Maritime client. Provision and drive AI agents on Maritime's serverless
+ * infrastructure from your own backend.
+ *
+ * ```ts
+ * import { Maritime } from 'maritime-sdk'
+ *
+ * const maritime = new Maritime({ apiKey: process.env.MARITIME_API_KEY })
+ *
+ * // When YOUR user signs up, give them their own agent (idempotent):
+ * const agent = await maritime.agents.provision({
+ *   externalId: `customer_${userId}`,
+ *   name: `assistant-${userId}`,
+ *   template: 'openclaw',
+ * })
+ *
+ * const { response } = await maritime.agents.chat(agent.id, 'Hello!')
+ * ```
+ */
+declare class Maritime {
+    readonly agents: AgentsResource;
+    readonly keys: KeysResource;
+    /** The underlying transport — escape hatch for endpoints not yet wrapped. */
+    readonly http: HttpClient;
+    constructor(options?: MaritimeClientOptions);
+}
+
+export { type Agent, type AgentStatus, type ApiKey, type ApiKeyScope, type ChatOptions, type ChatResult, type CreateAgentParams, type CreateApiKeyParams, type CreatedApiKey, type EnvVar, type EnvVarInput, type ListAgentsParams, type LogEntry, Maritime, MaritimeAPIError, MaritimeAuthError, type MaritimeClientOptions, MaritimeConflictError, MaritimeConnectionError, MaritimeError, MaritimeNotFoundError, MaritimePaymentRequiredError, MaritimeRateLimitError, type Template, type Tier, Maritime as default };