@magnet-cms/plugin-polar 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,140 @@
+import { EnvVarRequirement, PluginMagnetProvider } from '@magnet-cms/common';
+
+/**
+ * Configuration for the Polar plugin.
+ *
+ * Passed via `PluginModule.forRoot({ plugins: [{ plugin: PolarPlugin, options: { ... } }] })`
+ * and injected in services via `@InjectPluginOptions('polar')`.
+ */
+interface PolarPluginConfig {
+    /** Polar access token (polar_at_...). Auto-resolved from POLAR_ACCESS_TOKEN env var. */
+    accessToken?: string;
+    /** Polar webhook signing secret. Auto-resolved from POLAR_WEBHOOK_SECRET env var. */
+    webhookSecret?: string;
+    /** Polar organization ID. Auto-resolved from POLAR_ORGANIZATION_ID env var. */
+    organizationId?: string;
+    /** Whether to sync products from Polar via webhooks (default: true) */
+    syncProducts?: boolean;
+    /** Default currency for checkout sessions (default: 'usd') */
+    currency?: string;
+    /**
+     * Feature flags per plan name.
+     * Map of product/plan name to list of feature identifiers.
+     *
+     * @example
+     * ```ts
+     * {
+     *   'pro': ['unlimited-servers', 'priority-support'],
+     *   'basic': ['5-servers'],
+     * }
+     * ```
+     */
+    features?: Record<string, string[]>;
+}
+/**
+ * Response from the subscription access endpoint.
+ */
+interface SubscriptionAccessResponse {
+    /** Whether the user has an active subscription */
+    hasActiveSubscription: boolean;
+    /** Plan/product name (null if no subscription) */
+    plan: string | null;
+    /** When the current period ends (null if no subscription) */
+    expiresAt: Date | null;
+    /** Feature flags for the user's plan */
+    features: string[];
+}
+/**
+ * Request body for creating a checkout session.
+ */
+interface CreateCheckoutDto {
+    /** List of Polar Product IDs to offer at checkout */
+    products: string[];
+    /** URL to redirect to on success */
+    successUrl?: string;
+    /** URL to redirect to when customer clicks back */
+    returnUrl?: string;
+    /** Optional customer email to pre-fill */
+    customerEmail?: string;
+    /** Optional Magnet user ID to associate with the customer via externalCustomerId */
+    userId?: string;
+    /** Optional metadata to attach to the checkout session */
+    metadata?: Record<string, string>;
+}
+/**
+ * Request body for creating a customer portal session.
+ */
+interface CreatePortalDto {
+    /** Polar Customer ID */
+    customerId?: string;
+    /** Magnet user ID (used to look up customer if customerId not provided) */
+    userId?: string;
+    /** URL to redirect to when the user is done */
+    returnUrl?: string;
+}
+/**
+ * Response from creating a checkout or portal session.
+ */
+interface SessionResponse {
+    /** Session ID */
+    sessionId: string;
+    /** URL to redirect the user to */
+    url: string;
+}
+/**
+ * Admin metrics response from the dashboard endpoint.
+ */
+interface PolarMetricsResponse {
+    /** Monthly Recurring Revenue in cents */
+    mrr: number;
+    /** Total revenue this month in cents */
+    revenueThisMonth: number;
+    /** Number of active subscriptions */
+    activeSubscriptions: number;
+    /** Churn rate as a percentage (0-100) */
+    churnRate: number;
+    /** Revenue data for the last 12 months */
+    revenueByMonth: Array<{
+        month: string;
+        revenue: number;
+    }>;
+    /** Recent orders */
+    recentOrders: Array<{
+        id: string;
+        totalAmount: number;
+        currency: string;
+        status: string;
+        customerEmail: string;
+        createdAt: string;
+    }>;
+}
+
+/**
+ * Polar Plugin
+ *
+ * Provides Polar.sh payment integration for Magnet CMS:
+ * - Product, subscription, and customer management
+ * - Webhook processing with idempotency
+ * - Checkout and Customer Portal sessions
+ * - Admin dashboard with revenue metrics
+ * - User subscription access and feature flags
+ * - Benefit management (license keys, downloads, etc.)
+ */
+declare class PolarPlugin {
+    /** Environment variables used by this plugin */
+    static readonly envVars: EnvVarRequirement[];
+    /**
+     * Create a configured plugin provider for MagnetModule.forRoot().
+     * Auto-resolves secret values from environment variables if not provided.
+     *
+     * @example
+     * ```typescript
+     * MagnetModule.forRoot([
+     *   PolarPlugin.forRoot({ currency: 'usd' }),
+     * ])
+     * ```
+     */
+    static forRoot(config?: Partial<PolarPluginConfig>): PluginMagnetProvider;
+}
+
+export { type CreateCheckoutDto, type CreatePortalDto, type PolarMetricsResponse, PolarPlugin, type PolarPluginConfig, type SessionResponse, type SubscriptionAccessResponse };

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+import { EnvVarRequirement, PluginMagnetProvider } from '@magnet-cms/common';
+
+/**
+ * Configuration for the Polar plugin.
+ *
+ * Passed via `PluginModule.forRoot({ plugins: [{ plugin: PolarPlugin, options: { ... } }] })`
+ * and injected in services via `@InjectPluginOptions('polar')`.
+ */
+interface PolarPluginConfig {
+    /** Polar access token (polar_at_...). Auto-resolved from POLAR_ACCESS_TOKEN env var. */
+    accessToken?: string;
+    /** Polar webhook signing secret. Auto-resolved from POLAR_WEBHOOK_SECRET env var. */
+    webhookSecret?: string;
+    /** Polar organization ID. Auto-resolved from POLAR_ORGANIZATION_ID env var. */
+    organizationId?: string;
+    /** Whether to sync products from Polar via webhooks (default: true) */
+    syncProducts?: boolean;
+    /** Default currency for checkout sessions (default: 'usd') */
+    currency?: string;
+    /**
+     * Feature flags per plan name.
+     * Map of product/plan name to list of feature identifiers.
+     *
+     * @example
+     * ```ts
+     * {
+     *   'pro': ['unlimited-servers', 'priority-support'],
+     *   'basic': ['5-servers'],
+     * }
+     * ```
+     */
+    features?: Record<string, string[]>;
+}
+/**
+ * Response from the subscription access endpoint.
+ */
+interface SubscriptionAccessResponse {
+    /** Whether the user has an active subscription */
+    hasActiveSubscription: boolean;
+    /** Plan/product name (null if no subscription) */
+    plan: string | null;
+    /** When the current period ends (null if no subscription) */
+    expiresAt: Date | null;
+    /** Feature flags for the user's plan */
+    features: string[];
+}
+/**
+ * Request body for creating a checkout session.
+ */
+interface CreateCheckoutDto {
+    /** List of Polar Product IDs to offer at checkout */
+    products: string[];
+    /** URL to redirect to on success */
+    successUrl?: string;
+    /** URL to redirect to when customer clicks back */
+    returnUrl?: string;
+    /** Optional customer email to pre-fill */
+    customerEmail?: string;
+    /** Optional Magnet user ID to associate with the customer via externalCustomerId */
+    userId?: string;
+    /** Optional metadata to attach to the checkout session */
+    metadata?: Record<string, string>;
+}
+/**
+ * Request body for creating a customer portal session.
+ */
+interface CreatePortalDto {
+    /** Polar Customer ID */
+    customerId?: string;
+    /** Magnet user ID (used to look up customer if customerId not provided) */
+    userId?: string;
+    /** URL to redirect to when the user is done */
+    returnUrl?: string;
+}
+/**
+ * Response from creating a checkout or portal session.
+ */
+interface SessionResponse {
+    /** Session ID */
+    sessionId: string;
+    /** URL to redirect the user to */
+    url: string;
+}
+/**
+ * Admin metrics response from the dashboard endpoint.
+ */
+interface PolarMetricsResponse {
+    /** Monthly Recurring Revenue in cents */
+    mrr: number;
+    /** Total revenue this month in cents */
+    revenueThisMonth: number;
+    /** Number of active subscriptions */
+    activeSubscriptions: number;
+    /** Churn rate as a percentage (0-100) */
+    churnRate: number;
+    /** Revenue data for the last 12 months */
+    revenueByMonth: Array<{
+        month: string;
+        revenue: number;
+    }>;
+    /** Recent orders */
+    recentOrders: Array<{
+        id: string;
+        totalAmount: number;
+        currency: string;
+        status: string;
+        customerEmail: string;
+        createdAt: string;
+    }>;
+}
+
+/**
+ * Polar Plugin
+ *
+ * Provides Polar.sh payment integration for Magnet CMS:
+ * - Product, subscription, and customer management
+ * - Webhook processing with idempotency
+ * - Checkout and Customer Portal sessions
+ * - Admin dashboard with revenue metrics
+ * - User subscription access and feature flags
+ * - Benefit management (license keys, downloads, etc.)
+ */
+declare class PolarPlugin {
+    /** Environment variables used by this plugin */
+    static readonly envVars: EnvVarRequirement[];
+    /**
+     * Create a configured plugin provider for MagnetModule.forRoot().
+     * Auto-resolves secret values from environment variables if not provided.
+     *
+     * @example
+     * ```typescript
+     * MagnetModule.forRoot([
+     *   PolarPlugin.forRoot({ currency: 'usd' }),
+     * ])
+     * ```
+     */
+    static forRoot(config?: Partial<PolarPluginConfig>): PluginMagnetProvider;
+}
+
+export { type CreateCheckoutDto, type CreatePortalDto, type PolarMetricsResponse, PolarPlugin, type PolarPluginConfig, type SessionResponse, type SubscriptionAccessResponse };

