@phpsandbox/sdk 0.0.61 → 0.0.64

package/dist/composer.d.ts

@@ -1,4 +1,4 @@
-import { Action, Disposable, NotebookInstance } from './index.js';
+import { Action, Client, ComposerCredentials, Disposable, NotebookInstance } from './index.js';
 export interface ComposerEvents {
     'composer.log': string;
 }
@@ -29,7 +29,8 @@ export type Argument<Name extends string = string, Type extends string | string[
 export type Options<Name extends string = string, Type extends string | string[] | boolean = string | string[] | boolean> = Record<Name, Type>;
 export default class Composer {
     protected okra: NotebookInstance;
-    constructor(okra: NotebookInstance);
+    readonly credentials: ComposerCredentials;
+    constructor(okra: NotebookInstance, client: Client);
     invoke(command: ComposerCommand, args?: Argument, options?: Options): Promise<Result>;
     dumpAutoload(): Promise<{
         message: string;

package/dist/composer.js

@@ -1,6 +1,8 @@
+import { ComposerCredentials } from './index.js';
 export default class Composer {
-    constructor(okra) {
+    constructor(okra, client) {
         this.okra = okra;
+        this.credentials = new ComposerCredentials(client, okra.data.id);
     }
     invoke(command, args = {}, options = {}) {
         return this.okra.invoke('composer.invoke', { command, args, options });

package/dist/index.d.ts

@@ -58,12 +58,15 @@ export interface NotebookInitProgress {
     chunk?: string;
     command?: string;
 }
-export type NotebookInitErrorCode = 'github_import_credential_missing';
+export type NotebookInitErrorCode = 'github_import_credential_missing' | 'notebook_disk_quota_exceeded' | 'notebook_not_found' | 'notebook_setup_json_invalid' | 'notebook_backup_restore_failed';
 export interface NotebookInitErrorData {
     errorCode?: NotebookInitErrorCode;
     details?: string;
     retryable?: boolean;
     suggestedAction?: string;
+    phase?: string;
+    quotaMb?: number;
+    usedMb?: number;
     provider?: string;
     repository?: string;
     branch?: string | null;
@@ -118,9 +121,24 @@ export interface CreateNotebookInput extends NotebookLifecycleInput {
     title: string;
     visibility: 'public' | 'private' | 'unlisted';
     import?: CreateNotebookImportInput;
+    composerCredentials?: ComposerCredentialInput[];
 }
 export type ForkNotebookInput = NotebookLifecycleInput;
-export type UpdateNotebookInput = Omit<CreateNotebookInput, 'persistent'>;
+export interface NetworkMatchCondition {
+    path?: string;
+    method?: string;
+}
+export interface NetworkTransformation {
+    match?: NetworkMatchCondition;
+    header?: Record<string, string>;
+}
+export type NetworkPolicyAllow = Record<string, NetworkTransformation[]>;
+export type NetworkPolicy = 'allow' | 'deny' | {
+    allow: NetworkPolicyAllow;
+};
+export interface UpdateNotebookInput extends Omit<CreateNotebookInput, 'persistent'> {
+    network?: NetworkPolicy | null;
+}
 export interface NotebookPolicyData {
     auto_delete_when_stale: boolean;
     stale_after_minutes: number | null;
@@ -155,6 +173,37 @@ export type UpsertNotebookSecretsInput = UpsertNotebookSecretItemInput[] | Recor
 export interface NotebookSecretDeleteOptions {
     environment?: SecretEnvironment;
 }
+export type ComposerCredentialType = 'github-oauth' | 'gitlab-oauth' | 'gitlab-token' | 'bitbucket-oauth' | 'http-basic' | 'bearer';
+export type ComposerCredentialInput = {
+    type: 'github-oauth';
+    token: string;
+} | {
+    type: 'gitlab-oauth';
+    url: string;
+    token: string;
+} | {
+    type: 'gitlab-token';
+    url: string;
+    token: string;
+} | {
+    type: 'bitbucket-oauth';
+    consumerKey: string;
+    consumerSecret: string;
+} | {
+    type: 'http-basic';
+    url: string;
+    username: string;
+    password: string;
+} | {
+    type: 'bearer';
+    url: string;
+    token: string;
+};
+export interface ComposerCredentialInfo {
+    type: ComposerCredentialType;
+    url: string;
+    username?: string;
+}
 export interface NotebookPreviewDataDisabled {
     enabled: false;
 }
@@ -164,6 +213,9 @@ export interface NotebookPreviewDataEnabled {
     expires_at: string;
 }
 export type NotebookPreviewData = NotebookPreviewDataDisabled | NotebookPreviewDataEnabled;
+export type NotebookPreviewDataWithUrl = NotebookPreviewDataDisabled | (NotebookPreviewDataEnabled & {
+    url: string;
+});
 export interface SetNotebookPreviewInput {
     password: string;
 }
@@ -171,16 +223,22 @@ export interface NotebookPreviewSessionData {
     preview_session_id: string;
     token: string;
     expires_at: string;
+    url: string;
+}
+export interface CreateNotebookPreviewSessionInput {
+    url: string;
 }
 export interface CreateNotebookPreviewHandoffInput {
     preview_session_id: string;
     expires_in_seconds?: number;
+    url: string;
 }
 export interface NotebookPreviewHandoffData {
     handoff_id: string;
     preview_session_id: string;
     token: string;
     expires_at: string;
+    url: string;
 }
 export interface NotebookMailRecipientData {
     name?: string;
@@ -228,6 +286,7 @@ export declare class ApiError extends Error {
 export declare class NotebookApi {
     private readonly client;
     readonly secrets: NotebookSecretApi;
+    readonly composerCredentials: NotebookComposerCredentialApi;
     readonly preview: NotebookPreviewApi;
     readonly mail: NotebookMailApi;
     readonly deployment: NotebookDeploymentApi;
@@ -284,13 +343,20 @@ export declare class NotebookSecretApi {
     setMany(id: string, input: UpsertNotebookSecretsInput): Promise<NotebookSecretData[]>;
     delete(id: string, name: string, options?: NotebookSecretDeleteOptions): Promise<void>;
 }
+export declare class NotebookComposerCredentialApi {
+    private readonly client;
+    constructor(client: Client);
+    set(id: string, input: ComposerCredentialInput): Promise<ComposerCredentialInfo>;
+    remove(id: string, type: ComposerCredentialType, url?: string): Promise<void>;
+}
 export declare class NotebookPreviewApi {
     private readonly client;
     constructor(client: Client);
     get(id: string): Promise<NotebookPreviewData>;
+    get(id: string, url: string): Promise<NotebookPreviewDataWithUrl>;
     setPassword(id: string, input: SetNotebookPreviewInput): Promise<NotebookPreviewData>;
     disable(id: string): Promise<void>;
-    createSession(id: string): Promise<NotebookPreviewSessionData>;
+    createSession(id: string, input: CreateNotebookPreviewSessionInput): Promise<NotebookPreviewSessionData>;
     createHandoff(id: string, input: CreateNotebookPreviewHandoffInput): Promise<NotebookPreviewHandoffData>;
 }
 export declare class NotebookMailApi {
@@ -359,7 +425,7 @@ export declare class NotebookInstance {
     onDidConnect(handler: () => void): Disposable;
     onDidDisconnect(handler: () => void): Disposable;
     onDidBootError(handler: (error: NotebookUnavailableError) => void): Disposable;
-    update(): Promise<void>;
+    update(input: Partial<UpdateNotebookInput>): Promise<NotebookInstance>;
     onDidInitialize(handler: (result: NotebookInitResult) => void): Disposable;
     reconnect(): Promise<NotebookInstance>;
     beacon(iframe: HTMLIFrameElement, options?: BeaconOptions): Promise<Beacon>;
@@ -373,14 +439,22 @@ export declare class NotebookSecrets {
     setMany(input: UpsertNotebookSecretsInput): Promise<NotebookSecretData[]>;
     delete(name: string, options?: NotebookSecretDeleteOptions): Promise<void>;
 }
+export declare class ComposerCredentials {
+    private readonly client;
+    private readonly notebookId;
+    constructor(client: Client, notebookId: string);
+    set(input: ComposerCredentialInput): Promise<ComposerCredentialInfo>;
+    remove(type: ComposerCredentialType, url?: string): Promise<void>;
+}
 export declare class NotebookPreview {
     private readonly client;
     private readonly notebookId;
     constructor(client: Client, notebookId: string);
     get(): Promise<NotebookPreviewData>;
+    get(url: string): Promise<NotebookPreviewDataWithUrl>;
     setPassword(input: SetNotebookPreviewInput): Promise<NotebookPreviewData>;
     disable(): Promise<void>;
-    createSession(): Promise<NotebookPreviewSessionData>;
+    createSession(input: CreateNotebookPreviewSessionInput): Promise<NotebookPreviewSessionData>;
     createHandoff(input: CreateNotebookPreviewHandoffInput): Promise<NotebookPreviewHandoffData>;
 }
 export declare class NotebookMail {

package/dist/index.js

@@ -97,6 +97,7 @@ export class NotebookApi {
     constructor(client) {
         this.client = client;
         this.secrets = new NotebookSecretApi(client);
+        this.composerCredentials = new NotebookComposerCredentialApi(client);
         this.preview = new NotebookPreviewApi(client);
         this.mail = new NotebookMailApi(client);
         this.deployment = new NotebookDeploymentApi(client);
@@ -255,12 +256,28 @@ export class NotebookSecretApi {
         await this.client.delete(`/notebook/${id}/secrets/${encodeURIComponent(name)}${query ? `?${query}` : ''}`);
     }
 }
+export class NotebookComposerCredentialApi {
+    constructor(client) {
+        this.client = client;
+    }
+    async set(id, input) {
+        const response = await this.client.put(`/notebook/${id}/composer/credentials`, input);
+        return response.data;
+    }
+    async remove(id, type, url) {
+        const params = new URLSearchParams({ type });
+        if (url)
+            params.set('url', url);
+        await this.client.delete(`/notebook/${id}/composer/credentials?${params.toString()}`);
+    }
+}
 export class NotebookPreviewApi {
     constructor(client) {
         this.client = client;
     }
-    async get(id) {
-        const response = await this.client.get(`/notebook/${id}/preview`);
+    async get(id, url) {
+        const query = url === undefined ? '' : `?${new URLSearchParams({ url }).toString()}`;
+        const response = await this.client.get(`/notebook/${id}/preview${query}`);
         return response.data;
     }
     async setPassword(id, input) {
@@ -270,8 +287,8 @@ export class NotebookPreviewApi {
     async disable(id) {
         await this.client.delete(`/notebook/${id}/preview`);
     }
-    async createSession(id) {
-        const response = await this.client.post(`/notebook/${id}/preview/session`);
+    async createSession(id, input) {
+        const response = await this.client.post(`/notebook/${id}/preview/session`, input);
         return response.data;
     }
     async createHandoff(id, input) {
@@ -326,7 +343,7 @@ export class NotebookInstance {
         this.terminal = new Terminal(this);
         this.auth = new Auth(this);
         this.lsp = new Lsp(this);
-        this.composer = new Composer(this);
+        this.composer = new Composer(this, client);
         this.log = new Log(this);
         this.repl = new Repl(this);
         this.container = new Container(this);
@@ -475,8 +492,8 @@ export class NotebookInstance {
         this.disposables.push(disposable);
         return disposable;
     }
-    update() {
-        return this.invoke('notebook.update');
+    update(input) {
+        return this.client.notebook.update(this.data.id, input);
     }
     onDidInitialize(handler) {
         return this.listen('notebook.initialized', handler);
@@ -544,13 +561,25 @@ export class NotebookSecrets {
         return this.client.notebook.secrets.delete(this.notebookId, name, options);
     }
 }
+export class ComposerCredentials {
+    constructor(client, notebookId) {
+        this.client = client;
+        this.notebookId = notebookId;
+    }
+    set(input) {
+        return this.client.notebook.composerCredentials.set(this.notebookId, input);
+    }
+    remove(type, url) {
+        return this.client.notebook.composerCredentials.remove(this.notebookId, type, url);
+    }
+}
 export class NotebookPreview {
     constructor(client, notebookId) {
         this.client = client;
         this.notebookId = notebookId;
     }
-    get() {
-        return this.client.notebook.preview.get(this.notebookId);
+    get(url) {
+        return this.client.notebook.preview.get(this.notebookId, url);
     }
     setPassword(input) {
         return this.client.notebook.preview.setPassword(this.notebookId, input);
@@ -558,8 +587,8 @@ export class NotebookPreview {
     disable() {
         return this.client.notebook.preview.disable(this.notebookId);
     }
-    createSession() {
-        return this.client.notebook.preview.createSession(this.notebookId);
+    createSession(input) {
+        return this.client.notebook.preview.createSession(this.notebookId, input);
     }
     createHandoff(input) {
         return this.client.notebook.preview.createHandoff(this.notebookId, input);

package/examples/deploy-cloudflare-container.ts

@@ -1,4 +1,5 @@
 import { Client } from '../src/index.js';
+import { deploymentTargetProviderLabel } from './deployment-provider-label.js';
 
 const token = process.env.PHPSANDBOX_TOKEN;
 if (!token) {
@@ -18,7 +19,7 @@ const notebook = await client.notebook.get(notebookId);
 try {
   const deployment = await notebook.deployment();
   if (deployment && deployment.data.targetProvider !== 'okraCloudflareContainer') {
-    throw new Error(`Notebook is already published to ${deployment.data.targetProvider}. Delete that deployment before changing providers.`);
+    throw new Error(`Notebook is already published to ${deploymentTargetProviderLabel(deployment.data.targetProvider)}. Delete that deployment before changing providers.`);
   }
 
   const run = deployment

package/examples/deploy-laravel-cloud.ts

@@ -1,4 +1,5 @@
 import { Client, type LaravelCloudRegion } from '../src/index.js';
+import { deploymentTargetProviderLabel } from './deployment-provider-label.js';
 
 const token = process.env.PHPSANDBOX_TOKEN;
 if (!token) {
@@ -26,7 +27,7 @@ const notebook = await client.notebook.get(notebookId);
 try {
   const deployment = await notebook.deployment();
   if (deployment && deployment.data.targetProvider !== 'okraLaravelCloud') {
-    throw new Error(`Notebook is already published to ${deployment.data.targetProvider}. Delete that deployment before changing providers.`);
+    throw new Error(`Notebook is already published to ${deploymentTargetProviderLabel(deployment.data.targetProvider)}. Delete that deployment before changing providers.`);
   }
 
   const run = deployment ? await deployment.publish() : await publishFirstLaravelCloudDeployment();

package/examples/deploy-ssh-agent.ts

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Client, type ServerInstance } from '../src/index.js';
+import { deploymentTargetProviderLabel } from './deployment-provider-label.js';
 
 const token = process.env.PHPSANDBOX_TOKEN;
 if (!token) {
@@ -30,7 +31,7 @@ let agent: ChildProcessWithoutNullStreams | null = null;
 try {
   const deployment = await notebook.deployment();
   if (deployment && deployment.data.targetProvider !== 'okraSshAgent') {
-    throw new Error(`Notebook is already published to ${deployment.data.targetProvider}. Delete that deployment before changing providers.`);
+    throw new Error(`Notebook is already published to ${deploymentTargetProviderLabel(deployment.data.targetProvider)}. Delete that deployment before changing providers.`);
   }
 
   const run = deployment

package/examples/deployment-provider-label.ts

@@ -0,0 +1,11 @@
+import type { DeploymentTargetProvider } from '../src/index.js';
+
+const deploymentTargetProviderLabels: Record<DeploymentTargetProvider, string> = {
+  okraCloudflareContainer: 'Cloudflare Containers',
+  okraSshAgent: 'SSH Agent',
+  okraLaravelCloud: 'Laravel Cloud',
+};
+
+export function deploymentTargetProviderLabel(provider: DeploymentTargetProvider): string {
+  return deploymentTargetProviderLabels[provider] ?? provider;
+}

package/examples/laravel-load-test.ts

@@ -2028,7 +2028,7 @@ async function requestPreviewWithSession(
 ): Promise<{ status: number; body: string }> {
   let session: NotebookPreviewSessionData;
   try {
-    session = await notebook.preview.createSession();
+    session = await notebook.preview.createSession({ url });
   } catch (error) {
     if (formatError(error).includes('Preview access must be enabled')) {
       return requestPreview(options, url);
@@ -2037,7 +2037,7 @@ async function requestPreviewWithSession(
     throw error;
   }
 
-  const bootstrapUrl = previewUrlWithSessionToken(url, session.token);
+  const bootstrapUrl = session.url;
   const bootstrap = await requestPreview(options, bootstrapUrl, { maxRedirects: 0 });
   const cookie = firstSetCookie(bootstrap.headers);
 
@@ -2064,12 +2064,6 @@ async function requestPreviewWithSession(
   };
 }
 
-function previewUrlWithSessionToken(url: string, token: string): string {
-  const next = new URL(url);
-  next.searchParams.set('__helfer_preview_session', token);
-  return next.toString();
-}
-
 function firstSetCookie(headers: Record<string, unknown>): string | undefined {
   const raw = headers['set-cookie'];
   const value = Array.isArray(raw) ? raw[0] : raw;

package/package.json

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