@nextpluggable/plugin 0.0.0-stage → 0.1.1

package/dist/manifest.js

@@ -0,0 +1,348 @@
+/**
+ * The plugin manifest (`plugin.json`) — the contract between a plugin and any host.
+ * Everything a non-technical site owner sees about a plugin (name, what it adds,
+ * its settings form, what it is allowed to do) is derived from this file.
+ */
+export const MANIFEST_VERSION = 1;
+const ID_RE = /^[a-z][a-z0-9-]{1,48}[a-z0-9]$/;
+const KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+const COMPONENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SLOT_RE = /^[a-z][a-z0-9.-]{0,63}$/;
+/** Names that collide with built-in object properties; refusing them keeps every lookup by id/key safe. */
+const RESERVED = new Set(['constructor', 'prototype', 'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable', 'toLocaleString', 'toString', 'valueOf']);
+const isKey = (v) => typeof v === 'string' && KEY_RE.test(v) && !RESERVED.has(v);
+const SETTING_TYPES = [
+    'text',
+    'textarea',
+    'number',
+    'toggle',
+    'select',
+    'color',
+    'url',
+    'email',
+    'secret',
+];
+export class ManifestError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Invalid plugin manifest:\n- ${problems.join('\n- ')}`);
+        this.problems = problems;
+        this.name = 'ManifestError';
+    }
+}
+/** Validate a page path pattern. Returns a problem description, or null when fine. */
+export function checkPagePath(path) {
+    if (typeof path !== 'string' || !path.startsWith('/'))
+        return 'must start with "/"';
+    if (path.length > 200)
+        return 'is too long';
+    if (path !== '/' && path.endsWith('/'))
+        return 'must not end with "/"';
+    if (path === '/')
+        return 'cannot be the home page';
+    const segments = path.slice(1).split('/');
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (seg === '*') {
+            if (i !== segments.length - 1)
+                return '"*" is only allowed as the last segment';
+            continue;
+        }
+        if (seg.startsWith(':')) {
+            if (!KEY_RE.test(seg.slice(1)))
+                return `has an invalid parameter name "${seg}"`;
+            continue;
+        }
+        if (!/^[A-Za-z0-9._~-]+$/.test(seg) || seg === '.' || seg === '..')
+            return `has an invalid segment "${seg}" (use letters, digits, dashes)`;
+    }
+    return null;
+}
+export function isStaticPath(path) {
+    return !path.split('/').some((s) => s === '*' || s.startsWith(':'));
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Validate an untrusted value as a manifest. Throws ManifestError listing every
+ * problem in words a plugin author can act on.
+ */
+export function validateManifest(input) {
+    const p = [];
+    if (!isRecord(input))
+        throw new ManifestError(['manifest must be a JSON object']);
+    const m = input;
+    if (m.manifestVersion !== MANIFEST_VERSION)
+        p.push(`"manifestVersion" must be ${MANIFEST_VERSION}`);
+    if (typeof m.id !== 'string' || !ID_RE.test(m.id) || RESERVED.has(m.id))
+        p.push('"id" must be 3-50 characters: lowercase letters, digits and dashes, starting with a letter');
+    if (typeof m.name !== 'string' || !m.name.trim() || m.name.length > 80)
+        p.push('"name" is required (max 80 characters)');
+    if (typeof m.version !== 'string' || !VERSION_RE.test(m.version))
+        p.push('"version" must look like 1.2.3');
+    for (const k of ['description', 'author', 'homepage', 'icon', 'category']) {
+        if (m[k] !== undefined && typeof m[k] !== 'string')
+            p.push(`"${k}" must be text`);
+    }
+    if (typeof m.description === 'string' && m.description.length > 500)
+        p.push('"description" is too long (max 500 characters)');
+    if (m.entry !== undefined) {
+        if (!isRecord(m.entry))
+            p.push('"entry" must be an object');
+        else
+            for (const k of ['client', 'server'])
+                if (m.entry[k] !== undefined && typeof m.entry[k] !== 'string')
+                    p.push(`"entry.${k}" must be a file path`);
+    }
+    const pageIds = new Set();
+    const pagePaths = new Set();
+    if (m.pages !== undefined) {
+        if (!Array.isArray(m.pages))
+            p.push('"pages" must be a list');
+        else
+            m.pages.forEach((page, i) => {
+                const at = `pages[${i}]`;
+                if (!isRecord(page))
+                    return void p.push(`${at} must be an object`);
+                if (!isKey(page.id))
+                    p.push(`${at}.id must be a short identifier`);
+                else if (pageIds.has(page.id))
+                    p.push(`${at}.id "${page.id}" is used twice`);
+                else
+                    pageIds.add(page.id);
+                const pathProblem = checkPagePath(page.path);
+                if (pathProblem)
+                    p.push(`${at}.path ${pathProblem}`);
+                else if (pagePaths.has(page.path))
+                    p.push(`${at}.path "${String(page.path)}" is used twice`);
+                else
+                    pagePaths.add(page.path);
+                if (typeof page.component !== 'string' || !COMPONENT_RE.test(page.component))
+                    p.push(`${at}.component must be the name of an exported component`);
+                if (typeof page.title !== 'string' || !page.title.trim())
+                    p.push(`${at}.title is required`);
+                if (page.description !== undefined && typeof page.description !== 'string')
+                    p.push(`${at}.description must be text`);
+                if (page.configurablePath !== undefined && typeof page.configurablePath !== 'boolean')
+                    p.push(`${at}.configurablePath must be true or false`);
+            });
+    }
+    if (m.slots !== undefined) {
+        if (!Array.isArray(m.slots))
+            p.push('"slots" must be a list');
+        else
+            m.slots.forEach((slot, i) => {
+                const at = `slots[${i}]`;
+                if (!isRecord(slot))
+                    return void p.push(`${at} must be an object`);
+                if (typeof slot.slot !== 'string' || !SLOT_RE.test(slot.slot))
+                    p.push(`${at}.slot must be a slot name like "header.actions"`);
+                if (typeof slot.component !== 'string' || !COMPONENT_RE.test(slot.component))
+                    p.push(`${at}.component must be the name of an exported component`);
+                if (slot.order !== undefined && typeof slot.order !== 'number')
+                    p.push(`${at}.order must be a number`);
+            });
+    }
+    if (m.admin !== undefined) {
+        const ids = new Set();
+        if (!Array.isArray(m.admin))
+            p.push('"admin" must be a list');
+        else
+            m.admin.forEach((a, i) => {
+                const at = `admin[${i}]`;
+                if (!isRecord(a))
+                    return void p.push(`${at} must be an object`);
+                if (!isKey(a.id))
+                    p.push(`${at}.id must be a short identifier`);
+                else if (ids.has(a.id))
+                    p.push(`${at}.id "${a.id}" is used twice`);
+                else
+                    ids.add(a.id);
+                if (typeof a.title !== 'string' || !a.title.trim())
+                    p.push(`${at}.title is required`);
+                if (typeof a.component !== 'string' || !COMPONENT_RE.test(a.component))
+                    p.push(`${at}.component must be the name of an exported component`);
+            });
+    }
+    if (m.settings !== undefined) {
+        const keys = new Set();
+        if (!Array.isArray(m.settings))
+            p.push('"settings" must be a list');
+        else
+            m.settings.forEach((f, i) => {
+                const at = `settings[${i}]`;
+                if (!isRecord(f))
+                    return void p.push(`${at} must be an object`);
+                if (!isKey(f.key))
+                    p.push(`${at}.key must be a short identifier`);
+                else if (keys.has(f.key))
+                    p.push(`${at}.key "${f.key}" is used twice`);
+                else
+                    keys.add(f.key);
+                if (typeof f.label !== 'string' || !f.label.trim())
+                    p.push(`${at}.label is required`);
+                if (!SETTING_TYPES.includes(f.type))
+                    p.push(`${at}.type must be one of: ${SETTING_TYPES.join(', ')}`);
+                if (f.type === 'select') {
+                    if (!Array.isArray(f.options) || f.options.length === 0)
+                        p.push(`${at}.options is required for a select`);
+                    else if (!f.options.every((o) => isRecord(o) && typeof o.value === 'string' && typeof o.label === 'string'))
+                        p.push(`${at}.options must be a list of { value, label }`);
+                }
+                if (f.type === 'secret' && f.default !== undefined)
+                    p.push(`${at} is a secret and cannot have a default`);
+                if (f.default !== undefined) {
+                    const want = f.type === 'number' ? 'number' : f.type === 'toggle' ? 'boolean' : 'string';
+                    if (typeof f.default !== want)
+                        p.push(`${at}.default must be a ${want}`);
+                }
+                for (const k of ['min', 'max', 'step'])
+                    if (f[k] !== undefined && typeof f[k] !== 'number')
+                        p.push(`${at}.${k} must be a number`);
+                for (const k of ['help', 'placeholder', 'group'])
+                    if (f[k] !== undefined && typeof f[k] !== 'string')
+                        p.push(`${at}.${k} must be text`);
+                for (const k of ['required', 'serverOnly'])
+                    if (f[k] !== undefined && typeof f[k] !== 'boolean')
+                        p.push(`${at}.${k} must be true or false`);
+            });
+    }
+    if (m.permissions !== undefined) {
+        if (!Array.isArray(m.permissions))
+            p.push('"permissions" must be a list');
+        else
+            m.permissions.forEach((perm, i) => {
+                const ok = perm === 'storage' ||
+                    perm === 'email' ||
+                    (typeof perm === 'string' && /^fetch:(\*|[a-z0-9.-]+(?::\d+)?)$/i.test(perm));
+                if (!ok)
+                    p.push(`permissions[${i}] must be "storage", "email" or "fetch:<host>"`);
+            });
+    }
+    if (p.length)
+        throw new ManifestError(p);
+    return m;
+}
+/** Default values declared by the manifest's settings. */
+export function defaultConfig(manifest) {
+    const out = {};
+    for (const f of manifest.settings ?? [])
+        if (f.default !== undefined)
+            out[f.key] = f.default;
+    return out;
+}
+/** Whether a setting's value may be sent to browsers. */
+export function isPublicSetting(field) {
+    return field.type !== 'secret' && !field.serverOnly;
+}
+/**
+ * Check and normalise values submitted for a plugin's settings.
+ * Returns cleaned values plus per-field messages written for a non-technical reader.
+ */
+export function validateSettings(manifest, input) {
+    const values = {};
+    const errors = {};
+    for (const f of manifest.settings ?? []) {
+        let v = input[f.key];
+        if (typeof v === 'string')
+            v = f.type === 'textarea' || f.type === 'secret' ? v : v.trim();
+        const empty = v === undefined || v === null || v === '';
+        if (empty) {
+            if (f.required)
+                errors[f.key] = `${f.label} is required.`;
+            continue;
+        }
+        switch (f.type) {
+            case 'number': {
+                const n = typeof v === 'number' ? v : Number(v);
+                if (!Number.isFinite(n))
+                    errors[f.key] = `${f.label} must be a number.`;
+                else if (f.min !== undefined && n < f.min)
+                    errors[f.key] = `${f.label} must be at least ${f.min}.`;
+                else if (f.max !== undefined && n > f.max)
+                    errors[f.key] = `${f.label} must be at most ${f.max}.`;
+                else
+                    values[f.key] = n;
+                break;
+            }
+            case 'toggle':
+                if (typeof v !== 'boolean')
+                    errors[f.key] = `${f.label} must be on or off.`;
+                else
+                    values[f.key] = v;
+                break;
+            case 'select':
+                if (typeof v !== 'string' || !f.options?.some((o) => o.value === v))
+                    errors[f.key] = `Choose one of the options for ${f.label}.`;
+                else
+                    values[f.key] = v;
+                break;
+            case 'color':
+                if (typeof v !== 'string' || !/^#[0-9a-fA-F]{6}$/.test(v))
+                    errors[f.key] = `${f.label} must be a colour like #1d4ed8.`;
+                else
+                    values[f.key] = v.toLowerCase();
+                break;
+            case 'url':
+                if (typeof v !== 'string' || !/^https?:\/\/\S+$/i.test(v))
+                    errors[f.key] = `${f.label} must be a web address starting with http:// or https://.`;
+                else
+                    values[f.key] = v;
+                break;
+            case 'email':
+                if (typeof v !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v))
+                    errors[f.key] = `${f.label} must be an email address.`;
+                else
+                    values[f.key] = v;
+                break;
+            default:
+                if (typeof v !== 'string')
+                    errors[f.key] = `${f.label} must be text.`;
+                else if (v.length > 10_000)
+                    errors[f.key] = `${f.label} is too long.`;
+                else
+                    values[f.key] = v;
+        }
+    }
+    return { values, errors };
+}
+export function validateRepositoryIndex(input) {
+    if (!isRecord(input) || !Array.isArray(input.plugins) || !input.plugins.every((x) => typeof x === 'string'))
+        throw new ManifestError(['nextpluggable.json must contain a "plugins" list of directories']);
+    const plugins = input.plugins.map((d) => d.replace(/^\.?\/+/, '').replace(/\/+$/, ''));
+    if (plugins.some((d) => d.split('/').includes('..')))
+        throw new ManifestError(['plugin directories must stay inside the repository']);
+    return {
+        name: typeof input.name === 'string' ? input.name : undefined,
+        description: typeof input.description === 'string' ? input.description : undefined,
+        plugins,
+    };
+}
+export function validateBuild(input) {
+    if (!isRecord(input) || input.buildVersion !== 1)
+        throw new ManifestError(['dist/build.json is missing or was made by an incompatible build tool']);
+    const manifest = validateManifest(input.manifest);
+    const files = {};
+    const rawFiles = isRecord(input.files) ? input.files : {};
+    for (const k of ['client', 'server', 'style']) {
+        const f = rawFiles[k];
+        if (f === undefined)
+            continue;
+        if (!isRecord(f) ||
+            typeof f.path !== 'string' ||
+            f.path.split('/').includes('..') ||
+            f.path.startsWith('/') ||
+            typeof f.sha256 !== 'string' ||
+            !/^[0-9a-f]{64}$/.test(f.sha256) ||
+            typeof f.bytes !== 'number')
+            throw new ManifestError([`dist/build.json has a malformed "${k}" file entry`]);
+        files[k] = { path: f.path, sha256: f.sha256, bytes: f.bytes };
+    }
+    const needsClient = (manifest.pages?.length ?? 0) + (manifest.slots?.length ?? 0) + (manifest.admin?.length ?? 0) > 0;
+    if (needsClient && !files.client)
+        throw new ManifestError(['the plugin declares pages or components but has no built client bundle']);
+    const icon = typeof input.icon === 'string' && input.icon.length <= 64_000 ? input.icon : undefined;
+    return { buildVersion: 1, manifest, icon, files };
+}

