@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/customization/fonts.md

@@ -1,110 +1,105 @@
----
-sidebar_icon: baseline
-title: Font & Typography
-sidebar_label: Font & Typography
-description:
-  Learn how to customize fonts and typography in APIToGo using predefined Google Fonts, custom font
-  URLs, or local fonts for sans, serif, and monospace text.
----
-
-APIToGo allows you to customize fonts for text (`sans`), serif content (`serif`), and code (`mono`).
-You can use predefined Google Fonts, external sources, or local fonts.
-
-## Predefined Google Fonts
-
-The easiest way to use fonts is with predefined Google Fonts. Simply specify the font name as a
-string:
-
-```ts title=config
-const config = {
-  theme: {
-    fonts: {
-      sans: "Inter",
-      serif: "Merriweather",
-      mono: "JetBrains Mono",
-    },
-  },
-};
-```
-
-### Available Google Fonts
-
-The following fonts are available as predefined options:
-
-**Sans Serif:** Inter, Roboto, Open Sans, Poppins, Montserrat, Outfit, Plus Jakarta Sans, DM Sans,
-IBM Plex Sans, Geist, Oxanium, Space Grotesk
-
-**Serif:** Architects Daughter, Merriweather, Playfair Display, Lora, Source Serif Pro, Libre
-Baskerville
-
-**Monospace:** JetBrains Mono, Fira Code, Source Code Pro, IBM Plex Mono, Roboto Mono, Space Mono,
-Geist Mono
-
-## Custom Font URLs
-
-For more control or to use fonts not in the predefined list, you can specify a custom font URL:
-
-```ts title=config
-const config = {
-  theme: {
-    fonts: {
-      sans: {
-        url: "https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap",
-        fontFamily: "Roboto, sans-serif",
-      },
-      mono: {
-        url: "https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@400;700&display=swap",
-        fontFamily: "Roboto Mono, monospace",
-      },
-    },
-  },
-};
-```
-
-## Local Fonts
-
-To use local fonts, add them to the `public` folder and create a `fonts.css` file:
-
-```css
-@font-face {
-  font-family: "CustomFont";
-  font-style: normal;
-  font-weight: 400;
-  src: url("/custom-font-400.woff2") format("woff2");
-}
-```
-
-Then reference the local CSS file:
-
-```ts title=config
-const config = {
-  theme: {
-    fonts: {
-      sans: {
-        url: "/fonts.css",
-        fontFamily: "CustomFont, sans-serif",
-      },
-    },
-  },
-};
-```
-
-## Mixed Configuration
-
-You can mix predefined fonts with custom fonts:
-
-```ts title=config
-const config = {
-  theme: {
-    fonts: {
-      sans: "Inter", // Predefined Google Font
-      serif: {
-        // Custom font
-        url: "/custom-serif.css",
-        fontFamily: "CustomSerif, serif",
-      },
-      mono: "Fira Code", // Predefined Google Font
-    },
-  },
-};
-```
+---
+sidebar_icon: baseline
+title: Font & Typography
+sidebar_label: Font & Typography
+description:
+  Learn how to customize fonts and typography in APIToGo using predefined Google Fonts, custom font
+  URLs, or local fonts for sans, serif, and monospace text.
+---
+
+APIToGo allows you to customize fonts for text (`sans`), serif content (`serif`), and code (`mono`).
+You can use predefined Google Fonts, external sources, or local fonts.
+
+Fonts go under `fonts` in the portal's theme file, **`apitogo/portal/theme.json`**. See
+[Colors & theme](./colors-theme.mdx) for the rest of that file. Local font files go in
+`apitogo/portal/public/`, which the portal serves at `/`.
+
+## Predefined Google Fonts
+
+The easiest way to use fonts is with predefined Google Fonts. Simply specify the font name as a
+string:
+
+```json title=apitogo/portal/theme.json
+{
+  "fonts": {
+    "sans": "Inter",
+    "serif": "Merriweather",
+    "mono": "JetBrains Mono"
+  }
+}
+```
+
+### Available Google Fonts
+
+The following fonts are available as predefined options:
+
+**Sans Serif:** Inter, Roboto, Open Sans, Poppins, Montserrat, Outfit, Plus Jakarta Sans, DM Sans,
+IBM Plex Sans, Geist, Oxanium, Space Grotesk
+
+**Serif:** Architects Daughter, Merriweather, Playfair Display, Lora, Source Serif Pro, Libre
+Baskerville
+
+**Monospace:** JetBrains Mono, Fira Code, Source Code Pro, IBM Plex Mono, Roboto Mono, Space Mono,
+Geist Mono
+
+## Custom Font URLs
+
+For more control or to use fonts not in the predefined list, you can specify a custom font URL:
+
+```json title=apitogo/portal/theme.json
+{
+  "fonts": {
+    "sans": {
+      "url": "https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap",
+      "fontFamily": "Roboto, sans-serif"
+    },
+    "mono": {
+      "url": "https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@400;700&display=swap",
+      "fontFamily": "Roboto Mono, monospace"
+    }
+  }
+}
+```
+
+## Local Fonts
+
+To use local fonts, add them to the `public` folder and create a `fonts.css` file:
+
+```css
+@font-face {
+  font-family: "CustomFont";
+  font-style: normal;
+  font-weight: 400;
+  src: url("/custom-font-400.woff2") format("woff2");
+}
+```
+
+Then reference the local CSS file:
+
+```json title=apitogo/portal/theme.json
+{
+  "fonts": {
+    "sans": {
+      "url": "/fonts.css",
+      "fontFamily": "CustomFont, sans-serif"
+    }
+  }
+}
+```
+
+## Mixed Configuration
+
+You can mix predefined fonts with custom fonts:
+
+```json title=apitogo/portal/theme.json
+{
+  "fonts": {
+    "sans": "Inter",
+    "serif": {
+      "url": "/custom-serif.css",
+      "fontFamily": "CustomSerif, serif"
+    },
+    "mono": "Fira Code"
+  }
+}
+```