package/dist/index.js

@@ -0,0 +1 @@
+export { PolarPlugin } from './chunk-7KT7JQIH.js';

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@magnet-cms/plugin-polar",
+  "version": "0.1.0",
+  "description": "Polar.sh payments plugin for Magnet CMS — products, subscriptions, webhooks, and admin dashboard",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./backend": {
+      "import": {
+        "types": "./dist/backend/index.d.ts",
+        "default": "./dist/backend/index.js"
+      },
+      "require": {
+        "types": "./dist/backend/index.d.cts",
+        "default": "./dist/backend/index.cjs"
+      }
+    },
+    "./frontend": {
+      "import": "./src/admin/index.ts",
+      "types": "./src/admin/index.ts"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/admin"
+  ],
+  "scripts": {
+    "build:dev": "tsup --watch",
+    "build": "tsup && bun run build:frontend",
+    "build:frontend": "vite build",
+    "build:frontend:watch": "vite build --watch"
+  },
+  "devDependencies": {
+    "@magnet-cms/admin": "workspace:*",
+    "@magnet-cms/common": "workspace:*",
+    "@magnet-cms/core": "workspace:*",
+    "@magnet-cms/ui": "workspace:*",
+    "@magnet-cms/utils": "workspace:*",
+    "@nestjs/common": "^11.1.12",
+    "@polar-sh/sdk": "0.46.4",
+    "@repo/biome": "workspace:*",
+    "@repo/tsup": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "@types/react": "^19.0.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "lucide-react": "^0.468.0",
+    "react": "^19.0.0",
+    "react-router-dom": "^7.1.1",
+    "recharts": "^2.15.0",
+    "reflect-metadata": "0.2.2",
+    "vite": "^6.0.7"
+  },
+  "peerDependencies": {
+    "@magnet-cms/admin": "^0.1.2",
+    "@magnet-cms/common": "^0.1.0",
+    "@magnet-cms/core": "^1.0.3",
+    "@magnet-cms/ui": "^0.1.0",
+    "@magnet-cms/utils": "^0.1.0",
+    "@nestjs/common": "^11.1.12",
+    "@polar-sh/sdk": "^0.46.0",
+    "lucide-react": ">=0.400.0",
+    "react": ">=18.0.0",
+    "react-router-dom": ">=6.0.0",
+    "reflect-metadata": "0.2.2"
+  },
+  "magnet": {
+    "type": "plugin",
+    "backend": true,
+    "frontend": true
+  }
+}

