@tryghost/adapter-base-scheduling 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013-2026 Ghost Foundation
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @tryghost/adapter-base-scheduling
+
+The adapter-base-scheduling package for Ghost.
+
+## Develop
+
+This is a workspace package in the Ghost monorepo. From the repo root:
+
+```bash
+pnpm --filter @tryghost/adapter-base-scheduling build   # compile to build/ with tsc (ESM)
+pnpm --filter @tryghost/adapter-base-scheduling test    # type-check + unit tests
+pnpm --filter @tryghost/adapter-base-scheduling dev     # rebuild on change
+```
+
+In-monorepo consumers resolve this package via the `source` export condition
+(raw `src/*.ts`, no build needed in dev/test). Production and any published
+tarball use the compiled `build/` output.
+
+This package is ESM-only and compiled with `tsc` (`module: nodenext`). Relative
+imports in `src/` must carry an explicit extension; write the real `.ts` one —
+`import {x} from './x.ts'` — and `tsc` rewrites it to `.js` on emit
+(`rewriteRelativeImportExtensions`).
+
+`ghost/core` is CommonJS but consumes this package via `require()`, which works
+on Ghost's Node version (22.13+/24) through Node's `require(esm)` support. That
+support has one hard constraint: **no top-level `await`** anywhere in this
+package's module graph — it makes the graph async and `require()` of it throws
+`ERR_REQUIRE_ASYNC_MODULE`. Keep module-level initialization synchronous. (An
+ESLint rule enforces this.)

package/build/base.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shape of a job the scheduler adapter queues. Time is a unix timestamp;
+ * url carries a JWT-signed admin token; extra forwards through to the
+ * HTTP callback the adapter fires.
+ */
+export interface SchedulerJob {
+    time: number;
+    url: string;
+    extra: {
+        httpMethod: string;
+        oldTime?: number | null;
+    };
+}
+/**
+ * Options passed to `rescheduleAll` by the adapter when it calls the method on
+ * each registered rescheduler. The previous key is provided so that the
+ * rescheduler can unschedule any jobs that were queued under the old key.
+ */
+export interface RescheduleOpts {
+    previousKey?: {
+        id: string;
+        secret: string;
+    };
+}
+/**
+ * Implemented by scheduler-using subsystems (post-scheduling, automations,
+ * gift reminders). The adapter calls `rescheduleAll` on every registered
+ * rescheduler when something requires the queue to be rebuilt — currently
+ * after an internal API key rotation.
+ */
+export interface Rescheduler {
+    rescheduleAll(opts?: RescheduleOpts): Promise<void>;
+}
+/**
+ * The contract Ghost expects of any concrete scheduling adapter. Adapters
+ * that extend `SchedulingBase` inherit `register` and `rescheduleAll` for
+ * free; the three runtime methods (`schedule`, `unschedule`, `run`) are
+ * the ones each adapter implementation must provide.
+ */
+export interface SchedulerAdapter {
+    run(): void | Promise<void>;
+    schedule(job: SchedulerJob): void | Promise<void>;
+    unschedule(job: SchedulerJob, opts?: {
+        bootstrap?: boolean;
+    }): void | Promise<void>;
+    register(rescheduler: Rescheduler): void;
+}
+export declare abstract class SchedulingBase implements SchedulerAdapter {
+    #private;
+    readonly requiredFns: readonly ['run', 'schedule', 'unschedule'];
+    constructor();
+    register(rescheduler: Rescheduler): void;
+    /**
+     * Ask every registered rescheduler to rebuild its queue under the current
+     * key. Best-effort: a failure in one doesn't block the others.
+     */
+    rescheduleAll(opts?: RescheduleOpts): Promise<PromiseSettledResult<void>[]>;
+    abstract run(): void | Promise<void>;
+    abstract schedule(job: SchedulerJob): void | Promise<void>;
+    abstract unschedule(job: SchedulerJob, opts?: {
+        bootstrap?: boolean;
+    }): void | Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/build/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE;QACH,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC;CACL;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,WAAW,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,aAAa,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,GAAG,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5C;AAED,8BAAsB,cAAe,YAAW,gBAAgB;;IAC5D,SAAiB,WAAW,EAAE,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;IAIzE,cAKC;IAED,QAAQ,CAAC,WAAW,EAAE,WAAW,QAEhC;IAED;;;OAGG;IACG,aAAa,CAAC,IAAI,CAAC,EAAE,cAAc,yCAiBxC;IAED,QAAQ,CAAC,GAAG,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1D,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7F"}

package/build/base.js

@@ -0,0 +1,32 @@
+import logging from '@tryghost/logging';
+export class SchedulingBase {
+    #reschedulers = new Set();
+    constructor() {
+        Object.defineProperty(this, 'requiredFns', {
+            value: Object.freeze(['run', 'schedule', 'unschedule']),
+            writable: false,
+        });
+    }
+    register(rescheduler) {
+        this.#reschedulers.add(rescheduler);
+    }
+    /**
+     * Ask every registered rescheduler to rebuild its queue under the current
+     * key. Best-effort: a failure in one doesn't block the others.
+     */
+    async rescheduleAll(opts) {
+        const reschedulers = Array.from(this.#reschedulers);
+        const results = await Promise.allSettled(reschedulers.map(r => r.rescheduleAll(opts)));
+        results.forEach((result, i) => {
+            if (result.status === 'rejected') {
+                logging.error({
+                    event: { name: 'scheduler.reschedule_all.failed' },
+                    err: result.reason,
+                    rescheduler: reschedulers[i].constructor?.name || 'unknown'
+                }, 'Rescheduler failed');
+            }
+        });
+        return results;
+    }
+}
+//# sourceMappingURL=base.js.map

package/build/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,mBAAmB,CAAC;AAiDxC,MAAM,OAAgB,cAAc;IAGhC,aAAa,GAAG,IAAI,GAAG,EAAe,CAAC;IAEvC;QACI,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE;YACvC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;YACvD,QAAQ,EAAE,KAAK;SAClB,CAAC,CAAA;IACN,CAAC;IAED,QAAQ,CAAC,WAAwB;QAC7B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CAAC,IAAqB;QACrC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACpC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAC/C,CAAC;QAEF,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;YAC1B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC/B,OAAO,CAAC,KAAK,CAAC;oBACV,KAAK,EAAE,EAAC,IAAI,EAAE,iCAAiC,EAAC;oBAChD,GAAG,EAAE,MAAM,CAAC,MAAM;oBAClB,WAAW,EAAE,YAAY,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,IAAI,IAAI,SAAS;iBAC/D,EAAE,oBAAoB,CAAC,CAAC;YAC7B,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC;IACnB,CAAC;CAKJ"}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./base.ts";
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/build/index.js

@@ -0,0 +1,2 @@
+export * from "./base.js";
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@tryghost/adapter-base-scheduling",
+  "version": "0.1.0",
+  "description": "The adapter-base-scheduling package for Ghost.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TryGhost/Ghost.git",
+    "directory": "packages/adapters/scheduling-base"
+  },
+  "author": "Ghost Foundation",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    }
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "files": [
+    "build"
+  ],
+  "dependencies": {
+    "@tryghost/logging": "4.2.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test:unit": "NODE_ENV=testing vitest run --coverage",
+    "test": "pnpm run '/^test:/'",
+    "test:types": "tsc --noEmit -p test/tsconfig.json",
+    "lint:code": "eslint src/ --cache",
+    "lint:test": "eslint test/ --cache",
+    "lint": "pnpm run '/^lint:/'"
+  }
+}