@phpsandbox/sdk 0.0.53 → 0.0.55

package/dist/deployments.d.ts

@@ -0,0 +1,191 @@
+import type { Client, PaginatedApiResponse } from './index.js';
+export type DeploymentStrategy = 'auto' | 'laravel' | 'phpsandbox' | 'compose' | 'custom';
+export type DeploymentTargetProvider = 'okra' | 'cloudflare-containers';
+export type DeploymentRuntimeProvider = 'docker' | 'compose' | 'cloudflare-container';
+export type DeploymentStatus = 'pending' | 'queued' | 'building' | 'deploying' | 'healthy' | 'failed' | 'stopped' | 'deleting' | 'deleted' | 'delete_failed';
+export type DeploymentSize = 'nano' | 'small' | 'medium' | 'large' | 'lite' | 'basic' | 'standard-1' | 'standard-2';
+export interface DeploymentPlacement {
+    regions?: Array<'ENAM' | 'WNAM' | 'EEUR' | 'WEUR' | 'APAC' | 'SAM' | 'ME' | 'OC' | 'AFR' | string>;
+    jurisdiction?: 'eu' | 'fedramp' | string;
+}
+export interface DeployInput {
+    name?: string;
+    slug?: string;
+    strategy?: DeploymentStrategy;
+    target_provider?: DeploymentTargetProvider;
+    runtime_provider?: DeploymentRuntimeProvider;
+    size?: DeploymentSize;
+    sleep_after?: string;
+    placement?: DeploymentPlacement;
+    instances?: number;
+    source_ref?: string;
+    password?: string;
+    feedback_enabled?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface DeploymentSlugAvailabilityData {
+    slug: string;
+    available: boolean;
+    domain: string;
+}
+export interface DeploymentBuildData {
+    id: string;
+    status: string;
+    source_ref: string | null;
+    strategy: DeploymentStrategy | string;
+    target_provider: DeploymentTargetProvider | string;
+    runtime_provider: DeploymentRuntimeProvider | string | null;
+    size: DeploymentSize | string;
+    artifact_path: string | null;
+    artifact_checksum: string | null;
+    error_message: string | null;
+    started_at: string | null;
+    finished_at: string | null;
+}
+export interface DeploymentReleaseData {
+    id: string;
+    status: string;
+    artifact_path: string;
+    artifact_checksum: string;
+    manifest: Record<string, unknown>;
+}
+export interface DeploymentDomainDnsData {
+    type: 'CNAME' | 'ALIAS' | 'ANAME' | string;
+    name: string;
+    value: string;
+}
+export interface DeploymentDomainData {
+    id: string;
+    deployment_id: string;
+    hostname: string;
+    status: string;
+    provider: string;
+    provider_hostname_id: string | null;
+    dns: DeploymentDomainDnsData;
+    ssl: {
+        status: string | null;
+    };
+    validation_errors: unknown[];
+    validation_records: unknown[];
+    metadata: Record<string, unknown>;
+    verified_at: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface CreateDeploymentDomainInput {
+    hostname: string;
+}
+export interface DeploymentData {
+    id: string;
+    notebook_id: string;
+    name: string;
+    slug: string;
+    url: string;
+    status: DeploymentStatus | string;
+    strategy: DeploymentStrategy | string;
+    target_provider: DeploymentTargetProvider | string;
+    runtime_provider: DeploymentRuntimeProvider | string | null;
+    size: DeploymentSize | string;
+    sleep_after: string;
+    placement: DeploymentPlacement | null;
+    instances: number;
+    origin_url: string | null;
+    protection: {
+        mode: 'none' | 'password' | string;
+        enabled: boolean;
+    };
+    feedback: {
+        enabled: boolean;
+        config: Record<string, unknown>;
+    };
+    current_release?: DeploymentReleaseData | null;
+    domains?: DeploymentDomainData[];
+    latest_build?: DeploymentBuildData | null;
+    deployed_at: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface DeploymentEventData {
+    id?: number | string;
+    sequence: number;
+    type: string;
+    payload: Record<string, unknown>;
+    created_at: string | null;
+}
+export interface DeploymentLogChunkData {
+    sequence: number;
+    stream: 'build' | 'runtime' | string;
+    content: string;
+    created_at: string | null;
+}
+export interface UpdateDeploymentProtectionInput {
+    mode: 'none' | 'password';
+    password?: string;
+}
+export interface DeploymentProtectionData {
+    mode: 'none' | 'password' | string;
+    enabled: boolean;
+    token?: string;
+    expires_at?: string;
+    url?: string;
+}
+export interface DeploymentProtectionSessionData {
+    preview_session_id: string;
+    token: string;
+    expires_at: string;
+    url: string;
+}
+export interface UpdateDeploymentFeedbackInput {
+    enabled: boolean;
+    config?: Record<string, unknown>;
+}
+export declare class NotebookDeploymentApi {
+    private readonly client;
+    constructor(client: Client);
+    create(id: string, input?: DeployInput): Promise<DeploymentInstance>;
+    list(id: string): Promise<PaginatedApiResponse<DeploymentData>>;
+    slugAvailability(id: string, slug: string): Promise<DeploymentSlugAvailabilityData>;
+}
+export declare class DeploymentApi {
+    private readonly client;
+    constructor(client: Client);
+    get(id: string): Promise<DeploymentInstance>;
+    redeploy(id: string, input?: DeployInput): Promise<DeploymentInstance>;
+    delete(id: string): Promise<void>;
+    setProtection(id: string, input: UpdateDeploymentProtectionInput): Promise<DeploymentInstance>;
+    protection(id: string): Promise<DeploymentProtectionData>;
+    createProtectionSession(id: string): Promise<DeploymentProtectionSessionData>;
+    disableProtection(id: string): Promise<DeploymentInstance>;
+    setFeedback(id: string, input: UpdateDeploymentFeedbackInput): Promise<DeploymentInstance>;
+    listDomains(id: string): Promise<DeploymentDomainData[]>;
+    createDomain(id: string, input: CreateDeploymentDomainInput): Promise<DeploymentDomainData>;
+    refreshDomain(id: string, domainId: string): Promise<DeploymentDomainData>;
+    deleteDomain(id: string, domainId: string): Promise<void>;
+    events(id: string): Promise<ReadableStream<DeploymentEventData>>;
+    buildLogs(id: string, buildId: string): Promise<ReadableStream<DeploymentLogChunkData>>;
+    logs(id: string): Promise<ReadableStream<DeploymentLogChunkData>>;
+}
+export declare class DeploymentInstance {
+    readonly data: DeploymentData;
+    private readonly client;
+    constructor(data: DeploymentData, client: Client);
+    refresh(): Promise<DeploymentInstance>;
+    redeploy(input?: DeployInput): Promise<DeploymentInstance>;
+    delete(): Promise<void>;
+    wait(options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<DeploymentInstance>;
+    events(): Promise<ReadableStream<DeploymentEventData>>;
+    buildLogs(buildId?: string): Promise<ReadableStream<DeploymentLogChunkData>>;
+    logs(): Promise<ReadableStream<DeploymentLogChunkData>>;
+    setProtection(input: UpdateDeploymentProtectionInput): Promise<DeploymentInstance>;
+    protection(): Promise<DeploymentProtectionData>;
+    createProtectionSession(): Promise<DeploymentProtectionSessionData>;
+    disableProtection(): Promise<DeploymentInstance>;
+    setFeedback(input: UpdateDeploymentFeedbackInput): Promise<DeploymentInstance>;
+    domains(): Promise<DeploymentDomainData[]>;
+    addDomain(input: CreateDeploymentDomainInput): Promise<DeploymentDomainData>;
+    refreshDomain(domainId: string): Promise<DeploymentDomainData>;
+    deleteDomain(domainId: string): Promise<void>;
+}

package/dist/deployments.js

@@ -0,0 +1,182 @@
+export class NotebookDeploymentApi {
+    constructor(client) {
+        this.client = client;
+    }
+    async create(id, input = {}) {
+        const response = await this.client.post(`/notebook/${id}/deployments`, input);
+        return new DeploymentInstance(response.data, this.client);
+    }
+    async list(id) {
+        const response = await this.client.get(`/notebook/${id}/deployments`);
+        return response.data;
+    }
+    async slugAvailability(id, slug) {
+        const query = new URLSearchParams({ slug }).toString();
+        const response = await this.client.get(`/notebook/${id}/deployments/slug-availability?${query}`);
+        return response.data;
+    }
+}
+export class DeploymentApi {
+    constructor(client) {
+        this.client = client;
+    }
+    async get(id) {
+        const response = await this.client.get(`/deployments/${id}`);
+        return new DeploymentInstance(response.data, this.client);
+    }
+    async redeploy(id, input = {}) {
+        const response = await this.client.post(`/deployments/${id}/redeploy`, input);
+        return new DeploymentInstance(response.data, this.client);
+    }
+    async delete(id) {
+        await this.client.delete(`/deployments/${id}`);
+    }
+    async setProtection(id, input) {
+        const response = await this.client.put(`/deployments/${id}/protection`, input);
+        return new DeploymentInstance(response.data, this.client);
+    }
+    async protection(id) {
+        const response = await this.client.get(`/deployments/${id}/protection`);
+        return response.data;
+    }
+    async createProtectionSession(id) {
+        const response = await this.client.post(`/deployments/${id}/protection/session`);
+        return response.data;
+    }
+    async disableProtection(id) {
+        const response = await this.client.delete(`/deployments/${id}/protection`);
+        return new DeploymentInstance(response.data, this.client);
+    }
+    async setFeedback(id, input) {
+        const response = await this.client.put(`/deployments/${id}/feedback`, input);
+        return new DeploymentInstance(response.data, this.client);
+    }
+    async listDomains(id) {
+        const response = await this.client.get(`/deployments/${id}/domains`);
+        return unwrapDeploymentDomainCollection(response.data);
+    }
+    async createDomain(id, input) {
+        const response = await this.client.post(`/deployments/${id}/domains`, input);
+        return response.data;
+    }
+    async refreshDomain(id, domainId) {
+        const response = await this.client.post(`/deployments/${id}/domains/${domainId}/refresh`);
+        return response.data;
+    }
+    async deleteDomain(id, domainId) {
+        await this.client.delete(`/deployments/${id}/domains/${domainId}`);
+    }
+    async events(id) {
+        return parseNdjsonStream(await this.client.stream(`/deployments/${id}/events/stream`));
+    }
+    async buildLogs(id, buildId) {
+        return parseNdjsonStream(await this.client.stream(`/deployments/${id}/builds/${buildId}/logs/stream`));
+    }
+    async logs(id) {
+        return parseNdjsonStream(await this.client.stream(`/deployments/${id}/logs/stream`));
+    }
+}
+export class DeploymentInstance {
+    constructor(data, client) {
+        this.data = data;
+        this.client = client;
+    }
+    refresh() {
+        return this.client.deployments.get(this.data.id);
+    }
+    redeploy(input = {}) {
+        return this.client.deployments.redeploy(this.data.id, input);
+    }
+    delete() {
+        return this.client.deployments.delete(this.data.id);
+    }
+    async wait(options = {}) {
+        const intervalMs = options.intervalMs ?? 1000;
+        const timeoutMs = options.timeoutMs ?? 300000;
+        const startedAt = Date.now();
+        let current = this;
+        while (!deploymentStatusIsTerminal(current.data.status)) {
+            if (Date.now() - startedAt > timeoutMs) {
+                throw new Error(`Timed out waiting for deployment ${this.data.id}`);
+            }
+            await delay(intervalMs);
+            current = await current.refresh();
+        }
+        return current;
+    }
+    events() {
+        return this.client.deployments.events(this.data.id);
+    }
+    buildLogs(buildId = this.data.latest_build?.id ?? '') {
+        if (buildId === '') {
+            return Promise.reject(new Error('Deployment has no latest build id'));
+        }
+        return this.client.deployments.buildLogs(this.data.id, buildId);
+    }
+    logs() {
+        return this.client.deployments.logs(this.data.id);
+    }
+    setProtection(input) {
+        return this.client.deployments.setProtection(this.data.id, input);
+    }
+    protection() {
+        return this.client.deployments.protection(this.data.id);
+    }
+    createProtectionSession() {
+        return this.client.deployments.createProtectionSession(this.data.id);
+    }
+    disableProtection() {
+        return this.client.deployments.disableProtection(this.data.id);
+    }
+    setFeedback(input) {
+        return this.client.deployments.setFeedback(this.data.id, input);
+    }
+    domains() {
+        return this.client.deployments.listDomains(this.data.id);
+    }
+    addDomain(input) {
+        return this.client.deployments.createDomain(this.data.id, input);
+    }
+    refreshDomain(domainId) {
+        return this.client.deployments.refreshDomain(this.data.id, domainId);
+    }
+    deleteDomain(domainId) {
+        return this.client.deployments.deleteDomain(this.data.id, domainId);
+    }
+}
+function deploymentStatusIsTerminal(status) {
+    return ['healthy', 'failed', 'stopped', 'deleted', 'delete_failed'].includes(status);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function unwrapDeploymentDomainCollection(input) {
+    if (Array.isArray(input)) {
+        return input;
+    }
+    return Array.isArray(input.data) ? input.data : [];
+}
+function parseNdjsonStream(input) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    return input.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            buffer += decoder.decode(chunk, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed !== '') {
+                    controller.enqueue(JSON.parse(trimmed));
+                }
+            }
+        },
+        flush(controller) {
+            buffer += decoder.decode();
+            const trimmed = buffer.trim();
+            if (trimmed !== '') {
+                controller.enqueue(JSON.parse(trimmed));
+            }
+        },
+    }));
+}

