zuplo 6.70.70 → 6.71.0

package/docs/cli/deploy.partial.mdx

@@ -25,6 +25,38 @@ zuplo deploy --project my-project
 zuplo deploy --project my-project --environment my-env-name
 ```
 
+### Deploying from CI/CD
+
+Without `--environment`, the CLI names the environment after the current git
+branch. CI systems usually check out a detached HEAD, in which case the CLI
+resolves the branch from the remote branches that contain the checked-out
+commit. Two cases break this inference:
+
+- On GitHub Actions `pull_request` events, the checkout is the pull request
+  merge ref (`refs/pull/<number>/merge`) — a commit that doesn't exist on any
+  branch — so the environment is named after that ref instead of your branch.
+- When the checked-out commit exists on more than one branch, the first match
+  wins, which may not be the branch that triggered the build.
+
+Always pass `--environment` explicitly in CI so that every trigger deploys the
+same, predictably named environment:
+
+```bash
+# GitHub Actions: github.head_ref is the source branch on pull_request
+# events; github.ref_name is the branch on push events
+zuplo deploy --project my-project --environment "$BRANCH_NAME"
+```
+
+Deploying the same environment name always updates the same environment and
+keeps its URL stable across deploys. This matters whenever an external system
+must match the URL exactly — an OIDC token audience, a webhook registration, or
+an allowlist. Capture the URL from the deploy output (`Deployed to
+https://...`) rather than constructing it from the branch name: the URL
+hostname uses a normalized, truncated form of the environment name plus a
+unique identifier. See
+[Branch-Based Deployments](../articles/branch-based-deployments.mdx) for the
+naming rules.
+
 ## Polling timeout
 
 By default, the deploy command polls the status of the deployment every second

package/docs/concepts/api-keys.md

@@ -50,8 +50,8 @@ After successful validation, the policy populates `request.user`:
 - `request.user.data` contains the consumer's metadata (plan, customerId, etc.)
 
 This lets downstream policies and handlers make authorization decisions, apply
-per-consumer [rate limits](./rate-limiting.md), or forward identity to your
-backend.
+per-consumer [rate limits](../rate-limiting/how-it-works.md), or forward
+identity to your backend.
 
 :::note
 

package/docs/dedicated/akamai/architecture.mdx

@@ -229,7 +229,7 @@ Zuplo and your backend services. For complete documentation, see
 | **Shared Secret / API Key** | Add a secret header to requests that only the gateway knows. Simple to implement and widely used by companies like Stripe and Supabase.            |
 | **Zuplo JWT Service**       | Issue signed JWTs that your backend validates using Zuplo's JWKS endpoint. Provides cryptographic proof that requests originate from your gateway. |
 | **mTLS (Mutual TLS)**       | Certificate-based authentication where both gateway and backend present certificates. Provides zero-trust security for enterprise requirements.    |
-| **Cloud Provider IAM**      | Use AWS IAM, GCP Identity-Aware Proxy, or Azure AD to authorize requests. No credentials to manage - uses federated identity.                      |
+| **Cloud Provider IAM**      | Use AWS IAM, GCP Identity-Aware Proxy, or Microsoft Entra ID to authorize requests. No credentials to manage - uses federated identity.            |
 | **Secure Tunnel (VPN)**     | WireGuard-based tunnel for backends that can't be exposed to the internet. Useful for on-premise or bare-metal deployments.                        |
 | **Private Network**         | VPC peering, PrivateLink, or Transit Gateway for private connectivity without traversing the public internet.                                      |
 
@@ -238,14 +238,14 @@ Zuplo and your backend services. For complete documentation, see
 While most authentication methods work anywhere, some approaches are better
 suited for specific scenarios:
 
