npm - @lukoweb/apitogo - Versions diffs - 0.2.29 → 0.2.31 - Mend

@lukoweb/apitogo 0.2.29 → 0.2.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/cli/cli.js +359 -96
package/dist/declarations/cli/platform/client/platform-api.d.ts +16 -1
package/dist/declarations/cli/platform/helpers/platform-plan.d.ts +1 -1
package/docs/cli/commands.md +132 -75
package/docs/cli/go-live.md +135 -123
package/docs/cli/walkthrough.md +40 -1
package/docs/guides/customer-account.md +23 -2
package/package.json +1 -1

package/dist/declarations/cli/platform/client/platform-api.d.ts CHANGED Viewed

@@ -203,7 +203,8 @@ export interface ProjectSubscriptionDto {
     availableCurrencies: string[];
 }
 export interface CheckoutSessionResponse {
-    url: string;
+    url: string | null;
+    granted?: boolean;
 }
 export interface DeploymentTokenResponse {
     token: string;
@@ -443,6 +444,12 @@ export interface ProjectIdentityRequestBody {
     portalRedirectUris: string[];
     nativeSignup?: boolean;
 }
+export interface DevPortalBillingDto {
+    jobId: string;
+    mode: string;
+    webhookUrl: string;
+    hasWebhookSecret: boolean;
+}
 export interface DevPortalIdentityLinkDto {
     jobId: string;
 }
@@ -525,6 +532,7 @@ export declare class PlatformApiClient {
     createCheckoutSession(projectId: string, body: {
         planSlug: string;
         currency?: string;
+        skipPayment?: boolean;
     }): Promise<CheckoutSessionResponse>;
     getLatestAzureInfrastructureStatus(projectId: string): Promise<DeployStatusResponse>;
     retryAzureInfrastructure(projectId: string): Promise<StartDeployResponse>;
@@ -560,6 +568,13 @@ export declare class PlatformApiClient {
     deleteProjectIdentityConnection(projectId: string, connectionId: string): Promise<void>;
     getProjectIdentity(projectId: string): Promise<ProjectIdentityDto | null>;
     deleteProjectIdentity(projectId: string): Promise<ProjectIdentityDto | null>;
+    putDevPortalBilling(projectId: string, body: {
+        provider: "stripe" | "none";
+        apiKey?: string;
+        webhookSecret?: string;
+        successUrl?: string;
+        cancelUrl?: string;
+    }): Promise<DevPortalBillingDto>;
     linkDevPortalIdentity(projectId: string): Promise<DevPortalIdentityLinkDto>;
     getDevPortalBackend(projectId: string): Promise<DevPortalBackendDto | null>;
     getDevPortalSetupStatus(projectId: string): Promise<DevPortalSetupStatusDto>;

package/dist/declarations/cli/platform/helpers/platform-plan.d.ts CHANGED Viewed

@@ -3,7 +3,7 @@ import type { ProgressReporter } from "./progress.js";
 export declare function isPlatformPlanUnselected(planTier: string | undefined | null): boolean;
 export declare function isPlatformPlanSelected(subscription: ProjectSubscriptionDto): boolean;
 export declare function isPaidPlanTier(planTier: string): boolean;
-export declare function isPaidPlanActive(subscription: ProjectSubscriptionDto): boolean;
+export declare function isPaidPlanActive(subscription: Pick<ProjectSubscriptionDto, "planTier" | "subscriptionLifecycle">): boolean;
 export declare function isPlatformPlanReady(subscription: ProjectSubscriptionDto): boolean;
 export interface PlatformPlanWaitResult {
     status: "succeeded" | "timeout" | "failed";

package/docs/cli/commands.md CHANGED Viewed

@@ -1,75 +1,132 @@
----
-title: CLI commands
-description: APItoGo CLI command catalog by category.
-sidebar_icon: wrench
----
-Commands are exposed by the **`apitogo`** binary (`@lukoweb/apitogo`). The CLI is the **source of
-truth** for init, config, deploy, status, teardown, project create, and check. MCP tools spawn these
-same commands so agents and humans get identical behavior.
-## Lifecycle (prefer these)
-| Command          | Role                                                                  |
-| ---------------- | --------------------------------------------------------------------- |
-| `init`           | Scaffold portal (default `./dev-portal`; OpenAPI discovery + secrets) |
-| `config`         | Write or update `apitogo.config.json` (interactive or flags)          |
-| `run`            | Local preview server                                                  |
-| `build`          | Production build (`--preview` to serve locally)                       |
-| `check`          | Publish readiness (secrets, manifest, site validation)                |
-| `project create` | Create a platform project (plan unselected)                           |
-| `deploy`         | Publish config to platform (apihub + portal)                          |
-| `status`         | Account, project, and live readiness                                  |
-| `teardown --yes` | Delete the linked platform project                                    |
-## Scaffold and config
-| Command      | Role                                                                                                        |
-| ------------ | ----------------------------------------------------------------------------------------------------------- |
-| `init [dir]` | Folder (default `dev-portal`); `--name`, `--install` (default), `--overwrite`, `--json`, `--openapi-search` |
-| `config`     | Interactive on TTY; flags: `--openapi`, `--page-*`, `--plan`, `--backend`, `--theme`, `--patch`, `--json`   |
-`npx @lukoweb/apitogo@latest init` auto-wires nearby OpenAPI and `docs/`/`doc/` markdown after
-scaffold. See [Install the CLI](./setup.md#scaffold-options).
-See [Make config (CLI)](../configuration/make-config.mdx) for all `config` flags.
-## Local development
-| Command           | Role                                                      |
-| ----------------- | --------------------------------------------------------- |
-| `run`             | Run the local portal server (`--port`, `--open`, `--ssr`) |
-| `build`           | Production static build                                   |
-| `build --preview` | Build then serve locally                                  |
-## Platform (requires API credentials)
-| Command                    | Role                                                           |
-| -------------------------- | -------------------------------------------------------------- |
-| `project create --name`    | Create platform project only                                   |
-| `check`                    | Dry-run publish readiness                                      |
-| `deploy`                   | Full publish — project, plans, apihub, portal backend/frontend |
-| `deploy --only <resource>` | Limit to `apihub`, `portal-backend`, or `portal-frontend`      |
-| `deploy --force`           | Redeploy selected resources even when healthy                  |
-| `deploy --platform-plan`   | Select Free / Starter / Professional hosting                   |
-| `deploy --resume-from`     | Resume interrupted publish                                     |
-| `status`                   | Whoami + project + live verification                           |
-| `teardown --yes`           | Delete platform project (confirmation required)                |
-Env: `APITOGO_API_KEY_ID`, `APITOGO_API_SECRET`. Optional: `APITOGO_API_URL`.
-## Hand-edit exceptions
-| Change            | Where                                                    |
-| ----------------- | -------------------------------------------------------- |
-| Home page content | `landing/LandingPage.tsx`                                |
-| Site footer       | `apitogo.config.json` → `modules.landing.content.footer` |
-There is no CLI command for arbitrary home page content.
-## Related
-- [Overview](./overview.md)
-- [Shape](./shape.md)
-- [Go live](./go-live.md)
-- [MCP tools](../mcp/tools.md) — agent tool catalog (spawn the CLI)
+---
+title: CLI commands
+description: APItoGo CLI command catalog by category.
+sidebar_icon: wrench
+---
+Commands are exposed by the **`apitogo`** binary (`@lukoweb/apitogo`). The CLI is the **source of
+truth** for init, config, deploy, status, teardown, project create, and check. MCP tools spawn these
+same commands so agents and humans get identical behavior.
+## Lifecycle (prefer these)
+| Command          | Role                                                                     |
+| ---------------- | ------------------------------------------------------------------------ |
+| `init`           | Scaffold portal (default `./dev-portal`; OpenAPI discovery + secrets)    |
+| `config`         | Write or update `apitogo.config.json` (interactive or flags)             |
+| `run`            | Local preview server                                                     |
+| `build`          | Production build (`--preview` to serve locally)                          |
+| `check`          | Publish readiness (secrets, manifest, site validation)                   |
+| `project create` | Create the platform project (Free plan in version 2) and link the folder |
+| `deploy`         | Publish config to platform (apihub + portal)                             |
+| `status`         | Account, project, and live readiness                                     |
+| `teardown --yes` | Delete the linked platform project                                       |
+## Scaffold and config
+| Command      | Role                                                                                                        |
+| ------------ | ----------------------------------------------------------------------------------------------------------- |
+| `init [dir]` | Folder (default `dev-portal`); `--name`, `--install` (default), `--overwrite`, `--json`, `--openapi-search` |
+| `config`     | Interactive on TTY; flags: `--openapi`, `--page-*`, `--plan`, `--backend`, `--theme`, `--patch`, `--json`   |
+`npx @lukoweb/apitogo@latest init` auto-wires nearby OpenAPI and `docs/`/`doc/` markdown after
+scaffold. See [Install the CLI](./setup.md#scaffold-options).
+See [Make config (CLI)](../configuration/make-config.mdx) for all `config` flags.
+## Local development
+| Command           | Role                                                      |
+| ----------------- | --------------------------------------------------------- |
+| `run`             | Run the local portal server (`--port`, `--open`, `--ssr`) |
+| `build`           | Production static build                                   |
+| `build --preview` | Build then serve locally                                  |
+## Platform (requires API credentials)
+| Command                    | Role                                                                                                     |
+| -------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `project create`           | Create the platform project only; version 2 also selects Free, waits for hosting and writes `project.id` |
+| `check`                    | Dry-run publish readiness                                                                                |
+| `deploy`                   | Full publish — project, plans, apihub, portal backend/frontend                                           |
+| `deploy --only <resource>` | Limit to `apihub`, `portal-backend`, or `portal-frontend`                                                |
+| `deploy --force`           | Redeploy selected resources even when healthy                                                            |
+| `deploy --platform-plan`   | Select Free / Starter / Professional hosting                                                             |
+| `deploy --resume-from`     | Resume interrupted publish                                                                               |
+| `status`                   | Whoami + project + live verification                                                                     |
+| `teardown --yes`           | Delete platform project (confirmation required)                                                          |
+Env: `APITOGO_API_KEY_ID`, `APITOGO_API_SECRET`. Optional: `APITOGO_API_URL`.
+## Config version 2: create the project, then deploy
+```bash
+npx apitogo project create
+npx apitogo deploy
+```
+`project create` makes the platform project, selects the **Free** plan (or the plan from `--plan`),
+waits for the hosting that the enabled services need, and writes `project.id` into
+`apitogo.config.json`. `deploy` then publishes each service. It needs the project id from
+`project.id`, from `--project-id`, or from `APITOGO_DEFAULT_PROJECT_ID`, and says so when it has
+none.
+| `project create` option | In version 2                                                       |
+| ----------------------- | ------------------------------------------------------------------ |
+| `--name`                | Optional. Defaults to `project.name`                               |
+| `--description`         | Optional                                                           |
+| `--plan`                | `free` (default), `starter` or `professional`. See below           |
+| `--no-open`             | Print the checkout link of a paid plan and do not open the browser |
+| `--modules`             | Ignored. The modules come from the config (the portal needs one)   |
+| `--no-wait`             | Return before the hosting is ready                                 |
+| `--json`                | Print raw JSON only                                                |
+| `deploy` option   | In version 2                                               |
+| ----------------- | ---------------------------------------------------------- |
+| `--only`          | `portal`, `gateway`, `identity`, `plans` (comma-separated) |
+| `--env`           | Static Web App environment (default: production)           |
+| `--force`         | Redeploy even when nothing changed                         |
+| `--resume-from`   | Resume the publish ledger from a step id                   |
+| `--no-wait`       | Do not wait for long-running jobs                          |
+| `--platform-plan` | Ignored. The plan is chosen by `project create --plan`     |
+| `--project-name`  | Ignored. The name is `project.name`                        |
+### Selling paid plans needs Starter or Professional
+A project on the **Free** platform plan can only publish free plans, and its limits are capped. To
+charge your customers, create the project on a paid platform plan:
+```bash
+npx apitogo project create --plan starter
+```
+The command makes the project, then prints a link to the platform's own checkout (and opens it in
+your browser). You pay there, and the command waits until the payment is confirmed (up to 15
+minutes) before it waits for the hosting. If it stops early, run the same command again: it
+continues the same project and does not start a second checkout. With `--json` the command prints
+the link and exits, and a later run continues.
+Only a **new** project can be created on a paid plan. A project that is already on the Free plan, or
+on the other paid plan, is not moved: create a new project in a new folder, or change the plan in
+the web app.
+This is what you pay APItoGo for hosting. What your customers pay you for your plans is separate
+(see `plans.billing` in the config).
+See [Walkthrough: from an empty folder to a customer's first call](./walkthrough.md).
+## Hand-edit exceptions
+| Change            | Where                                                    |
+| ----------------- | -------------------------------------------------------- |
+| Home page content | `landing/LandingPage.tsx`                                |
+| Site footer       | `apitogo.config.json` → `modules.landing.content.footer` |
+There is no CLI command for arbitrary home page content.
+## Related
+- [Overview](./overview.md)
+- [Shape](./shape.md)
+- [Go live](./go-live.md)
+- [MCP tools](../mcp/tools.md) — agent tool catalog (spawn the CLI)

package/docs/cli/go-live.md CHANGED Viewed

@@ -1,123 +1,135 @@
----
-title: Go live with CLI
-description:
-  Publish an APIToGo developer portal with npx apitogo deploy — platform plans, secrets, and status.
-sidebar_icon: rocket
----
-**Go live** publishes your shaped portal to APItoGo hosting, optionally deploys the backend, upserts
-gateway plans, and verifies the live site. `npx apitogo deploy` is the source of truth; MCP
-`publish_dev_portal` spawns the same CLI.
-## Before you publish
-1. Confirm **gateway / API plans** in `apitogo.config.json`. Do not invent Free + Pro unless you
-   chose them.
-2. Save secrets in the site **`.env`** (never commit or paste into tickets):
-   ```sh
-   APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
-   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
-   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
-   # Only when you have paid project plans:
-   APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
-   APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
-   ```
-3. Export platform credentials and choose a **platform hosting** plan: **Free**, **Starter**, or
-   **Professional**. Starter and Professional use Stripe checkout on the platform.
-   **Free** cannot publish **paid gateway plans** (`priceAmount > 0`) or attach a **custom domain**.
-   If your manifest has paid API tiers, use Starter or Professional — see
-   [Gateway plans](../configuration/plans.md).
-   ```bash
-   export APITOGO_API_KEY_ID=apk_...
-   export APITOGO_API_SECRET=...
-   ```
-## Happy path
-```bash
-cd ./dev-portal
-npx apitogo deploy --platform-plan free
-npx apitogo status
-```
-`npx apitogo deploy`:
-- Creates or links the platform project
-- Provisions modules and syncs gateway plans
-- Deploys the API hub (when configured)
-- Updates the portal backend (including auth API URL in `.env`) and builds + deploys the portal
-  frontend
-If deploy is blocked, fix the reported checklist (missing secrets, plan, OpenAPI). Do not invent
-credentials.
-After success, register **`manualSteps.oidcRedirectUri`** in your IdP. When Stripe is required for
-paid gateway plans, create a webhook at `manualSteps.stripeWebhookUrl` for the listed events.
-Do not treat warm-pool URLs as live until deploy and status succeed.
-## Target specific resources
-```bash
-npx apitogo deploy --only apihub
-npx apitogo deploy --only portal-backend
-npx apitogo deploy --only portal-frontend
-npx apitogo deploy --only apihub,portal-frontend
-npx apitogo deploy --only portal-frontend --force
-```
-| Resource          | What it updates                                  |
-| ----------------- | ------------------------------------------------ |
-| `apihub`          | Gateway plans/baseline, API hub package + deploy |
-| `portal-backend`  | Dev-portal module settings and plan catalog      |
-| `portal-frontend` | Site build + Static Web App deploy               |
-Omit `--only` to apply all three. Use `--force` to redeploy even when hashes match.
-## Other deploy flags
-| Flag              | Purpose                               |
-| ----------------- | ------------------------------------- |
-| `--project-id`    | Override project GUID                 |
-| `--project-name`  | Display name when creating a project  |
-| `--platform-plan` | `free` \| `starter` \| `professional` |
-| `--resume-from`   | Resume publish ledger from step id    |
-| `--no-wait`       | Do not wait for long-running jobs     |
-| `--json`          | Print raw JSON result only            |
-Resume state is stored in `.apitogo/publish-state.json`.
-## After publish
-```bash
-npx apitogo status              # account + project + live checks
-npx apitogo status --skip-live  # skip live health probes
-npx apitogo teardown --yes      # delete the platform project
-```
-## Platform plan vs API plans
-| Kind             | Meaning                                     | How                                                                |
-| ---------------- | ------------------------------------------- | ------------------------------------------------------------------ |
-| Platform hosting | Free / Starter / Professional on APItoGo    | `--platform-plan`                                                  |
-| Gateway / API    | End-user SKUs and rate limits on `/pricing` | `apitogo.config.json` — [Gateway plans](../configuration/plans.md) |
-## CLI deploy vs MCP publish
-| Path                     | Use when                                     |
-| ------------------------ | -------------------------------------------- |
-| `npx apitogo deploy`     | Terminal, CI, scripts — full product go-live |
-| MCP `publish_dev_portal` | Agent-driven go-live with the same engine    |
-## Related
-- [Shape](./shape.md)
-- [Commands](./commands.md)
-- [Authentication](../configuration/authentication.md)
-- [Manifest](../configuration/manifest.md)
-- [Gateway plans](../configuration/plans.md)
-- [MCP go live](../mcp/go-live.md)
+---
+title: Go live with CLI
+description:
+  Publish an APIToGo developer portal with npx apitogo deploy — platform plans, secrets, and status.
+sidebar_icon: rocket
+---
+**Go live** publishes your shaped portal to APItoGo hosting, optionally deploys the backend, upserts
+gateway plans, and verifies the live site. `npx apitogo deploy` is the source of truth; MCP
+`publish_dev_portal` spawns the same CLI.
+:::note
+This page describes **config version 1** projects (the older `dev-portal` scaffold). A config
+version 2 project, which `npx @lukoweb/apitogo@latest init` creates by default, is published
+differently: run `npx apitogo project create`, then `npx apitogo deploy`. Its resources are
+`portal`, `gateway`, `identity` and `plans`, and the options `--platform-plan` and `--project-name`
+do not apply. See [Walkthrough: from an empty folder to a customer's first call](./walkthrough.md)
+and
+[Config version 2: create the project, then deploy](./commands.md#config-version-2-create-the-project-then-deploy).
+:::
+## Before you publish
+1. Confirm **gateway / API plans** in `apitogo.config.json`. Do not invent Free + Pro unless you
+   chose them.
+2. Save secrets in the site **`.env`** (never commit or paste into tickets):
+   ```sh
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
+   # Only when you have paid project plans:
+   APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
+   APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
+   ```
+3. Export platform credentials and choose a **platform hosting** plan: **Free**, **Starter**, or
+   **Professional**. Starter and Professional use Stripe checkout on the platform.
+   **Free** cannot publish **paid gateway plans** (`priceAmount > 0`) or attach a **custom domain**.
+   If your manifest has paid API tiers, use Starter or Professional — see
+   [Gateway plans](../configuration/plans.md).
+   ```bash
+   export APITOGO_API_KEY_ID=apk_...
+   export APITOGO_API_SECRET=...
+   ```
+## Happy path
+```bash
+cd ./dev-portal
+npx apitogo deploy --platform-plan free
+npx apitogo status
+```
+`npx apitogo deploy`:
+- Creates or links the platform project
+- Provisions modules and syncs gateway plans
+- Deploys the API hub (when configured)
+- Updates the portal backend (including auth API URL in `.env`) and builds + deploys the portal
+  frontend
+If deploy is blocked, fix the reported checklist (missing secrets, plan, OpenAPI). Do not invent
+credentials.
+After success, register **`manualSteps.oidcRedirectUri`** in your IdP. When Stripe is required for
+paid gateway plans, create a webhook at `manualSteps.stripeWebhookUrl` for the listed events.
+Do not treat warm-pool URLs as live until deploy and status succeed.
+## Target specific resources
+```bash
+npx apitogo deploy --only apihub
+npx apitogo deploy --only portal-backend
+npx apitogo deploy --only portal-frontend
+npx apitogo deploy --only apihub,portal-frontend
+npx apitogo deploy --only portal-frontend --force
+```
+| Resource          | What it updates                                  |
+| ----------------- | ------------------------------------------------ |
+| `apihub`          | Gateway plans/baseline, API hub package + deploy |
+| `portal-backend`  | Dev-portal module settings and plan catalog      |
+| `portal-frontend` | Site build + Static Web App deploy               |
+Omit `--only` to apply all three. Use `--force` to redeploy even when hashes match.
+## Other deploy flags
+| Flag              | Purpose                               |
+| ----------------- | ------------------------------------- |
+| `--project-id`    | Override project GUID                 |
+| `--project-name`  | Display name when creating a project  |
+| `--platform-plan` | `free` \| `starter` \| `professional` |
+| `--resume-from`   | Resume publish ledger from step id    |
+| `--no-wait`       | Do not wait for long-running jobs     |
+| `--json`          | Print raw JSON result only            |
+Resume state is stored in `.apitogo/publish-state.json`.
+## After publish
+```bash
+npx apitogo status              # account + project + live checks
+npx apitogo status --skip-live  # skip live health probes
+npx apitogo teardown --yes      # delete the platform project
+```
+## Platform plan vs API plans
+| Kind             | Meaning                                     | How                                                                |
+| ---------------- | ------------------------------------------- | ------------------------------------------------------------------ |
+| Platform hosting | Free / Starter / Professional on APItoGo    | `--platform-plan`                                                  |
+| Gateway / API    | End-user SKUs and rate limits on `/pricing` | `apitogo.config.json` — [Gateway plans](../configuration/plans.md) |
+## CLI deploy vs MCP publish
+| Path                     | Use when                                     |
+| ------------------------ | -------------------------------------------- |
+| `npx apitogo deploy`     | Terminal, CI, scripts — full product go-live |
+| MCP `publish_dev_portal` | Agent-driven go-live with the same engine    |
+## Related
+- [Shape](./shape.md)
+- [Commands](./commands.md)
+- [Authentication](../configuration/authentication.md)
+- [Manifest](../configuration/manifest.md)
+- [Gateway plans](../configuration/plans.md)
+- [MCP go live](../mcp/go-live.md)

package/docs/cli/walkthrough.md CHANGED Viewed

@@ -108,7 +108,46 @@ What the gateway answers:
 The customer sees their calls on the **Usage** page. See
 [Your customers' account pages](../guides/customer-account.md).
-## 5. Remove a test project
+## 5. Sell a paid plan (optional)
+Free plans need no payment. To charge your customers, the project needs two things: a Starter or
+Professional plan with APItoGo, and your own Stripe account. Your customers pay you, not APItoGo.
+1. Create the project on a paid platform plan: `npx apitogo project create --plan starter`. This
+   opens the platform's checkout for the hosting fee. A project that already exists on the Free plan
+   cannot be moved: create a new one. See
+   [Selling paid plans needs Starter or Professional](./commands.md#selling-paid-plans-needs-starter-or-professional).
+2. In your Stripe account, copy the secret key (it starts with `sk_test_` while you test). Store it
+   as a project secret. The command asks for the value, so it stays out of the config:
+   ```bash
+   npx apitogo secrets set STRIPE_KEY
+   ```
+3. Turn billing on in `apitogo.config.json`:
+   ```json
+   "plans": {
+     "billing": { "provider": "stripe", "apiKey": "secret:STRIPE_KEY" }
+   }
+   ```
+4. Give a plan a price in `plans.json`: `"priceAmount": 49`, `"priceCurrency": "usd"` and
+   `"billingPeriod": "month"`. Its limits cannot be higher than your platform plan allows. A plan
+   with a price is refused while billing is off, so nobody is offered a plan they cannot pay for.
+5. Deploy: `npx apitogo deploy`. The output says whether Stripe is in test or live mode and prints
+   your portal's webhook address.
+6. In Stripe, add that address as a webhook endpoint with the events `checkout.session.completed`,
+   `customer.subscription.updated`, `customer.subscription.deleted` and `invoice.payment_failed`.
+   Copy the signing secret (it starts with `whsec_`), store it with
+   `npx apitogo secrets set STRIPE_WEBHOOK`, add `"webhookSecret": "secret:STRIPE_WEBHOOK"` next to
+   `apiKey`, and deploy again. Until then a payment does not activate the plan, because the portal
+   cannot confirm it came from Stripe.
+While you use a test key, pay with [Stripe's test cards](https://docs.stripe.com/testing). No real
+money moves. Never type a live key until you have tested the whole path.
+## 6. Remove a test project
 ```bash
 npx apitogo teardown --yes

package/docs/guides/customer-account.md CHANGED Viewed

@@ -28,7 +28,27 @@ The plans come from `plans.json`. A plan has a name, limits, and optionally a pr
 subscribes to a plan and may hold more than one. Unsubscribing from a plan stops that plan's keys
 from working and keeps the customer's other plans.
-Free plans work without any payment. For paid plans see the `plans.billing` setting.
+Free plans work without any payment. For paid plans see
+[Sell a paid plan](../cli/walkthrough.md#5-sell-a-paid-plan-optional).
+### Paying for a plan
+A plan with a price sends the customer to Stripe's checkout page. The portal never sees the card
+details.
+1. The customer chooses the plan and pays on Stripe's page.
+2. Stripe returns the customer to **Billing**. The page says it is confirming the payment for a few
+   seconds, because Stripe tells the portal separately. Then the plan is active and the customer can
+   create a key for it.
+3. If the customer closes the checkout or goes back, the **Plans** page says checkout was cancelled
+   and nothing was charged.
+If a payment fails, Stripe retries it. The subscription shows as past due. When Stripe finally
+cancels it, the plan ends and its keys stop working with `401`. The customer is not moved to a free
+plan on their own. They can subscribe to one on the **Plans** page.
+What you see is in your own Stripe account: payments, customers and refunds. APItoGo does not take a
+share and does not issue refunds. Tax, trials and refunds are not handled by the portal.
 ## API keys
@@ -59,9 +79,10 @@ the customer calls, those calls show as errors in the usage page.
 | What the customer sees                        | What to check                                                                                     |
 | --------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `401` with a key that should work             | The key was revoked, or the plan was cancelled. Check the key on the API keys page.               |
+| `401` with a key that should work             | The key was revoked, or the plan was cancelled or its payment ended. Check the API keys page.     |
 | `401` on a project you set up by hand         | `gateway.policies.access`: when it also requires a login token, a key alone is refused.           |
 | `429`                                         | The plan's limit was reached. The rate limit renews each period; the quota carries `Retry-After`. |
+| A customer paid but has no plan               | The webhook is missing or its signing secret is wrong. Check it in Stripe and in `plans.billing`. |
 | The usage page shows nothing after real calls | Calls only count when made with a key. Check that the gateway has been deployed with plans.       |
 | Calls from the portal's own pages are blocked | Run `npx apitogo deploy` again. The gateway lists the portal's address after the portal exists.   |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "type": "module",
   "sideEffects": [
     "**/*.css",