@coursebuilder/analytics 1.1.0

package/src/types.ts

@@ -0,0 +1,333 @@
+declare const __brand: unique symbol
+
+type Brand<T, B extends string> = T & { readonly [__brand]: B }
+
+export type USD = Brand<number, 'USD'>
+export type Count = Brand<number, 'Count'>
+export type Percentage = Brand<number, 'Percentage'>
+export type Minutes = Brand<number, 'Minutes'>
+export type Seconds = Brand<number, 'Seconds'>
+
+export type AnalyticsRange = '24h' | '7d' | '30d' | '90d' | 'all'
+
+export interface RevenueSummary {
+	totalRevenue: USD
+	purchaseCount: Count
+	avgOrderValue: USD
+}
+
+export interface RevenueDaily {
+	date: string
+	revenue: USD
+	count: Count
+}
+
+export interface RevenueByProduct {
+	productId: string
+	productName: string
+	revenue: USD
+	count: Count
+}
+
+export interface RevenueByCountry {
+	country: string
+	revenue: USD
+	count: Count
+}
+
+export interface RecentPurchase {
+	id: string
+	createdAt: Date
+	totalAmount: USD
+	productName: string
+	productId: string
+	country: string | null
+	couponId: string | null
+	userName: string | null
+	userEmail: string | null
+}
+
+export interface AttributionCount {
+	type: string
+	count: Count
+}
+
+export interface ShortlinkPerformance {
+	shortlinkId: string
+	slug: string
+	url: string
+	clicks: Count
+}
+
+export interface RevenueBySource {
+	source: string
+	medium: string
+	campaign: string | null
+	revenue: USD
+	count: Count
+}
+
+export interface ConversionFunnel {
+	totalSignups: Count
+	totalPurchases: Count
+	attributedPurchases: Count
+	unattributedPurchases: Count
+	conversionRate: Percentage
+	attributionCoverage: Percentage
+}
+
+export interface ContentCorrelation {
+	resourceId: string
+	purchaserCount: Count
+}
+
+export interface AttributionCoverage {
+	totalRevenue: USD
+	attributedRevenue: USD
+	unattributedRevenue: USD
+	attributionRate: Percentage
+	totalPurchases: Count
+}
+
+export interface TrafficOverview {
+	sessions: Count
+	totalUsers: Count
+	newUsers: Count
+	pageviews: Count
+	avgSessionDuration: Seconds
+	bounceRate: Percentage
+}
+
+export interface TrafficDaily {
+	date: string
+	sessions: Count
+	users: Count
+	pageviews: Count
+}
+
+export interface TopPage {
+	path: string
+	pageviews: Count
+	users: Count
+	avgDuration: Seconds
+}
+
+export interface TrafficSource {
+	source: string
+	medium: string
+	sessions: Count
+	users: Count
+}
+
+export interface YouTubeChannelOverview {
+	subscriberCount: Count
+	viewCount: Count
+	videoCount: Count
+}
+
+export interface YouTubeVideoPerformance {
+	videoId: string
+	views: Count
+	watchMinutes: Minutes
+	avgViewDuration: Seconds
+	subscribersGained: Count
+	likes: Count
+	comments: Count
+}
+
+export interface YouTubeDaily {
+	date: string
+	views: Count
+	watchMinutes: Minutes
+}
+
+export interface YouTubeTrafficSource {
+	source: string
+	views: Count
+	watchMinutes: Minutes
+}
+
+export interface TrafficRevenueCorrelation {
+	traffic: TrafficDaily[]
+	revenue: RevenueDaily[]
+}
+
+export interface YouTubeRevenueCorrelation {
+	youtube: YouTubeDaily[]
+	traffic: TrafficDaily[]
+	revenue: RevenueDaily[]
+}
+
+export interface SurveySummary {
+	totalSurveys: Count
+	totalResponses: Count
+	uniqueRespondents: Count
+	avgResponsesPerSurvey: number
+}
+
+export interface SurveyListItem {
+	surveyId: string
+	surveyTitle: string
+	surveySlug: string
+	responses: Count
+	uniqueRespondents: Count
+	questionCount: Count
+}
+
+export interface SurveyResponsesDaily {
+	date: string
+	responses: Count
+}
+
+export interface SurveyQuestionBreakdown {
+	questionId: string
+	question: string
+	type: string | null
+	responses: Count
+	answerDistribution: { answer: string; count: Count }[]
+}
+
+export interface SurveyConversionByQuestion {
+	questionId: string
+	questionTitle: string | null
+	answer: string
+	respondents: Count
+	purchasers: Count
+	conversionRate: Percentage
+	revenue: USD
+	prePurchaseCount: Count
+	postPurchaseCount: Count
+}
+
+// ─── Newsletter (Kit) email campaign types ───────────────────────────────────
+
+export interface EmailCampaignKitLink {
+	url: string
+	uniqueClicks: Count
+	clickToDeliveryRate: Percentage
+	clickToOpenRate: Percentage
+	shortlinkSlug?: string | null
+}
+
+export interface EmailCampaignShortlink {
+	slug: string
+	url: string
+	kitClicks: Count
+	clickToDeliveryRate?: Percentage
+	clickToOpenRate?: Percentage
+	shortlinkClicks: Count
+	signups: Count
+	purchases: Count
+	revenue: USD
+}
+
+export interface EmailCampaignFunnel {
+	broadcastId: number
+	subject: string
+	sentAt: string | null
+	recipients: Count
+	openRate: Percentage
+	emailsOpened?: Count
+	clickRate: Percentage
+	totalClicks: Count
+	showTotalClicks?: boolean
+	unsubscribes: Count
+	unsubscribeRate?: Percentage
+	progress?: Percentage
+	openTrackingDisabled?: boolean
+	clickTrackingDisabled?: boolean
+	kitLinks?: EmailCampaignKitLink[]
+	shortlinks: EmailCampaignShortlink[]
+	totalSignups: Count
+	totalPurchases: Count
+	totalRevenue: USD
+	clickToPurchaseRate: Percentage
+}
+
+export interface EmailRevenueOverview {
+	configured: boolean
+	totalBroadcasts: Count
+	totalRecipients: Count
+	totalRevenue: USD
+	campaigns: EmailCampaignFunnel[]
+}
+
+export interface SurveyResponseRow {
+	responseId: string
+	surveyId: string
+	surveyTitle: string
+	surveySlug: string
+	questionId: string
+	questionText: string
+	questionType: string | null
+	answer: string
+	userId: string | null
+	userEmail: string | null
+	emailListSubscriberId: string | null
+	createdAt: string
+}
+
+export interface SurveyRevenueCorrelation {
+	totalRespondents: Count
+	respondentsWhoPurchased: Count
+	overallConversionRate: Percentage
+	totalRevenueFromRespondents: USD
+	prePurchaseRespondents: Count
+	postPurchaseRespondents: Count
+	neverPurchasedRespondents: Count
+	baselineConversionRate: Percentage
+	byQuestion: SurveyConversionByQuestion[]
+}
+
+export interface SurfaceMap {
+	summary: RevenueSummary
+	'revenue/daily': RevenueDaily[]
+	'revenue/products': RevenueByProduct[]
+	'revenue/countries': RevenueByCountry[]
+	'purchases/recent': RecentPurchase[]
+	attribution: AttributionCount[]
+	'attribution/shortlinks': ShortlinkPerformance[]
+	'attribution/sources': RevenueBySource[]
+	'attribution/funnel': ConversionFunnel
+	'attribution/content': ContentCorrelation[]
+	'attribution/coverage': AttributionCoverage
+	traffic: TrafficOverview
+	'traffic/daily': TrafficDaily[]
+	'traffic/pages': TopPage[]
+	'traffic/sources': TrafficSource[]
+	youtube: YouTubeChannelOverview
+	'youtube/videos': YouTubeVideoPerformance[]
+	'youtube/daily': YouTubeDaily[]
+	'youtube/sources': YouTubeTrafficSource[]
+	'correlation/traffic-revenue': TrafficRevenueCorrelation
+	'correlation/youtube-revenue': YouTubeRevenueCorrelation
+	surveys: SurveySummary
+	'surveys/list': SurveyListItem[]
+	'surveys/daily': SurveyResponsesDaily[]
+	'surveys/questions': SurveyQuestionBreakdown[]
+	'surveys/responses': SurveyResponseRow[]
+	'correlation/survey-revenue': SurveyRevenueCorrelation
+	'attribution/email-campaigns': EmailRevenueOverview
+}
+
+export type SurfaceName = keyof SurfaceMap
+
+export interface QueryOptions {
+	range?: AnalyticsRange
+	limit?: number
+}
+
+export type QueryResult<S extends SurfaceName> =
+	| {
+			ok: true
+			surface: S
+			range: AnalyticsRange
+			data: SurfaceMap[S]
+			meta: { queryTimeMs: number; truncated: boolean }
+	  }
+	| {
+			ok: false
+			surface: S
+			error: { message: string; code: string }
+			fix: string
+	  }