@ensera/plugin-backend 1.0.0

package/README.md

@@ -0,0 +1,15 @@
+# @ensera/plugin-backend
+
+Backend runtime SDK for Ensera plugins.
+
+## Install
+
+```bash
+npm install @ensera/plugin-backend express
+```
+
+## Purpose
+
+- verifies Ensera runtime JWTs
+- provides instance-scoped backend helpers
+- stays separate from the scaffold template packages

package/dist/index.d.ts

@@ -0,0 +1,376 @@
+import { Request, Response, NextFunction } from 'express';
+
+/**
+ * Plugin scope extracted from JWT token
+ */
+type PluginScope = {
+    userId: string;
+    workspaceId: string;
+    spaceId: string;
+    instanceId: string;
+    featureSlug: string;
+    tabViewId?: string;
+    taskScopeId?: string;
+    roles?: string[];
+    perms?: string[];
+    tokenId?: string;
+    issuedAt?: number;
+    expiresAt?: number;
+    issuer?: string;
+    audience?: string;
+};
+/**
+ * Plugin authentication middleware options
+ */
+type PluginAuthOptions = {
+    /**
+     * Enforce that tokens must match a specific featureSlug.
+     * If mismatched -> 403 PLUGIN_FEATURE_MISMATCH
+     */
+    featureSlug?: string;
+    /**
+     * One or more secrets to verify HS256 tokens.
+     * Provide multiple for rotation: [new, old]
+     */
+    secrets: string[];
+    /**
+     * Validate iss/aud if provided.
+     */
+    issuer?: string;
+    audience?: string;
+    /**
+     * Clock tolerance in seconds (default 30)
+     */
+    clockToleranceSec?: number;
+    /**
+     * Allow token from this header instead of Authorization.
+     * Default: none
+     */
+    tokenHeader?: string;
+    /**
+     * DEV ONLY: When true and no Bearer token is present,
+     * injects a mock PluginScope instead of returning 401.
+     * NEVER enable in production.
+     */
+    devMode?: boolean;
+    /**
+     * DEV ONLY: Override default mock scope values.
+     * Only used when devMode is true.
+     */
+    devScope?: Partial<PluginScope>;
+};
+declare global {
+    namespace Express {
+        interface Request {
+            plugin?: PluginScope;
+        }
+    }
+}
+/**
+ * JSON-serializable value types
+ */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JsonObject = Record<string, JsonValue>;
+/**
+ * Notification System - Action attached to a notification
+ */
+interface NotificationAction {
+    label: string;
+    actionId: string;
+    payload?: JsonValue;
+}
+/**
+ * Notification System - Notification payload sent from backend
+ */
+interface BackendNotification {
+    userId: string;
+    type: string;
+    title: string;
+    message: string;
+    metadata?: JsonValue;
+    priority?: "low" | "normal" | "high" | "urgent";
+    link?: string;
+    actions?: NotificationAction[];
+}
+/**
+ * Notification System - Options for sending notifications
+ */
+interface NotificationOptions {
+    /** Skip if user has disabled notifications for this feature */
+    respectPreferences?: boolean;
+    /** Only send via specific channels */
+    channels?: Array<"email" | "push" | "inApp">;
+    /** Schedule for later */
+    scheduledAt?: Date | string;
+}
+/**
+ * Notification System - Response from Core API
+ */
+interface NotificationPublishResponse {
+    success: boolean;
+    id?: string;
+    sent?: boolean;
+    emailSent?: boolean;
+    pushSent?: boolean;
+    error?: string;
+    reason?: string;
+}
+/**
+ * Notification System - Bulk send response
+ */
+interface NotificationBulkResponse {
+    success: boolean;
+    count: number;
+    errors?: Array<{
+        index: number;
+        userId: string;
+        error: string;
+    }>;
+}
+/**
+ * Notification System - Cancel response
+ */
+interface NotificationCancelResponse {
+    success: boolean;
+    cancelled: number;
+    error?: string;
+}
+/**
+ * Notification System - Type configuration in package.json
+ */
+interface NotificationTypeConfig {
+    id: string;
+    label: string;
+    description?: string;
+    defaultEnabled?: boolean;
+}
+/**
+ * Notification System - Feature capabilities
+ */
+interface NotificationCapabilities {
+    enabled: boolean;
+    types: NotificationTypeConfig[];
+}
+/**
+ * Publisher configuration
+ */
+interface NotificationPublisherConfig {
+    /** Feature slug/ID */
+    featureSlug: string;
+    /** Core API base URL (e.g., "http://localhost:3000") */
+    coreApiUrl: string;
+    /** Service-to-service authentication token */
+    serviceToken: string;
+    /** Timeout in ms (default 5000) */
+    timeoutMs?: number;
+}
+/**
+ * Internal: Notification payload sent to Core API
+ */
+interface NotificationApiPayload extends BackendNotification {
+    appId: string;
+    options?: NotificationOptions;
+    timestamp: string;
+}
+/**
+ * Internal: Bulk notification payload
+ */
+interface NotificationBulkApiPayload {
+    notifications: NotificationApiPayload[];
+}
+
+type PluginErrorResponse = {
+    message: string;
+    code: string;
+    requestId?: string;
+};
+declare class PluginError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(args: {
+        status: number;
+        message: string;
+        code: string;
+        requestId?: string;
+    });
+    toJSON(): PluginErrorResponse;
+}
+
+declare function pluginAuth(options: PluginAuthOptions): (req: Request, _res: Response, next: NextFunction) => void;
+
+declare function assertPluginScope(req: Request): PluginScope;
+declare function getPluginScope(req: Request): PluginScope | undefined;
+declare function requireFeature(featureSlug: string): (req: Request, _res: Response, next: NextFunction) => void;
+declare function requirePermission(perm: string): (req: Request, _res: Response, next: NextFunction) => void;
+declare function requireTaskScope(): (req: Request, _res: Response, next: NextFunction) => void;
+declare function requireTabView(): (req: Request, _res: Response, next: NextFunction) => void;
+
+declare function pluginErrorHandler(): (err: unknown, req: Request, res: Response, _next: NextFunction) => void;
+
+type InstanceOnlyHandler = (instanceId: string, req: Omit<Request, "plugin">, res: Response, next: NextFunction) => unknown | Promise<unknown>;
+/**
+ * Resolves the effective instance ID from the plugin scope.
+ *
+ * Priority:
+ *   1. scope.taskScopeId  — present when inside a synced Tab View
+ *   2. scope.instanceId   — normal standalone instance
+ */
+declare function resolveEffectiveInstanceId(scope: {
+    taskScopeId?: string;
+    instanceId: string;
+}): string;
+declare function withInstanceOnly(handler: InstanceOnlyHandler): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+type Options = {
+    keys?: string[];
+    locations?: ("body" | "query" | "params")[];
+};
+declare function forbidClientInstanceId(options?: Options): (req: Request, _res: Response, next: NextFunction) => void;
+
+/**
+ * Create a notification publisher for feature backend
+ *
+ * @example
+ * ```typescript
+ * const notifier = createNotificationPublisher({
+ *   featureSlug: "task-manager",
+ *   coreApiUrl: process.env.CORE_API_URL,
+ *   serviceToken: process.env.SERVICE_TOKEN,
+ * });
+ *
+ * await notifier.publish({
+ *   userId: "user-123",
+ *   type: "task.assigned",
+ *   title: "New Task Assigned",
+ *   message: "You were assigned to: Fix login bug",
+ *   link: "/tasks/456",
+ * });
+ * ```
+ */
+declare function createNotificationPublisher(config: NotificationPublisherConfig): {
+    publish: (notification: BackendNotification, options?: NotificationOptions) => Promise<NotificationPublishResponse>;
+    publishBulk: (notifications: BackendNotification[], options?: NotificationOptions) => Promise<NotificationBulkResponse>;
+    publishToUsers: (userIds: string[], notification: Omit<BackendNotification, "userId">, options?: NotificationOptions) => Promise<NotificationBulkResponse>;
+    schedule: (notification: BackendNotification, scheduledAt: Date | string, options?: Omit<NotificationOptions, "scheduledAt">) => Promise<NotificationPublishResponse>;
+    cancel: (metadata: Record<string, any>) => Promise<NotificationCancelResponse>;
+};
+type NotificationPublisher = ReturnType<typeof createNotificationPublisher>;
+
+/**
+ * Plugin context with both userId and instanceId
+ */
+interface PluginContext {
+    instanceId: string;
+    userId: string;
+    workspaceId?: string;
+}
+/**
+ * Request with plugin context
+ */
+interface RequestWithContext extends Request {
+    pluginContext?: PluginContext;
+}
+/**
+ * Handler that receives both instanceId and userId
+ */
+type UserAndInstanceHandler = (context: PluginContext, req: Omit<Request, "plugin">, res: Response, next: NextFunction) => unknown | Promise<unknown>;
+/**
+ * Middleware that extracts BOTH userId and instanceId from plugin scope
+ *
+ * Similar to withInstanceOnly but also captures userId before hiding req.plugin
+ */
+declare function withUserAndInstance(handler: UserAndInstanceHandler): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+/**
+ * Handler that receives the effective instanceId AND full scope
+ */
+type InstanceScopeHandler = (instanceId: string, scope: PluginScope, req: Omit<Request, "plugin">, res: Response, next: NextFunction) => unknown | Promise<unknown>;
+declare function withInstanceScope(handler: InstanceScopeHandler): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+/**
+ * Date and time utilities for notification scheduling
+ */
+interface ScheduleOptions {
+    /** Date as string or Date object */
+    date: string | Date;
+    /** Time in HH:mm or HH:mm:ss format */
+    time?: string | null;
+    /** Minutes to subtract from the calculated time (for reminders) */
+    minutesBefore?: number;
+    /** Default hour if no time provided (0-23) */
+    defaultHour?: number;
+    /** Default minute if no time provided (0-59) */
+    defaultMinute?: number;
+}
+/**
+ * Calculate a scheduled time from date, time, and offset
+ *
+ * @param options - Schedule options
+ * @returns Date object or null if invalid/past
+ *
+ * @example
+ * ```typescript
+ * // Schedule for specific date and time
+ * const scheduleTime = calculateScheduleTime({
+ *   date: "2026-03-15",
+ *   time: "14:30",
+ * });
+ *
+ * // Schedule 30 minutes before due time
+ * const reminderTime = calculateScheduleTime({
+ *   date: task.dueDate,
+ *   time: task.dueTime,
+ *   minutesBefore: 30,
+ * });
+ * ```
+ */
+declare function calculateScheduleTime(options: ScheduleOptions): Date | null;
+/**
+ * Format 24-hour time string to 12-hour AM/PM format
+ *
+ * @param time - Time string in HH:mm or HH:mm:ss format
+ * @returns Formatted time string or empty string if invalid
+ *
+ * @example
+ * ```typescript
+ * formatTime("14:30"); // "2:30 PM"
+ * formatTime("09:00"); // "9:00 AM"
+ * formatTime("00:30"); // "12:30 AM"
+ * ```
+ */
+declare function formatTime(time: string | null | undefined): string;
+/**
+ * Check if a date is in the past
+ *
+ * @param date - Date as string or Date object
+ * @returns true if the date is in the past
+ */
+declare function isPastDate(date: Date | string): boolean;
+/**
+ * Normalize date to YYYY-MM-DD string format
+ *
+ * @param date - Date as string or Date object
+ * @returns Date string in YYYY-MM-DD format or null if invalid
+ *
+ * @example
+ * ```typescript
+ * toDateString(new Date("2026-03-15")); // "2026-03-15"
+ * toDateString("2026-03-15T14:30:00"); // "2026-03-15"
+ * ```
+ */
+declare function toDateString(date: string | Date | null | undefined): string | null;
+/**
+ * Build a complete DateTime from separate date and time values
+ *
+ * @param dateValue - Date as string or Date object
+ * @param timeValue - Time in HH:mm or HH:mm:ss format
+ * @param defaultHour - Default hour if no time provided
+ * @param defaultMinute - Default minute if no time provided
+ * @returns Date object or null if invalid
+ */
+declare function buildDateTime(dateValue: string | Date | null | undefined, timeValue: string | null | undefined, defaultHour?: number, defaultMinute?: number): Date | null;
+
+export { type BackendNotification, type JsonObject, type JsonValue, type NotificationAction, type NotificationApiPayload, type NotificationBulkApiPayload, type NotificationBulkResponse, type NotificationCancelResponse, type NotificationCapabilities, type NotificationOptions, type NotificationPublishResponse, type NotificationPublisher, type NotificationPublisherConfig, type NotificationTypeConfig, type PluginAuthOptions, type PluginContext, PluginError, type PluginErrorResponse, type PluginScope, type RequestWithContext, type ScheduleOptions, assertPluginScope, buildDateTime, calculateScheduleTime, createNotificationPublisher, forbidClientInstanceId, formatTime, getPluginScope, isPastDate, pluginAuth, pluginErrorHandler, requireFeature, requirePermission, requireTabView, requireTaskScope, resolveEffectiveInstanceId, toDateString, withInstanceOnly, withInstanceScope, withUserAndInstance };

