@velocms/plugin-sdk 1.0.0-alpha.2

package/dist/context-BCzNwlqR.d.ts

@@ -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 };

package/dist/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+module.exports = __toCommonJS(src_exports);
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @velocms/plugin-sdk\n *\n * TypeScript SDK for VeloCMS plugin development.\n *\n * Provides types for capability manifests, hook registry, and context accessors.\n * Plugins built against this SDK can be submitted to the VeloCMS marketplace.\n *\n * @example\n * ```typescript\n * import type { PluginManifest, HookContext } from \"@velocms/plugin-sdk\";\n *\n * export const manifest: PluginManifest = {\n *   $schema: \"https://velocms.org/schemas/plugin-v2.json\",\n *   name: \"@myorg/my-plugin\",\n *   displayName: \"My Plugin\",\n *   version: \"1.0.0\",\n *   description: \"Does something useful\",\n *   author: { name: \"My Org\", email: \"plugins@myorg.com\" },\n *   type: \"integration\",\n *   category: \"analytics\",\n *   icon: \"./icon.png\",\n *   engines: { velocms: \">=1.0.0\" },\n *   capabilities: { network: true },\n *   pricing: { model: \"free\" },\n *   entry: { runtime: \"./dist/runtime.js\" },\n *   permissions_displayed_to_user: [\"Make HTTP requests to external services\"],\n * };\n * ```\n *\n * @packageDocumentation\n */\n\nexport * from \"./types/manifest\";\nexport * from \"./types/hooks\";\nexport * from \"./types/context\";\nexport * from \"./types/capabilities\";\n// Phase 2.A — Event Bus\nexport * from \"./types/events\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}