@nextsparkjs/core 0.1.0-beta.91 → 0.1.0-beta.94

package/dist/lib/scheduled-actions/processor.d.ts

@@ -1,11 +1,22 @@
 /**
  * Scheduled Actions - Processor
- * Processes pending actions and manages their lifecycle
+ * Processes pending actions with parallel execution and lock-group based locking
+ *
+ * Features:
+ * - Controlled parallelism with configurable concurrency limit
+ * - Lock-group based locking to prevent race conditions on same resource
+ * - SELECT FOR UPDATE SKIP LOCKED for safe concurrent processing
+ * - Timeout protection per action
  */
-import type { ProcessResult } from './types';
+import type { ScheduledAction, ProcessResult } from './types';
 /**
- * Process pending actions
- * Fetches pending actions, executes them, and updates their status
+ * Process pending actions with parallel execution
+ * Uses SELECT FOR UPDATE SKIP LOCKED for safe concurrent processing
+ *
+ * Lock Group Behavior:
+ * - Actions with same lockGroup are processed sequentially
+ * - Actions with NULL lockGroup can run in parallel with any other action
+ * - Uses PostgreSQL row-level locking to prevent race conditions
  *
  * @param batchSize - Maximum number of actions to process (uses config default if not provided)
  * @returns Result with counts and errors
@@ -15,4 +26,9 @@ import type { ProcessResult } from './types';
  * console.log(`Processed ${result.processed}, succeeded ${result.succeeded}, failed ${result.failed}`)
  */
 export declare function processPendingActions(batchSize?: number): Promise<ProcessResult>;
+/**
+ * Execute a single action
+ * Handles the full lifecycle of action execution
+ */
+export declare function executeAction(action: ScheduledAction): Promise<void>;
 //# sourceMappingURL=processor.d.ts.map

package/dist/lib/scheduled-actions/processor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../../src/lib/scheduled-actions/processor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,SAAS,CAAA;AAM7D;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CA+CxB"}
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../../src/lib/scheduled-actions/processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAO7D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAkExB;AAuFD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA4D1E"}

package/dist/lib/scheduled-actions/processor.js

@@ -4,9 +4,11 @@ import { getActionHandler } from "./registry.js";
 import { scheduleAction } from "./scheduler.js";
 const DEFAULT_BATCH_SIZE = 10;
 const DEFAULT_TIMEOUT = 3e4;
