@ensera/plugin-backend 1.1.0 → 1.2.1

package/dist/index.d.ts

@@ -1,5 +1,51 @@
 import { Request, Response, NextFunction, Express } from 'express';
 
+type CoarseCapabilities = {
+    /** Can invite / remove workspace members. OWNER/ADMIN only. */
+    canInviteMembers: boolean;
+    /** Can create, rename, delete, or reorder spaces. OWNER/ADMIN only. */
+    canManageSpaces: boolean;
+    /** Can install or uninstall workspace-level features. OWNER/ADMIN only. */
+    canInstallWorkspaceFeatures: boolean;
+    /** Can create feature instances inside spaces. OWNER/ADMIN only. */
+    canCreateFeatureInstances: boolean;
+    /**
+     * Can create new content items (tasks, cards, rows, etc.) inside a feature.
+     * False for MEMBER role — they may edit assigned content but cannot create.
+     * True for OWNER/ADMIN and for non-MEMBER actors with EDIT+ permission.
+     */
+    canCreateContent: boolean;
+    /**
+     * Can delete any content item regardless of ownership.
+     * True for OWNER/ADMIN or actors with FULL feature permission.
+     */
+    canDeleteAnyContent: boolean;
+    /**
+     * Can delete content items the actor personally created.
+     * False for MEMBER role. True for non-MEMBER actors with EDIT+ permission.
+     */
+    canDeleteOwnContent: boolean;
+    /**
+     * Can assign content items (tasks, cards) to other workspace members.
+     * OWNER/ADMIN only.
+     */
+    canAssignContent: boolean;
+    /**
+     * Can manage structural elements (columns, sections, board layout).
+     * OWNER/ADMIN or actors with FULL feature permission.
+     */
+    canManageContentStructure: boolean;
+};
+type CoarseAuthorization = {
+    workspaceRole: "OWNER" | "ADMIN" | "MEMBER" | "GUEST" | null;
+    /** Effective space-level permission (FULL|EDIT|COMMENT|VIEW|NO_ACCESS). */
+    spacePermission: string;
+    /** Effective feature-level permission (FULL|EDIT|COMMENT|VIEW|NO_ACCESS). */
+    featurePermission: string;
+    accessSource: "workspace" | "space" | "feature" | "none";
+    capabilities: CoarseCapabilities;
+    policyVersion: "v2";
+};
 /**
  * Plugin scope extracted from JWT token
  */
