@nextsparkjs/ai-workflow 0.1.0-beta.127 → 0.1.0-beta.128

package/claude/commands/how-to/set-plans-and-permissions.md

@@ -7,7 +7,7 @@ Interactive guide to configure subscription plans, features, and billing in Next
 ## Required Skills
 
 Before executing, these skills provide deeper context:
-- `.claude/skills/billing-subscriptions/SKILL.md` - Stripe integration and billing patterns
+- `.claude/skills/billing-subscriptions/SKILL.md` - Multi-provider billing and Gateway Factory patterns
 - `.claude/skills/permissions-system/SKILL.md` - Three-layer permission model
 
 ---
@@ -22,7 +22,7 @@ Before executing, these skills provide deeper context:
 
 ## Behavior
 
-Guides the user through configuring subscription plans with features, usage limits, and Stripe integration.
+Guides the user through configuring subscription plans with features, usage limits, and payment provider integration.
 
 ---
 
@@ -43,8 +43,8 @@ Step 3: Define Usage Limits (Quotas)
 Step 4: Configure Plans
         └── Create free, pro, enterprise plans
 
-Step 5: Set Up Stripe
-        └── Create products and prices
+Step 5: Set Up Payment Provider
+        └── Create products and prices (Stripe or Polar)
 
 Step 6: Test the Checkout Flow
         └── Verify the complete flow
@@ -327,8 +327,7 @@ export const billingConfig: BillingConfig = {
         api_calls: 1000,
         email_sends: 100,
       },
-      stripePriceIdMonthly: null,
-      stripePriceIdYearly: null,
+      // No price IDs for free plan
     },
 
     // PRO PLAN
@@ -357,8 +356,10 @@ export const billingConfig: BillingConfig = {
         api_calls: 100000,
         email_sends: 5000,
       },
-      stripePriceIdMonthly: 'price_xxx_monthly',  // From Stripe
-      stripePriceIdYearly: 'price_xxx_yearly',
+      providerPriceIds: {
+        monthly: 'price_xxx_monthly',  // From your payment provider
+        yearly: 'price_xxx_yearly',
+      },
     },
 
     // ENTERPRISE PLAN