-| Backend Location             | Recommended Methods                               | Notes                                                                       |
-| ---------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- |
-| **Akamai Connected Cloud**   | Shared secret, Zuplo JWT, mTLS                    | All methods work well; choose based on your security requirements           |
-| **AWS**                      | AWS IAM (federated identity), mTLS, shared secret | IAM provides credential-free auth; works with Lambda, API Gateway, ECS, EKS |
-| **GCP**                      | GCP Identity-Aware Proxy, GCP Service Auth, mTLS  | IAP provides zero-trust access to Cloud Run, GKE, and Compute Engine        |
-| **Azure**                    | Azure AD Service Auth, mTLS, shared secret        | Azure AD integrates with App Service, Functions, and AKS                    |
-| **On-Premise / Data Center** | Secure tunnel, mTLS, shared secret                | Tunnel allows private connectivity; mTLS provides strong authentication     |
-| **Third-Party APIs**         | Shared secret, API keys, mTLS                     | Use whatever the third-party API supports                                   |
+| Backend Location             | Recommended Methods                                  | Notes                                                                       |
+| ---------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------- |
+| **Akamai Connected Cloud**   | Shared secret, Zuplo JWT, mTLS                       | All methods work well; choose based on your security requirements           |
+| **AWS**                      | AWS IAM (federated identity), mTLS, shared secret    | IAM provides credential-free auth; works with Lambda, API Gateway, ECS, EKS |
+| **GCP**                      | GCP Identity-Aware Proxy, GCP Service Auth, mTLS     | IAP provides zero-trust access to Cloud Run, GKE, and Compute Engine        |
+| **Azure**                    | Microsoft Entra ID Service Auth, mTLS, shared secret | Microsoft Entra ID integrates with App Service, Functions, and AKS          |
+| **On-Premise / Data Center** | Secure tunnel, mTLS, shared secret                   | Tunnel allows private connectivity; mTLS provides strong authentication     |
+| **Third-Party APIs**         | Shared secret, API keys, mTLS                        | Use whatever the third-party API supports                                   |
 
 ### Choosing an authentication method
 

package/docs/dev-portal/zudoku/components/browser-window.mdx

@@ -0,0 +1,94 @@
+---
+title: Browser Window
+sidebar_icon: app-window
+---
+
+import { BrowserWindow } from "zudoku/components";
+import { Button } from "zudoku/ui/Button";
+
+A mock browser window for presenting UI previews, screenshots-as-code, or full page layouts in your
+documentation. It renders its children inside a browser-style frame with a URL bar and an optional
+zoom control — the current scale is displayed like in a real browser and readers can zoom in and out
+themselves.
+
+## Import
+
+```tsx
+import { BrowserWindow } from "zudoku/components";
+```
+
+## Usage
+
+<BrowserWindow>
+  <div className="flex flex-col items-center gap-3 p-10 text-center">
+    <span className="text-2xl font-bold">Hello, world!</span>
+    <p className="text-muted-foreground">Any content renders inside the browser frame.</p>
+    <Button>Get started</Button>
+  </div>
+</BrowserWindow>
+
+```tsx
+<BrowserWindow>
+  <div className="flex flex-col items-center gap-3 p-10 text-center">
+    <span className="text-2xl font-bold">Hello, world!</span>
+    <p className="text-muted-foreground">Any content renders inside the browser frame.</p>
+    <Button>Get started</Button>
+  </div>
+</BrowserWindow>
+```
+
+## Scale
+
+Use the `scale` prop to set the initial zoom of the content. This is useful for presenting
+full-width layouts, like a landing page, at a reduced size. Passing a `scale` enables the zoom
+control in the toolbar showing the current scale — readers can change it with the `+`/`-` buttons or
+click the percentage to reset it, just like in a real browser. Without a `scale`, the zoom control
+is hidden and the content renders at full size (pass `scale={1}` to start at 100% with the control
+enabled).
+
+<BrowserWindow scale={0.5}>
+  <div className="flex flex-col items-center gap-3 p-10 text-center">
+    <span className="text-4xl font-bold">Scaled to 50%</span>
+    <p className="text-muted-foreground">
+      The content is laid out at full width and scaled down to fit.
+    </p>
+  </div>
+</BrowserWindow>
+
+```tsx
+<BrowserWindow scale={0.5}>
+  <div className="flex flex-col items-center gap-3 p-10 text-center">
+    <span className="text-4xl font-bold">Scaled to 50%</span>
+    <p className="text-muted-foreground">
+      The content is laid out at full width and scaled down to fit.
+    </p>
+  </div>
+</BrowserWindow>
+```
+
+Scaling affects layout, not just size: at `scale={0.5}` the content is laid out at twice the
+container width and scaled down, so responsive layouts behave as if viewed on a larger screen.
+
+## URL
+
+Set the `url` prop to change the address shown in the URL bar (defaults to `localhost:3000`):
+
+<BrowserWindow url="https://developers.example.com">
+  <p className="p-10 text-center text-muted-foreground">Your developer portal</p>
+</BrowserWindow>
+
+```tsx
+<BrowserWindow url="https://developers.example.com">
+  <p className="p-10 text-center text-muted-foreground">Your developer portal</p>
+</BrowserWindow>
+```
+
+## Props
+
+| Prop               | Type        | Description                                                                                                                                      |
+| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `url`              | `string`    | Address displayed in the URL bar. Defaults to `localhost:3000`.                                                                                  |
+| `scale`            | `number`    | Initial zoom of the content (e.g. `0.75` for 75%). Enables the zoom control; if omitted, the control is hidden and content renders at full size. |
+| `className`        | `string`    | Additional classes for the outer frame.                                                                                                          |
+| `contentClassName` | `string`    | Additional classes for the content viewport.                                                                                                     |
+| `children`         | `ReactNode` | The content rendered inside the browser window.                                                                                                  |

