zuplo 7.8.7 → 7.8.9

package/docs/getting-started/ai-gateway/portal.mdx

@@ -0,0 +1,181 @@
+---
+category: AI Gateway
+showLastModified: false
+suggestEdit: false
+sidebar_label: Portal
+title: Getting Started with AI Gateway - Portal
+description:
+  Create an AI Gateway in the Portal, try the free demo model, and send an
+  authenticated chat request with cURL or the OpenAI SDK.
+---
+
+<WizardSteps build="ai-gateway" method="portal" />
+
+Create an AI Gateway, send a chat request through it, and connect an OpenAI SDK
+client. This tutorial uses the free Zuplo Demo provider, so you don't need a
+provider API key.
+
+## Prerequisites
+
+- A [Zuplo account](https://portal.zuplo.com).
+- A terminal with cURL to test the gateway from outside the Portal.
+
+## Create and test your AI Gateway
+
+<Stepper>
+
+1. **Create an AI Gateway project**
+
+   Open [**Projects**](https://portal.zuplo.com/+/account/projects), click **New
+   Project**, and select **AI Gateway**. Name the project `my-ai-gateway` and
+   click **Create Project**.
+
+   <ModalScreenshot>
+
+   ![New project dialog with AI Gateway selected](/media/ai-gateway-getting-started/create-project.png)
+
+   </ModalScreenshot>
+
+   When setup finishes, the project opens with **Create your first app**. The
+   gateway is already deployed.
+
+2. **Check the demo provider**
+
+   Open
+   [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models).
+   The new project includes **Zuplo Demo**, which provides test models without a
+   provider API key. This tutorial uses `zuplodemo/pirate`.
+
+   <ModalScreenshot>
+
+   ![AI provider settings with the Zuplo Demo provider](/media/ai-gateway-getting-started/providers.png)
+
+   </ModalScreenshot>
+
+   The part before `/` names the provider; the part after `/` names the model.
+   Later, use **Add Provider** to configure your own provider and its models.
+   See [AI Providers](../../ai-gateway/providers.mdx).
+
+3. **Create an app**
+
+   Open [**Apps**](https://portal.zuplo.com/+/account/project/ai/apps) and click
+   **Create App**. Enter `Tutorial app` as the **App name**. Keep the
+   **Default** pool selected and click **Create app**.
+
+   <ModalScreenshot>
+
+   ![New app dialog with an app name and the Default pool](/media/ai-gateway-getting-started/create-app.png)
+
+   </ModalScreenshot>
+
+   An app represents the software that calls your gateway. Each app has its own
+   URL and API key. The first app also creates the Default pool, which groups
+   apps and supplies shared policy settings.
+
+4. **Review authentication**
+
+   Open the app's **Policies** tab. The new app inherits **API Key
+   Authentication** from its pool. Keep this policy in place: requests must send
+   the app's key in the `Authorization` header.
+
+   <ModalScreenshot>
+
+   ![App policy chain with inherited API Key Authentication](/media/ai-gateway-getting-started/policies.png)
+
+   </ModalScreenshot>
+
+   You can add policies for model filtering, budgets, and other controls here.
+   For this first request, keep the default chain. See
+   [Policy Chains](../../ai-gateway/policy-chains.mdx).
+
+5. **Send a request in the Playground**
+
+   Click **Playground** in the app header. Select `zuplodemo/pirate`, enter
+   `Say hello`, and send the message. A pirate-themed reply confirms that the
+   app can reach the provider through the gateway.
+
+   <ModalScreenshot>
+
+   ![AI Playground showing a successful response from the pirate demo model](/media/ai-gateway-getting-started/playground.png)
+
+   </ModalScreenshot>
+
+6. **Call the gateway from a terminal**
+
+   In the **Playground**, click **Copy cURL**. Paste the copied command into
+   your terminal and run it. The command includes the selected model, your
+   conversation, and the app's API key. The response streams into the terminal
+   as it arrives.
+
+   Treat the copied command as a credential because it contains your API key.
+
+</Stepper>
+
+## Connect the OpenAI SDK
+
+Copy **API URL** from the app header and the app's key from its **API Key** tab.
+The URL includes the app ID after the hostname. Copy the complete URL without
+adding `/v1` yet.
+
+<ModalScreenshot>
+
+![App API Key tab with the key concealed](/media/ai-gateway-getting-started/api-key.png)
+
+</ModalScreenshot>
+
+Set these values in your terminal, replacing the placeholders:
+
+```bash
+export ZUPLO_APP_URL="https://YOUR_GATEWAY.zuplo.app/YOUR_APP_ID"
+export ZUPLO_APP_API_KEY="YOUR_APP_API_KEY"
+```
+
+With Node.js 24 or later installed, create a directory for the sample and
+install the SDK in the same terminal:
+
+```bash
+mkdir ai-gateway-client
+cd ai-gateway-client
+npm init -y
+npm install openai
+```
+
+Save this as `sample.mjs` and run `node sample.mjs` from the terminal where you
+set the environment variables:
+
+```javascript title="sample.mjs"
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: `${process.env.ZUPLO_APP_URL}/v1`,
+  apiKey: process.env.ZUPLO_APP_API_KEY,
+});
+
+const result = await client.chat.completions.create({
+  model: "zuplodemo/pirate",
+  messages: [{ role: "user", content: "Say hello" }],
+});
+
+console.log(result.choices[0].message.content);
+```
+
+The OpenAI SDK uses the app URL with `/v1` appended. It sends the app key to
+Zuplo; provider credentials stay in the gateway. See the
+[OpenAI SDK integration](../../ai-gateway/integrations/openai.mdx) for more
+examples.
+
+## Troubleshooting
+
+| Result                         | What to check                                                                                             |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `401 Unauthorized`             | Use the app's API key, not a provider key. Include the `Bearer` prefix.                                   |
+| `404`                          | Copy the complete app URL, including its app ID, then append `/v1/chat/completions`.                      |
+| Model not found or not allowed | Use `zuplodemo/pirate` and confirm Zuplo Demo is enabled. If you added Model Filtering, allow this model. |
+
+## Next steps
+
+- [Add providers](../../ai-gateway/providers.mdx) to connect your own models.
+- [Configure policy chains](../../ai-gateway/policy-chains.mdx) to restrict
+  models or add budgets and guardrails.
+- [Connect source control](../../ai-gateway/source-control.mdx) to deploy code
+  changes from Git.

package/docs/getting-started/dev-portal/agent.mdx

@@ -0,0 +1,148 @@
+---
+category: Developer Portal
+showLastModified: false
+suggestEdit: false
+sidebar_label: Agent
+title: Getting Started with Developer Portal - Agent
+description:
+  Build a developer portal with a coding agent, review its API key
+  configuration, and verify a signed-in request from the API playground.
+---
+
+<WizardSteps build="dev-portal" method="agent" />
+
+<MethodTabs build="dev-portal" method="agent" />
+
+Have a coding agent build a developer portal with an introduction, interactive
+API reference, and API key management. You'll assign a test key and verify the
+portal yourself.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download) 24 or later and Git.
+- A [Zuplo account](https://portal.zuplo.com).
+- An installed coding agent and an email address for the portal sign-in test.
+
+## Build your developer portal with an agent
+
+<Stepper>
+
+1. **Create the project**
+
+   Run:
+
+   ```bash
+   npx create-zuplo-api@latest my-api-project
+   cd my-api-project
+   ```
+
+   When prompted, choose **Yes** to create a matching Portal project, complete
+   sign-in, and select your Zuplo account. Select the coding agent you use when
+   asked. The CLI creates and links the hosted project. See
+   [`create-zuplo-api`](../../cli/create-zuplo-api.mdx).
+
+   :::tip{title="Zuplo skills"}
+
+   The scaffold installs Zuplo skills in this project for Codex and Cursor and
+   configures the Claude Code plugin. If setup fails, follow
+   [Agent Skills](../../build-with-ai.mdx#agent-skills) from this directory
+   before starting your agent.
+
+   :::
+
+2. **Ask the agent to build the portal**
+
+   Open your agent in the project directory and give it this prompt:
+
+   ```text
+   Read the project instructions and bundled Zuplo docs. Customize the default
+   developer portal for a Todo API. Keep the generated project structure.
+
+   In docs/zudoku.config.tsx, set site.title and metadata.title to
+   "Todo Developer Portal" and metadata.description to
+   "Explore the Todo API and manage your API keys." Keep the API reference
+   sourced from ../config/routes.oas.json at /api. Keep demo authentication
+   and apiKeys.enabled for this tutorial.
+
+   Replace docs/pages/introduction.mdx with a short introduction telling users
+   to sign in, find their assigned key under their profile's API Keys menu,
+   and try Get all todos in API Reference. Keep it in navigation. Explain
+   that an administrator assigns a consumer to the user's key manager email;
+   do not implement automatic provisioning.
+
+   In config/policies.json add api-key-auth, policyType api-key-inbound,
+   using ApiKeyInboundPolicy from $import(@zuplo/runtime) with
+   allowUnauthenticatedRequests false. Put it first in the inbound chain for
+   GET /todos in config/routes.oas.json. Preserve the existing URL forward
+   handler. Set this route's corsPolicy to anything-goes for the browser demo.
+   Update info.description so it says GET /todos requires a bearer API key.
+   Do not claim the other sample routes are protected.
+
+   Ensure .env and .env.zuplo are ignored and do not read or print credentials.
+   Run npm run dev. Report the gateway and Docs Server URLs. Verify GET /todos
+   without a key returns 401. Do not deploy; show me the diff and explain how
+   to finish the signed-in browser test with a Dev consumer.
+   ```
+
+3. **Review and open the result**
+
+   Review `git diff`. Confirm the reference still points to
+   `../config/routes.oas.json`, API keys remain enabled, and authentication is
+   attached to `GET /todos`.
+
+   With `npm run dev` running, open the **Docs Server** URL printed in the
+   terminal, normally `http://localhost:9200`. Open `/introduction` to check
+   your new page, then open **API Reference** to check the Todo API.
+
+4. **Assign a test key**
+
+   In the Zuplo Portal, open your project and go to
+   [**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services).
+   Select **Dev** and click **Create Consumer**. Enter `tutorial-consumer` for
+   **Subject**, your email under **Key managers**, and `{}` for **Metadata**.
+   Click **Save consumer**.
+
+   <ModalScreenshot>
+
+   ![Create a consumer and assign a key manager email](/media/api-key-consumer-bucket-portal-ui/create-consumer-modal.png)
+
+   </ModalScreenshot>
+
+5. **Verify the signed-in experience**
+
+   Sign in to the local developer portal with the key manager email. Open **API
+   Keys** from your profile menu and confirm the key appears. Then open **API
+   Reference → Get all todos**, click **Test**, expand **Authentication**,
+   select `tutorial-consumer`, and click **Send**. Expect `200 OK` and todos in
+   the response.
+
+   Test without credentials in a terminal:
+
+   ```bash
+   curl -i http://localhost:9000/todos
+   ```
+
+   Expect `401 Unauthorized`. If browser requests fail while cURL succeeds,
+   check the route's [CORS configuration](../../articles/cors.mdx). If the key
+   is missing, check the consumer's email and Dev bucket.
+
+6. **Publish after review**
+
+   Follow [Deploy to the edge](../gateway/deploy-to-the-edge/local.mdx), then
+   open **Deployment URLs → Dev Portal** in the Zuplo Portal. Create a consumer
+   in the **Prod** bucket to test the deployed portal.
+
+   Replace the demo authentication with your own
+   [identity provider](../../dev-portal/zudoku/configuration/authentication.md)
+   and restrict CORS to your portal's origin before inviting users.
+
+</Stepper>
+
+## Next steps
+
+- [Editor tutorial](./local.mdx) for the exact policy configuration and manual
+  walkthrough.
+- [Create consumers on login](../../dev-portal/dev-portal-create-consumer-on-auth.mdx)
+  to automate key assignment with your own identity provider.
+- [Customize navigation](../../dev-portal/zudoku/configuration/navigation.mdx)
+  and add pages for your API's users.

package/docs/getting-started/dev-portal/index.mdx

@@ -0,0 +1,26 @@
+---
+category: Developer Portal
+fullWidth: true
+disablePager: true
+showLastModified: false
+suggestEdit: false
+centered: false
+toc: false
+title: Getting Started with Developer Portal
+description:
+  Publish interactive API docs and let consumers manage their API keys through a
+  developer portal built in the Portal, locally, or with an AI agent.
+---
+
+<WizardSteps build="dev-portal" />
+
+A developer portal gives your API's users a place to read documentation, sign
+in, and test requests. This tutorial creates a portal with Zudoku, Zuplo's
+open-source documentation framework, using a sample Todo API.
+
+Choose a workflow to publish the reference docs and connect API key management.
+You assign a key to a consumer (the person or application calling your API),
+then sign in to test it. You need an email address you can access for the
+sign-in step.
+
+<MethodPicker build="dev-portal" />

package/docs/getting-started/dev-portal/local.mdx

@@ -0,0 +1,213 @@
+---
+category: Developer Portal
+showLastModified: false
+suggestEdit: false
+sidebar_label: Editor
+title: Getting Started with Developer Portal - Editor
+description:
+  Build a developer portal locally with API documentation, an introduction,
+  sign-in, and API key management, then test a protected route.
+---
+
+<WizardSteps build="dev-portal" method="local" />
+
+<MethodTabs build="dev-portal" method="local" />
+
+Build a developer portal with API reference documentation, a custom
+introduction, and API key management. You'll run it locally, sign in as an API
+consumer, and make an authenticated request from the API playground.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download) 24 or later and Git.
+- A [Zuplo account](https://portal.zuplo.com).
+- An editor and an email address you can use to sign in to the developer portal.
+
+## Create and customize the portal
+
+<Stepper>
+
+1. **Create a project**
+
+   Run:
+
+   ```bash
+   npx create-zuplo-api@latest my-api-project
+   cd my-api-project
+   npm run dev
+   ```
+
+   When prompted, choose **Yes** to create a matching Portal project, complete
+   sign-in, and select your Zuplo account. The CLI creates a hosted project and
+   links your local copy to it. Keep `.env.zuplo` out of source control.
+
+   The default template includes a Todo API and a developer portal. Open the
+   **Docs Server** URL printed in the terminal, normally
+   [http://localhost:9200](http://localhost:9200). You should see the Todo API
+   reference. The gateway runs on port `9000` and the Route Designer on `9100`.
+
+   :::tip{title="Use an existing project"}
+
+   If your project already has a `docs` directory, clone its Git repository, run
+   `npm install` at the project root, then run `npx zuplo login` and
+   `npx zuplo link`, selecting the project's **working copy**. This walkthrough
+   uses the Todo template; for your own API, apply the policy and tests to an
+   equivalent read-only route. Start all three services with `npm run dev` from
+   the project root. For an older project without `docs`, first follow
+   [Enable the Developer Portal](../../dev-portal/migration.mdx).
+
+   :::
+
+2. **Set your portal's title and introduction**
+
+   Open `docs/zudoku.config.tsx`. Set `site.title` and `metadata.title` to
+   `Todo Developer Portal`, and set `metadata.description` to
+   `Explore the Todo API and manage your API keys.` Keep the other settings.
+
+   The `apis` entry already reads `../config/routes.oas.json` and publishes it
+   at `/api`. Your API documentation updates when the OpenAPI file changes.
+
+   Replace `docs/pages/introduction.mdx` with:
+
+   ```mdx title="docs/pages/introduction.mdx"
+   ---
+   title: Welcome to the Todo API
+   description: Sign in, find your API key, and make your first request.
+   ---
+
+   Use the Todo API to retrieve tasks for your application.
+
+   1. Sign in using the email address registered as a key manager.
+   2. Open **API Keys** from your profile menu to find your assigned key.
+   3. Open **API Reference** and try **Get all todos** with that key.
+   ```
+
+   The default navigation already includes `introduction`. Open
+   `http://localhost:9200/introduction` to see the page. Changes appear as you
+   save. See [Writing content](../../dev-portal/zudoku/writing.mdx) for more
+   page options.
+
+3. **Require an API key for the sample route**
+
+   Replace the empty policy list with:
+
+   ```json title="config/policies.json"
+   {
+     "policies": [
+       {
+         "name": "api-key-auth",
+         "policyType": "api-key-inbound",
+         "handler": {
+           "export": "ApiKeyInboundPolicy",
+           "module": "$import(@zuplo/runtime)",
+           "options": { "allowUnauthenticatedRequests": false }
+         }
+       }
+     ]
+   }
+   ```
+
+   In `config/routes.oas.json`, find `paths["/todos"].get`. Update its
+   `x-zuplo-route` to retain the forward handler and add the policy:
+
+   ```json
+   "x-zuplo-route": {
+     "corsPolicy": "anything-goes",
+     "handler": {
+       "export": "urlForwardHandler",
+       "module": "$import(@zuplo/runtime)",
+       "options": { "baseUrl": "https://todo.zuplo.io" }
+     },
+     "policies": { "inbound": ["api-key-auth"] }
+   }
+   ```
+
+   If you're using an existing project, add the policy to its existing list and
+   put it first in this route's inbound chain. Leave the other routes and their
+   handlers in place.
+
+   `anything-goes` enables browser requests from the developer portal. For a
+   production API, configure [CORS](../../articles/cors.mdx) for your portal's
+   origin. This step protects `GET /todos`; apply authentication to other routes
+   before exposing private data through them.
+
+   Update `info.description` to say that `GET /todos` requires a bearer API key,
+   replacing the sample's statement that no authentication is required.
+
+   In a second terminal, run `curl -i http://localhost:9000/todos`. Expect
+   `401 Unauthorized`.
+
+</Stepper>
+
+## Assign an API key and test it
+
+<Stepper>
+
+1. **Create a consumer in the Portal**
+
+   Open your project in the Zuplo Portal and go to
+   [**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services).
+   Select **Dev**, then click **Create Consumer**.
+
+   Set **Subject** to `tutorial-consumer`, add your email address under **Key
+   managers**, and leave **Metadata** as `{}`. Click **Save consumer**.
+
+   <ModalScreenshot>
+
+   ![Create an API consumer with a subject and key manager email](/media/api-key-consumer-bucket-portal-ui/create-consumer-modal.png)
+
+   </ModalScreenshot>
+
+   Key managers can view and manage this consumer's keys after signing in to the
+   developer portal. Signing in alone doesn't create a consumer. See
+   [API key management](../../articles/api-key-management.mdx).
+
+2. **Sign in to the developer portal**
+
+   Open `http://localhost:9200` and sign in with the same email address you
+   entered as a key manager. The template includes a demo sign-in provider and
+   `apiKeys: { enabled: true }` for this test.
+
+   Open your profile menu and select **API Keys**. The assigned consumer and its
+   key should appear. If they don't, check the email address and that you
+   created the consumer in **Dev** for the linked project.
+
+3. **Call the API from the documentation**
+
+   Open **API Reference**, select **Get all todos**, and click **Test**. Expand
+   **Authentication**, select `tutorial-consumer`, and click **Send**. Expect
+   `200 OK` and a JSON response containing todos.
+
+   You can also copy the key and verify it from a second terminal:
+
+   ```bash
+   export TODO_API_KEY="YOUR_API_KEY"
+   curl -i http://localhost:9000/todos \
+     -H "Authorization: Bearer $TODO_API_KEY"
+   ```
+
+   This request should return `200`; the same request without the header should
+   still return `401`.
+
+</Stepper>
+
+## Publish the portal
+
+Follow [Deploy to the edge](../gateway/deploy-to-the-edge/local.mdx) to connect
+your repository and deploy. In the Zuplo Portal, open **Deployment URLs** and
+copy the **Dev Portal** URL. The portal deploys with the gateway.
+
+Create a consumer in the deployed environment's **Prod** API key bucket and
+repeat the sign-in and API request there. Development keys are separate from
+production keys.
+
+Before inviting users or configuring a custom domain, replace the template's
+demo sign-in configuration with your own
+[authentication provider](../../dev-portal/zudoku/configuration/authentication.md).
+
+## Next steps
+
+- [Customize the theme](../../dev-portal/zudoku/customization/colors-theme.mdx).
+- [Create consumers on login](../../dev-portal/dev-portal-create-consumer-on-auth.mdx)
+  if every user should receive a key automatically.
+- [Add more documentation](../../dev-portal/zudoku/writing.mdx).