@yellowpanther/shared 1.2.6 → 1.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yellowpanther/shared",
-  "version": "1.2.6",
+  "version": "1.2.9",
   "publishConfig": {
     "access": "public"
   },
@@ -23,6 +23,7 @@
     "./queue/newsTranslateQueue": "./src/queue/newsTranslateQueue.js",
     "./queue/newsPublishQueue": "./src/queue/newsPublishQueue.js",
     "./queue/articlePublishQueue": "./src/queue/articlePublishQueue.js",
+    "./queue/eventPublishQueue": "./src/queue/eventPublishQueue.js",
     "./queue/videoPublishQueue": "./src/queue/videoPublishQueue.js",
     "./queue/imagePublishQueue": "./src/queue/imagePublishQueue.js",
     "./queue/imageAlbumPublishQueue": "./src/queue/imageAlbumPublishQueue.js",

package/src/index.js

@@ -1,25 +1,33 @@
+const { addEventPublishJob } = require("./queue/eventPublishQueue");
+
 module.exports = {
   // ✅ Redis
-  redisClient: require('./redis/redisClient'),
+  redisClient: require("./redis/redisClient"),
 
   // ✅ Language tranlation Helper
-  translationHelper: require('./lang/translationHelper'),
+  translationHelper: require("./lang/translationHelper"),
 
   // ✅ Config
-  config: require('./config'),
+  config: require("./config"),
 
   // ✅ Queues
-  compressionQueue: require('./queue/compressionQueue'),
-  addCompressionJob: require('./queue/compressionQueue').addCompressionJob,
-  newsTranslateQueue: require('./queue/newsTranslateQueue'),
-  addNewsTranslationJob: require('./queue/newsTranslateQueue').addNewsTranslationJob,
-  addNewsPublishJob: require('./queue/newsPublishQueue').addNewsPublishJob,
-  addArticlePublishJob: require('./queue/articlePublishQueue').addArticlePublishJob,
-  addVideoPublishJob: require('./queue/videoPublishQueue').addVideoPublishJob,
-  addImagePublishJob: require('./queue/imagePublishQueue').addImagePublishJob,
-  addPagePublishJob: require('./queue/pagePublishQueue').addPagePublishJob,
-  addProductPublishJob: require('./queue/productPublishQueue').addProductPublishJob,
-  addQuizPublishJob: require('./queue/quizPublishQueue').addQuizPublishJob,
-  addPredictionPublishJob: require('./queue/predictionPublishQueue').addPredictionPublishJob,
-  addImageAlbumPublishJob: require('./queue/imageAlbumPublishQueue').addImageAlbumPublishJob,
-};
+  compressionQueue: require("./queue/compressionQueue"),
+  addCompressionJob: require("./queue/compressionQueue").addCompressionJob,
+  newsTranslateQueue: require("./queue/newsTranslateQueue"),
+  addNewsTranslationJob: require("./queue/newsTranslateQueue")
+    .addNewsTranslationJob,
+  addNewsPublishJob: require("./queue/newsPublishQueue").addNewsPublishJob,
+  addArticlePublishJob: require("./queue/articlePublishQueue")
+    .addArticlePublishJob,
+  addVideoPublishJob: require("./queue/videoPublishQueue").addVideoPublishJob,
+  addImagePublishJob: require("./queue/imagePublishQueue").addImagePublishJob,
+  addPagePublishJob: require("./queue/pagePublishQueue").addPagePublishJob,
+  addProductPublishJob: require("./queue/productPublishQueue")
+    .addProductPublishJob,
+  addQuizPublishJob: require("./queue/quizPublishQueue").addQuizPublishJob,
+  addPredictionPublishJob: require("./queue/predictionPublishQueue")
+    .addPredictionPublishJob,
+  addImageAlbumPublishJob: require("./queue/imageAlbumPublishQueue")
+    .addImageAlbumPublishJob,
+  addEventPublishJob: require("./queue/eventPublishQueue").addEventPublishJob,
+};

package/src/queue/articlePublishQueue.js

