Updated docs for public adapter base packages

.changeset/major-areas-fail.md

@@ -0,0 +1,8 @@
+---
+"@tryghost/adapter-base-cache": patch
+"@tryghost/adapter-base-scheduling": patch
+"@tryghost/adapter-base-sso": patch
+"ghost-storage-base": patch
+---
+
+Updated README documentation

packages/adapters/cache-base/README.md

@@ -1,9 +1,71 @@
 # @tryghost/adapter-base-cache
 
-Base class for Ghost cache adapters.
+Base class for Ghost cache adapters. A cache adapter backs one of Ghost's
+internal caches (settings, image sizes, gscan results, ...) with a store of
+your choice — an in-process map, Redis, Memcached, etc.
 
-Concrete adapters extend `CacheBase` and implement the methods listed in
-`requiredFns`: `get`, `set`, `reset`, and `keys`.
+See the [Ghost adapters documentation](https://docs.ghost.org/config#adapters)
+for how adapters are configured and loaded.
+
+## Usage
+
+Install the base class alongside your adapter:
+
+```bash
+npm install @tryghost/adapter-base-cache
+```
+
+Extend `CacheBase` and implement every method listed in `requiredFns`:
+`get`, `set`, `reset`, and `keys`. Each may be synchronous or return a
+`Promise`.
+
+```js
+const {CacheBase} = require('@tryghost/adapter-base-cache');
+
+class MyCache extends CacheBase {
+    constructor(config) {
+        super();
+        // `config` is the settings block from your Ghost config (see below)
+        this.store = new Map();
+    }
+
+    get(key) {
+        return this.store.get(key);
+    }
+
+    set(key, value) {
+        this.store.set(key, value);
+    }
+
+    reset() {
+        this.store.clear();
+    }
+
+    // Deprecated — may be removed in a future version. Returns all cache keys.
+    keys() {
+        return [...this.store.keys()];
+    }
+}
+
+module.exports = MyCache;
+```
+
+### Installing and activating
+
+Place the adapter at `content/adapters/cache/MyCache/index.js` and activate it
+in your Ghost config. `active` names the adapter; the matching block is passed
+to its constructor:
+
+```json
+{
+    "adapters": {
+        "cache": {
+            "active": "MyCache",
+            "MyCache": {}
+        }
+    }
+}
+```
 
 ## Develop
 
@@ -14,18 +76,11 @@ pnpm --filter @tryghost/adapter-base-cache build   # compile to build/ with tsc
 pnpm --filter @tryghost/adapter-base-cache test    # type-check + unit tests
 ```
 
-In-monorepo consumers resolve this package via the `source` export condition
-(raw `src/*.ts`, no build needed in dev/test). Production, and the tarball
-published to npm for external adapter authors, 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.)
+# Copyright & License
+
+Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](LICENSE). Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our [trademark policy](https://ghost.org/trademark/) for info on acceptable usage.

packages/adapters/scheduling-base/README.md

@@ -1,6 +1,65 @@
 # @tryghost/adapter-base-scheduling
 
-The adapter-base-scheduling package for Ghost.
+Base class for Ghost scheduling adapters. A scheduling adapter is responsible
+for firing Ghost's time-based jobs — publishing scheduled posts, sending
+scheduled newsletters, automations, gift reminders — by calling back into
+Ghost's API at the requested time.
+
+See the [Ghost adapters documentation](https://docs.ghost.org/config#adapters)
+for how adapters are configured and loaded.
+
+## Usage
+
+Install the base class alongside your adapter:
+
+```bash
+npm install @tryghost/adapter-base-scheduling
+```
+
+Extend `SchedulingBase` and implement every method listed in `requiredFns`:
+`run`, `schedule`, and `unschedule`. `register` and `rescheduleAll` are
+inherited from the base class.
+
+Each job has a `time` (unix timestamp), a `url` to call back (carrying a
+JWT-signed admin token), and an `extra` object holding the `httpMethod` to use.
+At `time`, the adapter fires the HTTP request described by the job.
+
+```js
+const {SchedulingBase} = require('@tryghost/adapter-base-scheduling');
+
+class MyScheduler extends SchedulingBase {
+    constructor(options) {
+        super();
+        // `options` is the settings block from your Ghost config
+    }
+
+    // Called on boot. Fire any jobs whose time has already passed and start
+    // watching for upcoming ones.
+    run() { /* ... */ }
+
+    // Queue `job` to fire at job.time via job.extra.httpMethod against job.url.
+    schedule(job) { /* ... */ }
+
+    // Remove a previously-scheduled job.
+    unschedule(job, options) { /* ... */ }
+}
+
+module.exports = MyScheduler;
+```
+
+### Installing and activating
+
+Place the adapter at `content/adapters/scheduling/MyScheduler/index.js` and
+activate it in your Ghost config:
+
+```json
+{
+    "scheduling": {
+        "active": "MyScheduler",
+        "MyScheduler": {}
+    }
+}
+```
 
 ## Develop
 
@@ -12,18 +71,11 @@ pnpm --filter @tryghost/adapter-base-scheduling test    # type-check + unit test
 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.)
+# Copyright & License
+
+Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](LICENSE). Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our [trademark policy](https://ghost.org/trademark/) for info on acceptable usage.

packages/adapters/sso-base/README.md

@@ -1,6 +1,69 @@
 # @tryghost/adapter-base-sso
 
-The adapter-base-sso package for Ghost.
+Base class for Ghost SSO adapters. An SSO adapter lets an external identity
+provider sign users in to Ghost admin: it reads credentials off the incoming
+request, resolves them to an identity, and maps that identity to a Ghost user.
+
+See the [Ghost adapters documentation](https://docs.ghost.org/config#adapters)
+for how adapters are configured and loaded.
+
+## Usage
+
+Install the base class alongside your adapter:
+
+```bash
+npm install @tryghost/adapter-base-sso
+```
+
+Extend `SSOBase` and implement every method listed in `requiredFns`:
+
+- `getRequestCredentials(request)` — pull the credentials (token, cookie, ...)
+  off the incoming Express request, or return `null` if none are present.
+- `getIdentityFromCredentials(credentials)` — validate the credentials and
+  resolve them to an identity, or `null`.
+- `getUserForIdentity(identity)` — map the identity to a Ghost user, or `null`.
+
+Ghost injects a user repository after constructing the adapter, exposed through
+the protected `getUserByEmail(email)` and `getOwnerUser()` helpers — use these
+to resolve Ghost users without reaching into Ghost's model layer directly.
+
+```js
+const {SSOBase} = require('@tryghost/adapter-base-sso');
+
+class MySSO extends SSOBase {
+    async getRequestCredentials(request) {
+        const token = request.get('authorization');
+        return token ?? null;
+    }
+
+    async getIdentityFromCredentials(token) {
+        return this.verify(token); // your validation → identity, or null
+    }
+
+    async getUserForIdentity(identity) {
+        // `getUserByEmail` is provided by the base class
+        return this.getUserByEmail(identity.email);
+    }
+}
+
+module.exports = MySSO;
+```
+
+### Installing and activating
+
+Place the adapter at `content/adapters/sso/MySSO/index.js` and activate it in
+your Ghost config:
+
+```json
+{
+    "adapters": {
+        "sso": {
+            "active": "MySSO",
+            "MySSO": {}
+        }
+    }
+}
+```
 
 ## Develop
 
@@ -12,18 +75,11 @@ pnpm --filter @tryghost/adapter-base-sso test    # type-check + unit tests
 pnpm --filter @tryghost/adapter-base-sso 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.)
+# Copyright & License
+
+Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](LICENSE). Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our [trademark policy](https://ghost.org/trademark/) for info on acceptable usage.