@velocms/plugin-sdk 1.0.0-alpha.2

package/dist/test-helpers.cjs

@@ -0,0 +1,126 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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/test-helpers.ts
+var test_helpers_exports = {};
+__export(test_helpers_exports, {
+  mockVelocms: () => mockVelocms,
+  resetMockContext: () => resetMockContext
+});
+module.exports = __toCommonJS(test_helpers_exports);
+function mockVelocms(opts = {}) {
+  const fetchCalls = [];
+  const logs = [];
+  const kvStore = { ...opts.kvStore ?? {} };
+  const emittedEvents = [];
+  const eventHandlers = /* @__PURE__ */ new Map();
+  const onEvent = ((eventName, handler) => {
+    let set = eventHandlers.get(eventName);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      eventHandlers.set(eventName, set);
+    }
+    set.add(handler);
+    return () => {
+      eventHandlers.get(eventName)?.delete(handler);
+    };
+  });
+  const emitEvent = async (eventName, payload) => {
+    emittedEvents.push({ eventName, payload });
+    const handlers = eventHandlers.get(eventName);
+    if (handlers) {
+      for (const handler of handlers) {
+        await handler(payload);
+      }
+    }
+  };
+  const events = { on: onEvent, emit: emitEvent };
+  const fetchQueue = Array.isArray(opts.fetchResponse) ? [...opts.fetchResponse] : opts.fetchResponse ? [opts.fetchResponse] : [];
+  const defaultFetchResponse = { ok: true, status: 200, data: {} };
+  const mockFetch = (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    fetchCalls.push({ url, options: init });
+    const response = fetchQueue.length > 0 ? fetchQueue.shift() ?? defaultFetchResponse : defaultFetchResponse;
+    const body = response.text ?? JSON.stringify(response.data ?? {});
+    const status = response.status ?? (response.ok ? 200 : 400);
+    return Promise.resolve(
+      new Response(body, {
+        status,
+        headers: { "Content-Type": "application/json" }
+      })
+    );
+  };
+  const tenant = {
+    id: opts.tenant?.id ?? "test-tenant-id",
+    slug: opts.tenant?.slug ?? "test-blog",
+    locale: opts.tenant?.locale ?? "en-US"
+  };
+  const settings = {
+    blogName: opts.settings?.blogName ?? "Test Blog",
+    siteUrl: opts.settings?.siteUrl ?? "https://test.velocms.org",
+    theme: opts.settings?.theme ?? "default",
+    plan: opts.settings?.plan ?? "pro"
+  };
+  const ctx = {
+    tenant,
+    settings,
+    fetch: mockFetch,
+    log: {
+      info: (message, data) => logs.push({ level: "info", message, data }),
+      warn: (message, data) => logs.push({ level: "warn", message, data }),
+      error: (message, data) => logs.push({ level: "error", message, data })
+    },
+    kv: {
+      get: (key) => Promise.resolve(kvStore[key] ?? null),
+      set: (key, value) => {
+        kvStore[key] = value;
+        return Promise.resolve();
+      },
+      delete: (key) => {
+        delete kvStore[key];
+        return Promise.resolve();
+      }
+    },
+    events,
+    _fetchCalls: fetchCalls,
+    _logs: logs,
+    _kvStore: kvStore,
+    _emittedEvents: emittedEvents,
+    _dispatchSystemEvent: async (eventName, payload) => {
+      const handlers = eventHandlers.get(eventName);
+      if (handlers) {
+        for (const handler of handlers) {
+          await handler(payload);
+        }
+      }
+    }
+  };
+  return ctx;
+}
+function resetMockContext(ctx) {
+  ctx._fetchCalls.length = 0;
+  ctx._logs.length = 0;
+  ctx._emittedEvents.length = 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  mockVelocms,
+  resetMockContext
+});
+//# sourceMappingURL=test-helpers.cjs.map

