@phpsandbox/sdk 0.0.65 → 0.0.66

package/dist/socket/index.js

@@ -65,13 +65,16 @@ export class Transport {
         this.incomingMessageChain = Promise.resolve();
         // Validate configuration
         this.validateConfiguration(options);
-        this.url = new URL(url);
+        this.url = typeof url === 'string' ? new URL(url) : null;
+        const urlProvider = typeof url === 'string'
+            ? this.url.toString()
+            : async () => new URL(await url()).toString();
         // 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(this.url.toString(), [], {
+        this.rws = new ReconnectingWebSocket(urlProvider, [], {
             WebSocket: options.webSocket ?? globalThis.WebSocket ?? WebSocket,
             connectionTimeout: options.connectionTimeout,
             maxReconnectionDelay: 2000,
@@ -81,7 +84,7 @@ export class Transport {
             startClosed,
         });
         this.log('debug', 'Transport initialized', {
-            url: this.url.toString(),
+            url: this.url === null ? 'dynamic' : transportLogUrl(this.url),
             options,
         });
         this.registerWatchers();
@@ -699,3 +702,9 @@ _Transport_instances = new WeakSet(), _Transport_connect = function _Transport_c
         };
     });
 };
+function transportLogUrl(url) {
+    const safeUrl = new URL(url);
+    safeUrl.search = '';
+    safeUrl.hash = '';
+    return safeUrl.toString();
+}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = 500 | 400 | 401 | 403 | 404 | 409 | 422 | 429 | 5000;
+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;

package/docs/api-summary.md

@@ -7,12 +7,18 @@ This is a quick reference for the current SDK surface.
 ```ts
 import { PHPSandbox } from '@phpsandbox/sdk';
 
-const client = new PHPSandbox(token, 'https://api.phpsandbox.io/v1', {
+const client = PHPSandbox.realtime(token, 'https://api.phpsandbox.io/v1', {
   debug: false,
   startClosed: true,
 });
+
+const restClient = PHPSandbox.rest(token, 'https://api.phpsandbox.io/v1', {
+  okraUrlProvider: async (notebookId) => getFreshOkraUrl(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?, init = true)`
@@ -114,7 +120,7 @@ const client = new PHPSandbox(token, 'https://api.phpsandbox.io/v1', {
 
 ### Auth (`notebook.auth`)
 
-- `login(newConnectionData)`
+- `login(okraUrl)` using a fresh ticket-bearing Okra URL
 - `logout()`
 
 ### Log (`notebook.log`)

package/examples/README.md

@@ -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.
-- `--auth-payload=...` exercises `notebook.auth.login()` / `logout()`.
+- `--reauthorization-url=wss://...?ticket=...` exercises `notebook.auth.login()` / `logout()` with a fresh ticket-bearing Okra 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 real connection payload
+- `auth`, because it needs a fresh ticket-bearing Okra 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
 

package/examples/laravel-load-test.ts

@@ -84,7 +84,7 @@ interface LoadTestOptions {
   requireInitMessages: string[];
   expectProvisioned?: boolean;
   expectProvisioningAction?: NotebookProvisioningAction;
-  authPayload?: string;
+  reauthorizationUrl?: string;
   json: boolean;
   jsonFile?: string;
   insecureTls: boolean;
@@ -947,14 +947,14 @@ async function runScenario(
         recordSkippedStep(steps, 'lsp.initialize', 'Enable with --include-lsp.');
       }
 
-      if (options.authPayload) {
+      if (options.reauthorizationUrl) {
         await runCheckedStep('auth.login-logout', async () => {
-          await notebook!.auth.login(options.authPayload!);
+          await notebook!.auth.login(options.reauthorizationUrl!);
           await notebook!.auth.logout();
           return 'ok';
         });
       } else {
-        recordSkippedStep(steps, 'auth.login-logout', 'Provide --auth-payload to exercise auth.');
+        recordSkippedStep(steps, 'auth.login-logout', 'Provide --reauthorization-url to exercise auth.');
       }
     }
   } catch (error) {
@@ -1085,7 +1085,7 @@ function renderConfiguration(options: LoadTestOptions): string {
     `  required init messages: ${options.requireInitMessages.length > 0 ? options.requireInitMessages.join(' -> ') : 'none'}`,
     `  expect provisioned: ${options.expectProvisioned ?? 'not asserted'}`,
     `  expect provisioning action: ${options.expectProvisioningAction ?? 'not asserted'}`,
-    `  include auth: ${Boolean(options.authPayload)}`,
+    `  include auth: ${Boolean(options.reauthorizationUrl)}`,
     `  insecure tls: ${options.insecureTls}`,
     `  ca file: ${options.caFile ?? 'none'}`,
   ];
@@ -2291,8 +2291,8 @@ function sanitizeArtifact<T>(payload: T): T {
     if ('token' in cloned.options) {
       cloned.options.token = '<redacted>';
     }
-    if ('authPayload' in cloned.options) {
-      cloned.options.authPayload = '<redacted>';
+    if ('reauthorizationUrl' in cloned.options) {
+      cloned.options.reauthorizationUrl = '<redacted>';
     }
   }
 
@@ -2425,7 +2425,7 @@ function parseOptions(argv: string[]): LoadTestOptions {
     requireInitMessages: listArg(args, 'require-init-messages'),
     expectProvisioned: booleanArg(args, 'expect-provisioned'),
     expectProvisioningAction: provisioningActionArg(args, 'expect-provisioning-action'),
-    authPayload: stringArg(args, 'auth-payload'),
+    reauthorizationUrl: stringArg(args, 'reauthorization-url'),
     json: booleanArg(args, 'json') ?? false,
     jsonFile: stringArg(args, 'json-file'),
     insecureTls,

package/package.json

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