# Guapocado

> Config-first billing, entitlements, usage, and subscriptions for product teams.

Guapocado is a billing layer that sits between your app and Stripe. You define plans, entitlements, and pricing in a `billing.config.ts` file, push it to sync Stripe, and check access from your server through a typed SDK or plain HTTP. No Stripe SDK in your product code. No plan logic scattered across conditionals.

The three ownership layers: your app owns the product and user model, Guapocado owns the billing projection and entitlement state, your app owns enforcement (what happens when a check fails).

## Start Here

- [Introduction](https://docs.guapocado.dev/): Overview of Guapocado, the three ownership layers, and links to core primitives and framework guides.
- [Quickstart](https://docs.guapocado.dev/quickstart/): Install the CLI and SDK, create a billing config with free and pro plans, push to sandbox, and make your first entitlement check in under 10 minutes.
- [Agent Skill](https://docs.guapocado.dev/agent-skill/): Install the official Guapocado Agent Skill for Codex and other compatible coding agents. Covers project and global installation, integration workflows, example prompts, test-first safety boundaries, agent-native signup, and updates.
- [Why Config-First](https://docs.guapocado.dev/concepts/why-config-first/): Why a config file beats a dashboard-only billing setup — billing becomes reviewable product code, diffs show what changes, and Stripe stays the payment processor without leaking IDs into app logic.

## Concepts

- [Core Concepts](https://docs.guapocado.dev/concepts/core-concepts/): Mental model covering billing config, environments, customers, products, entitlements, checkout, webhook projection, and the two runtime styles (managed edge vs local read model). Includes common mistakes.
- [Billing Primitives](https://docs.guapocado.dev/concepts/primitives/): The eight primitives in depth — Product, Feature, Meter, Limit, Overage, Expansion, Checkout, Context. Explains when to use each and how they map to Stripe objects.
- [Customers](https://docs.guapocado.dev/concepts/customers/): How to choose a customerId for different product shapes (user ID for individual products, org ID for B2B SaaS, workspace ID for multi-workspace). The consistency rule: the same ID must be used for checkout, feature checks, and usage consumption.
- [Environments and Keys](https://docs.guapocado.dev/concepts/environments/): Sandbox vs production separation via API key prefixes. Server keys (`sk_guap_`) for mutations, client keys (`ck_guap_`) for browser-safe reads. Test keys use `_test_`, live keys use `_live_`.

## Frameworks

- [Server SDK](https://docs.guapocado.dev/sdks/server/): Core TypeScript server SDK. Create a client with `createGuapocadoClient({ apiKey, customerId })`. Methods: `has()`, `limit()`, `usage.balance()`, `usage.consume()`, `usage.refund()`, `context()`, `checkout.create()`, `subscription.current()`, `customers.create()`. Includes read-only client variant and error types.
- [Hono](https://docs.guapocado.dev/frameworks/hono/): Hono integration with raw SDK or the `@guapocado/hono` thin wrapper. Middleware-based customerId resolution, feature checks, usage consumption with context batching, limit checks, and checkout routes.
- [Express](https://docs.guapocado.dev/frameworks/express/): Express integration patterns — request middleware that attaches a scoped guap client, usage consumption with refund on failure, checkout with customer creation, typed error handling.
- [Next.js](https://docs.guapocado.dev/frameworks/nextjs/): Next.js App Router patterns — server helper, route handlers, server actions with usage refund fallback, `GuapocadoProvider` for client components, and `useEntitlement` hook.
- [Supabase](https://docs.guapocado.dev/frameworks/supabase/): Supabase Edge Functions wrapper via `@guapocado/supabase`. Exposes a Deno HTTP handler covering all Guapocado routes. Supports custom customerId resolution from Supabase Auth or workspace membership queries.
- [React](https://docs.guapocado.dev/sdks/react/): Browser-safe React SDK using a client key. `GuapocadoProvider` setup, `useEntitlement` for features, `useUsageBalance` for meters, `useLimit` for numeric limits, `useGuapocado` for direct client access.
- [Better Auth](https://docs.guapocado.dev/sdks/better-auth/): Better Auth plugin that maps sessions to Guapocado customers. Server plugin with `guapocado()`, customerId source options (user/organization/team) that preserve the selected entity's native ID, server-side helpers, and a browser client plugin exposing authenticated billing methods without exposing the server key.

## Deployment

- [Deployment Modes](https://docs.guapocado.dev/deployment/modes/): Decision guide — start with managed edge API (no local tables, minimal setup), move to local read model only when you have a concrete reason (latency, availability, local reporting).
- [Managed Edge API](https://docs.guapocado.dev/deployment/managed-edge/): Default mode. SDK calls the hosted Guapocado API. No local tables or workers needed. Works with any server framework or serverless environment. Checkout requires a server key; usage writes happen after the action succeeds.
- [Local Read Model](https://docs.guapocado.dev/deployment/local-read-model/): Optional mode for hot paths or local reporting. Generate Drizzle tables, attach an adapter to the SDK, expose a webhook receiver. Guapocado forwards seven domain event types; the SDK reads locally first and falls back to the hosted API. Writes always go through the hosted API.

## CLI

- [Config Workflow](https://docs.guapocado.dev/cli/config-workflow/): Full CLI reference — `guap init`, `guap login`, `guap plan` (preview diff), `guap push` (apply config), `guap pull`, `guap generate` (local read model types), `guap listen` (dev relay). Covers Stripe price immutability: changing a price amount creates a new Stripe price and deactivates the old one; existing subscribers stay on the old rate until manually migrated.
- [Agent-native Signup](https://docs.guapocado.dev/cli/agent-signup/): How an agent can bootstrap an isolated test workspace, hand the user a claim URL, and preserve the configuration after the user signs in or creates an invited account. Covers the security boundary between the bootstrap key and live-mode access.

## Reference

- [Billing Config Reference](https://docs.guapocado.dev/reference/billing-config/): Complete `billing.config.ts` shape — top-level keys (`entitlements`, `products`, `webhooks`, `generate`), entitlement type definitions, meter reset values, product structure, recurring and one-time pricing modes, product entitlement value shapes, overage definition, expansion definition, webhook forwarding definition.
- [Server SDK API](https://docs.guapocado.dev/reference/server-sdk-api/): Full TypeScript method signatures with parameter and return types. Covers client options, all entitlement methods, usage methods, limit settings, customer creation, context, plans, purchases, subscriptions, checkout, webhook registration, and per-call customer override.
- [HTTP API](https://docs.guapocado.dev/reference/http-api/): Raw HTTP reference for any language. Base URL: `https://api.guapocado.dev`. Authentication via `x-guapocado-key` header. All endpoints: features, limits, usage, context, customers, checkout, plans, subscriptions, purchases, config sync. Includes curl/Python/Go/Ruby examples.
- [API Versioning](https://docs.guapocado.dev/reference/api-versioning/): How SDK and API versions are selected, which compatibility range is accepted, what version headers the SDK sends, and how upgrade and security notices are surfaced.
- [Webhooks](https://docs.guapocado.dev/reference/webhooks/): Guapocado domain events and how to receive them. Seven event types: `customer.updated`, `subscription.updated`, `purchase.completed`, `purchase.updated`, `entitlements.updated`, `invoice.updated`, `usage.updated`. Config-declared receivers, local dev relay, idempotent receiver design.

## Recipes

- [AI Credits](https://docs.guapocado.dev/recipes/ai-credits/): Model an AI credit system as a monthly meter with a free tier, pro tier, and one-time credit pack. Patterns for estimation before generation, consume-after-success with refund on failure, gating premium models as a separate feature entitlement, and displaying balances in React.
- [Seat Limits](https://docs.guapocado.dev/recipes/seat-limits/): Model seat limits as a limit entitlement. Invite flow that counts active members plus pending invites against the limit. Purchasing additional seats via `limits.configure({ purchased })`. Auto-expansion option where the app enforces the business rule about what counts as a billable seat.