@phpsandbox/sdk 0.0.56 → 0.0.58

package/dist/servers.d.ts

@@ -0,0 +1,42 @@
+import type { Client, PaginatedApiResponse } from './index.js';
+export interface ServerData {
+    id: string;
+    name: string;
+    host: string;
+    provider: string;
+    status: string;
+    token?: string;
+    sshPublicKey?: string;
+    installCommand?: string;
+    connectedAt: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface ServerSshOptions {
+    user?: string;
+    port?: number;
+}
+export interface CreateServerInput {
+    name: string;
+    host: string;
+    ssh?: ServerSshOptions;
+}
+export declare class ServerApi {
+    private readonly client;
+    constructor(client: Client);
+    list(): Promise<PaginatedApiResponse<ServerData>>;
+    create(input: CreateServerInput): Promise<ServerInstance>;
+    get(id: string): Promise<ServerInstance>;
+    delete(id: string): Promise<void>;
+}
+export declare class ServerInstance {
+    readonly data: ServerData;
+    private readonly client;
+    constructor(data: ServerData, client: Client);
+    refresh(): Promise<ServerInstance>;
+    delete(): Promise<void>;
+    waitReady(options?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<ServerInstance>;
+}

package/dist/servers.js

@@ -0,0 +1,48 @@
+export class ServerApi {
+    constructor(client) {
+        this.client = client;
+    }
+    async list() {
+        const response = await this.client.get('/servers');
+        return response.data;
+    }
+    async create(input) {
+        const response = await this.client.post('/servers', input);
+        return new ServerInstance(response.data, this.client);
+    }
+    async get(id) {
+        const response = await this.client.get(`/servers/${id}`);
+        return new ServerInstance(response.data, this.client);
+    }
+    async delete(id) {
+        await this.client.delete(`/servers/${id}`);
+    }
+}
+export class ServerInstance {
+    constructor(data, client) {
+        this.data = data;
+        this.client = client;
+    }
+    refresh() {
+        return this.client.servers.get(this.data.id);
+    }
+    delete() {
+        return this.client.servers.delete(this.data.id);
+    }
+    async waitReady(options) {
+        const timeout = options?.timeout ?? 300000; // 5 minutes default
+        const interval = options?.interval ?? 3000; // poll every 3s
+        const deadline = Date.now() + timeout;
+        while (Date.now() < deadline) {
+            const server = await this.refresh();
+            if (server.data.status === 'connected') {
+                return server;
+            }
+            if (server.data.status === 'failed') {
+                throw new Error(`Server provisioning failed: ${server.data.id}`);
+            }
+            await new Promise(resolve => setTimeout(resolve, interval));
+        }
+        throw new Error(`Server did not become ready within ${timeout}ms`);
+    }
+}

package/docs/api-summary.md

@@ -75,7 +75,7 @@ const client = new PHPSandbox(token, 'https://api.phpsandbox.io/v1', {
 ### Git (`notebook.git`)
 
 - `checkpoint(author, message, branch = 'main')`
-- `sync(url, author, ref?, token?, direction?, force?)`
+- `sync({ provider, repository, author, branch?, credential, direction?, visibility?, setDefault? })`
 - `diff({ url?, token?, ref?, base?, target? })`
 - `merge({ url?, token?, ref?, target?, expectedBaseRef?, author?, message? })`
 - `conflicts()`

package/examples/README.md

@@ -6,6 +6,34 @@
 PHPSANDBOX_TOKEN=your-token npx tsx examples/basic.ts
 ```
 
+### Running Deployment Examples
+
+Cloudflare Containers target:
+
+```bash
+PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
+  npx tsx examples/deploy-cloudflare-container.ts
+```
+
+SSH agent target:
+
+```bash
+PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
+  npx tsx examples/deploy-ssh-agent.ts
+```
+
+Laravel Cloud target:
+
+```bash
+PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
+  PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY=owner/repo \
+  PHPSANDBOX_GITHUB_TOKEN=github-token \
+  PHPSANDBOX_LARAVEL_CLOUD_API_KEY=lc-api-key \
+  npx tsx examples/deploy-laravel-cloud.ts
+```
+
+Deployment examples accept `PHPSANDBOX_API_URL` and `PHPSANDBOX_DEPLOY_SLUG`. On the first run they create the notebook's deployment; later runs publish the existing deployment without changing slug or provider. The SSH example creates a server registration when `PHPSANDBOX_DEPLOY_SERVER_ID` is not set; on local `.test` APIs it also starts local Rook from `PHPSANDBOX_ROOK_DIR` or the sibling `rook` repo. The Laravel Cloud example syncs the notebook to `PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY`, upserts `PHPSANDBOX_GITHUB_TOKEN` into `GITHUB_TOKEN`, and upserts `PHPSANDBOX_LARAVEL_CLOUD_API_KEY` into `LARAVEL_CLOUD_API_KEY` on first publish.
+
 ### Running The Laravel Load Test
 
 When stdout is a TTY, the load test renders a live dashboard with current stage, active scenarios, and rolling results. When output is redirected or piped, it falls back to plain logs.

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,106 @@
+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 gitAuthor = process.env.PHPSANDBOX_GIT_AUTHOR;
+  if (!gitAuthor) {
+    throw new Error('Missing PHPSANDBOX_GIT_AUTHOR');
+  }
+
+  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: gitAuthor,
+    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

@@ -15,6 +15,7 @@ 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());
 } finally {
   notebook.dispose();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "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",