@llmsafespaces/sdk 0.5.2

package/README.md

@@ -0,0 +1,113 @@
+# @llmsafespaces/sdk
+
+TypeScript SDK for the LLMSafeSpaces API. Zero runtime dependencies — uses native `fetch`.
+
+## Installation
+
+```bash
+npm install @llmsafespaces/sdk
+```
+
+## Quick Start
+
+```typescript
+import { LLMSafeSpaces } from '@llmsafespaces/sdk';
+
+const client = new LLMSafeSpaces({
+  baseUrl: 'https://llmsafespaces.example.com',
+  apiKey: 'lsp_your_api_key',
+});
+
+// Create a workspace and send a message
+const workspace = await client.workspaces.create({ name: 'my-project', runtime: 'python:3.11', storageSize: '10Gi' });
+const session = await client.sessions.ensure(workspace.id);
+const response = await client.sessions.sendMessage(workspace.id, session.sessionId, 'Write hello world in Python');
+console.log(response.content);
+```
+
+## Authentication
+
+```typescript
+// API key (recommended for programmatic use)
+const client = new LLMSafeSpaces({ baseUrl: '...', apiKey: 'lsp_...' });
+
+// Email/password (auto-manages JWT, refreshes on 401)
+const client = new LLMSafeSpaces({ baseUrl: '...', credentials: { email: '...', password: '...' } });
+```
+
+## Important: `sendMessage` Timeout
+
+`sendMessage` proxies to the LLM agent and blocks until it responds. This can take 30-120+ seconds. Default timeout is 120s. On timeout, a `TimeoutError` is thrown — the prompt may still be processing. Poll `getHistory` to check.
+
+```typescript
+import { TimeoutError } from '@llmsafespaces/sdk';
+
+try {
+  const resp = await client.sessions.sendMessage(wsId, sessId, 'complex prompt...');
+} catch (e) {
+  if (e instanceof TimeoutError) {
+    // Prompt may still be processing — check history later
+    const history = await client.sessions.getHistory(wsId, sessId);
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+import { NotFoundError, AuthError, ConflictError, LLMSafeSpacesError } from '@llmsafespaces/sdk';
+
+try {
+  await client.workspaces.get('nonexistent');
+} catch (e) {
+  if (e instanceof NotFoundError) { /* 404 */ }
+  if (e instanceof AuthError) { /* 401/403 */ }
+  if (e instanceof ConflictError) { /* 409 - e.g. workspace not active */ }
+  if (e instanceof LLMSafeSpacesError) { /* any API error: e.status, e.message */ }
+}
+```
+
+## API Reference
+
+### `client.workspaces`
+- `list(limit?, offset?)` — List workspaces
+- `create(req)` — Create workspace
+- `get(id)` — Get workspace
+- `rename(id, name)` — Rename workspace
+- `delete(id)` — Delete workspace
+- `getStatus(id)` — Get workspace status
+- `activate(id)` — Activate workspace (injects credentials, resumes from Suspended)
+- `suspend(id)` — Suspend workspace
+- `setBindings(id, secretIds)` — Set secret bindings
+- `setEnv(id, env)` — Set environment variables
+- `getEnv(id)` — Get environment variables
+
+### `client.sessions`
+- `ensure(workspaceId)` — Create session (activates workspace if needed)
+- `list(workspaceId)` — List sessions
+- `getActive(workspaceId)` — Get active sessions
+- `rename(workspaceId, sessionId, title)` — Rename session
+- `sendMessage(workspaceId, sessionId, content)` — Send message (sync, blocks)
+- `getHistory(workspaceId, sessionId)` — Get message history
+- `abort(workspaceId, sessionId)` — Abort current operation
+
+### `client.auth`
+- `me()` — Get current user
+- `listApiKeys()` — List API keys
+- `createApiKey(name)` — Create API key
+- `deleteApiKey(id)` — Delete API key
+
+### `client.secrets`
+- `create(req)` — Create secret
+- `list()` — List secrets
+- `get(id)` — Get secret
+- `delete(id)` — Delete secret
+- `reveal(id)` — Reveal secret value (audited)
+
+### `client.terminal`
+- `getTicket(workspaceId)` — Get one-time WebSocket terminal ticket
+
+## Requirements
+
+- Node.js 18+ or modern browser (native `fetch` required)
+- No runtime dependencies

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@llmsafespaces/sdk",
+  "version": "0.5.2",
+  "description": "TypeScript SDK for LLMSafeSpaces API",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "generate": "openapi-typescript ../../sdks/openapi.yaml -o src/generated/api.ts"
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.6.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "AGPL-3.0-or-later",
+  "dependencies": {
+    "node-fetch": "^2.7.0"
+  }
+}