+const DEFAULT_CONCURRENCY_LIMIT = 1;
 async function processPendingActions(batchSize) {
-  var _a;
+  var _a, _b;
   const effectiveBatchSize = batchSize ?? ((_a = APP_CONFIG_MERGED.scheduledActions) == null ? void 0 : _a.batchSize) ?? DEFAULT_BATCH_SIZE;
+  const concurrencyLimit = ((_b = APP_CONFIG_MERGED.scheduledActions) == null ? void 0 : _b.concurrencyLimit) ?? DEFAULT_CONCURRENCY_LIMIT;
   const result = {
     processed: 0,
     succeeded: 0,
@@ -14,28 +16,39 @@ async function processPendingActions(batchSize) {
     errors: []
   };
   try {
-    const actions = await queryWithRLS(
-      `SELECT * FROM "scheduled_actions"
-       WHERE status = 'pending'
-         AND "scheduledAt" <= NOW()
-       ORDER BY "scheduledAt" ASC
-       LIMIT $1`,
-      [effectiveBatchSize],
-      null
-      // System operation
-    );
-    console.log(`[ScheduledActions] Found ${actions.length} pending action(s) to process`);
-    for (const action of actions) {
-      result.processed++;
-      try {
-        await executeAction(action);
-        result.succeeded++;
-      } catch (error) {
-        result.failed++;
-        result.errors.push({
-          actionId: action.id,
-          error: error instanceof Error ? error.message : "Unknown error"
-        });
+    const actions = await fetchAndLockPendingActions(effectiveBatchSize);
+    if (actions.length === 0) {
+      console.log("[ScheduledActions] No pending actions to process");
+      return result;
+    }
+    console.log(`[ScheduledActions] Found ${actions.length} pending action(s) to process (concurrency: ${concurrencyLimit})`);
+    if (concurrencyLimit === 1) {
+      for (const action of actions) {
+        result.processed++;
+        try {
+          await executeAction(action);
+          result.succeeded++;
+        } catch (error) {
+          result.failed++;
+          result.errors.push({
+            actionId: action.id,
+            error: error instanceof Error ? error.message : "Unknown error"
+          });
+        }
+      }
+    } else {
+      const results = await processWithConcurrencyLimit(actions, concurrencyLimit);
+      for (const r of results) {
+        result.processed++;
+        if (r.status === "fulfilled") {
+          result.succeeded++;
+        } else {
+          result.failed++;
+          result.errors.push({
+            actionId: r.actionId,
+            error: r.reason instanceof Error ? r.reason.message : "Unknown error"
+          });
+        }
       }
     }
     console.log(`[ScheduledActions] Processing complete: ${result.succeeded} succeeded, ${result.failed} failed`);
@@ -45,11 +58,57 @@ async function processPendingActions(batchSize) {
   }
   return result;
 }
+async function fetchAndLockPendingActions(batchSize) {
+  const actions = await queryWithRLS(
+    `WITH ranked_actions AS (
+      SELECT *,
+        ROW_NUMBER() OVER (
+          PARTITION BY "lockGroup"
+          ORDER BY "scheduledAt" ASC
+        ) as rn
+      FROM "scheduled_actions"
+      WHERE status = 'pending'
+        AND "scheduledAt" <= NOW()
+    )
+    SELECT id, "actionType", status, payload, "teamId", "scheduledAt",
+           "startedAt", "completedAt", "errorMessage", attempts,
+           "recurringInterval", "recurrenceType", "lockGroup", "maxRetries",
+           "createdAt", "updatedAt"
+    FROM ranked_actions
+    WHERE rn = 1 OR "lockGroup" IS NULL
+    ORDER BY "scheduledAt" ASC
+    LIMIT $1
+    FOR UPDATE SKIP LOCKED`,
+    [batchSize],
+    null
+    // System operation
+  );
+  return actions;
+}
+async function processWithConcurrencyLimit(actions, limit) {
+  const results = [];
+  const executing = /* @__PURE__ */ new Set();
+  for (const action of actions) {
+    const promise = executeAction(action).then(() => {
+      results.push({ actionId: action.id, status: "fulfilled" });
+    }).catch((error) => {
+      results.push({ actionId: action.id, status: "rejected", reason: error });
+    }).finally(() => {
+      executing.delete(promise);
+    });
+    executing.add(promise);
+    if (executing.size >= limit) {
+      await Promise.race(executing);
+    }
+  }
+  await Promise.all(executing);
+  return results;
+}
 async function executeAction(action) {
   var _a;
   const startTime = Date.now();
   const configDefaultTimeout = ((_a = APP_CONFIG_MERGED.scheduledActions) == null ? void 0 : _a.defaultTimeout) ?? DEFAULT_TIMEOUT;
-  console.log(`[ScheduledActions] Executing action ${action.id} (${action.actionType})`);
+  console.log(`[ScheduledActions] Executing action ${action.id} (${action.actionType})${action.lockGroup ? ` [lockGroup: ${action.lockGroup}]` : ""}`);
   await markActionRunning(action.id);
   try {
     const actionDef = getActionHandler(action.actionType);
@@ -72,7 +131,14 @@ async function executeAction(action) {
     const executionTime = Date.now() - startTime;
     const errorMessage = error instanceof Error ? error.message : "Unknown error";
     console.error(`[ScheduledActions] Action ${action.id} failed after ${executionTime}ms:`, errorMessage);
-    await markActionFailed(action.id, errorMessage);
+    if (action.attempts < action.maxRetries) {
+      const retryDelayMinutes = action.attempts * 5;
+      console.log(`[ScheduledActions] Will retry action ${action.id} in ${retryDelayMinutes} minutes (attempt ${action.attempts}/${action.maxRetries})`);
+      await rescheduleFailedAction(action, errorMessage, retryDelayMinutes);
+    } else {
+      console.error(`[ScheduledActions] Max retries (${action.maxRetries}) reached for action ${action.id}`);
+      await markActionFailed(action.id, errorMessage);
+    }
     throw error;
   }
 }
@@ -117,36 +183,64 @@ async function markActionFailed(actionId, errorMessage) {
     null
   );
 }
+async function rescheduleFailedAction(action, errorMessage, delayMinutes) {
+  const nextAttemptTime = new Date(Date.now() + delayMinutes * 60 * 1e3);
+  await mutateWithRLS(
+    `UPDATE "scheduled_actions"
+     SET status = 'pending',
+         "scheduledAt" = $2,
+         "errorMessage" = $3,
+         "startedAt" = NULL,
+         "completedAt" = NULL,
+         "updatedAt" = NOW()
+     WHERE id = $1`,
+    [action.id, nextAttemptTime, errorMessage],
+    null
+  );
+  console.log(`[ScheduledActions] Rescheduled action ${action.id} for ${nextAttemptTime.toISOString()}`);
+}
 async function rescheduleRecurringAction(action) {
   if (!action.recurringInterval) {
     return;
   }
-  const nextScheduledAt = calculateNextScheduledTime(action.recurringInterval);
+  let nextScheduledAt;
+  if (action.recurrenceType === "rolling") {
+    nextScheduledAt = calculateNextScheduledTime(action.recurringInterval, /* @__PURE__ */ new Date());
+  } else {
+    nextScheduledAt = calculateNextScheduledTime(action.recurringInterval, action.scheduledAt);
+  }
   await scheduleAction(
     action.actionType,
     action.payload,
     {
       scheduledAt: nextScheduledAt,
       teamId: action.teamId ?? void 0,
-      recurringInterval: action.recurringInterval ?? void 0
+      recurringInterval: action.recurringInterval ?? void 0,
+      recurrenceType: action.recurrenceType ?? void 0,
+      lockGroup: action.lockGroup ?? void 0
     }
   );
-  console.log(`[ScheduledActions] Rescheduled recurring action ${action.actionType} for ${nextScheduledAt.toISOString()}`);
+  console.log(
+    `[ScheduledActions] Rescheduled recurring action ${action.actionType} for ${nextScheduledAt.toISOString()} (type: ${action.recurrenceType || "fixed"})`
+  );
 }
-function calculateNextScheduledTime(interval) {
-  const now = /* @__PURE__ */ new Date();
+function calculateNextScheduledTime(interval, baseTime) {
+  const base = new Date(baseTime);
   switch (interval) {
+    case "every-30-minutes":
+      return new Date(base.getTime() + 30 * 60 * 1e3);
     case "hourly":
-      return new Date(now.getTime() + 60 * 60 * 1e3);
+      return new Date(base.getTime() + 60 * 60 * 1e3);
     case "daily":
-      return new Date(now.getTime() + 24 * 60 * 60 * 1e3);
+      return new Date(base.getTime() + 24 * 60 * 60 * 1e3);
     case "weekly":
-      return new Date(now.getTime() + 7 * 24 * 60 * 60 * 1e3);
+      return new Date(base.getTime() + 7 * 24 * 60 * 60 * 1e3);
     default:
       console.warn(`[ScheduledActions] Unknown interval '${interval}', defaulting to 1 hour`);
-      return new Date(now.getTime() + 60 * 60 * 1e3);
+      return new Date(base.getTime() + 60 * 60 * 1e3);
   }
 }
 export {
+  executeAction,
   processPendingActions
 };

package/dist/lib/scheduled-actions/registry.d.ts

@@ -1,6 +1,9 @@
 /**
  * Scheduled Actions - Registry
  * Manages registration and lookup of action handlers
+ *
+ * Uses globalThis to persist across HMR in development mode.
+ * Same pattern as Next.js recommends for database connections.
  */
 import type { ScheduledActionDefinition, ScheduledActionHandler } from './types';
 /**

package/dist/lib/scheduled-actions/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/lib/scheduled-actions/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAShF;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,IAAI,CAaN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/lib/scheduled-actions/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAehF;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,IAAI,CAaN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C"}

package/dist/lib/scheduled-actions/registry.js

@@ -1,4 +1,5 @@
-const actionRegistry = /* @__PURE__ */ new Map();
+const globalForScheduledActions = globalThis;
+const actionRegistry = globalForScheduledActions.__scheduledActionsRegistry ??= /* @__PURE__ */ new Map();
 function registerScheduledAction(name, handler, options) {
   if (actionRegistry.has(name)) {
     console.warn(`[ScheduledActions] Action '${name}' is already registered. Overwriting.`);

package/dist/lib/scheduled-actions/scheduler.d.ts

@@ -28,7 +28,7 @@ import type { ScheduleOptions } from './types';
  *   data: { title: 'New Task' }
  * }, { teamId: 'team-456' })
  */
-export declare function scheduleAction(actionType: string, payload: unknown, options?: ScheduleOptions): Promise<string | null>;
+export declare function scheduleAction(actionType: string, payload: unknown, options?: ScheduleOptions): Promise<string>;
 /**
  * Schedule a recurring action
  * Convenience function that sets recurringInterval

package/dist/lib/scheduled-actions/scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/lib/scheduled-actions/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAM9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAsFxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,mBAAmB,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoB9E"}
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/lib/scheduled-actions/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAM9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,CAAC,CAkIjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,mBAAmB,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoB9E"}

package/dist/lib/scheduled-actions/scheduler.js

@@ -1,4 +1,4 @@
-import { mutateWithRLS, queryWithRLS } from "../db.js";
+import { mutateWithRLS, getTransactionClient } from "../db.js";
 import { APP_CONFIG_MERGED } from "../config/config-sync.js";
 async function scheduleAction(actionType, payload, options) {
   var _a;
@@ -8,41 +8,74 @@ async function scheduleAction(actionType, payload, options) {
   const entityId = payloadObj == null ? void 0 : payloadObj.entityId;
   const entityType = payloadObj == null ? void 0 : payloadObj.entityType;
   const shouldDeduplicate = windowSeconds > 0 && entityId && !(options == null ? void 0 : options.recurringInterval);
+  const actionId = globalThis.crypto.randomUUID();
+  const scheduledAt = (options == null ? void 0 : options.scheduledAt) || /* @__PURE__ */ new Date();
+  const teamId = (options == null ? void 0 : options.teamId) || null;
+  const recurringInterval = (options == null ? void 0 : options.recurringInterval) || null;
+  const lockGroup = (options == null ? void 0 : options.lockGroup) || null;
+  const maxRetries = (options == null ? void 0 : options.maxRetries) ?? 3;
+  const recurrenceType = (options == null ? void 0 : options.recurrenceType) || null;
   if (shouldDeduplicate) {
     const dedupKey = `${actionType}:${entityId}:${entityType || ""}`;
-    await queryWithRLS(
-      `SELECT pg_advisory_xact_lock(hashtext($1))`,
-      [dedupKey],
-      null
-    );
-    const existing = await queryWithRLS(
-      `SELECT id
-       FROM "scheduled_actions"
-       WHERE "actionType" = $1
-         AND status = 'pending'
-         AND payload->>'entityId' = $2
-         AND payload->>'entityType' = $3
-         AND "createdAt" > NOW() - INTERVAL '1 second' * $4
-       LIMIT 1`,
-      [actionType, entityId, entityType || "", windowSeconds],
-      null
-    );
-    if (existing.length > 0) {
-      await mutateWithRLS(
-        `UPDATE "scheduled_actions"
-         SET payload = $1, "updatedAt" = NOW()
-         WHERE id = $2 AND status = 'pending'`,
-        [JSON.stringify(payload), existing[0].id],
-        null
+    const client = await getTransactionClient(null);
+    try {
+      await client.query(`SELECT pg_advisory_xact_lock(hashtext($1))`, [dedupKey]);
+      const existing = await client.query(
+        `SELECT id
+         FROM "scheduled_actions"
+         WHERE "actionType" = $1
+           AND status = 'pending'
+           AND payload->>'entityId' = $2
+           AND payload->>'entityType' = $3
+           AND "createdAt" > NOW() - INTERVAL '1 second' * $4
+         LIMIT 1`,
+        [actionType, entityId, entityType || "", windowSeconds]
+      );
+      if (existing.length > 0) {
+        await client.query(
+          `UPDATE "scheduled_actions"
+           SET payload = $1, "updatedAt" = NOW()
+           WHERE id = $2 AND status = 'pending'`,
+          [payload, existing[0].id]
+        );
+        await client.commit();
+        console.log(`[ScheduledActions] Duplicate detected, updated payload: ${existing[0].id}`);
+        return existing[0].id;
+      }
+      await client.query(
+        `INSERT INTO "scheduled_actions" (
+          id,
+          "actionType",
+          status,
+          payload,
+          "teamId",
+          "scheduledAt",
+          "recurringInterval",
+          "lockGroup",
+          "maxRetries",
+          "recurrenceType"
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+        [
+          actionId,
+          actionType,
+          "pending",
+          payload,
+          teamId,
+          scheduledAt.toISOString(),
+          recurringInterval,
+          lockGroup,
+          maxRetries,
+          recurrenceType
+        ]
       );
-      console.log(`[ScheduledActions] Duplicate detected, updated payload: ${existing[0].id}`);
-      return existing[0].id;
+      await client.commit();
+      console.log(`[ScheduledActions] Scheduled action '${actionType}' with ID: ${actionId}${lockGroup ? ` (lockGroup: ${lockGroup})` : ""}`);
+      return actionId;
+    } catch (error) {
+      await client.rollback();
+      throw error;
     }
   }
-  const actionId = globalThis.crypto.randomUUID();
-  const scheduledAt = (options == null ? void 0 : options.scheduledAt) || /* @__PURE__ */ new Date();
-  const teamId = (options == null ? void 0 : options.teamId) || null;
-  const recurringInterval = (options == null ? void 0 : options.recurringInterval) || null;
   await mutateWithRLS(
     `INSERT INTO "scheduled_actions" (
       id,
@@ -51,29 +84,34 @@ async function scheduleAction(actionType, payload, options) {
       payload,
       "teamId",
       "scheduledAt",
-      "recurringInterval"
-    ) VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+      "recurringInterval",
+      "lockGroup",
+      "maxRetries",
+      "recurrenceType"
+    ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
     [
       actionId,
       actionType,
       "pending",
-      JSON.stringify(payload),
+      payload,
       teamId,
       scheduledAt.toISOString(),
-      recurringInterval
+      recurringInterval,
+      lockGroup,
+      maxRetries,
+      recurrenceType
     ],
     null
     // System operation, no RLS context needed
   );
-  console.log(`[ScheduledActions] Scheduled action '${actionType}' with ID: ${actionId}`);
+  console.log(`[ScheduledActions] Scheduled action '${actionType}' with ID: ${actionId}${lockGroup ? ` (lockGroup: ${lockGroup})` : ""}`);
   return actionId;
 }
 async function scheduleRecurringAction(actionType, payload, interval, options) {
-  const result = await scheduleAction(actionType, payload, {
+  return scheduleAction(actionType, payload, {
     ...options,
     recurringInterval: interval
   });
-  return result;
 }
 async function cancelScheduledAction(actionId) {
   const result = await mutateWithRLS(

package/dist/lib/scheduled-actions/types.d.ts

@@ -3,6 +3,17 @@
  * Core types for the scheduled actions system
  */
 export type ScheduledActionStatus = 'pending' | 'running' | 'completed' | 'failed';
+/**
+ * Determines how next execution time is calculated for recurring actions
+ *
+ * @example
+ * 'fixed' - Maintains exact schedule times (e.g., daily at 12:00)
+ *           If action scheduled at 12:00 runs at 12:05, next is still 12:00 tomorrow
+ *
+ * 'rolling' - Intervals from actual completion time (e.g., 30min after execution finishes)
+ *             If action scheduled at 12:00 runs at 12:15, next is 12:45
+ */
+export type RecurrenceType = 'fixed' | 'rolling';
 /**
  * Scheduled action record from database
  * NOTE: Database uses camelCase (e.g., actionType, teamId, scheduledAt)
@@ -18,7 +29,34 @@ export interface ScheduledAction {
     completedAt: Date | null;
     errorMessage: string | null;
     attempts: number;
+    /**
+     * Maximum value for the attempts counter before marking action as failed.
+     * Represents total attempts (initial execution + retries), not retry count.
+     * Default: 3
+     *
+     * @example
+     * maxRetries = 0 -> Fail immediately, no retries (1 total attempt)
+     * maxRetries = 3 -> 3 total attempts (1 initial + 2 retries)
+     * maxRetries = 5 -> 5 total attempts (1 initial + 4 retries)
+     */
+    maxRetries: number;
     recurringInterval: string | null;
+    /**
+     * Determines how next execution time is calculated for recurring actions.
+     * Only relevant when recurringInterval is set.
+     * Default: 'fixed'
+     */
+    recurrenceType: RecurrenceType | null;
+    /**
+     * Lock group key for parallel execution control.
+     * Actions with the same lockGroup will be processed sequentially.
+     * Actions with NULL lockGroup can run in parallel with any other action.
+     *
+     * @example
+     * lockGroup = 'client:123' -> All actions for client 123 run sequentially
+     * lockGroup = 'content:456' -> All actions for content 456 run sequentially
+     */
+    lockGroup: string | null;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -46,6 +84,41 @@ export interface ScheduleOptions {
     scheduledAt?: Date;
     teamId?: string;
     recurringInterval?: 'hourly' | 'daily' | 'weekly' | string;
+    /**
+     * Maximum value for the attempts counter before marking action as failed.
+     * Represents total attempts (initial execution + retries), not retry count.
+     * Default: 3
+     *
+     * @example
+     * { maxRetries: 0 } -> Fail immediately, no retries (1 total attempt)
+     * { maxRetries: 3 } -> 3 total attempts (1 initial + 2 retries)
+     * { maxRetries: 5 } -> 5 total attempts (1 initial + 4 retries) for critical operations
+     */
+    maxRetries?: number;
+    /**
+     * Lock group key for parallel execution control.
+     * Actions with the same lockGroup will be processed sequentially.
+     *
+     * @example
+     * { lockGroup: 'client:123' } -> All actions for client 123 run sequentially
+     * { lockGroup: `content:${contentId}` } -> Prevents concurrent content publishing
+     */
+    lockGroup?: string;
+    /**
+     * Determines how next execution time is calculated for recurring actions.
+     * Only relevant when recurringInterval is set.
+     * Default: 'fixed'
+     *
+     * @example
+     * // Daily report at 12:00 (fixed schedule)
+     * { recurringInterval: 'daily', recurrenceType: 'fixed' }
+     * // If runs at 12:05, next is still 12:00 tomorrow
+     *
+     * // Token refresh every 30 minutes (rolling interval)
+     * { recurringInterval: 'every-30-minutes', recurrenceType: 'rolling' }
+     * // If scheduled at 12:00 but runs at 12:15, next is 12:45
+     */
+    recurrenceType?: RecurrenceType;
 }
 /**
  * Result of processing actions

package/dist/lib/scheduled-actions/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/scheduled-actions/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;AAElF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,qBAAqB,CAAA;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,WAAW,EAAE,IAAI,CAAA;IACjB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAA;IACtB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,sBAAsB,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iBAAiB,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACnD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/scheduled-actions/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;AAElF;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,CAAA;AAEhD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,qBAAqB,CAAA;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,WAAW,EAAE,IAAI,CAAA;IACjB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAA;IACtB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;;;;;OASG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;;;;OAIG;IACH,cAAc,EAAE,cAAc,GAAG,IAAI,CAAA;IACrC;;;;;;;;OAQG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,sBAAsB,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iBAAiB,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC1D;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACnD"}