package/docs/dev-portal/zudoku/components/callout.mdx

@@ -193,24 +193,17 @@ Or pass any React node as the `icon` to override the default for the chosen `typ
 ## Customize colors
 
 Each callout type is driven by a single CSS variable that determines the icon, border tint, and
-background tint via `color-mix`. Override any of them in your theme's `customCss` to recolor a type
-globally:
-
-```ts title="zudoku.config.ts"
-export default {
-  theme: {
-    customCss: `
-      :root {
-        --callout-tip: oklch(0.65 0.18 160);
-        --callout-sparkles: oklch(0.6 0.22 320);
-      }
-      .dark {
-        --callout-tip: oklch(0.78 0.18 160);
-        --callout-sparkles: oklch(0.75 0.2 320);
-      }
-    `,
-  },
-};
+background tint via `color-mix`. Override any of them in your stylesheet to recolor a type globally:
+
+```css title=styles.css
+:root {
+  --callout-tip: oklch(0.65 0.18 160);
+  --callout-sparkles: oklch(0.6 0.22 320);
+}
+.dark {
+  --callout-tip: oklch(0.78 0.18 160);
+  --callout-sparkles: oklch(0.75 0.2 320);
+}
 ```
 
 All available variables:

package/docs/dev-portal/zudoku/components/landing-page.mdx

