ghost 6.55.0 → 6.57.0

package/core/server/services/members/import-export/import/importer.ts

@@ -82,7 +82,7 @@ interface StripeSubscriptions {
 
 // Gifts: reassigning a redeemed gift to the imported member.
 export interface GiftService {
-    reassignRedeemer(giftId: string, memberId: string, options: object): Promise<void>;
+    reassignRedeemer(giftId: string, memberId: string, options: {transacting?: Knex.Transaction}): Promise<void>;
 }
 
 // The completion email concern: who it goes to, the links it carries, and sending
@@ -99,7 +99,7 @@ type CustomFieldPlan = unknown;
 // The custom fields collaborator as the import needs it. activeFields is the field set a
 // custom_fields.* column is read against, empty when the feature is off; planWrite
 // validates a row's values (throwing so the row fails whole) and applyWrite persists
-// them, both on the row's transaction.
+// them, touching only the parts the row named, both on the row's transaction.
 export interface CustomFieldsImport {
     activeFields(): Promise<CsvField[]>;
     planWrite(values: Record<string, unknown>): Promise<CustomFieldPlan[]>;
@@ -332,7 +332,7 @@ class MembersCSVImporter {
                 // before any member write -- so there is no reason to hold a transaction
                 // across it, and doing so would deadlock the single-connection SQLite pool.
                 const customFieldPlan = activeCustomFields.length > 0
-                    ? await this._customFields.planWrite(fieldValuesFromCsvRow(activeCustomFields, row, stripFormulaGuard))
+                    ? await namingTheColumn(() => this._customFields.planWrite(fieldValuesFromCsvRow(activeCustomFields, row, stripFormulaGuard)))
                     : [];
 
                 trx = await this._knex.transaction(undefined, {doNotRejectOnRollback: false});
@@ -432,15 +432,16 @@ class MembersCSVImporter {
                 imported += 1;
             } catch (error) {
                 const errorList: unknown[] = Array.isArray(error) ? error : [error];
-                const errorMessage = errorList
+                const reasons = errorList
                     .map(e => (typeof e === 'object' && e !== null && 'message' in e ? e.message : undefined))
-                    .join(', ');
+                    .filter((message): message is string => typeof message === 'string');
+                const errorMessage = reasons.join('\n');
                 // trx is unset if the row failed before the transaction opened (a bad
                 // custom field value or gift combination).
                 if (trx) {
                     await trx.rollback();
                 }
-                importErrors.push({...row, error: errorMessage});
+                importErrors.push({...row, error: errorMessage, errors: reasons});
             }
         }
 
@@ -457,6 +458,26 @@ class MembersCSVImporter {
     }
 }
 
+// A row error is read next to a spreadsheet, and a value rejection states only what the
+// value should be — the same sentence Admin shows under a single input, where the field is
+// already on screen. `property` is the dotted path a default export writes as its column
+// header, so prefixing with it names the column a publisher has to go and fix.
+//
+// A rejection about the whole request carries the bare namespace and names no field after
+// it, so it is left alone rather than made to point at a column that does not exist.
+async function namingTheColumn<T>(plan: () => Promise<T>): Promise<T> {
+    try {
+        return await plan();
+    } catch (error) {
+        const {property, message} = (error ?? {}) as {property?: unknown; message?: unknown};
+        const namesAField = typeof property === 'string' && property.includes('.');
+        if (!namesAField || typeof message !== 'string') {
+            throw error;
+        }
+        throw new errors.DataImportError({message: `${property}: ${message}`});
+    }
+}
+
 function wrapGiftError(error: unknown) {
     const err = error as {message?: unknown};
     const message = (err && typeof err.message === 'string' && err.message) || tpl(messages.giftReassignFailed);

package/core/server/services/members/import-export/import/row.ts

@@ -42,7 +42,11 @@ export type MemberImportRow = z.infer<typeof memberImportRowSchema>;
 
 // A row that failed to import, carrying the raw message that stopped it. The message is
 // left raw here; turning it into human copy is a presentation concern.
-export type ImportErrorRow = MemberImportRow & {error: string};
+// A row can fail for more than one reason. `errors` is the list; `error` is that list
+// written out for the error report's single cell. Two fields because a reason may quote a
+// cell the publisher wrote, and a CSV cell legally holds commas and newlines, so no
+// separator survives being split back apart.
+export type ImportErrorRow = MemberImportRow & {error: string; errors: string[]};
 
 // The persisted import label as plain data -- taken off the Bookshelf model before it
 // leaves the kernel, so the result and the email carry only what they show.

package/core/server/services/members/import-export/index.js

@@ -40,7 +40,11 @@ function makeImporter(deps) {
     // Gifts is initialised at boot and always present at request time; the getter
     // resolves it lazily so the ready service is picked up whenever a row uses it.
     const gifts = {
-        reassignRedeemer: (giftId, memberId, options) => deps.getGiftService().reassignRedeemer(giftId, memberId, options)
+        reassignRedeemer: (giftId, memberId, options) => deps.getGiftService().reassignRedeemer({
+            giftId,
+            memberId,
+            transacting: options.transacting
+        })
     };
     // Gated by the same labs flag as the export, so the two halves round-trip or stay
     // silent together: off, activeFields resolves empty and every custom_fields.* column
@@ -48,7 +52,7 @@ function makeImporter(deps) {
     const customFields = {
         activeFields: async () => (labs.isSet('membersCustomFields') ? deps.customFields.definitions.browse() : []),
         planWrite: values => deps.customFields.values.planWrite(values),
-        applyWrite: (memberId, plan, executor) => deps.customFields.values.applyWrite(memberId, plan, executor)
+        applyWrite: (memberId, plan, executor) => deps.customFields.values.applyWrite(memberId, plan, { executor })
     };
     return new importer_1.default({
         knex: deps.knex,

package/core/server/services/members/import-export/index.ts

@@ -18,7 +18,9 @@ interface ImporterServices {
     getMembersRepository(): Promise<Omit<MembersRepository, 'getImportLabel'>>;
     getDefaultTier(): Promise<Tier>;
     getTierByName(name: string): Promise<Tier | null>;
-    getGiftService(): GiftService;
+    getGiftService(): {
+        reassignRedeemer(input: {giftId: string; memberId: string; transacting?: Knex.Transaction}): Promise<void>;
+    };
     sendEmail: EmailNotifications['send'];
     urlFor: EmailNotifications['urlFor'];
     addJob(job: {job: () => Promise<void>; offloaded: boolean; name: string}): void;
@@ -31,7 +33,7 @@ interface ImporterServices {
         definitions: {browse(): Promise<CsvField[]>};
         values: {
             planWrite(values: Record<string, unknown>): Promise<unknown[]>;
-            applyWrite(memberId: string, plan: unknown[], executor: Knex): Promise<void>;
+            applyWrite(memberId: string, plan: unknown[], options?: {executor?: Knex}): Promise<void>;
         };
     };
 }
@@ -72,7 +74,11 @@ export function makeImporter(deps: ImporterServices) {
     // Gifts is initialised at boot and always present at request time; the getter
     // resolves it lazily so the ready service is picked up whenever a row uses it.
     const gifts: GiftService = {
-        reassignRedeemer: (giftId, memberId, options) => deps.getGiftService().reassignRedeemer(giftId, memberId, options)
+        reassignRedeemer: (giftId, memberId, options) => deps.getGiftService().reassignRedeemer({
+            giftId,
+            memberId,
+            transacting: options.transacting
+        })
     };
 
     // Gated by the same labs flag as the export, so the two halves round-trip or stay
@@ -81,7 +87,7 @@ export function makeImporter(deps: ImporterServices) {
     const customFields: CustomFieldsImport = {
         activeFields: async () => (labs.isSet('membersCustomFields') ? deps.customFields.definitions.browse() : []),
         planWrite: values => deps.customFields.values.planWrite(values),
-        applyWrite: (memberId, plan, executor) => deps.customFields.values.applyWrite(memberId, plan, executor)
+        applyWrite: (memberId, plan, executor) => deps.customFields.values.applyWrite(memberId, plan, {executor})
     };
 
     return new MembersCSVImporter({

package/core/server/services/members/members-api/controllers/router-controller.js

@@ -525,7 +525,7 @@ module.exports = class RouterController {
      * @param {string} options.cancelUrl URL to redirect to after cancelled checkout
      * @param {string} [options.email] Email address of the customer
      * @param {object} [options.member] Currently authenticated member OR member associated with the email address
-     * @param {object} [options.gift] Active gift subscription for the member
+     * @param {number|null} [options.giftTrialDays] Stable continuation decision from gift subscriptions
      * @param {boolean} options.isAuthenticated
      * @param {object} options.metadata Metadata to be passed to Stripe
      * @returns
@@ -680,9 +680,11 @@ module.exports = class RouterController {
 
     /**
      * @param {object} options
-     * @param {object} options.tier
-     * @param {'month'|'year'} options.cadence
-     * @param {string} options.email
+     * @param {string} options.tierId
+     * @param {string} [options.offerId]
+     * @param {string} [options.cadence]
+     * @param {number} [options.duration]
+     * @param {string} [options.email]
      * @param {string} options.successUrl
      * @param {string} options.cancelUrl
      * @param {object} options.metadata
@@ -698,10 +700,26 @@ module.exports = class RouterController {
         }
 
         try {
-            const paymentLink = await this._paymentsService.getGiftPaymentLink(options);
-
-            return {url: paymentLink};
+            return await this._giftService.service.startCheckout({
+                tierId: options.tierId,
+                offerId: options.offerId,
+                cadence: options.cadence,
+                duration: options.duration,
+                metadata: options.metadata,
+                successUrl: options.successUrl,
+                cancelUrl: options.cancelUrl,
+                buyer: {
+                    memberId: options.member?.id ?? null,
+                    email: options.member?.get('email') ?? options.email ?? null,
+                    name: options.member?.get('name') ?? null,
+                    isAuthenticated: options.isAuthenticated
+                }
+            });
         } catch (err) {
+            if (err instanceof BadRequestError || err instanceof NoPermissionError) {
+                throw err;
+            }
+
             logging.error(err);
             this._sentry?.captureException?.(err);
             throw new BadRequestError({
@@ -788,7 +806,7 @@ module.exports = class RouterController {
             let tier;
             let cadence;
             let offer;
-            let gift;
+            let giftTrialDays;
 
             if (req.body.continueFromGift) {
                 if (!isAuthenticated || !member) {
@@ -796,25 +814,16 @@ module.exports = class RouterController {
                         message: tpl(messages.signInRequired)
                     });
                 }
-                if (member.get('status') !== 'gift') {
-                    throw new BadRequestError({
-                        message: tpl(messages.badRequest),
-                        context: 'Member does not have an active gift subscription'
-                    });
-                }
-
-                gift = await this._giftService.service.getActiveByMember(member.id);
-                if (!gift) {
-                    throw new BadRequestError({
-                        message: tpl(messages.badRequest),
-                        context: 'No active gift subscription found for member'
-                    });
-                }
+                const continuation = await this._giftService.service.preparePaidContinuation({
+                    memberId: member.id,
+                    memberStatus: member.get('status')
+                });
 
                 ({tier, cadence} = await this._getSubscriptionCheckoutData({
-                    tierId: gift.tierId,
-                    cadence: gift.cadence
+                    tierId: continuation.tierId,
+                    cadence: continuation.cadence
                 }));
+                giftTrialDays = continuation.trialDays;
             } else {
                 ({tier, cadence, offer} = await this._getSubscriptionCheckoutData(req.body));
             }
@@ -825,7 +834,7 @@ module.exports = class RouterController {
                 tier,
                 cadence,
                 offer,
-                gift
+                giftTrialDays
             });
 
             // Add welcome_page_url to the response if available and member is authenticated
@@ -842,19 +851,12 @@ module.exports = class RouterController {
                 });
             }
 
-            if (req.body.offerId) {
-                throw new BadRequestError({
-                    message: tpl(messages.badRequest),
-                    context: 'Offers cannot be applied to gift subscriptions'
-                });
-            }
-
-            const data = await this._getSubscriptionCheckoutData(req.body);
-
             response = await this._createGiftCheckoutSession({
                 ...options,
-                ...data,
-                duration: 1, // gifts are currently 1 month or 1 year only
+                tierId: req.body.tierId,
+                offerId: req.body.offerId,
+                cadence: req.body.cadence,
+                duration: req.body.duration,
                 successUrl: siteUrl,
                 cancelUrl: options.cancelUrl || siteUrl
             });

package/core/server/services/members/members-api/members-api.js

@@ -67,8 +67,7 @@ module.exports = function MembersAPI({
         MemberFeedback,
         Automation,
         WelcomeEmailAutomationRun,
-        AutomatedEmailRecipient,
-        Gift
+        AutomatedEmailRecipient
     },
     tiersService,
     stripeAPIService,
@@ -142,7 +141,7 @@ module.exports = function MembersAPI({
         memberAttributionService,
         MemberEmailChangeEvent,
         AutomatedEmailRecipient,
-        Gift
+        giftSubscriptions: giftService
     });
 
     const nextPaymentCalculator = new NextPaymentCalculator();
@@ -192,8 +191,7 @@ module.exports = function MembersAPI({
         Offer,
         offersAPI,
         stripeAPIService,
-        settingsCache,
-        giftService
+        settingsCache
     });
 
     const memberController = new MemberController({
@@ -283,7 +281,10 @@ module.exports = function MembersAPI({
             }
 
             if (giftToken) {
-                await giftService.service.redeem(giftToken, member.id);
+                await giftService.service.redeem({
+                    token: giftToken,
+                    memberId: member.id
+                });
             }
 
             await MemberLoginEvent.add({member_id: member.id});
@@ -316,7 +317,12 @@ module.exports = function MembersAPI({
                     {name, email, labels, newsletters, attribution, geolocation, status: 'gift'},
                     {transacting}
                 );
-                await giftService.service.redeem(giftToken, created.id, {transacting, newMember: true});
+                await giftService.service.redeem({
+                    token: giftToken,
+                    memberId: created.id,
+                    transacting,
+                    newMember: true
+                });
                 return created;
             });
         } else {

package/core/server/services/members/members-api/repositories/event-repository.js

@@ -37,7 +37,7 @@ module.exports = class EventRepository {
         urlService,
         MemberEmailChangeEvent,
         AutomatedEmailRecipient,
-        Gift
+        giftSubscriptions
     }) {
         this._DonationPaymentEvent = DonationPaymentEvent;
         this._MemberSubscribeEvent = MemberSubscribeEvent;
@@ -57,7 +57,7 @@ module.exports = class EventRepository {
         this._memberAttributionService = memberAttributionService;
         this._MemberEmailChangeEvent = MemberEmailChangeEvent;
         this._AutomatedEmailRecipient = AutomatedEmailRecipient;
-        this._Gift = Gift;
+        this._giftSubscriptions = giftSubscriptions;
         this._knex = db.knex;
     }
 
@@ -462,101 +462,11 @@ module.exports = class EventRepository {
     }
 
     async getGiftPurchaseEvents(options = {}, filter) {
-        options = {
-            ...options,
-            withRelated: ['buyer', 'tier'],
-            filter: 'buyer_member_id:-null+custom:true',
-            useBasicCount: true,
-            mongoTransformer: chainTransformers(
-                // First set the filter manually
-                replaceCustomFilterTransformer(filter),
-
-                // Map the used keys in that filter
-                ...mapKeys({
-                    'data.created_at': 'purchased_at',
-                    'data.member_id': 'buyer_member_id'
-                })
-            )
-        };
-
-        if (options.order) {
-            options.order = options.order.replace(/created_at/g, 'purchased_at');
-        }
-
-        const {data: models, meta} = await this._Gift.findPage(options);
-
-        const data = models.map((model) => {
-            const json = model.toJSON(options);
-
-            return {
-                type: 'gift_purchase_event',
-                data: {
-                    id: json.id,
-                    member: json.buyer || null,
-                    member_id: json.buyer_member_id,
-                    tier_name: json.tier?.name,
-                    cadence: json.cadence,
-                    duration: json.duration,
-                    amount: json.amount,
-                    currency: json.currency,
-                    created_at: json.purchased_at
-                }
-            };
-        });
-
-        return {
-            data,
-            meta
-        };
+        return this._giftSubscriptions.service.browsePurchaseEvents(options, filter);
     }
 
     async getGiftRedemptionEvents(options = {}, filter) {
-        options = {
-            ...options,
-            withRelated: ['redeemer', 'tier'],
-            filter: 'redeemer_member_id:-null+custom:true',
-            useBasicCount: true,
-            mongoTransformer: chainTransformers(
-                // First set the filter manually
-                replaceCustomFilterTransformer(filter),
-
-                // Map the used keys in that filter
-                ...mapKeys({
-                    'data.created_at': 'redeemed_at',
-                    'data.member_id': 'redeemer_member_id'
-                })
-            )
-        };
-
-        if (options.order) {
-            options.order = options.order.replace(/created_at/g, 'redeemed_at');
-        }
-
-        const {data: models, meta} = await this._Gift.findPage(options);
-
-        const data = models.map((model) => {
-            const json = model.toJSON(options);
-
-            return {
-                type: 'gift_redemption_event',
-                data: {
-                    id: json.id,
-                    member: json.redeemer || null,
-                    member_id: json.redeemer_member_id,
-                    tier_name: json.tier?.name,
-                    cadence: json.cadence,
-                    duration: json.duration,
-                    amount: json.amount,
-                    currency: json.currency,
-                    created_at: json.redeemed_at
-                }
-            };
-        });
-
-        return {
-            data,
-            meta
-        };
+        return this._giftSubscriptions.service.browseRedemptionEvents(options, filter);
     }
 
     async getGiftEndedEvents(options = {}, filter) {

package/core/server/services/members/members-api/services/member-bread-service.js

@@ -34,7 +34,7 @@ const CUSTOM_FIELDS_EDITED_ACTION = 'custom_fields_edited';
 
 /**
  * @typedef {object} IGiftServiceWrapper
- * @prop {{getActiveByMembers: (memberIds: string[]) => Promise<Map<string, {cadence: 'month' | 'year', currency: string, amount: number}>>}} service
+ * @prop {{getMemberPresentations: (memberIds: string[]) => Promise<Map<string, {cadence: 'month' | 'year', currency: string, amount: number}>>}} service
  */
 
 module.exports = class MemberBREADService {
@@ -347,7 +347,7 @@ module.exports = class MemberBREADService {
      * @private
      * Fetches active redeemed gifts for any gift-status members in the input list.
      * @param {import('bookshelf').Model[]} members - Bookshelf member models
-     * @returns {Promise<Map<string, {cadence: 'month' | 'year', currency: string, amount: number}>>} keyed by member.id → active Gift
+     * @returns {Promise<Map<string, {cadence: 'month' | 'year', currency: string, amount: number}>>} keyed by member.id → stable gift presentation
      */
     async fetchActiveGiftsForMembers(members) {
         const giftMemberIds = members
@@ -359,7 +359,7 @@ module.exports = class MemberBREADService {
         }
 
         try {
-            return await this.giftService.service.getActiveByMembers(giftMemberIds);
+            return await this.giftService.service.getMemberPresentations(giftMemberIds);
         } catch (e) {
             logging.error(`Failed to load active gifts for members - ${giftMemberIds.join(', ')}.`);
             logging.error(e);

package/core/server/services/members/members-api/services/payments-service.js

@@ -14,7 +14,6 @@ class PaymentsService {
      * @param {import('../../../offers/application/offers-api')} deps.offersAPI
      * @param {import('../../../stripe/stripe-api')} deps.stripeAPIService
      * @param {{get(key: string): any}} deps.settingsCache
-     * @param {{service: import('../../../gifts/gift-service').GiftService}} deps.giftService
      */
     constructor(deps) {
         /** @private */
@@ -31,9 +30,6 @@ class PaymentsService {
         this.stripeAPIService = deps.stripeAPIService;
         /** @private */
         this.settingsCache = deps.settingsCache;
-        /** @private */
-        this.giftService = deps.giftService;
-
         DomainEvents.subscribe(OfferCreatedEvent, async (event) => {
             await this.getCouponForOffer(event.data.offer.id);
         });
@@ -65,7 +61,7 @@ class PaymentsService {
      * @param {Tier.Cadence} params.cadence
      * @param {Offer} [params.offer]
      * @param {Member} [params.member]
-     * @param {import('../../../gifts/gift').Gift} [params.gift]
+     * @param {number|null} [params.giftTrialDays]
      * @param {Object.<string, any>} [params.metadata]
      * @param {string} params.successUrl
      * @param {string} params.cancelUrl
@@ -73,7 +69,7 @@ class PaymentsService {
      *
      * @returns {Promise<URL>}
      */
-    async getPaymentLink({tier, cadence, offer, member, gift, metadata, successUrl, cancelUrl, email}) {
+    async getPaymentLink({tier, cadence, offer, member, giftTrialDays, metadata, successUrl, cancelUrl, email}) {
         let coupon = null;
         let trialDays = null;
         if (offer) {
@@ -94,12 +90,10 @@ class PaymentsService {
             }
         }
 
-        // If continuing from a gift subscription, add gift remaining days as trial
-        if (trialDays === null && gift) {
-            const remainingDays = this.giftService.service.getRemainingActiveDays(gift);
-            if (remainingDays > 0) {
-                trialDays = Math.min(remainingDays, 730); // Stripe max trial period
-            }
+        // Gift subscriptions owns the continuation calculation. This adapter only
+        // translates the stable decision into the recurring Stripe checkout.
+        if (trialDays === null && giftTrialDays !== undefined) {
+            trialDays = giftTrialDays;
         }
 
         let customer = null;
@@ -163,62 +157,6 @@ class PaymentsService {
         return session.url;
     }
 
-    /**
-     * @param {object} params
-     * @param {import('../../../tiers/tier')} params.tier
-     * @param {'month'|'year'} params.cadence
-     * @param {number} params.duration
-     * @param {string} params.successUrl
-     * @param {string} params.cancelUrl
-     * @param {object} params.metadata
-     * @param {object} [params.member]
-     * @param {boolean} params.isAuthenticated
-     * @param {string} [params.email]
-     *
-     * @returns {Promise<string>}
-     */
-    async getGiftPaymentLink({tier, cadence, duration, metadata, successUrl, cancelUrl, member, isAuthenticated, email}) {
-        let customer = null;
-        if (member && isAuthenticated) {
-            customer = await this.getCustomerForMember(member);
-        }
-
-        const amount = tier.getPrice(cadence);
-        const currency = tier.currency.toLowerCase();
-
-        const token = this.giftService.service.generateToken();
-
-        const successUrlObj = new URL(successUrl);
-        successUrlObj.searchParams.set('stripe', 'gift-purchase-success');
-        successUrlObj.searchParams.set('gift_token', token);
-        successUrlObj.searchParams.set('gift_tier', tier.id.toHexString());
-        successUrlObj.searchParams.set('gift_cadence', cadence);
-
-        const data = {
-            amount,
-            currency,
-            tierName: tier.name,
-            cadence,
-            duration,
-            metadata: {
-                ...metadata,
-                ghost_gift: 'true',
-                gift_token: token,
-                tier_id: tier.id.toHexString(),
-                cadence,
-                duration: String(duration)
-            },
-            successUrl: successUrlObj.toString(),
-            cancelUrl,
-            customer,
-            customerEmail: !customer && email ? email : null
-        };
-
-        const session = await this.stripeAPIService.createGiftCheckoutSession(data);
-
-        return session.url;
-    }
-
     async getCustomerForMember(member) {
         const rows = await this.StripeCustomerModel.where({
             member_id: member.id

package/core/server/services/members-custom-fields/queries.js

@@ -3,19 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.activeFields = activeFields;
 const schema_1 = require("./schema");
 const FIELDS_TABLE = 'members_custom_fields';
-// Shared query builders over the field definitions, used by both the definitions
-// service and the values service.
-//
-// The `status = 'active'` filter is the one invariant worth centralising: archived
-// fields must stay out of every read and every write, and that's enforced by a
-// filter, not a database constraint — nothing stops a value row referencing an
-// archived field, so a query that forgets the filter is a silent bug. Keeping the
-// filter in one builder means there's one place to get it right.
-/**
- * The active field definitions. Takes the executor — a knex instance or a
- * transaction — so the same query runs standalone or inside a write's
- * transaction; callers chain their own `select`/`orderBy`/`whereIn` onto it.
- */
+// Archived fields must stay out of every read and write, and nothing in the database
+// enforces that — no constraint stops a value row referencing an archived field. A query
+// that forgets the filter is a silent bug, so the filter lives in one place.
+/** Takes the executor so the same query runs standalone or inside a write's transaction. */
 function activeFields(db) {
     return db(FIELDS_TABLE).where('status', schema_1.FIELD_STATUS.active);
 }

package/core/server/services/members-custom-fields/queries.ts

@@ -3,20 +3,11 @@ import {FIELD_STATUS} from './schema';
 
 const FIELDS_TABLE = 'members_custom_fields';
 
-// Shared query builders over the field definitions, used by both the definitions
-// service and the values service.
-//
-// The `status = 'active'` filter is the one invariant worth centralising: archived
-// fields must stay out of every read and every write, and that's enforced by a
-// filter, not a database constraint — nothing stops a value row referencing an
-// archived field, so a query that forgets the filter is a silent bug. Keeping the
-// filter in one builder means there's one place to get it right.
+// Archived fields must stay out of every read and write, and nothing in the database
+// enforces that — no constraint stops a value row referencing an archived field. A query
+// that forgets the filter is a silent bug, so the filter lives in one place.
 
-/**
- * The active field definitions. Takes the executor — a knex instance or a
- * transaction — so the same query runs standalone or inside a write's
- * transaction; callers chain their own `select`/`orderBy`/`whereIn` onto it.
- */
+/** Takes the executor so the same query runs standalone or inside a write's transaction. */
 export function activeFields(db: Knex) {
     return db(FIELDS_TABLE).where('status', FIELD_STATUS.active);
 }