cokit-cli 1.0.8 → 1.2.0

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

@@ -1,266 +0,0 @@
-# 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

@@ -1,184 +0,0 @@
-# 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

@@ -1,244 +0,0 @@
-# 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