webspresso 0.0.93 → 0.0.94

package/plugins/polar/README.md

@@ -0,0 +1,158 @@
+# Polar.sh Billing Plugin for Webspresso
+
+Production-ready Polar subscription billing for Webspresso. Zero extra dependencies (`crypto` + native `fetch` only).
+
+## Quick start
+
+### 1. Environment
+
+Copy `plugins/polar/.env.example` → `.env`:
+
+```bash
+POLAR_ACCESS_TOKEN=polar_oat_...
+POLAR_WEBHOOK_SECRET=whsec_...
+POLAR_PRO_PRODUCT_ID=<product-uuid-not-price-id>
+POLAR_ORG_SLUG=your-org
+POLAR_SANDBOX=false
+BASE_URL=https://example.com
+```
+
+### 2. Migration
+
+```bash
+webspresso polar:migrate
+webspresso db:migrate
+```
+
+### 3. Plugin config (~3 lines)
+
+```js
+const { polarPlugin, rateLimitPlugin } = require('webspresso/plugins');
+const { quickAuth } = require('webspresso/core/auth');
+
+createApp({
+  db,
+  auth: quickAuth({ db, jwt: true }),
+  plugins: [
+    rateLimitPlugin(), // optional but recommended — polar applies per-route limits
+    polarPlugin({
+      db,
+      userModel: 'User',
+      plans: { pro_monthly: process.env.POLAR_PRO_PRODUCT_ID },
+      tierMapping: { pro: ['pro_monthly'], free: [] },
+    }),
+  ],
+});
+```
+
+That's it — routes, webhooks, checkout, portal, and status API are auto-mounted.
+
+### 4. Polar Dashboard webhook
+
+- **URL:** `https://your-domain.com/api/v1/polar/webhook`
+- **Format:** Raw (not Slack/Discord)
+- **Events:** `customer.state_changed`, `subscription.*`, `order.*`, `checkout.updated`
+
+## Routes (defaults, all configurable)
+
+| Method | Path | Auth | Behavior |
+|--------|------|------|----------|
+| POST | `/api/v1/polar/webhook` | HMAC signature | Process Polar events |
+| GET/POST | `/settings/billing/checkout` | session/JWT | Sync → Polar checkout redirect |
+| GET | `/settings/billing/portal` | session/JWT | Customer portal redirect |
+| GET | `/api/v1/billing/status` | session/JWT | Sync + JSON billing status |
+
+## Template usage
+
+```njk
+{% if user.tier == 'pro' %}
+  <p>Pro until {{ user.polar_current_period_end | dateLabel }}</p>
+  <a href="/settings/billing/portal">Manage subscription</a>
+{% else %}
+  <form method="post" action="/settings/billing/checkout">
+    <button type="submit">Upgrade to Pro</button>
+  </form>
+{% endif %}
+```
+
+## SDK exports (`plugin.api` or direct imports)
+
+```js
+const polar = polarPlugin({ db });
+polar.api.verifyPolarWebhook(raw, headers, secret);
+polar.api.syncPolarBillingForUser(user, knex);
+polar.api.getPolarCheckoutUrl({ user, plan: 'pro_monthly', baseUrl });
+polar.api.handlePolarWebhookEvent(event, knex);
+polar.api.generateMigration();
+polar.api.parseEnv(process.env);
+```
+
+## Webhook raw body (production)
+
+For strict HMAC verification, mount **before** `express.json()`:
+
+```js
+const { createWebhookRawBodyMiddleware } = require('webspresso/plugins/polar/src/webhooks');
+
+app.use(createWebhookRawBodyMiddleware('/api/v1/polar/webhook'));
+app.use(express.json());
+```
+
+Without this, the plugin falls back to `JSON.stringify(req.body)` (works for most cases; key order edge cases possible).
+
+## Rate limiting
+
+Enabled by default (`rateLimit: true`). Requires `rateLimitPlugin()` registered **before** `polarPlugin`:
+
+| Route | Default |
+|-------|---------|
+| Webhook | 120 req/min (by IP) |
+| Checkout | 5 req/min (by user) |
+| Portal | 10 req/min (by user) |
+| Status | 60 req/min (by user) |
+
+```js
+polarPlugin({ db, rateLimit: false }); // disable
+polarPlugin({ db, rateLimit: { checkout: { limit: 3 } } }); // override
+```
+
+## Optional hooks
+
+```js
+polarPlugin({
+  db,
+  hooks: {
+    onSubscriptionChange({ user, tier, polarStatus, subscription, knex, update }) {
+      // Custom tier logic (default: updates users.* polar columns)
+      return knex('users').where('id', user.id).update(update);
+    },
+  },
+  syncMiddleware: {
+    when: (req) => req.query.tab === 'billing',
+  },
+});
+```
+
+## CSP (Helmet)
+
+```js
+const { polarCspDirectives } = require('webspresso/plugins/polar/src/urls');
+
+createApp({
+  helmet: {
+    contentSecurityPolicy: {
+      directives: {
+        ...polarCspDirectives(),
+      },
+    },
+  },
+});
+```
+
+Or rely on the plugin's built-in `csp` export (auto-merged by plugin manager).
+
+## Non-goals (v1)
+
+- Admin UI (use Polar dashboard)
+- Multi-org / team seat billing
+- `@polar-sh/sdk` dependency