package/dist/server.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Server-side API for plugin authors. Everything here is built on web
+ * standards (Request/Response) so the same plugin can run on any host adapter.
+ */
+/** A small key-value store private to the plugin. Values are JSON. */
+export interface PluginStorage {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Keys that start with `prefix` (all keys when omitted), sorted. */
+    list(prefix?: string): Promise<string[]>;
+}
+export interface AdminUser {
+    id: string;
+    name?: string;
+}
+export interface PluginContext<C = Record<string, unknown>> {
+    pluginId: string;
+    /** All settings, including server-only values and decrypted secrets. */
+    config: C;
+    storage: PluginStorage;
+    site: {
+        /** Origin of the site, e.g. `https://example.com`. */
+        url: string;
+    };
+    /** Addresses of this plugin's pages keyed by page id. */
+    paths: Record<string, string>;
+    log(...args: unknown[]): void;
+}
+/**
+ * What a page loader receives. There is deliberately no query string here:
+ * sites cache plugin pages, and a cached page cannot depend on it. Use address
+ * parameters (`/shop/:slug`, `/blog/page/:n`) for content search engines should
+ * see, and `useQuery()` in the browser for filters and searches.
+ */
+export interface PageContext<C = Record<string, unknown>> extends PluginContext<C> {
+    path: string;
+    params: Record<string, string>;
+}
+/**
+ * How a page presents itself to search engines and when shared. Everything is
+ * optional: the site fills in whatever is left out (the page's title and
+ * description from the manifest, a canonical link to the page itself, the
+ * site's own sharing image), so a page is complete without any of this.
+ */
+export interface PageMetadata {
+    title?: string;
+    /** One or two sentences for search results. About 150 characters. */
+    description?: string;
+    /** Absolute or site-relative canonical URL. Defaults to the page's own address. */
+    canonical?: string;
+    /** Absolute or site-relative image shown when the page is shared. Defaults to the site's own. */
+    image?: string;
+    /** What the image shows, for people who cannot see it. Defaults to the title. */
+    imageAlt?: string;
+    /** `article` for a dated piece of writing (a post, a news item). Default `website`. */
+    type?: 'website' | 'article';
+    /** For articles: ISO dates of first publication and last change. */
+    publishedTime?: string;
+    modifiedTime?: string;
+    /** Keep the page out of search engines (a thank-you page, a preview). */
+    noindex?: boolean;
+}
+/** One address for the site's sitemap: a path, or a path with the ISO date it last changed. */
+export type SitemapEntry = string | {
+    path: string;
+    lastModified?: string;
+};
+export interface PageResult<P = Record<string, unknown>> {
+    /** Passed to the page component as `data`. Must be JSON-serialisable. */
+    data?: P;
+    metadata?: PageMetadata;
+    /** schema.org structured data, rendered as JSON-LD. */
+    jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+    /** Respond with the site's 404 page. */
+    notFound?: boolean;
+    /** Redirect to another address. */
+    redirect?: string;
+}
+export interface ApiContext<C = Record<string, unknown>> extends PluginContext<C> {
+    request: Request;
+    /** Path below the plugin's API base, e.g. `/items/42`. */
+    path: string;
+    params: Record<string, string>;
+    /** The signed-in dashboard user, or null for public visitors. */
+    admin: AdminUser | null;
+}
+export type PageLoader<C = Record<string, unknown>> = (ctx: PageContext<C>) => PageResult | Promise<PageResult>;
+export type ApiHandler<C = Record<string, unknown>> = (ctx: ApiContext<C>) => Response | Promise<Response>;
+export interface PluginServer<C = Record<string, unknown>> {
+    /** Server loaders keyed by page id: fetch data and SEO metadata before the page renders. */
+    pages?: Record<string, PageLoader<C>>;
+    /** HTTP endpoints keyed by `"METHOD /path"`, e.g. `"POST /messages"` or `"GET /items/:id"`. */
+    api?: Record<string, ApiHandler<C>>;
+    /**
+     * The addresses of this plugin's pages that have parameters (`/shop/:slug`), for the
+     * site's sitemap: one entry per product, article and so on. Pages with a fixed
+     * address are listed by the site already. Addresses that do not belong to one of
+     * the plugin's pages are ignored.
+     */
+    sitemap?(ctx: PluginContext<C>): SitemapEntry[] | Promise<SitemapEntry[]>;
+    onInstall?(ctx: PluginContext<C>): void | Promise<void>;
+    onUninstall?(ctx: PluginContext<C>): void | Promise<void>;
+}
+/** Identity helper that gives the server entry full type checking. */
+export declare function definePluginServer<C = Record<string, unknown>>(server: PluginServer<C>): PluginServer<C>;
+/** Restrict an endpoint to the signed-in dashboard user. */
+export declare function adminOnly<C = Record<string, unknown>>(handler: ApiHandler<C>): ApiHandler<C>;
+export declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
+/** Read a JSON request body, returning null when it is missing, malformed or larger than `maxBytes`. */
+export declare function readJson<T = unknown>(request: Request, maxBytes?: number): Promise<T | null>;

