Changed gift-links service to split CQRS queries and commands

Separated the gift-links read path (GiftLinkQueries) from the write path
(GiftLinkCommands) so reads and mutations no longer share one class, and
extracted action recording and the row codec into their own modules. The
entry controller now resolves tokens through queries directly, keeping the
read seam free of command/action dependencies.

Author: rob-ghost

ghost/core/core/frontend/services/proxy.js

@@ -70,8 +70,8 @@ module.exports = {
 
     // Labs utils for enabling/disabling helpers
     labs: require('../../shared/labs'),
-    // Gift links service — reached through this seam so the entry controller
-    // doesn't require a server module directly.
+    // Reached through this seam so the entry controller doesn't require a server
+    // module directly.
     giftLinks: require('../../server/services/gift-links'),
     // Paid-member shim for gift-link reads (shared with previews). Lazy getter so
     // the members service resolves at call time, avoiding boot-time require-order

ghost/core/core/frontend/services/routing/controllers/entry/gift-links.ts

@@ -20,9 +20,8 @@ function strippedGiftUrl(req: Request): string {
 }
 
 /**
- * Flag the render as a gift view so `ghost_foot` injects the toast. Stores the
- * token (not just a boolean) for a later analytics pass-through. Internal flag,
- * not a public theme API.
+ * Flag the render as a gift view so `ghost_foot` injects the toast. Internal
+ * flag, not a public theme API.
  */
 function setGiftTemplateFlag(res: EntryResponse, token: string): void {
     const localTemplateOptions = hbs.getLocalTemplateOptions(res.locals);
@@ -80,7 +79,7 @@ async function renderUnlocked(req: Request, res: EntryResponse, token: string) {
 export async function serveGiftRequest(req: Request, res: EntryResponse, entry: Entry) {
     const token = giftToken(req);
 
-    if (token && await proxy.giftLinks.service.isValidTokenForPost(token, entry.id)) {
+    if (token && await proxy.giftLinks.queries.isValidTokenForPost(token, entry.id)) {
         return renderUnlocked(req, res, token);
     }
 

ghost/core/core/server/api/endpoints/gift-links.ts

@@ -1,4 +1,4 @@
-import {service, type RequestContext} from '../../services/gift-links';
+import {queries, commands, type RequestContext} from '../../services/gift-links';
 
 const permissionsService = require('../../services/permissions');
 
@@ -40,7 +40,7 @@ const controller = {
             return assertCanEditAndGift(frame);
         },
         query(frame: Frame) {
-            return service!.getPost(frame.options.id);
+            return queries!.getPost(frame.options.id);
         }
     },
 
@@ -53,7 +53,7 @@ const controller = {
             return assertCanEditAndGift(frame);
         },
         query(frame: Frame) {
-            return service!.ensure(requestContextFromFrame(frame), frame.options.id);
+            return commands!.ensure(requestContextFromFrame(frame), frame.options.id);
         }
     },
 
@@ -66,7 +66,7 @@ const controller = {
             return assertCanEditAndGift(frame);
         },
         query(frame: Frame) {
-            return service!.create(requestContextFromFrame(frame), frame.options.id);
+            return commands!.create(requestContextFromFrame(frame), frame.options.id);
         }
     },
 
@@ -77,7 +77,7 @@ const controller = {
             return permissionsService.canThis(frame.options.context).removeAll.gift_link();
         },
         async query(frame: Frame) {
-            const count = await service!.removeAll(requestContextFromFrame(frame));
+            const count = await commands!.removeAll(requestContextFromFrame(frame));
             return {count};
         }
     }

ghost/core/core/server/api/endpoints/utils/serializers/output/gift-links.ts

@@ -9,8 +9,7 @@ const serializeGiftLinks = (post: Post, _apiConfig: unknown, frame: Frame): void
     frame.response = toGiftLinksResponse.parse(post.giftLinks);
 };
 
