cokit-cli 1.0.1 → 1.0.3

package/skills/ck-payment-integration/references/polar/checkouts.md

@@ -0,0 +1,266 @@
+# Polar Checkouts
+
+Checkout flows, embedded checkout, and session management.
+
+## Checkout Approaches
+
+### 1. Checkout Links
+- Pre-configured shareable links
+- Created via dashboard or API
+- For marketing campaigns
+- Can pre-apply discounts
+
+**Create via API:**
+```typescript
+const link = await polar.checkoutLinks.create({
+  product_price_id: "price_xxx",
+  success_url: "https://example.com/success"
+});
+// Returns: link.url
+```
+
+### 2. Checkout Sessions (API)
+- Programmatically created
+- Server-side API call
+- Dynamic workflows
+- Custom logic
+
+**Create Session:**
+```typescript
+const session = await polar.checkouts.create({
+  product_price_id: "price_xxx",
+  success_url: "https://example.com/success?checkout_id={CHECKOUT_ID}",
+  customer_email: "user@example.com",
+  external_customer_id: "user_123",
+  metadata: {
+    user_id: "123",
+    source: "web"
+  }
+});
+
+// Redirect to: session.url
+```
+
+**Response:**
+```json
+{
+  "id": "checkout_xxx",
+  "url": "https://polar.sh/checkout/...",
+  "client_secret": "cs_xxx",
+  "status": "open",
+  "expires_at": "2025-01-15T10:00:00Z"
+}
+```
+
+### 3. Embedded Checkout
+- Inline checkout within your site
+- Seamless purchase experience
+- Theme customization
+
+**Implementation:**
+```html
+<script src="https://polar.sh/embed.js"></script>
+
+<div id="polar-checkout"></div>
+
+<script>
+  const checkout = await fetch('/api/create-checkout', {
+    method: 'POST',
+    body: JSON.stringify({ productPriceId: 'price_xxx' })
+  }).then(r => r.json());
+
+  Polar('checkout', {
+    checkoutId: checkout.id,
+    clientSecret: checkout.client_secret,
+    onSuccess: () => {
+      window.location.href = '/success';
+    },
+    theme: 'dark' // or 'light'
+  });
+</script>
+```
+
+**Server-side (create session):**
+```typescript
+app.post('/api/create-checkout', async (req, res) => {
+  const session = await polar.checkouts.create({
+    product_price_id: req.body.productPriceId,
+    embed_origin: "https://example.com",
+    external_customer_id: req.user.id
+  });
+
+  res.json({
+    id: session.id,
+    client_secret: session.client_secret
+  });
+});
+```
+
+## Configuration Parameters
+
+### Required
+- `product_price_id` - Product to checkout (or `products` array for multiple)
+- `success_url` - Post-payment redirect (absolute URL)
+
+### Optional
+- `external_customer_id` - Your user ID mapping
+- `embed_origin` - For embedded checkouts
+- `customer_email` - Pre-fill email
+- `customer_name` - Pre-fill name
+- `discount_id` - Pre-apply discount code
+- `allow_discount_codes` - Allow customer to enter codes (default: true)
+- `metadata` - Custom data (key-value)
+- `custom_field_data` - Pre-fill custom fields
+- `customer_billing_address` - Pre-fill billing address
+
+### Success URL Placeholder
+```typescript
+{
+  success_url: "https://example.com/success?checkout_id={CHECKOUT_ID}"
+}
+// Polar replaces {CHECKOUT_ID} with actual checkout ID
+```
+
+## Multi-Product Checkout
+
+```typescript
+const session = await polar.checkouts.create({
+  products: [
+    { product_price_id: "price_1", quantity: 1 },
+    { product_price_id: "price_2", quantity: 2 }
+  ],
+  success_url: "https://example.com/success"
+});
+```
+
+## Discount Application
+
+### Pre-apply Discount
+```typescript
+const session = await polar.checkouts.create({
+  product_price_id: "price_xxx",
+  discount_id: "discount_xxx",
+  success_url: "https://example.com/success"
+});
+```
+
+### Allow Customer Codes
+```typescript
+{
+  allow_discount_codes: true // default
+  // Set to false to disable code entry
+}
+```
+
+## Checkout States
+
+- `open` - Ready for payment
+- `confirmed` - Payment successful
+- `expired` - Session expired (typically 24 hours)
+
+## Events
+
+**Webhook Events:**
+- `checkout.created` - Session created
+- `checkout.updated` - Session updated
+- `order.created` - Order created after successful payment
+- `order.paid` - Payment confirmed
+
+**Handle Success:**
+```typescript
+// Listen to order.paid webhook
+app.post('/webhook/polar', async (req, res) => {
+  const event = validateEvent(req.body, req.headers, secret);
+
+  if (event.type === 'order.paid') {
+    const order = event.data;
+    await fulfillOrder(order);
+  }
+
+  res.json({ received: true });
+});
+```
+
+## Best Practices
+
+1. **Success URL:**
+   - Must be absolute URL: `https://example.com/success`
+   - Use `{CHECKOUT_ID}` placeholder to retrieve checkout details
+   - Verify payment via webhook, not just success redirect
+
+2. **External Customer ID:**
+   - Set on first checkout
+   - Never change once set
+   - Use for all customer operations
+   - Enables customer lookup without storing Polar IDs
+
+3. **Pre-filling Data:**
+   - Pre-fill customer info when available
+   - Reduces friction in checkout
+   - Improves conversion rates
+
+4. **Embedded Checkout:**
+   - Provide seamless experience
+   - Match your site's theme
+   - Handle errors gracefully
+   - Show loading states
+
+5. **Metadata:**
+   - Store tracking info (source, campaign, etc.)
+   - Link to your internal systems
+   - Use for analytics and reporting
+
+6. **Error Handling:**
+   - Handle expired sessions
+   - Provide clear error messages
+   - Offer to create new session
+   - Log failures for debugging
+
+7. **Mobile Optimization:**
+   - Test on mobile devices
+   - Ensure responsive design
+   - Consider mobile payment methods
+   - Test embedded checkout on mobile
+
+## Framework Examples
+
+### Next.js
+```typescript
+// app/actions/checkout.ts
+'use server'
+
+export async function createCheckout(productPriceId: string) {
+  const session = await polar.checkouts.create({
+    product_price_id: productPriceId,
+    success_url: `${process.env.NEXT_PUBLIC_URL}/success?checkout_id={CHECKOUT_ID}`,
+    external_customer_id: await getCurrentUserId()
+  });
+
+  return session.url;
+}
+
+// app/product/page.tsx
+export default function ProductPage() {
+  async function handleCheckout() {
+    const url = await createCheckout(productPriceId);
+    window.location.href = url;
+  }
+
+  return <button onClick={handleCheckout}>Buy Now</button>;
+}
+```
+
+### Laravel
+```php
+Route::post('/checkout', function (Request $request) {
+    $polar = new Polar(config('polar.access_token'));
+
+    $session = $polar->checkouts->create([
+        'product_price_id' => $request->input('product_price_id'),
+        'success_url' => route('checkout.success'),
+        'external_customer_id' => auth()->id(),
+    ]);
+
+    return redirect($session['url']);
+});
+```

