@velocms/plugin-sdk 1.0.0-alpha.2

package/dist/index.d.cts

@@ -0,0 +1,318 @@
+export { A as AfterMemberSignupPayload, a as AfterMemberUpdatePayload, b as AfterOrderCreatePayload, c as AfterPageCreatePayload, d as AfterPagePublishPayload, e as AfterPageUpdatePayload, f as AfterPostCreatePayload, g as AfterPostDeletePayload, h as AfterPostPublishPayload, i as AfterPostUpdatePayload, j as AfterProductCreatePayload, B as BeforeMemberDeletePayload, k as BeforePostPublishPayload, l as BeforePostPublishResult, C as ContextLogger, m as ContextSettings, n as ContextTenant, E as EventBusContext, o as EventName, H as HookContext, p as HookMember, q as HookName, r as HookPayloadMap, s as HookPost, O as OnAppStartPayload, t as OnDailySchedulePayload, P as PageHookData, u as PluginEventName, v as PluginEventPayload, S as SystemEventName, w as SystemEventPayloadMap } from './context-BCzNwlqR.cjs';
+
+/**
+ * Plugin Capabilities
+ *
+ * Capabilities follow the principle of least privilege. Declare only the
+ * capabilities your plugin actually needs — the VeloCMS review team will
+ * reject plugins with unnecessary permissions.
+ *
+ * @example
+ * ```typescript
+ * capabilities: {
+ *   content: { read: true },
+ *   network: true,
+ *   network_allowlist: ["api.example.com"],
+ * }
+ * ```
+ */
+/**
+ * Content access capabilities.
+ *
+ * `read` — read published + draft posts, pages, media metadata.
+ * `write` — create and update posts and pages.
+ * `delete` — delete posts, pages, and media.
+ */
+interface ContentCapabilities {
+    /** Read posts, pages, media metadata */
+    read?: boolean;
+    /** Create and update posts and pages */
+    write?: boolean;
+    /** Delete posts, pages, and media */
+    delete?: boolean;
+}
+/**
+ * Member access capabilities.
+ *
+ * `read` — read subscriber list (email redacted by default unless `read_pii` is true).
+ * `write` — create and update member records.
+ * `read_pii` — access raw member email addresses. Requires manual review justification.
+ */
+interface MemberCapabilities {
+    /** Read subscriber list (email redacted unless read_pii = true) */
+    read?: boolean;
+    /** Create and update member records */
+    write?: boolean;
+    /** Access raw member email addresses — requires review justification */
+    read_pii?: boolean;
+}
+/**
+ * Commerce capabilities.
+ *
+ * Requires the tenant to have commerce enabled.
+ */
+interface CommerceCapabilities {
+    /** Read products and orders */
+    read?: boolean;
+    /** Create and update products, process orders */
+    write?: boolean;
+}
+/**
+ * Database schema capabilities.
+ *
+ * `read` — introspect collection schemas.
+ * `modify` — add custom fields or collections. Requires architect review.
+ */
+interface SchemaCapabilities {
+    /** Read collection schemas */
+    read?: boolean;
+    /** Modify schemas — add fields or collections. HIGH RISK. Requires review. */
+    modify?: boolean;
+}
+/**
+ * Full capabilities declaration.
+ *
+ * All fields are optional — omit capabilities your plugin does not use.
+ */
+interface PluginCapabilities {
+    /** Content access */
+    content?: ContentCapabilities;
+    /** Member access */
+    members?: MemberCapabilities;
+    /** Commerce access */
+    commerce?: CommerceCapabilities;
+    /** Schema introspection/modification */
+    schema?: SchemaCapabilities;
+    /**
+     * External HTTP requests.
+     * If true, plugin can call any URL in `network_allowlist`.
+     * Network calls outside the allowlist are blocked at runtime.
+     */
+    network?: boolean;
+    /**
+     * Allowlisted domains for network access.
+     * Format: "hostname.tld" (no protocol, no path, no wildcards).
+     * Example: ["api.sendgrid.com", "hooks.slack.com"]
+     */
+    network_allowlist?: string[];
+    /** Send emails via the tenant's configured email provider */
+    email?: boolean;
+    /** UI integration points */
+    ui?: {
+        /** Inject a persistent sidebar widget */
+        sidebar?: boolean;
+        /** Inject toolbar items or panel tabs in the post editor */
+        post_editor?: boolean;
+        /** Add stat cards to the admin dashboard */
+        dashboard?: boolean;
+        /** Add a section to the admin settings page */
+        settings?: boolean;
+    };
+    /**
+     * Event bus subscription capability. (Phase 2.A)
+     *
+     * Declare which system events your plugin subscribes to and whether it
+     * emits custom events. The VeloCMS runtime will only inject ctx.events
+     * when this field is present.
+     *
+     * @example
+     * ```typescript
+     * capabilities: {
+     *   events: {
+     *     subscribe: ["post.published", "member.subscribed"],
+     *     emit_custom: true,
+     *   }
+     * }
+     * ```
+     */
+    events?: {
+        /**
+         * List of system event names the plugin subscribes to.
+         * Import `SystemEventName` from `@velocms/plugin-sdk` for the full catalog.
+         */
+        subscribe?: string[];
+        /**
+         * If true, the plugin may call `ctx.events.emit()` to broadcast custom events.
+         * Defaults to false. Requires `name` to follow "@org/slug" format for namespace enforcement.
+         */
+        emit_custom?: boolean;
+    };
+}
+
+/**
+ * Plugin Manifest
+ *
+ * Every plugin must export a `manifest` object conforming to this interface.
+ * The manifest is validated by the VeloCMS review pipeline before a plugin
+ * is accepted into the marketplace.
+ *
+ * @see https://velocms.org/developers/sdk#manifest
+ */
+
+/**
+ * Plugin type classification.
+ *
+ * - `block` — a content block renderable in the page builder and post editor.
+ * - `integration` — connects VeloCMS to an external service via hooks.
+ * - `widget` — a UI widget injected into the admin dashboard or sidebar.
+ */
+type PluginType = "block" | "integration" | "widget";
+/**
+ * Pricing model for the plugin.
+ *
+ * - `free` — no charge to install.
+ * - `paid` — one-time purchase via Stripe on the developer's connected account.
+ * - `subscription` — recurring subscription billed monthly.
+ */
+type PricingModel = "free" | "paid" | "subscription";
+/**
+ * Plugin pricing declaration.
+ *
+ * For paid and subscription plugins, the `price_usd` is the amount charged to
+ * the tenant. VeloCMS retains 20% platform fee; developers receive 80%.
+ */
+interface PluginPricing {
+    /** Pricing model */
+    model: PricingModel;
+    /**
+     * Price in USD cents (e.g. 999 = $9.99).
+     * Required when model is "paid" or "subscription".
+     */
+    price_usd?: number;
+    /**
+     * Stripe Price ID on the developer's connected account.
+     * Required when model is "paid" or "subscription".
+     */
+    stripe_price_id?: string;
+}
+/**
+ * Entry points for the plugin bundle.
+ *
+ * All paths are relative to the plugin root (e.g. `./dist/runtime.js`).
+ */
+interface PluginEntry {
+    /** Server-side runtime — executed in the V8 isolate sandbox on hook invocations. Required. */
+    runtime: string;
+    /** Admin UI component — loaded only in the admin dashboard. Optional. */
+    admin?: string;
+    /** Named block exports — required when plugin type is "block". */
+    blocks?: Record<string, {
+        /** Path to the React component file */
+        component: string;
+        /** Path to the JSON schema for block props */
+        schema: string;
+    }>;
+}
+/**
+ * Author information.
+ */
+interface PluginAuthor {
+    /** Author or organization name */
+    name: string;
+    /** Contact email for security disclosures */
+    email: string;
+    /** Author website or profile URL */
+    url?: string;
+}
+/**
+ * Repository information.
+ */
+interface PluginRepository {
+    type: "git";
+    url: string;
+}
+/**
+ * Engine compatibility requirements.
+ *
+ * The `velocms` field is a semver range string. The review pipeline checks
+ * compatibility against the current VeloCMS version.
+ *
+ * @example
+ * ```typescript
+ * engines: { velocms: ">=1.0.0" }
+ * // or range:
+ * engines: { velocms: ">=1.0.0 <2.0.0" }
+ * // or caret:
+ * engines: { velocms: "^1.0.0" }
+ * ```
+ */
+interface PluginEngines {
+    /** Supported VeloCMS semver range */
+    velocms: string;
+}
+/**
+ * VeloCMS Plugin Manifest v2
+ *
+ * This is the canonical shape of a plugin manifest. Export this as
+ * a named `manifest` const from your plugin's entry file.
+ *
+ * @example
+ * ```typescript
+ * import type { PluginManifest } from "@velocms/plugin-sdk";
+ *
+ * export const manifest: PluginManifest = {
+ *   $schema: "https://velocms.org/schemas/plugin-v2.json",
+ *   name: "@myorg/word-counter-pro",
+ *   displayName: "Word Counter Pro",
+ *   version: "1.0.0",
+ *   description: "Counts words and sets reading time estimates on every post.",
+ *   author: { name: "My Org", email: "plugins@myorg.com" },
+ *   type: "integration",
+ *   category: "writing",
+ *   icon: "./icon.png",
+ *   engines: { velocms: ">=1.0.0" },
+ *   capabilities: { content: { read: true } },
+ *   pricing: { model: "free" },
+ *   entry: { runtime: "./dist/runtime.js" },
+ *   permissions_displayed_to_user: ["Read your posts and pages"],
+ * };
+ * ```
+ */
+interface PluginManifest {
+    /** Schema identifier — must be "https://velocms.org/schemas/plugin-v2.json" */
+    $schema: "https://velocms.org/schemas/plugin-v2.json";
+    /**
+     * Scoped package name in "@author/plugin-slug" format.
+     * Must be unique across the VeloCMS marketplace.
+     */
+    name: string;
+    /** Human-readable plugin name shown in the marketplace */
+    displayName: string;
+    /** Semantic version string (e.g. "1.0.0", "2.1.3-beta.1") */
+    version: string;
+    /** Short description of what the plugin does (max 300 characters) */
+    description: string;
+    /** Author information */
+    author: PluginAuthor;
+    /** Plugin homepage URL */
+    homepage?: string;
+    /** Source code repository */
+    repository?: PluginRepository;
+    /** Plugin type classification */
+    type: PluginType;
+    /**
+     * Category for marketplace browsing.
+     * Examples: "analytics", "seo", "writing", "commerce", "social"
+     */
+    category: string;
+    /** Relative path to a 128x128 PNG icon file */
+    icon: string;
+    /** Supported VeloCMS versions */
+    engines: PluginEngines;
+    /** Capabilities the plugin requires (declare only what you use) */
+    capabilities: PluginCapabilities;
+    /** Pricing model */
+    pricing: PluginPricing;
+    /** Entry point file paths */
+    entry: PluginEntry;
+    /**
+     * Human-readable permission descriptions shown in the install modal.
+     * One sentence per item, written for a non-technical audience.
+     * Example: ["Read your posts and pages", "Make HTTP requests to Slack"]
+     */
+    permissions_displayed_to_user: string[];
+    /** SPDX license identifier (e.g. "MIT", "Apache-2.0"). Defaults to "proprietary". */
+    license?: string;
+}
+
+export type { CommerceCapabilities, ContentCapabilities, MemberCapabilities, PluginAuthor, PluginCapabilities, PluginEngines, PluginEntry, PluginManifest, PluginPricing, PluginRepository, PluginType, PricingModel, SchemaCapabilities };