-// module.exports (not export): the API framework loads serializers via require(). The endpoint ->
-// serializer mapping lives here; the response shaping lives with the gift-links service module.
+// module.exports (not export): the API framework loads serializers via require().
 module.exports = {
     browse: serializeGiftLinks,
     ensure: serializeGiftLinks,

ghost/core/core/server/services/gift-links/actions.ts

@@ -0,0 +1,51 @@
+import logging from '@tryghost/logging';
+
+export interface Actor {
+    id: string;
+    type: 'user' | 'integration';
+}
+
+export interface RequestContext {
+    actor: Actor | null;
+}
+
+export interface ActionRecorder {
+    add(data: Record<string, unknown>, options: {autoRefresh: boolean}): Promise<unknown>;
+}
+
+// The history UI only surfaces a verb-specific label (action_name) for 'edited' events; 'added' and
+// 'deleted' render as the bare event. So 'reset' maps to 'edited' to read as "reset", while
+// 'add'/'remove' read as plain "added"/"deleted".
+const COMMANDS = {
+    add: 'added',
+    reset: 'edited',
+    remove: 'deleted'
+} as const satisfies Record<string, 'added' | 'edited' | 'deleted'>;
+
+export type GiftLinkVerb = keyof typeof COMMANDS;
+
+export type RecordGiftLinkAction =
+    (input: {context: RequestContext; verb: GiftLinkVerb; subject: string | null}) => Promise<void>;
+
+// Best-effort action-log write: a failed action must never fail the command that triggered it.
+export async function recordGiftLinkAction(
+    {Action, context, verb, subject}:
+    {Action: ActionRecorder; context: RequestContext; verb: GiftLinkVerb; subject: string | null}
+): Promise<void> {
+    if (!context.actor) {
+        return;
+    }
+    const event = COMMANDS[verb];
+    try {
+        await Action.add({
+            event,
+            resource_type: 'gift_link',
+            resource_id: subject,
+            actor_type: context.actor.type,
+            actor_id: context.actor.id,
+            ...(event === 'edited' ? {context: {action_name: verb}} : {})
+        }, {autoRefresh: false});
+    } catch (err) {
+        logging.error(err);
+    }
+}

ghost/core/core/server/services/gift-links/codec.ts

@@ -0,0 +1,16 @@
+import {z} from 'zod';
+import {camelKeys, snakeKeys} from './case-keys';
+import {DbGiftLink} from './schema';
+import {GiftLink} from './models';
+
+export const GiftLinkRow = DbGiftLink.pick({
+    token: true,
+    created_at: true
+});
+
+export const giftLinkCodec = z.codec(GiftLinkRow, GiftLink, {
+    decode: row => camelKeys(row),
+    encode: link => snakeKeys(link)
+});
+
+export const giftLinkColumns = Object.keys(GiftLinkRow.shape).map(column => `gift_links.${column}`);

ghost/core/core/server/services/gift-links/commands.ts

@@ -0,0 +1,57 @@
+import {z} from 'zod';
+import type {Knex} from 'knex';
+import {giftLinkCodec} from './codec';
+import {generateGiftLinkToken, type GiftLink, type Post} from './models';
+import {type GiftLinkQueries} from './queries';
+import {type RecordGiftLinkAction, type RequestContext} from './actions';
+
+export class GiftLinkCommands {
+    private knex: Knex;
+    private queries: GiftLinkQueries;
+    private recordAction: RecordGiftLinkAction;
+
+    constructor({knex, queries, recordAction}: {knex: Knex; queries: GiftLinkQueries; recordAction: RecordGiftLinkAction}) {
+        this.knex = knex;
+        this.queries = queries;
+        this.recordAction = recordAction;
+    }
+
+    async ensure(context: RequestContext, postId: string): Promise<Post> {
+        const post = await this.queries.getPost(postId);
+        if (post.giftLinks.length) {
+            return post;
+        }
+        const minted = await this.mint(postId);
+        await this.recordAction({context, verb: 'add', subject: postId});
+        return minted;
+    }
+
+    async create(context: RequestContext, postId: string): Promise<Post> {
+        await this.queries.getPost(postId); // asserts the post exists (throws NotFound)
+        const minted = await this.mint(postId);
+        await this.recordAction({context, verb: 'reset', subject: postId});
+        return minted;
+    }
+
+    // gift_links rows are kept as history; only the live association is removed.
+    async removeAll(context: RequestContext): Promise<number> {
+        const removed = await this.knex('post_gift_links').del();
+        if (removed > 0) {
+            await this.recordAction({context, verb: 'remove', subject: null});
+        }
+        return removed;
+    }
+
+    private async mint(postId: string): Promise<Post> {
+        const now = new Date();
+        const link: GiftLink = {token: generateGiftLinkToken(), createdAt: now};
+        await this.knex.transaction(async (trx) => {
+            await trx('gift_links').insert({...z.encode(giftLinkCodec, link), post_id: postId});
+            await trx('post_gift_links')
+                .insert({post_id: postId, gift_link_token: link.token, created_at: now})
+                .onConflict('post_id')
+                .merge({gift_link_token: link.token, updated_at: now});
+        });
+        return {id: postId, giftLinks: [link]};
+    }
+}

ghost/core/core/server/services/gift-links/index.ts

@@ -1,17 +1,23 @@
-import {GiftLinksService} from './service';
+import {GiftLinkQueries} from './queries';
+import {GiftLinkCommands} from './commands';
+import {recordGiftLinkAction, type RecordGiftLinkAction} from './actions';
 
-export type {RequestContext} from './service';
+export type {RequestContext} from './actions';
 
-// Set by init() at boot, not at import: knex only exists once the DB has connected.
-export let service: GiftLinksService | undefined;
+// Constructed by init() at boot, not at import: knex is only available once the DB has connected.
+export let queries: GiftLinkQueries | undefined;
+export let commands: GiftLinkCommands | undefined;
 
 export function init(): void {
-    if (service) {
+    if (queries && commands) {
         return;
     }
 
     const {knex} = require('../../data/db');
     const models = require('../../models');
 
-    service = new GiftLinksService({knex, Action: models.Action});
+    queries = new GiftLinkQueries({knex});
+    const recordAction: RecordGiftLinkAction = ({context, verb, subject}) =>
+        recordGiftLinkAction({Action: models.Action, context, verb, subject});
+    commands = new GiftLinkCommands({knex, queries, recordAction});
 }

ghost/core/core/server/services/gift-links/models.ts

@@ -1,15 +1,21 @@
+import crypto from 'crypto';
 import {z} from 'zod';
 
 export const GiftLinkToken = z.string().brand('GiftLinkToken');
 export type GiftLinkToken = z.infer<typeof GiftLinkToken>;
 
+// 24 random bytes (192 bits of entropy); base64url keeps it URL-safe.
+export function generateGiftLinkToken(): GiftLinkToken {
+    return GiftLinkToken.parse(crypto.randomBytes(24).toString('base64url'));
+}
+
 export const GiftLink = z.object({
     token: GiftLinkToken,
     createdAt: z.date()
 });
 export type GiftLink = z.infer<typeof GiftLink>;
 
-/** The gift-links aggregate of a post and its live links; distinct from the Bookshelf Post model. */
+/** A post and its live gift links — distinct from the Bookshelf Post model. */
 export interface Post {
     id: string;
     giftLinks: GiftLink[];

ghost/core/core/server/services/gift-links/queries.ts

@@ -1,44 +1,50 @@
 import {z} from 'zod';
+import errors from '@tryghost/errors';
 import type {Knex} from 'knex';
-import {camelKeys, snakeKeys} from './case-keys';
-import {DbGiftLink} from './database';
-import {GiftLink} from './models';
-
-// The columns the read path selects and the codec decodes into a GiftLink.
-export const GiftLinkRow = DbGiftLink.pick({
-    token: true,
-    created_at: true
-});
-
-// Maps a selected row to/from the domain GiftLink (snake_case to camelCase, token branding).
-export const giftLinkCodec = z.codec(GiftLinkRow, GiftLink, {
-    decode: row => camelKeys(row),
-    encode: link => snakeKeys(link)
-});
-
-const giftLinkColumns = Object.keys(GiftLinkRow.shape).map(column => `gift_links.${column}`);
-
-// Executor-agnostic statements for the read shapes (joins, filters, columns): each is
-// parameterised by domain args and takes the connection at execution, so the service binds
-// knex (or a trx). The result generic names the row the codec expects, since knex can't infer
-// a dynamic column list.
-// Anchored on posts: zero rows means the post does not exist; a single all-null row means the
-// post exists with no live link (hence the nullable columns).
+import {GiftLinkRow, giftLinkCodec, giftLinkColumns} from './codec';
+import {type Post} from './models';
+
+// The LEFT JOIN leaves every link column nullable; the explicit generic names a row shape knex
+// can't infer from a dynamic column list.
 type LiveLinkRow = {[K in keyof z.input<typeof GiftLinkRow>]: z.input<typeof GiftLinkRow>[K] | null};
 
-// LEFT JOINs from posts: a missing post yields zero rows, while a post with no live link yields one
-// row with null link columns. So zero rows means "no such post".
-export function liveLinksForPost(postId: string) {
-    return (knex: Knex) => knex('posts')
-        .where('posts.id', postId)
-        .leftJoin('post_gift_links', 'post_gift_links.post_id', 'posts.id')
-        .leftJoin('gift_links', 'gift_links.token', 'post_gift_links.gift_link_token')
-        .select<LiveLinkRow[]>(giftLinkColumns);
-}
+export class GiftLinkQueries {
+    private knex: Knex;
+
+    constructor({knex}: {knex: Knex}) {
+        this.knex = knex;
+    }
+
+    async getPost(postId: string): Promise<Post> {
+        // Anchored on posts: zero rows means the post itself doesn't exist, not merely that it has
+        // no live link.
+        const rows = await this.knex('posts')
+            .where('posts.id', postId)
+            .leftJoin('post_gift_links', 'post_gift_links.post_id', 'posts.id')
+            .leftJoin('gift_links', 'gift_links.token', 'post_gift_links.gift_link_token')
+            .select<LiveLinkRow[]>(giftLinkColumns);
+
+        if (rows.length === 0) {
+            throw new errors.NotFoundError({message: `Post ${postId} does not exist.`});
+        }
+
+        const giftLinks = rows
+            .filter((row): row is z.input<typeof GiftLinkRow> => row.token !== null)
+            .map(row => z.decode(giftLinkCodec, row));
+        return {id: postId, giftLinks};
+    }
+
+    async getPostByToken(token: string): Promise<Post | null> {
+        const row = await this.knex('post_gift_links')
+            .join('gift_links', 'gift_links.token', 'post_gift_links.gift_link_token')
+            .where('gift_links.token', token)
+            .first<z.input<typeof GiftLinkRow> & {post_id: string}>(
+                [...giftLinkColumns, 'post_gift_links.post_id as post_id']
+            );
+        return row ? {id: row.post_id, giftLinks: [z.decode(giftLinkCodec, row)]} : null;
+    }
 
-export function liveLinkForToken(token: string) {
-    return (knex: Knex) => knex('post_gift_links')
-        .join('gift_links', 'gift_links.token', 'post_gift_links.gift_link_token')
-        .where('gift_links.token', token)
-        .first<z.input<typeof GiftLinkRow> & {post_id: string}>([...giftLinkColumns, 'post_gift_links.post_id as post_id']);
+    async isValidTokenForPost(token: string, postId: string): Promise<boolean> {
+        return (await this.getPostByToken(token))?.id === postId;
+    }
 }