@runnee/sdk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — Unreleased
+
+Explicit API-key constructor arguments are supported; existing configuration remains compatible.
+
+Initial remote-only Runnee Cloud client: execution, retained history, saved scripts and versions, encrypted secret management, usage, sandbox limits, public plan/health information and scoped telemetry. Includes typed errors, bounded responses, timeouts, cancellation, safe retries and pagination.
+
+No package has been published by this implementation. API-key issuance, account management, payment mutations and remote cancellation remain unavailable to SDK API keys.

package/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thank you for contributing to the official Runnee Cloud SDK. This repository contains the remote API client only. Keep runtime, infrastructure and customer data out of changes.
+
+## Local checks
+
+Use Node.js 22 or 24.
+
+```sh
+npm ci
+npm run build
+npm test
+npm run typecheck
+npm run format:check
+npx tsc --noEmit --strict --target es2022 --module nodenext tests/types.mts
+npm pack --dry-run
+```
+
+Also run `bun test tests/client.test.mjs` with Bun.
+
+## Pull requests
+
+Add regression coverage for behavior changes. Keep public names compatible and document changes in CHANGELOG.md. Never commit real API keys, secret values, .env files or customer responses. Tests use synthetic keys and local HTTP mocks; they neither execute customer scripts nor require production credentials. Live API verification belongs in an isolated staging account.
+
+The checked-in openapi.json is the public API contract snapshot. Coordinate API changes with the platform maintainers, then update this snapshot, client types, validation and tests together. Do not add methods for unimplemented endpoints.
+
+## Releases and security
+
+Follow [RELEASING.md](RELEASING.md). Use semantic versioning; breaking public changes require a major release (during 0.x, a new minor release). Security reports follow [SECURITY.md](SECURITY.md), rather than public issue reports.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Runnee
+
+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

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @runnee/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official server-side JavaScript and TypeScript SDK for Runnee Cloud. Scripts execute remotely on Runnee infrastructure. This package contains no interpreter.
+
+## Installation
+
+Release candidate: these commands apply after publication. For local development run npm ci and npm run build from this repository.
+
+```sh
+npm install @runnee/sdk
+bun add @runnee/sdk
+pnpm add @runnee/sdk
+yarn add @runnee/sdk
+```
+
+Node.js 22+ and Bun with native fetch are supported. ESM and CommonJS exports include TypeScript declarations. Trusted server runtimes providing fetch, AbortController and Web Streams can inject fetch; browser pages are rejected to prevent exposing secret keys.
+
+## Quickstart
+
+Set RUNNEE_API_KEY on your server. Create a key with scripts:execute in the dashboard.
+
+```ts
+import { Runnee } from "@runnee/sdk";
+const runnee = new Runnee(process.env.RUNNEE_API_KEY!);
+const result = await runnee.execute({
+  code: "function main() { return 10 + 20; }",
+  mode: "dry-run",
+});
+if (result.success && result.executionResult) {
+  console.log(result.executionResult.returnValue);
+}
+```
+
+CommonJS: const { Runnee } = require("@runnee/sdk"); const runnee = new Runnee(process.env.RUNNEE_API_KEY). Next.js: use only in server routes/actions, never a client component. Express, Fastify, NestJS and Hono can reuse one server-side client.
+
+## Configuration and reliability
+
+new Runnee(apiKey, { baseURL: "https://api.runnee.cloud", timeout: 30000, maxRetries: 2, fetch })
+
+RUNNEE_BASE_URL is an optional environment fallback. baseURL is an origin; the SDK adds /api paths. HTTP is accepted for loopback tests, or through allowInsecureHTTP for explicit development only. No redirects are followed. timeout is in milliseconds and bounds the whole request, retries and backoff. RequestOptions supports signal, timeout, maxRetries, idempotencyKey and onResponse({status,requestId,rateLimitRemaining}).
+
+GET requests retry transient network errors and 429/500/502/503/504 up to two times. Backoff is exponential with jitter and respects Retry-After. Authentication and permission errors are never retried. Writes default to no retries. Execute may retry only with an explicit idempotencyKey; use a business-operation key and retain it across uncertain results. Replays are receipts with originalResultOmitted, not cached output. Pending/conflicting claims produce HTTP409; inspect history. Keys expire after 24 hours, so do not treat them as permanent deduplication.
+
+AbortController cancels the client request, not guaranteed remote execution. Timeout or cancellation can happen after billing/admission. Do not submit a new key just because the connection ended.
+
+## API reference
+
+- execute(input, options?): code, mode, event (read as ctx.input), retainSource, scriptName, secretNames, scriptId.
+- executions.list({before,status,mode}?, options?), get(id, options?), iterate(filters?, options?): 20-item cursor pages, newest first; retained for 3 days with bounded history.
+- scripts.list/create/get/update/delete/getVersion/restore/storage. update requires expectedVersion and complete name/code; restore creates a new revision. List is bounded, not paginated.
+- secrets.list/get/create/update/delete: names identify secrets, values are write-only. create accepts {name,value,allowInline?,scriptIds?}; default policy denies all execution access. update accepts value and/or policy. Delete is irreversible.
+- usage.get/summary/history(7|30|90), sandbox.get, billing.plans, health.get.
+- telemetry.recordExecution(input), telemetry.recordEvent(input). External execution records consume quota. Do not send secrets in telemetry.
+
+See openapi.json for exact wire schemas and generated src/types.ts for all types. API-key issuance/revocation, account management, payment mutations and execution cancellation are session-only or unsupported; there are no fictional SDK methods for them.
+
+## Secrets
+
+```ts
+await runnee.secrets.create({ name: "EXTERNAL_API_KEY", value: process.env.EXTERNAL_API_KEY!, allowInline: true });
+const result = await runnee.execute({
+  code: 'use("secrets"); function main() { return secrets.has("EXTERNAL_API_KEY"); }',
+  secretNames: ["EXTERNAL_API_KEY"],
+});
+await runnee.secrets.update("EXTERNAL_API_KEY", { value: process.env.REPLACEMENT_API_KEY! });
+await runnee.secrets.delete("EXTERNAL_API_KEY");
+```
+
+Use secrets:write for management, secrets:read for metadata and scripts:execute plus secrets:use for execution grants. Prefer scriptIds over allowInline. Supply scriptId and the exact current saved source when executing a bound secret. No secret is injected automatically, including Dry run. Metadata never includes values. Review SECURITY.md for redaction boundaries.
+
+## Errors
+
+All exceptions extend RunneeError and expose status/requestId where available. Authentication, Permission, Validation, RateLimit, Timeout, Network, Server, Conflict, NotFound, Response and Cancelled errors have Runnee-prefixed classes. RunneeRateLimitError.retryAfter is seconds. A RunneeScript failure is a successful HTTP response with success:false and error; it does not throw an API exception.
+
+## Development
+
+npm install; npm run build; npm test; npm run typecheck; npm run format:check. CI checks Node22/24, Bun, ESM, CJS and TypeScript. Tests use synthetic credentials and controlled HTTP transports; run a separate staging API smoke check before release. See CONTRIBUTING.md, SECURITY.md and CHANGELOG.md. MIT licensed. npm publish requires explicit approval; see RELEASING.md.