@@ -11,6 +57,11 @@ type PluginScope = {
     featureSlug: string;
     tabViewId?: string;
     taskScopeId?: string;
+    /**
+     * Coarse authorization resolved by core at token-mint time.
+     * Use this for permission checks in route handlers and command handlers.
+     */
+    authorization?: CoarseAuthorization;
     roles?: string[];
     perms?: string[];
     tokenId?: string;
@@ -86,9 +137,12 @@ interface NotificationAction {
  */
 interface BackendNotification {
     userId: string;
+    actorId?: string | null;
     type: string;
     title: string;
     message: string;
+    entityType?: string;
+    entityId?: string;
     metadata?: JsonValue;
     priority?: "low" | "normal" | "high" | "urgent";
     link?: string;
@@ -114,6 +168,12 @@ interface NotificationPublishResponse {
     sent?: boolean;
     emailSent?: boolean;
     pushSent?: boolean;
+    scheduled?: boolean;
+    scheduledFor?: string;
+    warnings?: string[];
+    errorCode?: string;
+    hint?: string;
+    nextSteps?: string[];
     error?: string;
     reason?: string;
 }
@@ -135,6 +195,9 @@ interface NotificationBulkResponse {
 interface NotificationCancelResponse {
     success: boolean;
     cancelled: number;
+    errorCode?: string;
+    hint?: string;
+    nextSteps?: string[];
     error?: string;
 }
 /**
@@ -163,6 +226,8 @@ interface NotificationPublisherConfig {
     coreApiUrl: string;
     /** Service-to-service authentication token */
     serviceToken: string;
+    /** Developer Notification Token for Core-side notification authorization */
+    notificationToken?: string;
     /** Timeout in ms (default 5000) */
     timeoutMs?: number;
 }
@@ -381,6 +446,29 @@ type CoreRequestContext = {
     userId: string;
     taskScopeId?: string;
     requestId: string;
+    /**
+     * Structured coarse authorization resolved by core for this feature instance.
+     * Prefer this over the flat legacy fields below for new code.
+     */
+    authorization?: CoarseAuthorization;
+    /**
+     * Effective feature-level permission string.
+     * Kept for backward compatibility; use authorization.featurePermission instead.
+     * Values: "FULL" | "EDIT" | "COMMENT" | "VIEW" | "NO_ACCESS"
+     */
+    effectiveRole?: string;
+    /**
+     * Optional feature ownership/publisher attribution resolved by Core.
+     * Use this for logs, support diagnostics, or future ownership-aware behavior.
+     */
+    developer?: {
+        ownerUserId?: string | null;
+        ownerDeveloperProfileId?: string | null;
+        ownerDisplayName?: string | null;
+        ownerDeveloperType?: string | null;
+        releaseId?: string | null;
+        storageMode?: string | null;
+    };
 };
 type CommandHandler = (input: Record<string, unknown>, context: CoreRequestContext) => Promise<unknown>;
 type CommandRegistry = {
@@ -391,4 +479,18 @@ type CommandRegistry = {
 declare function createCommandRegistry(): CommandRegistry;
 declare function createCoreRouter(app: Express, registry: CommandRegistry): void;
 
-export { type BackendNotification, type CommandHandler, type CommandRegistry, type CoreRequestContext, 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, createCommandRegistry, createCoreRouter, createNotificationPublisher, forbidClientInstanceId, formatTime, getPluginScope, isPastDate, pluginAuth, pluginErrorHandler, requireFeature, requirePermission, requireTabView, requireTaskScope, resolveEffectiveInstanceId, toDateString, withCoreServiceToken, withInstanceOnly, withInstanceScope, withUserAndInstance };
+type CreateDbOptions = {
+    prismaDir?: string;
+    coreApiUrl?: string;
+    serviceToken?: string;
+    managedDbSessionToken?: string;
+    runMigrations?: boolean;
+};
+type DbProvisionResult = {
+    connectionString: string;
+    schemaName: string;
+    featureSlug: string;
+};
+declare function provisionDb(options?: CreateDbOptions): Promise<DbProvisionResult>;
+
+export { type BackendNotification, type CoarseAuthorization, type CoarseCapabilities, type CommandHandler, type CommandRegistry, type CoreRequestContext, type CreateDbOptions, type DbProvisionResult, 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, createCommandRegistry, createCoreRouter, createNotificationPublisher, forbidClientInstanceId, formatTime, getPluginScope, isPastDate, pluginAuth, pluginErrorHandler, provisionDb, requireFeature, requirePermission, requireTabView, requireTaskScope, resolveEffectiveInstanceId, toDateString, withCoreServiceToken, withInstanceOnly, withInstanceScope, withUserAndInstance };

package/dist/index.js

@@ -32,6 +32,14 @@ function pickClaim(obj, key) {
   const v = obj?.[key];
   return typeof v === "string" && v.length > 0 ? v : void 0;
 }
+function isCoarseAuthorization(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const candidate = value;
+  const capabilities = candidate.capabilities;
+  return (candidate.workspaceRole === null || typeof candidate.workspaceRole === "string") && typeof candidate.spacePermission === "string" && typeof candidate.featurePermission === "string" && typeof candidate.accessSource === "string" && !!capabilities && typeof capabilities === "object" && !Array.isArray(capabilities) && typeof capabilities.canInviteMembers === "boolean" && typeof capabilities.canManageSpaces === "boolean" && typeof capabilities.canInstallWorkspaceFeatures === "boolean" && typeof capabilities.canCreateFeatureInstances === "boolean" && candidate.policyVersion === "v2";
+}
 function normalizeScope(payload) {
   const userId = pickClaim(payload, "sub");
   const workspaceId = pickClaim(payload, "workspaceId");
@@ -55,6 +63,7 @@ function normalizeScope(payload) {
     featureSlug,
     tabViewId,
     taskScopeId,
+    authorization: isCoarseAuthorization(payload.authorization) ? payload.authorization : void 0,
     roles: Array.isArray(payload.roles) ? payload.roles : void 0,
     perms: Array.isArray(payload.perms) ? payload.perms : void 0,
     tokenId: pickClaim(payload, "jti"),
@@ -298,18 +307,101 @@ function forbidClientInstanceId(options = {}) {
 }
 
 // src/notify.ts
+function isLoopbackHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]" || hostname === "::ffff:127.0.0.1" || hostname === "0.0.0.0" || hostname === "host.docker.internal";
+}
+function normalizeScheduledOptions(options) {
+  if (!options) {
+    return void 0;
+  }
+  return {
+    ...options,
+    scheduledAt: options.scheduledAt instanceof Date ? options.scheduledAt.toISOString() : options.scheduledAt
+  };
+}
 function createNotificationPublisher(config) {
   const { featureSlug, coreApiUrl, serviceToken, timeoutMs = 5e3 } = config;
   if (!featureSlug?.trim()) {
-    throw new Error("NotificationPublisher: featureSlug is required");
+    throw new Error(
+      "NotificationPublisher: featureSlug is required for Core-attributed notification sends."
+    );
   }
   if (!coreApiUrl?.trim()) {
-    throw new Error("NotificationPublisher: coreApiUrl is required");
+    throw new Error(
+      "NotificationPublisher: coreApiUrl is required. Set CORE_API_URL before sending notifications."
+    );
   }
   if (!serviceToken?.trim()) {
-    throw new Error("NotificationPublisher: serviceToken is required");
+    throw new Error(
+      "NotificationPublisher: serviceToken is required. Set CORE_SERVICE_TOKEN or SERVICE_TOKEN from the installation Developer Settings page."
+    );
+  }
+  function getNotificationToken() {
+    return config.notificationToken?.trim() || process.env.ENSERA_NOTIFICATION_TOKEN?.trim() || process.env.NOTIFICATION_TOKEN?.trim() || process.env.ENSERA_DEVELOPER_NOTIFICATION_TOKEN?.trim() || void 0;
+  }
+  function getCoreApiUrls() {
+    const normalized = coreApiUrl.replace(/\/+$/, "");
+    const candidates = [normalized];
+    try {
+      const fallbackUrl = new URL(normalized);
+      if (fallbackUrl.hostname === "host.docker.internal") {
+        fallbackUrl.hostname = "localhost";
+        candidates.push(fallbackUrl.toString().replace(/\/+$/, ""));
+      }
+    } catch {
+    }
+    return [...new Set(candidates)];
+  }
+  function allowsNotificationCompatibilityBridge() {
+    if ((process.env.ENSERA_ALLOW_LEGACY_NOTIFICATION_ACCESS ?? "").trim() === "1") {
+      return true;
+    }
+    if (process.env.NODE_ENV === "production") {
+      return false;
+    }
+    try {
+      return isLoopbackHost(new URL(coreApiUrl).hostname);
+    } catch {
+      return false;
+    }
+  }
+  function buildMissingNotificationTokenError() {
+    return `[NOTIFICATION_TOKEN_REQUIRED] Backend notifications for '${featureSlug}' require a Notification Token. Open Developer Settings > Tokens, reveal or rotate the Notification Token, set ENSERA_NOTIFICATION_TOKEN or NOTIFICATION_TOKEN in the backend environment, and retry.`;
+  }
+  function getNotificationPreflightError() {
+    if (getNotificationToken() || allowsNotificationCompatibilityBridge()) {
+      return null;
+    }
+    return buildMissingNotificationTokenError();
+  }
+  function formatCoreError2(status, data) {
+    const code = typeof data?.errorCode === "string" && data.errorCode.trim() ? `[${data.errorCode.trim()}] ` : "";
+    const message = typeof data?.error === "string" && data.error.trim() ? data.error.trim() : `HTTP ${status}`;
+    const hints = [
+      typeof data?.hint === "string" ? data.hint.trim() : void 0,
+      ...Array.isArray(data?.nextSteps) ? data.nextSteps.filter(
+        (entry) => typeof entry === "string" && entry.trim().length > 0
+      ) : []
+    ];
+    return hints.length > 0 ? `${code}${message} ${hints.join(" ")}` : `${code}${message}`;
+  }
+  function buildHeaders(notificationToken) {
+    return {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${serviceToken}`,
+      "X-Feature-Slug": featureSlug,
+      ...notificationToken ? {
+        "X-Ensera-Notification-Token": notificationToken
+      } : {}
+    };
+  }
+  async function readJson(response) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
   }
-  const baseUrl = coreApiUrl.replace(/\/+$/, "");
   async function fetchWithTimeout(url, options) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -328,52 +420,84 @@ function createNotificationPublisher(config) {
       throw error;
     }
   }
+  async function requestCore(path2, init) {
+    let lastError = null;
+    const notificationToken = getNotificationToken();
+    for (const baseUrl of getCoreApiUrls()) {
+      try {
+        return await fetchWithTimeout(`${baseUrl}${path2}`, {
+          ...init,
+          headers: {
+            ...buildHeaders(notificationToken),
+            ...init.headers ?? {}
+          }
+        });
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error("Failed to reach Core notification API");
+  }
+  function toPublishFailure(status, data) {
+    return {
+      success: false,
+      error: formatCoreError2(status, data),
+      errorCode: typeof data?.errorCode === "string" ? data.errorCode : void 0,
+      hint: typeof data?.hint === "string" ? data.hint : void 0,
+      nextSteps: Array.isArray(data?.nextSteps) ? data.nextSteps.filter(
+        (entry) => typeof entry === "string" && entry.trim().length > 0
+      ) : void 0
+    };
+  }
+  function toCancelFailure(status, data) {
+    return {
+      success: false,
+      cancelled: 0,
+      error: formatCoreError2(status, data),
+      errorCode: typeof data?.errorCode === "string" ? data.errorCode : void 0,
+      hint: typeof data?.hint === "string" ? data.hint : void 0,
+      nextSteps: Array.isArray(data?.nextSteps) ? data.nextSteps.filter(
+        (entry) => typeof entry === "string" && entry.trim().length > 0
+      ) : void 0
+    };
+  }
   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 preflightError = getNotificationPreflightError();
+    if (preflightError) {
+      return {
+        success: false,
+        error: preflightError,
+        errorCode: "NOTIFICATION_TOKEN_REQUIRED"
+      };
+    }
     const payload = {
       ...notification,
       featureSlug,
-      options: processedOptions
+      options: normalizeScheduledOptions(options)
     };
-    console.log("[NotificationPublisher] Publishing notification:", {
-      featureSlug,
-      userId: notification.userId,
-      type: notification.type,
-      scheduledAt: processedOptions?.scheduledAt,
-      hasScheduledAt: !!processedOptions?.scheduledAt
-    });
     try {
-      const response = await fetchWithTimeout(url, {
+      const response = await requestCore("/api/notifications/publish", {
         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
-      });
+      const data = await readJson(response);
       if (!response.ok) {
-        return {
-          success: false,
-          error: data.error || `HTTP ${response.status}`
-        };
+        return toPublishFailure(response.status, data);
       }
-      return data;
+      return {
+        success: true,
+        id: typeof data?.id === "string" ? data.id : void 0,
+        sent: typeof data?.sent === "boolean" ? data.sent : void 0,
+        emailSent: typeof data?.emailSent === "boolean" ? data.emailSent : void 0,
+        pushSent: typeof data?.pushSent === "boolean" ? data.pushSent : void 0,
+        scheduled: typeof data?.scheduled === "boolean" ? data.scheduled : void 0,
+        scheduledFor: typeof data?.scheduledFor === "string" ? data.scheduledFor : void 0,
+        reason: typeof data?.reason === "string" ? data.reason : void 0,
+        warnings: Array.isArray(data?.warnings) ? data.warnings.filter(
+          (entry) => typeof entry === "string" && entry.trim().length > 0
+        ) : void 0
+      };
     } catch (error) {
-      console.error("[NotificationPublisher] Error:", error);
       return {
         success: false,
         error: error.message || "Failed to publish notification"
@@ -381,23 +505,31 @@ function createNotificationPublisher(config) {
     }
   }
   async function publishBulk(notifications, options) {
-    const url = `${baseUrl}/api/notifications/bulk`;
+    const preflightError = getNotificationPreflightError();
+    if (preflightError) {
+      return {
+        success: false,
+        count: 0,
+        errors: [
+          {
+            index: 0,
+            userId: "",
+            error: preflightError
+          }
+        ]
+      };
+    }
     const payload = {
       notifications,
       featureSlug,
-      options
+      options: normalizeScheduledOptions(options)
     };
     try {
-      const response = await fetchWithTimeout(url, {
+      const response = await requestCore("/api/notifications/bulk", {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${serviceToken}`,
-          "X-Feature-Slug": featureSlug
-        },
         body: JSON.stringify(payload)
       });
-      const data = await response.json();
+      const data = await readJson(response);
       if (!response.ok) {
         return {
           success: false,
@@ -406,12 +538,16 @@ function createNotificationPublisher(config) {
             {
               index: 0,
               userId: "",
-              error: data.error || `HTTP ${response.status}`
+              error: formatCoreError2(response.status, data)
             }
           ]
         };
       }
-      return data;
+      return {
+        success: Boolean(data?.success),
+        count: typeof data?.count === "number" ? data.count : 0,
+        errors: Array.isArray(data?.errors) ? data.errors : void 0
+      };
     } catch (error) {
       return {
         success: false,
@@ -434,46 +570,32 @@ function createNotificationPublisher(config) {
     });
   }
   async function cancel(metadata) {
-    const url = `${baseUrl}/api/notifications/cancel-scheduled`;
-    const payload = {
-      featureSlug,
-      metadata
-    };
-    console.log("[NotificationPublisher] Cancelling notifications:", {
-      featureSlug,
-      metadata
-    });
+    const preflightError = getNotificationPreflightError();
+    if (preflightError) {
+      return {
+        success: false,
+        cancelled: 0,
+        error: preflightError,
+        errorCode: "NOTIFICATION_TOKEN_REQUIRED"
+      };
+    }
     try {
-      const response = await fetchWithTimeout(url, {
+      const response = await requestCore("/api/notifications/cancel-scheduled", {
         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
+        body: JSON.stringify({
+          featureSlug,
+          metadata
+        })
       });
+      const data = await readJson(response);
       if (!response.ok) {
-        return {
-          success: false,
-          cancelled: 0,
-          error: data.error || `HTTP ${response.status}`
-        };
+        return toCancelFailure(response.status, data);
       }
       return {
         success: true,
-        cancelled: data.cancelled || 0
+        cancelled: typeof data?.cancelled === "number" ? data.cancelled : 0
       };
     } catch (error) {
-      console.error("[NotificationPublisher] Cancel error:", error);
       return {
         success: false,
         cancelled: 0,
@@ -751,6 +873,130 @@ function createCoreRouter(app, registry) {
     })
   );
 }
+
+// src/createDb.ts
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function formatCoreError(status, payload) {
+  if (!isRecord(payload)) {
+    return `Core returned ${status}. Unknown error`;
+  }
+  const parts = [
+    getString(payload.errorCode) ? `[${getString(payload.errorCode)}]` : void 0,
+    getString(payload.error) ?? `Core returned ${status}. Unknown error`
+  ].filter(
+    (entry) => typeof entry === "string" && entry.trim().length > 0
+  );
+  const hints = [
+    getString(payload.hint),
+    ...Array.isArray(payload.nextSteps) ? payload.nextSteps.filter(
+      (entry) => typeof entry === "string" && entry.trim().length > 0
+    ) : []
+  ];
+  return hints.length > 0 ? `${parts.join(" ")} ${hints.join(" ")}` : parts.join(" ");
+}
+function parseProvisionResult(value) {
+  if (!isRecord(value)) {
+    throw new Error("provisionDb: Core returned an invalid response body");
+  }
+  const connectionString = getString(value.connectionString);
+  const schemaName = getString(value.schemaName);
+  const featureSlug = getString(value.featureSlug);
+  if (!connectionString) {
+    throw new Error("provisionDb: Core did not return a connectionString");
+  }
+  if (!schemaName) {
+    throw new Error("provisionDb: Core did not return a schemaName");
+  }
+  if (!featureSlug) {
+    throw new Error("provisionDb: Core did not return a featureSlug");
+  }
+  return {
+    connectionString,
+    schemaName,
+    featureSlug
+  };
+}
+async function provisionDb(options = {}) {
+  const coreApiUrl = (options.coreApiUrl ?? process.env.CORE_API_URL)?.replace(/\/+$/, "");
+  const serviceToken = options.serviceToken ?? process.env.CORE_SERVICE_TOKEN;
+  const resolvedServiceToken = serviceToken ?? process.env.SERVICE_TOKEN;
+  const managedDbSessionToken = options.managedDbSessionToken ?? process.env.ENSERA_MANAGED_DB_SESSION_TOKEN ?? process.env.MANAGED_DB_SESSION_TOKEN ?? process.env.ENSERA_DEVELOPER_DB_TOKEN;
+  if (!coreApiUrl) {
+    throw new Error(
+      "provisionDb: CORE_API_URL is not set. Add it to your .env file."
+    );
+  }
+  if (!resolvedServiceToken) {
+    throw new Error(
+      "provisionDb: CORE_SERVICE_TOKEN or SERVICE_TOKEN is not set. Add it to your .env file."
+    );
+  }
+  const response = await fetch(`${coreApiUrl}/api/internal/db/provision`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${resolvedServiceToken}`,
+      ...managedDbSessionToken ? {
+        "x-ensera-managed-db-session-token": managedDbSessionToken
+      } : {}
+    }
+  });
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch {
+    payload = null;
+  }
+  if (!response.ok) {
+    throw new Error(
+      `provisionDb: ${formatCoreError(response.status, payload)}`
+    );
+  }
+  const result = parseProvisionResult(payload);
+  const shouldMigrate = options.runMigrations !== false;
+  if (shouldMigrate) {
+    const prismaDir = options.prismaDir ?? path.join(process.cwd(), "prisma");
+    const migrationsDir = path.join(prismaDir, "migrations");
+    if (fs.existsSync(prismaDir) && fs.existsSync(migrationsDir)) {
+      console.log(
+        `[ensera-db] Running migrations for schema: ${result.schemaName}`
+      );
+      try {
+        execSync("npx prisma migrate deploy", {
+          cwd: path.dirname(prismaDir),
+          stdio: "inherit",
+          env: {
+            ...process.env,
+            DATABASE_URL: result.connectionString
+          }
+        });
+        console.log("[ensera-db] Migrations complete");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown migration error";
+        throw new Error(`[ensera-db] Migration failed: ${message}`);
+      }
+    } else if (fs.existsSync(prismaDir)) {
+      console.warn(
+        `[ensera-db] No prisma migrations found at ${migrationsDir}. Skipping migrations.`
+      );
+    } else {
+      console.warn(
+        `[ensera-db] No prisma directory found at ${prismaDir}. Skipping migrations.`
+      );
+    }
+  }
+  return result;
+}
 export {
   PluginError,
   assertPluginScope,
@@ -765,6 +1011,7 @@ export {
   isPastDate,
   pluginAuth,
   pluginErrorHandler,
+  provisionDb,
   requireFeature,
   requirePermission,
   requireTabView,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ensera/plugin-backend",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Runtime backend SDK for Ensera plugins.",
   "type": "module",
   "main": "./dist/index.js",