package/src/admin/components/recent-orders.tsx

@@ -0,0 +1,80 @@
+import {
+	Badge,
+	DataTable,
+	type DataTableColumn,
+} from '@magnet-cms/ui/components'
+
+interface RecentOrder {
+	id: string
+	totalAmount: number
+	currency: string
+	status: string
+	customerEmail: string
+	createdAt: string
+}
+
+interface RecentOrdersProps {
+	orders: RecentOrder[]
+}
+
+function formatCurrency(cents: number, currency: string): string {
+	return `${currency.toUpperCase()} $${(cents / 100).toFixed(2)}`
+}
+
+function getStatusVariant(
+	status: string,
+): 'default' | 'secondary' | 'destructive' {
+	switch (status) {
+		case 'paid':
+			return 'default'
+		case 'refunded':
+			return 'destructive'
+		default:
+			return 'secondary'
+	}
+}
+
+const columns: DataTableColumn<RecentOrder>[] = [
+	{
+		type: 'text',
+		header: 'Amount',
+		accessorKey: 'totalAmount',
+		format: (_value, row) => formatCurrency(row.totalAmount, row.currency),
+	},
+	{
+		type: 'custom',
+		header: 'Status',
+		cell: (row) => (
+			<Badge variant={getStatusVariant(row.original.status)}>
+				{row.original.status}
+			</Badge>
+		),
+	},
+	{
+		type: 'text',
+		header: 'Customer',
+		accessorKey: 'customerEmail',
+		format: (value) => (
+			<span className="font-mono text-sm">{value as string}</span>
+		),
+	},
+	{
+		type: 'text',
+		header: 'Date',
+		accessorKey: 'createdAt',
+		format: (value) => new Date(value as string).toLocaleDateString(),
+	},
+]
+
+export function RecentOrders({ orders }: RecentOrdersProps) {
+	return (
+		<DataTable
+			data={orders}
+			columns={columns}
+			getRowId={(row) => row.id}
+			showCount={false}
+			className="border rounded-lg"
+			variant="content-manager"
+		/>
+	)
+}

