@deepraxis/sdk 0.1.1-dev.d775f1e → 0.1.1-dev.da4893e

package/dist/helpers/sandbox-templates.d.ts

@@ -0,0 +1,121 @@
+export interface TemplateBuildLog {
+    timestamp: string;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    step?: string;
+}
+export interface TemplateBuildReason {
+    message: string;
+    step?: string;
+    logEntries?: TemplateBuildLog[];
+}
+export interface TemplateBuildStatus {
+    templateID: string;
+    buildID: string;
+    status: 'waiting' | 'building' | 'ready' | 'error';
+    logEntries: TemplateBuildLog[];
+    logs: string[];
+    reason?: TemplateBuildReason;
+}
+export type SandboxTemplateBuildInput = {
+    /** Organization-local name. Reusing it reserves another build of the same template. */
+    name: string;
+    /** Optional resource counts; defaults to 2 vCPUs and 1024 MiB. */
+    cpuCount?: number;
+    memoryMB?: number;
+    /** Disk size in GiB, a positive integer; default 10. */
+    diskGb?: number;
+    /** Labels assigned only after a successful build. */
+    tags?: string[];
+    /** Structured build steps; COPY is rejected. Mutually exclusive with dockerfile. */
+    steps?: {
+        type: 'RUN' | 'ENV' | 'WORKDIR' | 'USER';
+        args: string[];
+    }[];
+    /** Called sequentially for newly read log entries. */
+    onLog?: (entry: TemplateBuildLog) => void | Promise<void>;
+    /** Stops requests and polling; the remote build continues. */
+    signal?: AbortSignal;
+    /** Nonnegative polling delay in milliseconds; default 1000. */
+    pollIntervalMs?: number;
+} & ({
+    dockerfile: string;
+    fromTemplate?: never;
+    fromImage?: never;
+    steps?: never;
+} | {
+    dockerfile?: never;
+    fromTemplate: string;
+    fromImage?: never;
+} | {
+    dockerfile?: never;
+    fromTemplate?: never;
+    fromImage: string;
+});
+export interface SandboxTemplateBuildResult extends TemplateBuildStatus {
+    status: 'ready';
+}
+export declare class SandboxTemplateBuildError extends Error {
+    readonly templateID: string;
+    readonly buildID: string;
+    readonly reason: TemplateBuildReason | undefined;
+    readonly logEntries: readonly TemplateBuildLog[];
+    readonly name = "SandboxTemplateBuildError";
+    constructor(templateID: string, buildID: string, reason: TemplateBuildReason | undefined, logEntries: readonly TemplateBuildLog[]);
+}
+/** Structural port keeps the helper independent of the client that attaches it. */
+export interface SandboxTemplateBuildClient {
+    sandbox: {
+        templates: {
+            create(input: {
+                body: {
+                    name: string;
+                    cpuCount?: number;
+                    memoryMB?: number;
+                    diskGb?: number;
+                    tags?: string[];
+                };
+                signal: AbortSignal;
+            }): Promise<{
+                templateID: string;
+                buildID: string;
+            }>;
+            builds: {
+                update(input: {
+                    path: {
+                        templateID: string;
+                        buildID: string;
+                    };
+                    body: {
+                        dockerfile?: string;
+                        fromTemplate?: string;
+                        fromImage?: string;
+                        steps?: {
+                            type: string;
+                            args: string[];
+                        }[];
+                    };
+                    signal: AbortSignal;
+                }): Promise<unknown>;
+                status: {
+                    list(input: {
+                        path: {
+                            templateID: string;
+                            buildID: string;
+                        };
+                        query: {
+                            logsOffset: number;
+                        };
+                        signal: AbortSignal;
+                    }): Promise<TemplateBuildStatus>;
+                };
+            };
+        };
+    };
+}
+/** Build an organization-local template and wait until it is ready, streaming logs in order.
+ * Uses create, source submission and status polling. COPY is unavailable; use RUN curl or git clone.
+ * fromTemplate accepts official catalog names only. Abort stops the client; it does not cancel the build.
+ * Terminal errors include the provider reason and the final twenty bounded log entries.
+ */
+export declare function buildSandboxTemplate(client: SandboxTemplateBuildClient, input: SandboxTemplateBuildInput): Promise<SandboxTemplateBuildResult>;

package/dist/helpers/sandbox-templates.js

