@beeuni/sdk 0.1.0

package/dist/core/session/message-queue.js

@@ -0,0 +1,101 @@
+export function createSessionQueue() {
+    return { pending: [], failed: [], inFlightId: null, inFlightIds: [] };
+}
+function inFlight(state) {
+    if (state.inFlightIds?.length)
+        return state.inFlightIds;
+    return state.inFlightId ? [state.inFlightId] : [];
+}
+export function enqueue(state, input) {
+    return { ...state, pending: [...state.pending, { ...input, attempts: 0 }] };
+}
+export function claimNext(state) {
+    if (inFlight(state).length > 0)
+        return { state };
+    const head = state.pending[0];
+    if (!head)
+        return { state };
+    const claimed = { ...head, attempts: head.attempts + 1 };
+    return {
+        state: {
+            ...state,
+            pending: [claimed, ...state.pending.slice(1)],
+            inFlightId: claimed.id,
+            inFlightIds: [claimed.id],
+        },
+        claimed,
+    };
+}
+export function completeInFlight(state) {
+    const sending = inFlight(state);
+    if (sending.length === 0)
+        return state;
+    return {
+        ...state,
+        pending: state.pending.filter((m) => !sending.includes(m.id)),
+        inFlightId: null,
+        inFlightIds: [],
+    };
+}
+export function failInFlight(state, error) {
+    const sending = inFlight(state);
+    if (sending.length === 0)
+        return state;
+    const items = state.pending.filter((m) => sending.includes(m.id));
+    if (items.length === 0)
+        return { ...state, inFlightId: null, inFlightIds: [] };
+    return {
+        pending: state.pending.filter((m) => !sending.includes(m.id)),
+        failed: [...state.failed, ...items.map((item) => ({ ...item, lastError: error }))],
+        inFlightId: null,
+        inFlightIds: [],
+    };
+}
+export function retryFailed(state, id) {
+    const item = state.failed.find((m) => m.id === id);
+    if (!item)
+        return state;
+    const { lastError: _dropped, ...rest } = item;
+    return {
+        ...state,
+        pending: [...state.pending, rest],
+        failed: state.failed.filter((m) => m.id !== id),
+    };
+}
+export function removeQueued(state, id) {
+    if (inFlight(state).includes(id))
+        return state;
+    if (state.pending.some((m) => m.id === id)) {
+        return { ...state, pending: state.pending.filter((m) => m.id !== id) };
+    }
+    if (state.failed.some((m) => m.id === id)) {
+        return { ...state, failed: state.failed.filter((m) => m.id !== id) };
+    }
+    return state;
+}
+export function editQueued(state, id, text) {
+    if (inFlight(state).includes(id))
+        return state;
+    if (!state.pending.some((m) => m.id === id))
+        return state;
+    return {
+        ...state,
+        pending: state.pending.map((m) => (m.id === id ? { ...m, text } : m)),
+    };
+}
+export function reorderQueued(state, id, toIndex) {
+    const sending = inFlight(state);
+    if (sending.includes(id))
+        return state;
+    const from = state.pending.findIndex((m) => m.id === id);
+    if (from === -1)
+        return state;
+    const first = sending.length;
+    const to = Math.min(Math.max(toIndex, first), state.pending.length - 1);
+    if (to === from)
+        return state;
+    const pending = [...state.pending];
+    const [moved] = pending.splice(from, 1);
+    pending.splice(to, 0, moved);
+    return { ...state, pending };
+}

package/dist/core/session/open-bundle.d.ts

