@phpsandbox/sdk 0.1.9 → 0.1.11

package/dist/schemas/publications.d.ts

@@ -54,11 +54,6 @@ export declare const PublicationJurisdictionSchema: z.ZodEnum<{
     eu: "eu";
     fedramp: "fedramp";
 }>;
-export declare const PublicationDomainDnsRecordTypeSchema: z.ZodEnum<{
-    CNAME: "CNAME";
-    ALIAS: "ALIAS";
-    ANAME: "ANAME";
-}>;
 export declare const PublicationProtectionModeSchema: z.ZodEnum<{
     none: "none";
     password: "password";
@@ -415,7 +410,6 @@ export type PublicationReleaseStatus = z.infer<typeof PublicationReleaseStatusSc
 export type PublicationSize = z.infer<typeof PublicationSizeSchema>;
 export type PublicationRegion = z.infer<typeof PublicationRegionSchema>;
 export type PublicationJurisdiction = z.infer<typeof PublicationJurisdictionSchema>;
-export type PublicationDomainDnsRecordType = z.infer<typeof PublicationDomainDnsRecordTypeSchema>;
 export type PublicationProtectionMode = z.infer<typeof PublicationProtectionModeSchema>;
 export type PublicationLogStream = z.infer<typeof PublicationLogStreamSchema>;
 export type PublicationEventData = z.infer<typeof PublicationEventDataSchema>;

package/dist/schemas/publications.js

@@ -47,7 +47,6 @@ export const PublicationRegionSchema = z.enum([
     'AFR',
 ]);
 export const PublicationJurisdictionSchema = z.enum(['eu', 'fedramp']);
-export const PublicationDomainDnsRecordTypeSchema = z.enum(['CNAME', 'ALIAS', 'ANAME']);
 export const PublicationProtectionModeSchema = z.enum(['none', 'password']);
 export const PublicationLogStreamSchema = z.enum(['build', 'runtime']);
 export const PublishStreamLogStreamSchema = z.enum(['build', 'publish', 'runtime']);

package/dist/servers.d.ts

@@ -21,13 +21,15 @@ export interface CreateServerInput {
     host: string;
     ssh?: ServerSshOptions;
 }
+export interface ServerListOptions {
+    page?: number;
+}
 export declare class ServerApi {
     private readonly client;
     constructor(client: Client);
-    list(): Promise<PaginatedApiResponse<ServerData>>;
+    list(options?: ServerListOptions): Promise<PaginatedApiResponse<ServerData>>;
     create(input: CreateServerInput): Promise<ServerInstance>;
     get(id: string): Promise<ServerInstance>;
-    delete(id: string): Promise<void>;
 }
 export declare class ServerInstance {
     readonly data: ServerData;

package/dist/servers.js

@@ -2,9 +2,9 @@ export class ServerApi {
     constructor(client) {
         this.client = client;
     }
-    async list() {
-        const response = await this.client.get('/servers');
-        return response.data;
+    async list(options = {}) {
+        const query = options.page === undefined ? '' : `?${new URLSearchParams({ page: String(options.page) }).toString()}`;
+        return this.client.get(`/servers${query}`);
     }
     async create(input) {
         const response = await this.client.post('/servers', input);
@@ -14,9 +14,6 @@ export class ServerApi {
         const response = await this.client.get(`/servers/${id}`);
         return new ServerInstance(response.data, this.client);
     }
-    async delete(id) {
-        await this.client.delete(`/servers/${id}`);
-    }
 }
 export class ServerInstance {
     constructor(data, client) {
@@ -26,8 +23,8 @@ export class ServerInstance {
     refresh() {
         return this.client.servers.get(this.data.id);
     }
-    delete() {
-        return this.client.servers.delete(this.data.id);
+    async delete() {
+        await this.client.delete(`/servers/${this.data.id}`);
     }
     async waitReady(options) {
         const timeout = options?.timeout ?? 300000; // 5 minutes default

package/dist/shell.d.ts

@@ -22,7 +22,7 @@ export interface ShellExecInput {
     opts?: Omit<SpawnOptions, 'abortSignal'>;
 }
 export interface ShellActions {
-    'shell.exec': Action<ShellExecInput, ProcessResultData>;
+    'shell.exec': Action<ShellExecInput, ProcessResult>;
     'shell.input': Action<{
         id: string;
         input: string;
@@ -31,24 +31,12 @@ export interface ShellActions {
         id: string;
     }, boolean>;
 }
-export interface ProcessResultData {
+export interface ProcessResult {
     output: string;
     stdout: string;
     stderr: string;
     exitCode: number;
 }
-export declare class CommandError extends Error {
-    readonly result: ProcessResult;
-    constructor(result: ProcessResult);
-}
-export declare class ProcessResult implements ProcessResultData {
-    readonly output: string;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly exitCode: number;
-    constructor(output: string, stdout: string, stderr: string, exitCode: number);
-    throw(): this;
-}
 export declare class ProcessReadable<T> {
     readonly stream: ReadableStream<T>;
     private controller;

package/dist/shell.js

@@ -7,26 +7,6 @@ function resolveRunInput(command, argsOrOpts = [], opts) {
         opts: { tty: false, ...resolvedOpts },
     };
 }
-export class CommandError extends Error {
-    constructor(result) {
-        super(result.output);
-        this.result = result;
-    }
-}
-export class ProcessResult {
-    constructor(output, stdout, stderr, exitCode) {
-        this.output = output;
-        this.stdout = stdout;
-        this.stderr = stderr;
-        this.exitCode = exitCode;
-    }
-    throw() {
-        if (this.exitCode !== 0) {
-            throw new CommandError(this);
-        }
-        return this;
-    }
-}
 export class ProcessReadable {
     constructor() {
         this.controller = null;
@@ -111,7 +91,7 @@ export class ShellProcess {
         const { abortSignal, ...payloadOpts } = opts;
         this.completion = this.okra.invoke('shell.exec', { command, opts: { ...payloadOpts, id: this.id } }, { abortSignal }).then((result) => {
             finish();
-            return new ProcessResult(result.output, result.stdout, result.stderr, result.exitCode);
+            return result;
         }).catch((error) => {
             fail(error);
             throw error;

package/dist/socket/index.d.ts

@@ -1,10 +1,9 @@
+import { RemoteError, TransportError } from '../errors/index.js';
 import type { CloseEvent as ReconnectingWebSocketCloseEvent, ErrorEvent as ReconnectingWebSocketErrorEvent } from 'reconnecting-websocket';
 import { EventDispatcher } from '../events/index.js';
-import { NotebookUnavailableError } from '../errors/index.js';
 type TransportUrlProvider = string | (() => string) | (() => Promise<string>);
 interface WsOptions {
     debug?: boolean;
-    startClosed?: boolean;
     pingInterval?: number;
     connectionTimeout?: number;
     connectWaitTimeout?: number;
@@ -28,14 +27,14 @@ export declare enum SocketEvent {
     Error = "error",
     ClientId = "App.Actions.GetClientId"
 }
-export declare class ConnectionTimeoutError extends Error {
+export declare class ConnectionTimeoutError extends TransportError<'ConnectionTimeout'> {
     constructor(message?: string);
 }
-export declare class ConnectionFailedError extends Error {
+export declare class ConnectionFailedError extends TransportError<'ConnectionFailed'> {
     readonly originalError?: unknown;
     constructor(message: string, originalError?: unknown);
 }
-export declare class InvalidMessageError extends Error {
+export declare class InvalidMessageError extends TransportError<'InvalidResponse'> {
     readonly data?: unknown;
     constructor(message: string, data?: unknown);
 }
@@ -44,7 +43,7 @@ export declare class InvalidConfigurationError extends Error {
 }
 export interface TransportEvents {
     'transport.boot_error': {
-        error: NotebookUnavailableError;
+        error: RemoteError<'NotebookUnavailable'>;
         timestamp: number;
     };
     'transport.error': {
@@ -94,7 +93,7 @@ export declare class Transport {
     private handleRawMessage;
     private handleMessage;
     listen(event: string, listener: (data: unknown) => void, _context?: unknown): import("../types.js").Disposable;
-    onDidBootError(listener: (error: NotebookUnavailableError) => void): {
+    onDidBootError(listener: (error: RemoteError<'NotebookUnavailable'>) => void): {
         dispose: () => void;
     };
     removeListener(event: string, listener?: (data: unknown) => void): void;

package/dist/socket/index.js

@@ -6,14 +6,17 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var _Transport_instances, _Transport_connect, _Transport_startPeriodicPing;
 import { nanoid } from 'nanoid';
 import { encode, decode } from '@msgpack/msgpack';
-import { ErrorEvent as SDKErrorEvent, RateLimitError } from '../types.js';
+import { PromiseTimeoutError, RemoteError, SendTimeoutError, TransportError, remoteError, } from '../errors/index.js';
 import { retry } from '../utils/retry.js';
 import * as ReconnectingWebSocketModule from 'reconnecting-websocket';
 import { timeout } from '../utils/promise.js';
 import { describeWebSocketEvent } from '../utils/websocket.js';
 import WebSocket from 'isomorphic-ws';
 import { NamedDisposable } from '../utils/disposable.js';
-import { NotebookUnavailableError, PromiseTimeoutError, SendTimeoutError } from '../errors/index.js';
+const SAFE_DEBUG_METADATA_KEYS = new Set([
+    'url', 'action', 'event', 'responseEvent', 'errorEvent', 'hasData',
+    'code', 'attempt', 'maxRetries', 'timeout', 'errorCount', 'byteLength',
+]);
 const ReconnectingWebSocket = (ReconnectingWebSocketModule.default
     ?? ReconnectingWebSocketModule);
 export var SocketEvent;
@@ -24,24 +27,21 @@ export var SocketEvent;
     SocketEvent["ClientId"] = "App.Actions.GetClientId";
 })(SocketEvent || (SocketEvent = {}));
 // Add specific error types for better error handling
-export class ConnectionTimeoutError extends Error {
+export class ConnectionTimeoutError extends TransportError {
     constructor(message = 'WebSocket connection timeout') {
-        super(message);
-        this.name = 'ConnectionTimeoutError';
+        super(message, 'ConnectionTimeout');
     }
 }
-export class ConnectionFailedError extends Error {
+export class ConnectionFailedError extends TransportError {
     constructor(message, originalError) {
-        super(message);
+        super(message, 'ConnectionFailed', originalError);
         this.originalError = originalError;
-        this.name = 'ConnectionFailedError';
     }
 }
-export class InvalidMessageError extends Error {
+export class InvalidMessageError extends TransportError {
     constructor(message, data) {
-        super(message);
+        super(message, 'InvalidResponse', data);
         this.data = data;
-        this.name = 'InvalidMessageError';
     }
 }
 // Add configuration validation
@@ -72,8 +72,6 @@ export class Transport {
         // Use configurable ping interval
         this.PING_INTERVAL = options.pingInterval ?? 30000;
         this.CONNECT_WAIT_TIMEOUT = options.connectWaitTimeout ?? 30000;
-        // Always start closed by default (lazy initialization)
-        const startClosed = options.startClosed !== false;
         this.rws = new ReconnectingWebSocket(urlProvider, [], {
             WebSocket: options.webSocket ?? globalThis.WebSocket ?? WebSocket,
             connectionTimeout: options.connectionTimeout,
@@ -81,7 +79,7 @@ export class Transport {
             minReconnectionDelay: 200,
             maxEnqueuedMessages: 0,
             maxRetries: options.maxRetries ?? 50,
-            startClosed,
+            startClosed: true,
         });
         this.log('debug', 'Transport initialized', {
             url: this.url === null ? 'dynamic' : transportLogUrl(this.url),
@@ -112,8 +110,9 @@ export class Transport {
     log(level, message, data) {
         if (this.options.debug) {
             const timestamp = new Date().toISOString();
-            const logData = data ? JSON.stringify(data, null, 2) : '';
-            console[level](`[Transport ${timestamp}] ${message}${logData ? '\n' + logData : ''}`);
+            const metadata = safeDebugMetadata(data);
+            const logData = metadata ? `\n${JSON.stringify(metadata, null, 2)}` : '';
+            console[level](`[Transport ${timestamp}] ${message}${logData}`);
         }
     }
     /**
@@ -243,7 +242,12 @@ export class Transport {
             }
             if (event === SocketEvent.BootError) {
                 const errorData = data;
-                const error = new NotebookUnavailableError(errorData?.message || 'Notebook is no longer available', errorData || {});
+                const error = new RemoteError(errorData?.message || 'Notebook is no longer available', {
+                    source: 'runtime',
+                    status: 503,
+                    code: 'NotebookUnavailable',
+                    details: errorData || {},
+                });
                 this.log('error', 'Boot error received', { data });
                 this.terminate(error, 4000, error.message);
                 return;
@@ -392,12 +396,16 @@ export class Transport {
             });
             this.listenOnce(errorEvent, (e) => {
                 this.log('error', 'Message error received', { action, error: e });
-                const error = e;
-                reject(new SDKErrorEvent(error.code, error.message, error));
+                reject(remoteError('runtime', e));
             });
             closeHandler = (_ev) => {
                 if (_ev.code === 1008 && (_ev.reason || '').includes('rate limit')) {
-                    reject(new RateLimitError(_ev.reason || 'Rate limit exceeded', _ev));
+                    reject(new RemoteError(_ev.reason || 'Rate limit exceeded', {
+                        source: 'runtime',
+                        status: 429,
+                        code: 'RateLimited',
+                        cause: _ev,
+                    }));
                     return;
                 }
                 const detail = describeWebSocketEvent(_ev);
@@ -411,7 +419,7 @@ export class Transport {
             }
             catch (error) {
                 this.log('error', 'Failed to send message', { action, error });
-                reject(error);
+                reject(new ConnectionFailedError(`Failed to send runtime action ${action}.`, error));
             }
         };
         const send = async () => {
@@ -470,11 +478,9 @@ export class Transport {
             }
             catch (e) {
                 // Don't retry these errors
-                if (e instanceof SDKErrorEvent ||
-                    e instanceof RateLimitError ||
+                if (e instanceof RemoteError ||
                     e instanceof InvalidConfigurationError ||
                     e instanceof InvalidMessageError ||
-                    e instanceof NotebookUnavailableError ||
                     e instanceof DOMException) {
                     this.log('debug', 'Non-retryable error, bailing', {
                         error: e.message,
@@ -550,7 +556,7 @@ export class Transport {
     }
     terminate(error, code = 4000, reason = error.message) {
         this.terminalError = error;
-        if (error instanceof NotebookUnavailableError) {
+        if (RemoteError.is(error, 'NotebookUnavailable')) {
             this.eventEmitter.emit('transport.boot_error', {
                 error,
                 timestamp: Date.now(),
@@ -702,6 +708,14 @@ _Transport_instances = new WeakSet(), _Transport_connect = function _Transport_c
         };
     });
 };
+function safeDebugMetadata(data) {
+    if (data === null || typeof data !== 'object') {
+        return null;
+    }
+    // Message bodies and errors can contain tokens, source code, or process output.
+    const metadata = Object.entries(data).filter(([key, value]) => SAFE_DEBUG_METADATA_KEYS.has(key) && ['string', 'number', 'boolean'].includes(typeof value));
+    return metadata.length > 0 ? Object.fromEntries(metadata) : null;
+}
 function transportLogUrl(url) {
     const safeUrl = new URL(url);
     safeUrl.search = '';

package/dist/types.d.ts

@@ -1,15 +1,3 @@
-export type ErrorCode = 400 | 401 | 403 | 404 | 405 | 409 | 413 | 422 | 429 | 500 | 503 | 5000;
-export declare class ErrorEvent extends Error {
-    readonly code: ErrorCode;
-    readonly message: string;
-    readonly raw: object;
-    constructor(code: ErrorCode, message: string, raw?: object);
-}
-export declare class RateLimitError extends ErrorEvent {
-    constructor(message: string, raw?: object);
-}
-export declare class PHPSandboxError extends ErrorEvent {
-}
 export interface Disposable {
     dispose: () => void;
 }

package/dist/types.js

@@ -1,15 +1 @@
-export class ErrorEvent extends Error {
-    constructor(code, message, raw = {}) {
-        super(message);
-        this.code = code;
-        this.message = message;
-        this.raw = raw;
-    }
-}
-export class RateLimitError extends ErrorEvent {
-    constructor(message, raw = {}) {
-        super(429, message, raw);
-    }
-}
-export class PHPSandboxError extends ErrorEvent {
-}
+export {};

package/docs/api-summary.md

@@ -9,7 +9,6 @@ import { PHPSandbox } from '@phpsandbox/sdk';
 
 const client = PHPSandbox.realtime(token, 'https://api.phpsandbox.io/v1', {
   debug: false,
-  startClosed: true,
 });
 
 const restClient = PHPSandbox.rest(token, 'https://api.phpsandbox.io/v1', {
@@ -21,17 +20,14 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 
 ### `NotebookApi`
 
-- `create(template, input?, init = true)`
+- `create(template, input?)`
 - `get(id)`
-- `fork(id, input?)`
-- `destroy(id)`
-- `openFromData(data)`
-- `mail.status(id)`, `mail.enable(id)`, `mail.disable(id)`, `mail.list(id, options?)`, `mail.get(id, hash)`, `mail.delete(id, hash)`
+- `open(data)`
 
 ## `NotebookInstance`
 
-- Lifecycle: `ready()`, `connected()`, `whenConnected()`, `reconnect()`, `dispose()`
-- Notebook actions: `fork(input?)`, `destroy()`, `stop()`, `restart()`, `ping()`, `update()`
+- Lifecycle: `ready()`, `connected()`, `reconnect()`, `dispose()`
+- Notebook actions: `fork(input?)`, `destroy()`, `stop()`, `restart()`
 - Processes: `exec(command, args?, options?)`, or `run(command, args?, options?)` returning native `stdin`, `stdout`, `stderr`, ordered `output`, `wait()`, and `kill()`
 - Events: `listen(event, handler)`, `onDidConnect(handler)`, `onDidDisconnect(handler)`, `onDidInitialize(handler)`
 - Raw call: `invoke(action, data?, options?)`
@@ -54,18 +50,21 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 - `attach(id, options?)` returns a terminal handle
 - Handles expose `input`, `output`, `wait()`, `resize()`, and `kill()`
 
-### Container (`notebook.container`)
+### Notebook lifecycle
 
-- Lifecycle: `start()`, `stop()`, `state()`
-- Runtime config: `setPhp(version)`
+- `notebook.stop()`, `notebook.restart()`
+
+### Runtime (`notebook.runtime`)
+
+- Runtime configuration: `setPhpVersion(version)`
 
 ### Runtime observability
 
-- `notebook.logs.follow({ signal? })` returns `ReadableStream<RuntimeLogEntry>`
-- `notebook.ports.list()` returns the current preview ports
-- `notebook.ports.watch({ signal? })` returns `ReadableStream<PortInfo[]>`
-- `notebook.metrics.current()` returns the current CPU, memory, and disk sample
-- `notebook.metrics.watch({ signal? })` returns `ReadableStream<ContainerStats>`
+- `notebook.runtime.logs.follow({ signal? })` returns `ReadableStream<RuntimeLogEntry>`
+- `notebook.runtime.ports.list()` returns the current preview ports
+- `notebook.runtime.ports.watch({ signal? })` returns `ReadableStream<PortInfo[]>`
+- `notebook.runtime.metrics.current()` returns the current CPU, memory, and disk sample
+- `notebook.runtime.metrics.watch({ signal? })` returns `ReadableStream<RuntimeStats>`
 
 ### Processes
 
@@ -84,8 +83,8 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 
 ### Composer (`notebook.composer`)
 
-- Core: `run(command, args?, options?)`
-- Helpers: `install()`, `update()`, `require()`, `remove()`, `dumpAutoload()`, `packages()`
+- `run(command, args?, options?)`
+- `packages()`
 - Command handles expose `output`, `stdout`, `stderr`, `wait()`, and `kill()`
 
 ### Git (`notebook.git`)
@@ -93,8 +92,8 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 - `checkpoint(author, message, branch = 'main')`
 - `targets.create({ provider, repository, author, branch?, setDefault? })`
 - `targets.list()`, `targets.get(target)`, and `target.sync({ direction?, author? })`
-- `diff({ url?, token?, ref?, base?, target? })`
-- `merge({ url?, token?, ref?, target?, expectedBaseRef?, author?, message? })`
+- `diff({ notebookId?, url?, token?, ref?, base?, target?, patch? })`
+- `merge({ notebookId?, url?, token?, ref?, target?, expectedBaseRef?, author?, message? })`
 - `conflicts()`
 - `abortMerge()`
 - `continueMerge(author, message?)`
@@ -153,7 +152,8 @@ Feedback ingestion is always available through the authenticated API. Configurat
 
 - `notebook.publish({ slug, provider, protection?, metadata? })`
 - `notebook.publication()` returns the current publication or `null`
-- `client.publications.get(id)`, `destroy(id)`, `events(id)`, `logs(id)`, and `buildLogs(id, buildId)`
+- `client.publications.get(id)` returns a publication reference.
+- Publication references expose `refresh()`, `destroy()`, `events()`, `logs()`, `buildLogs()`, and protection operations.
 - A publish run exposes `events()` as an `AsyncIterable`, `result()` with the final status and URL, and `publication()` when refreshed deployment state is needed.
 - Built-in provider names are `cloudflare-containers`, `ssh-server`, and `laravel-cloud`. Provider maps support TypeScript declaration merging.
 - Cloudflare Containers input uses `{ name: 'cloudflare-containers', accountId, size?, sleepAfter?, placement?, instances? }` and resolves the sandbox's attached Cloudflare integration when each operation runs.
@@ -162,19 +162,19 @@ Feedback ingestion is always available through the authenticated API. Configurat
 ## Account integrations
 
 - `client.integrations.link({ provider, label?, authorization })`
-- `client.integrations.list()`, `get(integration)`, `update(integration, input)`, and `unlink(integration)`
+- `client.integrations.list()` and `get(integration)`
 - Resource instances expose `update(input)` and `unlink()`.
 - Built-in providers are `cloudflare`, `github`, and `laravel-cloud`; current public authorization uses opaque caller-managed tokens.
 
 ## Common Errors
 
-- `ApiError` for HTTP API failures
-- `NotebookInitError` when notebook initialization returns `type: 'error'`
-- `FilesystemError` + `FilesystemErrorType.*` for file system operations
-- `RateLimitError` for rate-limited flows
+- `RemoteError` when Core or the notebook runtime returns a structured failure
+- `RemoteError.is(error, code)` for exact conditions such as `FileNotFound` and `RateLimited`
+- `RemoteError.isValidation(error)` for typed validation details
+- `TransportError` when no valid remote response is received
 
 ## Notes for Consumers
 
-- `get()` does not auto-initialize; call `await notebook.ready()`.
-- `create()` and `fork()` initialize by default.
+- Runtime actions wait for readiness before their handlers run.
+- Call `ready()` explicitly when you need provisioning metadata or initialization errors before another action.
 - Always call `notebook.dispose()` when finished.

package/docs/cdn-usage.md

@@ -1,80 +1,68 @@
-# CDN Usage Guide
+# Browser/CDN usage
 
-The SDK ships browser bundles under `dist/browser`.
+The SDK includes ESM and script-tag browser bundles. Browser support is a packaging capability, not permission to expose an account API key.
 
-## Security First
+## Choose a trust boundary
 
-Do not hardcode long-lived private API tokens in public frontend code. Use short-lived tokens issued by your backend.
+For public applications, keep the SDK on your backend. Authenticate your application users and authorize the sandbox and operation before making SDK calls. Do not expose a generic proxy for arbitrary management or runtime operations.
 
-## ESM in Browsers
+There is no public SDK API for minting short-lived account keys. Never embed a `psb_` API key in a page, frontend environment variable, local storage, or CDN example.
 
-### unpkg
+A trusted workspace can receive a notebook-specific runtime URL from its backend. That URL contains a bearer ticket and grants access to the sandbox runtime. Only give it to a user you trust to access that sandbox; it is not a preview link. Use preview sessions or handoffs for application review.
 
-```html
-<script type="module">
-  import { PHPSandbox } from 'https://unpkg.com/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.esm.min.js';
-
-  const client = new PHPSandbox('your-short-lived-token');
-  const notebook = await client.notebook.get('your-notebook-id');
-  await notebook.ready();
+## Trusted workspace example (ESM)
 
-  const result = await notebook.exec('php -v', { tty: false });
-  result.throw();
-  console.log(result.output);
-</script>
-```
-
-### jsDelivr
+The `/api/sandbox-session` endpoint below belongs to **your application** and must be implemented on your backend. It must authenticate the user, authorize access to the selected notebook, retrieve fresh notebook data using your server-side API key, and return `id`, `gitUrl`, and `runtimeUrl` with `Cache-Control: no-store`. Never return the account API key. Do not accept arbitrary notebook IDs without authorization.
 
 ```html
 <script type="module">
-  import { PHPSandbox } from 'https://cdn.jsdelivr.net/npm/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.esm.min.js';
+  import { PHPSandbox } from 'https://cdn.jsdelivr.net/npm/@phpsandbox/sdk@0.1.9/dist/browser/phpsandbox-sdk.esm.min.js';
+
+  async function getSession() {
+    const response = await fetch('/api/sandbox-session', {
+      credentials: 'same-origin',
+      cache: 'no-store',
+    });
+    if (!response.ok) throw new Error(`Sandbox session failed: ${response.status}`);
+    return response.json();
+  }
+
+  // No account token in this client. Management calls stay on your backend.
+  const client = PHPSandbox.realtime('', undefined, {
+    runtimeUrlProvider: async () => (await getSession()).runtimeUrl,
+  });
+  const notebook = client.notebook.open(await getSession());
 
-  const client = new PHPSandbox('your-short-lived-token');
+  const result = await notebook.exec('php', ['-v']);
+  if (result.exitCode !== 0) throw new Error(result.stderr || result.output);
+  document.querySelector('#output').textContent = result.stdout;
+  notebook.dispose();
 </script>
+<pre id="output"></pre>
 ```
 
-## Script Tag (IIFE)
+`open()` creates a runtime handle without requesting notebook data from Core. Do not call `client.notebook.create()`, `get()`, or other management methods with this tokenless client. Refresh the same authorized notebook's ticket through your backend when reconnecting. Never log session responses or runtime URLs.
 
-### unpkg
+## Script tag (IIFE)
 
 ```html
-<script src="https://unpkg.com/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.iife.min.js"></script>
+<script src="https://unpkg.com/@phpsandbox/sdk@0.1.9/dist/browser/phpsandbox-sdk.iife.min.js"></script>
 <script>
-  const client = new PHPSandbox.PHPSandbox('your-short-lived-token');
-
-  client.notebook.get('your-notebook-id').then(async (notebook) => {
-    await notebook.ready();
-    const result = await notebook.exec('php -v', { tty: false });
-    console.log(result.output);
-    notebook.dispose();
-  });
+  // The IIFE namespace contains the exported PHPSandbox class.
+  const client = PHPSandbox.PHPSandbox.realtime('');
+  // Use the same authorized backend session and open flow shown above.
 </script>
 ```
 
-### jsDelivr
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.iife.min.js"></script>
-```
-
-## Version Pinning
-
-Always pin a version in production URLs:
-
-```html
-https://unpkg.com/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.esm.min.js
-https://cdn.jsdelivr.net/npm/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.iife.min.js
-```
+## Version pinning
 
-## Bundle Files
+These URLs pin `0.1.9`. Use the version you have tested when upgrading; avoid unversioned or `latest` URLs. Both CDNs serve the same package files:
 
-- `phpsandbox-sdk.esm.js`
-- `phpsandbox-sdk.esm.min.js`
-- `phpsandbox-sdk.iife.js`
-- `phpsandbox-sdk.iife.min.js`
+- `dist/browser/phpsandbox-sdk.esm.js`
+- `dist/browser/phpsandbox-sdk.esm.min.js`
+- `dist/browser/phpsandbox-sdk.iife.js`
+- `dist/browser/phpsandbox-sdk.iife.min.js`
 
-## Browser Requirements
+## Browser requirements
 
-- ES2020-compatible runtime
-- `fetch`, `WebSocket`, and `ReadableStream` support
+Use a modern browser with `fetch`, `WebSocket`, `ReadableStream`, `WritableStream`, `TextEncoder`, `TextDecoder`, and `AbortController`. ES2020 syntax support alone does not supply these web APIs. Your application's CSP must permit the CDN script and the authorized runtime connection.