@growth-labs/cms 0.1.0

package/src/providers/types.ts

@@ -0,0 +1,284 @@
+import type { SeoScoreInput, SeoScoreResult } from '../engine/seo.js'
+
+export type ProviderStatus = 'live' | 'partial' | 'empty'
+export interface ProviderResult<T> {
+	status: ProviderStatus
+	data: T
+}
+
+export interface DateRange {
+	from: number
+	to: number
+}
+
+export interface ArticleAnalyticsSource {
+	source: string
+	medium: string
+	campaign: string
+	derivedSource: string
+	reads: number
+	uniqueVisitors: number
+	sessions: number
+	paidStarts: number
+}
+
+export interface ArticleAnalyticsDetail {
+	id: string
+	slug: string
+	title: string
+	contentType: string
+	status?: string
+	canonicalUrl?: string
+	editUrl?: string
+	range: DateRange
+	freshness?: {
+		latestDate?: string
+		status: ProviderStatus
+	}
+	summary: {
+		reads: number
+		uniqueVisitors: number
+		sessions: number
+		avgReadSeconds: number
+		paidStarts: number
+		attributedRevenueCents: number
+		attributedAmountCents: number
+		attributedRevenueCurrency: string
+		revenueBackedStarts: number
+		conversionRateByReads: number
+		conversionRateBySessions: number
+	}
+	scrollDepth: {
+		scroll25: number
+		scroll50: number
+		scroll75: number
+		scroll90: number
+		scroll25Rate: number
+		scroll50Rate: number
+		scroll75Rate: number
+		scroll90Rate: number
+	}
+	readsTimeSeries: Array<{ t: number; reads: number }>
+	sources: ArticleAnalyticsSource[]
+}
+
+export interface AnalyticsProvider {
+	getKpis(range: DateRange): Promise<ProviderResult<Record<string, number>>>
+	getReadsTimeSeries(range: DateRange): Promise<ProviderResult<Array<{ t: number; reads: number }>>>
+	getTopContent(
+		range: DateRange,
+	): Promise<ProviderResult<Array<{ id: string; title: string; reads: number }>>>
+	getTrafficSources(
+		range: DateRange,
+	): Promise<ProviderResult<Array<{ source: string; sessions: number }>>>
+	getArticleDetail(slug: string, range: DateRange): Promise<ProviderResult<ArticleAnalyticsDetail>>
+}
+
+export interface SubscriptionMember {
+	id: string
+	email: string | null
+	planVariantId: string | null
+	status: string | null
+}
+
+// ---------------------------------------------------------------------------
+// Subscriptions-admin parity shapes (legacy Fronts /admin → Masthead provider).
+// Mirrors the three legacy admin tools the SubscriptionsProvider previously
+// could not express: duplicate-account detection, the LemonSqueezy entitlement
+// sync (a privileged WRITE), and gift-order claim/delivery tracking. The host
+// glue implements these against fronts-data / LemonSqueezy; the package wires
+// them to the injected provider and renders the ProviderResult honestly.
+// ---------------------------------------------------------------------------
+
+/** A set of accounts that share one normalized LemonSqueezy billing email. */
+export interface BillingConflictGroup {
+	billingEmail: string
+	accountCount: number
+	userIds: string[]
+	accountEmails: string[]
+	subscriptionIds: string[]
+	lastSeenAt: number | null
+}
+
+/** A set of accounts whose canonical email (gmail dot/plus-folded) collides. */
+export interface CanonicalConflictGroup {
+	canonicalEmail: string
+	accountCount: number
+	userIds: string[]
+	accountEmails: string[]
+	lastSeenAt: number | null
+}
+
+export interface DuplicateAccountsReport {
+	billingConflicts: BillingConflictGroup[]
+	canonicalConflicts: CanonicalConflictGroup[]
+	summary: {
+		billingConflictGroups: number
+		canonicalConflictGroups: number
+		impactedAccounts: number
+	}
+}
+
+/** Options for the LemonSqueezy entitlement sync (a host-side WRITE). */
+export interface LsImportOptions {
+	/** Preview only — count what would sync, mutate nothing. */
+	dryRun: boolean
+	/** Restrict the sync to a single LemonSqueezy store. */
+	storeId?: string
+	/** Include LemonSqueezy test-mode subscriptions in the sync. */
+	includeTest: boolean
+}
+
+/** Summary the sync returns: counts of users/subscriptions created or updated. */
+export interface LsImportSummary {
+	dryRun: boolean
+	synced: number
+	usersCreated: number
+	usersUpdated: number
+	subscriptionsCreated: number
+	subscriptionsUpdated: number
+	createdEmails: string[]
+	updatedEmails: string[]
+}
+
+/** A single gift order with its claim/delivery + linked-subscription state. */
+export interface GiftOrderRow {
+	id: string
+	gifterEmail: string
+	gifterName: string | null
+	recipientEmail: string
+	recipientName: string | null
+	giftMessage: string | null
+	subscriptionId: string | null
+	lemonsqueezyOrderId: string | null
+	planType: string
+	durationDays: number
+	status: string
+	redeemedAt: number | null
+	createdAt: number
+	updatedAt: number
+	subscriptionStatus: string | null
+	currentPeriodStart: number | null
+	currentPeriodEnd: number | null
+}
+
+/** Query for the paginated gift-orders list. */
+export interface GiftOrdersQuery {
+	q?: string
+	status?: string
+	page: number
+	pageSize: number
+}
+
+export interface GiftOrdersPage {
+	rows: GiftOrderRow[]
+	total: number
+	page: number
+	pageSize: number
+	totalPages: number
+	summary: {
+		redeemed: number
+		pendingClaim: number
+	}
+}
+
+export interface SubscriptionsProvider {
+	listMembers(
+		filter: Record<string, string | undefined>,
+		page: number,
+	): Promise<ProviderResult<SubscriptionMember[]>>
+	getKpis(): Promise<ProviderResult<Record<string, number | null>>>
+	getPlanMix(): Promise<ProviderResult<Array<{ plan: string; count: number }>>>
+	resolvePlanName(variantId: string): string
+	exportMembers(fmt: 'csv' | 'json'): Promise<ProviderResult<string>>
+	createGift(input: {
+		email: string
+		planVariantId: string
+	}): Promise<ProviderResult<{ id: string }>>
+	/**
+	 * Detect accounts that collide on billing email or canonical (gmail-folded)
+	 * email — READ-only. Legacy: GET /admin/api/duplicate-accounts.
+	 */
+	detectDuplicates(): Promise<ProviderResult<DuplicateAccountsReport>>
+	/**
+	 * Trigger the LemonSqueezy → DB entitlement sync — a privileged WRITE on the
+	 * host side (creates/updates users + subscriptions). The provider runs it and
+	 * returns a summary. Legacy: POST /admin/api/import-ls-entitlements.
+	 */
+	importLsEntitlements(opts: LsImportOptions): Promise<ProviderResult<LsImportSummary>>
+	/**
+	 * List gift orders with claim/delivery tracking — READ-only, paginated.
+	 * Legacy: GET /admin/api/gifts.
+	 */
+	listGifts(query: GiftOrdersQuery): Promise<ProviderResult<GiftOrdersPage>>
+}
+
+/** Thin identity seam — the CMS never mints identity (spec §3.3/§12). */
+export interface IdentityProvider {
+	getSubject(ctx: unknown): Promise<string | null>
+	mintOrAttachAccount(email: string): Promise<{ subject: string }>
+}
+
+export interface LlmDispatchInput {
+	task: string
+	prompt: string
+	stream?: boolean
+}
+export type LlmDispatchResult =
+	| { text: string; status?: 'ok' }
+	| { text: string; status: 'unavailable'; reason?: string }
+	| ReadableStream
+export interface LlmDispatch {
+	dispatch(input: LlmDispatchInput): Promise<LlmDispatchResult>
+}
+
+export interface FoundryJobSpec {
+	contentId: string
+	sourceUrl: string
+	sourceKind?: string
+	kind: string
+	videoId?: string
+	title?: string
+	description?: string | null
+	processingTriggerTokenHash?: string
+}
+export interface FoundryDispatch {
+	dispatchVideo(jobSpec: FoundryJobSpec): Promise<{ correlationId: string }>
+	getJob(correlationId: string): Promise<{ state: string } | null>
+}
+
+export interface SeoProvider {
+	scoreDraft(input: SeoScoreInput): Promise<SeoScoreResult>
+}
+
+export interface SearchProvider {
+	query(q: string): Promise<ProviderResult<Array<{ id: string; title: string; type: string }>>>
+}
+
+export interface CmsDomain {
+	hostname: string
+	status?: string | null
+	primary?: boolean
+	zone?: string | null
+}
+
+export interface CmsIntegrationStatus {
+	status: ProviderStatus
+	configured?: boolean
+	label?: string
+	detail?: string | null
+}
+
+export interface SettingsProvider {
+	listDomains(): Promise<ProviderResult<CmsDomain[]>>
+	getIntegrations(): Promise<ProviderResult<Record<string, CmsIntegrationStatus | null>>>
+}
+
+export interface CmsProviders {
+	analytics: AnalyticsProvider
+	subscriptions: SubscriptionsProvider
+	identity: IdentityProvider
+	seo: SeoProvider
+	search: SearchProvider
+	settings: SettingsProvider
+}