@@ -0,0 +1,24 @@
+import { type SessionAudit, type SessionOpenBundle, type SessionPrompt, type SessionTranscriptSyncEnvelope, type SessionTurn, type SessionTurnEnded, type SessionTurnFailure } from '../rest/projects-client/sessions.js';
+export declare const OPEN_BUNDLE_SHARE_MS = 5000;
+export declare const OPEN_BUNDLE_TRANSCRIPT_TTL_MS = 60000;
+export declare const OPEN_BUNDLE_TRANSCRIPT_LIMIT = 40;
+export declare function resetSessionOpenBundles(): void;
+export interface OpenSessionBundleOptions {
+    transcript?: number;
+    now?: () => number;
+}
+export declare function openSessionBundle(projectId: string, sessionId: string, options?: OpenSessionBundleOptions): void;
+export declare function claimOpenBundle(projectId: string, sessionId: string, nowMs?: number): Promise<SessionOpenBundle | null> | null;
+export declare function settledOpenBundle(projectId: string, sessionId: string, nowMs?: number): SessionOpenBundle | null;
+export interface OpenBundleTurnObservation {
+    turns: SessionTurn[];
+    last_ended: SessionTurnEnded | undefined;
+    recent_failures?: SessionTurnFailure[];
+    atMs: number;
+}
+export declare function openBundleTurn(bundle: SessionOpenBundle): OpenBundleTurnObservation | null;
+export declare function openBundleQueue(bundle: SessionOpenBundle): SessionPrompt[] | null;
+export declare function openBundleAudit(bundle: SessionOpenBundle): SessionAudit | null;
+export declare function openBundleHistory(bundle: SessionOpenBundle): SessionTranscriptSyncEnvelope | null;
+export declare function takeOpenBundleTranscriptAbsence(projectId: string, sessionId: string, nowMs?: number): boolean;
+export declare function takeOpenBundleTranscript(projectId: string, sessionId: string, nowMs?: number): SessionTranscriptSyncEnvelope | null;

package/dist/core/session/open-bundle.js

@@ -0,0 +1,135 @@
+import { getSessionOpenBundle, } from '../rest/projects-client/sessions.js';
+export const OPEN_BUNDLE_SHARE_MS = 5_000;
+export const OPEN_BUNDLE_TRANSCRIPT_TTL_MS = 60_000;
+export const OPEN_BUNDLE_TRANSCRIPT_LIMIT = 40;
+const entries = new Map();
+const transcripts = new Map();
+const absentTranscripts = new Map();
+function scopeKey(projectId, sessionId) {
+    return `${projectId}/${sessionId}`;
+}
+export function resetSessionOpenBundles() {
+    entries.clear();
+    transcripts.clear();
+    absentTranscripts.clear();
+}
+export function openSessionBundle(projectId, sessionId, options = {}) {
+    if (!projectId || !sessionId)
+        return;
+    const now = options.now ?? Date.now;
+    const nowMs = now();
+    const key = scopeKey(projectId, sessionId);
+    const existing = entries.get(key);
+    if (existing && claimable(existing, nowMs))
+        return;
+    const entry = {
+        startedAtMs: nowMs,
+        settledAtMs: null,
+        promise: getSessionOpenBundle(projectId, sessionId, {
+            transcript: options.transcript ?? OPEN_BUNDLE_TRANSCRIPT_LIMIT,
+        })
+            .then((bundle) => {
+            stashTranscript(key, bundle, now());
+            return bundle;
+        })
+            .catch(() => null),
+    };
+    entry.promise = entry.promise.then((bundle) => {
+        entry.settledAtMs = now();
+        entry.bundle = bundle;
+        return bundle;
+    });
+    entries.set(key, entry);
+}
+function claimable(entry, nowMs) {
+    if (entry.settledAtMs === null)
+        return true;
+    return nowMs - entry.settledAtMs <= OPEN_BUNDLE_SHARE_MS;
+}
+export function claimOpenBundle(projectId, sessionId, nowMs = Date.now()) {
+    if (!projectId || !sessionId)
+        return null;
+    const key = scopeKey(projectId, sessionId);
+    const entry = entries.get(key);
+    if (!entry)
+        return null;
+    if (!claimable(entry, nowMs)) {
+        entries.delete(key);
+        return null;
+    }
+    return entry.promise;
+}
+export function settledOpenBundle(projectId, sessionId, nowMs = Date.now()) {
+    const entry = entries.get(scopeKey(projectId, sessionId));
+    return entry && entry.settledAtMs !== null && claimable(entry, nowMs) ? (entry.bundle ?? null) : null;
+}
+export function openBundleTurn(bundle) {
+    const turn = bundle.turn;
+    if (!turn || turn.known !== true)
+        return null;
+    const observedAtMs = Date.parse(bundle.observed_at);
+    return {
+        turns: turn.turns ?? [],
+        last_ended: turn.last_ended,
+        recent_failures: turn.recent_failures,
+        atMs: Number.isFinite(observedAtMs) ? observedAtMs : Date.now(),
+    };
+}
+export function openBundleQueue(bundle) {
+    const queue = bundle.queue;
+    if (!queue || queue.known !== true)
+        return null;
+    return queue.prompts ?? [];
+}
+export function openBundleAudit(bundle) {
+    const audit = bundle.audit;
+    if (!audit || audit.known !== true)
+        return null;
+    return {
+        session_id: audit.session_id,
+        agent: audit.agent,
+        audit_access: audit.audit_access,
+        count: audit.count,
+        actions: audit.actions,
+    };
+}
+export function openBundleHistory(bundle) {
+    const transcript = bundle.transcript;
+    if (!transcript || transcript.known !== true || transcript.requested !== true)
+        return null;
+    const { known: _known, requested: _requested, ...envelope } = transcript;
+    if (!envelope.available)
+        return envelope;
+    const root = bundle.session?.runtime_session_id ?? bundle.session?.opencode_session_id;
+    const savedRoot = envelope.runtime_session_id ?? envelope.opencode_session_id;
+    return root && savedRoot === root ? envelope : null;
+}
+function stashTranscript(key, bundle, nowMs) {
+    const transcript = bundle.transcript;
+    if (!transcript || transcript.known !== true || transcript.requested !== true)
+        return;
+    if (!transcript.available || transcript.messages.length === 0) {
+        absentTranscripts.set(key, nowMs);
+        return;
+    }
+    const { known: _known, requested: _requested, ...envelope } = transcript;
+    transcripts.set(key, { envelope, stashedAtMs: nowMs });
+}
+export function takeOpenBundleTranscriptAbsence(projectId, sessionId, nowMs = Date.now()) {
+    const key = scopeKey(projectId, sessionId);
+    const answeredAtMs = absentTranscripts.get(key);
+    if (answeredAtMs === undefined)
+        return false;
+    absentTranscripts.delete(key);
+    return nowMs - answeredAtMs <= OPEN_BUNDLE_TRANSCRIPT_TTL_MS;
+}
+export function takeOpenBundleTranscript(projectId, sessionId, nowMs = Date.now()) {
+    const key = scopeKey(projectId, sessionId);
+    const stash = transcripts.get(key);
+    if (!stash)
+        return null;
+    transcripts.delete(key);
+    if (nowMs - stash.stashedAtMs > OPEN_BUNDLE_TRANSCRIPT_TTL_MS)
+        return null;
+    return stash.envelope;
+}