package/dist/test-helpers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/test-helpers.ts"],"sourcesContent":["/**\n * VeloCMS Plugin SDK — Test Helpers\n *\n * Provides mock implementations of the host bridge contract so plugin authors\n * can write unit tests without a running VeloCMS instance.\n *\n * @example\n * ```typescript\n * import { mockVelocms } from \"@velocms/plugin-sdk/test-helpers\";\n *\n * const ctx = mockVelocms({\n *   tenant: { id: \"t1\", slug: \"my-blog\", locale: \"en-US\" },\n *   fetchResponse: { ok: true, data: { result: \"ok\" } },\n * });\n *\n * await myPlugin.handlePostPublish({ post: { slug: \"hello\" } }, ctx);\n * expect(ctx._fetchCalls).toHaveLength(1);\n * expect(ctx._fetchCalls[0].url).toBe(\"https://hooks.slack.com/...\");\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { HookContext, ContextTenant, ContextSettings } from \"./types/context\";\nimport type {\n  EventBusContext,\n  EventName,\n  SystemEventName,\n  PluginEventName,\n  SystemEventPayloadMap,\n} from \"./types/events\";\n\n// ---------------------------------------------------------------------------\n// Mock configuration types\n// ---------------------------------------------------------------------------\n\nexport interface MockFetchResponse {\n  ok: boolean;\n  status?: number;\n  /** JSON body returned by the mock */\n  data?: unknown;\n  text?: string;\n}\n\nexport interface MockVelocmsOptions {\n  tenant?: Partial<ContextTenant>;\n  settings?: Partial<ContextSettings>;\n  /**\n   * Static response for all fetch() calls.\n   * Pass an array to return different responses for successive calls.\n   */\n  fetchResponse?: MockFetchResponse | MockFetchResponse[];\n  /**\n   * Pre-populated key-value store entries.\n   */\n  kvStore?: Record<string, string>;\n}\n\n// ---------------------------------------------------------------------------\n// Instrumented context (extends HookContext with test introspection)\n// ---------------------------------------------------------------------------\n\nexport interface MockFetchCall {\n  url: string;\n  options?: RequestInit;\n}\n\n/** A custom event recorded when the plugin under test calls `ctx.events.emit()`. */\nexport interface MockEmittedEvent {\n  eventName: PluginEventName;\n  payload: Record<string, unknown>;\n}\n\nexport interface MockHookContext extends HookContext {\n  /** All fetch() calls made during the test */\n  _fetchCalls: MockFetchCall[];\n  /** All log messages emitted during the test */\n  _logs: Array<{ level: \"info\" | \"warn\" | \"error\"; message: string; data?: Record<string, unknown> }>;\n  /** Current key-value store state */\n  _kvStore: Record<string, string>;\n  /** All events emitted during the test via `ctx.events.emit()` */\n  _emittedEvents: MockEmittedEvent[];\n  /**\n   * Test-only helper: simulate VeloCMS core firing a system event, invoking\n   * every handler the plugin under test registered via `ctx.events.on(...)`.\n   *\n   * Not part of the real `HookContext` — the live event bus fires these\n   * automatically; in a unit test there's no running VeloCMS instance to\n   * fire them for you.\n   *\n   * @example\n   * ```typescript\n   * const ctx = mockVelocms();\n   * await myPlugin.onActivate(ctx); // registers ctx.events.on(\"post.published\", ...)\n   * await ctx._dispatchSystemEvent(\"post.published\", { post: { id: \"1\", title: \"Hi\" } });\n   * ```\n   */\n  _dispatchSystemEvent<E extends SystemEventName>(\n    eventName: E,\n    payload: SystemEventPayloadMap[E]\n  ): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a mock `HookContext` for unit testing plugin hook handlers.\n *\n * The returned context is a fully-instrumented stand-in that:\n * - Records all `ctx.fetch()` calls in `_fetchCalls`\n * - Records all `ctx.log.*()` calls in `_logs`\n * - Provides an in-memory `ctx.kv` store (seeded from `opts.kvStore`)\n * - Returns controlled responses from `opts.fetchResponse`\n *\n * No network requests are made. No VeloCMS instance is required.\n *\n * @param opts - Optional overrides for tenant, settings, fetch responses, kv seed\n * @returns    - Instrumented `MockHookContext` compatible with `HookContext`\n */\nexport function mockVelocms(opts: MockVelocmsOptions = {}): MockHookContext {\n  const fetchCalls: MockFetchCall[] = [];\n  const logs: MockHookContext[\"_logs\"] = [];\n  const kvStore: Record<string, string> = { ...(opts.kvStore ?? {}) };\n  const emittedEvents: MockEmittedEvent[] = [];\n\n  // In-memory pub/sub for ctx.events — mirrors the real EventBusContext\n  // shape without a running VeloCMS instance.\n  const eventHandlers = new Map<EventName, Set<(payload: never) => void | Promise<void>>>();\n\n  const onEvent: EventBusContext[\"on\"] = ((\n    eventName: EventName,\n    handler: (payload: never) => void | Promise<void>\n  ) => {\n    let set = eventHandlers.get(eventName);\n    if (!set) {\n      set = new Set();\n      eventHandlers.set(eventName, set);\n    }\n    set.add(handler);\n    return () => {\n      eventHandlers.get(eventName)?.delete(handler);\n    };\n  }) as EventBusContext[\"on\"];\n\n  const emitEvent: EventBusContext[\"emit\"] = async (\n    eventName: PluginEventName,\n    payload: Record<string, unknown>\n  ) => {\n    emittedEvents.push({ eventName, payload });\n    const handlers = eventHandlers.get(eventName);\n    if (handlers) {\n      for (const handler of handlers) {\n        await handler(payload as never);\n      }\n    }\n  };\n\n  const events: EventBusContext = { on: onEvent, emit: emitEvent };\n\n  // Build the fetch response queue\n  const fetchQueue: MockFetchResponse[] = Array.isArray(opts.fetchResponse)\n    ? [...opts.fetchResponse]\n    : opts.fetchResponse\n    ? [opts.fetchResponse]\n    : [];\n\n  const defaultFetchResponse: MockFetchResponse = { ok: true, status: 200, data: {} };\n\n  const mockFetch: typeof fetch = (input, init) => {\n    const url = typeof input === \"string\" ? input : input instanceof URL ? input.href : (input as Request).url;\n    fetchCalls.push({ url, options: init });\n\n    const response = fetchQueue.length > 0\n      ? (fetchQueue.shift() ?? defaultFetchResponse)\n      : defaultFetchResponse;\n\n    const body = response.text ?? JSON.stringify(response.data ?? {});\n    const status = response.status ?? (response.ok ? 200 : 400);\n\n    return Promise.resolve(\n      new Response(body, {\n        status,\n        headers: { \"Content-Type\": \"application/json\" },\n      })\n    ) as ReturnType<typeof fetch>;\n  };\n\n  const tenant: ContextTenant = {\n    id: opts.tenant?.id ?? \"test-tenant-id\",\n    slug: opts.tenant?.slug ?? \"test-blog\",\n    locale: opts.tenant?.locale ?? \"en-US\",\n  };\n\n  const settings: ContextSettings = {\n    blogName: opts.settings?.blogName ?? \"Test Blog\",\n    siteUrl: opts.settings?.siteUrl ?? \"https://test.velocms.org\",\n    theme: opts.settings?.theme ?? \"default\",\n    plan: opts.settings?.plan ?? \"pro\",\n  };\n\n  const ctx: MockHookContext = {\n    tenant,\n    settings,\n    fetch: mockFetch,\n    log: {\n      info: (message, data) => logs.push({ level: \"info\", message, data }),\n      warn: (message, data) => logs.push({ level: \"warn\", message, data }),\n      error: (message, data) => logs.push({ level: \"error\", message, data }),\n    },\n    kv: {\n      get: (key) => Promise.resolve(kvStore[key] ?? null),\n      set: (key, value) => {\n        kvStore[key] = value;\n        return Promise.resolve();\n      },\n      delete: (key) => {\n        delete kvStore[key];\n        return Promise.resolve();\n      },\n    },\n    events,\n    _fetchCalls: fetchCalls,\n    _logs: logs,\n    _kvStore: kvStore,\n    _emittedEvents: emittedEvents,\n    _dispatchSystemEvent: async (eventName, payload) => {\n      const handlers = eventHandlers.get(eventName);\n      if (handlers) {\n        for (const handler of handlers) {\n          await handler(payload as never);\n        }\n      }\n    },\n  };\n\n  return ctx;\n}\n\n/**\n * Reset a mock context's recorded calls, logs, and emitted events.\n * Useful for re-using a context across multiple test cases.\n *\n * Does NOT clear registered `ctx.events.on()` subscriptions — those persist\n * for the lifetime of the context, matching how a real plugin activation\n * (which typically registers subscriptions once) behaves.\n */\nexport function resetMockContext(ctx: MockHookContext): void {\n  ctx._fetchCalls.length = 0;\n  ctx._logs.length = 0;\n  ctx._emittedEvents.length = 0;\n}\n"],"mappings":"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","names":[]}

