@jettson/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jettson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# Jettson SDK for Node.js
+
+Build AI agents in 3 lines of code.
+
+```bash
+npm install @jettson/sdk
+```
+
+```ts
+import { Jettson } from "@jettson/sdk";
+
+const jettson = new Jettson({ apiKey: process.env.JETTSON_API_KEY! });
+
+const agent = await jettson.agents.spawn({
+  task: "Research linear.app and tell me what they do.",
+});
+const result = await jettson.agents.wait(agent.agent_id);
+
+console.log(result.final_result);
+```
+
+That's it. No vector database, no container orchestration, no agent loop you have to maintain.
+
+---
+
+## Installation
+
+Requires Node.js 18 or newer.
+
+```bash
+npm install @jettson/sdk
+# or
+pnpm add @jettson/sdk
+# or
+yarn add @jettson/sdk
+```
+
+The SDK has zero runtime dependencies — it uses native `fetch`.
+
+## Quickstart
+
+Get an API key at [jettson.dev/console/api-keys](https://jettson.dev/console/api-keys), then:
+
+```ts
+import { Jettson } from "@jettson/sdk";
+
+const jettson = new Jettson({ apiKey: process.env.JETTSON_API_KEY! });
+
+const agent = await jettson.agents.spawn({
+  task: "Browse https://news.ycombinator.com and return the top story title.",
+});
+
+// `wait` polls until completion with gentle exponential backoff.
+const result = await jettson.agents.wait(agent.agent_id);
+
+console.log(result.status);        // "completed"
+console.log(result.final_result);  // The agent's answer
+```
+
+## Authentication
+
+```ts
+new Jettson({
+  apiKey: "jett_sk_live_…",
+  baseUrl: "https://jettson.dev/api/v1",   // optional — this is the default
+  maxRetries: 3,                            // optional — retries on 429/5xx
+});
+```
+
+The API key is bearer-auth'd on every request. Store it in `process.env.JETTSON_API_KEY` (or your platform's secret store), never commit it.
+
+## Examples
+
+### Spawn → wait → use the result
+
+```ts
+const agent = await jettson.agents.spawn({
+  task: "Summarize the latest version of the OpenTelemetry spec in 3 bullets.",
+});
+const final = await jettson.agents.wait(agent.agent_id, {
+  timeoutMs: 5 * 60 * 1000,    // 5 minutes
+  pollIntervalMs: 1000,        // initial 1s, backs off to 5s
+});
+console.log(final.final_result);
+```
+
+### Spawn in a specific region
+
+Multi-region warm pool is live in `iad` (US East), `lhr` (Europe), and `syd` (Asia Pacific):
+
+```ts
+const agent = await jettson.agents.spawn({
+  task: "…",
+  region: "lhr",   // or pass `metadata: { region: "lhr" }`
+});
+```
+
+If you don't specify a region the server picks `iad`. The pool's hit rate per region is on the [Console overview](https://jettson.dev/console).
+
+### Cancel a running agent
+
+```ts
+await jettson.agents.cancel(agent.agent_id);
+```
+
+Idempotent — already-terminal agents return 200 unchanged.
+
+### Memory: write, search, recall
+
+Memory is user-scoped — every agent you spawn under the same account shares the same pool.
+
+```ts
+await jettson.memory.put({
+  key: "brand_color",
+  value: "Brand primary color is #FF5733",
+  namespace: "user_profile",
+  importance: 8,
+  tags: ["brand"],
+});
+
+const results = await jettson.memory.search({
+  query: "what color is the brand?",
+  namespace: "user_profile",
+  mode: "hybrid",   // 'hybrid' | 'semantic' | 'keyword'
+});
+
+for (const r of results) {
+  console.log(`${r.key}: ${r.value} (score=${r.score.toFixed(2)})`);
+}
+```
+
+### Idempotent spawn (defensive retries)
+
+If your code might retry a spawn because of a network blip on the way to Jettson, pass an idempotency key. The same key inside a short window returns the same agent instead of creating a duplicate.
+
+```ts
+const requestId = `spawn:${userId}:${Date.now()}`;
+await jettson.agents.spawn({
+  task: "…",
+  idempotencyKey: requestId,
+});
+```
+
+### List + paginate
+
+```ts
+let cursor: string | undefined;
+do {
+  const page = await jettson.agents.list({ limit: 50, cursor });
+  for (const a of page.data) {
+    console.log(a.agent_id, a.status);
+  }
+  cursor = page.next_cursor ?? undefined;
+} while (cursor);
+```
+
+## API Reference
+
+### `new Jettson(options)`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiKey` **(required)** | `string` | Your Jettson API key. |
+| `baseUrl` | `string` | Defaults to `https://jettson.dev/api/v1`. |
+| `maxRetries` | `number` | Retries on 429 / 5xx (default 3). |
+
+### `jettson.agents`
+
+| Method | Description |
+| --- | --- |
+| `spawn(input)` | POST `/agents`. Returns immediately with `status: "spawning"`. |
+| `get(agentId)` | GET `/agents/{id}`. |
+| `list(options?)` | Paginated `{ data, next_cursor }`. |
+| `cancel(agentId)` | DELETE `/agents/{id}`. Idempotent. |
+| `wait(agentId, options?)` | Poll until `completed` / `error` / `stopped`. Throws `AgentTimeoutError` on timeout. |
+
+### `jettson.memory`
+
+| Method | Description |
+| --- | --- |
+| `put(input)` | Create or version-update a memory. |
+| `get(key, options?)` | Returns the memory or `null` if not found. |
+| `delete(key, options?)` | Soft delete (pass `hardDelete: true` for permanent). |
+| `search(input)` | Hybrid semantic + keyword search. |
+| `list(options?)` | Newest-first, no ranking. |
+| `dedupe(options?)` | Soft-delete near-duplicates. |
+| `consolidate(options?)` | Cluster + summarize related memories. |
+| `namespaces()` | Per-namespace live-counts. |
+| `export()` | Dump every live memory. |
+| `import(memories)` | Bulk insert (round-trips with `export()`). |
+
+## Error handling
+
+Every HTTP failure surfaces as a typed error. All extend `JettsonError`.
+
+```ts
+import {
+  JettsonAuthError,
+  JettsonRateLimitError,
+  JettsonQuotaExceededError,
+  JettsonValidationError,
+  JettsonNotFoundError,
+  JettsonServerError,
+  JettsonNetworkError,
+  AgentTimeoutError,
+} from "@jettson/sdk";
+
+try {
+  await jettson.agents.spawn({ task: "…" });
+} catch (err) {
+  if (err instanceof JettsonRateLimitError) {
+    console.log(`Backing off ${err.retryAfterSeconds}s`);
+  } else if (err instanceof JettsonQuotaExceededError) {
+    console.log(`Hit quota: ${err.used}/${err.limit} on plan ${err.plan}`);
+  } else if (err instanceof JettsonAuthError) {
+    console.log("Bad API key.");
+  } else {
+    throw err;
+  }
+}
+```
+
+`memory.get()` is the one exception: instead of throwing on 404, it returns `null` (so the "lookup or fallback" pattern stays clean).
+
+## Retries and rate limits
+
+The HTTP client retries automatically:
+
+- **429** — waits the duration in `Retry-After`, then retries (up to `maxRetries`, default 3)
+- **5xx** — exponential backoff (1s → 2s → 4s), up to `maxRetries`
+- **Network failure** — one retry after the initial backoff window
+
+Disable retries with `new Jettson({ apiKey, maxRetries: 0 })` if you need first-failure semantics.
+
+## Development
+
+```bash
+git clone https://github.com/jettsondev/jettson-sdk-node
+cd jettson-sdk-node
+npm install
+npm run build
+npm test
+```
+
+The SDK is intentionally small (~1k LOC + tests). Read the source.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).