@growth-labs/cms 0.1.0

package/src/ui/screens/social-share-data.ts

@@ -0,0 +1,753 @@
+// src/ui/screens/social-share-data.ts — pure Social Share builder logic.
+//
+// This module is a UI-owned mirror of the analytics package's social enums +
+// the P6-A share-link HTTP contract. It DOES NOT import @growth-labs/analytics;
+// the CMS calls the analytics routes over fetch (the cross-package seam, spec §3.1).
+//
+// SOURCE OF TRUTH for the enum values: @growth-labs/analytics src/utils/social.ts
+// Keep SOCIAL_PLATFORM_OPTIONS and SOCIAL_PLACEMENT_OPTIONS in lockstep with that
+// file whenever the analytics package adds a new platform or placement.
+
+import type { ContentType } from '../../schema/types.js'
+
+// ---------------------------------------------------------------------------
+// Option lists (UI-owned mirror — see source-of-truth comment above)
+// ---------------------------------------------------------------------------
+
+/**
+ * The four share contexts. Mirrors the `kind` discriminant of the P6-A
+ * `batchCreateSchema` discriminated union in share-links-batch.ts.
+ */
+export const SHARE_MODES = ['author-social', 'owned-social', 'youtube', 'newsletter'] as const
+
+export type ShareMode = (typeof SHARE_MODES)[number]
+
+/**
+ * Social platform options.
+ * SOURCE OF TRUTH: @growth-labs/analytics src/utils/social.ts SOCIAL_PLATFORMS
+ */
+export const SOCIAL_PLATFORM_OPTIONS = [
+	'x',
+	'instagram',
+	'facebook',
+	'linkedin',
+	'tiktok',
+	'threads',
+	'bluesky',
+	'youtube',
+	'reddit',
+	'substack',
+	'discord',
+	'pinterest',
+] as const
+
+export type SocialPlatformOption = (typeof SOCIAL_PLATFORM_OPTIONS)[number]
+
+/**
+ * Social placement options.
+ * SOURCE OF TRUTH: @growth-labs/analytics src/utils/social.ts SOCIAL_PLACEMENTS
+ */
+export const SOCIAL_PLACEMENT_OPTIONS = [
+	'feed',
+	'reply',
+	'comment',
+	'story',
+	'bio',
+	'pinned',
+	'description',
+	'ad',
+	'reel',
+	'short',
+	'unknown',
+] as const
+
+export type SocialPlacementOption = (typeof SOCIAL_PLACEMENT_OPTIONS)[number]
+
+/**
+ * The YouTube 3-link bundle placements (description / pinned-comment / bio).
+ * NOTE: "pinned-comment" from the §11 brief maps to the `comment` placement
+ * here — the go-link is posted as a pinned comment on the YouTube video.
+ * SOURCE OF TRUTH: spec §11 "description / pinned-comment / bio".
+ */
+export const YOUTUBE_BUNDLE_PLACEMENTS: SocialPlacementOption[] = ['description', 'comment', 'bio']
+
+/**
+ * Boost modes. Mirrors analytics SocialBoostMode.
+ * SOURCE OF TRUTH: @growth-labs/analytics src/utils/social.ts SocialBoostMode
+ */
+export const BOOST_MODES = ['none', 'paid_direct', 'boosted_existing'] as const
+export type BoostMode = (typeof BOOST_MODES)[number]
+
+// ---------------------------------------------------------------------------
+// Picker reference types (UI-owned mirror of AuthorRef / HandleRef from P6-A)
+// SOURCE OF TRUTH: @growth-labs/analytics src/routes/share-links-batch.ts
+// ---------------------------------------------------------------------------
+
+/** A reference to an author — existing by id/slug or inline-created. */
+export interface AuthorRef {
+	id?: string
+	slug?: string
+	displayName?: string
+	create?: boolean
+}
+
+/** A reference to a social handle — existing by id/username or inline-created. */
+export interface HandleRef {
+	id?: string
+	username?: string
+	url?: string
+	isBrandAccount?: boolean
+	create?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Form state
+// ---------------------------------------------------------------------------
+
+/**
+ * The advanced disclosure fields shared across all modes.
+ * Placement + boost + promo are tucked behind the Advanced toggle.
+ */
+export interface AdvancedState {
+	placement: SocialPlacementOption
+	boostMode: BoostMode
+	promoCode: string
+	advancedOpen: boolean
+}
+
+/**
+ * Superset form state for all four contexts. The mode discriminant determines
+ * which fields are relevant (see `relevantFields`). Fields that are not
+ * applicable to the current mode are present but ignored by the request
+ * builders — they hold their defaults so mode-switching is non-destructive
+ * for the shared fields.
+ */
+export interface ShareFormState extends AdvancedState {
+	mode: ShareMode
+
+	// Shared across all modes
+	destinationUrl: string
+	contentSlug: string
+	contentType: ContentType | ''
+	property: string
+
+	// author-social / owned-social / youtube (optional in newsletter)
+	platform: string
+	author: AuthorRef
+	handle: HandleRef
+
+	// author-social / owned-social
+	campaign: string
+
+	// youtube-specific
+	youtubeVideoId: string
+	placements: SocialPlacementOption[]
+
+	// newsletter-specific
+	issue: string
+
+	// source path (optional across all)
+	sourcePath: string
+}
+
+// ---------------------------------------------------------------------------
+// Optional prefill (from a LibraryRow / open editor doc)
+// ---------------------------------------------------------------------------
+
+export interface ShareFormPrefill {
+	destinationUrl?: string
+	contentSlug?: string
+	contentType?: ContentType | ''
+	campaign?: string
+	author?: AuthorRef
+}
+
+// ---------------------------------------------------------------------------
+// initShareForm
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the initial `ShareFormState` for the given mode.
+ * Optionally merges a prefill (from the per-content Share action).
+ *
+ * youtube mode seeds `placements` to YOUTUBE_BUNDLE_PLACEMENTS and
+ * `platform` to 'youtube'; all other fields default to empty/false/none.
+ */
+export function initShareForm(mode: ShareMode, prefill?: ShareFormPrefill): ShareFormState {
+	const defaultCampaign =
+		mode === 'author-social' || mode === 'owned-social'
+			? prefill?.campaign?.trim() || prefill?.contentSlug?.trim() || ''
+			: ''
+	const base: ShareFormState = {
+		mode,
+		destinationUrl: prefill?.destinationUrl ?? '',
+		contentSlug: prefill?.contentSlug ?? '',
+		contentType: prefill?.contentType ?? '',
+		property: '',
+		platform: mode === 'youtube' ? 'youtube' : '',
+		author: prefill?.author ?? {},
+		handle: {},
+		campaign: defaultCampaign,
+		youtubeVideoId: '',
+		placements: mode === 'youtube' ? [...YOUTUBE_BUNDLE_PLACEMENTS] : [],
+		issue: '',
+		sourcePath: '',
+		// AdvancedState defaults
+		placement: 'unknown',
+		boostMode: 'none',
+		promoCode: '',
+		advancedOpen: false,
+	}
+	return base
+}
+
+// ---------------------------------------------------------------------------
+// ShareFormAction union
+// ---------------------------------------------------------------------------
+
+/**
+ * All actions the form reducer accepts.
+ * Mode switches preserve shared fields and reset mode-specific ones.
+ */
+export type ShareFormAction =
+	| { type: 'set-mode'; mode: ShareMode }
+	| {
+			type: 'prefill-content'
+			destinationUrl: string
+			contentSlug: string
+			contentType: ContentType | ''
+			author?: AuthorRef
+	  }
+	| {
+			type: 'set-field'
+			field: keyof Pick<
+				ShareFormState,
+				| 'destinationUrl'
+				| 'contentSlug'
+				| 'contentType'
+				| 'property'
+				| 'platform'
+				| 'campaign'
+				| 'youtubeVideoId'
+				| 'issue'
+				| 'sourcePath'
+			>
+			value: string
+	  }
+	| { type: 'toggle-advanced' }
+	| { type: 'set-placement'; value: SocialPlacementOption }
+	| { type: 'set-boost'; value: BoostMode }
+	| { type: 'set-promo'; value: string }
+	| { type: 'set-author'; ref: AuthorRef }
+	| { type: 'set-handle'; ref: HandleRef }
+	| { type: 'toggle-youtube-placement'; placement: SocialPlacementOption }
+
+// ---------------------------------------------------------------------------
+// shareFormReducer
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure reducer for the Social Share form.
+ *
+ * Mode switches:
+ *  - preserve shared fields: destinationUrl, contentSlug, contentType,
+ *    property, sourcePath, author, handle, advanced prefs
+ *  - reset mode-specific fields to their per-mode defaults
+ *
+ * toggle-youtube-placement enforces min 1 placement (removing the last is a
+ * no-op so the youtube bundle always submits at least one link).
+ */
+export function shareFormReducer(state: ShareFormState, action: ShareFormAction): ShareFormState {
+	switch (action.type) {
+		case 'set-mode': {
+			const mode = action.mode
+			// Preserve shared cross-mode fields; reset mode-specific ones
+			const shared = {
+				destinationUrl: state.destinationUrl,
+				contentSlug: state.contentSlug,
+				contentType: state.contentType,
+				property: state.property,
+				sourcePath: state.sourcePath,
+				author: state.author,
+				handle: state.handle,
+				// Preserve advanced prefs across mode switches
+				placement: 'unknown' as SocialPlacementOption,
+				boostMode: mode === 'newsletter' ? ('none' as BoostMode) : state.boostMode,
+				promoCode: state.promoCode,
+				advancedOpen: state.advancedOpen,
+			}
+			return {
+				...shared,
+				mode,
+				// Mode-specific resets
+				platform: mode === 'youtube' ? 'youtube' : mode === 'newsletter' ? '' : '',
+				campaign: mode === 'youtube' || mode === 'newsletter' ? '' : state.campaign,
+				placements: mode === 'youtube' ? [...YOUTUBE_BUNDLE_PLACEMENTS] : [],
+				youtubeVideoId: mode === 'youtube' ? state.youtubeVideoId : '',
+				issue: mode === 'newsletter' ? state.issue : '',
+			}
+		}
+
+		case 'prefill-content': {
+			const shouldDefaultCampaign =
+				(state.mode === 'author-social' || state.mode === 'owned-social') && !state.campaign.trim()
+			return {
+				...state,
+				destinationUrl: action.destinationUrl,
+				contentSlug: action.contentSlug,
+				contentType: action.contentType,
+				campaign: shouldDefaultCampaign ? action.contentSlug : state.campaign,
+				...(action.author ? { author: action.author } : {}),
+			}
+		}
+
+		case 'set-field':
+			return { ...state, [action.field]: action.value }
+
+		case 'toggle-advanced':
+			return { ...state, advancedOpen: !state.advancedOpen }
+
+		case 'set-placement':
+			return { ...state, placement: action.value }
+
+		case 'set-boost':
+			return { ...state, boostMode: action.value }
+
+		case 'set-promo':
+			return { ...state, promoCode: action.value }
+
+		case 'set-author':
+			return { ...state, author: action.ref }
+
+		case 'set-handle':
+			return { ...state, handle: action.ref }
+
+		case 'toggle-youtube-placement': {
+			const { placement } = action
+			const current = state.placements
+			if (current.includes(placement)) {
+				// min 1 guard — no-op if removing the last
+				if (current.length <= 1) return state
+				return { ...state, placements: current.filter((p) => p !== placement) }
+			}
+			return { ...state, placements: [...current, placement] }
+		}
+
+		default:
+			return state
+	}
+}
+
+// ---------------------------------------------------------------------------
+// BatchPayload local types (UI-owned mirror of P6-A share-links-batch.ts)
+// SOURCE OF TRUTH: @growth-labs/analytics src/routes/share-links-batch.ts
+// Keep in lockstep with the batchCreateSchema discriminated union there.
+// ---------------------------------------------------------------------------
+
+/** author-social batch request payload */
+export interface AuthorSocialBatchPayload {
+	kind: 'author-social'
+	destinationUrl: string
+	platform: string
+	campaign: string
+	placement?: string
+	boostMode?: string
+	promoCode?: string
+	contentSlug?: string
+	contentType?: string
+	property?: string
+	sourcePath?: string
+	author: AuthorRef
+	handle: HandleRef
+}
+
+/** owned-social batch request payload */
+export interface OwnedSocialBatchPayload {
+	kind: 'owned-social'
+	destinationUrl: string
+	platform: string
+	campaign: string
+	placement?: string
+	boostMode?: string
+	promoCode?: string
+	contentSlug?: string
+	contentType?: string
+	property?: string
+	sourcePath?: string
+	handle: HandleRef
+	author?: AuthorRef
+}
+
+/** youtube batch request payload — placements array drives the 3-link bundle */
+export interface YoutubeBatchPayload {
+	kind: 'youtube'
+	destinationUrl: string
+	youtubeVideoId: string
+	platform: 'youtube'
+	/** The placements array drives the 3-link bundle server-side (NOT a single placement). */
+	placements: string[]
+	boostMode?: string
+	promoCode?: string
+	contentSlug?: string
+	contentType?: string
+	property?: string
+	sourcePath?: string
+	handle?: HandleRef
+	author?: AuthorRef
+}
+
+/** newsletter batch request payload — NO campaign, NO platform, NO boostMode */
+export interface NewsletterBatchPayload {
+	kind: 'newsletter'
+	destinationUrl: string
+	issue: string
+	placement?: string
+	promoCode?: string
+	contentSlug?: string
+	contentType?: string
+	property?: string
+	sourcePath?: string
+	author?: AuthorRef
+	handle?: HandleRef
+}
+
+export type BatchPayload =
+	| AuthorSocialBatchPayload
+	| OwnedSocialBatchPayload
+	| YoutubeBatchPayload
+	| NewsletterBatchPayload
+
+export type BuildPayloadResult = { ok: true; payload: BatchPayload } | { ok: false; error: string }
+
+// ---------------------------------------------------------------------------
+// buildBatchPayloadFrom
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps a `ShareFormState` → the exact `POST /api/share-links/batch` payload
+ * for the current mode, matching the P6-A `batchCreateSchema` discriminated
+ * union (see SOURCE OF TRUTH comment above).
+ *
+ * Returns `{ ok: true, payload }` when valid, or `{ ok: false, error }` when
+ * a required field is missing (the screen renders the error inline before POST).
+ *
+ * NOTE: UTM derivation is 100% server-side. This builder shapes the request
+ * only — no client-side URL building, no call to buildSocialShareUrl.
+ */
+export function buildBatchPayloadFrom(state: ShareFormState): BuildPayloadResult {
+	// Universal guard
+	if (!state.destinationUrl.trim()) {
+		return { ok: false, error: 'Destination URL is required.' }
+	}
+
+	// Helper: omit undefined / empty string optional fields so the POST body
+	// is clean. Empty AuthorRef/HandleRef objects ({}) are treated as unset.
+	function nonEmpty(s: string | undefined): string | undefined {
+		return s?.trim() ? s : undefined
+	}
+	function refHasContent(ref: AuthorRef | HandleRef): boolean {
+		return Object.keys(ref).some((k) => {
+			const v = (ref as Record<string, unknown>)[k]
+			return v !== undefined && v !== '' && v !== false
+		})
+	}
+
+	const shared = {
+		destinationUrl: state.destinationUrl.trim(),
+		...(nonEmpty(state.contentSlug) ? { contentSlug: state.contentSlug } : {}),
+		...(nonEmpty(state.contentType) ? { contentType: state.contentType } : {}),
+		...(nonEmpty(state.property) ? { property: state.property } : {}),
+		...(nonEmpty(state.sourcePath) ? { sourcePath: state.sourcePath } : {}),
+	}
+
+	switch (state.mode) {
+		case 'author-social': {
+			if (!state.campaign.trim()) {
+				return { ok: false, error: 'Campaign is required for author-social.' }
+			}
+			const payload: AuthorSocialBatchPayload = {
+				kind: 'author-social',
+				...shared,
+				platform: state.platform,
+				campaign: state.campaign.trim(),
+				...(state.placement && state.placement !== 'unknown' ? { placement: state.placement } : {}),
+				...(state.boostMode && state.boostMode !== 'none' ? { boostMode: state.boostMode } : {}),
+				...(nonEmpty(state.promoCode) ? { promoCode: state.promoCode } : {}),
+				author: state.author,
+				handle: state.handle,
+			}
+			return { ok: true, payload }
+		}
+
+		case 'owned-social': {
+			if (!state.campaign.trim()) {
+				return { ok: false, error: 'Campaign is required for owned-social.' }
+			}
+			const payload: OwnedSocialBatchPayload = {
+				kind: 'owned-social',
+				...shared,
+				platform: state.platform,
+				campaign: state.campaign.trim(),
+				...(state.placement && state.placement !== 'unknown' ? { placement: state.placement } : {}),
+				...(state.boostMode && state.boostMode !== 'none' ? { boostMode: state.boostMode } : {}),
+				...(nonEmpty(state.promoCode) ? { promoCode: state.promoCode } : {}),
+				handle: state.handle,
+				// author is optional for owned-social; only include if the ref has content
+				...(refHasContent(state.author) ? { author: state.author } : {}),
+			}
+			return { ok: true, payload }
+		}
+
+		case 'youtube': {
+			if (!state.youtubeVideoId.trim()) {
+				return { ok: false, error: 'YouTube Video ID is required.' }
+			}
+			if (!state.placements || state.placements.length === 0) {
+				return { ok: false, error: 'At least one placement is required for the YouTube bundle.' }
+			}
+			const payload: YoutubeBatchPayload = {
+				kind: 'youtube',
+				...shared,
+				youtubeVideoId: state.youtubeVideoId.trim(),
+				platform: 'youtube',
+				placements: [...state.placements],
+				...(state.boostMode && state.boostMode !== 'none' ? { boostMode: state.boostMode } : {}),
+				...(nonEmpty(state.promoCode) ? { promoCode: state.promoCode } : {}),
+				...(refHasContent(state.handle) ? { handle: state.handle } : {}),
+				...(refHasContent(state.author) ? { author: state.author } : {}),
+			}
+			return { ok: true, payload }
+		}
+
+		case 'newsletter': {
+			if (!state.issue.trim()) {
+				return { ok: false, error: 'Issue is required for newsletter.' }
+			}
+			const payload: NewsletterBatchPayload = {
+				kind: 'newsletter',
+				...shared,
+				issue: state.issue.trim(),
+				...(state.placement && state.placement !== 'unknown' ? { placement: state.placement } : {}),
+				...(nonEmpty(state.promoCode) ? { promoCode: state.promoCode } : {}),
+				...(refHasContent(state.author) ? { author: state.author } : {}),
+				...(refHasContent(state.handle) ? { handle: state.handle } : {}),
+			}
+			return { ok: true, payload }
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// LinkResult local type (UI-owned mirror of the P6-A batch response shape)
+// SOURCE OF TRUTH: @growth-labs/analytics src/routes/share-links-batch.ts LinkResult
+// Keep in lockstep with the server-side type there.
+// ---------------------------------------------------------------------------
+
+/**
+ * A single link returned by `POST /api/share-links/batch`.
+ * The go-link the operator pastes is `<goBase>/<shortCode>`.
+ * The `taggedUrl` is the resolved destination with all UTMs appended (server-owned).
+ */
+export interface LinkResult {
+	id: string
+	kind: string
+	shortCode: string
+	taggedUrl: string
+	utmSource: string
+	utmMedium: string
+	utmCampaign: string
+	utmContent: string
+	utmTerm: string
+	youtubeVideoId: string | null
+	placement: string
+}
+
+// ---------------------------------------------------------------------------
+// ShareOutputItem + ShareOutput
+// ---------------------------------------------------------------------------
+
+/**
+ * A single item in the paste-ready output block.
+ * - `goLink`   — the short go-link to post (`<goBase>/<shortCode>`)
+ * - `taggedUrl` — the full destination + UTMs (reference / preview)
+ * - `label`    — human-readable context label (e.g. "YouTube — description",
+ *                "YouTube — pinned comment" for the `comment` placement)
+ * - `placement` — the raw placement value from the LinkResult
+ * - `kind`     — the share kind
+ */
+export interface ShareOutputItem {
+	goLink: string
+	taggedUrl: string
+	label: string
+	placement: string
+	kind: string
+}
+
+/** The structured result of `formatShareOutput`. */
+export interface ShareOutput {
+	items: ShareOutputItem[]
+}
+
+// ---------------------------------------------------------------------------
+// Placement label helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Bundle order for youtube placements (description → comment → bio).
+ * Used to sort the output items into the canonical §11 bundle order.
+ */
+const YOUTUBE_BUNDLE_ORDER: string[] = ['description', 'comment', 'bio']
+
+/**
+ * Returns the human-readable label for a placement.
+ *
+ * Special case: `comment` → "pinned comment"
+ * (The §11 brief's "pinned-comment" placement maps to the `comment` value;
+ * the go-link is posted as a pinned comment on the YouTube video.)
+ */
+function placementLabel(placement: string): string {
+	if (placement === 'comment') return 'pinned comment'
+	return placement
+}
+
+/**
+ * Returns the full context label for an output item.
+ * youtube items are prefixed "YouTube — <placement>" for clarity in the bundle.
+ */
+function itemLabel(kind: string, placement: string): string {
+	const pl = placementLabel(placement)
+	if (kind === 'youtube') return `YouTube — ${pl}`
+	if (kind === 'newsletter') return `Newsletter — ${pl}`
+	if (kind === 'owned-social') return `Owned social — ${pl}`
+	if (kind === 'author-social') return `Author social — ${pl}`
+	return `${kind} — ${pl}`
+}
+
+// ---------------------------------------------------------------------------
+// formatShareOutput
+// ---------------------------------------------------------------------------
+
+/**
+ * Formats the `POST /api/share-links/batch` response (`LinkResult[]`) into
+ * the operator's paste-ready output block.
+ *
+ * - Builds `goLink = ${goBase}/${shortCode}` for each result.
+ * - Attaches a human-readable context label (youtube `comment` → "pinned comment").
+ * - For youtube bundles, items are sorted into canonical bundle order
+ *   (description → comment/pinned-comment → bio); non-bundle placements are
+ *   appended in arrival order.
+ * - `goBase` is injected (pure, no `window`). Pass the site origin's `/go`
+ *   path or `https://go.fronts.co` at cutover.
+ *
+ * Returns a `ShareOutput` with a structured `items` array; use `toPlainText`
+ * for the "copy all" clipboard string.
+ */
+export function formatShareOutput(links: LinkResult[], opts: { goBase: string }): ShareOutput {
+	const { goBase } = opts
+	// Normalise the base — strip trailing slash so `${base}/${code}` is clean.
+	const base = goBase.replace(/\/+$/, '')
+
+	// Sort youtube links into bundle order; all others preserve arrival order.
+	const sorted = [...links].sort((a, b) => {
+		if (a.kind === 'youtube' && b.kind === 'youtube') {
+			const ai = YOUTUBE_BUNDLE_ORDER.indexOf(a.placement)
+			const bi = YOUTUBE_BUNDLE_ORDER.indexOf(b.placement)
+			// Known placements sort by bundle order; unknowns go to end.
+			const ao = ai === -1 ? Number.MAX_SAFE_INTEGER : ai
+			const bo = bi === -1 ? Number.MAX_SAFE_INTEGER : bi
+			return ao - bo
+		}
+		return 0 // preserve arrival order for non-youtube
+	})
+
+	const items: ShareOutputItem[] = sorted.map((link) => ({
+		goLink: `${base}/${link.shortCode}`,
+		taggedUrl: link.taggedUrl,
+		label: itemLabel(link.kind, link.placement),
+		placement: link.placement,
+		kind: link.kind,
+	}))
+
+	return { items }
+}
+
+// ---------------------------------------------------------------------------
+// toPlainText
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts a `ShareOutput` into a copy-friendly plaintext string for the
+ * "copy all" clipboard action.
+ *
+ * Format per item:
+ *   <label>
+ *   <goLink>
+ *   (<taggedUrl>)
+ *
+ * Multiple items are separated by a blank line.
+ */
+export function toPlainText(output: ShareOutput): string {
+	return output.items
+		.map((item) => `${item.label}\n${item.goLink}\n(${item.taggedUrl})`)
+		.join('\n\n')
+}
+
+// ---------------------------------------------------------------------------
+// relevantFields
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the set of form field names that are relevant/surfaced for the
+ * given mode. The React form renders only these inputs; the request builders
+ * read only these fields.
+ *
+ * 'author-social' → campaign, platform, author, handle, destinationUrl, advanced
+ * 'owned-social'  → campaign, platform, handle, (optional author), destinationUrl, advanced
+ * 'youtube'       → youtubeVideoId, placements, (optional handle/author), destinationUrl (NO campaign)
+ * 'newsletter'    → issue, (optional author/handle), destinationUrl (NO campaign/platform/boostMode)
+ */
+export function relevantFields(mode: ShareMode): string[] {
+	const shared = ['destinationUrl', 'contentSlug', 'contentType', 'property', 'sourcePath']
+
+	switch (mode) {
+		case 'author-social':
+			return [
+				...shared,
+				'campaign',
+				'platform',
+				'author',
+				'handle',
+				'placement',
+				'boostMode',
+				'promoCode',
+			]
+
+		case 'owned-social':
+			return [
+				...shared,
+				'campaign',
+				'platform',
+				'handle',
+				// author is optional for owned-social (brand handle is primary)
+				'placement',
+				'boostMode',
+				'promoCode',
+			]
+
+		case 'youtube':
+			// youtubeVideoId is the campaign key server-side; campaign not surfaced
+			return [
+				...shared,
+				'youtubeVideoId',
+				'placements',
+				'handle',
+				'placement',
+				'boostMode',
+				'promoCode',
+			]
+
+		case 'newsletter':
+			// newsletter: no campaign, no platform, no boostMode
+			return [...shared, 'issue', 'author', 'handle', 'placement', 'promoCode']
+	}
+}