package/dist/core/session/poll-owner.d.ts

@@ -0,0 +1,5 @@
+export declare function claimPoller(scope: string, id: string): void;
+export declare function releasePoller(scope: string, id: string): void;
+export declare function isPollOwner(scope: string, id: string): boolean;
+export declare function subscribePollOwner(scope: string, listener: () => void): () => void;
+export declare function resetPollOwners(): void;

package/dist/core/session/poll-owner.js

@@ -0,0 +1,58 @@
+const scopes = new Map();
+function stateFor(scope) {
+    let state = scopes.get(scope);
+    if (!state) {
+        state = { claimants: [], listeners: new Set() };
+        scopes.set(scope, state);
+    }
+    return state;
+}
+function notify(state) {
+    for (const listener of state.listeners)
+        listener();
+}
+function forget(scope, state) {
+    if (state.claimants.length === 0 && state.listeners.size === 0)
+        scopes.delete(scope);
+}
+export function claimPoller(scope, id) {
+    if (!scope || !id)
+        return;
+    const state = stateFor(scope);
+    if (state.claimants.includes(id))
+        return;
+    const wasOwner = state.claimants[0];
+    state.claimants.push(id);
+    if (state.claimants[0] !== wasOwner)
+        notify(state);
+}
+export function releasePoller(scope, id) {
+    const state = scopes.get(scope);
+    if (!state)
+        return;
+    const index = state.claimants.indexOf(id);
+    if (index === -1)
+        return;
+    const wasOwner = state.claimants[0];
+    state.claimants.splice(index, 1);
+    if (state.claimants[0] !== wasOwner)
+        notify(state);
+    forget(scope, state);
+}
+export function isPollOwner(scope, id) {
+    const state = scopes.get(scope);
+    if (!state)
+        return false;
+    return state.claimants[0] === id;
+}
+export function subscribePollOwner(scope, listener) {
+    const state = stateFor(scope);
+    state.listeners.add(listener);
+    return () => {
+        state.listeners.delete(listener);
+        forget(scope, state);
+    };
+}
+export function resetPollOwners() {
+    scopes.clear();
+}

package/dist/core/session/presentation.d.ts

