@sasjs/api 0.0.0-stage → 0.1.0

package/build/esm/drive/memory-store.js

@@ -0,0 +1,122 @@
+import { ApiError } from '../types.js';
+import { dirname } from './paths.js';
+export class MemoryDriveStore {
+    constructor(seed = {}) {
+        this.files = new Map();
+        this.folders = new Set(['/']);
+        for (const [path, contents] of Object.entries(seed)) {
+            this.putSync(path, contents);
+        }
+    }
+    /** Everything on the drive, for a snapshot or an assertion. */
+    dump() {
+        const out = {};
+        for (const [path, contents] of this.files)
+            out[path] = contents;
+        return out;
+    }
+    putSync(path, contents) {
+        this.mkdirpSync(dirname(path));
+        this.files.set(path, typeof contents === 'string' ? contents : contents.slice());
+    }
+    mkdirpSync(path) {
+        const parts = path.split('/').filter(Boolean);
+        let acc = '';
+        for (const part of parts) {
+            acc += '/' + part;
+            this.folders.add(acc);
+        }
+    }
+    children(path) {
+        const prefix = path === '/' ? '/' : path + '/';
+        const files = [];
+        const folders = [];
+        for (const candidate of this.files.keys()) {
+            if (!candidate.startsWith(prefix))
+                continue;
+            const rest = candidate.slice(prefix.length);
+            if (rest && !rest.includes('/'))
+                files.push(rest);
+        }
+        for (const candidate of this.folders) {
+            if (!candidate.startsWith(prefix))
+                continue;
+            const rest = candidate.slice(prefix.length);
+            if (rest && !rest.includes('/'))
+                folders.push(rest);
+        }
+        return { files: files.sort(), folders: folders.sort() };
+    }
+    async read(path) {
+        const contents = this.files.get(path);
+        if (contents === undefined)
+            throw new ApiError(404, `File doesn't exist.`);
+        return contents;
+    }
+    async write(path, contents) {
+        this.putSync(path, contents);
+    }
+    async exists(path) {
+        return this.files.has(path) || this.folders.has(path);
+    }
+    async stat(path) {
+        if (this.folders.has(path) && !this.files.has(path))
+            return { directory: true, size: 0 };
+        const contents = this.files.get(path);
+        if (contents === undefined)
+            throw new ApiError(404, `File doesn't exist.`);
+        return {
+            directory: false,
+            size: typeof contents === 'string' ? contents.length : contents.length
+        };
+    }
+    async list(path) {
+        return this.children(path);
+    }
+    async mkdirp(path) {
+        this.mkdirpSync(path);
+    }
+    async remove(path) {
+        if (this.files.delete(path))
+            return;
+        const prefix = path === '/' ? '/' : path + '/';
+        for (const candidate of [...this.files.keys()]) {
+            if (candidate.startsWith(prefix))
+                this.files.delete(candidate);
+        }
+        for (const candidate of [...this.folders]) {
+            if (candidate === path || candidate.startsWith(prefix))
+                this.folders.delete(candidate);
+        }
+    }
+    async move(from, to) {
+        const contents = this.files.get(from);
+        if (contents !== undefined) {
+            const copy = typeof contents === 'string' ? contents : contents.slice();
+            this.files.delete(from);
+            this.mkdirpSync(dirname(to));
+            this.files.set(to, copy);
+            return;
+        }
+        // a folder: every entry under it moves by prefix, then the folder records
+        const prefix = from + '/';
+        const moves = [];
+        for (const [candidate, value] of this.files) {
+            if (candidate.startsWith(prefix))
+                moves.push([candidate, to + candidate.slice(from.length), value]);
+        }
+        for (const [source] of moves)
+            this.files.delete(source);
+        for (const [, destination, value] of moves) {
+            this.mkdirpSync(dirname(destination));
+            this.files.set(destination, value);
+        }
+        for (const candidate of [...this.folders]) {
+            if (candidate === from || candidate.startsWith(prefix)) {
+                this.folders.delete(candidate);
+                this.folders.add(to + candidate.slice(from.length));
+            }
+        }
+        this.mkdirpSync(to);
+    }
+}