@@ -0,0 +1,283 @@
+---
+title: Landing Page
+sidebar_icon: layout-template
+---
+
+import { BrowserWindow, LandingPage } from "zudoku/components";
+import { BookOpenIcon, CodeIcon, KeyIcon, RocketIcon, WebhookIcon, ZapIcon } from "zudoku/icons";
+
+A ready-made, customizable landing page for your developer portal. It comes in three variants
+covering the most common layouts: a centered hero, a two-column split hero, and a compact
+documentation hub.
+
+Use it as the `element` of a [custom page](/dev-portal/zudoku/custom-pages) — typically your home page:
+
+```tsx title=zudoku.config.tsx
+import { LandingPage } from "zudoku/components";
+
+const config = {
+  navigation: [
+    {
+      type: "custom-page",
+      path: "/",
+      element: (
+        <LandingPage
+          title="Build with our API"
+          description="Everything you need to integrate in minutes."
+          actions={[
+            { label: "Get started", href: "/getting-started" },
+            { label: "API Reference", href: "/api" },
+          ]}
+        />
+      ),
+    },
+    // ...
+  ],
+};
+```
+
+## Import
+
+```tsx
+import { LandingPage } from "zudoku/components";
+```
+
+## Variants
+
+### Hero (default)
+
+A centered hero with call-to-action buttons and an optional feature grid below. The classic landing
+page for product-focused portals. The previews on this page are presented in a
+[Browser Window](./browser-window) component.
+
+<BrowserWindow url="https://developers.example.com" scale={0.75} contentClassName="px-8">
+  <LandingPage
+    eyebrow="Developer Platform"
+    title="Build with our API"
+    description="Everything you need to integrate payments, webhooks, and more — in minutes, not days."
+    actions={[
+      { label: "Get started", href: "/docs/getting-started" },
+      { label: "API Reference", href: "/docs", variant: "outline" },
+    ]}
+    features={[
+      {
+        icon: <ZapIcon />,
+        title: "Fast integration",
+        description: "Go from zero to your first API call in under five minutes.",
+      },
+      {
+        icon: <KeyIcon />,
+        title: "API keys built in",
+        description: "Issue, rotate, and revoke keys right from the portal.",
+      },
+      {
+        icon: <WebhookIcon />,
+        title: "Webhooks",
+        description: "Subscribe to events and react to changes in real time.",
+      },
+    ]}
+  />
+</BrowserWindow>
+
+```tsx
+<LandingPage
+  eyebrow="Developer Platform"
+  title="Build with our API"
+  description="Everything you need to integrate payments, webhooks, and more — in minutes, not days."
+  actions={[
+    { label: "Get started", href: "/getting-started" },
+    { label: "API Reference", href: "/api", variant: "outline" },
+  ]}
+  features={[
+    {
+      icon: <ZapIcon />,
+      title: "Fast integration",
+      description: "Go from zero to your first API call in under five minutes.",
+    },
+    {
+      icon: <KeyIcon />,
+      title: "API keys built in",
+      description: "Issue, rotate, and revoke keys right from the portal.",
+    },
+    {
+      icon: <WebhookIcon />,
+      title: "Webhooks",
+      description: "Subscribe to events and react to changes in real time.",
+    },
+  ]}
+/>
+```
+
+### Split
+
+A two-column hero with your own content on the side — an illustration, screenshot, or code sample
+passed via the `aside` prop. A great fit for developer-oriented portals that want to show code up
+front.
+
+<BrowserWindow url="https://shipping.example.com" scale={0.75} contentClassName="px-8">
+  <LandingPage
+    variant="split"
+    eyebrow="Shipping API"
+    title="Ship anywhere in the whole universe"
+    description="Create and manage shipments, track packages in real-time, and integrate with multiple carriers through a single interface."
+    actions={[
+      { label: "Get started", href: "/docs/getting-started" },
+      { label: "View on GitHub", href: "https://github.com/zuplo/zudoku", variant: "outline" },
+    ]}
+    aside={
+      <div className="rounded-xl border bg-card p-4 font-mono text-sm">
+        <pre>{`curl https://api.example.com/v1/shipments \\
+  -H "Authorization: Bearer $API_KEY" \\
+  -d destination="alpha-centauri"`}</pre>
+      </div>
+    }
+  />
+</BrowserWindow>
+
+```tsx
+<LandingPage
+  variant="split"
+  eyebrow="Shipping API"
+  title="Ship anywhere in the whole universe"
+  description="Create and manage shipments, track packages in real-time, and integrate with multiple carriers through a single interface."
+  actions={[
+    { label: "Get started", href: "/getting-started" },
+    {
+      label: "View on GitHub",
+      href: "https://github.com/zuplo/zudoku",
+      variant: "outline",
+    },
+  ]}
+  aside={
+    <div className="rounded-xl border bg-card p-4 font-mono text-sm">
+      <pre>{`curl https://api.example.com/v1/shipments \\
+  -H "Authorization: Bearer $API_KEY" \\
+  -d destination="alpha-centauri"`}</pre>
+    </div>
+  }
+/>
+```
+
+The `aside` accepts any React node — use an `<img />` for an illustration instead of code:
+
+```tsx
+<LandingPage
+  variant="split"
+  title="Ship anywhere"
+  aside={<img src="/hero.webp" alt="Hero" className="rounded-3xl" />}
+/>
+```
+
+### Grid
+
+A compact header followed by prominent, clickable feature cards. Ideal as a documentation hub that
+routes visitors to the right section quickly.
+
+<BrowserWindow url="https://developers.example.com/docs" scale={0.75} contentClassName="px-8">
+  <LandingPage
+    variant="grid"
+    title="Documentation"
+    description="Explore guides, API references, and examples to get the most out of the platform."
+    features={[
+      {
+        icon: <RocketIcon />,
+        title: "Getting Started",
+        description: "Set up your account and make your first request.",
+        href: "/docs/getting-started",
+      },
+      {
+        icon: <BookOpenIcon />,
+        title: "Guides",
+        description: "Step-by-step tutorials for common use cases.",
+        href: "/docs",
+      },
+      {
+        icon: <CodeIcon />,
+        title: "API Reference",
+        description: "Complete reference for every endpoint and type.",
+        href: "/docs",
+      },
+      {
+        icon: <WebhookIcon />,
+        title: "Webhooks",
+        description: "Listen to events and build real-time integrations.",
+        href: "/docs",
+      },
+    ]}
+  />
+</BrowserWindow>
+
+```tsx
+<LandingPage
+  variant="grid"
+  title="Documentation"
+  description="Explore guides, API references, and examples to get the most out of the platform."
+  features={[
+    {
+      icon: <RocketIcon />,
+      title: "Getting Started",
+      description: "Set up your account and make your first request.",
+      href: "/getting-started",
+    },
+    {
+      icon: <BookOpenIcon />,
+      title: "Guides",
+      description: "Step-by-step tutorials for common use cases.",
+      href: "/guides",
+    },
+    {
+      icon: <CodeIcon />,
+      title: "API Reference",
+      description: "Complete reference for every endpoint and type.",
+      href: "/api",
+    },
+    {
+      icon: <WebhookIcon />,
+      title: "Webhooks",
+      description: "Listen to events and build real-time integrations.",
+      href: "/webhooks",
+    },
+  ]}
+/>
+```
+
+## Props
+
+| Prop          | Type                          | Description                                                                                      |
+| ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `variant`     | `"hero" \| "split" \| "grid"` | Layout variant. Defaults to `"hero"`.                                                            |
+| `title`       | `ReactNode`                   | Main headline. Required.                                                                         |
+| `eyebrow`     | `ReactNode`                   | Short label displayed above the title.                                                           |
+| `description` | `ReactNode`                   | Supporting text below the title.                                                                 |
+| `actions`     | `LandingPageAction[]`         | Call-to-action buttons. Each action has `label`, `href`, and an optional Button `variant`.       |
+| `features`    | `LandingPageFeature[]`        | Feature cards with optional `icon`, `title`, `description`, and `href` (making the card a link). |
+| `aside`       | `ReactNode`                   | Side content for the `split` variant (image, code sample, …).                                    |
+| `children`    | `ReactNode`                   | Additional content rendered below the built-in sections.                                         |
+| `className`   | `string`                      | Additional classes for the outer `<section>`.                                                    |
+
+### Links
+
+`href` values in `actions` and `features` are rendered as client-side router links for internal
+paths (e.g. `/getting-started`) and as regular links opening in a new tab for external URLs (e.g.
+`https://github.com/...`).
+
+## Customization
+
+- **Buttons**: The first action defaults to the primary button style, all following actions to
+  `outline`. Override per action with `variant` (any [Button](/dev-portal/zudoku/components/button) variant).
+- **Rich titles**: `title`, `description`, and `eyebrow` accept any React node, so you can use
+  custom markup like highlighted words:
+  `title={<>Ship <span className="text-primary">faster</span></>}`.
+- **Extra sections**: Pass `children` to append your own sections (testimonials, pricing, …) below
+  the built-in layout.
+- **Page metadata**: Combine with the [Head](/dev-portal/zudoku/components/head) component to set the page title:
+
+```tsx
+import { Head, LandingPage } from "zudoku/components";
+
+<LandingPage title="Build with our API">
+  <Head>
+    <title>Home</title>
+  </Head>
+</LandingPage>;
+```

