@phpsandbox/sdk 0.1.20 → 0.2.0

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)));
-            }
-        },
-    }));
-}

package/dist/publication/types.d.ts

@@ -0,0 +1,303 @@
+import type { LaravelCloudSetupState, LaravelCloudProviderData, LaravelCloudProviderInput } from './providers/laravel-cloud.js';
+export type * from './providers/laravel-cloud.js';
+import type { PublicationBuildStatus, PublicationJurisdiction, PublicationProtectionMode, PublicationRegion, PublicationReleaseStatus, PublicationSize, PublicationStatus } from '../schemas/publications.js';
+export interface PublicationDestroyOptions {
+    deleteResources?: boolean;
+}
+export interface PublicationPlacement {
+    regions?: PublicationRegion[];
+    jurisdiction?: PublicationJurisdiction;
+}
+export interface PublicationProtectionData {
+    mode: PublicationProtectionMode;
+    enabled: boolean;
+    supported?: boolean;
+    token?: string;
+    expiresAt?: string;
+    url?: string;
+}
+export type PublicationProtectionInput = {
+    mode: 'none';
+    password?: never;
+} | {
+    mode: 'password';
+    password: string;
+};
+export interface CloudflareContainersProviderOptions {
+    resources?: Partial<Record<PublicationResourceKind, PublicationResourceSelection>>;
+    accountId: string;
+    size?: PublicationSize;
+    sleepAfter?: string;
+    placement?: PublicationPlacement;
+    instances?: number;
+}
+export interface SshServerProviderOptions {
+    serverId: string;
+    resources?: Partial<Record<PublicationResourceKind, PublicationResourceSelection>>;
+}
+export type PublicationResourceKind = 'database' | 'cache' | 'storage' | 'worker' | 'scheduler';
+export interface PublicationRequirement {
+    kind: PublicationResourceKind;
+    required?: boolean;
+    recommended?: boolean;
+    engine?: string;
+    reason?: string;
+}
+export interface PublicationReadiness {
+    repository: string | null;
+    branch: string | null;
+    sourceProvider: string | null;
+    requirements: PublicationRequirement[];
+    productionVariables: string[];
+    missingVariables: string[];
+    warnings: string[];
+}
+export type PublicationResourceMode = 'none' | 'create' | 'reuse' | 'external' | 'enable';
+export interface PublicationResourceSelection {
+    mode: PublicationResourceMode;
+    id?: string;
+    type?: string;
+    version?: string;
+    size?: string;
+    config?: Record<string, string | number | boolean | null>;
+}
+export type PublicationPlanProviderInput<TName extends PublicationProviderName = PublicationProviderName> = {
+    [Name in TName]: {
+        name: Name;
+    } & Partial<PublicationProviderInputs[Name]>;
+}[TName];
+export interface PublicationPlanInput<TName extends PublicationProviderName = PublicationProviderName> {
+    slug?: string;
+    provider: PublicationPlanProviderInput<TName>;
+    requirements?: PublicationRequirement[];
+    resources?: Partial<Record<PublicationResourceKind, PublicationResourceSelection>>;
+}
+export type PlannedPublishInput = PublishInput & Pick<PublicationPlanInput, 'requirements' | 'resources'>;
+export interface PublicationAccessCapabilities {
+    routing: 'platform' | 'provider';
+    protection: boolean;
+    feedback: boolean;
+}
+export interface PublicationCapabilities {
+    source: 'git' | 'workspace';
+    sourceProviders?: string[];
+    resourceCleanup?: boolean;
+    resources: Record<PublicationResourceKind, PublicationResourceMode[]>;
+    access: {
+        managed: PublicationAccessCapabilities;
+        custom: PublicationAccessCapabilities;
+    };
+}
+export interface PublicationCatalogConfigField {
+    name: string;
+    type: string;
+    required: boolean;
+    label?: string;
+    nullable?: boolean;
+    description?: string;
+    min?: number;
+    max?: number;
+    enum?: Array<string | number>;
+    example?: string | number;
+}
+export interface PublicationCatalogResourceType {
+    kind: PublicationResourceKind;
+    type: string;
+    label: string;
+    versions: string[];
+    regions: string[];
+    sizes: {
+        id: string;
+        label: string;
+    }[];
+    configFields: PublicationCatalogConfigField[];
+}
+export interface PublicationResourceCatalog {
+    provider: PublicationProviderName;
+    scope: string | null;
+    capabilities: PublicationCapabilities;
+    regions: {
+        id: string;
+        label: string;
+        flag?: string;
+    }[];
+    resourceTypes: PublicationCatalogResourceType[];
+    resources: {
+        id: string;
+        name: string;
+        kind: PublicationResourceKind;
+        type: string | null;
+        version: string | null;
+        region: string | null;
+        status: string;
+    }[];
+    pricingUrl: string | null;
+}
+export interface PublicationPlan<TName extends PublicationProviderName = PublicationProviderName> {
+    provider: TName;
+    capabilities: PublicationCapabilities;
+    readiness: PublicationReadiness;
+    source: {
+        type: 'git' | 'workspace';
+        repository: string | null;
+        branch: string | null;
+        commitAndPush: boolean;
+        providerAccess: 'verified' | 'confirmed' | 'confirmation_required' | 'not_required';
+    };
+    resources: Array<{
+        kind: PublicationResourceKind;
+        mode: PublicationResourceMode | 'unconfigured';
+        engine: string | null;
+        required: boolean;
+        recommended: boolean;
+        supported: boolean;
+        selection: PublicationResourceSelection | boolean | null;
+    }>;
+    blockers: Array<{
+        code: string;
+        message: string;
+    }>;
+    ready: boolean;
+    input: PublicationPlanInput<TName>;
+    cost: {
+        status: 'unknown';
+        message: string;
+    };
+}
+export interface PublicationDnsInstructions {
+    stage: 'ownership' | 'traffic' | 'connected';
+    records: PublicationDnsRecord[];
+    trafficRecords: PublicationDnsRecord[];
+}
+export interface PublicationProviderInputs {
+    'cloudflare-containers': CloudflareContainersProviderOptions;
+    'ssh-server': SshServerProviderOptions;
+    'laravel-cloud': LaravelCloudProviderInput;
+}
+export interface PublicationProviderData {
+    'cloudflare-containers': CloudflareContainersProviderOptions;
+    'ssh-server': SshServerProviderOptions;
+    'laravel-cloud': LaravelCloudProviderData;
+}
+export type PublicationProviderName = Extract<keyof PublicationProviderInputs, string>;
+export type PublicationProviderInput<TName extends PublicationProviderName = PublicationProviderName> = {
+    [Name in TName]: {
+        name: Name;
+    } & PublicationProviderInputs[Name];
+}[TName];
+export type PublicationProvider<TName extends PublicationProviderName = PublicationProviderName> = {
+    [Name in TName]: {
+        name: Name;
+    } & PublicationProviderData[Name];
+}[TName];
+export interface PublishInput<TName extends PublicationProviderName = PublicationProviderName> {
+    slug: string;
+    provider: PublicationProviderInput<TName>;
+    protection?: PublicationProtectionInput;
+    metadata?: Record<string, unknown>;
+}
+export interface PublicationBuildData<TProvider extends PublicationProviderName = PublicationProviderName> {
+    id: string;
+    status: PublicationBuildStatus;
+    strategy: string;
+    provider: PublicationProvider<TProvider>;
+    errorMessage: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export interface PublicationReleaseData {
+    id: string;
+    status: PublicationReleaseStatus;
+    manifest: Record<string, unknown>;
+}
+export interface PublicationData<TProvider extends PublicationProviderName = PublicationProviderName> {
+    capabilities?: PublicationCapabilities;
+    id: string;
+    slug: string;
+    url: string;
+    status: PublicationStatus;
+    strategy: string;
+    provider: PublicationProvider<TProvider>;
+    protection: PublicationProtectionData;
+    eventStreamUrl: string | null;
+    originUrl: string | null;
+    domains?: PublicationDomainData[];
+    setupState?: LaravelCloudSetupState | null;
+    currentRelease?: PublicationReleaseData | null;
+    latestBuild?: PublicationBuildData<TProvider> | null;
+    deployedAt: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface UpdatePublicationProtectionInput {
+    mode: PublicationProtectionMode;
+    password?: string;
+}
+export interface PublicationProtectionSessionData {
+    previewSessionId: string;
+    token: string;
+    expiresAt: string;
+    url: string;
+}
+export interface PublicationDnsRecord {
+    type: string;
+    name: string;
+    value: string;
+    purpose?: 'ownership' | 'certificate' | 'traffic';
+}
+export interface PublicationDomainData {
+    id: string;
+    publicationId: string | null;
+    hostname: string;
+    status: string;
+    provider: string;
+    providerHostnameId: string | null;
+    dns: {
+        type: string | null;
+        name: string | null;
+        value: string | null;
+    };
+    ssl: {
+        status: string | null;
+    };
+    dnsInstructions: PublicationDnsInstructions;
+    validationErrors: unknown[];
+    validationRecords: unknown[];
+    metadata: Record<string, unknown>;
+    verifiedAt: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface PublicationManagedResource {
+    id: string;
+    parentId: string | null;
+    provider: PublicationProviderName;
+    scope: string;
+    providerId: string;
+    kind: 'database' | 'cache' | 'storage';
+    name: string;
+    type: string | null;
+    version: string | null;
+    managed: boolean;
+    status: 'pending' | 'provisioning' | 'available' | 'unknown' | 'retained' | 'deleting' | 'delete_failed' | 'deleted';
+    observation?: {
+        status: 'present' | 'missing' | 'unreachable' | 'unauthorized' | 'unsupported';
+        message: string;
+        checkedAt: string;
+    } | null;
+    attachments: PublicationResourceAttachment[];
+    attachmentCount: number;
+    createdAt: string;
+}
+export interface PublicationResourceListOptions {
+    provider?: PublicationProviderName;
+    kind?: PublicationManagedResource['kind'];
+    type?: string;
+    scope?: string;
+    page?: number;
+}
+export interface PublicationResourceAttachment {
+    notebookId: string | null;
+    publicationId: string | null;
+    detachedAt: string | null;
+}

package/dist/publication/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/rest.d.ts

@@ -7,7 +7,7 @@ export declare class RestRuntimeInvoker {
     private ticket;
     private refreshPromise;
     private readonly notebookId;
-    constructor(data: NotebookData, fetch: typeof globalThis.fetch, refresh?: () => Promise<string>);
+    constructor(data: NotebookData, fetch: typeof globalThis.fetch, refresh?: (() => Promise<string>) | undefined);
     private configure;
     ready(): Promise<NotebookInitSuccessResult>;
     supports(action: string): action is RestRuntimeAction;