package/src/admin/components/revenue-chart.tsx

@@ -0,0 +1,56 @@
+import {
+	ChartContainer,
+	ChartTooltip,
+	ChartTooltipContent,
+} from '@magnet-cms/ui/components'
+import type { ChartConfig } from '@magnet-cms/ui/components'
+import { Bar, BarChart, CartesianGrid, XAxis, YAxis } from 'recharts'
+
+interface RevenueChartProps {
+	data: Array<{ month: string; revenue: number }>
+}
+
+const chartConfig: ChartConfig = {
+	revenue: {
+		label: 'Revenue',
+		color: 'hsl(var(--chart-1))',
+	},
+}
+
+function formatCurrency(cents: number): string {
+	return `$${(cents / 100).toFixed(0)}`
+}
+
+export function RevenueChart({ data }: RevenueChartProps) {
+	return (
+		<ChartContainer config={chartConfig} className="h-[300px] w-full">
+			<BarChart data={data}>
+				<CartesianGrid strokeDasharray="3 3" vertical={false} />
+				<XAxis
+					dataKey="month"
+					tickLine={false}
+					axisLine={false}
+					fontSize={12}
+				/>
+				<YAxis
+					tickLine={false}
+					axisLine={false}
+					fontSize={12}
+					tickFormatter={formatCurrency}
+				/>
+				<ChartTooltip
+					content={
+						<ChartTooltipContent
+							formatter={(value) => formatCurrency(Number(value))}
+						/>
+					}
+				/>
+				<Bar
+					dataKey="revenue"
+					fill="var(--color-revenue)"
+					radius={[4, 4, 0, 0]}
+				/>
+			</BarChart>
+		</ChartContainer>
+	)
+}

package/src/admin/components/subscription-metrics.tsx

@@ -0,0 +1,65 @@
+import { Card } from '@magnet-cms/ui/components'
+import { CreditCard, DollarSign, TrendingDown, Users } from 'lucide-react'
+
+interface MetricCardProps {
+	title: string
+	value: string
+	icon: React.ReactNode
+}
+
+function MetricCard({ title, value, icon }: MetricCardProps) {
+	return (
+		<Card className="p-6">
+			<div className="flex items-center justify-between">
+				<div>
+					<p className="text-sm font-medium text-muted-foreground">{title}</p>
+					<p className="text-2xl font-bold mt-1">{value}</p>
+				</div>
+				<div className="text-muted-foreground">{icon}</div>
+			</div>
+		</Card>
+	)
+}
+
+interface SubscriptionMetricsProps {
+	mrr: number
+	revenueThisMonth: number
+	activeSubscriptions: number
+	churnRate: number
+}
+
+function formatCurrency(cents: number): string {
+	return `$${(cents / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}`
+}
+
+export function SubscriptionMetrics({
+	mrr,
+	revenueThisMonth,
+	activeSubscriptions,
+	churnRate,
+}: SubscriptionMetricsProps) {
+	return (
+		<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+			<MetricCard
+				title="Monthly Recurring Revenue"
+				value={formatCurrency(mrr)}
+				icon={<DollarSign className="h-5 w-5" />}
+			/>
+			<MetricCard
+				title="Revenue This Month"
+				value={formatCurrency(revenueThisMonth)}
+				icon={<CreditCard className="h-5 w-5" />}
+			/>
+			<MetricCard
+				title="Active Subscriptions"
+				value={String(activeSubscriptions)}
+				icon={<Users className="h-5 w-5" />}
+			/>
+			<MetricCard
+				title="Churn Rate"
+				value={`${churnRate}%`}
+				icon={<TrendingDown className="h-5 w-5" />}
+			/>
+		</div>
+	)
+}