package/build/esm/drive/paths.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Drive path rules, in one place.
+ *
+ * These are the server's rules, not an invention of this package:
+ * `resolveWithinDrive` in sasjs/server resolves a caller-supplied path against
+ * the drive root and refuses anything that leaves it, and `filePathSchema`
+ * refuses a handful of extensions before a path reaches the drive at all.
+ * Because both hosts now import this file, the rule can only be changed in one
+ * place - which is the point of the package.
+ */
+/** True when the last segment of the path carries a refused extension. */
+export declare const hasBlockedExtension: (path: string) => boolean;
+/**
+ * A caller-supplied path as a drive-relative path, or `null` when it would land
+ * outside the drive.
+ *
+ * The rules, each of which a test pins:
+ *
+ *   - a leading slash means "under the drive root", never filesystem-absolute -
+ *     so `/Public/app/x` and `Public/app/x` are the same destination;
+ *   - a backslash is a separator, because a Windows client sends them;
+ *   - `.` is ignored and `..` pops a segment, so traversal is resolved rather
+ *     than string-matched;
+ *   - a `..` that would pop past the root returns null instead of clamping,
+ *     because a path that escapes is refused, not rewritten;
+ *   - a name that merely starts with dots (`..foo`) is a name, not a traversal.
+ *
+ * The return value starts with '/' (the root is '/'), has no trailing slash.
+ */
+export declare const normaliseDrivePath: (input: unknown) => string | null;
+/** The folder a file path sits in ('/' for a path at the root). */
+export declare const dirname: (path: string) => string;
+/** The last segment of a path. */
+export declare const basename: (path: string) => string;
+/** The drive root itself, which no write may name. */
+export declare const isRoot: (path: string) => boolean;
+/**
+ * The path a file request names, with the blocked-extension rule applied.
+ * Returns the reason rather than a status, so the caller chooses the wording:
+ * a traversal and an extension are both 400s, with different messages.
+ */
+export declare const checkFilePath: (input: unknown) => {
+    path: string;
+} | {
+    reason: "outside";
+} | {
+    reason: "extension";
+};
+//# sourceMappingURL=paths.d.ts.map

package/build/esm/drive/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/drive/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,OACrB,CAAA;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAe5D,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,MAGtC,CAAA;AAED,kCAAkC;AAClC,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,MACD,CAAA;AAEvC,sDAAsD;AACtD,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,OAAuB,CAAA;AAE7D;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,KACb;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,WAAW,CAAA;CAKlE,CAAA"}

package/build/esm/drive/paths.js

