@phpsandbox/sdk 0.0.66 → 0.0.67

package/dist/deployments.d.ts

@@ -153,6 +153,8 @@ export interface DeploymentData<TProvider extends DeploymentTargetProvider = Dep
     strategy: string;
     targetProvider: TProvider;
     options: DeploymentOptionsForProvider<TProvider>;
+    eventStreamUrl?: string | null;
+    /** @deprecated Use eventStreamUrl instead. */
     okraUrl: string | null;
     originUrl: string | null;
     currentRelease?: DeploymentReleaseData | null;

package/dist/deployments.js

@@ -124,8 +124,9 @@ export class DeploymentRun {
         if (this.started) {
             return this;
         }
-        if (!this.initial.data.okraUrl) {
-            throw new Error(`Deployment ${this.initial.data.id} has no okraUrl for SSE streaming`);
+        const eventStreamUrl = this.initial.data.eventStreamUrl ?? this.initial.data.okraUrl;
+        if (!eventStreamUrl) {
+            throw new Error(`Deployment ${this.initial.data.id} has no eventStreamUrl for SSE streaming`);
         }
         this.started = true;
         this.resultPromise = new Promise((resolve, reject) => {
@@ -133,7 +134,7 @@ export class DeploymentRun {
             this.rejectResult = reject;
         });
         this.resultPromise.catch(() => undefined);
-        void this.consumeStream(this.initial.data.okraUrl);
+        void this.consumeStream(eventStreamUrl);
         return this;
     }
     subscribe() {
@@ -152,9 +153,9 @@ export class DeploymentRun {
         }
         return queue;
     }
-    async consumeStream(okraUrl) {
+    async consumeStream(eventStreamUrl) {
         try {
-            const stream = await this.client.sse(okraUrl);
+            const stream = await this.client.sse(eventStreamUrl);
             for await (const event of readDeployStreamEvents(stream)) {
                 this.publish(event);
                 if (event.type === 'result') {

package/dist/index.d.ts

@@ -307,6 +307,8 @@ export interface PHPSandboxClientOptions {
     telemetry?: Set<TelemetryFeature>;
     fetch?: typeof globalThis.fetch;
     webSocket?: unknown;
+    runtimeUrlProvider?: (notebookId: string) => Promise<string>;
+    /** @deprecated Use runtimeUrlProvider instead. */
     okraUrlProvider?: (notebookId: string) => Promise<string>;
 }
 export type RuntimeTransport = 'realtime' | 'rest';
@@ -377,6 +379,8 @@ export declare class NotebookMailApi {
 }
 export interface NotebookData {
     id: string;
+    runtimeUrl?: string;
+    /** @deprecated Use runtimeUrl instead. */
     okraUrl: string;
     gitUrl: string;
     type?: string;

package/dist/index.js

@@ -347,24 +347,26 @@ export class NotebookInstance {
         this.initialized = false;
         _NotebookInstance_initPromise.set(this, null);
         this.disposables = [];
+        const runtimeUrl = data.runtimeUrl ?? data.okraUrl;
+        const runtimeUrlProvider = client.options.runtimeUrlProvider ?? client.options.okraUrlProvider;
         this.emitter = EventManager.createInstance();
         if (client.runtimeTransport === 'rest') {
             this.socket = null;
-            this.restInvoker = new RestRuntimeInvoker(data, client.options.fetch ?? globalThis.fetch, client.options.okraUrlProvider === undefined
+            this.restInvoker = new RestRuntimeInvoker(data, client.options.fetch ?? globalThis.fetch, runtimeUrlProvider === undefined
                 ? undefined
-                : () => client.options.okraUrlProvider(data.id));
+                : () => runtimeUrlProvider(data.id));
         }
         else {
             this.restInvoker = null;
             let initialConnection = true;
-            const connectionUrl = client.options.okraUrlProvider === undefined
-                ? data.okraUrl
+            const connectionUrl = runtimeUrlProvider === undefined
+                ? runtimeUrl
                 : async () => {
                     if (initialConnection) {
                         initialConnection = false;
-                        return data.okraUrl;
+                        return runtimeUrl;
                     }
-                    return client.options.okraUrlProvider(data.id);
+                    return runtimeUrlProvider(data.id);
                 };
             this.socket = new Transport(connectionUrl, this.emitter, {
                 debug: client.options.debug,

package/dist/runtime/rest.js

@@ -62,20 +62,20 @@ export class RestRuntimeInvoker {
         this.refresh = refresh;
         this.refreshPromise = null;
         this.notebookId = data.id;
-        this.configure(data.okraUrl);
+        this.configure(data.runtimeUrl ?? data.okraUrl);
     }
-    configure(connectionUrl) {
-        const okraUrl = new URL(connectionUrl);
-        const ticket = okraUrl.searchParams.get('ticket') ?? '';
+    configure(runtimeUrl) {
+        const actionUrl = new URL(runtimeUrl);
+        const ticket = actionUrl.searchParams.get('ticket') ?? '';
         if (ticket === '') {
             throw new UnsupportedRuntimeTransportError('The notebook connection does not contain a runtime ticket.');
         }
         this.ticket = ticket;
-        okraUrl.protocol = okraUrl.protocol === 'wss:' ? 'https:' : 'http:';
-        okraUrl.pathname = `/api/v1/notebooks/${encodeURIComponent(this.notebookId)}`;
-        okraUrl.searchParams.delete('ticket');
-        okraUrl.hash = '';
-        this.actionUrl = okraUrl;
+        actionUrl.protocol = actionUrl.protocol === 'wss:' ? 'https:' : 'http:';
+        actionUrl.pathname = `/api/v1/notebooks/${encodeURIComponent(this.notebookId)}`;
+        actionUrl.searchParams.delete('ticket');
+        actionUrl.hash = '';
+        this.actionUrl = actionUrl;
     }
     ready() {
         return this.invokeRaw('runtime.ready', {}, {});
@@ -134,7 +134,7 @@ export class RestRuntimeInvoker {
     }
     async refreshAuthorization() {
         if (this.refreshPromise === null) {
-            this.refreshPromise = this.refresh().then((okraUrl) => this.configure(okraUrl));
+            this.refreshPromise = this.refresh().then((runtimeUrl) => this.configure(runtimeUrl));
         }
         try {
             await this.refreshPromise;

package/docs/api-summary.md

@@ -13,7 +13,7 @@ const client = PHPSandbox.realtime(token, 'https://api.phpsandbox.io/v1', {
 });
 
 const restClient = PHPSandbox.rest(token, 'https://api.phpsandbox.io/v1', {
-  okraUrlProvider: async (notebookId) => getFreshOkraUrl(notebookId),
+  runtimeUrlProvider: async (notebookId) => getFreshRuntimeUrl(notebookId),
 });
 ```
 
@@ -116,11 +116,11 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 
 ### Laravel (`notebook.laravel`)
 
-- Wrapper exists in the SDK, but the current okra websocket action set does not expose Laravel maintenance actions.
+- Wrapper exists in the SDK, but the current runtime action set does not expose Laravel maintenance actions.
 
 ### Auth (`notebook.auth`)
 
-- `login(okraUrl)` using a fresh ticket-bearing Okra URL
+- `login(runtimeUrl)` using a fresh ticket-bearing runtime URL
 - `logout()`
 
 ### Log (`notebook.log`)

package/examples/README.md

@@ -96,7 +96,7 @@ Useful flags:
 
 - `--no-cleanup` keeps every notebook after the run.
 - `--keep-failed` keeps failed notebooks for inspection. By default, failures are deleted too.
-- `--okra-origin=ws://127.0.0.1:9511` preserves the SDK-issued websocket path/auth but routes okra traffic to another host.
+- `--runtime-origin=ws://127.0.0.1:9511` preserves the SDK-issued websocket path/auth but routes runtime traffic to another host.
 - `--include-container-restart` adds a mutable `container.start()` restart check on the fresh notebook.
 - `--include-download` adds `file.download()` to the baseline.
 - `--include-preview` fetches the initialized preview URL in init mode, or the route written by the scenario in full mode.
@@ -104,7 +104,7 @@ Useful flags:
 - `--require-init-messages="Preparing...|Setting up...|Opening..."` asserts frontend-visible init messages were received in order.
 - `--expect-provisioned=true` asserts the `notebook.ready()` initialization result reports provisioning work.
 - `--expect-provisioning-action=template` asserts the initialization result action.
-- `--reauthorization-url=wss://...?ticket=...` exercises `notebook.auth.login()` / `logout()` with a fresh ticket-bearing Okra URL.
+- `--reauthorization-url=wss://...?ticket=...` exercises `notebook.auth.login()` / `logout()` with a fresh ticket-bearing runtime URL.
 - `--mode=init` limits the scenario to notebook create, ready, and delete so you can isolate init capacity.
 - `--init-only` is shorthand for `--mode=init`.
 - `--stop-on-failure-level` stops after the first level that has at least one failing scenario.
@@ -131,7 +131,7 @@ Default baseline coverage:
 Intentionally excluded by default:
 
 - `beacon`, because it needs a browser iframe runtime
-- `auth`, because it needs a fresh ticket-bearing Okra URL
+- `auth`, because it needs a fresh ticket-bearing runtime URL
 - `laravel.maintenance.*`, because it is not part of the current okra websocket action set
 - `lsp`, because it is useful but more brittle than the rest of the headless baseline
 
@@ -153,12 +153,12 @@ PHPSANDBOX_TOKEN=your-token npx tsx examples/notebook-readonly-smoke.ts \
   --notebook-id=gypjc
 ```
 
-To preserve the SDK-issued notebook auth/path but route the websocket to a different okra host:
+To preserve the SDK-issued notebook auth/path but route the websocket to a different runtime host:
 
 ```bash
 PHPSANDBOX_TOKEN=your-token npx tsx examples/notebook-readonly-smoke.ts \
   --notebook-id=gypjc \
-  --okra-origin=ws://127.0.0.1:9501
+  --runtime-origin=ws://127.0.0.1:9501
 ```
 
 Default smoke coverage:

package/examples/laravel-load-test.ts

@@ -59,8 +59,8 @@ interface LoadTestOptions {
   token: string;
   local: boolean;
   apiUrl: string;
-  okraOrigin?: string;
-  okraUrl?: string;
+  runtimeOrigin?: string;
+  runtimeUrl?: string;
   template: string;
   mode: LoadTestMode;
   stopOnFailureLevel: boolean;
@@ -478,7 +478,7 @@ async function runScenario(
 
         const data = {
           ...created.data,
-          okraUrl: resolveOkraUrl(created.data.okraUrl, options),
+          runtimeUrl: resolveRuntimeUrl(created.data.runtimeUrl ?? created.data.okraUrl, options),
         };
         created.dispose();
 
@@ -1071,8 +1071,8 @@ function renderConfiguration(options: LoadTestOptions): string {
     `  mode: ${options.mode}`,
     `  stop on failing level: ${options.stopOnFailureLevel}`,
     `  api url: ${options.apiUrl}`,
-    options.okraOrigin ? `  okra origin override: ${options.okraOrigin}` : undefined,
-    options.okraUrl ? `  okra url override: ${redactUrl(options.okraUrl)}` : undefined,
+    options.runtimeOrigin ? `  runtime origin override: ${options.runtimeOrigin}` : undefined,
+    options.runtimeUrl ? `  runtime url override: ${redactUrl(options.runtimeUrl)}` : undefined,
     `  levels: ${options.levels.join(', ')}`,
     `  waves per level: ${options.waves}`,
     `  visibility: ${options.visibility}`,
@@ -2400,8 +2400,8 @@ function parseOptions(argv: string[]): LoadTestOptions {
     token,
     local,
     apiUrl,
-    okraOrigin: stringArg(args, 'okra-origin'),
-    okraUrl: stringArg(args, 'okra-url'),
+    runtimeOrigin: stringArg(args, 'runtime-origin'),
+    runtimeUrl: stringArg(args, 'runtime-url'),
     template: stringArg(args, 'template') ?? 'laravel',
     mode: resolveMode(args),
     stopOnFailureLevel: booleanArg(args, 'stop-on-failure-level') ?? false,
@@ -2433,17 +2433,17 @@ function parseOptions(argv: string[]): LoadTestOptions {
   };
 }
 
-function resolveOkraUrl(original: string, options: LoadTestOptions): string {
-  if (options.okraUrl) {
-    return options.okraUrl;
+function resolveRuntimeUrl(original: string, options: LoadTestOptions): string {
+  if (options.runtimeUrl) {
+    return options.runtimeUrl;
   }
 
-  if (!options.okraOrigin) {
+  if (!options.runtimeOrigin) {
     return original;
   }
 
   const source = new URL(original);
-  const target = new URL(options.okraOrigin);
+  const target = new URL(options.runtimeOrigin);
   source.protocol = target.protocol;
   source.host = target.host;
   return source.toString();

package/examples/notebook-readonly-smoke.ts

@@ -24,8 +24,8 @@ interface SmokeOptions {
   local: boolean;
   apiUrl: string;
   notebookId: string;
-  okraUrl?: string;
-  okraOrigin?: string;
+  runtimeUrl?: string;
+  runtimeOrigin?: string;
   includeExec: boolean;
   includeDownload: boolean;
   includePreview: boolean;
@@ -67,8 +67,8 @@ interface SmokeArtifact {
     apiUrl: string;
     local: boolean;
     notebookId: string;
-    okraUrl?: string;
-    okraOrigin?: string;
+    runtimeUrl?: string;
+    runtimeOrigin?: string;
     includeExec: boolean;
     includeDownload: boolean;
     includePreview: boolean;
@@ -77,7 +77,7 @@ interface SmokeArtifact {
     id: string;
     title?: string;
     type?: string;
-    okraUrl: string;
+    runtimeUrl: string;
   };
   initTrace: InitTraceArtifact;
   steps: StepArtifact[];
@@ -103,13 +103,13 @@ async function main(): Promise<void> {
       const result = await client.get<NotebookData>(`/notebook/${options.notebookId}`);
       return {
         data: result.data,
-        detail: `id=${result.data.id} type=${result.data.type ?? ''} title=${result.data.title ?? ''} okraUrl=${redactUrl(result.data.okraUrl)}`,
+        detail: `id=${result.data.id} type=${result.data.type ?? ''} title=${result.data.title ?? ''} runtimeUrl=${redactUrl(result.data.runtimeUrl ?? result.data.okraUrl)}`,
       };
     });
 
     notebookData = {
       ...response.data,
-      okraUrl: resolveOkraUrl(response.data.okraUrl, options),
+      runtimeUrl: resolveRuntimeUrl(response.data.runtimeUrl ?? response.data.okraUrl, options),
     };
 
     notebook = new NotebookInstance(notebookData, client);
@@ -289,8 +289,8 @@ async function main(): Promise<void> {
       apiUrl: options.apiUrl,
       local: options.local,
       notebookId: options.notebookId,
-      okraUrl: options.okraUrl ? redactUrl(options.okraUrl) : undefined,
-      okraOrigin: options.okraOrigin,
+      runtimeUrl: options.runtimeUrl ? redactUrl(options.runtimeUrl) : undefined,
+      runtimeOrigin: options.runtimeOrigin,
       includeExec: options.includeExec,
       includeDownload: options.includeDownload,
       includePreview: options.includePreview,
@@ -300,7 +300,7 @@ async function main(): Promise<void> {
           id: notebookData.id,
           title: notebookData.title,
           type: notebookData.type,
-          okraUrl: redactUrl(notebookData.okraUrl),
+          runtimeUrl: redactUrl(notebookData.runtimeUrl ?? notebookData.okraUrl),
         }
       : undefined,
     initTrace,
@@ -471,17 +471,17 @@ async function readStreamToString(stream: ReadableStream<string>, timeoutMs: num
   }
 }
 
-function resolveOkraUrl(original: string, options: SmokeOptions): string {
-  if (options.okraUrl) {
-    return options.okraUrl;
+function resolveRuntimeUrl(original: string, options: SmokeOptions): string {
+  if (options.runtimeUrl) {
+    return options.runtimeUrl;
   }
 
-  if (!options.okraOrigin) {
+  if (!options.runtimeOrigin) {
     return original;
   }
 
   const source = new URL(original);
-  const target = new URL(options.okraOrigin);
+  const target = new URL(options.runtimeOrigin);
   source.protocol = target.protocol;
   source.host = target.host;
   return source.toString();
@@ -508,8 +508,8 @@ function parseOptions(argv: string[]): SmokeOptions {
       process.env.PHPSANDBOX_API_URL ??
       ((booleanArg(args, 'local') ?? false) ? DEFAULT_LOCAL_API_URL : DEFAULT_API_URL),
     notebookId: stringArg(args, 'notebook-id') ?? 'gypjc',
-    okraUrl: stringArg(args, 'okra-url'),
-    okraOrigin: stringArg(args, 'okra-origin'),
+    runtimeUrl: stringArg(args, 'runtime-url'),
+    runtimeOrigin: stringArg(args, 'runtime-origin'),
     includeExec: booleanArg(args, 'include-exec') ?? false,
     includeDownload: booleanArg(args, 'include-download') ?? false,
     includePreview: booleanArg(args, 'include-preview') ?? false,
@@ -786,7 +786,7 @@ function printSummary(artifact: SmokeArtifact): void {
   console.log('\n=== Notebook readonly smoke summary ===');
   console.log(`Status: ${artifact.status}`);
   console.log(`Notebook: ${artifact.options.notebookId}`);
-  console.log(`Okra URL: ${artifact.notebook?.okraUrl ?? 'unresolved'}`);
+  console.log(`Runtime URL: ${artifact.notebook?.runtimeUrl ?? 'unresolved'}`);
   console.log(`Duration: ${formatDuration(artifact.durationMs)}`);
   console.log(`Steps: passed=${passed} failed=${failed} skipped=${skipped}`);
 
@@ -806,8 +806,8 @@ Options:
   --local                   Use ${DEFAULT_LOCAL_API_URL} and default to insecure TLS.
   --insecure-tls            Disable TLS verification for local HTTPS/WSS.
   --ca-file=<path>          Trust a custom CA for local HTTPS/WSS.
-  --okra-url=<url>          Replace notebook okraUrl with a full WebSocket URL.
-  --okra-origin=<origin>    Replace only the okraUrl origin, preserving path/query auth.
+  --runtime-url=<url>       Replace the notebook runtimeUrl with a full WebSocket URL.
+  --runtime-origin=<origin> Replace only the runtimeUrl origin, preserving path/query auth.
   --include-exec            Also run shell, terminal, and REPL read-safe execution checks.
   --include-download        Also run a read-only file.download() check for a known file.
   --include-preview         Fetch the initialized preview URL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.0.66",
+  "version": "0.0.67",
   "description": "A comprehensive TypeScript SDK for interacting with cloud-based PHP development environments",
   "main": "./dist/index.js",
   "module": "./dist/index.js",