@permute/sdk 0.4.0 → 0.5.0

package/README.md

@@ -442,6 +442,46 @@ Identical contents reuse existing files. Changed contents at the same path are s
 
 Visitors sign in through Permute and need app read permission. HTML receives a revision-specific base URL; use relative URLs for bundled and public assets. Inline scripts, external requests, workers, and server runtimes are not supported. Keep API keys and secrets out of compiled browser files. Restore a historical revision with `client.revisions.restore`, then publish the resulting draft to roll back. See the [complete app guide](https://permute.ai/docs/guides/deploy-app) for creation, directory uploads, updates, and rollback.
 
+### Deploy a build directory (SDK 0.5.0+)
+
+The Node/Bun entry `@permute/sdk/deploy` combines validation, upload, draft save,
+and publication for an existing live app. Available in SDK 0.5.0 and later; the
+individual calls above remain available for separate draft review and publication.
+
+```ts
+import { deployApp } from '@permute/sdk/deploy';
+
+const deployed = await deployApp(client, { appId, directory: './dist' });
+console.log(deployed.url, deployed.revisionId, deployed.changed);
+```
+
+The helper rejects symbolic links, unsupported paths, missing `index.html`, and
+oversized builds before uploading. It requires the current draft to be published;
+after reviewing an existing draft, pass its exact `expectedDraft` to approve
+replacing it. Omitted `actions` and `sourceIds` preserve current bindings (an empty
+array clears them). To change action bindings, supply explicit published revisions:
+
+```ts
+await deployApp(client, {
+  appId,
+  directory: './dist',
+  actions: [{ actionId, revisionId: publishedActionRevisionId }],
+  sourceIds: [databaseId],
+});
+```
+
+An unchanged build returns `changed: false` without uploading, saving, or publishing
+(files, SPA mode, and any supplied bindings must match). It rechecks refs before
+reporting no change. An approved unpublished draft is still published so settings
+edits are preserved. Changed deployments return `changed: true`.
+
+It stops if refs change and never retries mutations. After a failed or lost response,
+inspect app history before retrying: uploads may exist, a draft may be saved, or
+publication may already have completed. `deployment_conflict` requires review;
+`invalid_build` requires fixing the local build. Use the individual calls above
+when saving a draft for later review. The helper does not build, provision, or wait
+for hosting, and must not be imported into browser code.
+
 ### Inside a hosted app
 
 Use the browser entry with the app's existing sign-in session (no API key in frontend code):
@@ -467,6 +507,18 @@ Read scope is source-level; client-supplied SQL is not a row-level authorization
 Keep the same request ID and input when retrying an uncertain action response. The client
 does not retry writes automatically. A 401 requires signing in again.
 
+For recovery across reloads, retain `{ baseUrl: document.baseURI, actionId, request }`
+before sending (using storage appropriate to the input's sensitivity). After sign-in
+or a newer app release, create `new PermuteAppClient({ baseUrl: pending.baseUrl })`
+and invoke `pending.actionId` with `pending.request` as the same user. This keeps
+the original app/action revision as well as the request ID and input. Never store
+session cookies or API credentials with pending requests.
+
+A later 401, 403, or 409 does not prove that an earlier attempt failed to commit.
+Keep an uncertain request until its outcome is reconciled; do not silently clear
+it, change its input, or generate a replacement ID. An edited payload is a new
+operation only after resolving any earlier uncertain write.
+
 ## Business actions
 
 Use `client.actions.create`, `definition`, and `saveDefinition` to author a typed
@@ -476,6 +528,43 @@ handler with selected database tables or connector accounts. Publish with
 requires admin permission. See the [business action guide](https://permute.ai/docs/guides/business-actions)
 for the complete create, save, publish, and invoke workflow.
 
+### Expected failures in handlers
+
+Use `reject(code, message, details?)` for a deliberate business rejection:
+
+```js
+exports.handler = ({ input, db, reject }) => {
+  if (!input.name.trim()) reject('validation_failed', 'Enter a name.', { field: 'name' });
+  db.insert('customers', input);
+  return input;
+};
+```
+
+Rejection stops the handler and discards staged database writes. It cannot undo
+connector calls already sent. Messages and details are public to callers; never
+put credentials or private diagnostic data in them. A rejection message permits
+1–1,000 characters, with up to 20 string detail fields (keys 1–100 characters,
+values up to 500). Invalid rejections and unexpected exceptions return a safe
+`execution_failed` response; exception text stays in server logs.
+
+Both SDK entries expose `PermuteApiError.code`, `.status`, and `.details`.
+Branch on the code (not message text):
+
+| Code                             | HTTP     | Recovery                                                              |
+| -------------------------------- | -------- | --------------------------------------------------------------------- |
+| `validation_failed`              | 400      | Correct input; submit the changed input as a new request.             |
+| `record_conflict`                | 409      | Reload current data and resolve the stale edit.                       |
+| `invalid_transition`             | 409      | Choose an allowed transition from the current state.                  |
+| `permission_denied`, `not_found` | 403, 404 | Check current access or the selected record.                          |
+| `request_conflict`               | 409      | This ID already identifies different input; do not reuse it.          |
+| `request_in_progress`            | 409      | Wait, then retry the identical request.                               |
+| `outcome_unknown`                | 409      | Retain the request ID; inspect external effects before any new write. |
+| `execution_failed`               | 500      | Inspect server logs; retry only with the same request ID and input.   |
+
+Handlers may reject with the first five codes. Transport/authentication failures
+can still use the API's general error codes. A rejection after an external call
+does not establish that nothing happened; reconcile provider state first.
+
 ### Connector bindings
 
 An action definition can bind multiple connector accounts by name alongside its database

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@permute/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TypeScript client for the Permute public API",
   "type": "module",
   "license": "Apache-2.0",
@@ -33,6 +33,11 @@
       "types": "./dist/app.d.ts",
       "import": "./dist/app.js",
       "default": "./dist/app.js"
+    },
+    "./deploy": {
+      "types": "./dist/deploy.d.ts",
+      "import": "./dist/deploy.js",
+      "default": "./dist/deploy.js"
     }
   },
   "publishConfig": {
@@ -53,10 +58,10 @@
   },
   "devDependencies": {
     "@types/bun": "1.3.13",
-    "@types/node": "^24",
+    "@types/node": "^24.19.1",
     "openapi-typescript": "^7.13.0",
     "prettier": "3.6.2",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.11"
   }
 }