nextpluggable 0.0.0-stage → 0.1.0

package/dist/next/plugin-page.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { notFound, redirect } from 'next/navigation';
+import { cache } from 'react';
+import { PluginIsland } from '../client/island.js';
+import { effectivePaths, findPage, normalizePathname } from '../core/routes.js';
+import { prepareClient, publicConfig, runPageLoader } from '../core/runtime.js';
+import { getInstalledPlugins, invalidateInstalledPlugins } from '../core/state.js';
+import { PluginGoneError } from '../errors.js';
+/** The pathname a catch-all route was called with, whatever the segment is named. */
+async function pathnameOf(params) {
+    const values = Object.values(await params);
+    const catchAll = values.find(Array.isArray);
+    if (catchAll)
+        return normalizePathname(catchAll.join('/'));
+    return normalizePathname(typeof values[0] === 'string' ? values[0] : '/');
+}
+export function pluginInfo(cfg, install, page) {
+    return { id: install.id, version: install.manifest.version, apiBase: `${cfg.apiPath}/p/${install.id}`, paths: effectivePaths(install), page };
+}
+export function createPluginPage(getConfig) {
+    // `cache` de-duplicates the work between generateMetadata and the page within one request.
+    const run = cache(async (pathname) => {
+        const attempt = async () => {
+            const cfg = getConfig();
+            const match = findPage(await getInstalledPlugins(cfg), pathname);
+            if (!match)
+                return null;
+            const result = await runPageLoader(cfg, match.install, match.page.id, { path: pathname, params: match.params });
+            return { pathname, match, result, assets: await prepareClient(cfg, match.install) };
+        };
+        try {
+            return await attempt();
+        }
+        catch (e) {
+            if (!(e instanceof PluginGoneError))
+                throw e;
+            // This instance's list of plugins was stale (the plugin was just removed or updated elsewhere): look again.
+            invalidateInstalledPlugins(getConfig());
+            try {
+                return await attempt();
+            }
+            catch (again) {
+                if (again instanceof PluginGoneError)
+                    return null;
+                throw again;
+            }
+        }
+    });
+    // Only `params` is read, never the query string, cookies or headers, so this
+    // route can be statically cached as well as rendered per request.
+    const resolveRequest = async (props) => run(await pathnameOf(props.params));
+    async function generatePluginMetadata(props) {
+        const loaded = await resolveRequest(props);
+        if (!loaded || loaded.result.notFound || loaded.result.redirect)
+            return {};
+        const cfg = getConfig();
+        const meta = loaded.result.metadata ?? {};
+        const title = meta.title ?? loaded.match.page.title;
+        const description = meta.description ?? loaded.match.page.description;
+        const absolute = (value) => {
+            try {
+                return new URL(value, cfg.siteUrl).toString();
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const canonical = absolute(meta.canonical ?? loaded.pathname);
+        const image = meta.image ? absolute(meta.image) : undefined;
+        return {
+            title,
+            description,
+            alternates: canonical ? { canonical } : undefined,
+            openGraph: { title, description, url: canonical, type: 'website', images: image ? [image] : undefined },
+            robots: meta.noindex ? { index: false, follow: false } : undefined,
+        };
+    }
+    /**
+     * Server component for a root catch-all route. Renders the plugin page that
+     * owns the requested address, or the site's 404 when none does.
+     */
+    async function PluginPage(props) {
+        const loaded = await resolveRequest(props);
+        if (!loaded || loaded.result.notFound || !loaded.assets)
+            notFound();
+        const { match, result, pathname, assets } = loaded;
+        if (result.redirect)
+            redirect(result.redirect);
+        const cfg = getConfig();
+        const jsonLd = result.jsonLd ? (Array.isArray(result.jsonLd) ? result.jsonLd : [result.jsonLd]) : [];
+        return (_jsxs(_Fragment, { children: [assets.styleHref ? _jsx("link", { rel: "stylesheet", href: assets.styleHref, precedence: "nextpluggable" }) : null, jsonLd.map((item, i) => (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(item).replace(/</g, '\\u003c') } }, i))), _jsx(PluginIsland, { moduleKey: assets.moduleKey, src: assets.scriptSrc, component: match.page.component, info: pluginInfo(cfg, match.install, { id: match.page.id, path: pathname, params: match.params }), config: publicConfig(match.install), props: { data: result.data ?? {}, params: match.params }, errorFallback: _jsx("p", { style: { padding: '48px 16px', textAlign: 'center' }, children: "This page could not be displayed. Please try again later." }) })] }));
+    }
+    /**
+     * Whether an installed, switched-on plugin serves a page at this address. For sites
+     * whose own catch-all route has to choose between a plugin page and something of its
+     * own: unlike `PluginPage`, it never triggers the site's 404.
+     */
+    async function hasPluginPage(pathname) {
+        return findPage(await getInstalledPlugins(getConfig()), normalizePathname(pathname)) !== null;
+    }
+    return { PluginPage, generatePluginMetadata, hasPluginPage };
+}

package/dist/next/slot.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+import type { ResolvedConfig } from '../config.js';
+export interface SlotProps {
+    /** Slot name, e.g. `header.actions`, `footer`, `body.end`. Plugins declare which slots they fill. */
+    name: string;
+}
+export declare function createSlot(getConfig: () => ResolvedConfig): ({ name }: SlotProps) => Promise<ReactNode>;

package/dist/next/slot.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment } from 'react';
+import { PluginIsland } from '../client/island.js';
+import { prepareClient, publicConfig } from '../core/runtime.js';
+import { getInstalledPlugins } from '../core/state.js';
+import { PluginGoneError } from '../errors.js';
+import { pluginInfo } from './plugin-page.js';
+export function createSlot(getConfig) {
+    /**
+     * A place in the site's layout where installed plugins may render something
+     * (a cart button, a chat bubble, a banner). Renders nothing when no plugin fills it.
+     */
+    return async function Slot({ name }) {
+        try {
+            const cfg = getConfig();
+            const installs = await getInstalledPlugins(cfg);
+            const items = Object.values(installs)
+                .filter((i) => i.enabled)
+                .flatMap((install) => (install.manifest.slots ?? []).filter((s) => s.slot === name).map((slot) => ({ install, slot })))
+                .sort((a, b) => (a.slot.order ?? 0) - (b.slot.order ?? 0) || a.install.id.localeCompare(b.install.id));
+            if (!items.length)
+                return null;
+            const rendered = await Promise.all(items.map(async ({ install, slot }) => {
+                // A plugin removed moments ago on another instance simply stops showing; it must not break the layout.
+                const assets = await prepareClient(cfg, install).catch((e) => {
+                    if (e instanceof PluginGoneError)
+                        return null;
+                    throw e;
+                });
+                if (!assets)
+                    return null;
+                return (_jsxs(Fragment, { children: [assets.styleHref ? _jsx("link", { rel: "stylesheet", href: assets.styleHref, precedence: "nextpluggable" }) : null, _jsx(PluginIsland, { moduleKey: assets.moduleKey, src: assets.scriptSrc, component: slot.component, info: pluginInfo(cfg, install), config: publicConfig(install) })] }, `${install.id}:${slot.component}`));
+            }));
+            return _jsx(_Fragment, { children: rendered });
+        }
+        catch (e) {
+            // A slot sits in the site's layout: it must never take the whole site down.
+            console.error(`[nextpluggable] Slot "${name}" could not be rendered:`, e);
+            return null;
+        }
+    };
+}

package/dist/sources/github.d.ts

