@permute/sdk 0.3.0 → 0.5.0

package/dist/deploy.d.ts

@@ -0,0 +1,20 @@
+import type { PermuteClient } from './client.js';
+import type { AppSiteSaveRequest, PermuteRequestOptions } from './types.js';
+export interface DeployAppOptions {
+    appId: string;
+    directory: string;
+    /** Defaults to true. */
+    spa?: boolean;
+    /** Explicitly approve replacing this exact draft. Omit to require a clean published app. */
+    expectedDraft?: AppSiteSaveRequest['expectedDraft'];
+    /** Omit to preserve bindings; [] removes them. Revisions must already be published. */
+    actions?: AppSiteSaveRequest['actions'];
+    /** Omit to preserve source bindings; [] removes them. */
+    sourceIds?: AppSiteSaveRequest['sourceIds'];
+}
+/** Upload, save, and publish an existing live app. Builds and provisions nothing; never retries mutations. */
+export declare function deployApp(client: PermuteClient, options: DeployAppOptions, requestOptions?: PermuteRequestOptions): Promise<{
+    url: string;
+    revisionId: string;
+    changed: boolean;
+}>;

package/dist/deploy.js

@@ -0,0 +1,143 @@
+import { lstat, readdir, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { Ajv } from 'ajv';
+import { PermuteApiError } from './errors.js';
+import { publicApiRoutes } from './generated/runtime-contract.js';
+const ajv = new Ajv({ strict: false, allErrors: true, validateFormats: false });
+const validateUploads = ajv.compile(publicApiRoutes.appsUploadsCreate.bodySchema);
+const validateSite = ajv.compile(publicApiRoutes.appsSiteUpdate.bodySchema);
+function conflict(message) {
+    throw new PermuteApiError({ status: 409, code: 'deployment_conflict', message });
+}
+/** Node/Bun only. Validate the complete build before making any upload or draft mutation. */
+async function readBuild(directory, body, spa, signal) {
+    const entries = [];
+    const walk = async (absolutePath, path) => {
+        signal?.throwIfAborted();
+        const stat = await lstat(absolutePath);
+        if (stat.isSymbolicLink())
+            throw new Error(`Build contains a symbolic link: ${path || directory}`);
+        if (stat.isDirectory()) {
+            for (const name of (await readdir(absolutePath)).sort()) {
+                await walk(join(absolutePath, name), path ? `${path}/${name}` : name);
+            }
+        }
+        else if (stat.isFile() && path) {
+            entries.push({ path, absolutePath, size: stat.size, sha256: '0'.repeat(64) });
+            if (!validateUploads({ files: entries.map(({ absolutePath: _, ...file }) => file) })) {
+                throw new PermuteApiError({
+                    status: 0,
+                    code: 'invalid_build',
+                    message: 'Build files exceed app limits or contain an unsupported path.',
+                    details: validateUploads.errors,
+                });
+            }
+        }
+        else
+            throw new Error(`Unsupported build entry: ${path || directory}`);
+    };
+    await walk(directory, '');
+    const manifest = entries.map(({ absolutePath: _, ...file }) => file);
+    // JSON Schema cannot express the server's manifest refinements. Check these before uploading.
+    if (!manifest.some((file) => file.path === 'index.html') ||
+        manifest.reduce((total, file) => total + file.size, 0) > 50 * 1024 * 1024 ||
+        new Set(body.actions?.map((action) => action.actionId)).size !== (body.actions?.length ?? 0) ||
+        new Set(body.sourceIds).size !== (body.sourceIds?.length ?? 0) ||
+        !validateSite({ ...body, site: { files: manifest, spa } })) {
+        throw new PermuteApiError({
+            status: 0,
+            code: 'invalid_build',
+            message: 'Invalid app build or bindings. Include index.html, stay within 50 MiB, and use valid app settings.',
+            details: validateSite.errors,
+        });
+    }
+    const files = [];
+    for (const entry of entries) {
+        signal?.throwIfAborted();
+        const file = await open(entry.absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size !== entry.size)
+                throw new Error(`Build changed: ${entry.path}`);
+            const data = Buffer.alloc(entry.size + 1);
+            let length = 0;
+            while (length < data.byteLength) {
+                signal?.throwIfAborted();
+                const { bytesRead } = await file.read(data, length, data.byteLength - length, null);
+                if (!bytesRead)
+                    break;
+                length += bytesRead;
+            }
+            if (length !== entry.size)
+                throw new Error(`Build changed: ${entry.path}`);
+            files.push({ path: entry.path, data: data.subarray(0, length) });
+        }
+        finally {
+            await file.close();
+        }
+    }
+    return files;
+}
+/** Upload, save, and publish an existing live app. Builds and provisions nothing; never retries mutations. */
+export async function deployApp(client, options, requestOptions) {
+    const { appId, directory, spa = true, ...bindings } = structuredClone(options);
+    const app = await client.apps.get(appId, requestOptions);
+    if (app.deployment?.status !== 'live')
+        throw new Error('App hosting must be live before deploying. Inspect client.apps.get(appId).');
+    const history = await client.revisions.list(appId, requestOptions);
+    const expected = bindings.expectedDraft ?? app.draft;
+    if (history.draft?.revisionId !== expected.revisionId ||
+        history.draft.sequence !== expected.sequence ||
+        app.draft.revisionId !== expected.revisionId ||
+        app.draft.sequence !== expected.sequence) {
+        conflict('App draft changed. Read and review it before deploying.');
+    }
+    if (!bindings.expectedDraft && history.draft.revisionId !== history.published?.revisionId) {
+        conflict('App has an unpublished draft. Review it and supply its expectedDraft to replace it.');
+    }
+    const body = { ...bindings, expectedDraft: expected };
+    const files = await readBuild(directory, body, spa, requestOptions?.signal);
+    // Only a clean published draft can be skipped: an approved draft may also contain settings edits.
+    if (history.published && history.draft.revisionId === history.published.revisionId) {
+        const revision = await client.revisions.get(appId, history.published.revisionId, requestOptions);
+        const previous = {
+            expectedDraft: expected,
+            site: revision.value.site,
+            actions: revision.value.actions,
+            sourceIds: revision.value.sourceIds,
+        };
+        const localManifest = files.map(({ path, data }) => ({
+            path,
+            size: data.length,
+            sha256: createHash('sha256').update(data).digest('hex'),
+        }));
+        if (validateSite(previous) &&
+            previous.site.spa === spa &&
+            isDeepStrictEqual(new Map(previous.site.files.map((file) => [file.path, file])), new Map(localManifest.map((file) => [file.path, file]))) &&
+            (bindings.actions === undefined ||
+                isDeepStrictEqual(new Map((previous.actions ?? []).map((action) => [action.actionId, action.revisionId])), new Map(bindings.actions.map((action) => [action.actionId, action.revisionId])))) &&
+            (bindings.sourceIds === undefined ||
+                isDeepStrictEqual(new Set(previous.sourceIds ?? []), new Set(bindings.sourceIds)))) {
+            const current = await client.revisions.list(appId, requestOptions);
+            if (current.version !== history.version)
+                conflict('App changed during inspection. Review the current refs.');
+            return { url: app.deployment.url, revisionId: history.published.revisionId, changed: false };
+        }
+    }
+    const manifest = await client.apps.uploadFiles(appId, files, requestOptions);
+    const saved = await client.apps.saveSite(appId, { ...body, site: { files: manifest, spa } }, requestOptions);
+    const ready = await client.revisions.list(appId, requestOptions);
+    if (ready.draft?.revisionId !== saved.draft.revisionId ||
+        ready.draft.sequence !== saved.draft.sequence ||
+        ready.published?.revisionId !== history.published?.revisionId ||
+        ready.published?.sequence !== history.published?.sequence) {
+        conflict('App changed during deployment. Review the current refs before retrying.');
+    }
+    const published = await client.revisions.publish(appId, { expectedVersion: ready.version }, requestOptions);
+    if (published.published?.revisionId !== saved.draft.revisionId)
+        throw new Error('Publication returned an unexpected revision. Inspect app history before retrying.');
+    return { url: app.deployment.url, revisionId: published.published.revisionId, changed: true };
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export declare class PermuteApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    readonly requestId?: string;
+    constructor(input: {
+        status: number;
+        code: string;
+        message: string;
+        details?: unknown;
+        requestId?: string;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+export class PermuteApiError extends Error {
+    status;
+    code;
+    details;
+    requestId;
+    constructor(input) {
+        super(input.message);
+        this.name = 'PermuteApiError';
+        this.status = input.status;
+        this.code = input.code;
+        this.details = input.details;
+        this.requestId = input.requestId;
+    }
+}