@jettson/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,380 @@
+interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    /** Max retries on 429 / 5xx. Total attempts = 1 + maxRetries. */
+    maxRetries?: number;
+    /** Initial backoff in ms for 5xx (doubles each retry). */
+    initialBackoffMs?: number;
+}
+interface RequestOptions {
+    method: "GET" | "POST" | "DELETE" | "PUT" | "PATCH";
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    idempotencyKey?: string;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly initialBackoffMs;
+    constructor(opts: HttpClientOptions);
+    request<T>(req: RequestOptions): Promise<T>;
+    private buildUrl;
+}
+
+/**
+ * Public types for the Jettson SDK. Every interface here mirrors a shape
+ * the Jettson API actually returns; we don't synthesize anything that the
+ * server doesn't ground-truth.
+ */
+type AgentStatus = "spawning" | "running" | "completed" | "error" | "stopped" | "idle";
+type Region = "iad" | "lhr" | "syd";
+type MemorySource = "manual" | "auto_extracted" | "consolidated";
+type MemorySearchMode = "hybrid" | "semantic" | "keyword";
+interface AgentProgressEntry {
+    ts: number;
+    kind: "info" | "tool_use" | "complete" | "error";
+    message: string;
+}
+interface Agent {
+    agent_id: string;
+    name: string;
+    status: AgentStatus;
+    task: string | null;
+    created_at: string;
+    updated_at?: string;
+    final_result: string | null;
+    progress?: AgentProgressEntry[];
+    error: string | null;
+    model: string;
+    container?: {
+        region: string;
+        status: string;
+    };
+    warm_hit?: boolean;
+    spawn_time_ms?: number;
+}
+interface AgentListResponse {
+    data: Agent[];
+    next_cursor: string | null;
+}
+interface Memory {
+    memory_id: string;
+    key: string;
+    namespace: string;
+    value: string;
+    tags: string[];
+    importance: number;
+    source: MemorySource;
+    access_count: number;
+    created_at: number;
+    updated_at: number;
+    expires_at?: number;
+}
+interface MemorySearchResult {
+    memory_id: string;
+    key: string;
+    namespace: string;
+    value: string;
+    tags: string[];
+    importance: number;
+    source: MemorySource;
+    score: number;
+    breakdown: {
+        semantic?: number;
+        keyword?: number;
+        importance?: number;
+        timeDecay?: number;
+    };
+    created_at: number;
+}
+interface NamespaceInfo {
+    namespace: string;
+    count: number;
+}
+interface DedupePair {
+    kept: string;
+    removed: string;
+    similarity: number;
+}
+interface DedupeResult {
+    removed: number;
+    kept: number;
+    pairs: DedupePair[];
+}
+interface ConsolidateSummary {
+    memory_id: string;
+    key: string;
+    namespace: string;
+    value: string;
+    tags: string[];
+    importance: number;
+}
+interface ConsolidateResult {
+    consolidated: number;
+    new_summaries: ConsolidateSummary[];
+}
+interface ImportResult {
+    imported: number;
+    failed: number;
+    errors: Array<{
+        index: number;
+        key: unknown;
+        reason: string;
+    }>;
+    partial?: boolean;
+}
+/** Subset of `Memory` accepted by `client.memory.import()`. */
+interface MemoryImportInput {
+    key: string;
+    value: string;
+    namespace?: string;
+    tags?: string[];
+    importance?: number;
+    expires_at?: number;
+}
+
+/**
+ * AgentsResource — every operation on the `/api/v1/agents` surface.
+ *
+ * The killer feature is `wait()`: spawn → wait → done in three lines.
+ * Polling is server-friendly: 1s → 1.5s → 2.25s → up to 5s ceiling.
+ */
+
+interface SpawnInput {
+    task: string;
+    name?: string;
+    region?: Region;
+    /** Forwarded to the agent's metadata (server reads `metadata.region` too). */
+    metadata?: Record<string, unknown>;
+    /**
+     * Optional client-provided idempotency key. If you retry a spawn with
+     * the same key inside a short window, the server returns the existing
+     * agent instead of creating a duplicate. (Server-side idempotency is
+     * advisory for now — Day 12 deploy adds the full enforcement.)
+     */
+    idempotencyKey?: string;
+}
+interface ListInput {
+    limit?: number;
+    cursor?: string;
+}
+interface WaitInput {
+    /** Max wall-clock to wait. Defaults to 5 minutes. */
+    timeoutMs?: number;
+    /** Initial poll interval. Backs off to `maxPollIntervalMs`. */
+    pollIntervalMs?: number;
+    /** Ceiling for backoff. Defaults to 5,000 ms. */
+    maxPollIntervalMs?: number;
+}
+declare class AgentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Spawn a new agent. Returns immediately with `status: "spawning"`.
+     * Use `wait()` to block until the agent finishes.
+     */
+    spawn(input: SpawnInput): Promise<Agent>;
+    /** Fetch one agent by ID. */
+    get(agentId: string): Promise<Agent>;
+    /** Paginated list of the caller's agents, newest first. */
+    list(input?: ListInput): Promise<AgentListResponse>;
+    /**
+     * Cancel a running agent. Idempotent — terminal agents return 200
+     * unchanged.
+     */
+    cancel(agentId: string): Promise<void>;
+    /**
+     * Poll `get(agentId)` until the agent reaches a terminal status, with
+     * gentle exponential backoff. Throws `AgentTimeoutError` if the
+     * deadline lapses.
+     */
+    wait(agentId: string, opts?: WaitInput): Promise<Agent>;
+}
+
+/**
+ * MemoryResource — every operation on the `/api/v1/memory` surface.
+ *
+ * Memory is user-scoped (all your agents share the same pool), with
+ * (key, namespace) as the natural identity. Hybrid search ranks by
+ * semantic similarity + keyword overlap + importance + time decay.
+ */
+
+interface MemoryPutInput {
+    key: string;
+    value: string;
+    namespace?: string;
+    tags?: string[];
+    importance?: number;
+    expiresInDays?: number;
+}
+interface MemoryGetOptions {
+    namespace?: string;
+}
+interface MemoryDeleteOptions {
+    namespace?: string;
+    /** Default soft-deletes. Set true for permanent removal. */
+    hardDelete?: boolean;
+}
+interface MemorySearchInput {
+    query: string;
+    namespace?: string;
+    tags?: string[];
+    limit?: number;
+    mode?: MemorySearchMode;
+    minScore?: number;
+}
+interface MemoryListInput {
+    namespace?: string;
+    tags?: string[];
+    limit?: number;
+}
+interface DedupeInput {
+    namespace?: string;
+    similarityThreshold?: number;
+    dryRun?: boolean;
+}
+interface ConsolidateInput {
+    namespace?: string;
+    minClusterSize?: number;
+    threshold?: number;
+}
+declare class MemoryResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    put(input: MemoryPutInput): Promise<Memory>;
+    /** Returns `null` (not an error) when no memory matches. */
+    get(key: string, opts?: MemoryGetOptions): Promise<Memory | null>;
+    delete(key: string, opts?: MemoryDeleteOptions): Promise<void>;
+    search(input: MemorySearchInput): Promise<MemorySearchResult[]>;
+    list(input?: MemoryListInput): Promise<Memory[]>;
+    dedupe(input?: DedupeInput): Promise<DedupeResult>;
+    consolidate(input?: ConsolidateInput): Promise<ConsolidateResult>;
+    namespaces(): Promise<NamespaceInfo[]>;
+    export(): Promise<{
+        version: number;
+        exported_at: number;
+        count: number;
+        memories: Memory[];
+    }>;
+    import(memories: MemoryImportInput[]): Promise<ImportResult>;
+}
+
+/**
+ * SDK error hierarchy.
+ *
+ * Every HTTP failure response from Jettson lands as one of these. The
+ * server's `{ error: { code, message, details } }` envelope maps to
+ * specific subclasses based on HTTP status + the `code` field — so
+ * callers can `catch (e) { if (e instanceof JettsonRateLimitError) ... }`
+ * without parsing the response body.
+ *
+ * `details` carries the structured context the API surfaces (e.g.
+ * `{ used, limit, plan }` on quota errors). It's typed loosely on the
+ * base class because each subclass narrows the useful fields.
+ */
+declare class JettsonError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(opts: {
+        message: string;
+        code: string;
+        status: number;
+        details?: Record<string, unknown>;
+    });
+}
+/** HTTP 401 — missing, expired, or revoked API key. */
+declare class JettsonAuthError extends JettsonError {
+    constructor(opts: {
+        message: string;
+        code: string;
+        details?: Record<string, unknown>;
+    });
+}
+/** HTTP 429 — per-key spawn rate cap exceeded. */
+declare class JettsonRateLimitError extends JettsonError {
+    readonly retryAfterSeconds: number;
+    constructor(opts: {
+        message: string;
+        code: string;
+        retryAfterSeconds: number;
+        details?: Record<string, unknown>;
+    });
+}
+/** HTTP 402 — plan quota hit (memory pool, agent-hours, etc). */
+declare class JettsonQuotaExceededError extends JettsonError {
+    readonly used: number;
+    readonly limit: number;
+    readonly plan: string;
+    constructor(opts: {
+        message: string;
+        code: string;
+        used: number;
+        limit: number;
+        plan: string;
+        details?: Record<string, unknown>;
+    });
+}
+/** HTTP 400 — body or query failed validation. */
+declare class JettsonValidationError extends JettsonError {
+    constructor(opts: {
+        message: string;
+        code: string;
+        details?: Record<string, unknown>;
+    });
+}
+/** HTTP 404 — resource doesn't exist (or doesn't belong to the caller). */
+declare class JettsonNotFoundError extends JettsonError {
+    constructor(opts: {
+        message: string;
+        code: string;
+        details?: Record<string, unknown>;
+    });
+}
+/** HTTP 5xx — transient server-side issue. SDK retries automatically. */
+declare class JettsonServerError extends JettsonError {
+    constructor(opts: {
+        message: string;
+        code: string;
+        status: number;
+        details?: Record<string, unknown>;
+    });
+}
+/** Network connection failure — could not reach the API at all. */
+declare class JettsonNetworkError extends JettsonError {
+    constructor(message: string);
+}
+/** `agents.wait()` timed out without reaching a terminal status. */
+declare class AgentTimeoutError extends JettsonError {
+    readonly agentId: string;
+    readonly elapsedMs: number;
+    constructor(agentId: string, elapsedMs: number);
+}
+
+/**
+ * Jettson SDK for Node.js — top-level export.
+ *
+ * Build AI agents in 3 lines:
+ *
+ *     const j = new Jettson({ apiKey: process.env.JETTSON_API_KEY! });
+ *     const a = await j.agents.spawn({ task: "Research linear.app" });
+ *     const r = await j.agents.wait(a.agent_id);
+ */
+
+interface JettsonOptions {
+    /** Your Jettson API key (begins with `jett_sk_live_…`). Required. */
+    apiKey: string;
+    /** Override the API base URL — useful for testing against localhost. */
+    baseUrl?: string;
+    /** Max automatic retries on 429 + 5xx. Defaults to 3. */
+    maxRetries?: number;
+}
+declare class Jettson {
+    readonly agents: AgentsResource;
+    readonly memory: MemoryResource;
+    constructor(options: JettsonOptions);
+}
+
+export { type Agent, type AgentListResponse, type AgentProgressEntry, type AgentStatus, AgentTimeoutError, AgentsResource, type ConsolidateInput, type ConsolidateResult, type ConsolidateSummary, type DedupeInput, type DedupePair, type DedupeResult, type ImportResult, Jettson, JettsonAuthError, JettsonError, JettsonNetworkError, JettsonNotFoundError, type JettsonOptions, JettsonQuotaExceededError, JettsonRateLimitError, JettsonServerError, JettsonValidationError, type ListInput, type Memory, type MemoryDeleteOptions, type MemoryGetOptions, type MemoryImportInput, type MemoryListInput, type MemoryPutInput, MemoryResource, type MemorySearchInput, type MemorySearchMode, type MemorySearchResult, type MemorySource, type NamespaceInfo, type Region, type SpawnInput, type WaitInput };