@velocms/plugin-sdk 1.0.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VeloCMS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @velocms/plugin-sdk
+
+TypeScript SDK for VeloCMS plugin development.
+
+## Installation
+
+```bash
+npm install @velocms/plugin-sdk --save-dev
+```
+
+## Quick Start
+
+```typescript
+import type { PluginManifest, HookContext, AfterPostCreatePayload } from "@velocms/plugin-sdk";
+
+// 1. Define your manifest
+export const manifest: PluginManifest = {
+  $schema: "https://velocms.org/schemas/plugin-v2.json",
+  name: "@myorg/my-plugin",
+  displayName: "My Plugin",
+  version: "1.0.0",
+  description: "Sends a Slack notification on every new post.",
+  author: { name: "My Org", email: "plugins@myorg.com" },
+  type: "integration",
+  category: "social",
+  icon: "./icon.png",
+  engines: { velocms: ">=1.0.0" },
+  capabilities: {
+    content: { read: true },
+    network: true,
+    network_allowlist: ["hooks.slack.com"],
+  },
+  pricing: { model: "free" },
+  entry: { runtime: "./dist/runtime.js" },
+  permissions_displayed_to_user: [
+    "Read your posts",
+    "Make HTTP requests to Slack",
+  ],
+};
+
+// 2. Export hook handlers
+export async function afterPostCreate(
+  payload: AfterPostCreatePayload,
+  ctx: HookContext
+): Promise<void> {
+  await ctx.fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      text: `New post published: ${payload.post.title}`,
+    }),
+  });
+}
+```
+
+## Phase 2.A: Event Bus
+
+SDK version `1.0.0-alpha.2` adds a real-time event bus. Plugins can subscribe to
+VeloCMS system events and emit custom namespaced events.
+
+### Declare the capability
+
+```typescript
+export const manifest: PluginManifest = {
+  // ...
+  capabilities: {
+    events: {
+      subscribe: ["post.published", "member.subscribed"],
+      emit_custom: true,  // only if you call ctx.events.emit()
+    },
+  },
+};
+```
+
+### Subscribe to system events
+
+Register subscriptions in `onAppStart` — VeloCMS fires this hook once when
+your plugin's runtime loads, which is where `ctx.events.on()` registrations
+belong (registering inside a request-scoped hook like `afterPostCreate`
+would re-subscribe the same handler on every invocation).
+
+```typescript
+import type { OnAppStartPayload, HookContext } from "@velocms/plugin-sdk";
+
+export async function onAppStart(
+  _payload: OnAppStartPayload,
+  ctx: HookContext
+): Promise<void> {
+  ctx.events.on("post.published", async ({ post }) => {
+    await ctx.fetch("https://hooks.slack.com/services/xxx/yyy/zzz", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text: `New post: ${post.title}` }),
+    });
+  });
+
+  ctx.events.on("member.subscribed", async ({ member, source }) => {
+    await ctx.kv.set("last_signup_source", source);
+  });
+}
+```
+
+### Emit a custom event
+
+Custom events must be namespaced to your plugin's org prefix (`@org/`).
+Other plugins can subscribe to your events by name. Emitting requires
+`capabilities.events.emit_custom: true` in your manifest.
+
+```typescript
+// Emitting (from within any hook handler that receives ctx)
+await ctx.events.emit("@myorg/slack-notifier:webhook-sent", {
+  webhookUrl: "https://hooks.slack.com/...",
+  postTitle: post.title,
+});
+
+// Subscribing (from another plugin's onAppStart)
+ctx.events.on("@myorg/slack-notifier:webhook-sent", async (payload) => {
+  await ctx.kv.set("last_slack_event", JSON.stringify(payload));
+});
+```
+
+### Full example: Slack Notifier
+
+A plugin is just a module exporting a `manifest` plus one function per hook
+name it wants to handle — there is no `definePlugin()` wrapper. VeloCMS
+looks up handlers by matching the exported function name to the `HookName`
+union.
+
+```typescript
+import type {
+  PluginManifest,
+  OnAppStartPayload,
+  AfterPostPublishPayload,
+  HookContext,
+} from "@velocms/plugin-sdk";
+
+export const manifest: PluginManifest = {
+  $schema: "https://velocms.org/schemas/plugin-v2.json",
+  name: "@myorg/slack-notifier",
+  displayName: "Slack Notifier",
+  version: "1.0.0",
+  description: "Posts to Slack whenever a new post is published.",
+  author: { name: "My Org", email: "plugins@myorg.com" },
+  type: "integration",
+  category: "social",
+  icon: "./icon.png",
+  engines: { velocms: ">=1.0.0" },
+  capabilities: { network: true, network_allowlist: ["hooks.slack.com"] },
+  pricing: { model: "free" },
+  entry: { runtime: "./dist/runtime.js" },
+  permissions_displayed_to_user: ["Make HTTP requests to Slack"],
+};
+
+export async function onAppStart(
+  _payload: OnAppStartPayload,
+  ctx: HookContext
+): Promise<void> {
+  ctx.log.info("Slack Notifier activated");
+}
+
+export async function afterPostPublish(
+  payload: AfterPostPublishPayload,
+  ctx: HookContext
+): Promise<void> {
+  const webhookUrl = await ctx.kv.get("slack_webhook_url");
+  if (!webhookUrl) return;
+  await ctx.fetch(webhookUrl, {
+    method: "POST",
+    body: JSON.stringify({ text: `New post: ${payload.post.title}` }),
+  });
+}
+```
+
+### System event catalog
+
+| Event | Payload |
+|-------|---------|
+| `post.created` | `{ post: HookPost }` |
+| `post.updated` | `{ post: HookPost; changedFields: string[] }` |
+| `post.published` | `{ post: HookPost }` |
+| `post.unpublished` | `{ post: HookPost }` |
+| `post.deleted` | `{ postId: string; slug: string }` |
+| `member.subscribed` | `{ member: HookMember; source: string }` |
+| `member.unsubscribed` | `{ memberId: string }` |
+| `member.tier_changed` | `{ member: HookMember; previousTier: string }` |
+| `comment.posted` | `{ commentId: string; postId: string; authorEmail?: string }` |
+| `comment.approved` | `{ commentId: string; postId: string }` |
+| `comment.deleted` | `{ commentId: string; postId: string }` |
+| `page.published` | `{ page: PageHookData }` |
+| `media.uploaded` | `{ mediaId: string; filename: string; mimeType: string }` |
+
+### Delivery semantics
+
+- **Best-effort, not guaranteed.** If the Railway container restarts mid-flight,
+  events in transit may be missed. Plugin handlers must be idempotent.
+- **5-second timeout per handler.** A hung handler is killed; the next handler still runs.
+- **Circuit-breaker.** 3 consecutive handler errors → circuit opens for 5 minutes.
+  Events are not dispatched to a circuit-open handler. Reactivating the plugin resets the circuit.
+- **30-day audit log.** All events are persisted in `plugin_events` for 30 days.
+  Use this for debugging via the PocketBase admin panel.
+
+## Documentation
+
+Full SDK reference: [velocms.org/developers/sdk](https://velocms.org/developers/sdk)
+
+## Publishing to the Marketplace
+
+1. Build your plugin: `npm run build`
+2. Upload to [velocms.org/developers/submit](https://velocms.org/developers/submit)
+3. The automated review pipeline will scan your bundle
+4. Manual review by the VeloCMS team (2-5 business days)
+5. Published to the marketplace
+
+## License
+
+MIT

package/dist/context-BCzNwlqR.d.cts

@@ -0,0 +1,413 @@
+/**
+ * Hook Registry
+ *
+ * Plugins subscribe to lifecycle hooks by exporting handler functions from
+ * their `entry.runtime` module. The function name must match the hook name.
+ *
+ * All handlers receive a typed `HookContext` and optional payload, and must
+ * return a Promise<void> or Promise<HookResult>.
+ *
+ * @example
+ * ```typescript
+ * import type { AfterPostCreatePayload, HookContext } from "@velocms/plugin-sdk";
+ *
+ * export async function afterPostCreate(
+ *   payload: AfterPostCreatePayload,
+ *   ctx: HookContext
+ * ): Promise<void> {
+ *   const wordCount = payload.post.content.split(/\s+/).length;
+ *   await ctx.fetch("https://api.example.com/stats", {
+ *     method: "POST",
+ *     headers: { "Content-Type": "application/json" },
+ *     body: JSON.stringify({ postId: payload.post.id, wordCount }),
+ *   });
+ * }
+ * ```
+ *
+ * @see https://velocms.org/developers/sdk#hooks
+ */
+/** Minimal post data provided to hooks. */
+interface HookPost {
+    id: string;
+    title: string;
+    slug: string;
+    status: "draft" | "published" | "archived";
+    /** Rich text content (HTML string) */
+    content: string;
+    excerpt?: string;
+    published_at?: string;
+    reading_time_minutes?: number;
+    tags: string[];
+    author_id?: string;
+    category_id?: string;
+}
+/** Minimal member data provided to hooks. Email is available when `members.read_pii` capability is granted. */
+interface HookMember {
+    id: string;
+    /** Available only when `members.read_pii` capability is granted */
+    email?: string;
+    /** "free" or "paid" */
+    tier: string;
+    newsletter_subscribed: boolean;
+    created: string;
+}
+interface AfterPostCreatePayload {
+    post: HookPost;
+}
+interface AfterPostUpdatePayload {
+    post: HookPost;
+    /** Field names that changed in this update */
+    changedFields: string[];
+}
+interface AfterPostDeletePayload {
+    postId: string;
+    slug: string;
+}
+interface BeforePostPublishPayload {
+    post: HookPost;
+}
+/** Return value from `beforePostPublish` — can augment the post. */
+interface BeforePostPublishResult {
+    /** Suggested tags to add to the post */
+    suggestedTags?: string[];
+    /** Override the SEO title */
+    seoTitle?: string;
+    /** Override the SEO description */
+    seoDescription?: string;
+}
+interface AfterPostPublishPayload {
+    post: HookPost;
+}
+interface AfterMemberSignupPayload {
+    member: HookMember;
+    /** Source of signup: "checkout", "magic_link", "import" */
+    source: string;
+}
+interface AfterMemberUpdatePayload {
+    member: HookMember;
+    changedFields: string[];
+}
+interface BeforeMemberDeletePayload {
+    memberId: string;
+}
+interface PageHookData {
+    id: string;
+    title: string;
+    slug: string;
+    status: "draft" | "published";
+}
+interface AfterPageCreatePayload {
+    page: PageHookData;
+}
+interface AfterPageUpdatePayload {
+    page: PageHookData;
+}
+interface AfterPagePublishPayload {
+    page: PageHookData;
+}
+interface AfterOrderCreatePayload {
+    orderId: string;
+    productId: string;
+    memberId?: string;
+    amount_cents: number;
+    currency: string;
+}
+interface AfterProductCreatePayload {
+    productId: string;
+    name: string;
+    price_cents: number;
+    currency: string;
+}
+/** Fired when the plugin is first loaded (app start). Use for initialization. */
+interface OnAppStartPayload {
+    /** VeloCMS version string */
+    velocmsVersion: string;
+}
+/** Fired daily by the scheduler cron. Use for periodic tasks. */
+interface OnDailySchedulePayload {
+    /** UTC date string (e.g. "2026-04-19") */
+    date: string;
+}
+/** All available hook names. */
+type HookName = "afterPostCreate" | "afterPostUpdate" | "afterPostDelete" | "beforePostPublish" | "afterPostPublish" | "afterMemberSignup" | "afterMemberUpdate" | "beforeMemberDelete" | "afterPageCreate" | "afterPageUpdate" | "afterPagePublish" | "afterOrderCreate" | "afterProductCreate" | "onAppStart" | "onDailySchedule";
+/** Map from hook name to its payload type. */
+interface HookPayloadMap {
+    afterPostCreate: AfterPostCreatePayload;
+    afterPostUpdate: AfterPostUpdatePayload;
+    afterPostDelete: AfterPostDeletePayload;
+    beforePostPublish: BeforePostPublishPayload;
+    afterPostPublish: AfterPostPublishPayload;
+    afterMemberSignup: AfterMemberSignupPayload;
+    afterMemberUpdate: AfterMemberUpdatePayload;
+    beforeMemberDelete: BeforeMemberDeletePayload;
+    afterPageCreate: AfterPageCreatePayload;
+    afterPageUpdate: AfterPageUpdatePayload;
+    afterPagePublish: AfterPagePublishPayload;
+    afterOrderCreate: AfterOrderCreatePayload;
+    afterProductCreate: AfterProductCreatePayload;
+    onAppStart: OnAppStartPayload;
+    onDailySchedule: OnDailySchedulePayload;
+}
+
+/**
+ * Plugin SDK — Event Bus Types
+ *
+ * Phase 2.A — Plugin SDK Event Bus
+ * SDK version: 1.0.0-alpha.2
+ *
+ * Exports the system event catalog and the EventBusContext interface
+ * that is injected as ctx.events when a plugin declares
+ * `capabilities.events` in its manifest.
+ *
+ * @see https://velocms.org/developers/sdk#event-bus
+ */
+
+/**
+ * All system event names emitted by VeloCMS core.
+ *
+ * Use these as the first argument to `ctx.events.on()`.
+ *
+ * @example
+ * ```typescript
+ * ctx.events.on("post.published", async ({ post }) => {
+ *   await notifySlack(post.title);
+ * });
+ * ```
+ */
+type SystemEventName = "post.created" | "post.updated" | "post.published" | "post.unpublished" | "post.deleted" | "member.subscribed" | "member.unsubscribed" | "member.tier_changed" | "comment.posted" | "comment.approved" | "comment.deleted" | "page.published" | "media.uploaded";
+/**
+ * Plugin-emitted event names follow the pattern "@org/plugin:event-name".
+ *
+ * Your org is the first segment of your plugin's `name` field in the manifest.
+ * Example: if `name: "@myorg/slack-notifier"`, you may emit events starting
+ * with "@myorg/".
+ */
+type PluginEventName = `@${string}/${string}:${string}`;
+/** Union of all valid event names: system events + plugin-namespaced events. */
+type EventName = SystemEventName | PluginEventName;
+/**
+ * Maps each SystemEventName to its payload type.
+ *
+ * This is the canonical typed catalog for handlers registered via ctx.events.on().
+ */
+interface SystemEventPayloadMap {
+    "post.created": {
+        post: HookPost;
+    };
+    "post.updated": {
+        post: HookPost;
+        changedFields: string[];
+    };
+    "post.published": {
+        post: HookPost;
+    };
+    "post.unpublished": {
+        post: HookPost;
+    };
+    "post.deleted": {
+        postId: string;
+        slug: string;
+    };
+    "member.subscribed": {
+        member: HookMember;
+        source: string;
+    };
+    "member.unsubscribed": {
+        memberId: string;
+    };
+    "member.tier_changed": {
+        member: HookMember;
+        previousTier: string;
+    };
+    "comment.posted": {
+        commentId: string;
+        postId: string;
+        authorEmail?: string;
+    };
+    "comment.approved": {
+        commentId: string;
+        postId: string;
+    };
+    "comment.deleted": {
+        commentId: string;
+        postId: string;
+    };
+    "page.published": {
+        page: PageHookData;
+    };
+    "media.uploaded": {
+        mediaId: string;
+        filename: string;
+        mimeType: string;
+    };
+}
+/**
+ * The event bus context injected as `ctx.events`.
+ *
+ * Available when the plugin manifest declares:
+ * ```typescript
+ * capabilities: {
+ *   events: {
+ *     subscribe: ["post.published", "member.subscribed"],
+ *     emit_custom: true,  // required if you call ctx.events.emit()
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * export async function onActivate(ctx: HookContext) {
+ *   ctx.events.on("post.published", async ({ post }) => {
+ *     await ctx.fetch("https://hooks.slack.com/...", {
+ *       method: "POST",
+ *       body: JSON.stringify({ text: `New post: ${post.title}` }),
+ *     });
+ *   });
+ * }
+ * ```
+ */
+interface EventBusContext {
+    /**
+     * Subscribe to a typed system event.
+     *
+     * @param eventName - A SystemEventName from the catalog above
+     * @param handler - Async handler receiving the typed payload
+     * @returns A function to unsubscribe this specific handler
+     */
+    on<E extends SystemEventName>(eventName: E, handler: (payload: SystemEventPayloadMap[E]) => void | Promise<void>): () => void;
+    /**
+     * Subscribe to a plugin-namespaced event.
+     * Used for cross-plugin communication.
+     *
+     * @param eventName - A PluginEventName in "@org/plugin:event" format
+     * @param handler - Handler receiving an untyped payload (validate at runtime)
+     * @returns A function to unsubscribe this specific handler
+     */
+    on(eventName: PluginEventName, handler: (payload: Record<string, unknown>) => void | Promise<void>): () => void;
+    /**
+     * Emit a custom event namespaced to your plugin.
+     *
+     * Requires `capabilities.events.emit_custom: true` in your manifest.
+     * The event_name MUST start with "@{your-org}/".
+     *
+     * @throws CapabilityError if namespace does not match manifest name
+     *
+     * @example
+     * ```typescript
+     * await ctx.events.emit("@myorg/slack-notifier:ready", {
+     *   tenantId: ctx.tenant.id,
+     * });
+     * ```
+     */
+    emit(eventName: PluginEventName, payload: Record<string, unknown>): Promise<void>;
+}
+/** A generic plugin event payload — used when the event type is unknown at compile time. */
+type PluginEventPayload = Record<string, unknown>;
+
+/**
+ * Hook Context
+ *
+ * Every hook handler receives a `HookContext` as its second argument.
+ * The context provides safe, capability-enforced access to VeloCMS APIs.
+ *
+ * Access is sandboxed: attempting to use an API your plugin did not declare
+ * in `manifest.capabilities` will throw a `CapabilityError` at runtime.
+ *
+ * @example
+ * ```typescript
+ * export async function afterPostCreate(payload, ctx: HookContext): Promise<void> {
+ *   // Tenant info
+ *   const tenantId = ctx.tenant.id;
+ *
+ *   // Network fetch (requires capabilities.network = true)
+ *   const res = await ctx.fetch("https://hooks.slack.com/services/xxx/yyy/zzz", {
+ *     method: "POST",
+ *     body: JSON.stringify({ text: `New post: ${payload.post.title}` }),
+ *   });
+ * }
+ * ```
+ *
+ * @see https://velocms.org/developers/sdk#context
+ */
+
+/** Minimal tenant data available to plugins. */
+interface ContextTenant {
+    id: string;
+    slug: string;
+    /** Tenant's configured locale (e.g. "en-US") */
+    locale: string;
+}
+/** Minimal site settings available to plugins. */
+interface ContextSettings {
+    blogName: string;
+    siteUrl: string;
+    /** Active theme slug */
+    theme: string;
+    /** "free" | "pro" | "business" | "agency" */
+    plan: string;
+}
+/** Logger bound to the current plugin invocation. */
+interface ContextLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * The context object passed to every hook handler.
+ *
+ * All async operations in context are bound to the sandbox's CPU budget
+ * (default 500ms). Long-running tasks should be offloaded via `ctx.fetch`
+ * to an external queue.
+ */
+interface HookContext {
+    /** Current tenant */
+    tenant: ContextTenant;
+    /** Site settings (non-sensitive fields only) */
+    settings: ContextSettings;
+    /**
+     * Scoped HTTP fetch.
+     *
+     * - Requires `capabilities.network = true`
+     * - URL host must be in `capabilities.network_allowlist`
+     * - Timeout: 5 seconds (enforced by sandbox)
+     * - Response body is limited to 1MB
+     *
+     * Behaves like the global `fetch()` API.
+     */
+    fetch: typeof fetch;
+    /** Plugin-scoped logger. Messages appear in the VeloCMS plugin activity log. */
+    log: ContextLogger;
+    /**
+     * Key-value storage scoped to this plugin + tenant.
+     * Persists across hook invocations. 1MB limit per plugin.
+     *
+     * @example
+     * ```typescript
+     * // Store a value
+     * await ctx.kv.set("last_run", new Date().toISOString());
+     *
+     * // Retrieve a value
+     * const lastRun = await ctx.kv.get("last_run");
+     * ```
+     */
+    kv: {
+        get(key: string): Promise<string | null>;
+        set(key: string, value: string): Promise<void>;
+        delete(key: string): Promise<void>;
+    };
+    /**
+     * Event bus — subscribe to VeloCMS system events and emit custom
+     * namespaced events. (Phase 2.A)
+     *
+     * Present on every `HookContext`, same as `fetch`/`kv`/`log`. As with
+     * those accessors, calling `.on()` / `.emit()` without declaring
+     * `capabilities.events` in your manifest throws a `CapabilityError` at
+     * runtime — the type is unconditional, the capability check happens
+     * when you actually use it.
+     *
+     * @see https://velocms.org/developers/sdk#event-bus
+     */
+    events: EventBusContext;
+}
+
+export type { AfterMemberSignupPayload as A, BeforeMemberDeletePayload as B, ContextLogger as C, EventBusContext as E, HookContext as H, OnAppStartPayload as O, PageHookData as P, SystemEventName as S, AfterMemberUpdatePayload as a, AfterOrderCreatePayload as b, AfterPageCreatePayload as c, AfterPagePublishPayload as d, AfterPageUpdatePayload as e, AfterPostCreatePayload as f, AfterPostDeletePayload as g, AfterPostPublishPayload as h, AfterPostUpdatePayload as i, AfterProductCreatePayload as j, BeforePostPublishPayload as k, BeforePostPublishResult as l, ContextSettings as m, ContextTenant as n, EventName as o, HookMember as p, HookName as q, HookPayloadMap as r, HookPost as s, OnDailySchedulePayload as t, PluginEventName as u, PluginEventPayload as v, SystemEventPayloadMap as w };