package/skills/ck-payment-integration/references/polar/overview.md

@@ -0,0 +1,184 @@
+# Polar Overview
+
+Comprehensive payment & billing platform for software monetization with Merchant of Record services.
+
+## Core Capabilities
+
+**Platform Features:**
+- Digital product sales (one-time, recurring, usage-based)
+- Merchant of Record - handles global tax compliance
+- Subscription lifecycle management
+- Automated benefit distribution
+- Customer self-service portal
+- Real-time webhook system
+- Analytics dashboard
+- Multi-language SDKs
+
+**Merchant of Record Benefits:**
+- Global tax compliance (VAT, GST, sales tax)
+- Tax calculations for all jurisdictions
+- B2B reverse charge, B2C tax collection
+- Invoicing from Polar to customers
+- Payout invoicing to merchants
+- Transparent fees (20% discount vs other MoRs)
+
+## Authentication
+
+### Organization Access Tokens (OAT)
+
+**For:** Server-side API access
+
+**Create:**
+1. Org Settings → Developers
+2. Create new access token
+3. Copy and store securely
+
+**Usage:**
+```bash
+Authorization: Bearer polar_xxxxxxxxxxxxxxxx
+```
+
+**Security:** Never expose client-side (auto-revoked if leaked)
+
+### OAuth 2.0
+
+**For:** Third-party app integration
+
+**Authorization URL:** `https://polar.sh/oauth2/authorize`
+**Token URL:** `https://api.polar.sh/v1/oauth2/token`
+
+**Flow:**
+```
+1. Redirect to authorize URL with scopes
+2. User approves permissions
+3. Receive authorization code
+4. Exchange code for access_token + refresh_token
+5. Use access_token for API calls
+```
+
+**Scopes:**
+- `products:read/write` - Product management
+- `checkouts:read/write` - Checkout operations
+- `orders:read` - View orders
+- `subscriptions:read/write` - Subscription management
+- `benefits:read/write` - Benefit configuration
+- `customers:read/write` - Customer management
+- `discounts:read/write` - Discount codes
+- `refunds:read/write` - Refund processing
+
+### Customer Sessions
+
+**For:** Customer-facing portal operations
+
+**Create:** Server-side API call returns customer access token
+**Usage:** Pre-authenticated customer portal links
+**Scope:** Restricted to customer-specific operations
+
+## Base URLs
+
+**Production:**
+- Dashboard: `https://polar.sh`
+- API: `https://api.polar.sh/v1/`
+
+**Sandbox:**
+- Dashboard: `https://sandbox.polar.sh`
+- API: `https://sandbox-api.polar.sh/v1/`
+
+**SDK Configuration:**
+```typescript
+const polar = new Polar({
+  accessToken: process.env.POLAR_ACCESS_TOKEN,
+  server: "production" // or "sandbox"
+});
+```
+
+## Rate Limits
+
+**Limits:**
+- 300 requests/minute per org/customer/OAuth2 client
+- 3 requests/second for unauthenticated license validation
+
+**Response:** HTTP 429 with `Retry-After` header
+
+**Handling:**
+```javascript
+if (response.status === 429) {
+  const retryAfter = response.headers.get('Retry-After');
+  await sleep(retryAfter * 1000);
+  return retry();
+}
+```
+
+## Key Concepts
+
+### External Customer ID
+- Map your user IDs to Polar customers
+- Set at checkout: `external_customer_id`
+- Query API by external_id
+- Immutable once set
+- Use for all customer operations
+
+### Metadata
+- Custom key-value storage
+- Available on products, customers, subscriptions, orders
+- For reporting and filtering
+- Not indexed, use for supplementary data
+
+### Billing Reasons
+Track order types via `billing_reason`:
+- `purchase` - One-time product
+- `subscription_create` - New subscription
+- `subscription_cycle` - Renewal invoice
+- `subscription_update` - Plan change
+
+## Environments
+
+**Sandbox:**
+- Separate account required
+- Separate organization
+- Separate access tokens (production tokens don't work)
+- Test with Stripe test cards
+
+**Test Cards (Stripe):**
+- Success: `4242 4242 4242 4242`
+- Decline: `4000 0000 0000 0002`
+- Auth Required: `4000 0025 0000 3155`
+- Expiry: Any future date
+- CVC: Any 3 digits
+
+## SDKs
+
+**Official SDKs:**
+- TypeScript/JavaScript: `@polar-sh/sdk`
+- Python: `polar-sdk`
+- PHP: `polar-sh/sdk`
+- Go: Official SDK
+
+**Framework Adapters:**
+- Next.js: `@polar-sh/nextjs` (quickstart: `npx polar-init`)
+- Laravel: `polar-sh/laravel`
+- Remix, Astro, Express, TanStack Start
+- Elysia, Fastify, Hono, SvelteKit
+
+**BetterAuth Integration:**
+- Package: `@polar-sh/better-auth`
+- Auto-create customers on signup
+- External ID mapping
+- User-customer sync
+
+## Support & Resources
+
+- Docs: https://polar.sh/docs
+- API Reference: https://polar.sh/docs/api-reference
+- LLMs.txt: https://polar.sh/docs/llms.txt
+- GitHub: https://github.com/polarsource/polar
+- Discussions: https://github.com/orgs/polarsource/discussions
+
+## Next Steps
+
+- **For products:** Load `products.md`
+- **For checkout:** Load `checkouts.md`
+- **For subscriptions:** Load `subscriptions.md`
+- **For webhooks:** Load `webhooks.md`
+- **For benefits:** Load `benefits.md`
+- **For SDK usage:** Load `sdk.md`

package/skills/ck-payment-integration/references/polar/products.md

@@ -0,0 +1,244 @@
+# Polar Products & Pricing
+
+Product management, pricing models, and usage-based billing.
+
+## Billing Cycles
+
+**Options:**
+- One-time: Charged once, forever access
+- Monthly: Charged every month
+- Yearly: Charged every year
+
+**Important:** Cannot change after product creation
+
+## Pricing Types
+
+**Fixed Price:** Set amount
+**Pay What You Want:** Customer decides (optional minimum)
+**Free:** No charge
+
+**Important:** Cannot change after product creation
+
+## Advanced Pricing Models
+
+### Seat-Based Pricing
+- Team access with assignable seats
+- Works for recurring or one-time
+- Tiered pricing structures
+- Customer manages seat assignments
+
+**Configuration:**
+```typescript
+const product = await polar.products.create({
+  name: "Team Plan",
+  prices: [{
+    type: "recurring",
+    recurring_interval: "month",
+    price_amount: 5000, // per seat
+    pricing_type: "fixed"
+  }],
+  is_seat_based: true,
+  max_seats: 100
+});
+```
+
+### Usage-Based Billing
+
+**Architecture:** Events → Meters → Metered Prices
+
+**1. Events:** Usage data from your application
+```typescript
+await polar.events.create({
+  external_customer_id: "user_123",
+  event_name: "api_call",
+  properties: {
+    tokens: 1000,
+    model: "gpt-4"
+  }
+});
+```
+
+**2. Meters:** Filter & aggregate events
+```typescript
+const meter = await polar.meters.create({
+  name: "API Tokens",
+  slug: "api_tokens",
+  event_name: "api_call",
+  aggregation: {
+    type: "sum",
+    property: "tokens"
+  }
+});
+```
+
+**3. Metered Prices:** Billing based on usage
+```typescript
+const price = await polar.products.createPrice(productId, {
+  type: "metered",
+  meter_id: meter.id,
+  price_per_unit: 10, // 10 cents per 1000 tokens
+  billing_interval: "month"
+});
+```
+
+**Credits System:**
+- Pre-purchased usage credits
+- Credit customer's meter balance
+- Use as subscription benefit
+- Balance tracking API
+
+**Ingestion Strategies:**
+- LLM Strategy: AI/ML tracking
+- S3 Strategy: Bulk import
+- Stream Strategy: Real-time
+- Delta Time Strategy: Time-based
+
+## Product Features
+
+### Metadata
+```typescript
+const product = await polar.products.create({
+  name: "Pro Plan",
+  metadata: {
+    feature_x: "enabled",
+    tier: "pro",
+    custom_field: "value"
+  }
+});
+```
+
+### Custom Fields
+```typescript
+const product = await polar.products.create({
+  name: "Enterprise Plan",
+  custom_fields: [
+    {
+      slug: "company_name",
+      label: "Company Name",
+      type: "text",
+      required: true
+    },
+    {
+      slug: "employees",
+      label: "Number of Employees",
+      type: "number"
+    }
+  ]
+});
+```
+
+Data collected at checkout, accessible via Orders/Subscriptions API in `custom_field_data`.
+
+### Trials
+- Set on recurring products
+- Customer not charged during trial
+- Benefits granted immediately
+- Configure at product or checkout level
+
+```typescript
+const product = await polar.products.create({
+  name: "Pro Plan",
+  prices: [{
+    type: "recurring",
+    recurring_interval: "month",
+    price_amount: 2000,
+    trial_period_days: 14
+  }]
+});
+```
+
+## Product Operations
+
+### Create Product
+```typescript
+const product = await polar.products.create({
+  organization_id: "org_xxx",
+  name: "Pro Plan",
+  description: "Professional features",
+  prices: [{
+    type: "recurring",
+    recurring_interval: "month",
+    price_amount: 2000,
+    pricing_type: "fixed"
+  }]
+});
+```
+
+### List Products
+```typescript
+const products = await polar.products.list({
+  organization_id: "org_xxx",
+  is_archived: false
+});
+```
+
+### Update Product
+```typescript
+const product = await polar.products.update(productId, {
+  name: "Pro Plan Updated",
+  description: "New description"
+});
+```
+
+### Archive Product
+```typescript
+await polar.products.archive(productId);
+// Products can be unarchived later
+// Cannot be deleted (maintains order history)
+```
+
+### Update Benefits
+```typescript
+await polar.products.updateBenefits(productId, {
+  benefits: [benefitId1, benefitId2]
+});
+```
+
+## Important Constraints
+
+1. **Cannot change after creation:**
+   - Billing cycle (one-time, monthly, yearly)
+   - Pricing type (fixed, pay-what-you-want, free)
+
+2. **Price changes don't affect existing subscribers:**
+   - Current subscribers keep their original price
+   - New subscribers get new price
+   - Use separate products for significant changes
+
+3. **Products cannot be deleted:**
+   - Archive instead
+   - Maintains order history integrity
+   - Archived products not shown to new customers
+
+4. **Metadata vs Custom Fields:**
+   - Metadata: For internal use, not shown to customers
+   - Custom Fields: Collected from customers at checkout
+
+## Best Practices
+
+1. **Product Strategy:**
+   - Plan billing cycle carefully before creation
+   - Use separate products for different tiers
+   - Archive unused products rather than delete
+
+2. **Pricing Changes:**
+   - Create new product for major changes
+   - Grandfather existing customers
+   - Communicate changes clearly
+
+3. **Usage-Based:**
+   - Define clear meter aggregations
+   - Set appropriate billing intervals
+   - Monitor usage patterns
+   - Provide usage dashboards to customers
+
+4. **Custom Fields:**
+   - Collect only necessary information
+   - Validate on frontend before checkout
+   - Use for personalization and support
+
+5. **Trials:**
+   - Set appropriate trial duration
+   - Communicate trial end clearly
+   - Notify before trial expires
+   - Easy cancellation during trial