package/dist/test-helpers.d.cts

@@ -0,0 +1,110 @@
+import { u as PluginEventName, H as HookContext, S as SystemEventName, w as SystemEventPayloadMap, n as ContextTenant, m as ContextSettings } from './context-BCzNwlqR.cjs';
+
+/**
+ * VeloCMS Plugin SDK — Test Helpers
+ *
+ * Provides mock implementations of the host bridge contract so plugin authors
+ * can write unit tests without a running VeloCMS instance.
+ *
+ * @example
+ * ```typescript
+ * import { mockVelocms } from "@velocms/plugin-sdk/test-helpers";
+ *
+ * const ctx = mockVelocms({
+ *   tenant: { id: "t1", slug: "my-blog", locale: "en-US" },
+ *   fetchResponse: { ok: true, data: { result: "ok" } },
+ * });
+ *
+ * await myPlugin.handlePostPublish({ post: { slug: "hello" } }, ctx);
+ * expect(ctx._fetchCalls).toHaveLength(1);
+ * expect(ctx._fetchCalls[0].url).toBe("https://hooks.slack.com/...");
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface MockFetchResponse {
+    ok: boolean;
+    status?: number;
+    /** JSON body returned by the mock */
+    data?: unknown;
+    text?: string;
+}
+interface MockVelocmsOptions {
+    tenant?: Partial<ContextTenant>;
+    settings?: Partial<ContextSettings>;
+    /**
+     * Static response for all fetch() calls.
+     * Pass an array to return different responses for successive calls.
+     */
+    fetchResponse?: MockFetchResponse | MockFetchResponse[];
+    /**
+     * Pre-populated key-value store entries.
+     */
+    kvStore?: Record<string, string>;
+}
+interface MockFetchCall {
+    url: string;
+    options?: RequestInit;
+}
+/** A custom event recorded when the plugin under test calls `ctx.events.emit()`. */
+interface MockEmittedEvent {
+    eventName: PluginEventName;
+    payload: Record<string, unknown>;
+}
+interface MockHookContext extends HookContext {
+    /** All fetch() calls made during the test */
+    _fetchCalls: MockFetchCall[];
+    /** All log messages emitted during the test */
+    _logs: Array<{
+        level: "info" | "warn" | "error";
+        message: string;
+        data?: Record<string, unknown>;
+    }>;
+    /** Current key-value store state */
+    _kvStore: Record<string, string>;
+    /** All events emitted during the test via `ctx.events.emit()` */
+    _emittedEvents: MockEmittedEvent[];
+    /**
+     * Test-only helper: simulate VeloCMS core firing a system event, invoking
+     * every handler the plugin under test registered via `ctx.events.on(...)`.
+     *
+     * Not part of the real `HookContext` — the live event bus fires these
+     * automatically; in a unit test there's no running VeloCMS instance to
+     * fire them for you.
+     *
+     * @example
+     * ```typescript
+     * const ctx = mockVelocms();
+     * await myPlugin.onActivate(ctx); // registers ctx.events.on("post.published", ...)
+     * await ctx._dispatchSystemEvent("post.published", { post: { id: "1", title: "Hi" } });
+     * ```
+     */
+    _dispatchSystemEvent<E extends SystemEventName>(eventName: E, payload: SystemEventPayloadMap[E]): Promise<void>;
+}
+/**
+ * Create a mock `HookContext` for unit testing plugin hook handlers.
+ *
+ * The returned context is a fully-instrumented stand-in that:
+ * - Records all `ctx.fetch()` calls in `_fetchCalls`
+ * - Records all `ctx.log.*()` calls in `_logs`
+ * - Provides an in-memory `ctx.kv` store (seeded from `opts.kvStore`)
+ * - Returns controlled responses from `opts.fetchResponse`
+ *
+ * No network requests are made. No VeloCMS instance is required.
+ *
+ * @param opts - Optional overrides for tenant, settings, fetch responses, kv seed
+ * @returns    - Instrumented `MockHookContext` compatible with `HookContext`
+ */
+declare function mockVelocms(opts?: MockVelocmsOptions): MockHookContext;
+/**
+ * Reset a mock context's recorded calls, logs, and emitted events.
+ * Useful for re-using a context across multiple test cases.
+ *
+ * Does NOT clear registered `ctx.events.on()` subscriptions — those persist
+ * for the lifetime of the context, matching how a real plugin activation
+ * (which typically registers subscriptions once) behaves.
+ */
+declare function resetMockContext(ctx: MockHookContext): void;
+
+export { type MockEmittedEvent, type MockFetchCall, type MockFetchResponse, type MockHookContext, type MockVelocmsOptions, mockVelocms, resetMockContext };

package/dist/test-helpers.d.ts

@@ -0,0 +1,110 @@
+import { u as PluginEventName, H as HookContext, S as SystemEventName, w as SystemEventPayloadMap, n as ContextTenant, m as ContextSettings } from './context-BCzNwlqR.js';
+
+/**
+ * VeloCMS Plugin SDK — Test Helpers
+ *
+ * Provides mock implementations of the host bridge contract so plugin authors
+ * can write unit tests without a running VeloCMS instance.
+ *
+ * @example
+ * ```typescript
+ * import { mockVelocms } from "@velocms/plugin-sdk/test-helpers";
+ *
+ * const ctx = mockVelocms({
+ *   tenant: { id: "t1", slug: "my-blog", locale: "en-US" },
+ *   fetchResponse: { ok: true, data: { result: "ok" } },
+ * });
+ *
+ * await myPlugin.handlePostPublish({ post: { slug: "hello" } }, ctx);
+ * expect(ctx._fetchCalls).toHaveLength(1);
+ * expect(ctx._fetchCalls[0].url).toBe("https://hooks.slack.com/...");
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface MockFetchResponse {
+    ok: boolean;
+    status?: number;
+    /** JSON body returned by the mock */
+    data?: unknown;
+    text?: string;
+}
+interface MockVelocmsOptions {
+    tenant?: Partial<ContextTenant>;
+    settings?: Partial<ContextSettings>;
+    /**
+     * Static response for all fetch() calls.
+     * Pass an array to return different responses for successive calls.
+     */
+    fetchResponse?: MockFetchResponse | MockFetchResponse[];
+    /**
+     * Pre-populated key-value store entries.
+     */
+    kvStore?: Record<string, string>;
+}
+interface MockFetchCall {
+    url: string;
+    options?: RequestInit;
+}
+/** A custom event recorded when the plugin under test calls `ctx.events.emit()`. */
+interface MockEmittedEvent {
+    eventName: PluginEventName;
+    payload: Record<string, unknown>;
+}
+interface MockHookContext extends HookContext {
+    /** All fetch() calls made during the test */
+    _fetchCalls: MockFetchCall[];
+    /** All log messages emitted during the test */
+    _logs: Array<{
+        level: "info" | "warn" | "error";
+        message: string;
+        data?: Record<string, unknown>;
+    }>;
+    /** Current key-value store state */
+    _kvStore: Record<string, string>;
+    /** All events emitted during the test via `ctx.events.emit()` */
+    _emittedEvents: MockEmittedEvent[];
+    /**
+     * Test-only helper: simulate VeloCMS core firing a system event, invoking
+     * every handler the plugin under test registered via `ctx.events.on(...)`.
+     *
+     * Not part of the real `HookContext` — the live event bus fires these
+     * automatically; in a unit test there's no running VeloCMS instance to
+     * fire them for you.
+     *
+     * @example
+     * ```typescript
+     * const ctx = mockVelocms();
+     * await myPlugin.onActivate(ctx); // registers ctx.events.on("post.published", ...)
+     * await ctx._dispatchSystemEvent("post.published", { post: { id: "1", title: "Hi" } });
+     * ```
+     */
+    _dispatchSystemEvent<E extends SystemEventName>(eventName: E, payload: SystemEventPayloadMap[E]): Promise<void>;
+}
+/**
+ * Create a mock `HookContext` for unit testing plugin hook handlers.
+ *
+ * The returned context is a fully-instrumented stand-in that:
+ * - Records all `ctx.fetch()` calls in `_fetchCalls`
+ * - Records all `ctx.log.*()` calls in `_logs`
+ * - Provides an in-memory `ctx.kv` store (seeded from `opts.kvStore`)
+ * - Returns controlled responses from `opts.fetchResponse`
+ *
+ * No network requests are made. No VeloCMS instance is required.
+ *
+ * @param opts - Optional overrides for tenant, settings, fetch responses, kv seed
+ * @returns    - Instrumented `MockHookContext` compatible with `HookContext`
+ */
+declare function mockVelocms(opts?: MockVelocmsOptions): MockHookContext;
+/**
+ * Reset a mock context's recorded calls, logs, and emitted events.
+ * Useful for re-using a context across multiple test cases.
+ *
+ * Does NOT clear registered `ctx.events.on()` subscriptions — those persist
+ * for the lifetime of the context, matching how a real plugin activation
+ * (which typically registers subscriptions once) behaves.
+ */
+declare function resetMockContext(ctx: MockHookContext): void;
+
+export { type MockEmittedEvent, type MockFetchCall, type MockFetchResponse, type MockHookContext, type MockVelocmsOptions, mockVelocms, resetMockContext };

package/dist/test-helpers.js

@@ -0,0 +1,100 @@
+// src/test-helpers.ts
+function mockVelocms(opts = {}) {
+  const fetchCalls = [];
+  const logs = [];
+  const kvStore = { ...opts.kvStore ?? {} };
+  const emittedEvents = [];
+  const eventHandlers = /* @__PURE__ */ new Map();
+  const onEvent = ((eventName, handler) => {
+    let set = eventHandlers.get(eventName);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      eventHandlers.set(eventName, set);
+    }
+    set.add(handler);
+    return () => {
+      eventHandlers.get(eventName)?.delete(handler);
+    };
+  });
+  const emitEvent = async (eventName, payload) => {
+    emittedEvents.push({ eventName, payload });
+    const handlers = eventHandlers.get(eventName);
+    if (handlers) {
+      for (const handler of handlers) {
+        await handler(payload);
+      }
+    }
+  };
+  const events = { on: onEvent, emit: emitEvent };
+  const fetchQueue = Array.isArray(opts.fetchResponse) ? [...opts.fetchResponse] : opts.fetchResponse ? [opts.fetchResponse] : [];
+  const defaultFetchResponse = { ok: true, status: 200, data: {} };
+  const mockFetch = (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    fetchCalls.push({ url, options: init });
+    const response = fetchQueue.length > 0 ? fetchQueue.shift() ?? defaultFetchResponse : defaultFetchResponse;
+    const body = response.text ?? JSON.stringify(response.data ?? {});
+    const status = response.status ?? (response.ok ? 200 : 400);
+    return Promise.resolve(
+      new Response(body, {
+        status,
+        headers: { "Content-Type": "application/json" }
+      })
+    );
+  };
+  const tenant = {
+    id: opts.tenant?.id ?? "test-tenant-id",
+    slug: opts.tenant?.slug ?? "test-blog",
+    locale: opts.tenant?.locale ?? "en-US"
+  };
+  const settings = {
+    blogName: opts.settings?.blogName ?? "Test Blog",
+    siteUrl: opts.settings?.siteUrl ?? "https://test.velocms.org",
+    theme: opts.settings?.theme ?? "default",
+    plan: opts.settings?.plan ?? "pro"
+  };
+  const ctx = {
+    tenant,
+    settings,
+    fetch: mockFetch,
+    log: {
+      info: (message, data) => logs.push({ level: "info", message, data }),
+      warn: (message, data) => logs.push({ level: "warn", message, data }),
+      error: (message, data) => logs.push({ level: "error", message, data })
+    },
+    kv: {
+      get: (key) => Promise.resolve(kvStore[key] ?? null),
+      set: (key, value) => {
+        kvStore[key] = value;
+        return Promise.resolve();
+      },
+      delete: (key) => {
+        delete kvStore[key];
+        return Promise.resolve();
+      }
+    },
+    events,
+    _fetchCalls: fetchCalls,
+    _logs: logs,
+    _kvStore: kvStore,
+    _emittedEvents: emittedEvents,
+    _dispatchSystemEvent: async (eventName, payload) => {
+      const handlers = eventHandlers.get(eventName);
+      if (handlers) {
+        for (const handler of handlers) {
+          await handler(payload);
+        }
+      }
+    }
+  };
+  return ctx;
+}
+function resetMockContext(ctx) {
+  ctx._fetchCalls.length = 0;
+  ctx._logs.length = 0;
+  ctx._emittedEvents.length = 0;
+}
+export {
+  mockVelocms,
+  resetMockContext
+};
+//# sourceMappingURL=test-helpers.js.map

package/dist/test-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/test-helpers.ts"],"sourcesContent":["/**\n * VeloCMS Plugin SDK — Test Helpers\n *\n * Provides mock implementations of the host bridge contract so plugin authors\n * can write unit tests without a running VeloCMS instance.\n *\n * @example\n * ```typescript\n * import { mockVelocms } from \"@velocms/plugin-sdk/test-helpers\";\n *\n * const ctx = mockVelocms({\n *   tenant: { id: \"t1\", slug: \"my-blog\", locale: \"en-US\" },\n *   fetchResponse: { ok: true, data: { result: \"ok\" } },\n * });\n *\n * await myPlugin.handlePostPublish({ post: { slug: \"hello\" } }, ctx);\n * expect(ctx._fetchCalls).toHaveLength(1);\n * expect(ctx._fetchCalls[0].url).toBe(\"https://hooks.slack.com/...\");\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { HookContext, ContextTenant, ContextSettings } from \"./types/context\";\nimport type {\n  EventBusContext,\n  EventName,\n  SystemEventName,\n  PluginEventName,\n  SystemEventPayloadMap,\n} from \"./types/events\";\n\n// ---------------------------------------------------------------------------\n// Mock configuration types\n// ---------------------------------------------------------------------------\n\nexport interface MockFetchResponse {\n  ok: boolean;\n  status?: number;\n  /** JSON body returned by the mock */\n  data?: unknown;\n  text?: string;\n}\n\nexport interface MockVelocmsOptions {\n  tenant?: Partial<ContextTenant>;\n  settings?: Partial<ContextSettings>;\n  /**\n   * Static response for all fetch() calls.\n   * Pass an array to return different responses for successive calls.\n   */\n  fetchResponse?: MockFetchResponse | MockFetchResponse[];\n  /**\n   * Pre-populated key-value store entries.\n   */\n  kvStore?: Record<string, string>;\n}\n\n// ---------------------------------------------------------------------------\n// Instrumented context (extends HookContext with test introspection)\n// ---------------------------------------------------------------------------\n\nexport interface MockFetchCall {\n  url: string;\n  options?: RequestInit;\n}\n\n/** A custom event recorded when the plugin under test calls `ctx.events.emit()`. */\nexport interface MockEmittedEvent {\n  eventName: PluginEventName;\n  payload: Record<string, unknown>;\n}\n\nexport interface MockHookContext extends HookContext {\n  /** All fetch() calls made during the test */\n  _fetchCalls: MockFetchCall[];\n  /** All log messages emitted during the test */\n  _logs: Array<{ level: \"info\" | \"warn\" | \"error\"; message: string; data?: Record<string, unknown> }>;\n  /** Current key-value store state */\n  _kvStore: Record<string, string>;\n  /** All events emitted during the test via `ctx.events.emit()` */\n  _emittedEvents: MockEmittedEvent[];\n  /**\n   * Test-only helper: simulate VeloCMS core firing a system event, invoking\n   * every handler the plugin under test registered via `ctx.events.on(...)`.\n   *\n   * Not part of the real `HookContext` — the live event bus fires these\n   * automatically; in a unit test there's no running VeloCMS instance to\n   * fire them for you.\n   *\n   * @example\n   * ```typescript\n   * const ctx = mockVelocms();\n   * await myPlugin.onActivate(ctx); // registers ctx.events.on(\"post.published\", ...)\n   * await ctx._dispatchSystemEvent(\"post.published\", { post: { id: \"1\", title: \"Hi\" } });\n   * ```\n   */\n  _dispatchSystemEvent<E extends SystemEventName>(\n    eventName: E,\n    payload: SystemEventPayloadMap[E]\n  ): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a mock `HookContext` for unit testing plugin hook handlers.\n *\n * The returned context is a fully-instrumented stand-in that:\n * - Records all `ctx.fetch()` calls in `_fetchCalls`\n * - Records all `ctx.log.*()` calls in `_logs`\n * - Provides an in-memory `ctx.kv` store (seeded from `opts.kvStore`)\n * - Returns controlled responses from `opts.fetchResponse`\n *\n * No network requests are made. No VeloCMS instance is required.\n *\n * @param opts - Optional overrides for tenant, settings, fetch responses, kv seed\n * @returns    - Instrumented `MockHookContext` compatible with `HookContext`\n */\nexport function mockVelocms(opts: MockVelocmsOptions = {}): MockHookContext {\n  const fetchCalls: MockFetchCall[] = [];\n  const logs: MockHookContext[\"_logs\"] = [];\n  const kvStore: Record<string, string> = { ...(opts.kvStore ?? {}) };\n  const emittedEvents: MockEmittedEvent[] = [];\n\n  // In-memory pub/sub for ctx.events — mirrors the real EventBusContext\n  // shape without a running VeloCMS instance.\n  const eventHandlers = new Map<EventName, Set<(payload: never) => void | Promise<void>>>();\n\n  const onEvent: EventBusContext[\"on\"] = ((\n    eventName: EventName,\n    handler: (payload: never) => void | Promise<void>\n  ) => {\n    let set = eventHandlers.get(eventName);\n    if (!set) {\n      set = new Set();\n      eventHandlers.set(eventName, set);\n    }\n    set.add(handler);\n    return () => {\n      eventHandlers.get(eventName)?.delete(handler);\n    };\n  }) as EventBusContext[\"on\"];\n\n  const emitEvent: EventBusContext[\"emit\"] = async (\n    eventName: PluginEventName,\n    payload: Record<string, unknown>\n  ) => {\n    emittedEvents.push({ eventName, payload });\n    const handlers = eventHandlers.get(eventName);\n    if (handlers) {\n      for (const handler of handlers) {\n        await handler(payload as never);\n      }\n    }\n  };\n\n  const events: EventBusContext = { on: onEvent, emit: emitEvent };\n\n  // Build the fetch response queue\n  const fetchQueue: MockFetchResponse[] = Array.isArray(opts.fetchResponse)\n    ? [...opts.fetchResponse]\n    : opts.fetchResponse\n    ? [opts.fetchResponse]\n    : [];\n\n  const defaultFetchResponse: MockFetchResponse = { ok: true, status: 200, data: {} };\n\n  const mockFetch: typeof fetch = (input, init) => {\n    const url = typeof input === \"string\" ? input : input instanceof URL ? input.href : (input as Request).url;\n    fetchCalls.push({ url, options: init });\n\n    const response = fetchQueue.length > 0\n      ? (fetchQueue.shift() ?? defaultFetchResponse)\n      : defaultFetchResponse;\n\n    const body = response.text ?? JSON.stringify(response.data ?? {});\n    const status = response.status ?? (response.ok ? 200 : 400);\n\n    return Promise.resolve(\n      new Response(body, {\n        status,\n        headers: { \"Content-Type\": \"application/json\" },\n      })\n    ) as ReturnType<typeof fetch>;\n  };\n\n  const tenant: ContextTenant = {\n    id: opts.tenant?.id ?? \"test-tenant-id\",\n    slug: opts.tenant?.slug ?? \"test-blog\",\n    locale: opts.tenant?.locale ?? \"en-US\",\n  };\n\n  const settings: ContextSettings = {\n    blogName: opts.settings?.blogName ?? \"Test Blog\",\n    siteUrl: opts.settings?.siteUrl ?? \"https://test.velocms.org\",\n    theme: opts.settings?.theme ?? \"default\",\n    plan: opts.settings?.plan ?? \"pro\",\n  };\n\n  const ctx: MockHookContext = {\n    tenant,\n    settings,\n    fetch: mockFetch,\n    log: {\n      info: (message, data) => logs.push({ level: \"info\", message, data }),\n      warn: (message, data) => logs.push({ level: \"warn\", message, data }),\n      error: (message, data) => logs.push({ level: \"error\", message, data }),\n    },\n    kv: {\n      get: (key) => Promise.resolve(kvStore[key] ?? null),\n      set: (key, value) => {\n        kvStore[key] = value;\n        return Promise.resolve();\n      },\n      delete: (key) => {\n        delete kvStore[key];\n        return Promise.resolve();\n      },\n    },\n    events,\n    _fetchCalls: fetchCalls,\n    _logs: logs,\n    _kvStore: kvStore,\n    _emittedEvents: emittedEvents,\n    _dispatchSystemEvent: async (eventName, payload) => {\n      const handlers = eventHandlers.get(eventName);\n      if (handlers) {\n        for (const handler of handlers) {\n          await handler(payload as never);\n        }\n      }\n    },\n  };\n\n  return ctx;\n}\n\n/**\n * Reset a mock context's recorded calls, logs, and emitted events.\n * Useful for re-using a context across multiple test cases.\n *\n * Does NOT clear registered `ctx.events.on()` subscriptions — those persist\n * for the lifetime of the context, matching how a real plugin activation\n * (which typically registers subscriptions once) behaves.\n */\nexport function resetMockContext(ctx: MockHookContext): void {\n  ctx._fetchCalls.length = 0;\n  ctx._logs.length = 0;\n  ctx._emittedEvents.length = 0;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@velocms/plugin-sdk",
+  "version": "1.0.0-alpha.2",
+  "description": "Plugin SDK for VeloCMS — types, manifests, lifecycle hooks for first-party + community plugins",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./test-helpers": {
+      "types": "./dist/test-helpers.d.ts",
+      "import": "./dist/test-helpers.js",
+      "require": "./dist/test-helpers.cjs"
+    }
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "keywords": [
+    "velocms",
+    "cms",
+    "sdk",
+    "plugin-sdk",
+    "blog",
+    "nextjs",
+    "typescript",
+    "plugin",
+    "marketplace",
+    "hooks"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "VeloCMS",
+    "url": "https://velocms.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VeloCMS/plugin-sdk.git"
+  },
+  "homepage": "https://velocms.org/developers/sdk",
+  "bugs": {
+    "url": "https://github.com/VeloCMS/plugin-sdk/issues"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false
+}