musora-content-services 2.188.0 → 2.190.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.190.0](https://github.com/railroadmedia/musora-content-services/compare/v2.189.0...v2.190.0) (2026-10-20)
+
+
+### Features
+
+* **MU2-2024:** resolve placement copy in fetchAvailablePromotionalCampaigns ([ac69d37](https://github.com/railroadmedia/musora-content-services/commit/ac69d379a264e031b1f5bd999b6bed8c78fbfb58))
+
+## [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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musora-content-services",
-  "version": "2.188.0",
+  "version": "2.190.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,
+	resolveCampaignPlaceholders
 } from './services/marketing/promotions.ts';
 
 import {
@@ -901,6 +902,7 @@ declare module 'musora-content-services' {
 		resetAllAwards,
 		resetAllLearningPaths,
 		resetPassword,
+		resolveCampaignPlaceholders,
 		restoreComment,
 		restoreItemFromPlaylist,
 		restoreNotification,

package/src/index.js

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

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

@@ -117,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

@@ -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,7 +46,7 @@ export interface UserCampaignState {
   eligible: boolean
 }
 
-export type WithUserCampaignState<T extends PromotionalCampaignDocument> = T & {
+export type WithUserCampaignState<T extends PromotionalCampaign> = T & {
   user_state: UserCampaignState
 }
 
@@ -48,13 +63,18 @@ export interface CampaignQueryOptions {
   active?: boolean
 }
 
+export interface AvailableCampaignOptions extends CampaignQueryOptions {
+  /** Values for the `{name}` placeholders in placement copy. See `resolveCampaignPlaceholders`. */
+  placeholderValues?: CampaignPlaceholderValues
+}
+
 const UNTOUCHED: UserCampaignState = { claimed: false, dismissed: false, eligible: true }
 
 // ============================================
 // 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
@@ -79,10 +99,10 @@ function slugFilter(slug: CampaignQueryOptions['slug']): string {
 
 export function campaignQuery(
   options: CampaignQueryOptions = {}
-): GroqBuilder<PromotionalCampaignDocument[]> {
+): 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'),
@@ -103,7 +123,7 @@ export function campaignQuery(
 
 export async function fetchPromotionalCampaigns(
   options: CampaignQueryOptions = {}
-): Promise<PromotionalCampaignDocument[]> {
+): Promise<PromotionalCampaign[]> {
   return campaignQuery(options).run().recover([])
 }
 
@@ -111,12 +131,17 @@ export async function fetchPromotionalCampaigns(
  * Every running campaign the user has not already claimed or dismissed, and is eligible.
  */
 export async function fetchAvailablePromotionalCampaigns(
-  options: CampaignQueryOptions = {}
-): Promise<WithUserCampaignState<PromotionalCampaignDocument>[]> {
-  return campaignQuery(options)
+  options: AvailableCampaignOptions = {}
+): Promise<WithUserCampaignState<PromotionalCampaign>[]> {
+  const { placeholderValues = {}, ...queryOptions } = options
+
+  return campaignQuery(queryOptions)
     .run()
     .flatMap(decorateUserCampaignState)
     .map(filterCampaignsForUser)
+    .map((campaigns) =>
+      campaigns.map((campaign) => resolveCampaignPlaceholders(campaign, placeholderValues))
+    )
     .recover([])
 }
 
@@ -144,7 +169,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
     },
@@ -154,7 +179,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 () => {
@@ -168,6 +193,50 @@ export function decorateUserCampaignState<T extends PromotionalCampaignDocument>
   })
 }
 
+// ============================================
+// PLACEHOLDERS
+// ============================================
+
+export type CampaignPlaceholderValues = Record<string, string>
+
+const PLACEHOLDER = /\{(\w+)\}/g
+
+const COPY_FIELDS = ['title', 'body', 'disclaimer', 'cta_label'] as const
+
+const fillPlaceholders = (text: string, values: CampaignPlaceholderValues) =>
+  text.replace(PLACEHOLDER, (placeholder, name: string) => values[name] ?? placeholder)
+
+const hasPlaceholder = (text: string | undefined) => !!text && new RegExp(PLACEHOLDER).test(text)
+
+function resolvePlacementPlaceholders(
+  placement: PromotionalCampaignPlacement,
+  values: CampaignPlaceholderValues
+): 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 resolveCampaignPlaceholders<T extends PromotionalCampaign>(
+  campaign: T,
+  values: CampaignPlaceholderValues
+): T {
+  return {
+    ...campaign,
+    placements: (campaign.placements ?? [])
+      .map((placement) => resolvePlacementPlaceholders(placement, values))
+      .filter((placement) => !COPY_FIELDS.some((field) => hasPlaceholder(placement[field]))),
+  }
+}
+
 // ============================================
 // MUTATIONS
 // ============================================

package/src/version-info.js

@@ -1 +1 @@
-export const MCS_VERSION = '2.188.0'
+export const MCS_VERSION = '2.190.0'