@@ -2,18 +2,18 @@
 // One-off *publish* scheduler for article items (BullMQ).
 // Strong upsert: purge any prior job for the same article before adding a new delayed job.
 
-const { Queue } = require('bullmq');
-const redisClient = require('../redis/redisClient');
+const { Queue } = require("bullmq");
+const redisClient = require("../redis/redisClient");
 // const logger = require('../logger'); // uncomment if you have a shared logger
 
-const DEBUG = String(process.env.DEBUG_LOGGER || '').trim() === '1';
+const DEBUG = String(process.env.DEBUG_LOGGER || "").trim() === "1";
 const DRIFT_MS = Math.max(0, Number(process.env.SCHEDULE_DRIFT_MS || 250));
 
-const articlePublishQueue = new Queue('articlePublishQueue', {
+const articlePublishQueue = new Queue("articlePublishQueue", {
   connection: redisClient,
   defaultJobOptions: {
     attempts: 5,
-    backoff: { type: 'exponential', delay: 2000 },
+    backoff: { type: "exponential", delay: 2000 },
     removeOnComplete: 500,
     removeOnFail: 500,
   },
@@ -21,11 +21,19 @@ const articlePublishQueue = new Queue('articlePublishQueue', {
 
 // --- ID helpers --------------------------------------------------------------
 
+/** Replace invalid chars for BullMQ IDs */
+function sanitizeId(str) {
+  return str.replace(/[:.]/g, "-");
+}
+
+/** Stable id (latest schedule) */
 function stableJobId(article_id) {
-  return `article:publish:${article_id}`;
+  return sanitizeId(`article:publish:${article_id}`);
 }
+
+/** Versioned id (keeps history distinct) */
 function versionedJobId(article_id, runAtIso) {
-  return `article:publish:${article_id}:${runAtIso}`;
+  return sanitizeId(`article:publish:${article_id}:${runAtIso}`);
 }
 
 // --- Time helpers ------------------------------------------------------------
@@ -33,19 +41,21 @@ function versionedJobId(article_id, runAtIso) {
 /** Parse anything into a UTC Date. Strings without timezone are treated as UTC. */
 function normalizeToUtcDate(input) {
   if (input instanceof Date) return new Date(input.getTime());
-  if (typeof input === 'number') return new Date(input); // epoch ms
+  if (typeof input === "number") return new Date(input); // epoch ms
 
-  if (typeof input === 'string') {
+  if (typeof input === "string") {
     // Has timezone (Z or ±hh:mm)
     if (/[zZ]|[+\-]\d{2}:\d{2}$/.test(input)) {
       const d = new Date(input);
-      if (Number.isNaN(d.getTime())) throw new Error(`Invalid ISO datetime: ${input}`);
+      if (Number.isNaN(d.getTime()))
+        throw new Error(`Invalid ISO datetime: ${input}`);
       return d;
     }
     // No timezone => treat as UTC
-    const s = input.trim().replace(' ', 'T');
+    const s = input.trim().replace(" ", "T");
     const d = new Date(`${s}Z`);
-    if (Number.isNaN(d.getTime())) throw new Error(`Invalid datetime (no tz): ${input}`);
+    if (Number.isNaN(d.getTime()))
+      throw new Error(`Invalid datetime (no tz): ${input}`);
     return d;
   }
 
@@ -55,10 +65,12 @@ function normalizeToUtcDate(input) {
 // --- Purge helpers -----------------------------------------------------------
 
 async function findPendingArticleJobs(article_id) {
-  const states = ['delayed', 'waiting', 'waiting-children', 'active'];
+  const states = ["delayed", "waiting", "waiting-children", "active"];
   const jobs = await articlePublishQueue.getJobs(states);
   return jobs.filter(
-    (j) => j?.name === 'article:publish' && j?.data?.article_id === String(article_id)
+    (j) =>
+      j?.name === "article:publish" &&
+      j?.data?.article_id === String(article_id)
   );
 }
 
@@ -72,7 +84,10 @@ async function purgeExistingForArticle(article_id) {
       await j.remove();
       removed++;
     } catch (e) {
-      if (DEBUG) console.warn(`[articlePublishQueue] failed to remove pending job ${j.id}: ${e.message}`);
+      if (DEBUG)
+        console.warn(
+          `[articlePublishQueue] failed to remove pending job ${j.id}: ${e.message}`
+        );
     }
   }
 
@@ -83,12 +98,15 @@ async function purgeExistingForArticle(article_id) {
       await last.remove();
       removed++;
     } catch (e) {
-      if (DEBUG) console.warn(`[articlePublishQueue] failed to remove stable job ${last.id}: ${e.message}`);
+      if (DEBUG)
+        console.warn(
+          `[articlePublishQueue] failed to remove stable job ${last.id}: ${e.message}`
+        );
     }
   }
 
   if (DEBUG) {
-    console.info('[articlePublishQueue] purgeExistingForArticle', {
+    console.info("[articlePublishQueue] purgeExistingForArticle", {
       article_id: String(article_id),
       removed,
     });
@@ -109,9 +127,16 @@ async function purgeExistingForArticle(article_id) {
  * @param {object} [params.extra]
  * @param {boolean} [params.useStableId=false] - if true, uses stable jobId
  */
-async function addArticlePublishJob({ article_id, runAtUtc, extra = {}, useStableId = false }) {
+async function addArticlePublishJob({
+  article_id,
+  runAtUtc,
+  extra = {},
+  useStableId = false,
+}) {
   if (!article_id || !runAtUtc) {
-    throw new Error('addArticlePublishJob: article_id and runAtUtc are required');
+    throw new Error(
+      "addArticlePublishJob: article_id and runAtUtc are required"
+    );
   }
 
   const runAt = normalizeToUtcDate(runAtUtc);
@@ -126,16 +151,18 @@ async function addArticlePublishJob({ article_id, runAtUtc, extra = {}, useStabl
   await purgeExistingForArticle(article_id);
 
   // Choose jobId strategy
-  const jobId = useStableId ? stableJobId(article_id) : versionedJobId(article_id, runAtIso);
+  const jobId = useStableId
+    ? stableJobId(article_id)
+    : versionedJobId(article_id, runAtIso);
 
   const job = await articlePublishQueue.add(
-    'article:publish',
+    "article:publish",
     { article_id: String(article_id), runAtUtc: runAtIso, extra },
     { jobId, delay: delayMs }
   );
 
   if (DEBUG) {
-    console.info('[articlePublishQueue] upsert', {
+    console.info("[articlePublishQueue] upsert", {
       article_id: String(article_id),
       jobId,
       runAtIso,
@@ -161,4 +188,4 @@ module.exports = {
   stableJobId,
   versionedJobId,
   normalizeToUtcDate,
-};
+};

package/src/queue/eventPublishQueue.js

@@ -0,0 +1,187 @@
+// src/queue/eventPublishQueue.js
+// One-off *publish* scheduler for event items (BullMQ).
+// Strong upsert: purge any prior job for the same event before adding a new delayed job.
+
+const { Queue } = require("bullmq");
+const redisClient = require("../redis/redisClient");
+// const logger = require('../logger'); // uncomment if you have a shared logger
+
+const DEBUG = String(process.env.DEBUG_LOGGER || "").trim() === "1";
+const DRIFT_MS = Math.max(0, Number(process.env.SCHEDULE_DRIFT_MS || 250));
+
+const eventPublishQueue = new Queue("eventPublishQueue", {
+  connection: redisClient,
+  defaultJobOptions: {
+    attempts: 5,
+    backoff: { type: "exponential", delay: 2000 },
+    removeOnComplete: 500,
+    removeOnFail: 500,
+  },
+});
+
+// --- ID helpers --------------------------------------------------------------
+
+/** Replace invalid chars for BullMQ IDs */
+function sanitizeId(str) {
+  return str.replace(/[:.]/g, "-");
+}
+
+/** Stable id (latest schedule) */
+function stableJobId(event_id) {
+  return sanitizeId(`event:publish:${event_id}`);
+}
+
+/** Versioned id (keeps history distinct) */
+function versionedJobId(event_id, runAtIso) {
+  return sanitizeId(`event:publish:${event_id}:${runAtIso}`);
+}
+
+// --- Time helpers ------------------------------------------------------------
+
+/** Parse anything into a UTC Date. Strings without timezone are treated as UTC. */
+function normalizeToUtcDate(input) {
+  if (input instanceof Date) return new Date(input.getTime());
+  if (typeof input === "number") return new Date(input); // epoch ms
+
+  if (typeof input === "string") {
+    // Has timezone (Z or ±hh:mm)
+    if (/[zZ]|[+\-]\d{2}:\d{2}$/.test(input)) {
+      const d = new Date(input);
+      if (Number.isNaN(d.getTime()))
+        throw new Error(`Invalid ISO datetime: ${input}`);
+      return d;
+    }
+    // No timezone => treat as UTC
+    const s = input.trim().replace(" ", "T");
+    const d = new Date(`${s}Z`);
+    if (Number.isNaN(d.getTime()))
+      throw new Error(`Invalid datetime (no tz): ${input}`);
+    return d;
+  }
+
+  throw new Error(`Unsupported runAtUtc type: ${typeof input}`);
+}
+
+// --- Purge helpers -----------------------------------------------------------
+
+async function findPendingEventJobs(event_id) {
+  const states = ["delayed", "waiting", "waiting-children", "active"];
+  const jobs = await eventPublishQueue.getJobs(states);
+  return jobs.filter(
+    (j) => j?.name === "event:publish" && j?.data?.event_id === String(event_id)
+  );
+}
+
+async function purgeExistingForEvent(event_id) {
+  let removed = 0;
+
+  // Remove any pending/waiting/active jobs for this event
+  const pendings = await findPendingEventJobs(event_id);
+  for (const j of pendings) {
+    try {
+      await j.remove();
+      removed++;
+    } catch (e) {
+      if (DEBUG)
+        console.warn(
+          `[eventPublishQueue] failed to remove pending job ${j.id}: ${e.message}`
+        );
+    }
+  }
+
+  // Also remove a leftover stable job if present
+  const last = await eventPublishQueue.getJob(stableJobId(event_id));
+  if (last) {
+    try {
+      await last.remove();
+      removed++;
+    } catch (e) {
+      if (DEBUG)
+        console.warn(
+          `[eventPublishQueue] failed to remove stable job ${last.id}: ${e.message}`
+        );
+    }
+  }
+
+  if (DEBUG) {
+    console.info("[eventPublishQueue] purgeExistingForEvent", {
+      event_id: String(event_id),
+      removed,
+    });
+  }
+  return removed;
+}
+
+// --- Public API --------------------------------------------------------------
+
+/**
+ * Upsert a one-off publish job for an event.
+ * - Purges any previous jobs for this event
+ * - Uses a versioned jobId by default (or stable if useStableId=true)
+ *
+ * @param {Object} params
+ * @param {string|number} params.event_id
+ * @param {string|number|Date} params.runAtUtc - ISO string, epoch ms, or Date (UTC)
+ * @param {object} [params.extra]
+ * @param {boolean} [params.useStableId=false] - if true, uses stable jobId
+ */
+async function addEventPublishJob({
+  event_id,
+  runAtUtc,
+  extra = {},
+  useStableId = false,
+}) {
+  if (!event_id || !runAtUtc) {
+    throw new Error("addEventPublishJob: event_id and runAtUtc are required");
+  }
+
+  const runAt = normalizeToUtcDate(runAtUtc);
+  const runAtIso = runAt.toISOString();
+
+  // drift guard to avoid immediate fire due to ms skew
+  const now = Date.now();
+  let delayMs = runAt.getTime() - now;
+  if (delayMs < DRIFT_MS) delayMs = Math.max(0, DRIFT_MS);
+
+  // Purge any prior jobs for this event (across states)
+  await purgeExistingForEvent(event_id);
+
+  // Choose jobId strategy
+  const jobId = useStableId
+    ? stableJobId(event_id)
+    : versionedJobId(event_id, runAtIso);
+
+  const job = await eventPublishQueue.add(
+    "event:publish",
+    { event_id: String(event_id), runAtUtc: runAtIso, extra },
+    { jobId, delay: delayMs }
+  );
+
+  if (DEBUG) {
+    console.info("[eventPublishQueue] upsert", {
+      event_id: String(event_id),
+      jobId,
+      runAtIso,
+      delayMs,
+      nowIso: new Date(now).toISOString(),
+    });
+  }
+
+  return job;
+}
+
+/** Cancel any scheduled publish for a given event (if present). */
+async function cancelEventPublishJob(event_id) {
+  const removed = await purgeExistingForEvent(event_id);
+  return removed > 0;
+}
+
+module.exports = {
+  eventPublishQueue,
+  addEventPublishJob,
+  cancelEventPublishJob,
+  // exported helpers for tooling/tests
+  stableJobId,
+  versionedJobId,
+  normalizeToUtcDate,
+};

package/src/queue/imageAlbumPublishQueue.js

@@ -2,18 +2,18 @@
 // One-off *publish* scheduler for image album items (BullMQ).
 // Strong upsert: purge any prior job for the same album before adding a new delayed job.
 
-const { Queue } = require('bullmq');
-const redisClient = require('../redis/redisClient');
+const { Queue } = require("bullmq");
+const redisClient = require("../redis/redisClient");
 // const logger = require('../logger'); // uncomment if you have a shared logger
 
-const DEBUG    = String(process.env.DEBUG_LOGGER || '').trim() === '1';
+const DEBUG = String(process.env.DEBUG_LOGGER || "").trim() === "1";
 const DRIFT_MS = Math.max(0, Number(process.env.SCHEDULE_DRIFT_MS || 250));
 
-const imageAlbumPublishQueue = new Queue('imageAlbumPublishQueue', {
+const imageAlbumPublishQueue = new Queue("imageAlbumPublishQueue", {
   connection: redisClient,
   defaultJobOptions: {
     attempts: 5,
-    backoff: { type: 'exponential', delay: 2000 },
+    backoff: { type: "exponential", delay: 2000 },
     removeOnComplete: 500,
     removeOnFail: 500,
   },
@@ -21,11 +21,19 @@ const imageAlbumPublishQueue = new Queue('imageAlbumPublishQueue', {
 
 // ── ID helpers ────────────────────────────────────────────────────────────────
 
+/** Replace invalid chars for BullMQ IDs */
+function sanitizeId(str) {
+  return str.replace(/[:.]/g, "-");
+}
+
+/** Stable id (latest schedule) */
 function stableJobId(album_id) {
-  return `imageAlbum:publish:${album_id}`;
+  return sanitizeId(`imageAlbum:publish:${album_id}`);
 }
+
+/** Versioned id (keeps history distinct) */
 function versionedJobId(album_id, runAtIso) {
-  return `imageAlbum:publish:${album_id}:${runAtIso}`;
+  return sanitizeId(`imageAlbum:publish:${album_id}:${runAtIso}`);
 }
 
 // ── Time helpers ──────────────────────────────────────────────────────────────
@@ -33,19 +41,21 @@ function versionedJobId(album_id, runAtIso) {
 /** Parse anything into a UTC Date. Strings without timezone are treated as UTC. */
 function normalizeToUtcDate(input) {
   if (input instanceof Date) return new Date(input.getTime());
-  if (typeof input === 'number') return new Date(input); // epoch ms
+  if (typeof input === "number") return new Date(input); // epoch ms
 
-  if (typeof input === 'string') {
+  if (typeof input === "string") {
     // Has timezone (Z or ±hh:mm)
     if (/[zZ]|[+\-]\d{2}:\d{2}$/.test(input)) {
       const d = new Date(input);
-      if (Number.isNaN(d.getTime())) throw new Error(`Invalid ISO datetime: ${input}`);
+      if (Number.isNaN(d.getTime()))
+        throw new Error(`Invalid ISO datetime: ${input}`);
       return d;
     }
     // No timezone => treat as UTC
-    const s = input.trim().replace(' ', 'T');
+    const s = input.trim().replace(" ", "T");
     const d = new Date(`${s}Z`);
-    if (Number.isNaN(d.getTime())) throw new Error(`Invalid datetime (no tz): ${input}`);
+    if (Number.isNaN(d.getTime()))
+      throw new Error(`Invalid datetime (no tz): ${input}`);
     return d;
   }
 
@@ -55,10 +65,11 @@ function normalizeToUtcDate(input) {
 // ── Purge helpers ────────────────────────────────────────────────────────────
 
 async function findPendingAlbumJobs(album_id) {
-  const states = ['delayed', 'waiting', 'waiting-children', 'active'];
+  const states = ["delayed", "waiting", "waiting-children", "active"];
   const jobs = await imageAlbumPublishQueue.getJobs(states);
   return jobs.filter(
-    (j) => j?.name === 'imageAlbum:publish' && j?.data?.album_id === String(album_id)
+    (j) =>
+      j?.name === "imageAlbum:publish" && j?.data?.album_id === String(album_id)
   );
 }
 
@@ -72,7 +83,10 @@ async function purgeExistingForAlbum(album_id) {
       await j.remove();
       removed++;
     } catch (e) {
-      if (DEBUG) console.warn(`[imageAlbumPublishQueue] failed to remove pending job ${j.id}: ${e.message}`);
+      if (DEBUG)
+        console.warn(
+          `[imageAlbumPublishQueue] failed to remove pending job ${j.id}: ${e.message}`
+        );
     }
   }
 
@@ -83,12 +97,15 @@ async function purgeExistingForAlbum(album_id) {
       await last.remove();
       removed++;
     } catch (e) {
-      if (DEBUG) console.warn(`[imageAlbumPublishQueue] failed to remove stable job ${last.id}: ${e.message}`);
+      if (DEBUG)
+        console.warn(
+          `[imageAlbumPublishQueue] failed to remove stable job ${last.id}: ${e.message}`
+        );
     }
   }
 
   if (DEBUG) {
-    console.info('[imageAlbumPublishQueue] purgeExistingForAlbum', {
+    console.info("[imageAlbumPublishQueue] purgeExistingForAlbum", {
       album_id: String(album_id),
       removed,
     });
@@ -109,9 +126,16 @@ async function purgeExistingForAlbum(album_id) {
  * @param {object} [params.extra]
  * @param {boolean} [params.useStableId=false] - if true, uses stable jobId
  */
-async function addImageAlbumPublishJob({ album_id, runAtUtc, extra = {}, useStableId = false }) {
+async function addImageAlbumPublishJob({
+  album_id,
+  runAtUtc,
+  extra = {},
+  useStableId = false,
+}) {
   if (!album_id || !runAtUtc) {
-    throw new Error('addImageAlbumPublishJob: album_id and runAtUtc are required');
+    throw new Error(
+      "addImageAlbumPublishJob: album_id and runAtUtc are required"
+    );
   }
 
   const runAt = normalizeToUtcDate(runAtUtc);
@@ -126,16 +150,18 @@ async function addImageAlbumPublishJob({ album_id, runAtUtc, extra = {}, useStab
   await purgeExistingForAlbum(album_id);
 
   // Choose jobId strategy
-  const jobId = useStableId ? stableJobId(album_id) : versionedJobId(album_id, runAtIso);
+  const jobId = useStableId
+    ? stableJobId(album_id)
+    : versionedJobId(album_id, runAtIso);
 
   const job = await imageAlbumPublishQueue.add(
-    'imageAlbum:publish',
+    "imageAlbum:publish",
     { album_id: String(album_id), runAtUtc: runAtIso, extra },
     { jobId, delay: delayMs }
   );
 
   if (DEBUG) {
-    console.info('[imageAlbumPublishQueue] upsert', {
+    console.info("[imageAlbumPublishQueue] upsert", {
       album_id: String(album_id),
       jobId,
       runAtIso,
@@ -161,4 +187,4 @@ module.exports = {
   stableJobId,
   versionedJobId,
   normalizeToUtcDate,
-};
+};