autumn-best-practices: Скилл интеграции с Stripe для биллинга

--- name: autumn-best-practices description: Skill for integrating Autumn - the billing and entitlements layer over Stripe. --- # Autumn Integration Guide **Always consult [docs.useautumn.com](https://docs.useautumn.com) for code examples and latest API.** Autumn is a TypeScript-first billing SDK supporting subscriptions, usage-based pricing, credits, trials, and more via Stripe. --- ## Quick Reference ### Environment Variables - `AUTUMN_SECRET_KEY` - API key (required). Get one at [app.useautumn.com](https://app.useautumn.com/dev?tab=api_keys) ### Installation ```bash npm install autumn-js # Node.js pip install autumn-py # Python ``` ### Core Methods | Method | Purpose | |--------|---------| | `customers.create` | Create or get customer (idempotent) | | `checkout` | Get Stripe URL or payment preview | | `attach` | Confirm purchase (card on file) | | `cancel` | Cancel subscription | | `check` | Verify feature access | | `track` | Record usage | | `products.list` | Get products with billing scenarios | --- ## Core Config Options | Option | Notes | |--------|-------| | `secretKey` | Required. From env `AUTUMN_SECRET_KEY` | | `baseURL` | Optional. Defaults to `https://api.useautumn.com` | --- ## Billing Patterns ### Check → Work → Track Always follow this order for protected actions: ```typescript const { data } = await autumn.check({ customer_id, feature_id: "api_calls" }); if (!data.allowed) return { error: "Limit reached" }; const result = await doWork(); await autumn.track({ customer_id, feature_id: "api_calls", value: 1 }); return result; ``` ### Two-Step Checkout ```typescript const { data } = await autumn.checkout({ customer_id, product_id: "pro" }); if (data.url) return redirect(data.url); // New customer → Stripe // Returning customer → show confirmation, then: await autumn.attach({ customer_id, product_id: "pro" }); ``` --- ## Product Scenarios Use `products.list` to get scenarios. Don't build custom logic. | Scenario | Meaning | |----------|---------| | `new` | Not subscribed | | `active` | Currently on plan | | `scheduled` | Scheduled for future | | `upgrade` | Higher tier available | | `downgrade` | Lower tier available | | `renew` | Cancelled, can reactivate | --- ## Feature Types | Type | Behavior | |------|----------| | `boolean` | Access granted or denied | | `metered` | Usage tracked against limit | | `credit_system` | Pool for multiple features | --- ## React Hooks | Hook | Purpose | |------|---------| | `useCustomer` | Get customer, checkout, attach, check | | `usePricingTable` | Get products with scenarios | ```tsx import { AutumnProvider } from "autumn-js/react"; <AutumnProvider>{children}</AutumnProvider> ``` --- ## Handler Imports | Framework | Import | |-----------|--------| | Next.js | `autumn-js/next` | | React Router | `autumn-js/react-router` | | Hono | `autumn-js/hono` | | Express | `autumn-js/express` | | Fastify | `autumn-js/fastify` | | Generic | `autumn-js/backend` | --- ## Common Gotchas 1. **URL field** - Checkout URL is `data.url`, not `data.checkout_url` 2. **Frontend checks** - For UX only. Always enforce on backend 3. **Track after success** - Only track usage after work completes 4. **Credit systems** - Track metered features, not the credit system itself 5. **Cancel via free plan** - Prefer `attach({ product_id: "free" })` over `cancel()` 6. **Idempotent creation** - `customers.create` returns existing customer if ID exists --- ## Resources - [Docs](https://docs.useautumn.com) - [API Reference](https://docs.useautumn.com/api-reference) - [LLMs.txt](https://docs.useautumn.com/llms.txt) - [GitHub](https://github.com/useautumn/autumn)