musora-content-services 2.187.0 → 2.189.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.189.0](https://github.com/railroadmedia/musora-content-services/compare/v2.188.0...v2.189.0) (2026-10-20)
+
+
+### Features
+
+* **MU2-2024:** add placeholder resolution for promotional campaign copy ([f5cebb3](https://github.com/railroadmedia/musora-content-services/commit/f5cebb3888ce1228ecba5ec17412c8bcfaff8c35))
+
+## [2.188.0](https://github.com/railroadmedia/musora-content-services/compare/v2.187.0...v2.188.0) (2026-10-20)
+
+
+### Features
+
+* **MU2-2024:** add brand filtering to promotional campaign queries ([0d6fed8](https://github.com/railroadmedia/musora-content-services/commit/0d6fed83329ccfeabab2ddbd6dff129075c1207b))
+
 ## [2.187.0](https://github.com/railroadmedia/musora-content-services/compare/v2.186.1...v2.187.0) (2026-10-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musora-content-services",
-  "version": "2.187.0",
+  "version": "2.189.0",
   "description": "A package for Musoras content services ",
   "main": "src/index.js",
   "type": "module",

package/src/index.d.ts

@@ -221,7 +221,8 @@ import {
 	dismissPromotionalCampaign,
 	fetchAvailablePromotionalCampaigns,
 	fetchPromotionalCampaigns,
-	fetchUserCampaignStates
+	fetchUserCampaignStates,
+	resolveCampaignCopy
 } from './services/marketing/promotions.ts';
 
 import {
@@ -901,6 +902,7 @@ declare module 'musora-content-services' {
 		resetAllAwards,
 		resetAllLearningPaths,
 		resetPassword,
+		resolveCampaignCopy,
 		restoreComment,
 		restoreItemFromPlaylist,
 		restoreNotification,

package/src/index.js

@@ -225,7 +225,8 @@ import {
 	dismissPromotionalCampaign,
 	fetchAvailablePromotionalCampaigns,
 	fetchPromotionalCampaigns,
-	fetchUserCampaignStates
+	fetchUserCampaignStates,
+	resolveCampaignCopy
 } from './services/marketing/promotions.ts';
 
 import {
@@ -900,6 +901,7 @@ export {
 	resetAllAwards,
 	resetAllLearningPaths,
 	resetPassword,
+	resolveCampaignCopy,
 	restoreComment,
 	restoreItemFromPlaylist,
 	restoreNotification,

package/src/lib/brands.ts

@@ -6,3 +6,5 @@ export enum Brands {
   Singeo = 'singeo',
   Playbass = 'playbass',
 }
+
+export type Brand = 'musora' | 'drumeo' | 'pianote' | 'guitareo' | 'singeo' | 'playbass'

package/src/lib/sanity/types/marketing.d.ts

@@ -99,6 +99,7 @@ export type PromotionalCampaignDocument = {
   _createdAt: string
   _updatedAt: string
   _rev: string
+  brand: "musora" | "drumeo" | "pianote" | "singeo" | "guitareo" | "playbass"
   /** Campaign Name */
   name: string
   slug: { _type: "slug"; current: string }
@@ -116,10 +117,10 @@ export type PromotionalCampaignDocument = {
     title?: string
     body?: string
     disclaimer?: string
-    /** Resolved to a CDN url by the promotions query projection. */
-    dark_mode_image?: string
-    /** Resolved to a CDN url by the promotions query projection. */
-    light_mode_image?: string
+    /** Dark Image */
+    dark_mode_image?: { _type: "image"; asset: { _type: "reference"; _ref: string } }
+    /** Light Image */
+    light_mode_image?: { _type: "image"; asset: { _type: "reference"; _ref: string } }
     /** CTA Label */
     cta_label?: string
     /** Dismissible? */

package/src/services/marketing/promotions.ts

@@ -5,8 +5,8 @@ import { Filters as f } from '../../lib/sanity/filter'
 import { groq } from '../../lib/sanity/groq'
 import type { GroqBuilder } from '../../lib/sanity/groq'
 import type { PromotionalCampaignDocument } from '../../lib/sanity/types/marketing'
-import { SanityQueryError } from '../../lib/sanity/runner'
 import { AsyncEither } from '../../lib/ads/async-either'
+import { Brand } from '../../lib/brands'
 
 const excludeFromGeneratedIndex = [
   'campaignQuery',
@@ -19,6 +19,21 @@ const excludeFromGeneratedIndex = [
 // TYPES
 // ============================================
 
+type PlacementDocument = PromotionalCampaignDocument['placements'][number]
+
+/** A placement as `campaignProjection` returns it, with both images resolved to CDN urls. */
+export type PromotionalCampaignPlacement = Omit<
+  PlacementDocument,
+  'dark_mode_image' | 'light_mode_image'
+> & {
+  dark_mode_image?: string
+  light_mode_image?: string
+}
+
+export type PromotionalCampaign = Omit<PromotionalCampaignDocument, 'placements'> & {
+  placements: PromotionalCampaignPlacement[]
+}
+
 export const USER_CAMPAIGN_STATE_FIELD = 'user_state' as const
 
 /**
@@ -31,11 +46,13 @@ export interface UserCampaignState {
   eligible: boolean
 }
 
-export type WithUserCampaignState<T extends PromotionalCampaignDocument> = T & {
+export type WithUserCampaignState<T extends PromotionalCampaign> = T & {
   user_state: UserCampaignState
 }
 
 export interface CampaignQueryOptions {
+  /** Restricts the query to one brand's campaigns. */
+  brand?: Brand
   /** Restricts the query to one campaign, or to any of several. */
   slug?: string | string[]
   /** The moment the campaign window is tested against. Defaults to now. */
@@ -52,7 +69,7 @@ const UNTOUCHED: UserCampaignState = { claimed: false, dismissed: false, eligibl
 // UTILITIES
 // ============================================
 
-const filterCampaignsForUser = (campaigns: WithUserCampaignState<PromotionalCampaignDocument>[]) =>
+const filterCampaignsForUser = (campaigns: WithUserCampaignState<PromotionalCampaign>[]) =>
   campaigns.filter(
     (campaign) =>
       campaign.user_state.eligible && !campaign.user_state.claimed && !campaign.user_state.dismissed
@@ -77,13 +94,14 @@ function slugFilter(slug: CampaignQueryOptions['slug']): string {
 
 export function campaignQuery(
   options: CampaignQueryOptions = {}
-): GroqBuilder<PromotionalCampaignDocument[]> {
-  const { slug, on = new Date(), running = true, active = true } = options
+): GroqBuilder<PromotionalCampaign[]> {
+  const { brand, slug, on = new Date(), running = true, active = true } = options
 
-  return groq<PromotionalCampaignDocument[]>()
+  return groq<PromotionalCampaign[]>()
     .and(
       f.combine(
         f.type('promotional-campaign'),
+        brand && f.brand(brand),
         active && f.flag('active'),
         running && f.dateWithin('starts_at', 'ends_at', on.toISOString()),
         slugFilter(slug)
@@ -100,7 +118,7 @@ export function campaignQuery(
 
 export async function fetchPromotionalCampaigns(
   options: CampaignQueryOptions = {}
-): Promise<PromotionalCampaignDocument[]> {
+): Promise<PromotionalCampaign[]> {
   return campaignQuery(options).run().recover([])
 }
 
@@ -109,7 +127,7 @@ export async function fetchPromotionalCampaigns(
  */
 export async function fetchAvailablePromotionalCampaigns(
   options: CampaignQueryOptions = {}
-): Promise<WithUserCampaignState<PromotionalCampaignDocument>[]> {
+): Promise<WithUserCampaignState<PromotionalCampaign>[]> {
   return campaignQuery(options)
     .run()
     .flatMap(decorateUserCampaignState)
@@ -141,7 +159,7 @@ export function userCampaignStateDecorator(
   return {
     field: USER_CAMPAIGN_STATE_FIELD,
     compute: async (item) => {
-      const campaign = item as unknown as PromotionalCampaignDocument
+      const campaign = item as unknown as PromotionalCampaign
 
       return states[campaign.slug?.current] ?? UNTOUCHED
     },
@@ -151,7 +169,7 @@ export function userCampaignStateDecorator(
 /**
  * Attaches each campaign's claim and dismiss state in a single backend request.
  */
-export function decorateUserCampaignState<T extends PromotionalCampaignDocument>(
+export function decorateUserCampaignState<T extends PromotionalCampaign>(
   campaigns: T[]
 ): AsyncEither<Error, WithUserCampaignState<T>[]> {
   return AsyncEither.attempt(async () => {
@@ -165,6 +183,50 @@ export function decorateUserCampaignState<T extends PromotionalCampaignDocument>
   })
 }
 
+// ============================================
+// COPY
+// ============================================
+
+export type CampaignCopyValues = Record<string, string>
+
+const PLACEHOLDER = /\{(\w+)\}/g
+
+const COPY_FIELDS = ['title', 'body', 'disclaimer', 'cta_label'] as const
+
+const fillPlaceholders = (text: string, values: CampaignCopyValues) =>
+  text.replace(PLACEHOLDER, (placeholder, name: string) => values[name] ?? placeholder)
+
+const hasPlaceholder = (text: string | undefined) => !!text && new RegExp(PLACEHOLDER).test(text)
+
+function resolvePlacementCopy(
+  placement: PromotionalCampaignPlacement,
+  values: CampaignCopyValues
+): PromotionalCampaignPlacement {
+  const resolved = { ...placement }
+
+  for (const field of COPY_FIELDS) {
+    if (resolved[field]) resolved[field] = fillPlaceholders(resolved[field], values)
+  }
+
+  return resolved
+}
+
+/**
+ * Replaces `{name}` placeholders in each placement's copy with the given values. A placement left
+ * with a placeholder that has no value is dropped, so raw `{name}` text never reaches the user.
+ */
+export function resolveCampaignCopy<T extends PromotionalCampaign>(
+  campaign: T,
+  values: CampaignCopyValues
+): T {
+  return {
+    ...campaign,
+    placements: campaign.placements
+      .map((placement) => resolvePlacementCopy(placement, values))
+      .filter((placement) => !COPY_FIELDS.some((field) => hasPlaceholder(placement[field]))),
+  }
+}
+
 // ============================================
 // MUTATIONS
 // ============================================

package/src/version-info.js

@@ -1 +1 @@
-export const MCS_VERSION = '2.187.0'
+export const MCS_VERSION = '2.189.0'