@@ -0,0 +1,11 @@
+export type RuntimePresentationFormat = 'pdf' | 'pptx';
+export declare function buildPresentationTemplatePdfUrl(_backendUrl: string, _templateId: string): string;
+export declare function buildPresentationTemplateImageUrl(_backendUrl: string, _templateId: string): string;
+export declare function buildRuntimePresentationConversionUrl(runtimeUrl: string, format: RuntimePresentationFormat): string;
+export interface ConvertRuntimePresentationOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onGenerating?: () => void;
+}
+export declare function convertRuntimePresentation(format: RuntimePresentationFormat, runtimeUrl: string, presentationPath: string, options?: ConvertRuntimePresentationOptions): Promise<Blob>;

package/dist/core/session/presentation.js

@@ -0,0 +1,70 @@
+import { retiredEndpointError } from '../http/api/errors.js';
+function trimTrailingSlashes(value) {
+    let trimmed = value;
+    while (trimmed.endsWith('/'))
+        trimmed = trimmed.slice(0, -1);
+    return trimmed;
+}
+export function buildPresentationTemplatePdfUrl(_backendUrl, _templateId) {
+    throw retiredEndpointError('buildPresentationTemplatePdfUrl');
+}
+export function buildPresentationTemplateImageUrl(_backendUrl, _templateId) {
+    throw retiredEndpointError('buildPresentationTemplateImageUrl');
+}
+export function buildRuntimePresentationConversionUrl(runtimeUrl, format) {
+    return `${trimTrailingSlashes(runtimeUrl)}/presentation/convert-to-${format}`;
+}
+export async function convertRuntimePresentation(format, runtimeUrl, presentationPath, options) {
+    const endpoint = buildRuntimePresentationConversionUrl(runtimeUrl, format);
+    const pollIntervalMs = options?.pollIntervalMs ?? 2_500;
+    const timeoutMs = options?.timeoutMs ?? 4 * 60_000;
+    const startedAt = Date.now();
+    let notifiedGenerating = false;
+    for (;;) {
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ presentation_path: presentationPath, download: true }),
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+        const contentType = response.headers.get('content-type') || '';
+        const isFile = response.ok &&
+            (contentType.includes('pdf') ||
+                contentType.includes('presentation') ||
+                contentType.includes('octet-stream'));
+        if (isFile) {
+            const blob = await response.blob();
+            if (blob.size === 0)
+                throw new Error('Downloaded file is empty');
+            return blob;
+        }
+        if (response.status === 202) {
+            if (!notifiedGenerating) {
+                notifiedGenerating = true;
+                options?.onGenerating?.();
+            }
+            if (Date.now() - startedAt > timeoutMs) {
+                throw new Error(`Timed out waiting for the ${format.toUpperCase()} to generate`);
+            }
+            await new Promise((resolve, reject) => {
+                const timeout = setTimeout(resolve, pollIntervalMs);
+                options?.signal?.addEventListener('abort', () => {
+                    clearTimeout(timeout);
+                    reject(options.signal?.reason ?? new DOMException('Aborted', 'AbortError'));
+                }, { once: true });
+            });
+            continue;
+        }
+        const text = await response.text().catch(() => '');
+        let detail = response.statusText;
+        try {
+            const json = JSON.parse(text);
+            detail = String(json.error || json.detail || json.message || detail);
+        }
+        catch {
+            if (text)
+                detail = text;
+        }
+        throw new Error(`Failed to download ${format.toUpperCase()}: ${detail} (HTTP ${response.status})`);
+    }
+}

package/dist/core/session/preview-auth.d.ts

@@ -0,0 +1,6 @@
+export declare function ensurePreviewSessionCookie(previewUrl: string, options?: {
+    serverUrl?: string;
+}): Promise<boolean>;
+export declare function authorizePreviewUrl(previewUrl: string, options?: {
+    serverUrl?: string;
+}): Promise<string>;

package/dist/core/session/preview-auth.js