@@ -386,7 +387,7 @@ export const billingConfig: BillingConfig = {
 📋 Plan Types:
 
 • 'free'       - No payment required
-• 'paid'       - Requires Stripe subscription
+• 'paid'       - Requires payment subscription
 • 'enterprise' - Custom pricing (contact sales)
 
 📋 Visibility:
@@ -398,37 +399,47 @@ export const billingConfig: BillingConfig = {
 
 What would you like to do?
 
-[1] Continue to Step 5 (Stripe Setup)
+[1] Continue to Step 5 (Payment Provider Setup)
 [2] How do I add more plan tiers?
 [3] Show me the pricing page component
 ```
 
 ---
 
-## Step 5: Set Up Stripe
+## Step 5: Set Up Payment Provider
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-STEP 5 OF 6: Set Up Stripe
+STEP 5 OF 6: Set Up Payment Provider
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-1️⃣  Create Stripe Products and Prices:
-
-In Stripe Dashboard (dashboard.stripe.com):
+1️⃣  Create Products and Prices in your provider:
 
+For Stripe (dashboard.stripe.com):
 • Products → Add Product → "Pro Plan"
 • Add Price → $29/month → Copy price_xxx_monthly
 • Add Price → $290/year → Copy price_xxx_yearly
 
+For Polar (polar.sh):
+• Products → Create Product → Set pricing
+• Copy the Product Price ID
+
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 2️⃣  Configure Environment Variables:
 
 ```env
 # .env.local
+
+# For Stripe:
 STRIPE_SECRET_KEY=sk_test_xxx
 STRIPE_PUBLISHABLE_KEY=pk_test_xxx
 STRIPE_WEBHOOK_SECRET=whsec_xxx
+
+# For Polar:
+POLAR_ACCESS_TOKEN=pat_xxx
+POLAR_WEBHOOK_SECRET=whsec_xxx
+POLAR_SERVER=sandbox
 ```
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -440,8 +451,10 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 {
   slug: 'pro',
   // ...
-  stripePriceIdMonthly: 'price_1xxx',  // From Stripe
-  stripePriceIdYearly: 'price_1yyy',
+  providerPriceIds: {
+    monthly: 'price_1xxx',  // From your provider
+    yearly: 'price_1yyy',
+  },
 }
 ```
 
@@ -449,23 +462,17 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 
 4️⃣  Set Up Webhook:
 
-In Stripe Dashboard → Webhooks → Add endpoint:
-
+For Stripe: Dashboard → Webhooks → Add endpoint
 URL: https://your-domain.com/api/v1/billing/webhooks/stripe
 
-Events to listen for:
-• checkout.session.completed
-• invoice.paid
-• invoice.payment_failed
-• customer.subscription.updated
-• customer.subscription.deleted
+For Polar: Organization Settings → Webhooks → Add endpoint
+URL: https://your-domain.com/api/v1/billing/webhooks/polar
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-5️⃣  Test with Stripe CLI (development):
+5️⃣  Test locally (Stripe example):
 
 ```bash
-# Install Stripe CLI
 stripe listen --forward-to localhost:3000/api/v1/billing/webhooks/stripe
 ```
 
@@ -474,7 +481,7 @@ stripe listen --forward-to localhost:3000/api/v1/billing/webhooks/stripe
 What would you like to do?
 
 [1] Continue to Step 6 (Test Checkout)
-[2] I have questions about Stripe setup
+[2] I have questions about provider setup
 [3] Help me set up webhook forwarding
 ```
 
@@ -536,7 +543,7 @@ node core/scripts/build/registry.mjs
 
 • Go to /pricing (or /dashboard/settings/billing)
 • Click "Upgrade to Pro"
-• Use Stripe test card: 4242 4242 4242 4242
+• Use test card (Stripe): 4242 4242 4242 4242
 • Complete checkout
 • Verify webhook updates subscription
 • Check features are now available
@@ -557,7 +564,7 @@ You've configured:
 • Feature flags for plan gating
 • Usage limits and quotas
 • Subscription plans with pricing
-• Stripe integration
+• Payment provider integration (Stripe or Polar)
 
 📚 Related tutorials:
    • /how-to:set-user-roles-and-permissions - RBAC configuration

package/claude/skills/billing-subscriptions/SKILL.md

@@ -20,7 +20,7 @@ BILLING ARCHITECTURE:
 
 Configuration Layer:
 contents/themes/{theme}/config/billing.config.ts
-├── provider: 'stripe' | 'polar' | 'paddle' | 'lemonsqueezy'
+├── provider: 'stripe' | 'polar'  # (paddle, lemonsqueezy, mercadopago: type defined, not yet implemented)
 ├── currency: 'usd' | 'eur' | ...
 ├── defaultPlan: 'free'
 ├── features: { featureSlug: FeatureDefinition }
@@ -37,7 +37,7 @@ core/lib/billing/
 │   ├── types.ts         # Provider-agnostic result types
 │   ├── interface.ts     # BillingGateway interface (contract)
 │   ├── factory.ts       # getBillingGateway() factory
-│   └── stripe.ts        # StripeGateway implements BillingGateway
+│   ├── stripe.ts        # StripeGateway implements BillingGateway
 │   └── polar.ts         # PolarGateway implements BillingGateway
 ├── queries.ts           # Database queries
 ├── enforcement.ts       # Limit/feature enforcement
@@ -97,6 +97,11 @@ export interface BillingGateway {
 
   // Webhooks (Stripe passes string signature, Polar passes headers Record)
   verifyWebhookSignature(payload: string | Buffer, signatureOrHeaders: string | Record<string, string>): WebhookEventResult
+
+  // Dashboard & Metadata
+  getProviderName(): string
+  getSubscriptionDashboardUrl(externalSubscriptionId: string | null | undefined): string | null
+  getResourceHintDomains(): { preconnect: string[]; dnsPrefetch: string[] }
 }
 ```
 
@@ -144,29 +149,33 @@ const session = await getBillingGateway().createCheckoutSession(params)
 const portal = await getBillingGateway().createPortalSession(params)
 await getBillingGateway().cancelSubscriptionAtPeriodEnd(subId)
 
+// Provider metadata
+const name = getBillingGateway().getProviderName()             // "Stripe" or "Polar"
+const url = getBillingGateway().getSubscriptionDashboardUrl(id) // Dashboard URL or null
+
+// Resource hints (used in layout.tsx automatically)
+import { getBillingResourceHints } from '@nextsparkjs/core/lib/billing/gateways/factory'
+const { preconnect, dnsPrefetch } = getBillingResourceHints()
+
 // WRONG: Import from specific provider
 import { createCheckoutSession } from '.../gateways/stripe'  // DEPRECATED
 ```
 
 ### Plan Price IDs
 
-Plans support both provider-specific and generic price IDs:
+Plans use `providerPriceIds` for price configuration (works with any provider):
 
 ```typescript
 // PlanDefinition in config-types.ts
 {
   slug: 'pro',
-  // Generic (checked first) - works with any provider
   providerPriceIds: {
     monthly: 'price_xxx_monthly',
     yearly: 'price_xxx_yearly',
   },
-  // Stripe-specific (fallback for backward compat)
-  stripePriceIdMonthly: 'price_pro_monthly',
-  stripePriceIdYearly: 'price_pro_yearly',
 }
 
-// PlanService.getPriceId() checks providerPriceIds first, falls back to stripe-specific
+// PlanService.getPriceId() reads from providerPriceIds
 const priceId = PlanService.getPriceId('pro', 'monthly')
 ```
 
@@ -237,13 +246,16 @@ export class StripeGateway implements BillingGateway {
 // app/api/v1/billing/webhooks/stripe/route.ts
 // NOTE: Webhook routes stay provider-specific by design.
 // They need raw provider types for proper type narrowing.
-import { getStripeInstance } from '@nextsparkjs/core/lib/billing/gateways/stripe'
-import type Stripe from 'stripe'
+import Stripe from 'stripe'
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
 
 export async function POST(request: NextRequest) {
   const payload = await request.text()
   const signature = request.headers.get('stripe-signature')!
-  const event = getStripeInstance().webhooks.constructEvent(payload, signature, secret)
+  const event = stripe.webhooks.constructEvent(
+    payload, signature, process.env.STRIPE_WEBHOOK_SECRET!
+  )
 
   switch (event.type) {
     case 'checkout.session.completed':
@@ -659,15 +671,11 @@ export const billingConfig: BillingConfig = {
       features: ['basic_analytics', 'advanced_analytics', 'api_access'],
       limits: { team_members: 15, tasks: 1000, api_calls: 100000 },
 
-      // Generic price IDs (preferred - works with any provider)
+      // Price IDs from your payment provider dashboard
       providerPriceIds: {
         monthly: 'price_pro_monthly',
         yearly: 'price_pro_yearly',
       },
-
-      // OR Stripe-specific (backward compat)
-      stripePriceIdMonthly: 'price_pro_monthly',
-      stripePriceIdYearly: 'price_pro_yearly',
     },
     {
       slug: 'enterprise',
@@ -784,8 +792,8 @@ CREATE TABLE plans (
   "trialDays" INTEGER DEFAULT 0,
   features JSONB DEFAULT '[]',
   limits JSONB DEFAULT '{}',
-  "stripePriceIdMonthly" TEXT,
-  "stripePriceIdYearly" TEXT,
+  -- Price IDs stored in providerPriceIds (via billing.config.ts)
+  -- Legacy: stripePriceIdMonthly/Yearly columns may exist in older migrations but are unused
   "createdAt" TIMESTAMPTZ DEFAULT NOW(),
   "updatedAt" TIMESTAMPTZ DEFAULT NOW()
 );
@@ -829,7 +837,7 @@ POLAR_SERVER=sandbox                  # 'sandbox' or 'production'
 
 ```typescript
 // NEVER: Import from specific provider in consumers
-import { createCheckoutSession } from '.../gateways/stripe'  // DEPRECATED
+import { createCheckoutSession } from '.../gateways/stripe'  // REMOVED
 
 // CORRECT: Use factory
 import { getBillingGateway } from '.../gateways/factory'
@@ -841,7 +849,7 @@ const session: Stripe.Checkout.Session = ...
 // CORRECT: Use provider-agnostic types
 const session: CheckoutSessionResult = ...
 
-// NEVER: Use getStripePriceId (deprecated)
+// NEVER: Use getStripePriceId (removed)
 PlanService.getStripePriceId('pro', 'monthly')
 
 // CORRECT: Use generic getPriceId
@@ -885,7 +893,7 @@ if (current >= limit) return false
 ### General (all providers)
 
 - [ ] Provider selected in `billing.config.ts`
-- [ ] Plans defined with price IDs (providerPriceIds or stripe-specific)
+- [ ] Plans defined with price IDs (providerPriceIds)
 - [ ] Features and limits defined
 - [ ] Action mappings configured
 - [ ] Team-based subscription created on team creation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/ai-workflow",
-  "version": "0.1.0-beta.127",
+  "version": "0.1.0-beta.128",
   "description": "AI workflow templates for NextSpark - Claude Code agents, commands, skills, and multi-editor support",
   "license": "MIT",
   "author": "NextSpark <hello@nextspark.dev>",