package/RELEASING.md

@@ -0,0 +1,32 @@
+# Releasing
+
+This repository is prepared for public release but no registry publication is implied by its presence. Never publish before the matching API and secrets features have passed staging verification. The SDK does not deploy or configure the service.
+
+## GitHub setup (maintainer)
+
+Create an empty **public** repository named runnee-sdk-js under `Runnee-cloud` (or update all repository URLs first). From the prepared SDK folder:
+
+```sh
+git init -b main
+git add .
+git commit -m "Initial public SDK release"
+git remote add origin https://github.com/Runnee-cloud/runnee-sdk-js.git
+git push -u origin main
+```
+
+Review `git diff --cached` before committing. Never upload the parent application repository. Enable GitHub private vulnerability reporting, dependency alerts and branch protection. Create the `npm` GitHub Actions environment; restrict it to main and require a maintainer review if available for your account. The workflow only publishes when manually requested with publish=true on main. Ordinary pushes and tags run CI only. A manual run with publish=false builds downloadable artifacts without publishing.
+
+## Versioning
+
+Use semantic versioning. Update all version constants and CHANGELOG.md together. Search for the previous version in tracked files, including HTTP User-Agent strings; review the diff and regenerate distribution files. The workflow checks the expected version before building. Once published, treat versioned artifacts as immutable. After publication, tag the exact tested commit `vVERSION` and attach checksums and artifacts to a GitHub release.
+
+## npm
+
+1. Confirm you control the `@runnee` npm scope and that `@runnee/sdk` is available: `npm view @runnee/sdk`. A not-found response is not a reservation. If the scope is unavailable, rename the package, imports, lockfile and documentation consistently before publication.
+2. Run `npm ci`, `npm run build`, `npm test`, `npm run typecheck`, `npm run format:check` and `npm pack --dry-run`. Inspect the file list; only client output and public release documents belong in the package.
+3. For a new package, first authenticate locally with `npm login` using an authorized account with 2FA, then explicitly publish the inspected package: `npm publish --access public --provenance=false`. This is a manual first-release step; do not put login credentials into this repository.
+4. In npm package Settings → Trusted publishing, add GitHub Actions: owner `Runnee-cloud`, repository `runnee-sdk-js`, workflow `release.yml`, environment `npm`; allow publishing.
+5. Future releases: Actions → Release → Run workflow on main; enter the new expected version and select publish=true. The job uses Node 24 and npm 11 with OIDC/provenance, without an NPM_TOKEN.
+6. Verify installation into a clean project with `npm install @runnee/sdk@VERSION`, ESM import, CommonJS require and TypeScript declarations.
+
+See [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/).

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security policy
+
+Report vulnerabilities privately through GitHub private vulnerability reporting for the repository, when enabled. If unavailable, use the Runnee contact form and request a private security channel; do not post credentials or exploitable details publicly.
+
+API keys belong only on trusted servers. These SDKs execute code remotely and contain no interpreter. Requests use HTTPS by default, do not follow redirects, and do not log credentials or retain raw response bodies in exceptions. HTTP is limited to loopback unless explicitly enabled for development. Never disable TLS verification in production.
+
+Only the latest released minor version receives fixes while the SDK is pre-1.0. Dependencies should be patched promptly. Caller-provided transports are trusted code and must preserve authentication and TLS protections.
+
+Execution retries require an idempotency key. Receipt replays omit the original output, and a pending result is not evidence that execution failed. Client cancellation stops waiting; it does not guarantee remote cancellation.
+
+Secrets are encrypted by Runnee and granted explicitly to executions. Management returns metadata only. Do not put credentials in script source, events, telemetry, replies or errors. Redaction covers common accidental verbatim/encoded disclosure; it cannot stop an authorized malicious script from transforming or sending a secret to an external endpoint. Review secret-enabled scripts and narrow HTTP permissions. SDK request bodies necessarily contain values during create/rotate; configure application/APM instrumentation to omit them.