@@ -0,0 +1,60 @@
+import { sleep } from "../core/retry.js";
+export class SandboxTemplateBuildError extends Error {
+    templateID;
+    buildID;
+    reason;
+    logEntries;
+    name = 'SandboxTemplateBuildError';
+    constructor(templateID, buildID, reason, logEntries) {
+        super(`Template build failed: ${reason?.message ?? 'Unknown build error'}${logEntries.length ? `\n${logEntries.map(log => log.message).join('\n')}` : ''}`);
+        this.templateID = templateID;
+        this.buildID = buildID;
+        this.reason = reason;
+        this.logEntries = logEntries;
+    }
+}
+/** Build an organization-local template and wait until it is ready, streaming logs in order.
+ * Uses create, source submission and status polling. COPY is unavailable; use RUN curl or git clone.
+ * fromTemplate accepts official catalog names only. Abort stops the client; it does not cancel the build.
+ * Terminal errors include the provider reason and the final twenty bounded log entries.
+ */
+export async function buildSandboxTemplate(client, input) {
+    const signal = input.signal ?? new AbortController().signal;
+    signal.throwIfAborted();
+    const interval = input.pollIntervalMs ?? 1000;
+    if (!Number.isSafeInteger(interval) || interval < 0)
+        throw new RangeError('pollIntervalMs must be a nonnegative integer');
+    if ([input.dockerfile, input.fromTemplate, input.fromImage].filter(value => value !== undefined).length !== 1
+        || (input.dockerfile !== undefined && input.steps !== undefined))
+        throw new TypeError('Supply dockerfile, fromTemplate or fromImage; dockerfile cannot include steps');
+    const created = await client.sandbox.templates.create({ body: {
+            name: input.name, cpuCount: input.cpuCount, memoryMB: input.memoryMB, diskGb: input.diskGb, tags: input.tags,
+        }, signal });
+    const path = { templateID: created.templateID, buildID: created.buildID };
+    await client.sandbox.templates.builds.update({ path, body: input.dockerfile !== undefined ? { dockerfile: input.dockerfile }
+            : { fromTemplate: input.fromTemplate, fromImage: input.fromImage, steps: input.steps }, signal });
+    let logsOffset = 0;
+    const tail = [];
+    let terminal;
+    while (true) {
+        signal.throwIfAborted();
+        const result = await client.sandbox.templates.builds.status.list({ path, query: { logsOffset }, signal });
+        for (const entry of result.logEntries) {
+            signal.throwIfAborted();
+            await input.onLog?.(entry);
+            // Bound retained diagnostics even when one provider log message is enormous.
+            tail.push({ ...entry, message: entry.message.slice(-4096) });
+            if (tail.length > 20)
+                tail.shift();
+        }
+        logsOffset += result.logEntries.length;
+        if (!terminal && (result.status === 'ready' || result.status === 'error'))
+            terminal = result;
+        if (terminal && result.logEntries.length === 0) {
+            if (terminal.status === 'error')
+                throw new SandboxTemplateBuildError(path.templateID, path.buildID, terminal.reason, tail);
+            return { ...terminal, status: 'ready', logEntries: [] };
+        }
+        await sleep(interval, signal);
+    }
+}

package/dist/index.d.ts

@@ -7,7 +7,13 @@ export { parseSSE } from './core/sse.js';
 export type { SSEEvent, SSEOptions } from './core/sse.js';
 export { publish } from './helpers/application-publish.js';
 export type { PublishInput, PublishResult, AssetsConfig } from './helpers/application-publish.js';
+export { publishInputFromBuild } from './helpers/application-build.js';
+export type { BuildOutput } from './helpers/application-build.js';
 export { count } from './helpers/database-count.js';
 export type { CountInput, CountResult } from './helpers/database-count.js';
 export { uploadFile } from './helpers/file-upload.js';
 export type { UploadFileOptions, UploadedFile } from './helpers/file-upload.js';
+export { connectBrowser } from './helpers/browser-connect.js';
+export type { PraxisBrowser, BrowserTab, BrowserConnectOptions } from './helpers/browser-connect.js';
+export { buildSandboxTemplate, SandboxTemplateBuildError } from './helpers/sandbox-templates.js';
+export type { SandboxTemplateBuildInput, SandboxTemplateBuildResult, TemplateBuildLog, TemplateBuildReason } from './helpers/sandbox-templates.js';

package/dist/index.js

@@ -3,5 +3,8 @@ export { PraxisError, PraxisConnectionError, PraxisTimeoutError } from "./core/e
 export { Page } from "./core/pagination.js";
 export { parseSSE } from "./core/sse.js";
 export { publish } from "./helpers/application-publish.js";
+export { publishInputFromBuild } from "./helpers/application-build.js";
 export { count } from "./helpers/database-count.js";
 export { uploadFile } from "./helpers/file-upload.js";
+export { connectBrowser } from "./helpers/browser-connect.js";
+export { buildSandboxTemplate, SandboxTemplateBuildError } from "./helpers/sandbox-templates.js";