package/dist/index.d.ts

@@ -0,0 +1,318 @@
+export { A as AfterMemberSignupPayload, a as AfterMemberUpdatePayload, b as AfterOrderCreatePayload, c as AfterPageCreatePayload, d as AfterPagePublishPayload, e as AfterPageUpdatePayload, f as AfterPostCreatePayload, g as AfterPostDeletePayload, h as AfterPostPublishPayload, i as AfterPostUpdatePayload, j as AfterProductCreatePayload, B as BeforeMemberDeletePayload, k as BeforePostPublishPayload, l as BeforePostPublishResult, C as ContextLogger, m as ContextSettings, n as ContextTenant, E as EventBusContext, o as EventName, H as HookContext, p as HookMember, q as HookName, r as HookPayloadMap, s as HookPost, O as OnAppStartPayload, t as OnDailySchedulePayload, P as PageHookData, u as PluginEventName, v as PluginEventPayload, S as SystemEventName, w as SystemEventPayloadMap } from './context-BCzNwlqR.js';
+
+/**
+ * Plugin Capabilities
+ *
+ * Capabilities follow the principle of least privilege. Declare only the
+ * capabilities your plugin actually needs — the VeloCMS review team will
+ * reject plugins with unnecessary permissions.
+ *
+ * @example
+ * ```typescript
+ * capabilities: {
+ *   content: { read: true },
+ *   network: true,
+ *   network_allowlist: ["api.example.com"],
+ * }
+ * ```
+ */
+/**
+ * Content access capabilities.
+ *
+ * `read` — read published + draft posts, pages, media metadata.
+ * `write` — create and update posts and pages.
+ * `delete` — delete posts, pages, and media.
+ */
+interface ContentCapabilities {
+    /** Read posts, pages, media metadata */
+    read?: boolean;
+    /** Create and update posts and pages */
+    write?: boolean;
+    /** Delete posts, pages, and media */
+    delete?: boolean;
+}
+/**
+ * Member access capabilities.
+ *
+ * `read` — read subscriber list (email redacted by default unless `read_pii` is true).
+ * `write` — create and update member records.
+ * `read_pii` — access raw member email addresses. Requires manual review justification.
+ */
+interface MemberCapabilities {
+    /** Read subscriber list (email redacted unless read_pii = true) */
+    read?: boolean;
+    /** Create and update member records */
+    write?: boolean;
+    /** Access raw member email addresses — requires review justification */
+    read_pii?: boolean;
+}
+/**
+ * Commerce capabilities.
+ *
+ * Requires the tenant to have commerce enabled.
+ */
+interface CommerceCapabilities {
+    /** Read products and orders */
+    read?: boolean;
+    /** Create and update products, process orders */
+    write?: boolean;
+}
+/**
+ * Database schema capabilities.
+ *
+ * `read` — introspect collection schemas.
+ * `modify` — add custom fields or collections. Requires architect review.
+ */
+interface SchemaCapabilities {
+    /** Read collection schemas */
+    read?: boolean;
+    /** Modify schemas — add fields or collections. HIGH RISK. Requires review. */
+    modify?: boolean;
+}
+/**
+ * Full capabilities declaration.
+ *
+ * All fields are optional — omit capabilities your plugin does not use.
+ */
+interface PluginCapabilities {
+    /** Content access */
+    content?: ContentCapabilities;
+    /** Member access */
+    members?: MemberCapabilities;
+    /** Commerce access */
+    commerce?: CommerceCapabilities;
+    /** Schema introspection/modification */
+    schema?: SchemaCapabilities;
+    /**
+     * External HTTP requests.
+     * If true, plugin can call any URL in `network_allowlist`.
+     * Network calls outside the allowlist are blocked at runtime.
+     */
+    network?: boolean;
+    /**
+     * Allowlisted domains for network access.
+     * Format: "hostname.tld" (no protocol, no path, no wildcards).
+     * Example: ["api.sendgrid.com", "hooks.slack.com"]
+     */
+    network_allowlist?: string[];
+    /** Send emails via the tenant's configured email provider */
+    email?: boolean;
+    /** UI integration points */
+    ui?: {
+        /** Inject a persistent sidebar widget */
+        sidebar?: boolean;
+        /** Inject toolbar items or panel tabs in the post editor */
+        post_editor?: boolean;
+        /** Add stat cards to the admin dashboard */
+        dashboard?: boolean;
+        /** Add a section to the admin settings page */
+        settings?: boolean;
+    };
+    /**
+     * Event bus subscription capability. (Phase 2.A)
+     *
+     * Declare which system events your plugin subscribes to and whether it
+     * emits custom events. The VeloCMS runtime will only inject ctx.events
+     * when this field is present.
+     *
+     * @example
+     * ```typescript
+     * capabilities: {
+     *   events: {
+     *     subscribe: ["post.published", "member.subscribed"],
+     *     emit_custom: true,
+     *   }
+     * }
+     * ```
+     */
+    events?: {
+        /**
+         * List of system event names the plugin subscribes to.
+         * Import `SystemEventName` from `@velocms/plugin-sdk` for the full catalog.
+         */
+        subscribe?: string[];
+        /**
+         * If true, the plugin may call `ctx.events.emit()` to broadcast custom events.
+         * Defaults to false. Requires `name` to follow "@org/slug" format for namespace enforcement.
+         */
+        emit_custom?: boolean;
+    };
+}
+
+/**
+ * Plugin Manifest
+ *
+ * Every plugin must export a `manifest` object conforming to this interface.
+ * The manifest is validated by the VeloCMS review pipeline before a plugin
+ * is accepted into the marketplace.
+ *
+ * @see https://velocms.org/developers/sdk#manifest
+ */
+
+/**
+ * Plugin type classification.
+ *
+ * - `block` — a content block renderable in the page builder and post editor.
+ * - `integration` — connects VeloCMS to an external service via hooks.
+ * - `widget` — a UI widget injected into the admin dashboard or sidebar.
+ */
+type PluginType = "block" | "integration" | "widget";
+/**
+ * Pricing model for the plugin.
+ *
+ * - `free` — no charge to install.
+ * - `paid` — one-time purchase via Stripe on the developer's connected account.
+ * - `subscription` — recurring subscription billed monthly.
+ */
+type PricingModel = "free" | "paid" | "subscription";
+/**
+ * Plugin pricing declaration.
+ *
+ * For paid and subscription plugins, the `price_usd` is the amount charged to
+ * the tenant. VeloCMS retains 20% platform fee; developers receive 80%.
+ */
+interface PluginPricing {
+    /** Pricing model */
+    model: PricingModel;
+    /**
+     * Price in USD cents (e.g. 999 = $9.99).
+     * Required when model is "paid" or "subscription".
+     */
+    price_usd?: number;
+    /**
+     * Stripe Price ID on the developer's connected account.
+     * Required when model is "paid" or "subscription".
+     */
+    stripe_price_id?: string;
+}
+/**
+ * Entry points for the plugin bundle.
+ *
+ * All paths are relative to the plugin root (e.g. `./dist/runtime.js`).
+ */
+interface PluginEntry {
+    /** Server-side runtime — executed in the V8 isolate sandbox on hook invocations. Required. */
+    runtime: string;
+    /** Admin UI component — loaded only in the admin dashboard. Optional. */
+    admin?: string;
+    /** Named block exports — required when plugin type is "block". */
+    blocks?: Record<string, {
+        /** Path to the React component file */
+        component: string;
+        /** Path to the JSON schema for block props */
+        schema: string;
+    }>;
+}
+/**
+ * Author information.
+ */
+interface PluginAuthor {
+    /** Author or organization name */
+    name: string;
+    /** Contact email for security disclosures */
+    email: string;
+    /** Author website or profile URL */
+    url?: string;
+}
+/**
+ * Repository information.
+ */
+interface PluginRepository {
+    type: "git";
+    url: string;
+}
+/**
+ * Engine compatibility requirements.
+ *
+ * The `velocms` field is a semver range string. The review pipeline checks
+ * compatibility against the current VeloCMS version.
+ *
+ * @example
+ * ```typescript
+ * engines: { velocms: ">=1.0.0" }
+ * // or range:
+ * engines: { velocms: ">=1.0.0 <2.0.0" }
+ * // or caret:
+ * engines: { velocms: "^1.0.0" }
+ * ```
+ */
+interface PluginEngines {
+    /** Supported VeloCMS semver range */
+    velocms: string;
+}
+/**
+ * VeloCMS Plugin Manifest v2
+ *
+ * This is the canonical shape of a plugin manifest. Export this as
+ * a named `manifest` const from your plugin's entry file.
+ *
+ * @example
+ * ```typescript
+ * import type { PluginManifest } from "@velocms/plugin-sdk";
+ *
+ * export const manifest: PluginManifest = {
+ *   $schema: "https://velocms.org/schemas/plugin-v2.json",
+ *   name: "@myorg/word-counter-pro",
+ *   displayName: "Word Counter Pro",
+ *   version: "1.0.0",
+ *   description: "Counts words and sets reading time estimates on every post.",
+ *   author: { name: "My Org", email: "plugins@myorg.com" },
+ *   type: "integration",
+ *   category: "writing",
+ *   icon: "./icon.png",
+ *   engines: { velocms: ">=1.0.0" },
+ *   capabilities: { content: { read: true } },
+ *   pricing: { model: "free" },
+ *   entry: { runtime: "./dist/runtime.js" },
+ *   permissions_displayed_to_user: ["Read your posts and pages"],
+ * };
+ * ```
+ */
+interface PluginManifest {
+    /** Schema identifier — must be "https://velocms.org/schemas/plugin-v2.json" */
+    $schema: "https://velocms.org/schemas/plugin-v2.json";
+    /**
+     * Scoped package name in "@author/plugin-slug" format.
+     * Must be unique across the VeloCMS marketplace.
+     */
+    name: string;
+    /** Human-readable plugin name shown in the marketplace */
+    displayName: string;
+    /** Semantic version string (e.g. "1.0.0", "2.1.3-beta.1") */
+    version: string;
+    /** Short description of what the plugin does (max 300 characters) */
+    description: string;
+    /** Author information */
+    author: PluginAuthor;
+    /** Plugin homepage URL */
+    homepage?: string;
+    /** Source code repository */
+    repository?: PluginRepository;
+    /** Plugin type classification */
+    type: PluginType;
+    /**
+     * Category for marketplace browsing.
+     * Examples: "analytics", "seo", "writing", "commerce", "social"
+     */
+    category: string;
+    /** Relative path to a 128x128 PNG icon file */
+    icon: string;
+    /** Supported VeloCMS versions */
+    engines: PluginEngines;
+    /** Capabilities the plugin requires (declare only what you use) */
+    capabilities: PluginCapabilities;
+    /** Pricing model */
+    pricing: PluginPricing;
+    /** Entry point file paths */
+    entry: PluginEntry;
+    /**
+     * Human-readable permission descriptions shown in the install modal.
+     * One sentence per item, written for a non-technical audience.
+     * Example: ["Read your posts and pages", "Make HTTP requests to Slack"]
+     */
+    permissions_displayed_to_user: string[];
+    /** SPDX license identifier (e.g. "MIT", "Apache-2.0"). Defaults to "proprietary". */
+    license?: string;
+}
+
+export type { CommerceCapabilities, ContentCapabilities, MemberCapabilities, PluginAuthor, PluginCapabilities, PluginEngines, PluginEntry, PluginManifest, PluginPricing, PluginRepository, PluginType, PricingModel, SchemaCapabilities };

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}