package/dist/index.js

@@ -0,0 +1,681 @@
+// src/errors.ts
+var PluginError = class extends Error {
+  status;
+  code;
+  requestId;
+  constructor(args) {
+    super(args.message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "PluginError";
+    this.status = args.status;
+    this.code = args.code;
+    this.requestId = args.requestId;
+  }
+  toJSON() {
+    return { message: this.message, code: this.code, requestId: this.requestId };
+  }
+};
+
+// src/auth.ts
+import jwt from "jsonwebtoken";
+function readBearerToken(req, tokenHeader) {
+  if (tokenHeader) {
+    const v = req.header(tokenHeader);
+    if (v && v.trim()) return v.trim();
+  }
+  const auth = req.header("authorization") ?? req.header("Authorization");
+  if (!auth) return null;
+  const m = auth.match(/^Bearer\s+(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+function pickClaim(obj, key) {
+  const v = obj?.[key];
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function normalizeScope(payload) {
+  const userId = pickClaim(payload, "sub");
+  const workspaceId = pickClaim(payload, "workspaceId");
+  const spaceId = pickClaim(payload, "spaceId");
+  const instanceId = pickClaim(payload, "instanceId");
+  const featureSlug = pickClaim(payload, "featureSlug");
+  const tabViewId = pickClaim(payload, "tabViewId");
+  const taskScopeId = pickClaim(payload, "taskScopeId");
+  if (!userId || !workspaceId || !spaceId || !instanceId || !featureSlug) {
+    throw new PluginError({
+      status: 401,
+      message: "Invalid or expired plugin token",
+      code: "PLUGIN_AUTH_FAILED"
+    });
+  }
+  return {
+    userId,
+    workspaceId,
+    spaceId,
+    instanceId,
+    featureSlug,
+    tabViewId,
+    taskScopeId,
+    roles: Array.isArray(payload.roles) ? payload.roles : void 0,
+    perms: Array.isArray(payload.perms) ? payload.perms : void 0,
+    tokenId: pickClaim(payload, "jti"),
+    issuedAt: typeof payload.iat === "number" ? payload.iat : void 0,
+    expiresAt: typeof payload.exp === "number" ? payload.exp : void 0,
+    issuer: pickClaim(payload, "iss"),
+    audience: pickClaim(payload, "aud")
+  };
+}
+function pluginAuth(options) {
+  if (!options.devMode && !options?.secrets?.length) {
+    throw new Error(
+      "pluginAuth: options.secrets is required (provide at least 1 secret)"
+    );
+  }
+  if (options.devMode) {
+    console.warn(
+      "[plugin-backend] WARNING: devMode is ON \u2014 auth will be bypassed for tokenless requests. Do not use in production."
+    );
+  }
+  const clockToleranceSec = options.clockToleranceSec ?? 30;
+  return function pluginAuthMiddleware(req, _res, next) {
+    const requestId = req.header("x-request-id") ?? void 0;
+    if (requestId) _res.setHeader("x-request-id", requestId);
+    try {
+      const token = readBearerToken(req, options.tokenHeader);
+      if (!token && options.devMode) {
+        req.plugin = {
+          userId: "dev-user",
+          workspaceId: "dev-workspace",
+          spaceId: "dev-space",
+          instanceId: "dev-instance",
+          featureSlug: options.featureSlug ?? "unknown",
+          ...options.devScope
+        };
+        return next();
+      }
+      if (!token) {
+        throw new PluginError({
+          status: 401,
+          message: "Invalid or expired plugin token",
+          code: "PLUGIN_AUTH_FAILED",
+          requestId
+        });
+      }
+      let lastErr = null;
+      let decoded = null;
+      for (const secret of options.secrets) {
+        try {
+          if (token.length > 1e4) throw "auth failed";
+          decoded = jwt.verify(token, secret, {
+            algorithms: ["HS256"],
+            issuer: options.issuer,
+            audience: options.audience,
+            clockTolerance: clockToleranceSec
+          });
+          lastErr = null;
+          break;
+        } catch (e) {
+          lastErr = e;
+        }
+      }
+      if (!decoded || typeof decoded !== "object") {
+        throw new PluginError({
+          status: 401,
+          message: "Invalid or expired plugin token",
+          code: "PLUGIN_AUTH_FAILED",
+          requestId
+        });
+      }
+      const scope = normalizeScope(decoded);
+      if (options.featureSlug && scope.featureSlug !== options.featureSlug) {
+        throw new PluginError({
+          status: 403,
+          message: "Token featureSlug mismatch",
+          code: "PLUGIN_FEATURE_MISMATCH",
+          requestId
+        });
+      }
+      req.plugin = scope;
+      return next();
+    } catch (err) {
+      return next(err);
+    }
+  };
+}
+
+// src/guards.ts
+function assertPluginScope(req) {
+  if (!req.plugin) {
+    throw new PluginError({
+      status: 500,
+      message: "Plugin scope missing on request (did you forget app.use(pluginAuth())?)",
+      code: "PLUGIN_SCOPE_MISSING"
+    });
+  }
+  return req.plugin;
+}
+function getPluginScope(req) {
+  return req.plugin;
+}
+function requireFeature(featureSlug) {
+  return (req, _res, next) => {
+    try {
+      const p = assertPluginScope(req);
+      if (p.featureSlug !== featureSlug) {
+        throw new PluginError({
+          status: 403,
+          message: "Forbidden for this plugin",
+          code: "FORBIDDEN"
+        });
+      }
+      next();
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+function requirePermission(perm) {
+  return (req, _res, next) => {
+    try {
+      const p = assertPluginScope(req);
+      if (!p.perms?.includes(perm)) {
+        throw new PluginError({
+          status: 403,
+          message: "Missing permission",
+          code: "FORBIDDEN"
+        });
+      }
+      next();
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+function requireTaskScope() {
+  return (req, _res, next) => {
+    try {
+      const p = assertPluginScope(req);
+      if (!p.taskScopeId) {
+        throw new PluginError({
+          status: 400,
+          message: "taskScopeId missing. This endpoint requires a task-scoped context (open inside a synced tab or use a default task scope).",
+          code: "TASK_SCOPE_MISSING"
+        });
+      }
+      next();
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+function requireTabView() {
+  return (req, _res, next) => {
+    try {
+      const p = assertPluginScope(req);
+      if (!p.tabViewId) {
+        throw new PluginError({
+          status: 400,
+          message: "tabViewId missing. This endpoint requires a tab context.",
+          code: "TAB_VIEW_MISSING"
+        });
+      }
+      next();
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+
+// src/errorHandler.ts
+function pluginErrorHandler() {
+  return (err, req, res, _next) => {
+    const requestId = req.header("x-request-id") ?? void 0;
+    if (err instanceof PluginError) {
+      res.status(err.status).json(err.toJSON());
+      return;
+    }
+    if (process.env.NODE_ENV !== "production") {
+      console.error("[plugin-backend] unhandled error", { requestId, err });
+    }
+    res.status(500).json({
+      message: "Internal server error",
+      code: "INTERNAL_ERROR",
+      requestId
+    });
+  };
+}
+
+// src/withInstance.ts
+function resolveEffectiveInstanceId(scope) {
+  const effective = scope.taskScopeId?.trim() || scope.instanceId;
+  if (!effective || !effective.trim()) {
+    throw new PluginError({
+      status: 500,
+      code: "INSTANCE_SCOPE_MISSING",
+      message: "Instance scope missing. All plugin backend routes must be instance-scoped."
+    });
+  }
+  return effective;
+}
+function withInstanceOnly(handler) {
+  return async function instanceOnlyWrapped(req, res, next) {
+    try {
+      const scope = assertPluginScope(req);
+      const instanceId = resolveEffectiveInstanceId(scope);
+      const safeReq = req;
+      safeReq.plugin = void 0;
+      await handler(instanceId, safeReq, res, next);
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+
+// src/forbidClientInstanceId.ts
+function forbidClientInstanceId(options = {}) {
+  const keys = options.keys ?? ["instanceId", "instance_id"];
+  const locations = options.locations ?? ["body", "query", "params"];
+  return (req, _res, next) => {
+    const targets = [];
+    if (locations.includes("body")) targets.push(req.body);
+    if (locations.includes("query")) targets.push(req.query);
+    if (locations.includes("params")) targets.push(req.params);
+    for (const t of targets) {
+      if (!t || typeof t !== "object") continue;
+      for (const k of keys) {
+        if (k in t) {
+          return next(
+            new PluginError({
+              status: 400,
+              code: "INSTANCE_ID_NOT_ALLOWED",
+              message: "Do not send instanceId from the client. Instance scope is derived from the runtime token."
+            })
+          );
+        }
+      }
+    }
+    next();
+  };
+}
+
+// src/notify.ts
+function createNotificationPublisher(config) {
+  const { featureSlug, coreApiUrl, serviceToken, timeoutMs = 5e3 } = config;
+  if (!featureSlug?.trim()) {
+    throw new Error("NotificationPublisher: featureSlug is required");
+  }
+  if (!coreApiUrl?.trim()) {
+    throw new Error("NotificationPublisher: coreApiUrl is required");
+  }
+  if (!serviceToken?.trim()) {
+    throw new Error("NotificationPublisher: serviceToken is required");
+  }
+  const baseUrl = coreApiUrl.replace(/\/+$/, "");
+  async function fetchWithTimeout(url, options) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal
+      });
+      clearTimeout(timeout);
+      return response;
+    } catch (error) {
+      clearTimeout(timeout);
+      if (error.name === "AbortError") {
+        throw new Error(`Request timeout after ${timeoutMs}ms`);
+      }
+      throw error;
+    }
+  }
+  async function publish(notification, options) {
+    const url = `${baseUrl}/api/notifications/publish`;
+    const processedOptions = options ? {
+      ...options,
+      scheduledAt: options.scheduledAt instanceof Date ? options.scheduledAt.toISOString() : options.scheduledAt
+    } : void 0;
+    const payload = {
+      ...notification,
+      featureSlug,
+      options: processedOptions
+    };
+    console.log("[NotificationPublisher] Publishing notification:", {
+      featureSlug,
+      userId: notification.userId,
+      type: notification.type,
+      scheduledAt: processedOptions?.scheduledAt,
+      hasScheduledAt: !!processedOptions?.scheduledAt
+    });
+    try {
+      const response = await fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${serviceToken}`,
+          "X-Feature-Slug": featureSlug
+        },
+        body: JSON.stringify(payload)
+      });
+      const data = await response.json();
+      console.log("[NotificationPublisher] Response:", {
+        ok: response.ok,
+        status: response.status,
+        success: data.success,
+        scheduled: data.scheduled,
+        scheduledFor: data.scheduledFor,
+        error: data.error
+      });
+      if (!response.ok) {
+        return {
+          success: false,
+          error: data.error || `HTTP ${response.status}`
+        };
+      }
+      return data;
+    } catch (error) {
+      console.error("[NotificationPublisher] Error:", error);
+      return {
+        success: false,
+        error: error.message || "Failed to publish notification"
+      };
+    }
+  }
+  async function publishBulk(notifications, options) {
+    const url = `${baseUrl}/api/notifications/bulk`;
+    const payload = {
+      notifications,
+      featureSlug,
+      options
+    };
+    try {
+      const response = await fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${serviceToken}`,
+          "X-Feature-Slug": featureSlug
+        },
+        body: JSON.stringify(payload)
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        return {
+          success: false,
+          count: 0,
+          errors: [
+            {
+              index: 0,
+              userId: "",
+              error: data.error || `HTTP ${response.status}`
+            }
+          ]
+        };
+      }
+      return data;
+    } catch (error) {
+      return {
+        success: false,
+        count: 0,
+        errors: [{ index: 0, userId: "", error: error.message }]
+      };
+    }
+  }
+  async function publishToUsers(userIds, notification, options) {
+    const notifications = userIds.map((userId) => ({
+      ...notification,
+      userId
+    }));
+    return publishBulk(notifications, options);
+  }
+  async function schedule(notification, scheduledAt, options) {
+    return publish(notification, {
+      ...options,
+      scheduledAt
+    });
+  }
+  async function cancel(metadata) {
+    const url = `${baseUrl}/api/notifications/cancel-scheduled`;
+    const payload = {
+      featureSlug,
+      metadata
+    };
+    console.log("[NotificationPublisher] Cancelling notifications:", {
+      featureSlug,
+      metadata
+    });
+    try {
+      const response = await fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${serviceToken}`,
+          "X-Feature-Slug": featureSlug
+        },
+        body: JSON.stringify(payload)
+      });
+      const data = await response.json();
+      console.log("[NotificationPublisher] Cancel response:", {
+        ok: response.ok,
+        status: response.status,
+        success: data.success,
+        cancelled: data.cancelled,
+        error: data.error
+      });
+      if (!response.ok) {
+        return {
+          success: false,
+          cancelled: 0,
+          error: data.error || `HTTP ${response.status}`
+        };
+      }
+      return {
+        success: true,
+        cancelled: data.cancelled || 0
+      };
+    } catch (error) {
+      console.error("[NotificationPublisher] Cancel error:", error);
+      return {
+        success: false,
+        cancelled: 0,
+        error: error.message || "Failed to cancel notifications"
+      };
+    }
+  }
+  return {
+    publish,
+    publishBulk,
+    publishToUsers,
+    schedule,
+    cancel
+  };
+}
+
+// src/withUserAndInstance.ts
+function withUserAndInstance(handler) {
+  return async function userAndInstanceWrapped(req, res, next) {
+    try {
+      const scope = req.plugin;
+      if (!scope) {
+        throw new PluginError({
+          status: 500,
+          code: "PLUGIN_SCOPE_MISSING",
+          message: "Plugin scope missing. Ensure pluginAuth middleware runs first."
+        });
+      }
+      const instanceId = scope.instanceId;
+      const userId = scope.userId;
+      if (!instanceId) {
+        throw new PluginError({
+          status: 500,
+          code: "INSTANCE_SCOPE_MISSING",
+          message: "Instance scope missing. All plugin routes must be instance-scoped."
+        });
+      }
+      if (!userId) {
+        throw new PluginError({
+          status: 400,
+          code: "USER_ID_MISSING",
+          message: "User ID missing from plugin scope."
+        });
+      }
+      const context = {
+        instanceId,
+        userId,
+        workspaceId: scope.workspaceId
+      };
+      const safeReq = req;
+      safeReq.plugin = void 0;
+      await handler(context, safeReq, res, next);
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+
+// src/withInstanceScope.ts
+function withInstanceScope(handler) {
+  return async function instanceScopeWrapped(req, res, next) {
+    try {
+      const scope = assertPluginScope(req);
+      const instanceId = resolveEffectiveInstanceId(scope);
+      const safeReq = req;
+      safeReq.plugin = void 0;
+      await handler(instanceId, scope, safeReq, res, next);
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+
+// src/dateUtils.ts
+function calculateScheduleTime(options) {
+  const {
+    date,
+    time,
+    minutesBefore = 0,
+    defaultHour = 9,
+    defaultMinute = 0
+  } = options;
+  let baseDate;
+  if (date instanceof Date) {
+    if (isNaN(date.getTime())) return null;
+    baseDate = new Date(date);
+  } else if (typeof date === "string") {
+    const parsed = new Date(date);
+    if (isNaN(parsed.getTime())) return null;
+    baseDate = parsed;
+  } else {
+    return null;
+  }
+  if (time && typeof time === "string") {
+    const timeParts = time.split(":");
+    const hours = parseInt(timeParts[0], 10);
+    const minutes = parseInt(timeParts[1], 10);
+    const seconds = parseInt(timeParts[2], 10) || 0;
+    if (!isNaN(hours) && !isNaN(minutes)) {
+      baseDate.setHours(hours, minutes, seconds, 0);
+    } else {
+      baseDate.setHours(defaultHour, defaultMinute, 0, 0);
+    }
+  } else {
+    baseDate.setHours(defaultHour, defaultMinute, 0, 0);
+  }
+  if (minutesBefore > 0) {
+    baseDate.setMinutes(baseDate.getMinutes() - minutesBefore);
+  }
+  if (baseDate <= /* @__PURE__ */ new Date()) {
+    return null;
+  }
+  return baseDate;
+}
+function formatTime(time) {
+  if (!time) return "";
+  const parts = time.split(":");
+  if (parts.length < 2) return "";
+  const h = parseInt(parts[0], 10);
+  const minutes = parts[1];
+  if (isNaN(h)) return "";
+  const ampm = h >= 12 ? "PM" : "AM";
+  const hour12 = h % 12 || 12;
+  return `${hour12}:${minutes} ${ampm}`;
+}
+function isPastDate(date) {
+  const dateObj = date instanceof Date ? date : new Date(date);
+  if (isNaN(dateObj.getTime())) return false;
+  return dateObj <= /* @__PURE__ */ new Date();
+}
+function toDateString(date) {
+  if (!date) return null;
+  if (date instanceof Date) {
+    if (isNaN(date.getTime())) return null;
+    const yyyy = date.getFullYear();
+    const mm = String(date.getMonth() + 1).padStart(2, "0");
+    const dd = String(date.getDate()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}`;
+  }
+  if (typeof date === "string") {
+    const trimmed = date.trim();
+    if (!trimmed) return null;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) return trimmed;
+    const d = new Date(trimmed);
+    if (!isNaN(d.getTime())) {
+      const yyyy = d.getFullYear();
+      const mm = String(d.getMonth() + 1).padStart(2, "0");
+      const dd = String(d.getDate()).padStart(2, "0");
+      return `${yyyy}-${mm}-${dd}`;
+    }
+  }
+  return null;
+}
+function buildDateTime(dateValue, timeValue, defaultHour = 9, defaultMinute = 0) {
+  if (!dateValue) return null;
+  let result;
+  if (dateValue instanceof Date) {
+    if (isNaN(dateValue.getTime())) return null;
+    result = new Date(dateValue);
+  } else if (typeof dateValue === "string") {
+    const dateStr = toDateString(dateValue);
+    if (!dateStr) return null;
+    const [year, month, day] = dateStr.split("-").map(Number);
+    result = new Date(year, month - 1, day);
+  } else {
+    return null;
+  }
+  if (timeValue && typeof timeValue === "string") {
+    const timeParts = timeValue.split(":");
+    const hours = parseInt(timeParts[0], 10);
+    const minutes = parseInt(timeParts[1], 10);
+    const seconds = parseInt(timeParts[2], 10) || 0;
+    if (!isNaN(hours) && !isNaN(minutes)) {
+      result.setHours(hours, minutes, seconds, 0);
+    } else {
+      result.setHours(defaultHour, defaultMinute, 0, 0);
+    }
+  } else {
+    result.setHours(defaultHour, defaultMinute, 0, 0);
+  }
+  if (isNaN(result.getTime())) return null;
+  return result;
+}
+export {
+  PluginError,
+  assertPluginScope,
+  buildDateTime,
+  calculateScheduleTime,
+  createNotificationPublisher,
+  forbidClientInstanceId,
+  formatTime,
+  getPluginScope,
+  isPastDate,
+  pluginAuth,
+  pluginErrorHandler,
+  requireFeature,
+  requirePermission,
+  requireTabView,
+  requireTaskScope,
+  resolveEffectiveInstanceId,
+  toDateString,
+  withInstanceOnly,
+  withInstanceScope,
+  withUserAndInstance
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ensera/plugin-backend",
+  "version": "1.0.0",
+  "description": "Runtime backend SDK for Ensera plugins.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --target es2022 --outDir dist",
+    "dev": "tsup src/index.ts --format esm --dts --watch --target es2022 --outDir dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "keywords": [
+    "ensera",
+    "backend",
+    "sdk",
+    "plugin",
+    "express"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/jsonwebtoken": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "jsonwebtoken": "^9.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0",
+    "jsonwebtoken": "^9.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}