package/docs/dev-portal/zudoku/configuration/search.md

@@ -167,3 +167,39 @@ your [Dev Portal Configuration](./overview.md):
   // ...
 }
 ```
+
+### Customizing Inkeep
+
+Any other [base settings](https://docs.inkeep.com/cloud/ui-components/common-settings/base) can be
+set alongside the required fields, for example `filters` to scope results or `transformSource` to
+customize how sources are displayed.
+
+You can also pass
+[`searchSettings`](https://docs.inkeep.com/cloud/ui-components/common-settings/search),
+[`aiChatSettings`](https://docs.inkeep.com/cloud/ui-components/common-settings/ai-chat), and
+`modalSettings` to customize the respective parts of the search experience. They are merged with
+Zudoku's defaults and passed through to Inkeep as-is, so any option Inkeep supports can be used —
+including ones added after this Dev Portal version was released.
+
+For example, to categorize results into tabs based on their URL:
+
+```typescript
+{
+  // ...
+  search: {
+    type: "inkeep",
+    // ...required fields from above
+    transformSource: (source) => {
+      if (!source.url.includes("/blog/")) return source;
+      return { ...source, tabs: [...(source.tabs ?? []), "Blog"] };
+    },
+    searchSettings: {
+      tabs: [["All", { isAlwaysVisible: true }], "Blog"],
+    },
+    aiChatSettings: {
+      aiAssistantName: "My Assistant",
+    },
+  },
+  // ...
+}
+```

package/docs/dev-portal/zudoku/configuration/site.md

@@ -127,6 +127,44 @@ export const NotFound = () => (
 
 ## Layout
 
+### Collapsible Sidebar
+
+The navigation sidebar is collapsible by default. A small toggle button on the sidebar's right
+border lets users hide and reveal it. Configure the behavior under `site.sidebar`:
+
+```tsx title=zudoku.config.tsx
+{
+  site: {
+    sidebar: {
+      collapsible: true, // default: true. Set to false to disable the toggle entirely.
+      toggleVisibility: "always", // "always" (default) or "hover" — show button only when hovering the sidebar's right edge
+      togglePosition: "bottom", // "top", "center", or "bottom" (default)
+    },
+  }
+}
+```
+
+For finer vertical placement, override the `--sidebar-toggle-y` CSS variable in your stylesheet:
+
+```css
+:root {
+  --sidebar-toggle-y: 30%;
+}
+```
+
+The toggle button carries `aria-expanded="true"` when the sidebar is open and `"false"` when
+collapsed. Combine it with the `[data-sidebar-toggle]` selector to position the button differently
+per state:
+
+```css
+[data-sidebar-toggle][aria-expanded="true"] {
+  --sidebar-toggle-y: 20%;
+}
+[data-sidebar-toggle][aria-expanded="false"] {
+  --sidebar-toggle-y: 80%;
+}
+```
+
 ### Banner
 
 Add a banner message to the top of the page: