@phpsandbox/sdk 0.1.12 → 0.1.14

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';
@@ -36,8 +35,7 @@ export type { RemoteErrorCode, RemoteErrorSource, TransportErrorCode, Validation
 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 {
@@ -254,6 +269,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);

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.12",
-  "description": "A comprehensive TypeScript SDK for interacting with cloud-based PHP development environments",
+  "version": "0.1.14",
+  "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.

package/docs/getting-started.md

@@ -1,169 +0,0 @@
-# Getting Started with PHPSandbox SDK
-
-This guide walks through the fastest path from install to a working notebook.
-
-## Prerequisites
-
-- Node.js 18+
-- A PHPSandbox account with an active subscription and available notebook capacity
-- SDK access enabled and an API key created in **API keys**
-
-## Install
-
-```bash
-npm install @phpsandbox/sdk
-```
-
-Copy the API key when shown and store it in `PHPSANDBOX_TOKEN` in your server environment or secret store. Keys are shown once and grant notebook read and write access; never include them in frontend bundles or commit them. If **API keys** is unavailable, request SDK access first.
-
-For a complete runnable example, save the [root quick start](../README.md#quick-start) as `quickstart.mjs` and run `node quickstart.mjs`. The snippets below explain individual operations.
-
-## 1. Create a Client
-
-```ts
-import { PHPSandbox } from '@phpsandbox/sdk';
-
-const token = process.env.PHPSANDBOX_TOKEN;
-if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
-
-const client = PHPSandbox.realtime(token);
-```
-
-## 2. Create or Open a Notebook
-
-```ts
-const notebook = await client.notebook.create('standard');
-
-const persistent = await client.notebook.create('laravel', {
-  title: 'Persistent Laravel',
-  persistent: true,
-});
-
-const existing = await client.notebook.get('notebook-id');
-
-const fork = await existing.fork();
-const persistentFork = await existing.fork({ persistent: true });
-```
-
-API notebook creates and forks are ephemeral by default. Use `persistent: true` only when your account is allowed to create persistent notebooks.
-
-## 3. Write and Read Files
-
-```ts
-await notebook.files.write('hello.php', '<?php echo "Hello";');
-
-const data = await notebook.files.read('hello.php');
-const text = new TextDecoder().decode(data);
-
-console.log(text);
-```
-
-The same `write()` method accepts text, bytes, readable streams, and async iterables:
-
-```ts
-await notebook.files.write('binary.dat', new Uint8Array([1, 2, 3]), {
-  create: true,
-  overwrite: true,
-  unlock: false,
-  atomic: false,
-});
-```
-
-## 4. Run Commands
-
-### Terminal (stream output)
-
-```ts
-const task = await notebook.terminals.create({ command: 'php', args: ['hello.php'] });
-const reader = task.output.getReader();
-
-while (true) {
-  const { done, value } = await reader.read();
-  if (done) break;
-  process.stdout.write(value);
-}
-reader.releaseLock();
-
-const exitCode = await task.wait();
-console.log(`\nExit code: ${exitCode}`);
-```
-
-### Shell (single command result)
-
-```ts
-const result = await notebook.exec('php -v', { tty: false });
-if (result.exitCode !== 0) throw new Error(result.stderr || result.output);
-console.log(result.stdout);
-```
-
-## 5. Search and Watch Files
-
-```ts
-const matches = await notebook.files.find('*.php', {
-  includes: ['app/**'],
-  excludes: ['vendor/**'],
-});
-
-console.log(matches.map((match) => match.path));
-
-const watcher = await notebook.files.watch(
-  '/app',
-  {
-    recursive: true,
-    excludes: ['vendor/**', 'node_modules/**'],
-  },
-  (change) => {
-    console.log(change.type, change.path);
-  }
-);
-
-// later
-watcher.dispose();
-```
-
-## 6. Use Composer and Git
-
-```ts
-const installResult = await notebook.composer.run('install').wait();
-if (installResult.exitCode !== 0) throw new Error(installResult.stderr || installResult.output);
-
-const requireResult = await notebook.composer.run('require', { packages: ['monolog/monolog'] }).wait();
-if (requireResult.exitCode !== 0) throw new Error(requireResult.stderr || requireResult.output);
-
-await notebook.git.checkpoint('Jane Doe <jane@example.com>', 'Initial checkpoint');
-```
-
-## 7. Clean Up
-
-Use a `finally` block to dispose every connection, including forks and notebooks opened with `get()`. `dispose()` only closes local resources. For temporary automation, delete the remote notebook as well:
-
-```ts
-try {
-  await notebook.destroy();
-} finally {
-  notebook.dispose();
-}
-```
-
-Omit `destroy()` only when you intend to keep the notebook. Stopping a notebook does not delete it. Ephemeral notebooks are eventually pruned according to `notebook.data.policy`; do not rely on that as immediate cleanup.
-
-## Common Pitfalls
-
-- Runtime actions wait for readiness. Call `ready()` only when you need its provisioning metadata.
-- `files.watch()` requires an `excludes` array.
-- Command results include `exitCode`; decide explicitly whether a non-zero exit should fail your workflow.
-
-## Troubleshooting
-
-- `401`: check that the API key is set and has not been revoked.
-- `403`: check permissions, account subscription, notebook capacity, and persistence entitlement.
-- `404`: the notebook is missing or inaccessible to your account.
-- `422`: use `RemoteError.isValidation(error)` to inspect field errors; `standard` is the plain PHP template ID.
-- `429`: respect `error.response.headers.get('Retry-After')` and reduce concurrency. Avoid blind retries of resource creation or publication.
-- A process stays alive after the script finishes: ensure all notebook instances are disposed in `finally`.
-
-## Next Reading
-
-- API overview: [API overview](api-summary.md)
-- CDN/browser usage: [Browser usage](cdn-usage.md)
-- Root quick start: [Root quick start](../README.md)