roborama 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roborama
+
+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,63 @@
+# roborama
+
+Official TypeScript/JavaScript SDK for [Roborama](https://roborama.com) — real robots as an API. Statistically defensible evaluation of robot policies on physical hardware: every result carries `n` and a 95% confidence interval, everything is versioned (robots pin firmware, environments and suites pin revisions), and both meters (robot-hours × environment-hours) are visible in every quote.
+
+> **Status.** The API surface is a **stable draft** of [openapi.json](https://roborama.com/openapi.json); hosted execution is in **private preview**. This SDK ships a deterministic **mock mode** so you (and your agents) can integrate today — set `ROBORAMA_MOCK=1` and every call returns fixture-shaped results with honest statistics, no hardware and no API key required.
+
+```bash
+npm i roborama
+```
+
+## First call
+
+`new Roborama()` reads `ROBORAMA_API_KEY` (keys carry the `rbr_live_` prefix) from the environment; every method returns a promise; full type definitions ship for every request and result shape.
+
+```ts
+import Roborama from "roborama"; // reads ROBORAMA_API_KEY
+
+const roborama = new Roborama();
+
+const run = await roborama.runs.create({
+  robot: "g1-edu-pro@fw2.3", // embodiment @ pinned firmware
+  environment: "kitchen-std@v1.2", // versioned catalogue scene
+  policy: {
+    type: "checkpoint", // openpi / lerobot checkpoints,
+    hf: "acme/skill-v4", // containers, or hosted endpoints
+    runtime: "openpi",
+  },
+  task: "load_dishwasher@v2",
+  episodes: "auto(ci=0.95, moe=0.03)", // size n for ±3% at 95% — or an int
+  max_budget_usd: 4000, // hard stop, metered live
+});
+
+const result = await run.result();
+console.log(result);
+// { n: 612, success_rate: 0.874, ci95: [0.846, 0.898], cost_usd: 3812, ... }
+```
+
+## Mock mode — runnable today
+
+```bash
+ROBORAMA_MOCK=1 node your-script.mjs   # or: new Roborama({ mock: true })
+```
+
+Mock mode is deterministic and fixture-shaped: quote math follows the [public rate card](https://roborama.com/pricing), run results are shaped like the canonical runs, `max_budget_usd` hard stops throw a `RoboramaError` with `code === "budget_exceeded"` and an honest `partial_result`, and Wilson intervals are computed exactly as documented. The same code runs unchanged against the hosted API once you have a key.
+
+## The shape of the SDK
+
+`roborama.runs.create()` is the workhorse: its `kind` field selects the primitive — `run` (the default), `eval`, `verify`, `matrix`, `threshold`, `compare`, or `transfer` — mirroring `POST /v1/runs` exactly, with the return type narrowed per kind (a `compare` run has `.winner`; a `matrix` run has `.heatmap()`; a `threshold` contract has `.onVerified()`).
+
+- **Resources**: `roborama.robots.list()`, `roborama.environments.list({ cls })`, `roborama.suites`, `roborama.tasks` (create → `pilot()` → `amend()` → `freeze()`), `roborama.kits` (register → `shippingLabel()`), `roborama.streams.get(cell)`, `roborama.keys`, `roborama.budgets`, `roborama.data.purge()`, `roborama.calibration.export()`, `roborama.gates.create()`, plus `roborama.quote()` and `roborama.usage()` at the top level.
+- **Policies**: `Roborama.Policy.container({...})`, `.checkpoint({...})`, `.endpoint({...})` — or write the plain object; declared contracts are validated before any motor moves.
+- **Results**: `await run.result()` (n, rate, ci95, clusters, both meters), `await run.episodes()` (video, MCAP, replay spec), `for await (const e of run.watch())` (live SSE), `run.export({ format: "lerobot" })`, `run.report({ format: "pdf" })`.
+- **Errors**: one class, `RoboramaError`, with a `.code` from [the documented fixed set](https://roborama.com/docs/errors/) — switch on the code, not the message. `budget_exceeded` carries `err.partial_result`.
+
+Docs: [quickstart](https://roborama.com/docs/quickstart/) · [primitives](https://roborama.com/docs/primitives/run/) · [errors](https://roborama.com/docs/errors/) · [OpenAPI](https://roborama.com/openapi.json)
+
+## Requirements
+
+Node ≥ 18.17 (or any runtime with `fetch`). Zero runtime dependencies. Dual ESM + CJS build with full `.d.ts` types.
+
+## License
+
+MIT