@phpsandbox/sdk 0.0.57 → 0.0.59

package/examples/deploy-cloudflare-container.ts

@@ -0,0 +1,49 @@
+import { Client } from '../src/index.js';
+
+const token = process.env.PHPSANDBOX_TOKEN;
+if (!token) {
+  throw new Error('Missing PHPSANDBOX_TOKEN');
+}
+
+const notebookId = process.env.PHPSANDBOX_NOTEBOOK_ID;
+if (!notebookId) {
+  throw new Error('Missing PHPSANDBOX_NOTEBOOK_ID');
+}
+
+const slug = process.env.PHPSANDBOX_DEPLOY_SLUG ?? `sdk-cloudflare-${Date.now().toString(36)}`;
+const apiUrl = process.env.PHPSANDBOX_API_URL;
+const client = new Client(token, apiUrl);
+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.`);
+  }
+
+  const run = deployment
+    ? await deployment.publish()
+    : await notebook.publish({
+      slug,
+      targetProvider: 'okraCloudflareContainer',
+      options: {
+        size: 'small',
+        sleepAfter: '30m',
+      },
+    });
+
+  for await (const event of run.events()) {
+    if (event.type === 'phase') {
+      console.log('phase:', event.name);
+    } else if (event.type === 'log') {
+      process.stdout.write(event.content);
+    } else if (event.type === 'result') {
+      console.log('result:', event);
+    }
+  }
+
+  const current = await run.deployment();
+  console.log('deployment:', current.data.id, current.data.status, current.data.url);
+} finally {
+  notebook.dispose();
+}

package/examples/deploy-laravel-cloud.ts

@@ -0,0 +1,111 @@
+import { Client, type LaravelCloudRegion } from '../src/index.js';
+
+const token = process.env.PHPSANDBOX_TOKEN;
+if (!token) {
+  throw new Error('Missing PHPSANDBOX_TOKEN');
+}
+
+const notebookId = process.env.PHPSANDBOX_NOTEBOOK_ID;
+if (!notebookId) {
+  throw new Error('Missing PHPSANDBOX_NOTEBOOK_ID');
+}
+
+const apiKeySecret = 'LARAVEL_CLOUD_API_KEY';
+const githubTokenSecret = 'GITHUB_TOKEN';
+const slug = process.env.PHPSANDBOX_DEPLOY_SLUG ?? `sdk-laravel-cloud-${Date.now().toString(36)}`;
+const region: LaravelCloudRegion = 'eu-central-1';
+const apiUrl = process.env.PHPSANDBOX_API_URL ?? 'https://api.phpsandbox.io/v1';
+
+if (new URL(apiUrl).hostname.endsWith('.test') && process.env.NODE_TLS_REJECT_UNAUTHORIZED === undefined) {
+  process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+}
+
+const client = new Client(token, apiUrl);
+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.`);
+  }
+
+  const run = deployment ? await deployment.publish() : await publishFirstLaravelCloudDeployment();
+
+  for await (const event of run.events()) {
+    if (event.type === 'phase') {
+      console.log('phase:', event.name);
+    } else if (event.type === 'log') {
+      process.stdout.write(`${event.content}\n`);
+    } else if (event.type === 'result') {
+      console.log('result:', event);
+    }
+  }
+
+  const current = await run.deployment();
+  console.log('deployment:', current.data.id, current.data.status, current.data.url);
+} finally {
+  notebook.dispose();
+}
+
+async function publishFirstLaravelCloudDeployment() {
+  const repository = process.env.PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY;
+  if (!repository) {
+    throw new Error('Missing PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY');
+  }
+
+  const githubToken = process.env.PHPSANDBOX_GITHUB_TOKEN;
+  if (!githubToken) {
+    throw new Error('Missing PHPSANDBOX_GITHUB_TOKEN');
+  }
+
+  const gitAuthorName = process.env.PHPSANDBOX_GIT_AUTHOR_NAME;
+  if (!gitAuthorName) {
+    throw new Error('Missing PHPSANDBOX_GIT_AUTHOR_NAME');
+  }
+
+  const gitAuthorEmail = process.env.PHPSANDBOX_GIT_AUTHOR_EMAIL;
+  if (!gitAuthorEmail) {
+    throw new Error('Missing PHPSANDBOX_GIT_AUTHOR_EMAIL');
+  }
+
+  const apiKey = process.env.PHPSANDBOX_LARAVEL_CLOUD_API_KEY;
+  if (!apiKey) {
+    throw new Error('Missing PHPSANDBOX_LARAVEL_CLOUD_API_KEY');
+  }
+
+  await notebook.secrets.set(githubTokenSecret, {
+    value: githubToken,
+    type: 'credential',
+  });
+
+  const source = await notebook.git.sync({
+    provider: 'github',
+    repository,
+    author: { name: gitAuthorName, email: gitAuthorEmail },
+    branch: 'main',
+    credential: {
+      secret: githubTokenSecret,
+    },
+    setDefault: true,
+  });
+
+  console.log('source:', source.repository, source.branch, source.lastCommitSha);
+
+  const secret = await notebook.secrets.set(apiKeySecret, {
+    value: apiKey,
+    type: 'credential',
+  });
+
+  console.log('secret:', secret.name);
+
+  return notebook.publish({
+    slug,
+    targetProvider: 'okraLaravelCloud',
+    options: {
+      apiKey: {
+        secret: apiKeySecret,
+      },
+      region,
+    },
+  });
+}

package/examples/deploy-ssh-agent.ts

@@ -0,0 +1,211 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { existsSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client, type ServerInstance } from '../src/index.js';
+
+const token = process.env.PHPSANDBOX_TOKEN;
+if (!token) {
+  throw new Error('Missing PHPSANDBOX_TOKEN');
+}
+
+const notebookId = process.env.PHPSANDBOX_NOTEBOOK_ID;
+if (!notebookId) {
+  throw new Error('Missing PHPSANDBOX_NOTEBOOK_ID');
+}
+
+const slug = process.env.PHPSANDBOX_DEPLOY_SLUG ?? `sdk-ssh-${Date.now().toString(36)}`;
+const apiUrl = process.env.PHPSANDBOX_API_URL ?? 'https://api.phpsandbox.io/v1';
+const isLocal = new URL(apiUrl).hostname.endsWith('.test');
+
+if (isLocal && process.env.NODE_TLS_REJECT_UNAUTHORIZED === undefined) {
+  process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+}
+
+const client = new Client(token, apiUrl);
+const notebook = await client.notebook.get(notebookId);
+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.`);
+  }
+
+  const run = deployment
+    ? await deployment.publish()
+    : await notebook.publish({
+      slug,
+      targetProvider: 'okraSshAgent',
+      options: { serverId: (await resolveServer()).data.id },
+    });
+
+  for await (const event of run.events()) {
+    if (event.type === 'phase') {
+      console.log('phase:', event.name);
+    } else if (event.type === 'log') {
+      process.stdout.write(event.content);
+    } else if (event.type === 'result') {
+      console.log('result:', event);
+    }
+  }
+
+  const current = await run.deployment();
+  console.log('deployment:', current.data.id, current.data.status, current.data.url);
+
+  if (current.data.url) {
+    const response = await fetch(current.data.url);
+    console.log('http:', response.status, response.statusText, await response.text());
+    if (!response.ok) {
+      throw new Error(`Deployment URL returned ${response.status} ${response.statusText}`);
+    }
+  }
+} finally {
+  notebook.dispose();
+  if (agent) {
+    stopLocalAgent(agent);
+  }
+}
+
+async function resolveServer(): Promise<ServerInstance> {
+  const serverId = process.env.PHPSANDBOX_DEPLOY_SERVER_ID;
+  if (serverId) {
+    const server = await client.servers.get(serverId);
+    console.log('server:', server.data.id, server.data.status);
+    return server;
+  }
+
+  const server = await client.servers.create({
+    name: `SDK SSH ${slug}`,
+    host: process.env.PHPSANDBOX_DEPLOY_SERVER_HOST ?? 'localhost',
+    ssh: {
+      user: process.env.USER ?? 'local',
+      port: Number(process.env.PHPSANDBOX_DEPLOY_SERVER_PORT ?? 22),
+    },
+  });
+
+  console.log('server:', server.data.id, server.data.status);
+
+  if (!isLocal) {
+    throw new Error('Created server registration. Install the agent on the target server, then rerun with PHPSANDBOX_DEPLOY_SERVER_ID.');
+  }
+
+  if (!server.data.token) {
+    throw new Error('Created server registration without an agent token.');
+  }
+
+  agent = await startLocalAgent(server.data.id, server.data.token);
+  const connected = await server.waitReady({ timeout: 120_000, interval: 1_000 });
+  console.log('server:', connected.data.id, connected.data.status);
+
+  return connected;
+}
+
+async function startLocalAgent(serverId: string, serverToken: string): Promise<ChildProcessWithoutNullStreams> {
+  const dir = mkdtempSync(join(tmpdir(), 'phpsandbox-sdk-ssh-agent-'));
+  const configPath = join(dir, 'agent.yaml');
+  const stateDir = join(dir, 'state');
+  const controlPlane = process.env.PHPSANDBOX_AGENT_CONTROL_PLANE ?? 'wss://okra-edge.ciroue.test/_okra/agent/connect';
+
+  writeFileSync(configPath, [
+    `server_id: "${serverId}"`,
+    `token: "${serverToken}"`,
+    `control_plane: "${controlPlane}"`,
+    `state_dir: "${stateDir}"`,
+    '',
+  ].join('\n'));
+
+  const rookDir = process.env.PHPSANDBOX_ROOK_DIR
+    ?? fileURLToPath(new URL('../../rook/', import.meta.url));
+  if (!existsSync(join(rookDir, 'cmd/rook/main.go'))) {
+    throw new Error('Cannot find local Rook repo. Set PHPSANDBOX_ROOK_DIR to the rook directory.');
+  }
+
+  const child = spawn('go', ['run', './cmd/rook', '--config', configPath], {
+    cwd: rookDir,
+    detached: true,
+    env: {
+      ...process.env,
+      SSL_CERT_FILE: localCaCertPath(),
+    },
+  });
+
+  process.once('exit', () => stopLocalAgent(child));
+
+  await waitForAgent(child);
+  console.log('agent:', 'connected');
+
+  return child;
+}
+
+function stopLocalAgent(child: ChildProcessWithoutNullStreams): void {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+
+  if (child.pid && child.pid > 0) {
+    try {
+      process.kill(-child.pid, 'SIGTERM');
+      return;
+    } catch {
+      // Fall back to killing the direct child when process group signaling is unavailable.
+    }
+  }
+
+  child.kill('SIGTERM');
+}
+
+function waitForAgent(child: ChildProcessWithoutNullStreams): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let output = '';
+    const timeout = setTimeout(() => {
+      finish(new Error(`Timed out waiting for Rook to connect. ${output.trim()}`));
+    }, 120_000);
+
+    const finish = (error?: Error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      child.stdout.off('data', onStdout);
+      child.stderr.off('data', onStderr);
+      child.off('exit', onExit);
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    };
+
+    const append = (chunk: Buffer) => {
+      output = `${output}${chunk.toString()}`.slice(-4000);
+    };
+
+    const onStdout = (chunk: Buffer) => {
+      append(chunk);
+      if (chunk.toString().includes('connected, waiting for commands')) {
+        finish();
+      }
+    };
+
+    const onStderr = (chunk: Buffer) => append(chunk);
+    const onExit = (code: number | null) => {
+      finish(new Error(`Rook exited before connecting with code ${code}. ${output.trim()}`));
+    };
+
+    child.stdout.on('data', onStdout);
+    child.stderr.on('data', onStderr);
+    child.once('exit', onExit);
+  });
+}
+
+function localCaCertPath(): string {
+  const configured = process.env.PHPSANDBOX_LOCAL_CA_CERT
+    ?? process.env.NODE_EXTRA_CA_CERTS
+    ?? `${process.env.HOME}/.config/valet/CA/LaravelValetCASelfSigned.pem`;
+
+  return configured.replace(/^"(.*)"$/, '$1');
+}

package/examples/get.ts

@@ -5,7 +5,7 @@ if (!token) {
   throw new Error('Missing PHPSANDBOX_TOKEN');
 }
 
-const notebookId = 'sfl89';
+const notebookId = process.env.PHPSANDBOX_NOTEBOOK_ID;
 if (!notebookId) {
   throw new Error('Missing PHPSANDBOX_NOTEBOOK_ID');
 }
@@ -15,11 +15,8 @@ const client = new Client(token, apiUrl);
 const notebook = await client.notebook.get(notebookId);
 
 try {
+  console.log('notebook:', notebook.data.id, notebook.data.title ?? '');
   console.log(await notebook.mail.status());
-  console.log(await notebook.preview.createHandoff({
-    preview_session_id: 'ps_29c3265107354bb9a70d19470a57b272',
-    expires_in_seconds: 900,
-  }));
 } finally {
   notebook.dispose();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "description": "A comprehensive TypeScript SDK for interacting with cloud-based PHP development environments",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -28,7 +28,7 @@
     "build:browser": "node build.mjs",
     "clean": "rm -rf dist",
     "test": "vitest run",
-    "check:examples": "tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2020 --types node --skipLibCheck --allowSyntheticDefaultImports --esModuleInterop examples/basic.ts examples/get.ts examples/git-merge-smoke.ts examples/laravel-load-test.ts examples/notebook-readonly-smoke.ts",
+    "check:examples": "tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2020 --types node --skipLibCheck --allowSyntheticDefaultImports --esModuleInterop examples/basic.ts examples/deploy-cloudflare-container.ts examples/deploy-laravel-cloud.ts examples/deploy-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 clean && npm run build",
     "bumpAndPublish": "npm version patch && npm publish --access public"
   },
@@ -61,7 +61,8 @@
     "mitt": "^3.0.1",
     "nanoid": "^5.1.2",
     "reconnecting-websocket": "^4.4.0",
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",