package/plugins/polar/index.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * Polar.sh billing plugin for Webspresso
+ * @module plugins/polar
+ */
+
+const { resolvePolarConfig } = require('./src/config');
+const { polarEnvSchema, parsePolarEnv } = require('./src/env.schema');
+const { polarApiRequest } = require('./src/api');
+const { verifyPolarWebhook, handlePolarWebhookEvent, createWebhookRawBodyMiddleware } = require('./src/webhooks');
+const { getPolarCheckoutUrl } = require('./src/checkout');
+const { getPolarPortalUrl } = require('./src/portal');
+const { syncPolarBillingForUser } = require('./src/sync');
+const {
+  resolveUserFromPolarData,
+  buildCheckoutMetadata,
+  isProSubscriptionStatus,
+  userHasProTier,
+  pickBestActiveSubscription,
+} = require('./src/user-resolver');
+const {
+  isValidCheckoutRedirectUrl,
+  isValidPortalRedirectUrl,
+  extractCheckoutUrlFromResponse,
+  polarCspDirectives,
+} = require('./src/urls');
+const { generatePolarMigration } = require('./src/migration');
+const { polarSyncMiddleware } = require('./src/middleware');
+const { registerNunjucksFilters, dateLabel } = require('./src/nunjucks-filters');
+const {
+  createInjectDb,
+  createWebhookHandler,
+  createCheckoutHandler,
+  createPortalHandler,
+  createStatusHandler,
+  createRequireAuth,
+} = require('./src/routes');
+const { resolvePolarRateLimiters, DEFAULT_RATE_LIMITS } = require('./src/rate-limit');
+
+/**
+ * @param {Object} options
+ * @param {import('../../core/orm/database').Database} options.db
+ * @param {string} [options.userModel='User']
+ * @param {string} [options.userTable='users']
+ * @param {Record<string, string>} [options.plans]
+ * @param {Record<string, string[]>} [options.tierMapping]
+ * @param {Object} [options.routes]
+ * @param {Object} [options.urls]
+ * @param {Object} [options.fields]
+ * @param {Object} [options.hooks]
+ * @param {Function} [options.requireAuth]
+ * @param {boolean} [options.enabled=true]
+ */
+function polarPlugin(options = {}) {
+  const config = resolvePolarConfig(options);
+  let runtimeConfig = config;
+
+  const sdk = {
+    verifyPolarWebhook,
+    polarApiRequest: (path, opts = {}) => polarApiRequest(path, {
+      ...opts,
+      accessToken: opts.accessToken || runtimeConfig.accessToken,
+      sandbox: opts.sandbox !== undefined ? opts.sandbox : runtimeConfig.sandbox,
+    }),
+    getPolarCheckoutUrl: (params) => getPolarCheckoutUrl({ ...params, config: runtimeConfig }),
+    getPolarPortalUrl: (user, baseUrl) => getPolarPortalUrl(user, baseUrl, runtimeConfig),
+    syncPolarBillingForUser: (user, knex) => syncPolarBillingForUser(user, knex, runtimeConfig),
+    handlePolarWebhookEvent: (event, knex, hooks) => handlePolarWebhookEvent(event, knex, runtimeConfig, hooks),
+    resolveUserFromPolarData: (data, knex) => resolveUserFromPolarData(data, knex, runtimeConfig),
+    extractCheckoutUrlFromResponse: (data) => extractCheckoutUrlFromResponse(data, runtimeConfig.sandbox),
+    isValidCheckoutRedirectUrl,
+    isValidPortalRedirectUrl,
+    buildCheckoutMetadata: (user, customFields) => buildCheckoutMetadata(user, runtimeConfig, customFields),
+    userHasProTier: (user) => userHasProTier(user, runtimeConfig),
+    isProSubscriptionStatus,
+    pickBestActiveSubscription: (subs) => pickBestActiveSubscription(subs, runtimeConfig),
+    generateMigration: (opts) => generatePolarMigration({ ...opts, fields: runtimeConfig.fields }),
+    polarSyncMiddleware: (opts) => polarSyncMiddleware(runtimeConfig, opts),
+    polarCspDirectives,
+    createWebhookRawBodyMiddleware,
+    registerNunjucksFilters,
+    dateLabel,
+    parseEnv: parsePolarEnv,
+    envSchema: polarEnvSchema,
+    getConfig: () => ({ ...runtimeConfig }),
+    defaultRateLimits: DEFAULT_RATE_LIMITS,
+  };
+
+  return {
+    name: 'polar',
+    version: '1.0.0',
+    description: 'Polar.sh subscription billing — checkout, portal, webhooks, and tier sync',
+
+    csp: polarCspDirectives(),
+
+    api: sdk,
+
+    register(ctx) {
+      runtimeConfig = resolvePolarConfig({ ...options, db: options.db || ctx.db });
+      if (!runtimeConfig.enabled) return;
+
+      registerNunjucksFilters(ctx.nunjucksEnv);
+
+      if (runtimeConfig.syncMiddleware) {
+        ctx.app.use(polarSyncMiddleware(runtimeConfig));
+      }
+    },
+
+    onRoutesReady(ctx) {
+      runtimeConfig = resolvePolarConfig({ ...options, db: options.db || ctx.db });
+      if (!runtimeConfig.enabled) return;
+
+      const db = runtimeConfig.db || ctx.db;
+      if (!db) {
+        console.warn('[polar] Skipping routes: no database (pass options.db or createApp({ db }))');
+        return;
+      }
+
+      const injectDb = createInjectDb(db);
+      const requireAuth = createRequireAuth(runtimeConfig, ctx);
+      const { routes } = runtimeConfig;
+      const rl = resolvePolarRateLimiters(ctx, runtimeConfig);
+
+      const chain = (...handlers) => handlers.filter(Boolean);
+
+      ctx.addRoute('post', routes.webhook, ...chain(injectDb, rl.webhook, createWebhookHandler(runtimeConfig)));
+      ctx.addRoute('post', routes.checkout, ...chain(injectDb, requireAuth, rl.checkout, createCheckoutHandler(runtimeConfig)));
+      ctx.addRoute('get', routes.checkout, ...chain(injectDb, requireAuth, rl.checkout, createCheckoutHandler(runtimeConfig)));
+      ctx.addRoute('get', routes.portal, ...chain(injectDb, requireAuth, rl.portal, createPortalHandler(runtimeConfig)));
+      ctx.addRoute('get', routes.status, ...chain(injectDb, requireAuth, rl.status, createStatusHandler(runtimeConfig)));
+
+      if (process.env.NODE_ENV !== 'production') {
+        console.log(`  Polar billing: POST ${routes.webhook}`);
+        console.log(`  Polar billing: GET/POST ${routes.checkout}`);
+        console.log(`  Polar billing: GET ${routes.portal}`);
+        console.log(`  Polar billing: GET ${routes.status}`);
+      }
+    },
+  };
+}
+
+module.exports = polarPlugin;
+module.exports.polarPlugin = polarPlugin;

