@lukoweb/apitogo 0.2.56 → 0.2.57

package/docs/deployment.md

@@ -1,9 +1,15 @@
-# Deployment
-
-| Path                           | Docs                                 |
-| ------------------------------ | ------------------------------------ |
-| **CLI** (`npx apitogo deploy`) | [Go live with CLI](./cli/go-live.md) |
-| **MCP / agents**               | [Go live](./mcp/go-live.md)          |
-
-Local-only builds: `npx apitogo build` (optional `--preview`). Platform publish is always
-`npx apitogo deploy`.
+# Deployment
+
+Your portal, gateway, sign-in and plans are deployed to APItoGo with one command:
+
+```bash
+npx apitogo deploy
+```
+
+| Path             | Docs                                                                                      |
+| ---------------- | ----------------------------------------------------------------------------------------- |
+| **CLI**          | [Deploy with the APItoGo CLI](./deploy/apitogo.md) · [Go live with CLI](./cli/go-live.md) |
+| **MCP / agents** | [Go live](./mcp/go-live.md)                                                               |
+
+To check the portal before deploying, `npx apitogo run` previews it locally and `npx apitogo build`
+makes a production build.

package/docs/guides/stripe-setup.mdx

@@ -0,0 +1,123 @@
+---
+title: Set up Stripe for paid plans
+sidebar_icon: credit-card
+description:
+  Find your Stripe secret key and create the webhook that tells your portal a payment went through,
+  step by step with pictures.
+---
+
+A plan with a price is paid through **your own Stripe account**. `npx apitogo deploy` needs two
+things from Stripe:
+
+| What                   | Starts with              | What it does                                        |
+| ---------------------- | ------------------------ | --------------------------------------------------- |
+| Secret key             | `sk_test_` or `sk_live_` | Lets your plans backend create checkout pages       |
+| Webhook signing secret | `whsec_`                 | Lets your plans backend trust Stripe's payment news |
+
+Deploy asks for both, hidden, and stores them as project secrets. They never go into
+`apitogo.config.json`.
+
+:::tip
+
+Start in a **sandbox** (Stripe's test mode). The pictures below come from one: nothing you do there
+charges real cards. Switch to your live account when you are ready to sell.
+
+:::
+
+## 1. Copy the secret key
+
+In the Stripe dashboard, open **Developers › API keys**. Under **Standard keys**, reveal the
+**Secret key** and copy it.
+
+<Framed>![The API keys page with the publishable and secret keys](./stripe/1-api-keys.jpg)</Framed>
+
+Use the **secret** key. The publishable key (`pk_`) cannot take payments, and deploy refuses it. A
+restricted key (`rk_`) works too, if it may write Checkout Sessions, Customers and Subscriptions.
+
+Run deploy and paste the key when it asks:
+
+```bash
+npx apitogo deploy
+# Stripe secret key (hidden):
+```
+
+## 2. Add the webhook
+
+After a payment, Stripe sends an event to your portal's plans backend. That event is what turns a
+paid checkout into an active plan.
+
+Deploy prints the address to use, for example:
+
+```
+https://portal.<your-portal>.apitogo.com/api/v1/webhooks/stripe
+```
+
+In Stripe, open **Workbench › Webhooks** and choose **Add destination**.
+
+<Framed>
+  ![The Event destinations list with the Add destination button](./stripe/2-event-destinations.jpg)
+</Framed>
+
+Keep **Your account** and the **Snapshot** payload style.
+
+<Framed>![The first step: event destination scope and payload style](./stripe/3-scope.jpg)</Framed>
+
+Search for and select these four events:
+
+- `checkout.session.completed`
+- `customer.subscription.updated`
+- `customer.subscription.deleted`
+- `invoice.payment_failed`
+
+<Framed>![Selected events: the four events ticked](./stripe/4-events.jpg)</Framed>
+
+Choose **Webhook endpoint** as the destination type, then paste the address deploy printed into
+**Endpoint URL** and choose **Create destination**.
+
+<Framed>
+  ![The Configure destination step with the endpoint URL filled in](./stripe/5-endpoint-url.jpg)
+</Framed>
+
+## 3. Copy the signing secret
+
+Open the new destination. Under **Signing secret**, reveal the secret (the eye icon) and copy it.
+
+<Framed>![The destination page with its signing secret](./stripe/6-signing-secret.jpg)</Framed>
+
+Paste it where deploy asks:
+
+```bash
+# Stripe webhook signing secret (hidden, Enter to skip):
+```
+
+If you skipped it, set it later and deploy the plans again:
+
+```bash
+npx apitogo secrets set STRIPE_WEBHOOK
+npx apitogo deploy --only plans
+```
+
+## Check it works
+
+Run `npx apitogo deploy --only plans` again. When Stripe has sent an event, it reports:
+
+```
+Stripe webhook: verified (last event 2 min ago, checkout.session.completed)
+```
+
+Buy your own plan with a [Stripe test card](https://docs.stripe.com/testing#cards), such as
+`4242 4242 4242 4242`, to send the first event.
+
+## Going live
+
+Live mode has its own keys and its own webhooks. Switch to your live account in Stripe, repeat the
+three steps there, and set the new values:
+
+```bash
+npx apitogo secrets set STRIPE_API_KEY
+npx apitogo secrets set STRIPE_WEBHOOK
+npx apitogo deploy --only plans
+```
+
+Selling paid plans needs the **Starter** or **Professional** hosting plan. See
+[Gateway plans](../configuration/plans.md).

package/docs/markdown/frontmatter.md

@@ -1,173 +1,172 @@
----
-sidebar_icon: scissors-line-dashed
-title: Frontmatter
-description:
-  Learn how to use YAML frontmatter in APIToGo markdown files to customize page titles,
-  descriptions, navigation, and other document properties.
----
-
-Frontmatter is metadata written in [YAML](https://yaml.org/) format at the beginning of markdown
-files, enclosed between triple dashes (`---`). It allows you to configure various aspects of your
-pages without affecting the visible content.
-
-In APIToGo, frontmatter enables you to customize page titles, descriptions, navigation settings, and
-other document properties. Here are all the supported properties:
-
-## Properties
-
-### `title`
-
-Sets the page title that appears in the browser tab and as the document title.
-
-```md
----
-title: My Page Title
----
-```
-
-### `description`
-
-Provides a description for the page, which can be used for SEO and content summaries.
-
-```md
----
-description: This page explains how to use APIToGo's markdown features.
----
-```
-
-### `category`
-
-Assigns the page to a specific category for organizational purposes. This will be shown above the
-main heading of the document.
-
-```md
----
-category: Getting Started
----
-```
-
-### `navigation_label`
-
-_Deprecated (`sidebar_label`)_
-
-Sets a custom label for the page in the sidebar navigation, allowing you to use a shorter or
-different title than the main page title.
-
-```md
----
-title: My Very Long Documentation Page Title
-navigation_label: Short Title
----
-```
-
-### `navigation_icon`
-
-_Deprecated (`sidebar_icon`)_
-
-Specifies a [Lucide icon](https://lucide.dev/icons) to display next to the page in the sidebar
-navigation.
-
-```md
----
-navigation_icon: compass
----
-```
-
-### `navigation_display`
-
-Specifies the display property of the navigation item. See the
-[Navigation guide](/docs/configuration/navigation#display-control)
-
-```md
----
-navigation_display: auth
----
-```
-
-### `toc`
-
-Controls whether the table of contents is displayed for the page. Set to `false` to hide the table
-of contents.
-
-```md
----
-toc: false
----
-```
-
-### `disable_pager`
-
-Controls whether the previous/next page navigation is displayed at the bottom of the page. Set to
-`true` to disable it.
-
-```md
----
-disable_pager: true
----
-```
-
-### `draft`
-
-Marks a document as a draft. Draft documents are only visible when running in development mode and
-are excluded from production builds. This is useful for working on content that isn't ready to be
-published.
-
-```md
----
-draft: true
----
-```
-
-:::info
-
-When `draft: true` is set:
-
-- The document will be visible when running `npx apitogo run`
-- The document will be excluded from builds created with `npx apitogo build`
-- The document won't appear in the navigation or be accessible via URL in production
-
-:::
-
-### `lastModifiedTime`
-
-The last modified timestamp for the page. This property is automatically set by APIToGo during the
-build process based on the Git commit history. You generally should not set this manually.
-
-If you need to override the automatically detected date, you can set it explicitly:
-
-```md
----
-lastModifiedTime: 2025-11-20T10:30:00.000Z
----
-```
-
-::if{mode=opensource}
-
-:::info
-
-For accurate last modified dates in deployment environments, ensure full Git history is available
-during builds. See the [Vercel deployment guide](/docs/deploy/vercel#accurate-last-modified-dates)
-for configuration details.
-
-:::
-
-::
-
-## Complete Example
-
-Here's an example showing multiple frontmatter properties used together:
-
-```md title=documentation.md
----
-title: Advanced Configuration Guide
-description: Learn how to configure advanced features in APIToGo
-category: Configuration
-navigation_label: Advanced Config
-navigation_icon: settings
-toc: true
-disable_pager: false
-draft: false
----
-
-This page content follows the frontmatter...
-```
+---
+sidebar_icon: scissors-line-dashed
+title: Frontmatter
+description:
+  Learn how to use YAML frontmatter in APIToGo markdown files to customize page titles,
+  descriptions, navigation, and other document properties.
+---
+
+Frontmatter is metadata written in [YAML](https://yaml.org/) format at the beginning of markdown
+files, enclosed between triple dashes (`---`). It allows you to configure various aspects of your
+pages without affecting the visible content.
+
+In APIToGo, frontmatter enables you to customize page titles, descriptions, navigation settings, and
+other document properties. Here are all the supported properties:
+
+## Properties
+
+### `title`
+
+Sets the page title that appears in the browser tab and as the document title.
+
+```md
+---
+title: My Page Title
+---
+```
+
+### `description`
+
+Provides a description for the page, which can be used for SEO and content summaries.
+
+```md
+---
+description: This page explains how to use APIToGo's markdown features.
+---
+```
+
+### `category`
+
+Assigns the page to a specific category for organizational purposes. This will be shown above the
+main heading of the document.
+
+```md
+---
+category: Getting Started
+---
+```
+
+### `navigation_label`
+
+_Deprecated (`sidebar_label`)_
+
+Sets a custom label for the page in the sidebar navigation, allowing you to use a shorter or
+different title than the main page title.
+
+```md
+---
+title: My Very Long Documentation Page Title
+navigation_label: Short Title
+---
+```
+
+### `order`
+
+The page's place in the sidebar among its siblings, lowest first. Pages without one follow, by name.
+A folder's `index` page always comes first.
+
+```md
+---
+order: 2
+---
+```
+
+### `navigation_icon`
+
+_Deprecated (`sidebar_icon`)_
+
+Specifies a [Lucide icon](https://lucide.dev/icons) to display next to the page in the sidebar
+navigation.
+
+```md
+---
+navigation_icon: compass
+---
+```
+
+### `navigation_display`
+
+When the page shows in the sidebar: `always` (default), `auth` (only to signed-in visitors), `anon`
+(only to signed-out visitors) or `hide`.
+
+```md
+---
+navigation_display: auth
+---
+```
+
+### `toc`
+
+Controls whether the table of contents is displayed for the page. Set to `false` to hide the table
+of contents.
+
+```md
+---
+toc: false
+---
+```
+
+### `disable_pager`
+
+Controls whether the previous/next page navigation is displayed at the bottom of the page. Set to
+`true` to disable it.
+
+```md
+---
+disable_pager: true
+---
+```
+
+### `draft`
+
+Marks a document as a draft. Draft documents are only visible when running in development mode and
+are excluded from production builds. This is useful for working on content that isn't ready to be
+published.
+
+```md
+---
+draft: true
+---
+```
+
+:::info
+
+When `draft: true` is set:
+
+- The document will be visible when running `npx apitogo run`
+- The document will be excluded from builds created with `npx apitogo build`
+- The document won't appear in the navigation or be accessible via URL in production
+
+:::
+
+### `lastModifiedTime`
+
+The last modified timestamp for the page. This property is automatically set by APIToGo during the
+build process based on the Git commit history. You generally should not set this manually.
+
+If you need to override the automatically detected date, you can set it explicitly:
+
+```md
+---
+lastModifiedTime: 2025-11-20T10:30:00.000Z
+---
+```
+
+## Complete Example
+
+Here's an example showing multiple frontmatter properties used together:
+
+```md title=documentation.md
+---
+title: Advanced Configuration Guide
+description: Learn how to configure advanced features in APIToGo
+category: Configuration
+navigation_label: Advanced Config
+navigation_icon: settings
+toc: true
+disable_pager: false
+draft: false
+---
+
+This page content follows the frontmatter...
+```