@@ -0,0 +1,19 @@
+import type { SourceReader } from './reader.js';
+export interface GitHubLocation {
+    owner: string;
+    repo: string;
+    ref?: string;
+    dir?: string;
+}
+/**
+ * Understand whatever a person pastes for a repository: `owner/repo`, a
+ * browser URL (optionally `/tree/<branch>/<folder>`), or a git clone address.
+ */
+export declare function parseGitHubUrl(input: string): GitHubLocation | null;
+export interface GitHubReaderOptions {
+    apiUrl: string;
+    token?: string;
+    fetch?: typeof fetch;
+}
+/** Reads files from a GitHub repository at an exact commit, via the REST API. */
+export declare function githubReader(location: GitHubLocation, options: GitHubReaderOptions): SourceReader;

package/dist/sources/github.js

@@ -0,0 +1,109 @@
+import { HttpError } from '../errors.js';
+const NAME = /^[A-Za-z0-9._-]+$/;
+/**
+ * Understand whatever a person pastes for a repository: `owner/repo`, a
+ * browser URL (optionally `/tree/<branch>/<folder>`), or a git clone address.
+ */
+export function parseGitHubUrl(input) {
+    let s = input.trim();
+    if (!s)
+        return null;
+    s = s.replace(/^git@github\.com:/i, 'https://github.com/').replace(/^(?:www\.)?github\.com\//i, 'https://github.com/');
+    let parts;
+    if (/^https?:\/\//i.test(s)) {
+        let url;
+        try {
+            url = new URL(s);
+        }
+        catch {
+            return null;
+        }
+        if (!/^(www\.)?github\.com$/i.test(url.hostname))
+            return null;
+        parts = url.pathname.split('/').filter(Boolean);
+    }
+    else {
+        // Shorthand must be exactly `owner/repo`; anything path-like (`/srv/plugins`, `./plugins`) is not GitHub.
+        if (!/^[A-Za-z0-9_-][A-Za-z0-9._-]*\/[A-Za-z0-9._-]+$/.test(s))
+            return null;
+        parts = s.split('/');
+    }
+    const [owner, repoRaw, kind, ref, ...rest] = parts;
+    if (!owner || !repoRaw)
+        return null;
+    const repo = repoRaw.replace(/\.git$/i, '');
+    if (!NAME.test(owner) || !NAME.test(repo))
+        return null;
+    const location = { owner, repo };
+    if (kind === 'tree' && ref) {
+        location.ref = decodeURIComponent(ref);
+        const dir = rest.map(decodeURIComponent).join('/');
+        if (dir) {
+            if (dir.split('/').some((p) => p === '..' || p === '.'))
+                return null;
+            location.dir = dir;
+        }
+    }
+    return location;
+}
+const encodePath = (p) => p.split('/').map(encodeURIComponent).join('/');
+/** Reads files from a GitHub repository at an exact commit, via the REST API. */
+export function githubReader(location, options) {
+    const doFetch = options.fetch ?? fetch;
+    const repoUrl = `${options.apiUrl}/repos/${encodeURIComponent(location.owner)}/${encodeURIComponent(location.repo)}`;
+    const name = `${location.owner}/${location.repo}`;
+    async function call(url, accept) {
+        let res;
+        try {
+            res = await doFetch(url, {
+                headers: {
+                    accept,
+                    'user-agent': 'nextpluggable',
+                    'x-github-api-version': '2022-11-28',
+                    ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+                },
+                cache: 'no-store',
+                redirect: 'follow',
+            });
+        }
+        catch {
+            throw new HttpError(502, 'Could not reach GitHub. Check the internet connection of the server and try again.');
+        }
+        if (res.status === 401)
+            throw new HttpError(400, `GitHub did not accept the access token for ${name}. It may have expired — create a new one and reconnect the source.`);
+        if (res.status === 403 || res.status === 429) {
+            if (res.headers.get('x-ratelimit-remaining') === '0' || res.status === 429) {
+                const reset = Number(res.headers.get('x-ratelimit-reset')) * 1000;
+                const mins = Number.isFinite(reset) && reset > Date.now() ? Math.max(1, Math.ceil((reset - Date.now()) / 60_000)) : null;
+                throw new HttpError(429, `GitHub is limiting requests right now${mins ? ` — try again in about ${mins} minute${mins === 1 ? '' : 's'}` : ''}.${options.token ? '' : ' Adding an access token raises the limit.'}`);
+            }
+            throw new HttpError(400, options.token
+                ? `The access token does not have permission to read ${name}. It needs read access to the repository's contents.`
+                : `GitHub refused access to ${name}. If the repository is private, add an access token.`);
+        }
+        return res;
+    }
+    return {
+        async resolveRevision() {
+            const res = await call(`${repoUrl}/commits/${encodePath(location.ref ?? 'HEAD')}`, 'application/vnd.github.sha');
+            if (res.status === 404 || res.status === 422 || res.status === 409)
+                throw new HttpError(404, location.ref
+                    ? `We could not find "${location.ref}" in ${name}. Check the address${options.token ? '' : ' — if the repository is private, add an access token'}.`
+                    : `We could not find the repository ${name}, or it is empty. Check the address${options.token ? ' and that the access token can read it' : ' — if the repository is private, add an access token'}.`);
+            if (!res.ok)
+                throw new HttpError(502, `GitHub returned an unexpected response (${res.status}).`);
+            const sha = (await res.text()).trim();
+            if (!/^[0-9a-f]{40,64}$/.test(sha))
+                throw new HttpError(502, 'GitHub returned an unexpected response.');
+            return sha;
+        },
+        async read(path, revision) {
+            const res = await call(`${repoUrl}/contents/${encodePath(path)}?ref=${encodeURIComponent(revision)}`, 'application/vnd.github.raw+json');
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new HttpError(502, `GitHub returned an unexpected response (${res.status}) for ${path}.`);
+            return new Uint8Array(await res.arrayBuffer());
+        },
+    };
+}

package/dist/sources/local.d.ts

@@ -0,0 +1,3 @@
+import type { SourceReader } from './reader.js';
+/** Reads plugins from a folder on the server. For plugin development. */
+export declare function localReader(dir: string): SourceReader;

package/dist/sources/local.js

@@ -0,0 +1,22 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+/** Reads plugins from a folder on the server. For plugin development. */
+export function localReader(dir) {
+    const root = path.resolve(/* turbopackIgnore: true */ dir);
+    return {
+        async resolveRevision() {
+            return 'local';
+        },
+        async read(file) {
+            const target = path.resolve(/* turbopackIgnore: true */ root, file);
+            if (target !== root && !target.startsWith(root + path.sep))
+                return null;
+            try {
+                return new Uint8Array(await readFile(target));
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}

package/dist/sources/reader.d.ts

@@ -0,0 +1,17 @@
+import type { ResolvedConfig } from '../config.js';
+import type { Catalog, SourceRecord } from '../core/types.js';
+/** Read-only access to the files of a plugin source at a fixed revision. */
+export interface SourceReader {
+    /** The exact revision (commit SHA) the source currently points at. */
+    resolveRevision(): Promise<string>;
+    /** File contents, or null when the file does not exist. */
+    read(path: string, revision: string): Promise<Uint8Array | null>;
+}
+export declare const joinPath: (...parts: (string | undefined)[]) => string;
+export declare function readerFor(cfg: ResolvedConfig, source: SourceRecord): {
+    reader: SourceReader;
+    baseDir: string;
+};
+export declare const decodeText: (bytes: Uint8Array) => string;
+/** List the plugins a source offers, at its current revision. */
+export declare function loadCatalog(source: SourceRecord, reader: SourceReader, baseDir: string): Promise<Catalog>;

package/dist/sources/reader.js

@@ -0,0 +1,78 @@
+import { ManifestError, validateBuild, validateRepositoryIndex } from '@nextpluggable/plugin/manifest';
+import { decrypt, sha256Hex } from '../crypto.js';
+import { HttpError } from '../errors.js';
+import { githubReader } from './github.js';
+import { localReader } from './local.js';
+export const joinPath = (...parts) => parts.filter(Boolean).join('/');
+export function readerFor(cfg, source) {
+    if (source.type === 'local' && source.local) {
+        if (!cfg.allowLocalSources)
+            throw new HttpError(400, 'Folder sources are turned off on this site.');
+        return { reader: localReader(source.local.dir), baseDir: '' };
+    }
+    if (source.type === 'github' && source.github) {
+        const own = source.github.token ? decrypt(cfg.secret, source.github.token) : null;
+        if (source.github.token && own === null)
+            throw new HttpError(400, `The saved access token for ${source.label} can no longer be read (the site secret changed). Remove the source and connect it again.`);
+        return {
+            reader: githubReader(source.github, { apiUrl: cfg.githubApiUrl, token: own ?? cfg.githubToken }),
+            baseDir: source.github.dir ?? '',
+        };
+    }
+    throw new HttpError(500, 'Unknown source type.');
+}
+const decoder = new TextDecoder('utf-8', { fatal: false });
+export const decodeText = (bytes) => decoder.decode(bytes);
+/** List the plugins a source offers, at its current revision. */
+export async function loadCatalog(source, reader, baseDir) {
+    const revision = await reader.resolveRevision();
+    const catalog = { sourceId: source.id, revision, fetchedAt: new Date().toISOString(), plugins: [], problems: [] };
+    const indexBytes = await reader.read(joinPath(baseDir, 'nextpluggable.json'), revision);
+    let dirs;
+    if (indexBytes) {
+        try {
+            const index = validateRepositoryIndex(JSON.parse(decodeText(indexBytes)));
+            catalog.name = index.name;
+            catalog.description = index.description;
+            dirs = [...new Set(index.plugins)];
+        }
+        catch (e) {
+            throw new HttpError(422, `The file nextpluggable.json in ${source.label} could not be read: ${e instanceof ManifestError ? e.problems.join('; ') : 'it is not valid JSON'}.`);
+        }
+    }
+    else {
+        dirs = [''];
+    }
+    if (dirs.length > 100)
+        throw new HttpError(422, `${source.label} lists more than 100 plugins.`);
+    const seen = new Set();
+    const results = await Promise.all(dirs.map(async (dir) => {
+        const bytes = await reader.read(joinPath(baseDir, dir, 'dist/build.json'), revision);
+        if (!bytes) {
+            if (!indexBytes)
+                return null;
+            return { path: dir, message: 'This plugin has not been built yet (dist/build.json is missing).' };
+        }
+        try {
+            return { path: dir, build: validateBuild(JSON.parse(decodeText(bytes))), buildHash: sha256Hex(bytes) };
+        }
+        catch (e) {
+            return { path: dir, message: e instanceof ManifestError ? e.problems.join('; ') : 'dist/build.json is not valid JSON.' };
+        }
+    }));
+    for (const r of results) {
+        if (!r)
+            continue;
+        if ('message' in r)
+            catalog.problems.push(r);
+        else if (seen.has(r.build.manifest.id))
+            catalog.problems.push({ path: r.path, message: `Another plugin in this source already uses the id "${r.build.manifest.id}".` });
+        else {
+            seen.add(r.build.manifest.id);
+            catalog.plugins.push(r);
+        }
+    }
+    if (!indexBytes && catalog.plugins.length === 0 && catalog.problems.length === 0)
+        throw new HttpError(422, `${source.label} does not look like a plugin source: it has no nextpluggable.json and no built plugin at its top level.`);
+    return catalog;
+}

package/dist/storage/file.d.ts

@@ -0,0 +1,12 @@
+import { type StorageAdapter } from './types.js';
+export interface FileStorageOptions {
+    /** Directory to store data in. Default: `NEXTPLUGGABLE_DATA_DIR`, else `.nextpluggable` in the project root. */
+    dir?: string;
+}
+/**
+ * Stores everything as files in a directory. Right for local development and
+ * for a single long-running server (VPS, Docker with a volume). Not for
+ * serverless hosts such as Vercel, whose filesystem is read-only and not shared
+ * between instances — use a database adapter there.
+ */
+export declare function fileStorage(options?: FileStorageOptions): StorageAdapter;

package/dist/storage/file.js

@@ -0,0 +1,61 @@
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { assertKey } from './types.js';
+/**
+ * Stores everything as files in a directory. Right for local development and
+ * for a single long-running server (VPS, Docker with a volume). Not for
+ * serverless hosts such as Vercel, whose filesystem is read-only and not shared
+ * between instances — use a database adapter there.
+ */
+export function fileStorage(options = {}) {
+    const root = path.resolve(/* turbopackIgnore: true */ options.dir ?? process.env.NEXTPLUGGABLE_DATA_DIR ?? path.join(/* turbopackIgnore: true */ process.cwd(), '.nextpluggable'));
+    const file = (key) => {
+        assertKey(key);
+        return path.join(root, ...key.split('/'));
+    };
+    let seq = 0;
+    async function walk(dir, prefix, out) {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const e of entries) {
+            if (e.name.endsWith('.tmp'))
+                continue;
+            const key = prefix ? `${prefix}/${e.name}` : e.name;
+            if (e.isDirectory())
+                await walk(path.join(dir, e.name), key, out);
+            else
+                out.push(key);
+        }
+    }
+    return {
+        async get(key) {
+            try {
+                return await readFile(file(key), 'utf8');
+            }
+            catch (e) {
+                if (e.code === 'ENOENT' || e.code === 'ENOTDIR')
+                    return null;
+                throw e;
+            }
+        },
+        async set(key, value) {
+            const target = file(key);
+            await mkdir(path.dirname(target), { recursive: true });
+            // Write-then-rename so a crash never leaves a half-written record.
+            const tmp = `${target}.${process.pid}.${++seq}.tmp`;
+            await writeFile(tmp, value, 'utf8');
+            await rename(tmp, target);
+        },
+        async delete(key) {
+            await rm(file(key), { force: true });
+        },
+        async list(prefix) {
+            const slash = prefix.lastIndexOf('/');
+            const dirKey = slash === -1 ? '' : prefix.slice(0, slash);
+            if (dirKey)
+                assertKey(dirKey);
+            const out = [];
+            await walk(dirKey ? path.join(root, ...dirKey.split('/')) : root, dirKey, out);
+            return out.filter((k) => k.startsWith(prefix)).sort();
+        },
+    };
+}

package/dist/storage/memory.d.ts

@@ -0,0 +1,3 @@
+import { type StorageAdapter } from './types.js';
+/** Keeps everything in memory. For tests and demos — data is lost on restart. */
+export declare function memoryStorage(): StorageAdapter;

package/dist/storage/memory.js

@@ -0,0 +1,22 @@
+import { assertKey } from './types.js';
+/** Keeps everything in memory. For tests and demos — data is lost on restart. */
+export function memoryStorage() {
+    const map = new Map();
+    return {
+        async get(key) {
+            assertKey(key);
+            return map.get(key) ?? null;
+        },
+        async set(key, value) {
+            assertKey(key);
+            map.set(key, value);
+        },
+        async delete(key) {
+            assertKey(key);
+            map.delete(key);
+        },
+        async list(prefix) {
+            return [...map.keys()].filter((k) => k.startsWith(prefix)).sort();
+        },
+    };
+}

package/dist/storage/postgres.d.ts

@@ -0,0 +1,15 @@
+import { type StorageAdapter } from './types.js';
+export interface PostgresStorageOptions {
+    /**
+     * Runs a parameterised query (`$1`, `$2`, …) and resolves to the rows, or to an
+     * object with a `rows` array. Matches `pg`'s `pool.query`, Neon's `sql.query`,
+     * and is a one-liner to adapt for other clients.
+     */
+    query: (text: string, params: unknown[]) => Promise<{
+        rows: unknown[];
+    } | unknown[]>;
+    /** Table name. Default `nextpluggable_kv`. Created automatically. */
+    table?: string;
+}
+/** Stores everything in one Postgres table. Works with any client you already use. */
+export declare function postgresStorage(options: PostgresStorageOptions): StorageAdapter;

package/dist/storage/postgres.js

@@ -0,0 +1,39 @@
+import { assertKey } from './types.js';
+/** Stores everything in one Postgres table. Works with any client you already use. */
+export function postgresStorage(options) {
+    const table = options.table ?? 'nextpluggable_kv';
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(table))
+        throw new Error(`Invalid table name: ${table}`);
+    let ready;
+    async function run(text, params = []) {
+        ready ??= options
+            .query(`CREATE TABLE IF NOT EXISTS ${table} (key text PRIMARY KEY, value text NOT NULL, updated_at timestamptz NOT NULL DEFAULT now())`, [])
+            .catch((e) => {
+            ready = undefined;
+            throw e;
+        });
+        await ready;
+        const result = await options.query(text, params);
+        return (Array.isArray(result) ? result : result.rows);
+    }
+    return {
+        async get(key) {
+            assertKey(key);
+            const rows = await run(`SELECT value FROM ${table} WHERE key = $1`, [key]);
+            return rows.length ? String(rows[0].value) : null;
+        },
+        async set(key, value) {
+            assertKey(key);
+            await run(`INSERT INTO ${table} (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()`, [key, value]);
+        },
+        async delete(key) {
+            assertKey(key);
+            await run(`DELETE FROM ${table} WHERE key = $1`, [key]);
+        },
+        async list(prefix) {
+            const pattern = prefix.replace(/[\\%_]/g, '\\$&') + '%';
+            const rows = await run(`SELECT key FROM ${table} WHERE key LIKE $1 ESCAPE '\\' ORDER BY key COLLATE "C"`, [pattern]);
+            return rows.map((r) => String(r.key));
+        },
+    };
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where NextPluggable keeps everything: connected sources, installed plugins,
+ * their bundles, settings and data. A flat string key-value store is all it
+ * needs, so any database can back it.
+ *
+ * Keys are `/`-separated paths whose segments use only `A-Z a-z 0-9 . _ @ % ~ -`.
+ */
+export interface StorageAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** All keys that start with `prefix`, sorted. */
+    list(prefix: string): Promise<string[]>;
+}
+export declare function assertKey(key: string): void;
+/** Encode an arbitrary string as a single safe key segment. */
+export declare function encodeSegment(value: string): string;
+export declare const decodeSegment: (segment: string) => string;

package/dist/storage/types.js

@@ -0,0 +1,15 @@
+const SEGMENT = /^[A-Za-z0-9_@%~-][A-Za-z0-9._@%~-]*$/;
+export function assertKey(key) {
+    if (!key || key.length > 900 || !key.split('/').every((s) => SEGMENT.test(s)))
+        throw new Error(`Invalid storage key: ${JSON.stringify(key)}`);
+}
+/** Encode an arbitrary string as a single safe key segment. */
+export function encodeSegment(value) {
+    const out = encodeURIComponent(value)
+        .replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+        .replace(/^\./, '%2E');
+    if (!out)
+        throw new Error('Storage keys cannot be empty');
+    return out;
+}
+export const decodeSegment = (segment) => decodeURIComponent(segment);

package/dist/storage/upstash.d.ts

@@ -0,0 +1,15 @@
+import { type StorageAdapter } from './types.js';
+export interface UpstashStorageOptions {
+    /** REST URL. Default: `UPSTASH_REDIS_REST_URL` or `KV_REST_API_URL`. */
+    url?: string;
+    /** REST token. Default: `UPSTASH_REDIS_REST_TOKEN` or `KV_REST_API_TOKEN`. */
+    token?: string;
+    /** Prefix for every key, so one database can be shared. Default `np:`. */
+    prefix?: string;
+}
+/**
+ * Stores everything in Upstash Redis over its REST API (also what Vercel's
+ * "Upstash for Redis" marketplace integration provisions). Works on serverless
+ * hosts and needs no extra dependency.
+ */
+export declare function upstashStorage(options?: UpstashStorageOptions): StorageAdapter;