@@ -0,0 +1,73 @@
+/**
+ * Drive path rules, in one place.
+ *
+ * These are the server's rules, not an invention of this package:
+ * `resolveWithinDrive` in sasjs/server resolves a caller-supplied path against
+ * the drive root and refuses anything that leaves it, and `filePathSchema`
+ * refuses a handful of extensions before a path reaches the drive at all.
+ * Because both hosts now import this file, the rule can only be changed in one
+ * place - which is the point of the package.
+ */
+/**
+ * Extensions a drive request may not name, on any route (the server's
+ * `blockFileRegex`). Nothing is executable on a browser host, but a client that
+ * would be refused by a server should hear the same answer from the mock.
+ */
+const BLOCKED_EXTENSION = /\.(exe|sh|htaccess)$/i;
+/** True when the last segment of the path carries a refused extension. */
+export const hasBlockedExtension = (path) => BLOCKED_EXTENSION.test(path);
+/**
+ * A caller-supplied path as a drive-relative path, or `null` when it would land
+ * outside the drive.
+ *
+ * The rules, each of which a test pins:
+ *
+ *   - a leading slash means "under the drive root", never filesystem-absolute -
+ *     so `/Public/app/x` and `Public/app/x` are the same destination;
+ *   - a backslash is a separator, because a Windows client sends them;
+ *   - `.` is ignored and `..` pops a segment, so traversal is resolved rather
+ *     than string-matched;
+ *   - a `..` that would pop past the root returns null instead of clamping,
+ *     because a path that escapes is refused, not rewritten;
+ *   - a name that merely starts with dots (`..foo`) is a name, not a traversal.
+ *
+ * The return value starts with '/' (the root is '/'), has no trailing slash.
+ */
+export const normaliseDrivePath = (input) => {
+    const given = typeof input === 'string' ? input : '';
+    const segments = [];
+    for (const segment of given.replace(/\\/g, '/').split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (!segments.length)
+                return null;
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return '/' + segments.join('/');
+};
+/** The folder a file path sits in ('/' for a path at the root). */
+export const dirname = (path) => {
+    const cut = path.lastIndexOf('/');
+    return cut <= 0 ? '/' : path.slice(0, cut);
+};
+/** The last segment of a path. */
+export const basename = (path) => path.slice(path.lastIndexOf('/') + 1);
+/** The drive root itself, which no write may name. */
+export const isRoot = (path) => path === '/';
+/**
+ * The path a file request names, with the blocked-extension rule applied.
+ * Returns the reason rather than a status, so the caller chooses the wording:
+ * a traversal and an extension are both 400s, with different messages.
+ */
+export const checkFilePath = (input) => {
+    const path = normaliseDrivePath(input);
+    if (path === null)
+        return { reason: 'outside' };
+    if (hasBlockedExtension(path))
+        return { reason: 'extension' };
+    return { path };
+};

package/build/esm/drive/service.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The drive, as behaviour rather than storage.
+ *
+ * Every function here is the same decision a SASjs Server makes today - the
+ * status, the message, the order of the checks - with the bytes left to a
+ * `DriveStore` the host supplies. The server passes a store over node's fs; the
+ * browser build passes one over its in-memory drive. Neither re-implements the
+ * rules, which is how the two drifted apart before (sasjs/cli#1542).
+ *
+ * The functions are `async` even though both current stores are synchronous, so
+ * that an async backend later is a store change rather than a signature change
+ * in every consumer.
+ */
+import type { DriveStore, TreeNode } from '../types.js';
+export interface DriveResult {
+    status: 'success';
+}
+export interface DriveListing {
+    files: string[];
+    folders: string[];
+}
+export interface DriveFile {
+    contents: string | Uint8Array;
+    binary: boolean;
+}
+export interface DriveTree {
+    status: 'success';
+    tree: TreeNode;
+}
+export interface DriveService {
+    list(folderPath?: string): Promise<DriveListing>;
+    read(filePath: string): Promise<DriveFile>;
+    save(filePath: string, contents: string | Uint8Array): Promise<DriveResult>;
+    update(filePath: string, contents: string | Uint8Array): Promise<DriveResult>;
+    remove(filePath: string): Promise<DriveResult>;
+    mkdir(folderPath: string): Promise<DriveResult>;
+    rmdir(folderPath: string): Promise<DriveResult>;
+    rename(oldPath: string, newPath: string): Promise<DriveResult>;
+    tree(folderPath?: string): Promise<DriveTree>;
+}
+export declare const createDriveService: (store: DriveStore) => DriveService;
+//# sourceMappingURL=service.d.ts.map

package/build/esm/drive/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/drive/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAUvD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;IAC7B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,EAAE,QAAQ,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAChD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IAC1C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC7E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC9C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/C,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC9D,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;CAC9C;AAqBD,eAAO,MAAM,kBAAkB,GAAI,OAAO,UAAU,KAAG,YA4ItD,CAAA"}

package/build/esm/drive/service.js

@@ -0,0 +1,139 @@
+import { ApiError } from '../types.js';
+import { basename, checkFilePath, dirname, isRoot, normaliseDrivePath } from './paths.js';
+/** A path a file operation may act on, or the refusal the operation answers. */
+const filePath = (input, outside) => {
+    const checked = checkFilePath(input);
+    if ('reason' in checked) {
+        throw checked.reason === 'extension'
+            ? new ApiError(400, 'Invalid file extension')
+            : new ApiError(400, outside);
+    }
+    if (isRoot(checked.path))
+        throw new ApiError(400, outside);
+    return checked.path;
+};
+/** A folder path, which may be the drive root but never an extension check. */
+const folderPath = (input, outside) => {
+    const path = normaliseDrivePath(input);
+    if (path === null)
+        throw new ApiError(400, outside);
+    return path;
+};
+export const createDriveService = (store) => {
+    const treeOf = async (path) => {
+        const listing = await store.list(path);
+        const children = [];
+        for (const folder of listing.folders) {
+            children.push(await treeOf(path === '/' ? '/' + folder : path + '/' + folder));
+        }
+        for (const file of listing.files) {
+            children.push({
+                name: file,
+                relativePath: path === '/' ? '/' + file : path + '/' + file,
+                isFolder: false,
+                children: []
+            });
+        }
+        return {
+            name: path === '/' ? 'files' : basename(path),
+            relativePath: path,
+            isFolder: true,
+            children
+        };
+    };
+    return {
+        async list(given) {
+            // an empty path is the root, which is what the server's GET /folder does
+            // with no `_folderPath`
+            const path = folderPath(given === undefined ? '' : given, "Can't get folder outside drive.");
+            if (!(await store.exists(path)))
+                throw new ApiError(404, `Folder doesn't exist.`);
+            const stat = await store.stat(path);
+            if (!stat.directory)
+                throw new ApiError(400, 'Not a Folder.');
+            const listing = await store.list(path);
+            return {
+                files: [...listing.files].sort(),
+                folders: [...listing.folders].sort()
+            };
+        },
+        async read(given) {
+            const path = filePath(given, "Can't get file outside drive.");
+            if (!(await store.exists(path)))
+                throw new ApiError(404, `File doesn't exist.`);
+            const contents = await store.read(path);
+            return { contents, binary: typeof contents !== 'string' };
+        },
+        async save(given, contents) {
+            const path = filePath(given, "Can't put file outside drive.");
+            if (await store.exists(path))
+                throw new ApiError(409, 'File already exists.');
+            await store.mkdirp(dirname(path));
+            await store.write(path, contents);
+            return { status: 'success' };
+        },
+        async update(given, contents) {
+            const path = filePath(given, "Can't modify file outside drive.");
+            if (!(await store.exists(path)))
+                throw new ApiError(404, `File doesn't exist.`);
+            await store.write(path, contents);
+            return { status: 'success' };
+        },
+        async remove(given) {
+            const path = filePath(given, "Can't delete file outside drive.");
+            if (!(await store.exists(path)))
+                throw new ApiError(404, `File doesn't exist.`);
+            await store.remove(path);
+            return { status: 'success' };
+        },
+        async mkdir(given) {
+            const path = folderPath(given, "Can't put folder outside drive.");
+            if (isRoot(path))
+                throw new ApiError(400, "Can't put folder outside drive.");
+            if (await store.exists(path))
+                throw new ApiError(409, 'Folder already exists.');
+            await store.mkdirp(path);
+            return { status: 'success' };
+        },
+        async rmdir(given) {
+            const path = folderPath(given, "Can't delete folder outside drive.");
+            // the root is the whole drive: refused here as well as at validation,
+            // because a caller reaching this function directly has no validation
+            if (isRoot(path))
+                throw new ApiError(400, "Can't delete folder outside drive.");
+            if (!(await store.exists(path)) || !(await store.stat(path)).directory)
+                throw new ApiError(404, `Folder doesn't exist.`);
+            await store.remove(path);
+            return { status: 'success' };
+        },
+        async rename(oldPath, newPath) {
+            const from = folderPath(oldPath, "Old path can't be outside of drive.");
+            const to = folderPath(newPath, "New path can't be outside of drive.");
+            if (isRoot(from) || isRoot(to))
+                throw new ApiError(400, "New path can't be outside of drive.");
+            if (await store.exists(from)) {
+                const stat = await store.stat(from);
+                // a folder moved inside itself would be an infinite copy, and the
+                // server loses this at the filesystem with an opaque error
+                if (stat.directory && (to === from || to.startsWith(from + '/')))
+                    throw new ApiError(400, "New path can't be inside the folder being moved.");
+                if (await store.exists(to))
+                    throw new ApiError(409, stat.directory
+                        ? 'Folder with new name already exists.'
+                        : 'File with new name already exists.');
+                await store.move(from, to);
+                return { status: 'success' };
+            }
+            throw new ApiError(404, 'No file/folder found for provided path.');
+        },
+        async tree(given) {
+            const path = folderPath(given === undefined ? '' : given, "Can't get folder outside drive.");
+            if (!(await store.exists(path)))
+                throw new ApiError(404, `Folder doesn't exist.`);
+            const stat = await store.stat(path);
+            if (!stat.directory)
+                throw new ApiError(400, 'Not a Folder.');
+            return { status: 'success', tree: await treeOf(path) };
+        }
+    };
+};

package/build/esm/host/dispatch.d.ts

@@ -0,0 +1,24 @@
+import type { DriveService } from '../drive/service.js';
+export interface ApiRequest {
+    query?: Record<string, string | undefined>;
+    body?: Record<string, unknown>;
+    /** The multipart payload: the API names it `file` on every route that takes one. */
+    file?: {
+        name: string;
+        contents: string | Uint8Array;
+    };
+}
+export interface ApiResponse {
+    status: number;
+    /** A JSON body. */
+    body?: unknown;
+    /** A raw body, for the one route that answers with the file itself. */
+    contents?: string | Uint8Array;
+}
+export interface Services {
+    drive: DriveService;
+}
+export declare const dispatch: (services: Services, routeId: string, request?: ApiRequest) => Promise<ApiResponse>;
+/** Whether a route is one `dispatch` can answer today. */
+export declare const HANDLED_ROUTES: string[];
+//# sourceMappingURL=dispatch.d.ts.map

package/build/esm/host/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/host/dispatch.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGvD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,oFAAoF;IACpF,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;CACvD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,YAAY,CAAA;CACpB;AAsCD,eAAO,MAAM,QAAQ,GACnB,UAAU,QAAQ,EAClB,SAAS,MAAM,EACf,UAAS,UAAe,KACvB,OAAO,CAAC,WAAW,CA2DrB,CAAA;AAED,0DAA0D;AAC1D,eAAO,MAAM,cAAc,EAAE,MAAM,EAUlC,CAAA"}

package/build/esm/host/dispatch.js

@@ -0,0 +1,98 @@
+import { routeById } from '../routes/index.js';
+import { ApiError } from '../types.js';
+/**
+ * The parameters the table marks required, checked before the handler runs.
+ *
+ * Multipart fields are deliberately left to the handler: the payload carries the
+ * file itself, and the server words a missing one as `"file" is not present.`
+ * rather than `"file" is required` - a distinction a client may already key on.
+ */
+const validate = (route, request) => {
+    for (const param of route.params) {
+        if (!param.required || param.in === 'formData' || param.in === 'header')
+            continue;
+        // a path parameter comes from the matcher, not from the caller's payload, so
+        // it is the host's job to have supplied it
+        if (param.in === 'path')
+            continue;
+        const given = param.in === 'query'
+            ? request.query?.[param.name]
+            : request.body?.[param.name];
+        if (given === undefined || given === '')
+            throw new ApiError(400, `"${param.name}" is required`);
+    }
+};
+/** The drive path a write names: the query parameter wins over the form field. */
+const targetPath = (request) => {
+    const fromQuery = request.query?._filePath;
+    const fromBody = request.body?.filePath;
+    const path = fromQuery !== undefined
+        ? String(fromQuery)
+        : fromBody;
+    // neither given: the server's validation answers for the query parameter
+    if (path === undefined)
+        throw new ApiError(400, '"_filePath" is required');
+    return path;
+};
+export const dispatch = async (services, routeId, request = {}) => {
+    const route = routeById(routeId);
+    if (!route)
+        throw new ApiError(404, `No such operation: ${routeId}`);
+    validate(route, request);
+    const { drive } = services;
+    const query = request.query || {};
+    switch (routeId) {
+        case 'GET /SASjsApi/drive/file': {
+            const file = await drive.read(String(query._filePath || ''));
+            return { status: 200, contents: file.contents };
+        }
+        case 'POST /SASjsApi/drive/file':
+        case 'PATCH /SASjsApi/drive/file': {
+            if (!request.file)
+                throw new ApiError(400, '"file" is not present.');
+            const path = targetPath(request);
+            const result = routeId === 'PATCH /SASjsApi/drive/file'
+                ? await drive.update(path, request.file.contents)
+                : await drive.save(path, request.file.contents);
+            return { status: 200, body: result };
+        }
+        case 'DELETE /SASjsApi/drive/file':
+            return {
+                status: 200,
+                body: await drive.remove(String(query._filePath || ''))
+            };
+        case 'GET /SASjsApi/drive/folder':
+            return { status: 200, body: await drive.list(query._folderPath) };
+        case 'POST /SASjsApi/drive/folder':
+            return {
+                status: 200,
+                body: await drive.mkdir(String(request.body?.folderPath || ''))
+            };
+        case 'DELETE /SASjsApi/drive/folder':
+            return {
+                status: 200,
+                body: await drive.rmdir(String(query._folderPath || ''))
+            };
+        case 'POST /SASjsApi/drive/rename':
+            return {
+                status: 200,
+                body: await drive.rename(String(request.body?.oldPath || ''), String(request.body?.newPath || ''))
+            };
+        case 'GET /SASjsApi/drive/filetree':
+            return { status: 200, body: await drive.tree(query._folderPath) };
+        default:
+            throw new ApiError(501, `This package has no handler for ${routeId}.`);
+    }
+};
+/** Whether a route is one `dispatch` can answer today. */
+export const HANDLED_ROUTES = [
+    'GET /SASjsApi/drive/file',
+    'POST /SASjsApi/drive/file',
+    'PATCH /SASjsApi/drive/file',
+    'DELETE /SASjsApi/drive/file',
+    'GET /SASjsApi/drive/folder',
+    'POST /SASjsApi/drive/folder',
+    'DELETE /SASjsApi/drive/folder',
+    'POST /SASjsApi/drive/rename',
+    'GET /SASjsApi/drive/filetree'
+];

package/build/esm/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@sasjs/api` - the SASjs Server API described once.
+ *
+ * The package has three parts, and each is usable on its own:
+ *
+ *   - the route table (`ROUTES`, `findRoute`), generated from sasjs/server's
+ *     published OpenAPI document and amended by a reviewed overlay;
+ *   - the services (`createDriveService`), which are the API's decisions over
+ *     storage a host supplies;
+ *   - the conformance corpus (`DRIVE_CORPUS`, `runCase`), which is what "the
+ *     same API" means when a test has to check it.
+ *
+ * It imports no runtime on purpose: the same build runs in an Express server and
+ * in a service worker, so anything node-shaped is a store a host passes in.
+ */
+export * from './types.js';
+export { normaliseDrivePath, hasBlockedExtension, dirname, basename, isRoot } from './drive/paths.js';
+export { createDriveService } from './drive/service.js';
+export type { DriveService, DriveResult, DriveListing, DriveFile, DriveTree } from './drive/service.js';
+export { MemoryDriveStore } from './drive/memory-store.js';
+export { ROUTES, routeById, findRoute } from './routes/index.js';
+export type { RouteMatch } from './routes/index.js';
+export { OVERLAY, TAG_CAPABILITIES } from './routes/overlay.js';
+export type { RouteOverlay } from './routes/overlay.js';
+export { dispatch, HANDLED_ROUTES } from './host/dispatch.js';
+export type { ApiRequest, ApiResponse, Services } from './host/dispatch.js';
+export { DRIVE_CORPUS } from './corpus/drive.js';
+export type { CorpusCase } from './corpus/drive.js';
+export { runCase, servicesFor } from './corpus/runner.js';
+export type { CaseResult } from './corpus/runner.js';
+//# sourceMappingURL=index.d.ts.map

package/build/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,YAAY,CAAA;AAC1B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,OAAO,EACP,QAAQ,EACR,MAAM,EACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAChE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAC7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACzD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA"}

package/build/esm/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@sasjs/api` - the SASjs Server API described once.
+ *
+ * The package has three parts, and each is usable on its own:
+ *
+ *   - the route table (`ROUTES`, `findRoute`), generated from sasjs/server's
+ *     published OpenAPI document and amended by a reviewed overlay;
+ *   - the services (`createDriveService`), which are the API's decisions over
+ *     storage a host supplies;
+ *   - the conformance corpus (`DRIVE_CORPUS`, `runCase`), which is what "the
+ *     same API" means when a test has to check it.
+ *
+ * It imports no runtime on purpose: the same build runs in an Express server and
+ * in a service worker, so anything node-shaped is a store a host passes in.
+ */
+export * from './types.js';
+export { normaliseDrivePath, hasBlockedExtension, dirname, basename, isRoot } from './drive/paths.js';
+export { createDriveService } from './drive/service.js';
+export { MemoryDriveStore } from './drive/memory-store.js';
+export { ROUTES, routeById, findRoute } from './routes/index.js';
+export { OVERLAY, TAG_CAPABILITIES } from './routes/overlay.js';
+export { dispatch, HANDLED_ROUTES } from './host/dispatch.js';
+export { DRIVE_CORPUS } from './corpus/drive.js';
+export { runCase, servicesFor } from './corpus/runner.js';

package/build/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/build/esm/routes/generated.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GENERATED - do not edit.
+ *
+ * Derived from spec/swagger.yaml (sasjs/server's published OpenAPI document) by
+ * scripts/sync-routes.mjs. Run `npm run sync:routes` after replacing that file;
+ * `npm run check:routes` fails the build when the two disagree.
+ *
+ * The overlay in ./overlay.ts adds what a document cannot say: the body each
+ * response carries, which capability a route needs, and whether this package
+ * implements it.
+ */
+import type { GeneratedRoute } from '../types.js';
+export declare const GENERATED_ROUTES: GeneratedRoute[];
+//# sourceMappingURL=generated.d.ts.map

package/build/esm/routes/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../../src/routes/generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,eAAO,MAAM,gBAAgB,EAAE,cAAc,EA+jD5C,CAAA"}