@phpsandbox/sdk 0.1.13 → 0.1.15

package/dist/errors/index.d.ts

@@ -29,9 +29,15 @@ export declare class RemoteError<TCode extends RemoteErrorCode = RemoteErrorCode
     };
     is<TExpectedCode extends RemoteErrorCode>(code: TExpectedCode): this is this & RemoteError<TExpectedCode>;
 }
+export interface HttpResponseDiagnostics {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+}
 export declare class TransportError<TCode extends TransportErrorCode = TransportErrorCode> extends PHPSandboxError {
     readonly code: TCode;
-    constructor(message: string, code: TCode, cause?: unknown);
+    readonly response?: HttpResponseDiagnostics;
+    constructor(message: string, code: TCode, cause?: unknown, response?: HttpResponseDiagnostics);
     static is(error: unknown): error is TransportError;
     static is<TCode extends TransportErrorCode>(error: unknown, code: TCode): error is TransportError<TCode>;
     is<TExpectedCode extends TransportErrorCode>(code: TExpectedCode): this is this & TransportError<TExpectedCode>;

package/dist/errors/index.js

@@ -56,9 +56,10 @@ export class RemoteError extends PHPSandboxError {
     }
 }
 export class TransportError extends PHPSandboxError {
-    constructor(message, code, cause) {
+    constructor(message, code, cause, response) {
         super(message, cause);
         this.code = code;
+        this.response = response;
     }
     static is(error, code) {
         return error instanceof TransportError && (code === undefined || error.code === code);

package/dist/index.d.ts

@@ -15,15 +15,14 @@ import { RemoteError } from './errors/index.js';
 import { PublicationApi, PublicationInstance, PublicationRun, type PublishInput } from './publications.js';
 import { ServerApi } from './servers.js';
 import { Feedback } from './feedback.js';
-import { IntegrationApi } from './integrations.js';
-import { SandboxIntegrationApi } from './sandbox-integrations.js';
+import { IntegrationApi, SandboxIntegrationApi } from './integrations/index.js';
 export type { Disposable } from './types.js';
 export { LspConnection } from './lsp.js';
 export { FileChangeFilter, FileChangeType, FileType, } from './filesystem.js';
 export type { FileChange, FileContents, FileDeleteOptions, FileDownloadOptions, FileFollowOptions, FileLineRange, FileLineRangeResult, FileListOptions, FileOverwriteOptions, FileResult, FileSearchOptions, FileTailOptions, FileWriteOptions, Filesystem, Stats, TextSearchMatch, TextSearchOptions, TextSearchQuery, TextSearchResult, WatchOptions, } from './filesystem.js';
 export type { PortInfo } from './runtime.js';
 export type { RuntimeLogEntry } from './log.js';
-export type { RuntimeWatchOptions } from './runtime-telemetry.js';
+export type { RuntimeWatchOptions } from './telemetry.js';
 export type { RuntimeResourceUsage, RuntimeStats } from './runtime.js';
 export type { ProcessOutputChunk, ProcessOutputSource, ProcessResult, ShellProcess } from './shell.js';
 export type { SandboxProcess, SpawnOptions, Task, TerminalOptions } from './terminal.js';
@@ -32,12 +31,11 @@ export { notebookBuiltinServices, notebookKnownServices } from './services.js';
 export type { NotebookBuiltinServiceName, NotebookKnownServiceName, NotebookServiceCommand, NotebookServiceKind, NotebookServiceName, NotebookServiceSource, NotebookServiceState, NotebookServiceStatus, ServiceLogOptions, ServiceLogStreamOptions, } from './services.js';
 export type { ConfigPortMapping, ProjectConfig } from './config.js';
 export { PHPSandboxError, RemoteError, TransportError, } from './errors/index.js';
-export type { RemoteErrorCode, RemoteErrorSource, TransportErrorCode, ValidationErrorDetails, } from './errors/index.js';
+export type { HttpResponseDiagnostics, RemoteErrorCode, RemoteErrorSource, TransportErrorCode, ValidationErrorDetails, } from './errors/index.js';
 export type { BuiltInPublicationProviderName, CloudflareContainersProviderOptions, LaravelCloudProviderData, LaravelCloudProviderInput, LaravelCloudRegion, PublicationBuildData, PublicationBuildStatus, PublicationData, PublicationEventData, PublicationInstance, PublicationJurisdiction, PublicationLogChunkData, PublicationLogStream, PublicationPlacement, PublicationProtectionData, PublicationProtectionInput, PublicationProtectionMode, PublicationProtectionSessionData, PublicationProvider, PublicationProviderData, PublicationProviderInput, PublicationProviderInputs, PublicationProviderName, PublicationRegion, PublicationReleaseData, PublicationReleaseStatus, PublicationRun, PublicationSize, PublicationStatus, PublishInput, PublishStreamEvent, PublishStreamLog, PublishStreamPhase, PublishStreamResult, PublishStreamSseEvent, SshServerProviderOptions, UpdatePublicationProtectionInput, } from './publications.js';
 export type { CreateServerInput, ServerData, ServerInstance, ServerListOptions, ServerSshOptions } from './servers.js';
 export type { ConfigureFeedbackInput, FeedbackData, FeedbackListOptions, FeedbackSource, FeedbackStatus, FeedbackType, FeedbackWidgetConfig, FeedbackWidgetTarget, SubmitFeedbackInput, UpdateFeedbackInput, } from './feedback.js';
-export type { Integration, IntegrationAuthorization, IntegrationAuthorizationType, IntegrationData, IntegrationProvider, IntegrationReference, LinkIntegrationInput, UpdateIntegrationInput, } from './integrations.js';
-export type { AttachSandboxIntegrationInput, SandboxIntegration, SandboxIntegrationData, SandboxIntegrationEffect, SandboxIntegrationReference, UpdateSandboxIntegrationInput, } from './sandbox-integrations.js';
+export type { Integration, IntegrationAuthorization, IntegrationAuthorizationType, IntegrationData, IntegrationProvider, IntegrationReference, LinkIntegrationInput, UpdateIntegrationInput, AttachSandboxIntegrationInput, SandboxIntegration, SandboxIntegrationData, SandboxIntegrationEffect, SandboxIntegrationReference, UpdateSandboxIntegrationInput, } from './integrations/index.js';
 interface Result<TType extends 'success' | 'error' | 'running', TData extends object> {
     type: TType;
     message: string;
@@ -108,8 +106,24 @@ export interface CreateNotebookImportInput {
     provider: 'github';
     repo: string;
     branch?: string;
+    ref?: string;
     auth: CreateNotebookImportAuthInput;
 }
+export type InspectNotebookImportInput = CreateNotebookImportInput;
+export interface NotebookImportRequiredSecret {
+    name: string;
+    description: string | null;
+}
+export interface NotebookImportInspectionData {
+    supported: boolean;
+    repository: string;
+    branch: string;
+    ref: string;
+    framework: 'laravel' | 'adonisjs' | 'custom' | null;
+    template: string | null;
+    reason: string | null;
+    requiredSecrets: NotebookImportRequiredSecret[];
+}
 export interface NotebookLifecycleInput {
     persistent?: true;
 }
@@ -118,6 +132,7 @@ export interface CreateNotebookInput extends NotebookLifecycleInput {
     visibility: 'public' | 'private' | 'unlisted';
     import?: CreateNotebookImportInput;
     composerCredentials?: ComposerCredentialInput[];
+    secrets?: UpsertNotebookSecretItemInput[];
 }
 export type ForkNotebookInput = NotebookLifecycleInput;
 export interface NotebookPolicyData {
@@ -196,11 +211,14 @@ export interface NotebookPreviewDataEnabled {
 export type NotebookPreviewData = NotebookPreviewDataDisabled | NotebookPreviewDataEnabled;
 export type NotebookPreviewDataWithUrl = NotebookPreviewDataDisabled | (NotebookPreviewDataEnabled & {
     url: string;
+    accessUrl: string;
 });
 export interface SetNotebookPreviewInput {
     password: string;
 }
 export interface NotebookPreviewSessionData {
+    /** Open this URL to establish preview access. */
+    accessUrl: string;
     previewSessionId: string;
     token: string;
     expiresAt: string;
@@ -215,6 +233,8 @@ export interface CreateNotebookPreviewHandoffInput {
     url: string;
 }
 export interface NotebookPreviewHandoffData {
+    /** Open this URL to establish preview access. */
+    accessUrl: string;
     handoffId: string;
     previewSessionId: string;
     token: string;
@@ -254,6 +274,7 @@ export interface NotebookMailListOptions {
 declare class NotebookApi {
     private readonly client;
     constructor(client: Client);
+    inspectImport(input: InspectNotebookImportInput): Promise<NotebookImportInspectionData>;
     create(template: string, input?: Partial<CreateNotebookInput>): Promise<NotebookInstance>;
     get(id: string): Promise<NotebookInstance>;
     open(data: NotebookData): NotebookInstance;

package/dist/index.js

@@ -28,8 +28,7 @@ import { PublicationApi, PublicationInstance, PublicationRun, } from './publicat
 import { ServerApi } from './servers.js';
 import { RestRuntimeInvoker } from './runtime/rest.js';
 import { Feedback } from './feedback.js';
-import { IntegrationApi } from './integrations.js';
-import { SandboxIntegrationApi } from './sandbox-integrations.js';
+import { IntegrationApi, SandboxIntegrationApi } from './integrations/index.js';
 import { authenticatedRequest } from './http.js';
 export { LspConnection } from './lsp.js';
 export { FileChangeFilter, FileChangeType, FileType, } from './filesystem.js';
@@ -48,6 +47,10 @@ class NotebookApi {
     constructor(client) {
         this.client = client;
     }
+    async inspectImport(input) {
+        const response = await this.client.post('/notebook/imports/inspect', input);
+        return response.data;
+    }
     async create(template, input = {}) {
         const response = await this.client.post('/notebook', { template, ...input });
         return new NotebookInstance(response.data, this.client);
@@ -111,7 +114,7 @@ class ClientImplementation {
             headers: this.headers,
         }));
         if (!response.ok) {
-            throw remoteError('core', errorPayload(await responsePayload(response)), response);
+            throw await responseError(response);
         }
         if (!response.body) {
             throw new TransportError('PHPSandbox API response body is not readable.', 'InvalidResponse', response);
@@ -127,7 +130,7 @@ class ClientImplementation {
             },
         }));
         if (!response.ok) {
-            throw remoteError('core', errorPayload(await responsePayload(response)), response);
+            throw await responseError(response);
         }
         if (!response.body) {
             throw new TransportError('PHPSandbox API SSE response body is not readable.', 'InvalidResponse', response);
@@ -141,7 +144,7 @@ class ClientImplementation {
             headers: this.headers,
         }));
         if (!response.ok) {
-            throw remoteError('core', errorPayload(await responsePayload(response)), response);
+            throw await responseError(response);
         }
         if (response.status === 204) {
             return { data: undefined };
@@ -176,16 +179,17 @@ class ClientImplementation {
         }
     }
 }
-async function responsePayload(response) {
+async function responseError(response) {
     const body = await response.text();
-    if (body === '') {
-        return undefined;
-    }
     try {
-        return JSON.parse(body);
+        return remoteError('core', errorPayload(body === '' ? undefined : JSON.parse(body)), response);
     }
-    catch (error) {
-        throw new TransportError('PHPSandbox API returned an invalid JSON response.', 'InvalidResponse', error);
+    catch {
+        return new TransportError(`PHPSandbox API returned an invalid error response (HTTP ${response.status}).`, 'InvalidResponse', response, {
+            status: response.status,
+            statusText: response.statusText,
+            body,
+        });
     }
 }
 function errorPayload(payload) {

package/dist/{integrations.d.ts → integrations/account.d.ts}

@@ -1,4 +1,4 @@
-import type { Client } from './index.js';
+import type { Client } from '../index.js';
 export type IntegrationProvider = 'cloudflare' | 'github' | 'laravel-cloud';
 export type IntegrationAuthorizationType = 'token';
 export interface IntegrationAuthorization {

package/dist/integrations/index.d.ts

@@ -0,0 +1,2 @@
+export * from './account.js';
+export * from './sandbox.js';

package/dist/integrations/index.js

@@ -0,0 +1,2 @@
+export * from './account.js';
+export * from './sandbox.js';

package/dist/{sandbox-integrations.d.ts → integrations/sandbox.d.ts}

@@ -1,5 +1,5 @@
-import type { Client } from './index.js';
-import { Integration, type IntegrationData, type IntegrationReference } from './integrations.js';
+import type { Client } from '../index.js';
+import { Integration, type IntegrationData, type IntegrationReference } from './account.js';
 export type SandboxIntegrationEffect = 'network';
 export interface AttachSandboxIntegrationInput {
     integration: IntegrationReference;

package/dist/{sandbox-integrations.js → integrations/sandbox.js}

@@ -1,4 +1,4 @@
-import { Integration, integrationId, } from './integrations.js';
+import { Integration, integrationId, } from './account.js';
 export class SandboxIntegrationApi {
     constructor(notebookId, client) {
         this.notebookId = notebookId;

package/dist/log.d.ts

@@ -1,5 +1,5 @@
 import type { NotebookInstance } from './index.js';
-import { RuntimeTelemetry, type RuntimeWatchOptions } from './runtime-telemetry.js';
+import { RuntimeTelemetry, type RuntimeWatchOptions } from './telemetry.js';
 export interface LogEvents {
     'notebook.log': string;
 }

package/dist/log.js

@@ -1,4 +1,4 @@
-import { watchRuntimeTelemetry } from './runtime-telemetry.js';
+import { watchRuntimeTelemetry } from './telemetry.js';
 export default class Logs {
     constructor(okra, telemetry) {
         this.okra = okra;

package/dist/metrics.d.ts

@@ -1,6 +1,6 @@
 import type { NotebookInstance } from './index.js';
 import type { RuntimeStats } from './runtime.js';
-import { RuntimeTelemetry, type RuntimeWatchOptions } from './runtime-telemetry.js';
+import { RuntimeTelemetry, type RuntimeWatchOptions } from './telemetry.js';
 export default class Metrics {
     private readonly okra;
     private readonly telemetry;

package/dist/metrics.js

@@ -1,4 +1,4 @@
-import { watchRuntimeTelemetry } from './runtime-telemetry.js';
+import { watchRuntimeTelemetry } from './telemetry.js';
 export default class Metrics {
     constructor(okra, telemetry) {
         this.okra = okra;

package/dist/ports.d.ts

@@ -1,6 +1,6 @@
 import type { NotebookInstance } from './index.js';
 import type { PortInfo } from './runtime.js';
-import { RuntimeTelemetry, type RuntimeWatchOptions } from './runtime-telemetry.js';
+import { RuntimeTelemetry, type RuntimeWatchOptions } from './telemetry.js';
 export default class Ports {
     private readonly okra;
     private readonly telemetry;

package/dist/ports.js

@@ -1,4 +1,4 @@
-import { watchRuntimeTelemetry } from './runtime-telemetry.js';
+import { watchRuntimeTelemetry } from './telemetry.js';
 export default class Ports {
     constructor(okra, telemetry) {
         this.okra = okra;

package/dist/runtime.d.ts

@@ -2,7 +2,7 @@ import type { Action, NotebookInstance } from './index.js';
 import Logs, { type RuntimeLogEntry } from './log.js';
 import Metrics from './metrics.js';
 import Ports from './ports.js';
-import { type RuntimeTelemetryFeature, type RuntimeWatchOptions } from './runtime-telemetry.js';
+import { type RuntimeTelemetryFeature, type RuntimeWatchOptions } from './telemetry.js';
 export interface PortInfo {
     subdomain: string;
     url: string;

package/dist/runtime.js

@@ -1,7 +1,7 @@
 import Logs from './log.js';
 import Metrics from './metrics.js';
 import Ports from './ports.js';
-import { RuntimeTelemetry, } from './runtime-telemetry.js';
+import { RuntimeTelemetry, } from './telemetry.js';
 export class RuntimeMetrics {
     constructor(metrics) {
         this.metrics = metrics;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.1.13",
-  "description": "A comprehensive TypeScript SDK for interacting with cloud-based PHP development environments",
+  "version": "0.1.15",
+  "description": "The TypeScript SDK for PHPSandbox cloud development environments",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,8 +20,6 @@
   },
   "files": [
     "dist",
-    "docs",
-    "examples",
     "README.md",
     "LICENSE"
   ],
@@ -42,10 +40,8 @@
     "smoke:feedback-widget": "npm run build:tsc && vitest run --reporter=verbose --config tests/smoke/vitest.config.ts tests/smoke/integrations/feedback-widget.smoke.ts",
     "smoke:reaper": "npm run build:tsc && vitest run --reporter=verbose --config tests/smoke/vitest.config.ts tests/smoke/maintenance/resources.reaper.smoke.ts",
     "smoke:typecheck": "npm run build:tsc && tsc --project tests/smoke/tsconfig.json --noEmit",
-    "check:examples": "tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2020 --types node --skipLibCheck --allowSyntheticDefaultImports --esModuleInterop examples/basic.ts examples/publish-cloudflare-container.ts examples/publish-laravel-cloud.ts examples/publish-ssh-agent.ts examples/get.ts examples/git-merge-smoke.ts examples/laravel-load-test.ts examples/notebook-readonly-smoke.ts",
-    "prepublishOnly": "npm test && npm run check:examples && npm run check:docs && npm run clean && npm run build",
-    "bumpAndPublish": "npm version patch && npm publish --access public",
-    "check:docs": "npm run build:tsc && node tools/check-documentation.mjs"
+    "prepublishOnly": "npm test && npm run clean && npm run build",
+    "bumpAndPublish": "npm version patch && npm publish --access public"
   },
   "keywords": [
     "php",
@@ -86,6 +82,6 @@
     "esbuild": "^0.27.1",
     "playwright": "^1.62.1",
     "typescript": "^5.7.2",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.11"
   }
 }

package/docs/api-summary.md

@@ -1,181 +0,0 @@
-# PHPSandbox SDK API Summary
-
-This is a quick reference for the current SDK surface.
-
-## Top-Level Client
-
-```ts
-import { PHPSandbox } from '@phpsandbox/sdk';
-
-const client = PHPSandbox.realtime(token, 'https://api.phpsandbox.io/v1', {
-  debug: false,
-});
-
-const restClient = PHPSandbox.rest(token, 'https://api.phpsandbox.io/v1', {
-  runtimeUrlProvider: async (notebookId) => getFreshRuntimeUrl(notebookId),
-});
-```
-
-Connection lifecycle methods, streaming actions, and event subscriptions require the realtime transport. The REST transport rejects unsupported operations without falling back to a websocket.
-
-### `NotebookApi`
-
-- `create(template, input?)`
-- `get(id)`
-- `open(data)`
-
-## `NotebookInstance`
-
-- 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?)`
-
-## Services
-
-### Filesystem (`notebook.files`)
-
-- File data: `read()`, `readText()`, `readStream()`, `write()`, `tail()`, `stat()`, `exists()`
-- File management: `move()`, `copy()`, `remove()`
-- Directory: `createDirectory()`, `list()`, `tree()`
-- Search: `find()`, `search()`
-- Streaming/monitoring: `readStream()`, `watch()`, `download()`
-- `tail()` is an eager last-lines snapshot; it does not follow future appends.
-
-### Terminal (`notebook.terminals`)
-
-- `list()` returns terminal metadata
-- `create(options?)` returns a terminal handle
-- `attach(id, options?)` returns a terminal handle
-- Handles expose `input`, `output`, `wait()`, `resize()`, and `kill()`
-
-### Notebook lifecycle
-
-- `notebook.stop()`, `notebook.restart()`
-
-### Runtime (`notebook.runtime`)
-
-- Runtime configuration: `setPhpVersion(version)`
-
-### Runtime observability
-
-- `notebook.runtime.logs.follow({ signal? })` returns `ReadableStream<RuntimeLogEntry>`
-- `notebook.runtime.ports.list()` returns the current preview ports
-- `notebook.runtime.ports.resolve(port)` returns preview routing information even when the port is not open
-- `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
-
-- `notebook.run(command, args?, options?)` returns a streaming process handle
-- `notebook.exec(command, args?, options?)` returns a buffered `ProcessResult` for one-shot commands
-- Process handles expose `output`, `stdout`, `stderr`, `stdin`, `wait()`, and `kill()`
-
-### Services (`notebook.services`)
-
-- Constants: `notebookBuiltinServices`, `notebookKnownServices`
-- `list()`
-- `run(name, command?)`
-- `stop(name)`
-- `logs(name, { tail? })`
-- `logs(name, { follow: true, tail?, id? })` returning `ReadableStream<string>`; cancel the stream to stop following
-
-### Composer (`notebook.composer`)
-
-- `run(command, args?, options?)`
-- `packages()`
-- Command handles expose `output`, `stdout`, `stderr`, `wait()`, and `kill()`
-
-### Git (`notebook.git`)
-
-- `checkpoint(author, message, branch = 'main')`
-- `targets.create({ provider, repository, author, branch?, setDefault? })`
-- `targets.list()`, `targets.get(target)`, and `target.sync({ direction?, author? })`
-- `diff({ notebookId?, url?, token?, ref?, base?, target?, patch? })`
-- `merge({ notebookId?, url?, token?, ref?, target?, expectedBaseRef?, author?, message? })`
-- `conflicts()`
-- `abortMerge()`
-- `continueMerge(author, message?)`
-- `review()`
-- `stage({ path?, paths?, all? })`
-- `unstage({ path?, paths?, all? })`
-- `revert({ path?, paths?, all?, staged? })`
-- `log(ref = 'main')`
-- `restore(ref)`
-
-### Sandbox integrations (`notebook.integrations`)
-
-- `attach({ integration, effects? })`
-- A sandbox has one attached integration per provider. `binding.update({ integration })` replaces that provider selection.
-- Provider-backed operations resolve the attached integration when they run; persistent sandbox behavior remains controlled by explicit effects.
-- `list()`
-- `get(binding)`
-- Binding resources expose `update({ effects })` and `detach()`
-- The currently supported sandbox effect is GitHub `network`; effects are explicit and provider-specific.
-
-### Mail (`notebook.mail`)
-
-- `status()` returning non-sensitive mail configuration state
-- `enable()` enabling SMTP env injection for the notebook
-- `disable()` disabling SMTP env injection and revoking the active SMTP token
-- `list({ page? })` returning paginated notebook mail
-- `get(hash)`
-- `delete(hash)`
-
-### Feedback (`sandbox.feedback`)
-
-- `configure({ widget })`, where `widget` is `null` or contains `targets`, optional `label`, and optional `types`
-- `submit({ type, message, author?, context?, metadata? })`
-- `list({ type?, status?, source?, page? })`
-- `get(id)`
-- `update(id, { status })`
-
-Feedback ingestion is always available through the authenticated API. Configuration controls only the optional widget and can target `preview`, `publication`, or both.
-
-### LSP (`notebook.lsp`)
-
-- Messaging: `start(id)`, `close(id)`, `message(id, payload)`
-- Events: `onResponse()`, `onError()`, `onClose()`, `onClientDisconnect()`
-- Connection wrapper: `connection(id)`
-
-### REPL (`notebook.repl`)
-
-- `stop()`, `eval(code, args?, replOpts?)`, `write(input)`, `resize(cols, rows)`
-- Events: `listen()`, `onOutput()`
-
-### Auth (`notebook.auth`)
-
-- `login(runtimeUrl)` using a fresh ticket-bearing runtime URL
-
-## Publications
-
-- `notebook.publish({ slug, provider, protection?, metadata? })`
-- `notebook.publication()` returns the current publication or `null`
-- `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.
-- Laravel Cloud input uses `{ name: 'laravel-cloud', region }` and resolves the sandbox's attached Laravel Cloud integration when each operation runs.
-
-## Account integrations
-
-- `client.integrations.link({ provider, label?, authorization })`
-- `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
-
-- `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
-
-- 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,68 +0,0 @@
-# Browser/CDN usage
-
-The SDK includes ESM and script-tag browser bundles. Browser support is a packaging capability, not permission to expose an account API key.
-
-## Choose a trust boundary
-
-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.
-
-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.
-
-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.
-
-## Trusted workspace example (ESM)
-
-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.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 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>
-```
-
-`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.
-
-## Script tag (IIFE)
-
-```html
-<script src="https://unpkg.com/@phpsandbox/sdk@0.1.9/dist/browser/phpsandbox-sdk.iife.min.js"></script>
-<script>
-  // 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>
-```
-
-## Version pinning
-
-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:
-
-- `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
-
-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.