@phpsandbox/sdk 0.0.65 → 0.0.66

package/dist/errors/index.d.ts

@@ -9,3 +9,6 @@ export declare class NotebookUnavailableError extends Error {
     readonly raw: object;
     constructor(message?: string, raw?: object);
 }
+export declare class UnsupportedRuntimeTransportError extends Error {
+    constructor(message: string);
+}

package/dist/errors/index.js

@@ -16,3 +16,9 @@ export class NotebookUnavailableError extends Error {
         this.name = 'NotebookUnavailableError';
     }
 }
+export class UnsupportedRuntimeTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnsupportedRuntimeTransportError';
+    }
+}

package/dist/filesystem.d.ts

@@ -451,8 +451,8 @@ declare class FilesystemSubscription {
 export declare class Filesystem {
     protected okra: NotebookInstance;
     private watches;
-    constructor(okra: NotebookInstance);
-    private watchOkraConnection;
+    constructor(okra: NotebookInstance, registerReconnect?: ((handler: () => void) => Disposable) | null);
+    private registerReconnectHandler;
     info(path: string): Promise<FileInfo>;
     write(path: string, contents: string): Promise<boolean>;
     find(query: string, options?: Partial<FileSearchOptions>): Promise<FileResult[]>;

package/dist/filesystem.js

@@ -69,13 +69,16 @@ class FilesystemSubscription {
     }
 }
 export class Filesystem {
-    constructor(okra) {
+    constructor(okra, registerReconnect = (handler) => okra.onDidConnect(handler)) {
         this.okra = okra;
         this.watches = new Map();
-        this.watchOkraConnection();
+        this.registerReconnectHandler(registerReconnect);
     }
-    watchOkraConnection() {
-        this.okra.onDidConnect(() => {
+    registerReconnectHandler(registerReconnect) {
+        if (registerReconnect === null) {
+            return;
+        }
+        registerReconnect(() => {
             for (const { path, options } of this.watches.values()) {
                 void this.okra.invoke('fs.watch', { path, options }).catch(() => { });
             }

package/dist/index.d.ts

@@ -307,12 +307,16 @@ export interface PHPSandboxClientOptions {
     telemetry?: Set<TelemetryFeature>;
     fetch?: typeof globalThis.fetch;
     webSocket?: unknown;
+    okraUrlProvider?: (notebookId: string) => Promise<string>;
 }
+export type RuntimeTransport = 'realtime' | 'rest';
 export declare class Client {
     readonly notebook: NotebookApi;
     readonly deployments: DeploymentApi;
     readonly servers: ServerApi;
     readonly options: PHPSandboxClientOptions;
+    protected runtimeTransportValue: RuntimeTransport;
+    get runtimeTransport(): RuntimeTransport;
     private readonly fetch;
     private readonly baseUrl;
     private readonly headers;
@@ -334,6 +338,8 @@ export declare class Client {
     private makeRequest;
 }
 export declare class PHPSandbox extends Client {
+    static realtime(token: string, url?: string, options?: PHPSandboxClientOptions): PHPSandbox;
+    static rest(token: string, url?: string, options?: PHPSandboxClientOptions): PHPSandbox;
 }
 export declare class NotebookSecretApi {
     private readonly client;
@@ -400,8 +406,10 @@ export declare class NotebookInstance {
     readonly preview: NotebookPreview;
     readonly mail: NotebookMail;
     private readonly socket;
+    private readonly restInvoker;
     readonly emitter: EventDispatcher;
     initialized: NotebookInitResult | false;
+    get runtimeTransport(): RuntimeTransport;
     private readonly disposables;
     constructor(data: NotebookData, client: Client);
     ready(): Promise<NotebookInitSuccessResult>;
@@ -425,10 +433,12 @@ export declare class NotebookInstance {
     onDidConnect(handler: () => void): Disposable;
     onDidDisconnect(handler: () => void): Disposable;
     onDidBootError(handler: (error: NotebookUnavailableError) => void): Disposable;
+    private restInitialization;
     update(input: Partial<UpdateNotebookInput>): Promise<NotebookInstance>;
     onDidInitialize(handler: (result: NotebookInitResult) => void): Disposable;
     reconnect(): Promise<NotebookInstance>;
     beacon(iframe: HTMLIFrameElement, options?: BeaconOptions): Promise<Beacon>;
+    private realtimeSocket;
 }
 export declare class NotebookSecrets {
     private readonly client;

package/dist/index.js

@@ -26,9 +26,10 @@ import { Transport } from './socket/index.js';
 import EventManager from './events/index.js';
 import Git from './git.js';
 import { createBeacon } from './beacon/index.js';
-import { NotebookUnavailableError } from './errors/index.js';
+import { NotebookUnavailableError, UnsupportedRuntimeTransportError } from './errors/index.js';
 import { DeploymentApi, NotebookDeploymentApi } from './deployments.js';
 import { ServerApi } from './servers.js';
+import { RestRuntimeInvoker } from './runtime/rest.js';
 export * from './types.js';
 export { Transport } from './socket/index.js';
 export * from './lsp.js';
@@ -150,7 +151,11 @@ function normalizeApiBaseUrl(url) {
     return baseUrl.toString();
 }
 export class Client {
+    get runtimeTransport() {
+        return this.runtimeTransportValue;
+    }
     constructor(token, url = 'https://api.phpsandbox.io/v1', options = {}) {
+        this.runtimeTransportValue = 'realtime';
         this.fetch = globalThis.fetch;
         this.deployments = new DeploymentApi(this);
         this.notebook = new NotebookApi(this);
@@ -224,6 +229,14 @@ export class Client {
     }
 }
 export class PHPSandbox extends Client {
+    static realtime(token, url = 'https://api.phpsandbox.io/v1', options = {}) {
+        return new PHPSandbox(token, url, options);
+    }
+    static rest(token, url = 'https://api.phpsandbox.io/v1', options = {}) {
+        const client = new PHPSandbox(token, url, options);
+        client.runtimeTransportValue = 'rest';
+        return client;
+    }
 }
 export class NotebookSecretApi {
     constructor(client) {
@@ -324,22 +337,44 @@ export class NotebookMailApi {
     }
 }
 export class NotebookInstance {
+    get runtimeTransport() {
+        return this.client.runtimeTransport;
+    }
     constructor(data, client) {
         _NotebookInstance_instances.add(this);
         this.data = data;
         this.client = client;
         this.initialized = false;
-        _NotebookInstance_initPromise.set(this, void 0);
+        _NotebookInstance_initPromise.set(this, null);
         this.disposables = [];
         this.emitter = EventManager.createInstance();
-        this.socket = new Transport(data.okraUrl, this.emitter, {
-            debug: client.options.debug,
-            startClosed: client.options.startClosed,
-            webSocket: client.options.webSocket,
-        });
-        this.watchConnection();
-        __classPrivateFieldSet(this, _NotebookInstance_initPromise, __classPrivateFieldGet(this, _NotebookInstance_instances, "m", _NotebookInstance_init).call(this), "f");
-        this.file = new Filesystem(this);
+        if (client.runtimeTransport === 'rest') {
+            this.socket = null;
+            this.restInvoker = new RestRuntimeInvoker(data, client.options.fetch ?? globalThis.fetch, client.options.okraUrlProvider === undefined
+                ? undefined
+                : () => client.options.okraUrlProvider(data.id));
+        }
+        else {
+            this.restInvoker = null;
+            let initialConnection = true;
+            const connectionUrl = client.options.okraUrlProvider === undefined
+                ? data.okraUrl
+                : async () => {
+                    if (initialConnection) {
+                        initialConnection = false;
+                        return data.okraUrl;
+                    }
+                    return client.options.okraUrlProvider(data.id);
+                };
+            this.socket = new Transport(connectionUrl, this.emitter, {
+                debug: client.options.debug,
+                startClosed: client.options.startClosed,
+                webSocket: client.options.webSocket,
+            });
+            this.watchConnection();
+            __classPrivateFieldSet(this, _NotebookInstance_initPromise, __classPrivateFieldGet(this, _NotebookInstance_instances, "m", _NotebookInstance_init).call(this), "f");
+        }
+        this.file = new Filesystem(this, this.socket === null ? null : (handler) => this.onDidConnect(handler));
         this.terminal = new Terminal(this);
         this.auth = new Auth(this);
         this.lsp = new Lsp(this);
@@ -357,7 +392,11 @@ export class NotebookInstance {
         this.mail = new NotebookMail(client, this.data.id);
     }
     async ready() {
-        const terminalError = this.socket.getTerminalError();
+        if (this.restInvoker !== null) {
+            return this.restInitialization();
+        }
+        const socket = this.realtimeSocket();
+        const terminalError = socket.getTerminalError();
         if (terminalError) {
             throw terminalError;
         }
@@ -366,8 +405,8 @@ export class NotebookInstance {
              * If ready is called, ensure the websocket is open so server-driven
              * initialization can begin, but do not block on an extra ping roundtrip.
              */
-            if (this.client.options.startClosed && !this.socket.isConnected) {
-                await this.socket.connect();
+            if (this.client.options.startClosed && !socket.isConnected) {
+                await socket.connect();
             }
             return __classPrivateFieldGet(this, _NotebookInstance_initPromise, "f");
         };
@@ -389,7 +428,7 @@ export class NotebookInstance {
     }
     delete() {
         return this.client.notebook.delete(this.data.id).then(() => {
-            this.socket.terminate(new NotebookUnavailableError('Notebook has been deleted.', { id: this.data.id }));
+            this.socket?.terminate(new NotebookUnavailableError('Notebook has been deleted.', { id: this.data.id }));
         });
     }
     stop() {
@@ -399,10 +438,19 @@ export class NotebookInstance {
         return this.container.restart();
     }
     invoke(action, data = {}, options = {}) {
-        return this.socket.invoke(action, data || {}, options);
+        if (this.restInvoker !== null) {
+            if (this.restInvoker.supports(String(action))) {
+                void this.restInitialization();
+            }
+            return this.restInvoker.invoke(action, data || {}, options);
+        }
+        return this.realtimeSocket().invoke(action, data || {}, options);
     }
     send(action, data = {}) {
-        return this.socket.send(action, data || {});
+        if (this.restInvoker !== null) {
+            return this.restInvoker.send();
+        }
+        return this.realtimeSocket().send(action, data || {});
     }
     ping() {
         return this.invoke('ping');
@@ -414,7 +462,9 @@ export class NotebookInstance {
     }
     dispose() {
         this.disposables.forEach((d) => d.dispose());
-        !this.socket.isClosed && this.socket.disconnect();
+        if (this.socket !== null && !this.socket.isClosed) {
+            this.socket.disconnect();
+        }
     }
     connected() {
         return this.waitForSocketConnection({ rejectOnClose: true });
@@ -423,11 +473,12 @@ export class NotebookInstance {
         return this.waitForSocketConnection({ rejectOnClose: false });
     }
     waitForSocketConnection(options) {
-        const terminalError = this.socket.getTerminalError();
+        const socket = this.realtimeSocket();
+        const terminalError = socket.getTerminalError();
         if (terminalError) {
             return Promise.reject(terminalError);
         }
-        if (this.socket.isConnected) {
+        if (socket.isConnected) {
             return Promise.resolve(this);
         }
         return new Promise((resolve, reject) => {
@@ -448,11 +499,11 @@ export class NotebookInstance {
                 callback();
             };
             try {
-                disposables.push(this.socket.onDidConnect(() => settle(() => resolve(this))));
+                disposables.push(socket.onDidConnect(() => settle(() => resolve(this))));
                 if (options.rejectOnClose) {
-                    disposables.push(this.socket.onDidClose(() => settle(() => reject(new Error('Connection closed')))));
+                    disposables.push(socket.onDidClose(() => settle(() => reject(new Error('Connection closed')))));
                 }
-                disposables.push(this.socket.onDidBootError((error) => settle(() => reject(error))));
+                disposables.push(socket.onDidBootError((error) => settle(() => reject(error))));
             }
             catch (e) {
                 settle(() => reject(e));
@@ -460,38 +511,54 @@ export class NotebookInstance {
         });
     }
     watchConnection() {
-        this.socket.onDidConnect(() => {
-            this.socket.emit('okra.connected');
+        const socket = this.realtimeSocket();
+        socket.onDidConnect(() => {
+            socket.emit('okra.connected');
             if (this.client.options.telemetry) {
                 this.container.enableTelemetry(this.client.options.telemetry);
             }
         });
-        this.socket.onDidClose(() => {
-            this.socket.emit('okra.disconnected');
+        socket.onDidClose(() => {
+            socket.emit('okra.disconnected');
             this.initialized = false;
         });
-        this.socket.onDidBootError((error) => {
-            this.socket.emit('okra.boot_error', error);
-            this.socket.emit('okra.disconnected');
+        socket.onDidBootError((error) => {
+            socket.emit('okra.boot_error', error);
+            socket.emit('okra.disconnected');
             this.initialized = false;
         });
     }
     onDidConnect(handler) {
-        this.socket.removeListener('okra.connected', handler);
-        const disposable = this.socket.listen('okra.connected', handler);
+        const socket = this.realtimeSocket();
+        socket.removeListener('okra.connected', handler);
+        const disposable = socket.listen('okra.connected', handler);
         this.disposables.push(disposable);
         return disposable;
     }
     onDidDisconnect(handler) {
-        const disposable = this.socket.listen('okra.disconnected', handler);
+        const disposable = this.realtimeSocket().listen('okra.disconnected', handler);
         this.disposables.push(disposable);
         return disposable;
     }
     onDidBootError(handler) {
-        const disposable = this.socket.listen('okra.boot_error', handler);
+        const disposable = this.realtimeSocket().listen('okra.boot_error', handler);
         this.disposables.push(disposable);
         return disposable;
     }
+    restInitialization() {
+        if (this.restInvoker === null) {
+            throw new UnsupportedRuntimeTransportError('This operation requires the REST transport.');
+        }
+        if (__classPrivateFieldGet(this, _NotebookInstance_initPromise, "f") === null) {
+            __classPrivateFieldSet(this, _NotebookInstance_initPromise, this.restInvoker.ready().then((result) => {
+                this.initialized = result;
+                this.emitter.emit('notebook.initialized', result);
+                return result;
+            }), "f");
+            void __classPrivateFieldGet(this, _NotebookInstance_initPromise, "f").catch(() => { });
+        }
+        return __classPrivateFieldGet(this, _NotebookInstance_initPromise, "f");
+    }
     update(input) {
         return this.client.notebook.update(this.data.id, input);
     }
@@ -499,10 +566,11 @@ export class NotebookInstance {
         return this.listen('notebook.initialized', handler);
     }
     async reconnect() {
+        const socket = this.realtimeSocket();
         const whenConnected = this.whenConnected();
         // Use the socket's reconnect method which preserves listeners
         // and uses the underlying ReconnectingWebSocket mechanism
-        this.socket.reconnect();
+        socket.reconnect();
         // Reset initialization state
         this.initialized = false;
         // Wait for the socket to reconnect
@@ -517,6 +585,12 @@ export class NotebookInstance {
         iframe.src = result.data.previewUrl;
         return createBeacon(iframe, options);
     }
+    realtimeSocket() {
+        if (this.socket === null) {
+            throw new UnsupportedRuntimeTransportError('This operation requires the realtime transport.');
+        }
+        return this.socket;
+    }
 }
 _NotebookInstance_initPromise = new WeakMap(), _NotebookInstance_instances = new WeakSet(), _NotebookInstance_init = function _NotebookInstance_init() {
     __classPrivateFieldSet(this, _NotebookInstance_initPromise, new Promise((resolve, reject) => {

package/dist/runtime/rest.d.ts

@@ -0,0 +1,20 @@
+import type { CallOption, Invokable, NotebookData, NotebookInitSuccessResult } from '../index.js';
+type RestRuntimeAction = keyof Invokable | 'runtime.ready';
+export declare class RestRuntimeInvoker {
+    private readonly fetch;
+    private readonly refresh?;
+    private actionUrl;
+    private ticket;
+    private refreshPromise;
+    private readonly notebookId;
+    constructor(data: NotebookData, fetch: typeof globalThis.fetch, refresh?: () => Promise<string>);
+    private configure;
+    ready(): Promise<NotebookInitSuccessResult>;
+    supports(action: string): action is RestRuntimeAction;
+    invoke<T extends keyof Invokable>(action: T, data?: Invokable[T]['args'], options?: CallOption): Promise<Invokable[T]['response']>;
+    send(): never;
+    private invokeRaw;
+    private request;
+    private refreshAuthorization;
+}
+export {};

package/dist/runtime/rest.js

@@ -0,0 +1,226 @@
+import { ErrorEvent } from '../types.js';
+import { UnsupportedRuntimeTransportError } from '../errors/index.js';
+const restActionRoutes = {
+    'runtime.ready': { method: 'GET', path: '/runtime' },
+    ping: { method: 'GET', path: '/runtime/ping' },
+    'config.get': { method: 'GET', path: '/runtime/config' },
+    'config.update': { method: 'PATCH', path: '/runtime/config' },
+    'config.set-ports': { method: 'PUT', path: '/runtime/config/ports' },
+    'container.state': { method: 'GET', path: '/runtime/container' },
+    'container.start': { method: 'POST', path: '/runtime/container/start' },
+    'container.restart': { method: 'POST', path: '/runtime/container/restart' },
+    'container.stop': { method: 'POST', path: '/runtime/container/stop' },
+    'container.set-php': { method: 'PUT', path: '/runtime/container/php' },
+    'container.opened-ports': { method: 'GET', path: '/runtime/container/ports' },
+    'terminal.list': { method: 'GET', path: '/runtime/terminals' },
+    'shell.exec': { method: 'POST', path: '/runtime/executions' },
+    'fs.info': { method: 'POST', path: '/runtime/files/info' },
+    'fs.readFile': { method: 'GET', path: '/runtime/files/content' },
+    'fs.writeFile': { method: 'PUT', path: '/runtime/files/content' },
+    'fs.write': { method: 'PUT', path: '/runtime/files/text' },
+    'fs.mkdir': { method: 'POST', path: '/runtime/directories' },
+    'fs.createDirectory': { method: 'PUT', path: '/runtime/directories' },
+    'fs.readDirectory': { method: 'POST', path: '/runtime/directories/read' },
+    'fs.stat': { method: 'POST', path: '/runtime/files/stat' },
+    'fs.move': { method: 'POST', path: '/runtime/files/move' },
+    'fs.rename': { method: 'POST', path: '/runtime/files/rename' },
+    'fs.copy': { method: 'POST', path: '/runtime/files/copy' },
+    'fs.remove': { method: 'POST', path: '/runtime/files/remove' },
+    'fs.delete': { method: 'DELETE', path: '/runtime/files' },
+    'fs.tail': { method: 'POST', path: '/runtime/files/tail' },
+    'fs.find': { method: 'POST', path: '/runtime/files/find' },
+    'fs.textSearch': { method: 'POST', path: '/runtime/files/search' },
+    'fs.tree': { method: 'POST', path: '/runtime/files/tree' },
+    'service.list': { method: 'GET', path: '/runtime/services' },
+    'service.run': { method: 'POST', path: '/runtime/services/run' },
+    'service.stop': { method: 'POST', path: '/runtime/services/stop' },
+    'service.logs': { method: 'POST', path: '/runtime/services/logs' },
+    'composer.invoke': { method: 'POST', path: '/runtime/composer/executions' },
+    'composer.packages': { method: 'GET', path: '/runtime/composer/packages' },
+    'composer.dump-autoload': {
+        method: 'POST',
+        path: '/runtime/composer/autoload',
+    },
+    'git.checkpoint': { method: 'POST', path: '/runtime/git/checkpoints' },
+    'git.checkout': { method: 'POST', path: '/runtime/git/checkouts' },
+    'git.log': { method: 'POST', path: '/runtime/git/log' },
+    'git.sync': { method: 'POST', path: '/runtime/git/sync' },
+    'git.diff': { method: 'POST', path: '/runtime/git/diff' },
+    'git.merge': { method: 'POST', path: '/runtime/git/merge' },
+    'git.conflicts': { method: 'GET', path: '/runtime/git/conflicts' },
+    'git.resolve': { method: 'POST', path: '/runtime/git/conflicts/resolve' },
+    'git.restore': { method: 'POST', path: '/runtime/git/restore' },
+    'git.status': { method: 'GET', path: '/runtime/git/status' },
+    'git.review': { method: 'GET', path: '/runtime/git/review' },
+    'git.stage': { method: 'POST', path: '/runtime/git/stage' },
+    'git.unstage': { method: 'POST', path: '/runtime/git/unstage' },
+    'git.revert': { method: 'POST', path: '/runtime/git/revert' },
+};
+export class RestRuntimeInvoker {
+    constructor(data, fetch, refresh) {
+        this.fetch = fetch;
+        this.refresh = refresh;
+        this.refreshPromise = null;
+        this.notebookId = data.id;
+        this.configure(data.okraUrl);
+    }
+    configure(connectionUrl) {
+        const okraUrl = new URL(connectionUrl);
+        const ticket = okraUrl.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;
+    }
+    ready() {
+        return this.invokeRaw('runtime.ready', {}, {});
+    }
+    supports(action) {
+        return action in restActionRoutes;
+    }
+    invoke(action, data = {}, options = {}) {
+        return this.invokeRaw(action, data ?? {}, options);
+    }
+    send() {
+        throw new UnsupportedRuntimeTransportError('Fire-and-forget actions require the realtime transport.');
+    }
+    async invokeRaw(action, data, options) {
+        const abort = runtimeAbort(options);
+        try {
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                const response = await this.fetch(this.request(action, data, abort.signal));
+                if (response.status === 401 && attempt === 0 && this.refresh !== undefined) {
+                    await this.refreshAuthorization();
+                    continue;
+                }
+                const payload = await runtimeActionResponse(response);
+                if (!response.ok || payload.error !== undefined) {
+                    const error = payload.error ?? payload;
+                    const message = typeof error.message === 'string' ? error.message : `Runtime action ${action} failed.`;
+                    const code = typeof error.code === 'number' ? error.code : response.status;
+                    throw new ErrorEvent(code, message, error);
+                }
+                return payload.data;
+            }
+            throw new ErrorEvent(401, `Runtime action ${action} could not be authorized.`, {});
+        }
+        finally {
+            abort.dispose();
+        }
+    }
+    request(action, data, signal) {
+        const route = restActionRoutes[action];
+        if (route === undefined) {
+            throw new UnsupportedRuntimeTransportError(`Runtime action ${action} requires the realtime transport.`);
+        }
+        const url = new URL(this.actionUrl);
+        url.pathname += route.path;
+        const headers = {
+            Accept: 'application/json, application/octet-stream',
+            Authorization: `Bearer ${this.ticket}`,
+        };
+        const body = runtimeActionRequestBody(action, data, url, headers);
+        return new Request(url, {
+            method: route.method,
+            headers,
+            body: route.method === 'GET' ? undefined : body,
+            signal,
+        });
+    }
+    async refreshAuthorization() {
+        if (this.refreshPromise === null) {
+            this.refreshPromise = this.refresh().then((okraUrl) => this.configure(okraUrl));
+        }
+        try {
+            await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+}
+async function runtimeActionResponse(response) {
+    if (response.ok && response.headers.get('content-type')?.toLowerCase().startsWith('application/octet-stream')) {
+        return { data: new Uint8Array(await response.arrayBuffer()) };
+    }
+    const body = await response.text();
+    if (body === '') {
+        return {};
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return { error: { code: response.status, message: body } };
+    }
+}
+function runtimeActionRequestBody(action, data, url, headers) {
+    const payload = runtimeActionRecord(data);
+    if (action === 'fs.readFile') {
+        setRequiredRuntimeQuery(url, 'path', payload.path);
+        const lineRange = runtimeActionRecord(payload.lineRange);
+        if (lineRange.lineStart !== undefined || lineRange.lineEnd !== undefined) {
+            setRequiredRuntimeQuery(url, 'lineStart', lineRange.lineStart);
+            setRequiredRuntimeQuery(url, 'lineEnd', lineRange.lineEnd);
+        }
+        return undefined;
+    }
+    if (action === 'fs.writeFile') {
+        setRequiredRuntimeQuery(url, 'path', payload.path);
+        const options = runtimeActionRecord(payload.options);
+        setBooleanRuntimeQuery(url, 'overwrite', options.overwrite);
+        setBooleanRuntimeQuery(url, 'create', options.create);
+        setBooleanRuntimeQuery(url, 'unlock', options.unlock);
+        const atomic = runtimeActionRecord(options.atomic);
+        if (typeof atomic.postfix === 'string' && atomic.postfix !== '') {
+            url.searchParams.set('atomicPostfix', atomic.postfix);
+        }
+        if (!ArrayBuffer.isView(payload.contents)) {
+            throw new TypeError('Runtime file contents must be binary data.');
+        }
+        headers['Content-Type'] = 'application/octet-stream';
+        return Uint8Array.from(new Uint8Array(payload.contents.buffer, payload.contents.byteOffset, payload.contents.byteLength)).buffer;
+    }
+    headers['Content-Type'] = 'application/json';
+    return JSON.stringify(data);
+}
+function runtimeActionRecord(value) {
+    return value !== null && typeof value === 'object' ? value : {};
+}
+function setRequiredRuntimeQuery(url, name, value) {
+    if ((typeof value !== 'string' && typeof value !== 'number') || String(value) === '') {
+        throw new TypeError(`Runtime file ${name} is required.`);
+    }
+    url.searchParams.set(name, String(value));
+}
+function setBooleanRuntimeQuery(url, name, value) {
+    url.searchParams.set(name, value === true ? 'true' : 'false');
+}
+function runtimeAbort(options) {
+    if (options.timeout === undefined && options.abortSignal === undefined) {
+        return { signal: new AbortController().signal, dispose: () => undefined };
+    }
+    const controller = new AbortController();
+    const abortFromCaller = () => controller.abort(options.abortSignal?.reason);
+    options.abortSignal?.addEventListener('abort', abortFromCaller, {
+        once: true,
+    });
+    if (options.abortSignal?.aborted) {
+        abortFromCaller();
+    }
+    const timeout = options.timeout === undefined ? undefined : setTimeout(() => controller.abort(), options.timeout);
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            options.abortSignal?.removeEventListener('abort', abortFromCaller);
+            if (timeout !== undefined) {
+                clearTimeout(timeout);
+            }
+        },
+    };
+}

package/dist/socket/index.d.ts

@@ -1,6 +1,7 @@
 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;
@@ -73,7 +74,7 @@ export declare class Transport {
     private readonly CONNECT_WAIT_TIMEOUT;
     private pingIntervalStarted;
     private incomingMessageChain;
-    constructor(url: string, eventEmitter: EventDispatcher, options?: WsOptions);
+    constructor(url: TransportUrlProvider, eventEmitter: EventDispatcher, options?: WsOptions);
     /**
      * Validate configuration options
      */