package/plugins/polar/src/api.js

@@ -0,0 +1,54 @@
+'use strict';
+
+function getPolarApiBase(sandbox) {
+  return sandbox ? 'https://sandbox-api.polar.sh/v1' : 'https://api.polar.sh/v1';
+}
+
+/**
+ * @param {string} path
+ * @param {Object} opts
+ * @param {string} opts.method
+ * @param {Object} [opts.body]
+ * @param {string} opts.accessToken
+ * @param {boolean} [opts.sandbox=false]
+ */
+async function polarApiRequest(path, { method = 'GET', body, accessToken, sandbox = false } = {}) {
+  if (!accessToken) {
+    throw new Error('POLAR_ACCESS_TOKEN is not configured');
+  }
+
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  const res = await fetch(`${getPolarApiBase(sandbox)}${normalizedPath}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const raw = await res.text();
+  let data = null;
+  if (raw) {
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      data = { raw };
+    }
+  }
+
+  if (!res.ok) {
+    const detail = typeof data?.detail === 'string'
+      ? data.detail
+      : JSON.stringify(data?.detail || data?.error || data?.error_description || raw).slice(0, 500);
+    throw new Error(`Polar API ${res.status}: ${detail}`);
+  }
+
+  return data || {};
+}
+
+module.exports = {
+  getPolarApiBase,
+  polarApiRequest,
+};

package/plugins/polar/src/checkout.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { polarApiRequest } = require('./api');
+const { buildCheckoutMetadata } = require('./user-resolver');
+const {
+  extractCheckoutUrlFromResponse,
+  isValidCheckoutRedirectUrl,
+  getPolarBuyBase,
+} = require('./urls');
+
+function resolvePlanProductId(plan, config) {
+  if (config.plans[plan]) return config.plans[plan];
+  if (plan === 'pro_yearly') {
+    return config.plans.pro_yearly || config.plans.pro_monthly;
+  }
+  return config.plans.pro_monthly;
+}
+
+function resolveHostedCheckoutBaseUrl(config) {
+  if (config.checkoutUrl) return config.checkoutUrl;
+
+  const productId = resolvePlanProductId('pro_monthly', config);
+  if (productId && productId.startsWith('polar_cl_')) {
+    return `${getPolarBuyBase(config.sandbox)}/${productId}`;
+  }
+
+  return null;
+}
+
+function buildHostedCheckoutUrl(hostedUrl, user, config) {
+  const url = new URL(hostedUrl);
+  const f = config.fields;
+  if (user[f.email]) url.searchParams.set('email', user[f.email]);
+  url.searchParams.set('metadata[user_id]', String(user[f.id]));
+  if (user[f.publicId]) url.searchParams.set('metadata[public_id]', user[f.publicId]);
+  return url.toString();
+}
+
+async function createCheckoutSessionViaApi({ user, productId, baseUrl, config }) {
+  const metadata = buildCheckoutMetadata(user, config);
+  const f = config.fields;
+  const shared = {
+    success_url: config.urls.success.startsWith('http')
+      ? config.urls.success
+      : `${baseUrl}${config.urls.success}`,
+    return_url: config.urls.return.startsWith('http')
+      ? config.urls.return
+      : `${baseUrl}${config.urls.return}`,
+    metadata,
+    external_customer_id: String(user[f.publicId] || user[f.id]),
+  };
+  if (user[f.email]) shared.customer_email = user[f.email];
+
+  const attempts = [{ products: [productId], ...shared }];
+
+  if (config.priceId) {
+    attempts.push({
+      product_id: productId,
+      product_price_id: config.priceId,
+      customer_email: user[f.email] || undefined,
+      success_url: shared.success_url,
+      metadata,
+    });
+  }
+
+  const apiOpts = { accessToken: config.accessToken, sandbox: config.sandbox };
+  let lastError = null;
+
+  for (const payload of attempts) {
+    try {
+      const data = await polarApiRequest('/checkouts/', { method: 'POST', body: payload, ...apiOpts });
+      const checkoutUrl = extractCheckoutUrlFromResponse(data, config.sandbox);
+      if (checkoutUrl) return checkoutUrl;
+      const received = data.url || data.checkout_url || (data.client_secret ? 'client_secret only' : 'none');
+      lastError = new Error(`Polar checkout response did not include a valid checkout URL (received: ${received})`);
+    } catch (err) {
+      lastError = err;
+    }
+  }
+
+  throw lastError || new Error('Unable to create Polar checkout session');
+}
+
+async function getPolarCheckoutUrl({ user, plan = 'pro_monthly', baseUrl, config }) {
+  const productId = resolvePlanProductId(plan, config);
+
+  if (config.accessToken && productId && !productId.startsWith('polar_cl_')) {
+    try {
+      return await createCheckoutSessionViaApi({ user, productId, baseUrl, config });
+    } catch (err) {
+      console.error('[polar] Checkout API error:', err.message);
+    }
+  }
+
+  const hostedUrl = resolveHostedCheckoutBaseUrl(config);
+  if (hostedUrl && isValidCheckoutRedirectUrl(hostedUrl)) {
+    return buildHostedCheckoutUrl(hostedUrl, user, config);
+  }
+
+  throw new Error(
+    'Polar checkout is not configured. Set POLAR_ACCESS_TOKEN + POLAR_PRO_PRODUCT_ID (product UUID), or POLAR_CHECKOUT_URL (https://buy.polar.sh/polar_cl_...).'
+  );
+}
+
+module.exports = {
+  resolvePlanProductId,
+  resolveHostedCheckoutBaseUrl,
+  buildHostedCheckoutUrl,
+  createCheckoutSessionViaApi,
+  getPolarCheckoutUrl,
+};

package/plugins/polar/src/config.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const { parsePolarEnv } = require('./env.schema');
+
+const DEFAULT_FIELDS = {
+  id: 'id',
+  email: 'email',
+  publicId: 'public_id',
+  tier: 'tier',
+  polarCustomerId: 'polar_customer_id',
+  polarSubscriptionId: 'polar_subscription_id',
+  polarStatus: 'polar_status',
+  polarCurrentPeriodEnd: 'polar_current_period_end',
+  polarCancelAtPeriodEnd: 'polar_cancel_at_period_end',
+};
+
+const DEFAULT_ROUTES = {
+  webhook: '/api/v1/polar/webhook',
+  checkout: '/settings/billing/checkout',
+  portal: '/settings/billing/portal',
+  status: '/api/v1/billing/status',
+};
+
+const DEFAULT_URLS = {
+  success: '/settings?tab=billing&upgraded=1',
+  return: '/settings?tab=billing',
+  alreadySubscribed: '/settings?tab=billing&success=already_pro',
+  login: '/login?error=required',
+};
+
+/**
+ * @param {Object} options - polarPlugin options
+ * @returns {import('./types').PolarConfig}
+ */
+function resolvePolarConfig(options = {}) {
+  const env = parsePolarEnv({ ...process.env, ...options.env });
+
+  const fields = { ...DEFAULT_FIELDS, ...(options.fields || {}) };
+  const tierMapping = options.tierMapping || { pro: ['pro_monthly'], free: [] };
+  const plans = {
+    ...(options.plans || {}),
+  };
+
+  if (!plans.pro_monthly && env.POLAR_PRO_PRODUCT_ID) {
+    plans.pro_monthly = env.POLAR_PRO_PRODUCT_ID;
+  }
+  if (!plans.pro_yearly && env.POLAR_PRO_YEARLY_PRODUCT_ID) {
+    plans.pro_yearly = env.POLAR_PRO_YEARLY_PRODUCT_ID;
+  }
+
+  const proTiers = Object.keys(tierMapping).filter(
+    (t) => t !== 'free' && Array.isArray(tierMapping[t]) && tierMapping[t].length > 0
+  );
+
+  return {
+    db: options.db || null,
+    userModel: options.userModel || 'User',
+    userTable: options.userTable || 'users',
+    fields,
+    plans,
+    tierMapping,
+    proTiers,
+    proTierName: options.proTierName || proTiers[0] || 'pro',
+    freeTierName: options.freeTierName || 'free',
+    routes: { ...DEFAULT_ROUTES, ...(options.routes || {}) },
+    urls: { ...DEFAULT_URLS, ...(options.urls || {}) },
+    hooks: options.hooks || {},
+    requireAuth: options.requireAuth || null,
+    syncMiddleware: options.syncMiddleware || null,
+    rateLimit: options.rateLimit !== undefined ? options.rateLimit : true,
+    env,
+    accessToken: options.accessToken || env.POLAR_ACCESS_TOKEN || null,
+    webhookSecret: options.webhookSecret || env.POLAR_WEBHOOK_SECRET || null,
+    orgSlug: options.orgSlug || env.POLAR_ORG_SLUG || null,
+    checkoutUrl: options.checkoutUrl || env.POLAR_CHECKOUT_URL || null,
+    priceId: options.priceId || env.POLAR_PRO_PRICE_ID || null,
+    sandbox: options.sandbox !== undefined ? options.sandbox : env.POLAR_SANDBOX === true,
+    baseUrl: options.baseUrl || env.BASE_URL || null,
+    enabled: options.enabled !== false,
+  };
+}
+
+module.exports = {
+  DEFAULT_FIELDS,
+  DEFAULT_ROUTES,
+  DEFAULT_URLS,
+  resolvePolarConfig,
+};

package/plugins/polar/src/env.schema.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { z } = require('zod');
+
+const polarEnvSchema = z.object({
+  POLAR_ACCESS_TOKEN: z.string().min(1).optional(),
+  POLAR_WEBHOOK_SECRET: z.string().min(1).optional(),
+  POLAR_PRO_PRODUCT_ID: z.string().optional(),
+  POLAR_PRO_YEARLY_PRODUCT_ID: z.string().optional(),
+  POLAR_PRO_PRICE_ID: z.string().optional(),
+  POLAR_ORG_SLUG: z.string().optional(),
+  POLAR_SANDBOX: z
+    .union([z.literal('true'), z.literal('false'), z.boolean()])
+    .optional()
+    .transform((v) => v === true || v === 'true'),
+  POLAR_CHECKOUT_URL: z.string().url().optional(),
+  BASE_URL: z.string().url().optional(),
+});
+
+/**
+ * Parse Polar-related env vars (process.env or overrides).
+ * @param {Record<string, string|undefined>} [source=process.env]
+ */
+function parsePolarEnv(source = process.env) {
+  const parsed = polarEnvSchema.safeParse(source);
+  if (!parsed.success) {
+    const msg = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+    throw new Error(`Invalid Polar env: ${msg}`);
+  }
+  return parsed.data;
+}
+
+module.exports = {
+  polarEnvSchema,
+  parsePolarEnv,
+};

package/plugins/polar/src/middleware.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const { syncPolarBillingForUser } = require('./sync');
+
+/**
+ * Optional middleware: sync billing from Polar on matching requests (webhook delay fallback).
+ * @param {import('./config').PolarConfig} config
+ * @param {Object} [opts]
+ * @param {(req: import('express').Request) => boolean} [opts.when]
+ */
+function polarSyncMiddleware(config, opts = {}) {
+  const when = opts.when || config.syncMiddleware?.when || (() => false);
+
+  return async function polarSync(req, res, next) {
+    try {
+      if (!when(req) || !req.user) return next();
+
+      const knex = config.db?.knex || config.db;
+      if (!knex || !config.accessToken) return next();
+
+      const f = config.fields;
+      let user = req.user;
+      const dbUser = await knex(config.userTable).where(f.id, req.user[f.id] || req.user.id).first();
+      if (dbUser) user = dbUser;
+
+      req.user = await syncPolarBillingForUser(user, knex, config);
+      next();
+    } catch (err) {
+      console.error('[polar] Sync middleware error:', err.message);
+      next();
+    }
+  };
+}
+
+module.exports = {
+  polarSyncMiddleware,
+};

package/plugins/polar/src/migration.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { DEFAULT_FIELDS } = require('./config');
+
+/**
+ * Generate idempotent Knex migration for Polar billing columns.
+ * @param {Object} [opts]
+ * @param {string} [opts.tableName='users']
+ * @param {Object} [opts.fields]
+ */
+function generatePolarMigration(opts = {}) {
+  const tableName = opts.tableName || 'users';
+  const f = { ...DEFAULT_FIELDS, ...(opts.fields || {}) };
+
+  return `/**
+ * Migration: Add Polar.sh billing fields to ${tableName}
+ * Auto-generated by polar plugin — idempotent (safe to re-run)
+ */
+
+exports.up = async function up(knex) {
+  const hasTable = await knex.schema.hasTable('${tableName}');
+  if (!hasTable) return;
+
+  const hasTier = await knex.schema.hasColumn('${tableName}', '${f.tier}');
+  if (!hasTier) {
+    await knex.schema.alterTable('${tableName}', (table) => {
+      table.string('${f.tier}', 32).notNullable().defaultTo('free').index();
+      table.string('${f.polarCustomerId}', 128).nullable().index();
+      table.string('${f.polarSubscriptionId}', 128).nullable().index();
+      table.string('${f.polarStatus}', 32).notNullable().defaultTo('none').index();
+      table.string('${f.polarCurrentPeriodEnd}', 64).nullable();
+      table.boolean('${f.polarCancelAtPeriodEnd}').notNullable().defaultTo(false);
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  const hasTable = await knex.schema.hasTable('${tableName}');
+  if (!hasTable) return;
+
+  const hasTier = await knex.schema.hasColumn('${tableName}', '${f.tier}');
+  if (hasTier) {
+    await knex.schema.alterTable('${tableName}', (table) => {
+      table.dropColumn('${f.tier}');
+      table.dropColumn('${f.polarCustomerId}');
+      table.dropColumn('${f.polarSubscriptionId}');
+      table.dropColumn('${f.polarStatus}');
+      table.dropColumn('${f.polarCurrentPeriodEnd}');
+      table.dropColumn('${f.polarCancelAtPeriodEnd}');
+    });
+  }
+};
+`;
+}
+
+module.exports = {
+  generatePolarMigration,
+};