package/dist/server.js

@@ -0,0 +1,30 @@
+/**
+ * Server-side API for plugin authors. Everything here is built on web
+ * standards (Request/Response) so the same plugin can run on any host adapter.
+ */
+/** Identity helper that gives the server entry full type checking. */
+export function definePluginServer(server) {
+    return server;
+}
+/** Restrict an endpoint to the signed-in dashboard user. */
+export function adminOnly(handler) {
+    return (ctx) => (ctx.admin ? handler(ctx) : json({ error: 'Sign in to the dashboard to do this.' }, 401));
+}
+export function json(body, status = 200, headers) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8', ...headers },
+    });
+}
+/** Read a JSON request body, returning null when it is missing, malformed or larger than `maxBytes`. */
+export async function readJson(request, maxBytes = 100_000) {
+    try {
+        const text = await request.text();
+        if (text.length > maxBytes)
+            return null;
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@nextpluggable/plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "SDK and build tool for writing NextPluggable plugins",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rohittp0/NextPluggable.git",
+    "directory": "packages/plugin"
+  },
+  "homepage": "https://github.com/rohittp0/NextPluggable#readme",
+  "bugs": "https://github.com/rohittp0/NextPluggable/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.16"
+  },
+  "type": "module",
+  "bin": {
+    "nextpluggable-plugin": "./bin/nextpluggable-plugin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "peerDependencies": {
+    "esbuild": ">=0.21",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "esbuild": "^0.28.2",
+    "react": "^19.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }