@jettson/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,464 @@
+// src/errors.ts
+var JettsonError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "JettsonError";
+    this.code = opts.code;
+    this.status = opts.status;
+    this.details = opts.details;
+  }
+};
+var JettsonAuthError = class extends JettsonError {
+  constructor(opts) {
+    super({ ...opts, status: 401 });
+    this.name = "JettsonAuthError";
+  }
+};
+var JettsonRateLimitError = class extends JettsonError {
+  retryAfterSeconds;
+  constructor(opts) {
+    super({ ...opts, status: 429 });
+    this.name = "JettsonRateLimitError";
+    this.retryAfterSeconds = opts.retryAfterSeconds;
+  }
+};
+var JettsonQuotaExceededError = class extends JettsonError {
+  used;
+  limit;
+  plan;
+  constructor(opts) {
+    super({ ...opts, status: 402 });
+    this.name = "JettsonQuotaExceededError";
+    this.used = opts.used;
+    this.limit = opts.limit;
+    this.plan = opts.plan;
+  }
+};
+var JettsonValidationError = class extends JettsonError {
+  constructor(opts) {
+    super({ ...opts, status: 400 });
+    this.name = "JettsonValidationError";
+  }
+};
+var JettsonNotFoundError = class extends JettsonError {
+  constructor(opts) {
+    super({ ...opts, status: 404 });
+    this.name = "JettsonNotFoundError";
+  }
+};
+var JettsonServerError = class extends JettsonError {
+  constructor(opts) {
+    super(opts);
+    this.name = "JettsonServerError";
+  }
+};
+var JettsonNetworkError = class extends JettsonError {
+  constructor(message) {
+    super({ message, code: "network_error", status: 0 });
+    this.name = "JettsonNetworkError";
+  }
+};
+var AgentTimeoutError = class extends JettsonError {
+  agentId;
+  elapsedMs;
+  constructor(agentId, elapsedMs) {
+    super({
+      message: `Agent ${agentId} did not reach a terminal state within ${elapsedMs}ms.`,
+      code: "agent_timeout",
+      status: 0
+    });
+    this.name = "AgentTimeoutError";
+    this.agentId = agentId;
+    this.elapsedMs = elapsedMs;
+  }
+};
+function errorFromResponse(input) {
+  const status = input.status;
+  const code = input.body?.error?.code ?? "unknown_error";
+  const message = input.body?.error?.message ?? `Request failed with status ${status}`;
+  const details = input.body?.error?.details;
+  if (status === 402) {
+    return new JettsonQuotaExceededError({
+      message,
+      code,
+      used: numField(details, "used") ?? 0,
+      limit: numField(details, "limit") ?? numField(details, "limitHours") ?? 0,
+      plan: strField(details, "plan") ?? "unknown",
+      details
+    });
+  }
+  if (status === 401) return new JettsonAuthError({ message, code, details });
+  if (status === 404) return new JettsonNotFoundError({ message, code, details });
+  if (status === 400 || status === 422) {
+    return new JettsonValidationError({ message, code, details });
+  }
+  if (status === 429) {
+    const retryAfter = parseRetryAfter(input.retryAfterHeader, details);
+    return new JettsonRateLimitError({
+      message,
+      code,
+      retryAfterSeconds: retryAfter,
+      details
+    });
+  }
+  if (status >= 500) {
+    return new JettsonServerError({ message, code, status, details });
+  }
+  return new JettsonError({ message, code, status, details });
+}
+function parseRetryAfter(header, details) {
+  if (header) {
+    const n = Number.parseInt(header, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  const detail = numField(details, "retryAfterSeconds");
+  return detail ?? 1;
+}
+function numField(obj, key) {
+  const v = obj?.[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function strField(obj, key) {
+  const v = obj?.[key];
+  return typeof v === "string" ? v : null;
+}
+
+// src/agents.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "error",
+  "stopped"
+]);
+var AgentsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Spawn a new agent. Returns immediately with `status: "spawning"`.
+   * Use `wait()` to block until the agent finishes.
+   */
+  async spawn(input) {
+    const body = { task: input.task };
+    if (input.name !== void 0) body.name = input.name;
+    if (input.region !== void 0) body.region = input.region;
+    if (input.metadata !== void 0) body.metadata = input.metadata;
+    return this.http.request({
+      method: "POST",
+      path: "/agents",
+      body,
+      idempotencyKey: input.idempotencyKey
+    });
+  }
+  /** Fetch one agent by ID. */
+  async get(agentId) {
+    return this.http.request({
+      method: "GET",
+      path: `/agents/${encodeURIComponent(agentId)}`
+    });
+  }
+  /** Paginated list of the caller's agents, newest first. */
+  async list(input = {}) {
+    return this.http.request({
+      method: "GET",
+      path: "/agents",
+      query: { limit: input.limit, cursor: input.cursor }
+    });
+  }
+  /**
+   * Cancel a running agent. Idempotent — terminal agents return 200
+   * unchanged.
+   */
+  async cancel(agentId) {
+    await this.http.request({
+      method: "DELETE",
+      path: `/agents/${encodeURIComponent(agentId)}`
+    });
+  }
+  /**
+   * Poll `get(agentId)` until the agent reaches a terminal status, with
+   * gentle exponential backoff. Throws `AgentTimeoutError` if the
+   * deadline lapses.
+   */
+  async wait(agentId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5 * 60 * 1e3;
+    const initialInterval = opts.pollIntervalMs ?? 1e3;
+    const maxInterval = opts.maxPollIntervalMs ?? 5e3;
+    const deadline = Date.now() + timeoutMs;
+    let interval = initialInterval;
+    while (true) {
+      const agent = await this.get(agentId);
+      if (TERMINAL_STATUSES.has(agent.status)) return agent;
+      if (Date.now() >= deadline) {
+        throw new AgentTimeoutError(agentId, timeoutMs);
+      }
+      const remaining = deadline - Date.now();
+      const sleepMs = Math.max(0, Math.min(interval, remaining));
+      await sleep(sleepMs);
+      interval = Math.min(Math.round(interval * 1.5), maxInterval);
+    }
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/http.ts
+var SDK_VERSION = "0.1.0";
+var HttpClient = class {
+  apiKey;
+  baseUrl;
+  maxRetries;
+  initialBackoffMs;
+  constructor(opts) {
+    if (!opts.apiKey) {
+      throw new JettsonError({
+        message: "Missing `apiKey` \u2014 pass one when constructing `new Jettson()`.",
+        code: "missing_api_key",
+        status: 0
+      });
+    }
+    this.apiKey = opts.apiKey;
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.maxRetries = opts.maxRetries ?? 3;
+    this.initialBackoffMs = opts.initialBackoffMs ?? 1e3;
+  }
+  async request(req) {
+    const url = this.buildUrl(req.path, req.query);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "User-Agent": `jettson-node/${SDK_VERSION}`,
+      Accept: "application/json"
+    };
+    if (req.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (req.idempotencyKey) {
+      headers["X-Idempotency-Key"] = req.idempotencyKey;
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      let res;
+      try {
+        res = await fetch(url, {
+          method: req.method,
+          headers,
+          body: req.body !== void 0 ? JSON.stringify(req.body) : void 0
+        });
+      } catch (err) {
+        lastError = new JettsonNetworkError(
+          err instanceof Error ? err.message : "Network request failed"
+        );
+        if (attempt === 0 && this.maxRetries > 0) {
+          await sleep2(this.initialBackoffMs);
+          continue;
+        }
+        throw lastError;
+      }
+      if (res.ok) {
+        if (res.status === 204) return void 0;
+        const text = await res.text();
+        if (text.length === 0) return void 0;
+        try {
+          return JSON.parse(text);
+        } catch {
+          throw new JettsonError({
+            message: "Server returned malformed JSON.",
+            code: "invalid_response",
+            status: res.status
+          });
+        }
+      }
+      const body = await safeJson(res);
+      const error = errorFromResponse({
+        status: res.status,
+        body,
+        retryAfterHeader: res.headers.get("retry-after")
+      });
+      lastError = error;
+      const retryable = res.status === 429 && attempt < this.maxRetries || res.status >= 500 && attempt < this.maxRetries;
+      if (!retryable) throw error;
+      const delayMs = res.status === 429 ? Math.max(1, "retryAfterSeconds" in error ? error.retryAfterSeconds : 1) * 1e3 : this.initialBackoffMs * 2 ** attempt;
+      await sleep2(delayMs);
+    }
+    throw lastError ?? new JettsonError({
+      message: "Request failed after retries.",
+      code: "max_retries_exceeded",
+      status: 0
+    });
+  }
+  buildUrl(path, query) {
+    const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    if (!query) return url;
+    const search = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v === void 0 || v === null) continue;
+      search.append(k, String(v));
+    }
+    const qs = search.toString();
+    return qs.length === 0 ? url : `${url}?${qs}`;
+  }
+};
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function safeJson(res) {
+  try {
+    const text = await res.text();
+    if (text.length === 0) return null;
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+// src/memory.ts
+var MemoryResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async put(input) {
+    const body = {
+      key: input.key,
+      value: input.value
+    };
+    if (input.namespace !== void 0) body.namespace = input.namespace;
+    if (input.tags !== void 0) body.tags = input.tags;
+    if (input.importance !== void 0) body.importance = input.importance;
+    if (input.expiresInDays !== void 0) {
+      body.expires_in_days = input.expiresInDays;
+    }
+    return this.http.request({
+      method: "POST",
+      path: "/memory",
+      body
+    });
+  }
+  /** Returns `null` (not an error) when no memory matches. */
+  async get(key, opts = {}) {
+    try {
+      return await this.http.request({
+        method: "GET",
+        path: "/memory",
+        query: { key, namespace: opts.namespace }
+      });
+    } catch (err) {
+      if (err?.status === 404) return null;
+      throw err;
+    }
+  }
+  async delete(key, opts = {}) {
+    await this.http.request({
+      method: "DELETE",
+      path: "/memory",
+      query: {
+        key,
+        namespace: opts.namespace,
+        hard: opts.hardDelete ? "true" : void 0
+      }
+    });
+  }
+  async search(input) {
+    const body = { query: input.query };
+    if (input.namespace !== void 0) body.namespace = input.namespace;
+    if (input.tags !== void 0) body.tags = input.tags;
+    if (input.limit !== void 0) body.limit = input.limit;
+    if (input.mode !== void 0) body.mode = input.mode;
+    if (input.minScore !== void 0) body.min_score = input.minScore;
+    const res = await this.http.request({
+      method: "POST",
+      path: "/memory/search",
+      body
+    });
+    return res.results;
+  }
+  async list(input = {}) {
+    const res = await this.http.request({
+      method: "GET",
+      path: "/memory/list",
+      query: {
+        namespace: input.namespace,
+        tags: input.tags?.join(","),
+        limit: input.limit
+      }
+    });
+    return res.memories;
+  }
+  async dedupe(input = {}) {
+    const body = {};
+    if (input.namespace !== void 0) body.namespace = input.namespace;
+    if (input.similarityThreshold !== void 0) {
+      body.threshold = input.similarityThreshold;
+    }
+    if (input.dryRun !== void 0) body.dry_run = input.dryRun;
+    return this.http.request({
+      method: "POST",
+      path: "/memory/dedupe",
+      body
+    });
+  }
+  async consolidate(input = {}) {
+    const body = {};
+    if (input.namespace !== void 0) body.namespace = input.namespace;
+    if (input.minClusterSize !== void 0) {
+      body.min_cluster_size = input.minClusterSize;
+    }
+    if (input.threshold !== void 0) body.threshold = input.threshold;
+    return this.http.request({
+      method: "POST",
+      path: "/memory/consolidate",
+      body
+    });
+  }
+  async namespaces() {
+    const res = await this.http.request({
+      method: "GET",
+      path: "/memory/namespaces"
+    });
+    return res.namespaces;
+  }
+  async export() {
+    return this.http.request({
+      method: "GET",
+      path: "/memory/export"
+    });
+  }
+  async import(memories) {
+    return this.http.request({
+      method: "POST",
+      path: "/memory/import",
+      body: { memories }
+    });
+  }
+};
+
+// src/index.ts
+var Jettson = class {
+  agents;
+  memory;
+  constructor(options) {
+    const http = new HttpClient({
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl ?? "https://jettson.dev/api/v1",
+      maxRetries: options.maxRetries
+    });
+    this.agents = new AgentsResource(http);
+    this.memory = new MemoryResource(http);
+  }
+};
+export {
+  AgentTimeoutError,
+  Jettson,
+  JettsonAuthError,
+  JettsonError,
+  JettsonNetworkError,
+  JettsonNotFoundError,
+  JettsonQuotaExceededError,
+  JettsonRateLimitError,
+  JettsonServerError,
+  JettsonValidationError
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@jettson/sdk",
+  "version": "0.1.0",
+  "description": "Official Jettson SDK for Node.js — build AI agents in 3 lines of code.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --target node18",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "jettson",
+    "ai",
+    "agents",
+    "automation",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jettsondev/jettson-sdk-node.git"
+  },
+  "homepage": "https://jettson.dev/docs/sdks/node",
+  "bugs": {
+    "url": "https://github.com/jettsondev/jettson-sdk-node/issues"
+  },
+  "license": "MIT",
+  "author": "Jettson",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}