@phpsandbox/sdk 0.1.19 → 0.2.0

package/dist/publication/notebook.js

@@ -0,0 +1,46 @@
+import { RemoteError } from '../errors/index.js';
+import { PublicationInstance } from './instance.js';
+import { PublicationRun } from './run.js';
+import { PublicationResources } from './resources.js';
+export class NotebookPublication {
+    constructor(notebookId, client) {
+        this.notebookId = notebookId;
+        this.client = client;
+        this.resources = new PublicationResources(client, `${this.path}/publication/resources`);
+    }
+    get path() {
+        return `/notebook/${encodeURIComponent(this.notebookId)}`;
+    }
+    async current() {
+        try {
+            const response = await this.client.get(`${this.path}/publication`);
+            return new PublicationInstance(response.data, this.client, this.notebookId);
+        }
+        catch (error) {
+            if (RemoteError.is(error) && error.status === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async readiness() {
+        return (await this.client.get(`${this.path}/publication/readiness`)).data;
+    }
+    /** Review a publishing plan without committing changes or creating resources. */
+    async prepare(input) {
+        return (await this.client.post(`${this.path}/publication/plan`, input)).data;
+    }
+    async catalog(provider, serverId) {
+        const query = new URLSearchParams({ provider });
+        if (serverId !== undefined) {
+            query.set('serverId', serverId);
+        }
+        return (await this.client.get(`${this.path}/publication/catalog?${query}`))
+            .data;
+    }
+    /** Core validates the plan, prepares source and executes publishing. */
+    async publish(input) {
+        const response = await this.client.post(`${this.path}/publication`, input);
+        return new PublicationRun(new PublicationInstance(response.data, this.client, this.notebookId), this.client).start();
+    }
+}

package/dist/publication/providers/laravel-cloud.d.ts

@@ -0,0 +1,114 @@
+export type LaravelCloudRegion = 'us-east-2' | 'us-east-1' | 'ca-central-1' | 'eu-central-1' | 'eu-west-1' | 'eu-west-2' | 'me-central-1' | 'ap-southeast-1' | 'ap-southeast-2' | 'ap-northeast-1';
+export interface LaravelCloudResourceInput {
+    mode: 'none' | 'reuse' | 'create' | 'external';
+    id?: string;
+    type?: string;
+    version?: string;
+    size?: string;
+    config?: Record<string, string | number | boolean | null>;
+}
+export interface LaravelCloudSetupInput {
+    repositoryAccessConfirmed?: boolean;
+    database?: LaravelCloudResourceInput;
+    cache?: LaravelCloudResourceInput;
+    storage?: LaravelCloudResourceInput;
+    worker?: boolean;
+    scheduler?: boolean;
+    workerPlacement?: 'app' | 'separate';
+    workerSize?: string;
+    buildCommand?: string;
+    deployCommand?: string;
+}
+export interface LaravelCloudCatalogResource {
+    id: string;
+    name: string;
+    region: string | null;
+    type: string | null;
+    status: string | null;
+    clusterId?: string;
+    bucketId?: string;
+    keyName?: string;
+}
+export interface LaravelCloudConfigField {
+    name: string;
+    type: string;
+    required: boolean;
+    nullable?: boolean;
+    description?: string;
+    min?: number;
+    max?: number;
+    enum?: Array<string | number>;
+    example?: string | number;
+}
+export interface LaravelCloudDatabaseType {
+    type: string;
+    label: string;
+    versions: string[];
+    regions: string[];
+    config_schema: LaravelCloudConfigField[];
+}
+export interface LaravelCloudCatalog {
+    regions: Array<{
+        region: string;
+        label: string;
+        flag?: string;
+    }>;
+    databaseTypes: LaravelCloudDatabaseType[];
+    cacheTypes: Array<{
+        type: string;
+        label: string;
+        regions: string[];
+        sizes: Array<string | {
+            value?: string;
+            name?: string;
+            size?: string;
+            label?: string;
+            supports_hibernation?: boolean;
+        }>;
+    }>;
+    databases: LaravelCloudCatalogResource[];
+    caches: LaravelCloudCatalogResource[];
+    storage: LaravelCloudCatalogResource[];
+    pricingUrl: string;
+}
+export interface LaravelCloudSetupState {
+    applicationId?: string;
+    environmentId?: string;
+    applicationManaged?: boolean;
+    environmentManaged?: boolean;
+    databaseId?: string;
+    databaseIdManaged?: boolean;
+    cacheId?: string;
+    cacheIdManaged?: boolean;
+    storageId?: string;
+    storageIdManaged?: boolean;
+    workerId?: string;
+    backgroundInstanceId?: string;
+    backgroundProcessId?: string;
+    configuredAt?: string;
+    retainedResources?: Array<{
+        kind: string;
+        id: string;
+        providerId: string;
+        name: string | null;
+    }>;
+    pendingCreation?: {
+        resource: string;
+        name: string | null;
+        startedAt: string;
+    };
+}
+export interface LaravelCloudProviderData {
+    setup?: LaravelCloudSetupInput;
+    region?: LaravelCloudRegion;
+    repository?: string;
+    branch?: string;
+    expectedCommitSha?: string | null;
+    sourceControlProviderType?: 'github' | 'gitlab' | 'bitbucket';
+}
+export interface LaravelCloudProviderInput {
+    setup?: LaravelCloudSetupInput;
+    region: LaravelCloudRegion;
+}
+/** Keep retained resources when publishing again after removing the Cloud application. */
+export declare function laravelCloudSetupForRepublish(setup?: LaravelCloudSetupInput, state?: LaravelCloudSetupState | null): LaravelCloudSetupInput;

package/dist/publication/providers/laravel-cloud.js

@@ -0,0 +1,13 @@
+/** Keep retained resources when publishing again after removing the Cloud application. */
+export function laravelCloudSetupForRepublish(setup = {}, state = null) {
+    const next = { ...setup };
+    const ids = { database: state?.databaseId, cache: state?.cacheId, storage: state?.storageId };
+    const kinds = ['database', 'cache', 'storage'];
+    for (const kind of kinds) {
+        const id = ids[kind];
+        if (setup[kind]?.mode === 'create' && id) {
+            next[kind] = { mode: 'reuse', id };
+        }
+    }
+    return next;
+}

package/dist/publication/resources.d.ts

@@ -0,0 +1,9 @@
+import type { Client, PaginatedApiResponse } from '../index.js';
+import type { PublicationManagedResource, PublicationResourceListOptions } from './types.js';
+export declare class PublicationResources {
+    private readonly client;
+    private readonly path;
+    constructor(client: Client, path?: string);
+    inspect(id: string): Promise<PublicationManagedResource>;
+    list(options?: PublicationResourceListOptions): Promise<PaginatedApiResponse<PublicationManagedResource>>;
+}

package/dist/publication/resources.js

@@ -0,0 +1,19 @@
+export class PublicationResources {
+    constructor(client, path = '/publication-resources') {
+        this.client = client;
+        this.path = path;
+    }
+    async inspect(id) {
+        return (await this.client.post(`/publication-resources/${encodeURIComponent(id)}/inspect`, {})).data;
+    }
+    async list(options = {}) {
+        const query = new URLSearchParams();
+        for (const [name, value] of Object.entries(options)) {
+            if (value !== undefined) {
+                query.set(name, String(value));
+            }
+        }
+        const suffix = query.size > 0 ? `?${query.toString()}` : '';
+        return this.client.get(`${this.path}${suffix}`);
+    }
+}

package/dist/publication/run.d.ts

@@ -0,0 +1,30 @@
+import type { PublicationProviderName } from './types.js';
+import type { Client } from '../index.js';
+import type { PublishStreamEvent, PublishStreamResult } from '../schemas/publications.js';
+import { PublicationInstance } from './instance.js';
+export declare class PublicationRun<TProvider extends PublicationProviderName = PublicationProviderName> {
+    readonly initial: PublicationInstance<TProvider>;
+    private readonly client;
+    private readonly streamAbort;
+    private started;
+    private completed;
+    private finalError;
+    private finalResult;
+    private resultPromise;
+    private resolveResult;
+    private rejectResult;
+    private readonly bufferedEvents;
+    private readonly subscribers;
+    constructor(initial: PublicationInstance<TProvider>, client: Client);
+    events(): AsyncIterable<PublishStreamEvent>;
+    result(): Promise<PublishStreamResult>;
+    publication(): Promise<PublicationInstance<TProvider>>;
+    start(): this;
+    /** Stop observing this run. Once its stream has attached, the server-side publication continues. */
+    dispose(): void;
+    private subscribe;
+    private consumeStream;
+    private publish;
+    private closeSubscribers;
+    private fail;
+}

package/dist/{publications.js → publication/run.js}

@@ -1,34 +1,5 @@
-import { PublicationEventDataSchema, PublicationLogChunkDataSchema, PublishStreamSseEventNameSchema, PublishStreamSseEventSchema, } from './schemas/publications.js';
-export class PublicationDomains {
-    constructor(client, publicationId) {
-        this.client = client;
-        this.publicationId = publicationId;
-    }
-    async list() {
-        return (await this.client.get(this.path())).data;
-    }
-    async create(hostname) {
-        return (await this.client.post(this.path(), { hostname })).data;
-    }
-    async refresh(id) {
-        return (await this.client.post(`${this.path()}/${encodeURIComponent(id)}/refresh`)).data;
-    }
-    async delete(id) {
-        await this.client.delete(`${this.path()}/${encodeURIComponent(id)}`);
-    }
-    path() {
-        return `/publications/${encodeURIComponent(this.publicationId)}/domains`;
-    }
-}
-export class PublicationApi {
-    constructor(client) {
-        this.client = client;
-    }
-    async get(id) {
-        const response = await this.client.get(`/publications/${id}`);
-        return new PublicationInstance(response.data, this.client);
-    }
-}
+import { PublishStreamSseEventNameSchema, PublishStreamSseEventSchema } from '../schemas/publications.js';
+import { PHPSandboxError } from '../errors/index.js';
 export class PublicationRun {
     constructor(initial, client) {
         this.initial = initial;
@@ -59,6 +30,9 @@ export class PublicationRun {
     }
     result() {
         this.start();
+        if (!this.resultPromise) {
+            throw new PHPSandboxError('Publication stream could not start.');
+        }
         return this.resultPromise;
     }
     async publication() {
@@ -71,7 +45,7 @@ export class PublicationRun {
         }
         const eventStreamUrl = this.initial.data.eventStreamUrl;
         if (!eventStreamUrl) {
-            throw new Error(`Publication ${this.initial.data.id} has no eventStreamUrl for SSE streaming`);
+            throw new PHPSandboxError(`Publication ${this.initial.data.id} has no eventStreamUrl for SSE streaming`);
         }
         this.started = true;
         this.resultPromise = new Promise((resolve, reject) => {
@@ -82,10 +56,11 @@ export class PublicationRun {
         void this.consumeStream(eventStreamUrl);
         return this;
     }
-    /** Stop observing this run; the server-side publication continues. */
+    /** Stop observing this run. Once its stream has attached, the server-side publication continues. */
     dispose() {
-        if (this.completed)
+        if (this.completed) {
             return;
+        }
         const error = new DOMException('Stopped observing publication; deployment continues.', 'AbortError');
         if (!this.started) {
             this.started = true;
@@ -123,12 +98,12 @@ export class PublicationRun {
                 }
             }
             if (!this.finalResult) {
-                throw new Error('Publish stream ended without result');
+                throw new PHPSandboxError('Publish stream ended without result');
             }
             this.closeSubscribers();
         }
         catch (err) {
-            this.fail(err instanceof Error ? err : new Error(String(err)));
+            this.fail(err instanceof Error ? err : new PHPSandboxError(String(err), err));
         }
     }
     publish(event) {
@@ -154,79 +129,6 @@ export class PublicationRun {
         this.subscribers.clear();
     }
 }
-export class PublicationInstance {
-    constructor(data, client, notebookId) {
-        this.data = data;
-        this.client = client;
-        this.notebookId = notebookId;
-        this.domains = new PublicationDomains(client, data.id);
-    }
-    async refresh() {
-        const response = await this.client.get(`/publications/${this.data.id}`);
-        return new PublicationInstance(response.data, this.client, this.notebookId);
-    }
-    async publish() {
-        if (!this.notebookId) {
-            return Promise.reject(new Error('Publishing requires a notebook-scoped publication instance.'));
-        }
-        const response = await this.client.post(`/notebook/${this.notebookId}/publication`);
-        const run = new PublicationRun(new PublicationInstance(response.data, this.client, this.notebookId), this.client);
-        run.start();
-        return run;
-    }
-    async destroy() {
-        await this.client.delete(`/publications/${this.data.id}`);
-    }
-    async wait(options = {}) {
-        const intervalMs = options.intervalMs ?? 1000;
-        const timeoutMs = options.timeoutMs ?? 300000;
-        const startedAt = Date.now();
-        let current = this;
-        while (!publicationStatusIsTerminal(current.data.status)) {
-            if (Date.now() - startedAt > timeoutMs) {
-                throw new Error(`Timed out waiting for publication ${this.data.id}`);
-            }
-            await delay(intervalMs);
-            current = await current.refresh();
-        }
-        return current;
-    }
-    async events() {
-        return parseNdjsonStream(await this.client.stream(`/publications/${this.data.id}/events/stream`), PublicationEventDataSchema);
-    }
-    buildLogs(buildId = this.data.latestBuild?.id ?? '') {
-        if (buildId === '') {
-            return Promise.reject(new Error('Publication has no latest build id'));
-        }
-        return this.client.stream(`/publications/${this.data.id}/builds/${buildId}/logs/stream`)
-            .then((stream) => parseNdjsonStream(stream, PublicationLogChunkDataSchema));
-    }
-    async logs() {
-        return parseNdjsonStream(await this.client.stream(`/publications/${this.data.id}/logs/stream`), PublicationLogChunkDataSchema);
-    }
-    async setProtection(input) {
-        const response = await this.client.put(`/publications/${this.data.id}/protection`, input);
-        return new PublicationInstance(response.data, this.client, this.notebookId);
-    }
-    async protection() {
-        const response = await this.client.get(`/publications/${this.data.id}/protection`);
-        return response.data;
-    }
-    async createProtectionSession() {
-        const response = await this.client.post(`/publications/${this.data.id}/protection/session`);
-        return response.data;
-    }
-    async disableProtection() {
-        const response = await this.client.delete(`/publications/${this.data.id}/protection`);
-        return new PublicationInstance(response.data, this.client, this.notebookId);
-    }
-}
-function publicationStatusIsTerminal(status) {
-    return ['healthy', 'failed', 'stopped', 'deleted', 'delete_failed'].includes(status);
-}
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
 class AsyncPublishEventQueue {
     constructor() {
         this.values = [];
@@ -363,27 +265,3 @@ function parseSSEBlock(block) {
         return { event: eventType, data };
     }
 }
-function parseNdjsonStream(input, schema) {
-    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(schema.parse(JSON.parse(trimmed)));
-                }
-            }
-        },
-        flush(controller) {
-            buffer += decoder.decode();
-            const trimmed = buffer.trim();
-            if (trimmed !== '') {
-                controller.enqueue(schema.parse(JSON.parse(trimmed)));
-            }
-        },
-    }));
-}