@coursebuilder/analytics 1.1.0 → 1.1.2-canary.0.0c9beb2ae

package/src/providers/attribution-recovery.ts

@@ -0,0 +1,97 @@
+export const SHORTLINK_RECOVERY_LANE =
+	'recovered_from_shortlink_attribution_table' as const
+
+export type PurchaseAttributionClass =
+	| 'purchase_field'
+	| typeof SHORTLINK_RECOVERY_LANE
+	| 'dark'
+
+export interface ShortlinkAttributionEvidence {
+	type?: string | null
+	metadata?: unknown
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function nonEmptyString(value: unknown) {
+	return typeof value === 'string' && value.trim().length > 0
+}
+
+function parseMetadata(value: unknown): Record<string, unknown> | null {
+	if (typeof value === 'string') {
+		try {
+			const parsed = JSON.parse(value) as unknown
+			return isRecord(parsed) ? parsed : null
+		} catch {
+			return null
+		}
+	}
+
+	return isRecord(value) ? value : null
+}
+
+/**
+ * Detects durable purchase-field attribution on a purchase fields object.
+ *
+ * @param fields Unknown purchase fields payload.
+ * @returns True when the purchase already has attribution, legacy UTM source, or legacy GA client ID evidence.
+ * @example
+ * hasPurchaseFieldAttribution({ attribution: { source: 'email' } })
+ */
+export function hasPurchaseFieldAttribution(fields: unknown) {
+	const record = isRecord(fields) ? fields : {}
+	const attribution = record.attribution
+
+	return Boolean(
+		(isRecord(attribution) && Object.keys(attribution).length > 0) ||
+		nonEmptyString(record.utmSource) ||
+		nonEmptyString(record.gaClientId),
+	)
+}
+
+/**
+ * Detects exact shortlink purchase evidence for one purchase.
+ *
+ * @param params.purchaseId Purchase ID that must match attribution metadata.purchaseId.
+ * @param params.attributions ShortlinkAttributionEvidence rows to inspect.
+ * @returns True only for purchase rows with valid JSON metadata and an exact purchase ID match.
+ */
+export function hasExactShortlinkPurchaseAttribution(params: {
+	purchaseId: string
+	attributions: readonly ShortlinkAttributionEvidence[]
+}) {
+	return params.attributions.some((attribution) => {
+		if (attribution.type !== 'purchase') return false
+		const metadata = parseMetadata(attribution.metadata)
+		return metadata?.purchaseId === params.purchaseId
+	})
+}
+
+/**
+ * Classifies purchase attribution with purchase fields taking precedence.
+ *
+ * @param params.purchaseId Purchase ID being classified.
+ * @param params.fields Purchase fields payload.
+ * @param params.shortlinkAttributions ShortlinkAttributionEvidence rows used as exact fallback evidence.
+ * @returns A PurchaseAttributionClass: 'purchase_field', SHORTLINK_RECOVERY_LANE, or 'dark'.
+ * @example
+ * classifyPurchaseAttribution({ purchaseId: 'p1', fields: {}, shortlinkAttributions: [] })
+ */
+export function classifyPurchaseAttribution(params: {
+	purchaseId: string
+	fields?: unknown
+	shortlinkAttributions?: readonly ShortlinkAttributionEvidence[]
+}): PurchaseAttributionClass {
+	if (hasPurchaseFieldAttribution(params.fields)) return 'purchase_field'
+	if (
+		hasExactShortlinkPurchaseAttribution({
+			purchaseId: params.purchaseId,
+			attributions: params.shortlinkAttributions ?? [],
+		})
+	) {
+		return SHORTLINK_RECOVERY_LANE
+	}
+	return 'dark'
+}