@phpsandbox/sdk 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export type { ConfigPortMapping, ProjectConfig } from './config.js';
 export { PHPSandboxError, RemoteError, TransportError } from './errors/index.js';
 export type { HttpResponseDiagnostics, RemoteErrorCode, RemoteErrorSource, TransportErrorCode, ValidationErrorDetails, } from './errors/index.js';
 export * from './publication/index.js';
-export type { CreateServerInput, ServerData, ServerInstance, ServerListOptions, ServerSshOptions } from './servers.js';
+export type { CreateServerInput, ServerData, ServerInstance, ServerListOptions, ServerMemberData, 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';
 interface Result<TType extends 'success' | 'error' | 'running', TData extends object> {

package/dist/publication/index.d.ts

@@ -6,3 +6,4 @@ export type { BuiltInPublicationProviderName, PublicationStatus, PublicationBuil
 export { laravelCloudSetupForRepublish } from './providers/laravel-cloud.js';
 export { PublicationResources } from './resources.js';
 export { PublicationDomains } from './domains.js';
+export { readPublicationStream, createPublicationStreamResponse } from './stream.js';

package/dist/publication/index.js

@@ -4,3 +4,4 @@ export { PublicationRun } from './run.js';
 export { laravelCloudSetupForRepublish } from './providers/laravel-cloud.js';
 export { PublicationResources } from './resources.js';
 export { PublicationDomains } from './domains.js';
+export { readPublicationStream, createPublicationStreamResponse } from './stream.js';

package/dist/publication/instance.d.ts

@@ -21,6 +21,8 @@ export declare class PublicationInstance<TProvider extends PublicationProviderNa
     refresh(): Promise<PublicationInstance<TProvider>>;
     /** Start or reattach to the current release stream without queuing another release. */
     follow(): PublicationRun<TProvider>;
+    /** Open the original publishing SSE bytes for an authenticated, transparent proxy. */
+    stream(signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
     destroy(options?: PublicationDestroyOptions): Promise<void>;
     wait(options?: {
         intervalMs?: number;

package/dist/publication/instance.js

@@ -36,6 +36,13 @@ export class PublicationInstance {
     follow() {
         return new PublicationRun(this, this.client).start();
     }
+    /** Open the original publishing SSE bytes for an authenticated, transparent proxy. */
+    async stream(signal) {
+        if (!this.data.eventStreamUrl) {
+            throw new PHPSandboxError(`Publication ${this.data.id} has no eventStreamUrl for SSE streaming`);
+        }
+        return this.client.sse(this.data.eventStreamUrl, signal);
+    }
     async destroy(options = {}) {
         const query = options.deleteResources ? '?deleteResources=1' : '';
         await this.client.delete(`/publications/${encodeURIComponent(this.data.id)}${query}`);

package/dist/publication/run.js

@@ -1,4 +1,4 @@
-import { PublishStreamSseEventNameSchema, PublishStreamSseEventSchema } from '../schemas/publications.js';
+import { readPublicationStream } from './stream.js';
 import { PHPSandboxError } from '../errors/index.js';
 export class PublicationRun {
     constructor(initial, client) {
@@ -89,7 +89,7 @@ export class PublicationRun {
     async consumeStream(eventStreamUrl) {
         try {
             const stream = await this.client.sse(eventStreamUrl, this.streamAbort.signal);
-            for await (const event of readPublishStreamEvents(stream)) {
+            for await (const event of readPublicationStream(stream)) {
                 this.publish(event);
                 if (event.type === 'result') {
                     const { type: _, ...result } = event;
@@ -191,77 +191,3 @@ class AsyncPublishEventQueue {
         });
     }
 }
-async function* readPublishStreamEvents(stream) {
-    const reader = parseSSEStream(stream).getReader();
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done) {
-                return;
-            }
-            const event = parsePublishStreamEvent(value);
-            if (event) {
-                yield event;
-            }
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-}
-function parsePublishStreamEvent(event) {
-    if (!PublishStreamSseEventNameSchema.safeParse(event.event).success) {
-        return null;
-    }
-    return PublishStreamSseEventSchema.parse(event);
-}
-function parseSSEStream(input) {
-    const decoder = new TextDecoder();
-    let buffer = '';
-    return input.pipeThrough(new TransformStream({
-        transform(chunk, controller) {
-            buffer += decoder.decode(chunk, { stream: true });
-            const blocks = buffer.split('\n\n');
-            buffer = blocks.pop() ?? '';
-            for (const block of blocks) {
-                const event = parseSSEBlock(block);
-                if (event) {
-                    controller.enqueue(event);
-                }
-            }
-        },
-        flush(controller) {
-            buffer += decoder.decode();
-            if (buffer.trim() !== '') {
-                const event = parseSSEBlock(buffer);
-                if (event) {
-                    controller.enqueue(event);
-                }
-            }
-        },
-    }));
-}
-function parseSSEBlock(block) {
-    let eventType = 'message';
-    let data = '';
-    for (const line of block.split('\n')) {
-        if (line.startsWith('event: ')) {
-            eventType = line.slice(7).trim();
-        }
-        else if (line.startsWith('data: ')) {
-            data += line.slice(6);
-        }
-        else if (line.startsWith('data:')) {
-            data += line.slice(5);
-        }
-    }
-    if (data === '') {
-        return null;
-    }
-    try {
-        return { event: eventType, data: JSON.parse(data) };
-    }
-    catch {
-        return { event: eventType, data };
-    }
-}

package/dist/publication/stream.d.ts

@@ -0,0 +1,18 @@
+import type { PublishStreamEvent } from '../schemas/publications.js';
+export type { PublishStreamEvent } from '../schemas/publications.js';
+/** Consume publishing SSE in browsers or servers, including through an authenticated proxy.
+ * Cancels the source when iteration ends early or parsing fails. Fetch cancellation belongs
+ * to the caller's AbortSignal. Unknown event names and heartbeat comments are ignored.
+ * A complete stream must include a result; set requireResult to false only for fragments.
+ */
+export declare function readPublicationStream(input: Response | ReadableStream<Uint8Array>, options?: {
+    requireResult?: boolean;
+}): AsyncIterable<PublishStreamEvent>;
+/** Forward the original bytes with SSE headers and exactly-once resource cleanup.
+ * Works with Fetch-based servers and frameworks that accept a standard Response.
+ * Does not parse, buffer a replay, or re-encode events. Upstream errors fail the body.
+ */
+export declare function createPublicationStreamResponse(stream: ReadableStream<Uint8Array>, options?: {
+    signal?: AbortSignal;
+    onDispose?: () => void | Promise<void>;
+}): Response;

package/dist/publication/stream.js

@@ -0,0 +1,168 @@
+import { PublishStreamSseEventNameSchema, PublishStreamSseEventSchema } from '../schemas/publications.js';
+import { PHPSandboxError } from '../errors/index.js';
+/** Consume publishing SSE in browsers or servers, including through an authenticated proxy.
+ * Cancels the source when iteration ends early or parsing fails. Fetch cancellation belongs
+ * to the caller's AbortSignal. Unknown event names and heartbeat comments are ignored.
+ * A complete stream must include a result; set requireResult to false only for fragments.
+ */
+export async function* readPublicationStream(input, options = {}) {
+    if (input instanceof Response && (!input.ok || !input.body)) {
+        await input.body?.cancel().catch(() => undefined);
+        throw new PHPSandboxError(`Publishing stream is unavailable (HTTP ${input.status}).`);
+    }
+    const stream = input instanceof Response ? input.body : input;
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let eventName = 'message';
+    let data = [];
+    let ended = false;
+    let receivedResult = false;
+    function dispatch() {
+        const name = eventName;
+        const lines = data;
+        eventName = 'message';
+        data = [];
+        if (!lines.length || !PublishStreamSseEventNameSchema.safeParse(name).success)
+            return null;
+        const raw = lines.join('\n');
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            payload = raw;
+        }
+        const event = PublishStreamSseEventSchema.parse({ event: name, data: payload });
+        if (event.type === 'result')
+            receivedResult = true;
+        return event;
+    }
+    function line(value) {
+        if (value === '')
+            return dispatch();
+        if (value.startsWith(':'))
+            return null;
+        const colon = value.indexOf(':');
+        const field = colon < 0 ? value : value.slice(0, colon);
+        let content = colon < 0 ? '' : value.slice(colon + 1);
+        if (content.startsWith(' '))
+            content = content.slice(1);
+        if (field === 'event')
+            eventName = content;
+        if (field === 'data')
+            data.push(content);
+        return null;
+    }
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+            // A CR at the end of a chunk may be the first half of CRLF.
+            let match;
+            while ((match = /\r\n|\r|\n/.exec(buffer))) {
+                if (!done && match[0] === '\r' && match.index === buffer.length - 1)
+                    break;
+                const event = line(buffer.slice(0, match.index));
+                buffer = buffer.slice(match.index + match[0].length);
+                if (event)
+                    yield event;
+            }
+            if (done) {
+                ended = true;
+                if (buffer) {
+                    const event = line(buffer);
+                    if (event)
+                        yield event;
+                }
+                // Preserve the SDK's support for a final event without a trailing blank line.
+                const event = dispatch();
+                if (event)
+                    yield event;
+                if (options.requireResult !== false && !receivedResult) {
+                    throw new PHPSandboxError('Publish stream ended without result');
+                }
+                return;
+            }
+        }
+    }
+    finally {
+        if (!ended)
+            await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+/** Forward the original bytes with SSE headers and exactly-once resource cleanup.
+ * Works with Fetch-based servers and frameworks that accept a standard Response.
+ * Does not parse, buffer a replay, or re-encode events. Upstream errors fail the body.
+ */
+export function createPublicationStreamResponse(stream, options = {}) {
+    const reader = stream.getReader();
+    let disposed = false;
+    let finished = false;
+    let cancellation;
+    let abort;
+    async function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        options.signal?.removeEventListener('abort', abort);
+        reader.releaseLock();
+        await options.onDispose?.();
+    }
+    function cancel(reason) {
+        return cancellation ?? (cancellation = (async () => {
+            finished = true;
+            try {
+                await reader.cancel(reason);
+            }
+            finally {
+                await dispose();
+            }
+        })());
+    }
+    return new Response(new ReadableStream({
+        start(controller) {
+            abort = () => {
+                controller.error(options.signal.reason);
+                void cancel(options.signal.reason).catch(() => undefined);
+            };
+            if (options.signal?.aborted)
+                abort();
+            else
+                options.signal?.addEventListener('abort', abort, { once: true });
+        },
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (finished)
+                    return;
+                if (done) {
+                    finished = true;
+                    await dispose();
+                    controller.close();
+                }
+                else {
+                    controller.enqueue(value);
+                }
+            }
+            catch (error) {
+                if (finished && cancellation)
+                    return;
+                try {
+                    await cancel(error);
+                }
+                finally {
+                    controller.error(error);
+                }
+            }
+        },
+        cancel,
+    }, { highWaterMark: 0 }), {
+        headers: {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-transform',
+            'X-Accel-Buffering': 'no',
+        },
+    });
+}

package/dist/servers.d.ts

@@ -5,6 +5,7 @@ export interface ServerData {
     host: string;
     provider: string;
     status: string;
+    access: 'owner' | 'deployer';
     token?: string;
     sshPublicKey?: string;
     installCommand?: string;
@@ -12,6 +13,12 @@ export interface ServerData {
     createdAt: string | null;
     updatedAt: string | null;
 }
+export interface ServerMemberData {
+    id: number;
+    name: string;
+    email: string;
+    access: 'deployer';
+}
 export interface ServerSshOptions {
     user?: string;
     port?: number;
@@ -38,6 +45,9 @@ export declare class ServerInstance {
     installation(): Promise<{
         installCommand: string;
     }>;
+    members(options?: ServerListOptions): Promise<PaginatedApiResponse<ServerMemberData>>;
+    share(email: string): Promise<ServerMemberData>;
+    revokeAccess(memberId: number): Promise<void>;
     refresh(): Promise<ServerInstance>;
     delete(): Promise<void>;
     waitReady(options?: {

package/dist/servers.js

@@ -23,6 +23,16 @@ export class ServerInstance {
     async installation() {
         return (await this.client.get(`/servers/${encodeURIComponent(this.data.id)}/installation`)).data;
     }
+    async members(options = {}) {
+        const query = options.page === undefined ? '' : `?${new URLSearchParams({ page: String(options.page) }).toString()}`;
+        return this.client.get(`/servers/${encodeURIComponent(this.data.id)}/members${query}`);
+    }
+    async share(email) {
+        return (await this.client.post(`/servers/${encodeURIComponent(this.data.id)}/members`, { email })).data;
+    }
+    async revokeAccess(memberId) {
+        await this.client.delete(`/servers/${encodeURIComponent(this.data.id)}/members/${encodeURIComponent(String(memberId))}`);
+    }
     refresh() {
         return this.client.servers.get(this.data.id);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "The TypeScript SDK for PHPSandbox cloud development environments",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./stream": {
+      "types": "./dist/publication/stream.d.ts",
+      "import": "./dist/publication/stream.js",
+      "default": "./dist/publication/stream.js"
+    },
     "./beacon": {
       "types": "./dist/beacon/index.d.ts",
       "import": "./dist/beacon/index.js",