@@ -0,0 +1,36 @@
+import { getAuthToken } from '../http/auth.js';
+import { platformConfig } from '../http/config.js';
+import { appendPreviewToken, buildPreviewAuthEndpoint, isSubdomainPreviewUrl } from './preview.js';
+import { shouldAttachPreviewToken } from './preview-origin-trust.js';
+export async function ensurePreviewSessionCookie(previewUrl, options = {}) {
+    const authEndpoint = buildPreviewAuthEndpoint(previewUrl, options.serverUrl || platformConfig().backendUrl || undefined);
+    if (!authEndpoint)
+        return false;
+    const token = await getAuthToken();
+    if (!token)
+        return false;
+    try {
+        const response = await fetch(authEndpoint, {
+            method: 'POST',
+            credentials: 'include',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function authorizePreviewUrl(previewUrl, options = {}) {
+    if (isSubdomainPreviewUrl(previewUrl)) {
+        if (!(await shouldAttachPreviewToken(previewUrl, options)))
+            return previewUrl;
+        const token = await getAuthToken();
+        return token ? appendPreviewToken(previewUrl, token) : previewUrl;
+    }
+    await ensurePreviewSessionCookie(previewUrl, options);
+    return previewUrl;
+}

package/dist/core/session/preview-config.d.ts

@@ -0,0 +1,5 @@
+export declare function cachedPreviewUrlTemplate(backendUrl: string): string | null;
+export declare function knownPreviewUrlTemplates(): string[];
+export declare function hasPreviewConfig(backendUrl: string): boolean;
+export declare function loadPreviewUrlTemplate(backendUrl: string): Promise<string | null>;
+export declare function resetPreviewConfigCache(): void;

package/dist/core/session/preview-config.js

@@ -0,0 +1,54 @@
+import { backendApi } from '../http/api-client.js';
+const templates = new Map();
+const inFlight = new Map();
+function key(backendUrl) {
+    let end = backendUrl.length;
+    while (end > 0 && backendUrl.charCodeAt(end - 1) === 47)
+        end--;
+    return backendUrl.slice(0, end);
+}
+export function cachedPreviewUrlTemplate(backendUrl) {
+    return templates.get(key(backendUrl)) ?? null;
+}
+export function knownPreviewUrlTemplates() {
+    return [...templates.values()].filter((template) => typeof template === 'string');
+}
+export function hasPreviewConfig(backendUrl) {
+    return templates.has(key(backendUrl));
+}
+export async function loadPreviewUrlTemplate(backendUrl) {
+    const cacheKey = key(backendUrl);
+    const cached = templates.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const pending = inFlight.get(cacheKey);
+    if (pending)
+        return pending;
+    const request = (async () => {
+        try {
+            const response = await backendApi.get('/p/config', {
+                showErrors: false,
+                errorContext: { operation: 'load preview config', silent: true },
+            });
+            if (!response.success)
+                return null;
+            const template = typeof response.data?.preview_url_template === 'string'
+                ? response.data.preview_url_template
+                : null;
+            templates.set(cacheKey, template);
+            return template;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            inFlight.delete(cacheKey);
+        }
+    })();
+    inFlight.set(cacheKey, request);
+    return request;
+}
+export function resetPreviewConfigCache() {
+    templates.clear();
+    inFlight.clear();
+}

package/dist/core/session/preview-options.d.ts

@@ -0,0 +1,9 @@
+import type { SubdomainUrlOptions } from './url.js';
+export interface ResolvedPreviewOptions extends SubdomainUrlOptions {
+    previewUrlTemplate: string | null;
+}
+export declare function resolvePreviewOptions(input: {
+    sandboxId: string;
+    apiBaseUrl: string;
+    backendPort: number;
+}): ResolvedPreviewOptions;

package/dist/core/session/preview-options.js

@@ -0,0 +1,12 @@
+import { cachedPreviewUrlTemplate, hasPreviewConfig, loadPreviewUrlTemplate } from './preview-config.js';
+export function resolvePreviewOptions(input) {
+    const { apiBaseUrl } = input;
+    if (!hasPreviewConfig(apiBaseUrl))
+        void loadPreviewUrlTemplate(apiBaseUrl).catch(() => { });
+    return {
+        sandboxId: input.sandboxId,
+        backendPort: input.backendPort,
+        apiBaseUrl,
+        previewUrlTemplate: cachedPreviewUrlTemplate(apiBaseUrl),
+    };
+}

package/dist/core/session/preview-origin-trust.d.ts

@@ -0,0 +1,7 @@
+export declare function isTrustedPreviewOrigin(candidateUrl: string, input: {
+    templates: readonly string[];
+    backendUrls: readonly string[];
+}): boolean;
+export declare function shouldAttachPreviewToken(previewUrl: string, options?: {
+    serverUrl?: string;
+}): Promise<boolean>;

package/dist/core/session/preview-origin-trust.js

@@ -0,0 +1,64 @@
+import { platformConfig } from '../http/config.js';
+import { isSubdomainPreviewUrl } from './preview.js';
+import { knownPreviewUrlTemplates, loadPreviewUrlTemplate } from './preview-config.js';
+const LOCAL_PREVIEW_HOST = /^p\d{1,5}-[a-z0-9-]+\.localhost$/;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function originMatchesTemplate(origin, template) {
+    if (!template.includes('{port}') || !template.includes('{sandbox}'))
+        return false;
+    const schemeEnd = template.indexOf('://');
+    if (schemeEnd <= 0)
+        return false;
+    const scheme = template.slice(0, schemeEnd).toLowerCase();
+    if (scheme !== 'https' && scheme !== 'http')
+        return false;
+    const authority = (template.slice(schemeEnd + 3).split('/')[0] ?? '').toLowerCase();
+    const source = `${scheme}://${authority}`
+        .split('{port}')
+        .map((part) => part.split('{sandbox}').map(escapeRegExp).join('[a-z0-9-]+'))
+        .join('\\d{1,5}');
+    return new RegExp(`^${source}$`).test(origin);
+}
+function isLocalBackend(backendUrl) {
+    try {
+        const url = new URL(backendUrl);
+        return url.hostname === 'localhost' || url.hostname === '127.0.0.1' ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+function effectivePort(url) {
+    if (url.port)
+        return url.port;
+    return url.protocol === 'https:' ? '443' : '80';
+}
+export function isTrustedPreviewOrigin(candidateUrl, input) {
+    let url;
+    try {
+        url = new URL(candidateUrl);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return false;
+    if (LOCAL_PREVIEW_HOST.test(url.hostname)) {
+        return input.backendUrls.some((backendUrl) => {
+            const backend = isLocalBackend(backendUrl);
+            return backend !== null && effectivePort(backend) === effectivePort(url);
+        });
+    }
+    return input.templates.some((template) => originMatchesTemplate(url.origin, template));
+}
+export async function shouldAttachPreviewToken(previewUrl, options = {}) {
+    if (!isSubdomainPreviewUrl(previewUrl))
+        return false;
+    const backendUrl = platformConfig().backendUrl;
+    if (backendUrl)
+        await loadPreviewUrlTemplate(backendUrl).catch(() => null);
+    const backendUrls = [backendUrl, options.serverUrl].filter((value) => typeof value === 'string' && value.length > 0);
+    return isTrustedPreviewOrigin(previewUrl, { templates: knownPreviewUrlTemplates(), backendUrls });
+}

package/dist/core/session/preview-probe.d.ts

@@ -0,0 +1,7 @@
+export type PreviewPortProbe = 'reachable' | 'unreachable' | 'unknown';
+export declare const PREVIEW_PROBE_TIMEOUT_MS = 3000;
+export declare function classifyPreviewProbeStatus(status: number): PreviewPortProbe;
+export declare function probePreviewPort(previewUrl: string, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<PreviewPortProbe>;

package/dist/core/session/preview-probe.js

@@ -0,0 +1,36 @@
+export const PREVIEW_PROBE_TIMEOUT_MS = 3_000;
+export function classifyPreviewProbeStatus(status) {
+    if (!Number.isFinite(status) || status < 100 || status > 599)
+        return 'unknown';
+    if (status === 502 || status === 503 || status === 504)
+        return 'unreachable';
+    if (status === 401 || status === 403)
+        return 'unknown';
+    return 'reachable';
+}
+export async function probePreviewPort(previewUrl, options) {
+    if (!previewUrl)
+        return 'unknown';
+    if (options?.signal?.aborted)
+        return 'unknown';
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    options?.signal?.addEventListener('abort', abort);
+    const timer = setTimeout(abort, options?.timeoutMs ?? PREVIEW_PROBE_TIMEOUT_MS);
+    try {
+        const res = await fetch(previewUrl, {
+            method: 'HEAD',
+            credentials: 'include',
+            cache: 'no-store',
+            signal: controller.signal,
+        });
+        return classifyPreviewProbeStatus(res.status);
+    }
+    catch {
+        return 'unknown';
+    }
+    finally {
+        clearTimeout(timer);
+        options?.signal?.removeEventListener('abort', abort);
+    }
+}

package/dist/core/session/preview.d.ts

@@ -0,0 +1,3 @@
+export declare function buildPreviewAuthEndpoint(previewUrl: string, serverUrl?: string): string | null;
+export declare function isSubdomainPreviewUrl(candidateUrl: string): boolean;
+export declare function appendPreviewToken(previewUrl: string, token: string): string;