package/src/admin/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Polar Plugin - Frontend Entry
+ *
+ * Self-registers the plugin when loaded via script injection.
+ * The admin app loads plugin bundles at runtime and plugins self-register
+ * on window.__MAGNET_PLUGINS__.
+ */
+
+import type { ComponentType } from 'react'
+
+interface FrontendPluginManifest {
+	pluginName: string
+	routes?: {
+		path: string
+		componentId: string
+		children?: { path: string; componentId: string }[]
+	}[]
+	sidebar?: {
+		id: string
+		title: string
+		url: string
+		icon: string
+		order?: number
+		items?: { id: string; title: string; url: string; icon: string }[]
+	}[]
+}
+
+interface PluginRegistration {
+	manifest: FrontendPluginManifest
+	components: Record<string, () => Promise<{ default: ComponentType<unknown> }>>
+}
+
+const manifest: FrontendPluginManifest = {
+	pluginName: 'polar',
+	routes: [
+		{
+			path: 'polar',
+			componentId: 'PolarDashboard',
+			children: [
+				{ path: '', componentId: 'PolarDashboard' },
+				{ path: 'customers', componentId: 'PolarCustomers' },
+				{ path: 'products', componentId: 'PolarProducts' },
+				{ path: 'subscriptions', componentId: 'PolarSubscriptions' },
+				{ path: 'orders', componentId: 'PolarOrders' },
+				{ path: 'benefits', componentId: 'PolarBenefits' },
+			],
+		},
+	],
+	sidebar: [
+		{
+			id: 'polar',
+			title: 'Polar Payments',
+			url: '/polar',
+			icon: 'Zap',
+			order: 31,
+			items: [
+				{
+					id: 'polar-dashboard',
+					title: 'Dashboard',
+					url: '/polar',
+					icon: 'BarChart3',
+				},
+				{
+					id: 'polar-customers',
+					title: 'Customers',
+					url: '/polar/customers',
+					icon: 'Users',
+				},
+				{
+					id: 'polar-products',
+					title: 'Products',
+					url: '/polar/products',
+					icon: 'Package',
+				},
+				{
+					id: 'polar-subscriptions',
+					title: 'Subscriptions',
+					url: '/polar/subscriptions',
+					icon: 'RefreshCw',
+				},
+				{
+					id: 'polar-orders',
+					title: 'Orders',
+					url: '/polar/orders',
+					icon: 'Receipt',
+				},
+				{
+					id: 'polar-benefits',
+					title: 'Benefits',
+					url: '/polar/benefits',
+					icon: 'Gift',
+				},
+			],
+		},
+	],
+}
+
+const components: Record<
+	string,
+	() => Promise<{ default: ComponentType<unknown> }>
+> = {
+	PolarDashboard: () => import('./pages/polar-dashboard'),
+	PolarCustomers: () => import('./pages/customers'),
+	PolarProducts: () => import('./pages/products'),
+	PolarSubscriptions: () => import('./pages/subscriptions'),
+	PolarOrders: () => import('./pages/orders'),
+	PolarBenefits: () => import('./pages/benefits'),
+}
+
+function registerPlugin() {
+	if (!window.__MAGNET_PLUGINS__) {
+		window.__MAGNET_PLUGINS__ = []
+	}
+
+	const alreadyRegistered = window.__MAGNET_PLUGINS__.some(
+		(p) => p.manifest.pluginName === manifest.pluginName,
+	)
+
+	if (!alreadyRegistered) {
+		window.__MAGNET_PLUGINS__.push({ manifest, components })
+		console.log(`[Magnet] Plugin registered: ${manifest.pluginName}`)
+	}
+}
+
+registerPlugin()
+
+export const polarPlugin = () => ({ manifest, components })
+export default polarPlugin