package/docs/customization/landing-page.md

@@ -1,188 +1,189 @@
----
-sidebar_icon: house
-title: Landing Page
-description:
-  Customize your dev portal home page and show your real API operations in the API showcase, loaded
-  live from your dev portal backend.
----
-
-A scaffolded dev portal home page lives in `landing/LandingPage.tsx`. It composes section components
-from `@lukoweb/apitogo-module-landing` inside a `LandingShell`:
-
-| Component             | Purpose                                       |
-| --------------------- | --------------------------------------------- |
-| `HeroSection`         | Headline, description, CTAs and code examples |
-| `TrustSection`        | Logos or social proof                         |
-| `FeaturesSection`     | Feature grid                                  |
-| `StepsSection`        | Numbered "how it works" steps                 |
-| `ApiShowcaseSection`  | Grid or method + path list of your API        |
-| `PlansPreviewSection` | Short plan comparison linking to `/pricing`   |
-| `PricingCtaSection`   | Closing call to action                        |
-
-Edit the file directly to add, remove or reorder sections. The site footer is configured separately
-in `apitogo.config.json` under `modules.landing.content.footer` (see
-[Footer](/docs/configuration/footer)).
-
-## API showcase
-
-`ApiShowcaseSection` renders the items you pass it. The scaffold ships with a **static sample
-list**:
-
-```tsx
-<ApiShowcaseSection
-  apiShowcase={{
-    title: "Sample endpoints",
-    layout: "list", // or "grid"
-    browseAllHref: "/api",
-    items: [
-      { name: "List users", path: "/v1/users", method: "GET", summary: "List paginated users" },
-    ],
-  }}
-/>
-```
-
-Each item accepts `name`, `path`, and optionally `method`, `summary`, `icon` and `latency`.
-
-## Live APIs
-
-Instead of maintaining the list by hand, you can load your API's real operations. Your dev portal
-backend syncs the **gateway actions** of your project (every operation discovered from the OpenAPI
-spec you deployed) and serves them publicly at `GET /api/v1/actions`. The `useGatewayActions()` hook
-fetches that list; you decide what to show and pass the result to `ApiShowcaseSection`.
-
-```tsx
-import {
-  ApiShowcaseSection,
-  LandingShell,
-  toApiShowcaseItems,
-  useGatewayActions,
-} from "@lukoweb/apitogo-module-landing";
-
-const staticItems = [
-  { name: "List users", path: "/v1/users", method: "GET", summary: "List paginated users" },
-];
-
-// Optional friendly labels, keyed by action key (`method:path`, lower-case method).
-const labels: Record<string, string> = {
-  "get:/v1/users": "List paginated users",
-  "post:/v1/orders": "Create an order",
-};
-
-export default function LandingPage() {
-  const { data } = useGatewayActions({ inPlan: true });
-
-  const liveItems = toApiShowcaseItems(
-    (data?.actions ?? []).filter((action) => action.path.startsWith("/v1/")).slice(0, 6),
-    labels,
-  );
-
-  return (
-    <LandingShell title="My API">
-      <ApiShowcaseSection
-        apiShowcase={{
-          title: "Our APIs",
-          layout: "list",
-          browseAllHref: "/api",
-          items: liveItems.length > 0 ? liveItems : staticItems,
-        }}
-      />
-    </LandingShell>
-  );
-}
-```
-
-### Filters
-
-`useGatewayActions()` accepts server-side filters. All filters are combined:
-
-| Option       | Type      | Description                                            |
-| ------------ | --------- | ------------------------------------------------------ |
-| `inPlan`     | `boolean` | Only actions included in at least one active plan      |
-| `plan`       | `string`  | Only actions included in the plan with this SKU        |
-| `isPublic`   | `boolean` | Only actions callable without an API key (or only not) |
-| `method`     | `string`  | HTTP method, e.g. `GET`                                |
-| `pathPrefix` | `string`  | Path prefix, e.g. `/v1/orders`                         |
-| `limit`      | `number`  | Maximum number of actions (server cap: 500)            |
-| `enabled`    | `boolean` | Set to `false` to skip the request                     |
-
-Anything else — sorting, renaming, grouping, picking a hand-curated subset — is up to you in plain
-TypeScript before you build the items.
-
-Each action has this shape:
-
-```ts
-type GatewayAction = {
-  actionKey: string; // e.g. "get:/orders/{id}"
-  method: string; // e.g. "GET"
-  path: string; // e.g. "/orders/{id}"
-  isPublic: boolean; // callable without an API key
-};
-```
-
-Actions only carry the method and path. Use the `summaries` argument of `toApiShowcaseItems()` (or
-your own mapping) to add human-friendly names.
-
-### Always keep a fallback
-
-The hook runs in the browser only, so the prerendered HTML never contains a stale list. `data` is
-`undefined`:
-
-- while the request is loading,
-- if the request fails,
-- in preview and demo mode, or when no dev portal backend URL is configured (for example in
-  `npm run dev` before your portal is provisioned).
-
-`ApiShowcaseSection` renders nothing for an empty list, so pass a static fallback as shown above.
-
-### What becomes public
-
-`GET /api/v1/actions` is anonymous: **every operation in the OpenAPI spec deployed to your gateway
-is listable**, including ones you may not document in the portal. Use `inPlan: true` to limit the
-list to operations your plans actually sell, and remove internal operations from the spec you deploy
-to the gateway if they must not be discoverable.
-
-### Freshness and limits
-
-- The backend syncs actions at startup and on the plan sync interval (15 minutes by default). A new
-  release shows up after the next sync.
-- Responses are cacheable for 5 minutes (`Cache-Control: public, max-age=300`).
-- The endpoint is rate limited per client IP (60 requests per minute).
-
-### Troubleshooting
-
-- **The list is always the fallback:** check that `authentication.apiBaseUrl` (or
-  `VITE_APITOGO_AUTHENTICATION_API_BASE_URL`) points at your dev portal backend and is not the
-  placeholder URL.
-- **CORS errors:** the backend only allows the portal's configured frontend URL. Serving the site
-  from another domain requires adding it to the backend's allowed origins.
-- **Empty list on a new portal:** the portal is not activated yet, or the gateway has no release.
-  Deploy your backend, then wait for the next sync.
-
-## Plans preview
-
-`PlansPreviewSection` shows the same plans as `/pricing`. The scaffold loads them with the
-`usePlansPreview` hook from the billing plugin, so you only maintain plans in one place —
-`modules.userPanel.plans.items` in `apitogo.config.json`:
-
-```tsx
-import { usePlansPreview } from "@lukoweb/apitogo-plugin-dev-portal-billing";
-
-export default function LandingPage() {
-  const plans = usePlansPreview();
-
-  return (
-    <LandingShell title="…">
-      {/* … */}
-      <PlansPreviewSection plans={plans} />
-    </LandingShell>
-  );
-}
-```
-
-In a live portal the plans come from your dev portal backend (`GET /api/v1/plans`); in local
-preview, and while the live catalog loads, they come from `apitogo.config.json`. Each card shows the
-plan's `displayName`, price and billing period, and its first two feature lines (`features`, or
-lines derived from `limits`). The highlighted card matches the "Popular" plan on `/pricing`.
-
-To write the cards by hand instead, pass a static array of `{ name, price, unit, blurb, featured }`
-objects to `plans`.
+---
+sidebar_icon: house
+title: Landing Page
+description:
+  Customize your dev portal home page and show your real API operations in the API showcase, loaded
+  live from your dev portal backend.
+---
+
+The portal's home page is a React file: `apitogo/portal/landing/LandingPage.tsx`, named by
+`portal.landing` in `apitogo.config.json`. `apitogo add portal` writes a starter one (or
+`apitogo create --template full`). It composes section components from
+`@lukoweb/apitogo-module-landing` inside a `LandingShell`:
+
+| Component             | Purpose                                       |
+| --------------------- | --------------------------------------------- |
+| `HeroSection`         | Headline, description, CTAs and code examples |
+| `TrustSection`        | Logos or social proof                         |
+| `FeaturesSection`     | Feature grid                                  |
+| `StepsSection`        | Numbered "how it works" steps                 |
+| `ApiShowcaseSection`  | Grid or method + path list of your API        |
+| `PlansPreviewSection` | Short plan comparison linking to `/pricing`   |
+| `PricingCtaSection`   | Closing call to action                        |
+
+Edit the file directly to add, remove or reorder sections. Remove `portal.landing` from the config
+to have no home page: `/` then opens the first docs page. The footer is a file of its own (see
+[Footer](../configuration/footer.mdx)).
+
+## API showcase
+
+`ApiShowcaseSection` renders the items you pass it. The scaffold ships with a **static sample
+list**:
+
+```tsx
+<ApiShowcaseSection
+  apiShowcase={{
+    title: "Sample endpoints",
+    layout: "list", // or "grid"
+    browseAllHref: "/api",
+    items: [
+      { name: "List users", path: "/v1/users", method: "GET", summary: "List paginated users" },
+    ],
+  }}
+/>
+```
+
+Each item accepts `name`, `path`, and optionally `method`, `summary`, `icon` and `latency`.
+
+## Live APIs
+
+Instead of maintaining the list by hand, you can load your API's real operations. Your dev portal
+backend syncs the **gateway actions** of your project (every operation discovered from the OpenAPI
+spec you deployed) and serves them publicly at `GET /api/v1/actions`. The `useGatewayActions()` hook
+fetches that list; you decide what to show and pass the result to `ApiShowcaseSection`.
+
+```tsx
+import {
+  ApiShowcaseSection,
+  LandingShell,
+  toApiShowcaseItems,
+  useGatewayActions,
+} from "@lukoweb/apitogo-module-landing";
+
+const staticItems = [
+  { name: "List users", path: "/v1/users", method: "GET", summary: "List paginated users" },
+];
+
+// Optional friendly labels, keyed by action key (`method:path`, lower-case method).
+const labels: Record<string, string> = {
+  "get:/v1/users": "List paginated users",
+  "post:/v1/orders": "Create an order",
+};
+
+export default function LandingPage() {
+  const { data } = useGatewayActions({ inPlan: true });
+
+  const liveItems = toApiShowcaseItems(
+    (data?.actions ?? []).filter((action) => action.path.startsWith("/v1/")).slice(0, 6),
+    labels,
+  );
+
+  return (
+    <LandingShell title="My API">
+      <ApiShowcaseSection
+        apiShowcase={{
+          title: "Our APIs",
+          layout: "list",
+          browseAllHref: "/api",
+          items: liveItems.length > 0 ? liveItems : staticItems,
+        }}
+      />
+    </LandingShell>
+  );
+}
+```
+
+### Filters
+
+`useGatewayActions()` accepts server-side filters. All filters are combined:
+
+| Option       | Type      | Description                                            |
+| ------------ | --------- | ------------------------------------------------------ |
+| `inPlan`     | `boolean` | Only actions included in at least one active plan      |
+| `plan`       | `string`  | Only actions included in the plan with this SKU        |
+| `isPublic`   | `boolean` | Only actions callable without an API key (or only not) |
+| `method`     | `string`  | HTTP method, e.g. `GET`                                |
+| `pathPrefix` | `string`  | Path prefix, e.g. `/v1/orders`                         |
+| `limit`      | `number`  | Maximum number of actions (server cap: 500)            |
+| `enabled`    | `boolean` | Set to `false` to skip the request                     |
+
+Anything else — sorting, renaming, grouping, picking a hand-curated subset — is up to you in plain
+TypeScript before you build the items.
+
+Each action has this shape:
+
+```ts
+type GatewayAction = {
+  actionKey: string; // e.g. "get:/orders/{id}"
+  method: string; // e.g. "GET"
+  path: string; // e.g. "/orders/{id}"
+  isPublic: boolean; // callable without an API key
+};
+```
+
+Actions only carry the method and path. Use the `summaries` argument of `toApiShowcaseItems()` (or
+your own mapping) to add human-friendly names.
+
+### Always keep a fallback
+
+The hook runs in the browser only, so the prerendered HTML never contains a stale list. `data` is
+`undefined`:
+
+- while the request is loading,
+- if the request fails,
+- in preview and demo mode, or when no dev portal backend URL is configured (for example in
+  `npm run dev` before your portal is provisioned).
+
+`ApiShowcaseSection` renders nothing for an empty list, so pass a static fallback as shown above.
+
+### What becomes public
+
+`GET /api/v1/actions` is anonymous: **every operation in the OpenAPI spec deployed to your gateway
+is listable**, including ones you may not document in the portal. Use `inPlan: true` to limit the
+list to operations your plans actually sell, and remove internal operations from the spec you deploy
+to the gateway if they must not be discoverable.
+
+### Freshness and limits
+
+- The backend syncs actions at startup and on the plan sync interval (15 minutes by default). A new
+  release shows up after the next sync.
+- Responses are cacheable for 5 minutes (`Cache-Control: public, max-age=300`).
+- The endpoint is rate limited per client IP (60 requests per minute).
+
+### Troubleshooting
+
+- **The list is always the fallback:** the project has no plans backend yet. Add `plans` to the
+  config and run `npx apitogo deploy`.
+- **CORS errors:** the backend only allows the portal's configured frontend URL. Serving the site
+  from another domain requires adding it to the backend's allowed origins.
+- **Empty list on a new portal:** the portal is not activated yet, or the gateway has no release.
+  Deploy your backend, then wait for the next sync.
+
+## Plans preview
+
+`PlansPreviewSection` shows the same plans as `/pricing`. The scaffold loads them with the
+`usePlansPreview` hook from the billing plugin, so you only maintain plans in one place,
+`apitogo/plans.json`:
+
+```tsx
+import { usePlansPreview } from "@lukoweb/apitogo-plugin-dev-portal-billing";
+
+export default function LandingPage() {
+  const plans = usePlansPreview();
+
+  return (
+    <LandingShell title="…">
+      {/* … */}
+      <PlansPreviewSection plans={plans} />
+    </LandingShell>
+  );
+}
+```
+
+In a live portal the plans come from your dev portal backend (`GET /api/v1/plans`); in local
+preview, and while the live catalog loads, they come from `apitogo/plans.json`. Each card shows the
+plan's `displayName`, price and billing period, and its first two feature lines (`features`, or
+lines derived from `limits`). The highlighted card matches the "Popular" plan on `/pricing`.
+
+To write the cards by hand instead, pass a static array of `{ name, price, unit, blurb, featured }`
+objects to `plans`.

package/docs/deploy/apitogo.md

@@ -1,17 +1,13 @@
-# Deploy with APIToGo CLI
-
-Platform publish is **`npx apitogo deploy`** — the same engine as MCP `publish_dev_portal`.
-
-Full walkthrough (prerequisites, secrets, `--only`, status, teardown):
-
-→ **[Go live with CLI](../cli/go-live.md)**
-
-Quick reference:
-
-```bash
-export APITOGO_API_KEY_ID=apk_...
-export APITOGO_API_SECRET=...
-cd ./dev-portal
-npx apitogo deploy --platform-plan free
-npx apitogo status
-```
+# Deploy with the APItoGo CLI
+
+```bash
+npx apitogo login
+npx apitogo deploy
+npx apitogo status
+```
+
+`deploy` creates the project on its first run, then sets up every service in `apitogo.config.json`.
+`--only portal` (or `gateway`, `identity`, `plans`) deploys one of them.
+
+Full walkthrough (sign-in, secrets, `--only`, status, teardown):
+**[Go live with CLI](../cli/go-live.md)**.