@phpsandbox/sdk 0.1.19 → 0.2.0

package/dist/errors/index.d.ts

@@ -36,8 +36,8 @@ export interface HttpResponseDiagnostics {
 }
 export declare class TransportError<TCode extends TransportErrorCode = TransportErrorCode> extends PHPSandboxError {
     readonly code: TCode;
-    readonly response?: HttpResponseDiagnostics;
-    constructor(message: string, code: TCode, cause?: unknown, response?: HttpResponseDiagnostics);
+    readonly response?: HttpResponseDiagnostics | undefined;
+    constructor(message: string, code: TCode, cause?: unknown, response?: HttpResponseDiagnostics | undefined);
     static is(error: unknown): error is TransportError;
     static is<TCode extends TransportErrorCode>(error: unknown, code: TCode): error is TransportError<TCode>;
     is<TExpectedCode extends TransportErrorCode>(code: TExpectedCode): this is this & TransportError<TExpectedCode>;

package/dist/events/index.d.ts

@@ -1,23 +1,29 @@
-import * as MittModule from 'mitt';
+import mitt from 'mitt';
 import type { EventHandlerMap, EventType, Handler } from 'mitt';
 import { Disposable } from '../types.js';
-export interface EventDispatcher {
-    listen: (event: EventType, callback: Handler<unknown>, context?: unknown) => Disposable;
-    once: (event: EventType, callback: Handler<unknown>, context?: unknown) => Disposable;
-    emit: (event: EventType, ...args: unknown[]) => void;
-    removeListener: (event?: EventType, callbackSignature?: Handler<unknown>) => void;
+export interface EventDispatcher<Events extends Record<EventType, unknown> = Record<EventType, unknown>> {
+    listen: <Key extends keyof Events>(event: Key, callback: Handler<Events[Key]>, context?: unknown) => Disposable;
+    once: <Key extends keyof Events>(event: Key, callback: Handler<Events[Key]>, context?: unknown) => Disposable;
+    emit: {
+        <Key extends keyof Events>(event: Key, payload: Events[Key]): void;
+        <Key extends keyof Events>(event: undefined extends Events[Key] ? Key : never): void;
+    };
+    removeListener: <Key extends keyof Events>(event?: Key, callbackSignature?: Handler<Events[Key]>) => void;
 }
-export declare function mittWithOnce<Events extends Record<EventType, unknown>>(all?: EventHandlerMap<Events>): MittModule.Emitter<Events> & {
-    once<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): Disposable;
+export declare function mittWithOnce<Events extends Record<EventType, unknown>>(all?: EventHandlerMap<Events>): mitt.Emitter<Events> & {
+    once: <Key extends keyof Events>(type: Key, fn: Handler<Events[Key]>) => {
+        dispose: () => void;
+    };
 };
-export default class EventManager implements EventDispatcher {
+export default class EventManager<Events extends Record<EventType, unknown> = Record<EventType, unknown>> implements EventDispatcher<Events> {
     private readonly emitter;
-    listen(event: EventType, callback: Handler<unknown>): Disposable;
-    emit(event: EventType, ...data: unknown[]): void;
-    once(event: EventType, callback: Handler<unknown>): Disposable;
-    static make(): EventDispatcher;
+    listen<Key extends keyof Events>(event: Key, callback: Handler<Events[Key]>): Disposable;
+    emit<Key extends keyof Events>(event: Key, payload: Events[Key]): void;
+    emit<Key extends keyof Events>(event: undefined extends Events[Key] ? Key : never): void;
+    once<Key extends keyof Events>(event: Key, callback: Handler<Events[Key]>): Disposable;
+    static make<Events extends Record<EventType, unknown> = Record<EventType, unknown>>(): EventDispatcher<Events>;
     static refresh(): EventDispatcher;
-    removeListener(event?: EventType, callbackSignature?: Handler<unknown>): void;
+    removeListener<Key extends keyof Events>(event?: Key, callbackSignature?: Handler<Events[Key]>): void;
     static createInstance(): EventDispatcher;
-    inspect(): EventHandlerMap<Record<EventType, unknown>>;
+    inspect(): EventHandlerMap<Events>;
 }

package/dist/events/index.js

@@ -1,8 +1,8 @@
-import * as MittModule from 'mitt';
-const createMitt = (MittModule.default ?? MittModule);
+import mitt from 'mitt';
+const createMitt = typeof mitt === 'function' ? mitt : mitt.default;
 export function mittWithOnce(all) {
     const inst = createMitt(all);
-    inst.once = (type, fn) => {
+    const once = (type, fn) => {
         const onceHandler = (event) => {
             inst.off(type, onceHandler);
             fn(event);
@@ -14,7 +14,7 @@ export function mittWithOnce(all) {
             },
         };
     };
-    return inst;
+    return Object.assign(inst, { once });
 }
 export default class EventManager {
     constructor() {
@@ -28,7 +28,7 @@ export default class EventManager {
         return { dispose };
     }
     emit(event, ...data) {
-        this.emitter.emit(event, data.length > 1 ? data : data[0]);
+        this.emitter.emit(event, data[0]);
     }
     once(event, callback) {
         return this.emitter.once(event, callback);
@@ -40,6 +40,10 @@ export default class EventManager {
         return new EventManager();
     }
     removeListener(event, callbackSignature) {
+        if (event === undefined) {
+            this.emitter.all.clear();
+            return;
+        }
         this.emitter.off(event, callbackSignature);
     }
     static createInstance() {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { NotebookPublication } from './publication/index.js';
 import { Filesystem, FilesystemActions, FilesystemEvents } from './filesystem.js';
 import Terminals, { TerminalEvents, TerminalActions, type SpawnOptions } from './terminal.js';
 import Auth, { AuthActions } from './auth.js';
@@ -9,16 +10,16 @@ import Repl, { ReplActions, ReplEvents } from './repl.js';
 import { ShellEvents, ShellActions, type ProcessResult, type ShellProcess } from './shell.js';
 import Services, { ServiceActions, ServiceEvents } from './services.js';
 import Config, { ConfigActions } from './config.js';
-import Git, { GitActions } from './git.js';
+import Git, { GitActions, type GitSyncAuthor } from './git.js';
 import { Disposable } from './types.js';
 import { RemoteError } from './errors/index.js';
-import { PublicationApi, PublicationInstance, PublicationRun, type PublishInput } from './publications.js';
+import { PublicationApi } from './publication/index.js';
 import { ServerApi } from './servers.js';
 import { Feedback } from './feedback.js';
 import { IntegrationApi, SandboxIntegrationApi } from './integrations/index.js';
 export type { Disposable } from './types.js';
 export { LspConnection } from './lsp.js';
-export { FileChangeFilter, FileChangeType, FileType, } from './filesystem.js';
+export { FileChangeFilter, FileChangeType, FileType } from './filesystem.js';
 export type { FileChange, FileContents, FileDeleteOptions, FileDownloadOptions, FileFollowOptions, FileLineRange, FileLineRangeResult, FileListOptions, FileOverwriteOptions, FileResult, FileSearchOptions, FileTailOptions, FileWriteOptions, Filesystem, Stats, TextSearchMatch, TextSearchOptions, TextSearchQuery, TextSearchResult, WatchOptions, } from './filesystem.js';
 export type { PortInfo } from './runtime.js';
 export type { RuntimeLogEntry } from './log.js';
@@ -30,9 +31,9 @@ export type { GitChangedFile, GitCheckoutResult, GitConflict, GitConflictsResult
 export { notebookBuiltinServices, notebookKnownServices } from './services.js';
 export type { NotebookBuiltinServiceName, NotebookKnownServiceName, NotebookServiceCommand, NotebookServiceKind, NotebookServiceName, NotebookServiceSource, NotebookServiceState, NotebookServiceStatus, ServiceLogOptions, ServiceLogStreamOptions, } from './services.js';
 export type { ConfigPortMapping, ProjectConfig } from './config.js';
-export { PHPSandboxError, RemoteError, TransportError, } from './errors/index.js';
+export { PHPSandboxError, RemoteError, TransportError } from './errors/index.js';
 export type { HttpResponseDiagnostics, RemoteErrorCode, RemoteErrorSource, TransportErrorCode, ValidationErrorDetails, } from './errors/index.js';
-export type { BuiltInPublicationProviderName, CloudflareContainersProviderOptions, LaravelCloudProviderData, LaravelCloudProviderInput, LaravelCloudRegion, PublicationBuildData, PublicationBuildStatus, PublicationData, PublicationDomainData, PublicationDomains, PublicationEventData, PublicationInstance, PublicationJurisdiction, PublicationLogChunkData, PublicationLogStream, PublicationPlacement, PublicationProtectionData, PublicationProtectionInput, PublicationProtectionMode, PublicationProtectionSessionData, PublicationProvider, PublicationProviderData, PublicationProviderInput, PublicationProviderInputs, PublicationProviderName, PublicationRegion, PublicationReleaseData, PublicationReleaseStatus, PublicationRun, PublicationSize, PublicationStatus, PublishInput, PublishStreamEvent, PublishStreamLog, PublishStreamPhase, PublishStreamResult, PublishStreamSseEvent, SshServerProviderOptions, UpdatePublicationProtectionInput, } from './publications.js';
+export * from './publication/index.js';
 export type { CreateServerInput, ServerData, ServerInstance, ServerListOptions, ServerSshOptions } from './servers.js';
 export type { ConfigureFeedbackInput, FeedbackData, FeedbackListOptions, FeedbackSource, FeedbackStatus, FeedbackType, FeedbackWidgetConfig, FeedbackWidgetTarget, SubmitFeedbackInput, UpdateFeedbackInput, } from './feedback.js';
 export type { Integration, IntegrationAuthorization, IntegrationAuthorizationType, IntegrationData, IntegrationProvider, IntegrationReference, LinkIntegrationInput, UpdateIntegrationInput, AttachSandboxIntegrationInput, SandboxIntegration, SandboxIntegrationData, SandboxIntegrationEffect, SandboxIntegrationReference, UpdateSandboxIntegrationInput, } from './integrations/index.js';
@@ -133,7 +134,12 @@ export interface NotebookImportInspectionData {
     reason: string | null;
     requiredSecrets: NotebookImportRequiredSecret[];
 }
+export interface NotebookGitConfiguration {
+    /** Set a sandbox default identity, or use null to reset it to the Helfer bot. */
+    author: GitSyncAuthor | null;
+}
 export interface NotebookLifecycleInput {
+    git?: NotebookGitConfiguration;
     persistent?: true;
 }
 export interface CreateNotebookInput extends NotebookLifecycleInput {
@@ -144,6 +150,11 @@ export interface CreateNotebookInput extends NotebookLifecycleInput {
     secrets?: UpsertNotebookSecretItemInput[];
 }
 export type ForkNotebookInput = NotebookLifecycleInput;
+export interface UpdateNotebookInput {
+    title?: string;
+    visibility?: 'public' | 'private' | 'unlisted';
+    git?: NotebookGitConfiguration;
+}
 export interface NotebookPolicyData {
     autoDeleteWhenStale: boolean;
     staleAfterMinutes: number | null;
@@ -330,8 +341,8 @@ declare class ClientImplementation {
     post<T extends unknown>(path: string, body?: unknown): Promise<{
         data: T;
     }>;
-    delete<T extends unknown>(path: string): Promise<{
-        data: T;
+    delete<T>(path: string): Promise<{
+        data: T | undefined;
     }>;
     put<T extends unknown>(path: string, body?: unknown): Promise<{
         data: T;
@@ -341,6 +352,7 @@ declare class ClientImplementation {
     }>;
     stream(path: string): Promise<ReadableStream<Uint8Array>>;
     sse(url: string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    private requireData;
     private makeRequest;
     private fetchResponse;
 }
@@ -365,6 +377,9 @@ export interface NotebookData {
     slug?: string;
     description?: string | null;
     policy?: NotebookPolicyData;
+    git?: {
+        author: GitSyncAuthor;
+    };
 }
 export declare class NotebookInstance {
     #private;
@@ -386,6 +401,7 @@ export declare class NotebookInstance {
     readonly preview: NotebookPreview;
     readonly mail: NotebookMail;
     readonly feedback: Feedback;
+    readonly publication: NotebookPublication;
     private readonly socket;
     private readonly restInvoker;
     private readonly emitter;
@@ -394,9 +410,9 @@ export declare class NotebookInstance {
     private readonly disposables;
     constructor(data: NotebookData, client: Client);
     ready(): Promise<NotebookInitSuccessResult>;
+    /** Update sandbox metadata and Git defaults without restarting it. */
+    update(input: UpdateNotebookInput): Promise<NotebookData>;
     fork(input?: Partial<ForkNotebookInput>): Promise<NotebookInstance>;
-    publication(): Promise<PublicationInstance | null>;
-    publish(input?: PublishInput): Promise<PublicationRun>;
     run(command: string | string[], opts?: SpawnOptions): ShellProcess;
     run(command: string, args: string[], opts?: SpawnOptions): ShellProcess;
     exec(command: string | string[], opts?: SpawnOptions): Promise<ProcessResult>;

package/dist/index.js

@@ -10,6 +10,7 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
 var _NotebookInstance_instances, _NotebookInstance_initPromise, _NotebookInstance_init;
+import { NotebookPublication } from './publication/index.js';
 import { Filesystem } from './filesystem.js';
 import Terminals from './terminal.js';
 import Auth from './auth.js';
@@ -23,17 +24,18 @@ import Config from './config.js';
 import { Transport } from './socket/index.js';
 import EventManager from './events/index.js';
 import Git from './git.js';
-import { PHPSandboxError, RemoteError, TransportError, remoteError, } from './errors/index.js';
-import { PublicationApi, PublicationInstance, PublicationRun, } from './publications.js';
+import { PHPSandboxError, RemoteError, TransportError, remoteError } from './errors/index.js';
+import { PublicationApi } from './publication/index.js';
 import { ServerApi } from './servers.js';
 import { RestRuntimeInvoker } from './runtime/rest.js';
 import { Feedback } from './feedback.js';
 import { IntegrationApi, SandboxIntegrationApi } from './integrations/index.js';
 import { authenticatedRequest } from './http.js';
 export { LspConnection } from './lsp.js';
-export { FileChangeFilter, FileChangeType, FileType, } from './filesystem.js';
+export { FileChangeFilter, FileChangeType, FileType } from './filesystem.js';
 export { notebookBuiltinServices, notebookKnownServices } from './services.js';
-export { PHPSandboxError, RemoteError, TransportError, } from './errors/index.js';
+export { PHPSandboxError, RemoteError, TransportError } from './errors/index.js';
+export * from './publication/index.js';
 function normalizeNotebookSecretInputs(input) {
     if (Array.isArray(input)) {
         return input;
@@ -91,25 +93,25 @@ class ClientImplementation {
             this.fetch = options.fetch;
         }
         this.headers = {
-            'Accept': 'application/json',
-            'Authorization': `Bearer ${token}`,
+            Accept: 'application/json',
+            Authorization: `Bearer ${token}`,
             'Content-Type': 'application/json',
         };
     }
     get(path) {
-        return this.makeRequest('GET', path);
+        return this.requireData(this.makeRequest('GET', path));
     }
     post(path, body) {
-        return this.makeRequest('POST', path, { body: body === undefined ? undefined : JSON.stringify(body) });
+        return this.requireData(this.makeRequest('POST', path, { body: body === undefined ? undefined : JSON.stringify(body) }));
     }
     delete(path) {
         return this.makeRequest('DELETE', path);
     }
     put(path, body) {
-        return this.makeRequest('PUT', path, { body: body === undefined ? undefined : JSON.stringify(body) });
+        return this.requireData(this.makeRequest('PUT', path, { body: body === undefined ? undefined : JSON.stringify(body) }));
     }
     patch(path, body) {
-        return this.makeRequest('PATCH', path, { body: body === undefined ? undefined : JSON.stringify(body) });
+        return this.requireData(this.makeRequest('PATCH', path, { body: body === undefined ? undefined : JSON.stringify(body) }));
     }
     async stream(path) {
         const response = await this.fetchResponse(authenticatedRequest(new URL(path.replace(/^\//, ''), this.baseUrl), {
@@ -129,7 +131,7 @@ class ClientImplementation {
             method: 'GET',
             headers: {
                 ...this.headers,
-                'Accept': 'text/event-stream',
+                Accept: 'text/event-stream',
             },
             ...(signal === undefined ? {} : { signal }),
         }));
@@ -141,6 +143,13 @@ class ClientImplementation {
         }
         return response.body;
     }
+    async requireData(request) {
+        const response = await request;
+        if (response.data === undefined) {
+            throw new TransportError('PHPSandbox API returned no data for a data request.', 'InvalidResponse');
+        }
+        return { ...response, data: response.data };
+    }
     async makeRequest(method, path, init) {
         const response = await this.fetchResponse(authenticatedRequest(new URL(path.replace(/^\//, ''), this.baseUrl), {
             method,
@@ -159,7 +168,10 @@ class ClientImplementation {
         }
         try {
             const payload = JSON.parse(body);
-            if (payload === null || typeof payload !== 'object' || Array.isArray(payload) || !Object.prototype.hasOwnProperty.call(payload, 'data')) {
+            if (payload === null ||
+                typeof payload !== 'object' ||
+                Array.isArray(payload) ||
+                !Object.prototype.hasOwnProperty.call(payload, 'data')) {
                 throw new TransportError('PHPSandbox API returned an invalid success response.', 'InvalidResponse', response);
             }
             return payload;
@@ -234,9 +246,7 @@ export class NotebookInstance {
         this.emitter = EventManager.createInstance();
         if (client.runtimeTransport === 'rest') {
             this.socket = null;
-            this.restInvoker = new RestRuntimeInvoker(data, client.options.fetch ?? globalThis.fetch, runtimeUrlProvider === undefined
-                ? undefined
-                : () => runtimeUrlProvider(data.id));
+            this.restInvoker = new RestRuntimeInvoker(data, client.options.fetch ?? globalThis.fetch, runtimeUrlProvider === undefined ? undefined : () => runtimeUrlProvider(data.id));
         }
         else {
             this.restInvoker = null;
@@ -273,6 +283,7 @@ export class NotebookInstance {
         this.preview = new NotebookPreview(client, this.data.id);
         this.mail = new NotebookMail(client, this.data.id);
         this.feedback = new Feedback(client, this.data.id);
+        this.publication = new NotebookPublication(this.data.id, client);
     }
     async ready() {
         if (this.restInvoker !== null) {
@@ -297,28 +308,16 @@ export class NotebookInstance {
         // Just apply a reasonable timeout for the entire initialization process
         return ready();
     }
+    /** Update sandbox metadata and Git defaults without restarting it. */
+    async update(input) {
+        const response = await this.client.put(`/notebook/${this.data.id}`, input);
+        Object.assign(this.data, response.data);
+        return this.data;
+    }
     async fork(input = {}) {
         const response = await this.client.post(`/notebook/${this.data.id}/fork`, input);
         return new NotebookInstance(response.data, this.client);
     }
-    async publication() {
-        try {
-            const response = await this.client.get(`/notebook/${this.data.id}/publication`);
-            return new PublicationInstance(response.data, this.client, this.data.id);
-        }
-        catch (error) {
-            if (RemoteError.is(error) && error.status === 404) {
-                return null;
-            }
-            throw error;
-        }
-    }
-    async publish(input) {
-        const response = await this.client.post(`/notebook/${this.data.id}/publication`, input);
-        const run = new PublicationRun(new PublicationInstance(response.data, this.client, this.data.id), this.client);
-        run.start();
-        return run;
-    }
     run(command, argsOrOpts = [], opts) {
         if (Array.isArray(argsOrOpts)) {
             return this.shell.run(command, argsOrOpts, opts);
@@ -441,7 +440,11 @@ export class NotebookInstance {
         return disposable;
     }
     onDidBootError(handler) {
-        const disposable = this.realtimeSocket().listen('okra.boot_error', handler);
+        const disposable = this.realtimeSocket().listen('okra.boot_error', (error) => {
+            if (RemoteError.is(error, 'NotebookUnavailable')) {
+                handler(error);
+            }
+        });
         this.disposables.push(disposable);
         return disposable;
     }

package/dist/publication/domains.d.ts

@@ -0,0 +1,17 @@
+import type { Client } from '../index.js';
+import type { PublicationDomainData } from './types.js';
+export declare class PublicationDomains {
+    private readonly client;
+    private readonly publicationId;
+    constructor(client: Client, publicationId: string);
+    list(): Promise<PublicationDomainData[]>;
+    create(hostname: string): Promise<PublicationDomainData>;
+    refresh(id: string): Promise<PublicationDomainData>;
+    /** Sets production APP_URL. Publish again to apply it to the running app. */
+    useAsApplicationUrl(id: string): Promise<{
+        url: string;
+        requiresPublication: boolean;
+    }>;
+    delete(id: string): Promise<void>;
+    private path;
+}

package/dist/publication/domains.js

@@ -0,0 +1,25 @@
+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;
+    }
+    /** Sets production APP_URL. Publish again to apply it to the running app. */
+    async useAsApplicationUrl(id) {
+        return (await this.client.post(`${this.path()}/${encodeURIComponent(id)}/application-url`)).data;
+    }
+    async delete(id) {
+        await this.client.delete(`${this.path()}/${encodeURIComponent(id)}`);
+    }
+    path() {
+        return `/publications/${encodeURIComponent(this.publicationId)}/domains`;
+    }
+}

package/dist/publication/index.d.ts

@@ -0,0 +1,8 @@
+export { NotebookPublication } from './notebook.js';
+export { PublicationApi, PublicationInstance } from './instance.js';
+export { PublicationRun } from './run.js';
+export type * from './types.js';
+export type { BuiltInPublicationProviderName, PublicationStatus, PublicationBuildStatus, PublicationReleaseStatus, PublicationSize, PublicationRegion, PublicationJurisdiction, PublicationProtectionMode, PublicationLogStream, PublicationEventData, PublicationLogChunkData, PublishStreamPhase, PublishStreamLog, PublishStreamResult, PublishStreamEvent, PublishStreamSseEvent, } from '../schemas/publications.js';
+export { laravelCloudSetupForRepublish } from './providers/laravel-cloud.js';
+export { PublicationResources } from './resources.js';
+export { PublicationDomains } from './domains.js';

package/dist/publication/index.js

@@ -0,0 +1,6 @@
+export { NotebookPublication } from './notebook.js';
+export { PublicationApi, PublicationInstance } from './instance.js';
+export { PublicationRun } from './run.js';
+export { laravelCloudSetupForRepublish } from './providers/laravel-cloud.js';
+export { PublicationResources } from './resources.js';
+export { PublicationDomains } from './domains.js';

package/dist/publication/instance.d.ts

@@ -0,0 +1,42 @@
+import type { Client } from '../index.js';
+import type { PublicationEventData, PublicationLogChunkData } from '../schemas/publications.js';
+import type { PublicationProtectionData, LaravelCloudSetupInput, PublicationProviderName, PublicationData, UpdatePublicationProtectionInput, PublicationProtectionSessionData, PublicationDestroyOptions } from './types.js';
+import { PublicationRun } from './run.js';
+import { PublicationResources } from './resources.js';
+import { PublicationDomains } from './domains.js';
+export declare class PublicationApi {
+    private readonly client;
+    readonly resources: PublicationResources;
+    constructor(client: Client);
+    get<TProvider extends PublicationProviderName = PublicationProviderName>(id: string): Promise<PublicationInstance<TProvider>>;
+}
+export declare class PublicationInstance<TProvider extends PublicationProviderName = PublicationProviderName> {
+    readonly data: PublicationData<TProvider>;
+    private readonly client;
+    private readonly notebookId?;
+    readonly domains: PublicationDomains;
+    constructor(data: PublicationData<TProvider>, client: Client, notebookId?: string | undefined);
+    reconcileLaravelCloudResource(resourceId: string): Promise<PublicationInstance<TProvider>>;
+    configureLaravelCloud(setup: LaravelCloudSetupInput): Promise<PublicationInstance<TProvider>>;
+    refresh(): Promise<PublicationInstance<TProvider>>;
+    /** Start or reattach to the current release stream without queuing another release. */
+    follow(): PublicationRun<TProvider>;
+    publish(): Promise<PublicationRun<TProvider>>;
+    destroy(options?: PublicationDestroyOptions): Promise<void>;
+    wait(options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<PublicationInstance<TProvider>>;
+    events(): Promise<ReadableStream<PublicationEventData>>;
+    buildLogs(buildId?: string): Promise<ReadableStream<PublicationLogChunkData>>;
+    logSnapshot(stream: 'build' | 'runtime', limit?: number): Promise<{
+        stream: 'build' | 'runtime';
+        content: string;
+        truncated: boolean;
+    }>;
+    logs(): Promise<ReadableStream<PublicationLogChunkData>>;
+    setProtection(input: UpdatePublicationProtectionInput): Promise<PublicationInstance<TProvider>>;
+    protection(): Promise<PublicationProtectionData>;
+    createProtectionSession(): Promise<PublicationProtectionSessionData>;
+    disableProtection(): Promise<PublicationInstance<TProvider>>;
+}

package/dist/publication/instance.js

@@ -0,0 +1,133 @@
+import { PublicationEventDataSchema, PublicationLogChunkDataSchema } from '../schemas/publications.js';
+import { PHPSandboxError, TransportError } from '../errors/index.js';
+import { PublicationRun } from './run.js';
+import { PublicationResources } from './resources.js';
+import { PublicationDomains } from './domains.js';
+export class PublicationApi {
+    constructor(client) {
+        this.client = client;
+        this.resources = new PublicationResources(client);
+    }
+    async get(id) {
+        const response = await this.client.get(`/publications/${encodeURIComponent(id)}`);
+        return new PublicationInstance(response.data, this.client);
+    }
+}
+export class PublicationInstance {
+    constructor(data, client, notebookId) {
+        this.data = data;
+        this.client = client;
+        this.notebookId = notebookId;
+        this.domains = new PublicationDomains(client, data.id);
+    }
+    async reconcileLaravelCloudResource(resourceId) {
+        const response = await this.client.post(`/publications/${encodeURIComponent(this.data.id)}/laravel-cloud/reconcile`, { resourceId });
+        return new PublicationInstance(response.data, this.client, this.notebookId);
+    }
+    async configureLaravelCloud(setup) {
+        const response = await this.client.put(`/publications/${encodeURIComponent(this.data.id)}/laravel-cloud/setup`, { setup });
+        return new PublicationInstance(response.data, this.client, this.notebookId);
+    }
+    async refresh() {
+        const response = await this.client.get(`/publications/${encodeURIComponent(this.data.id)}`);
+        return new PublicationInstance(response.data, this.client, this.notebookId);
+    }
+    /** Start or reattach to the current release stream without queuing another release. */
+    follow() {
+        return new PublicationRun(this, this.client).start();
+    }
+    async publish() {
+        if (!this.notebookId) {
+            throw new PHPSandboxError('Publishing requires a notebook-scoped publication instance.');
+        }
+        const response = await this.client.post(`/notebook/${encodeURIComponent(this.notebookId)}/publication`);
+        const run = new PublicationRun(new PublicationInstance(response.data, this.client, this.notebookId), this.client);
+        run.start();
+        return run;
+    }
+    async destroy(options = {}) {
+        const query = options.deleteResources ? '?deleteResources=1' : '';
+        await this.client.delete(`/publications/${encodeURIComponent(this.data.id)}${query}`);
+    }
+    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 PHPSandboxError(`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/${encodeURIComponent(this.data.id)}/events/stream`), PublicationEventDataSchema);
+    }
+    buildLogs(buildId = this.data.latestBuild?.id ?? '') {
+        if (buildId === '') {
+            return Promise.reject(new PHPSandboxError('Publication has no latest build id'));
+        }
+        return this.client
+            .stream(`/publications/${encodeURIComponent(this.data.id)}/builds/${encodeURIComponent(buildId)}/logs/stream`)
+            .then((stream) => parseNdjsonStream(stream, PublicationLogChunkDataSchema));
+    }
+    async logSnapshot(stream, limit = 50) {
+        const query = new URLSearchParams({ stream, limit: String(limit) });
+        return (await this.client.get(`/publications/${encodeURIComponent(this.data.id)}/logs?${query}`)).data;
+    }
+    async logs() {
+        return parseNdjsonStream(await this.client.stream(`/publications/${encodeURIComponent(this.data.id)}/logs/stream`), PublicationLogChunkDataSchema);
+    }
+    async setProtection(input) {
+        const response = await this.client.put(`/publications/${encodeURIComponent(this.data.id)}/protection`, input);
+        return new PublicationInstance(response.data, this.client, this.notebookId);
+    }
+    async protection() {
+        const response = await this.client.get(`/publications/${encodeURIComponent(this.data.id)}/protection`);
+        return response.data;
+    }
+    async createProtectionSession() {
+        const response = await this.client.post(`/publications/${encodeURIComponent(this.data.id)}/protection/session`);
+        return response.data;
+    }
+    async disableProtection() {
+        const response = await this.client.delete(`/publications/${encodeURIComponent(this.data.id)}/protection`);
+        if (!response.data) {
+            throw new TransportError('Protection response has no publication data.', 'InvalidResponse');
+        }
+        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));
+}
+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/notebook.d.ts

@@ -0,0 +1,20 @@
+import type { Client } from '../index.js';
+import { PublicationInstance } from './instance.js';
+import { PublicationRun } from './run.js';
+import { PublicationResources } from './resources.js';
+import type { PlannedPublishInput, PublicationPlan, PublicationPlanInput, PublicationProviderName, PublicationReadiness, PublicationResourceCatalog } from './types.js';
+export declare class NotebookPublication {
+    private readonly notebookId;
+    private readonly client;
+    readonly resources: PublicationResources;
+    constructor(notebookId: string, client: Client);
+    private get path();
+    current(): Promise<PublicationInstance | null>;
+    readiness(): Promise<PublicationReadiness>;
+    /** Review a publishing plan without committing changes or creating resources. */
+    prepare<TName extends PublicationProviderName>(input: PublicationPlanInput<TName>): Promise<PublicationPlan<TName>>;
+    catalog(provider: 'laravel-cloud' | 'cloudflare-containers'): Promise<PublicationResourceCatalog>;
+    catalog(provider: 'ssh-server', serverId: string): Promise<PublicationResourceCatalog>;
+    /** Core validates the plan, prepares source and executes publishing. */
+    publish(input?: PlannedPublishInput): Promise<PublicationRun>;
+}