package/dist/index.d.ts

@@ -15,6 +15,7 @@ import Git, { GitActions, GitCredentials, GitEvents } from './git.js';
 import { Disposable } from './types.js';
 import { Beacon, BeaconOptions } from './beacon/index.js';
 import { NotebookUnavailableError } from './errors/index.js';
+import { DeploymentApi, NotebookDeploymentApi, type DeployInput, type DeploymentInstance } from './deployments.js';
 export * from './types.js';
 export { Transport } from './socket/index.js';
 export * from './lsp.js';
@@ -28,6 +29,7 @@ export * from './config.js';
 export * from './utils/promise.js';
 export * from './beacon/index.js';
 export * from './errors/index.js';
+export * from './deployments.js';
 interface Result<TType extends 'success' | 'error' | 'running', TData extends object> {
     type: TType;
     message: string;
@@ -203,6 +205,8 @@ export declare class ApiError extends Error {
     readonly response: Response;
     readonly body: string;
     readonly status: number;
+    readonly data: unknown;
+    readonly apiMessage?: string;
     constructor(response: Response, body: string);
 }
 export declare class NotebookApi {
@@ -210,6 +214,7 @@ export declare class NotebookApi {
     readonly secrets: NotebookSecretApi;
     readonly preview: NotebookPreviewApi;
     readonly mail: NotebookMailApi;
+    readonly deployments: NotebookDeploymentApi;
     constructor(client: Client);
     create(template: string, input?: Partial<CreateNotebookInput>, init?: boolean): Promise<NotebookInstance>;
     get(id: string): Promise<NotebookInstance>;
@@ -230,6 +235,7 @@ export interface PHPSandboxClientOptions {
 }
 export declare class Client {
     readonly notebook: NotebookApi;
+    readonly deployments: DeploymentApi;
     readonly options: PHPSandboxClientOptions;
     private readonly fetch;
     private readonly baseUrl;
@@ -247,6 +253,7 @@ export declare class Client {
     put<T extends unknown>(path: string, body?: unknown): Promise<{
         data: T;
     }>;
+    stream(path: string): Promise<ReadableStream<Uint8Array>>;
     private makeRequest;
 }
 export declare class PHPSandbox extends Client {
@@ -315,6 +322,7 @@ export declare class NotebookInstance {
     constructor(data: NotebookData, client: Client);
     ready(): Promise<NotebookInitSuccessResult>;
     fork(input?: Partial<ForkNotebookInput>): Promise<NotebookInstance>;
+    deploy(input?: DeployInput): Promise<DeploymentInstance>;
     gitCredentials(): Promise<GitCredentials>;
     delete(): Promise<void>;
     stop(): Promise<void>;

package/dist/index.js

@@ -27,6 +27,7 @@ import EventManager from './events/index.js';
 import Git from './git.js';
 import { createBeacon } from './beacon/index.js';
 import { NotebookUnavailableError } from './errors/index.js';
+import { DeploymentApi, NotebookDeploymentApi } from './deployments.js';
 export * from './types.js';
 export { Transport } from './socket/index.js';
 export * from './lsp.js';
@@ -40,6 +41,7 @@ export * from './config.js';
 export * from './utils/promise.js';
 export * from './beacon/index.js';
 export * from './errors/index.js';
+export * from './deployments.js';
 function normalizeNotebookSecretInputs(input) {
     if (Array.isArray(input)) {
         return input;
@@ -59,18 +61,43 @@ export class NotebookInitError extends Error {
 }
 export class ApiError extends Error {
     constructor(response, body) {
-        super(`PHPSandbox API Error: ${response.status} ${response.statusText} - ${body}`);
+        const data = parseApiErrorBody(body);
+        const apiMessage = apiErrorMessage(data, body);
+        super(`PHPSandbox API Error: ${response.status} ${response.statusText}${apiMessage === '' ? '' : ` - ${apiMessage}`}`);
         this.response = response;
         this.body = body;
         this.status = response.status;
+        this.data = data;
+        this.apiMessage = apiMessage === '' ? undefined : apiMessage;
     }
 }
+function parseApiErrorBody(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+}
+function apiErrorMessage(data, fallback) {
+    if (data !== null && typeof data === 'object') {
+        const record = data;
+        if (typeof record.message === 'string' && record.message.trim() !== '') {
+            return record.message.trim();
+        }
+        if (record.error !== undefined) {
+            return typeof record.error === 'string' ? record.error.trim() : JSON.stringify(record.error);
+        }
+    }
+    return fallback.trim();
+}
 export class NotebookApi {
     constructor(client) {
         this.client = client;
         this.secrets = new NotebookSecretApi(client);
         this.preview = new NotebookPreviewApi(client);
         this.mail = new NotebookMailApi(client);
+        this.deployments = new NotebookDeploymentApi(client);
     }
     async create(template, input = {}, init = true) {
         const response = await this.client.post('/notebook', { template, ...input });
@@ -122,6 +149,7 @@ function normalizeApiBaseUrl(url) {
 export class Client {
     constructor(token, url = 'https://api.phpsandbox.io/v1', options = {}) {
         this.fetch = globalThis.fetch;
+        this.deployments = new DeploymentApi(this);
         this.notebook = new NotebookApi(this);
         this.options = Object.assign({ startClosed: true }, options);
         this.baseUrl = normalizeApiBaseUrl(url);
@@ -146,6 +174,19 @@ export class Client {
     put(path, body) {
         return this.makeRequest('PUT', path, { body: body === undefined ? undefined : JSON.stringify(body) });
     }
+    async stream(path) {
+        const response = await this.fetch(new Request(new URL(path.replace(/^\//, ''), this.baseUrl), {
+            method: 'GET',
+            headers: this.headers,
+        }));
+        if (!response.ok) {
+            throw new ApiError(response, await response.text());
+        }
+        if (!response.body) {
+            throw new Error('PHPSandbox API Error: response body is not readable');
+        }
+        return response.body;
+    }
     async makeRequest(method, path, init) {
         const response = await this.fetch(new Request(new URL(path.replace(/^\//, ''), this.baseUrl), {
             method,
@@ -293,6 +334,9 @@ export class NotebookInstance {
     fork(input = {}) {
         return this.client.notebook.fork(this.data.id, input);
     }
+    deploy(input = {}) {
+        return this.client.notebook.deployments.create(this.data.id, input);
+    }
     gitCredentials() {
         return this.client.notebook.gitCredentials(this.data.id);
     }

package/package.json

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