zuplo 6.67.33 → 6.68.0

package/README.md

@@ -11,3 +11,12 @@ fast, secure and with game-changing Developer Experience.</p>
 
 This is a convenience package that bundles the Zuplo CLI and various packages
 for use with Zuplo.
+
+## Bundled Documentation
+
+This package includes offline documentation and policy reference content in the
+`docs/` directory. After installing, you can find it at:
+
+```
+node_modules/zuplo/docs/
+```

package/docs/_index.md

@@ -0,0 +1,44 @@
+# Zuplo Documentation
+
+This bundle contains the Zuplo documentation for use by AI agents.
+
+## Contents
+
+- `policies/` - Zuplo policy reference
+  - `_index.md` - Policy catalog with names and descriptions
+  - `{policy-id}/schema.json` - Policy configuration schema (handler export, module, options)
+  - `{policy-id}/intro.md` - Short policy description
+  - `{policy-id}/doc.md` - Full usage documentation with examples
+- `articles/` - General documentation and how-to guides
+- `ai-gateway/` - AI Gateway documentation
+- `cli/` - Zuplo CLI reference
+- `handlers/` - Request handler documentation
+- `programmable-api/` - Programmable API reference (ZuploRequest, ZuploContext, etc.)
+- `guides/` - Step-by-step tutorials
+- `dev-portal/` - Developer Portal documentation
+- `errors/` - Error reference pages
+- `concepts/` - Core concepts
+- `dedicated/` - Dedicated infrastructure documentation
+- `mcp-server/` - MCP Server documentation
+
+## Configuring Policies
+
+To configure a Zuplo policy:
+
+1. Read `policies/_index.md` to find the right policy
+2. Read the policy's `schema.json` for the handler export, module, and options schema
+3. Read the policy's `doc.md` for usage details and examples
+
+Each policy is configured in `config/policies.json` with this structure:
+
+```json
+{
+  "name": "my-policy",
+  "policyType": "<policy-id>",
+  "handler": {
+    "export": "<from schema.json>",
+    "module": "<from schema.json>",
+    "options": {}
+  }
+}
+```

package/docs/ai-gateway/apps.mdx

@@ -0,0 +1,28 @@
+---
+title: AI Gateway Apps
+sidebar_label: Overview
+---
+
+Apps in the Zuplo AI Gateway represent any app or integration that will call the
+AI Gateway. For example, you might have a custom support chatbot on your
+website - that chatbot would be an App in the AI Gateway. Each App has its own
+API Key so that usage is tracked independently. Apps are owned by a specific
+[team](./teams.mdx) and can access the AI Providers assigned to that team.
+
+## API Keys
+
+Each App in the AI Gateway has its own API Key. This allows you to track usage
+independently for each App. You can find the API Key for an App by navigating to
+the **Apps** tab of your AI Gateway project in the
+[Zuplo Portal](https://portal.zuplo.com). Select the App you want to view the
+API Key for. With the App open you will see the API Key section at the top of
+the app page.
+
+**Additional Resources**
+
+- [Creating & Editing Apps](./managing-apps.mdx) - How to add, remove, and set
+  roles for project members.
+- [Creating & Editing Teams](./managing-teams.mdx) - How to create and edit
+  teams.
+- [Role Permissions](../articles/accounts/roles-and-permissions.mdx) - Details
+  on the roles available at the account and project levels.

package/docs/ai-gateway/custom-providers.mdx

@@ -0,0 +1,54 @@
+---
+title: Using Custom AI Providers
+sidebar_label: Custom Providers
+---
+
+Zuplo's AI Gateway supports the addition of custom AI providers. This allows
+users to route their AI Gateway Apps to self hosted services and models,
+providing an additional layer of control, security and governance when using
+these models in production.
+
+:::note
+
+Please note that currently only OpenAI-compatible models are supported using
+custom providers
+
+:::
+
+## Adding a Custom AI Provider
+
+To add a custom AI provider to your Zuplo AI Gateway, follow these steps:
+
+<Stepper>
+
+1. Navigate to the **Settings** > **AI Providers** section of your AI Gateway
+   project in the [Zuplo Portal](https://portal.zuplo.com).
+
+1. Click on the **Add Provider** button.
+
+1. Select the **Custom** option from the Custom Providers section of the list
+
+1. Specify a label for the custom provider instance. You can change the label
+   later if required.
+
+1. Specify the API URL of the custom provider you are using.
+
+1. Enter the API Key for the selected provider (if there is no API key required,
+   you can leave this blank).
+
+1. Finally, add the available models that are hosted with your custom provider,
+   along with their type. Optionally, you can add a dollar cost for input and
+   output tokens if you wish to track this via the AI Gateway.
+
+1. Click **Create**.
+
+</Stepper>
+
+## Modify, Update or Delete your Custom AI Provider
+
+Existing providers can be modified, updated or deleted by navigating to the
+**Settings** > **AI Providers** section and clicking the **Edit** or **Delete**
+icon next to the custom provider you want to modify, update or delete.
+
+Further information can be found in the
+[Managing Providers](./managing-providers.mdx) guide.

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

@@ -0,0 +1,224 @@
+---
+title: Zuplo AI Gateway Getting Started
+sidebar_label: Getting Started
+---
+
+This guide will walk you through setting up your first AI Gateway project, from
+initial configuration to making your first LLM request through Zuplo.
+
+## Prerequisites
+
+- A Zuplo account (sign up free at [zuplo.com](https://zuplo.com))
+- API keys for at least one LLM provider (OpenAI, Anthropic, Google Gemini,
+  etc.)
+- An application that needs to call LLM APIs
+
+## Step 1: Create an AI Gateway Project
+
+1. Log into your Zuplo account
+2. Navigate to **Projects**
+3. Click **New Project**
+4. Click **AI or MCP Gateway** at the bottom of the dialog
+5. Give your project a name (for example, "MyCompany AI Gateway")
+6. Click **Create Project**
+
+Your AI Gateway project will be created in seconds. You'll notice the interface
+includes Apps, Teams, and a setup guide to help you get started.
+
+## Step 2: Configure Providers
+
+Providers are the LLM services (like OpenAI or Google Gemini) that your
+applications will use. You'll configure these once as an administrator, and your
+team members can use them without needing direct access to provider API keys.
+
+### Adding Your First Provider
+
+1. Click **Add Provider**
+2. Select your AI provider (for example, **OpenAI**)
+3. Enter a name for this provider configuration
+4. Paste your provider's API key
+5. Select which models you want to make available to your teams
+6. Click **Create**
+
+### Adding Additional Providers
+
+Repeat the process above to add more providers. This allows your teams to switch
+between providers (OpenAI, Gemini, etc.) without changing application code.
+
+**Example providers you might add:**
+
+- OpenAI (for GPT models)
+- Google Gemini (for Gemini models)
+- Additional providers as they become available
+
+## Step 3: Create a Team
+
+Teams allow you to organize users and set hierarchical budget controls. Even if
+you're starting solo, you'll need at least one team.
+
+### Creating Your Root Team
+
+1. Click **Create Team**
+2. Name your team (for example, "Root" or your company name)
+3. Choose an icon for easy identification
+4. Click **Create Team**
+5. Set organization-wide limits (optional) by selecting the **Usage & Limits**
+   tab:
+   - **Budget Limit**: Maximum spend per day (for example, $1,000)
+   - **Rate Limits**: Request limits if needed
+
+### Creating Sub-Teams (Optional)
+
+For larger organizations, create sub-teams with their own budgets:
+
+1. From your root team, click **Create Sub-Team**
+2. Name the team (for example, "Engineering Team", "Credit Team")
+3. Choose an icon
+4. Set team-specific limits by clicking on **Settings**:
+   - Daily budgets that are equal to or less than the parent team's limit
+   - Example: If root is $1,000/day, a sub-team might be $500/day
+5. Click **Save Changes**
+
+## Step 4: Create Applications
+
+Applications represent individual projects or services that will use the AI
+Gateway. Each app gets its own unique URL and API key.
+
+### Creating Your First App
+
+1. Click **Apps** followed by **Create App**
+2. Configure your app:
+   - **App Name**: Descriptive name (for example, "Tennis Chat", "Customer
+     Support Bot")
+   - **Team**: Select which team owns this app
+   - **Provider**: Choose your LLM provider (for example, OpenAI)
+   - **Completions**: Select the model for chat completions (for example,
+     GPT-4o)
+   - **Embeddings**: Select the model for embeddings (optional)
+3. Set application-level budgets:
+   - **Daily Limit**: (for example, $1/day for a hackathon project)
+   - **Monthly Limit**: (for example, $10/month)
+4. Enable **Semantic Caching** (optional):
+   - Caches similar prompts to reduce costs and improve performance
+   - Best for applications with repeated queries
+5. Click **Create App**
+
+### Access Your App Credentials
+
+After creating your application, you'll see:
+
+- **API Key**: Your Zuplo-managed key. You'll need it to integrate with your
+  application.
+
+## Step 5: Integrate with Your Application
+
+Now you'll update your application to use the Zuplo AI Gateway instead of
+calling LLM providers directly.
+
+In the examples below, we assume that you are using the official
+[Node.js OpenAI SDK](https://platform.openai.com/docs/libraries/node-js-library)
+and that you have executed `npm install openai`.
+
+### Before: Direct Provider Integration (sample.mjs)
+
+```javascript
+import OpenAI from "openai";
+
+// Old approach - directly calling OpenAI
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const completion = await openai.chat.completions.create({
+  model: "gpt-4",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+
+console.log(completion.choices[0].message.content);
+```
+
+### After: Using Zuplo AI Gateway (sample.mjs)
+
+```javascript
+import OpenAI from "openai";
+
+// New approach - using Zuplo AI Gateway
+const openai = new OpenAI({
+  apiKey: process.env.ZUPLO_API_KEY,
+  baseURL: "https://your-ai-gateway-url.zuplo.app/v1",
+});
+
+const completion = await openai.chat.completions.create({
+  model: "gpt-4",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+
+console.log(completion.choices[0].message.content);
+```
+
+Run the example with `node sample.mjs`.
+
+### What Changed?
+
+1. **URL**: Replace your provider's URL with your Zuplo Gateway URL
+2. **API Key**: Use your Zuplo API key instead of the provider's key
+3. **Everything else stays the same**: The request format remains compatible
+   with OpenAI's API
+
+## Verify Your Setup
+
+### Make Your First Request
+
+Send a test request through your gateway:
+
+```bash
+curl https://your-ai-gateway-url.zuplo.app/v1/chat/completions \
+  -H "Authorization: Bearer YOUR_ZUPLO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-4",
+    "messages": [{"role": "user", "content": "Hello, world!"}]
+  }'
+```
+
+### Check Your Dashboard
+
+1. Return to your AI Gateway project
+2. Click on your app
+3. Click on **Dashboard** to view:
+   - Request count
+   - Token usage
+   - Time to first byte
+   - Current spending
+
+You should see your test request appear with token usage and performance
+metrics.
+
+## Next Steps
+
+Now that your AI Gateway is running, explore additional features:
+
+### Switch Providers Without Code Changes
+
+1. Go to your app settings
+2. Change the **Provider** dropdown (for example, from OpenAI to Gemini)
+3. Select a new model
+4. Click **Save Changes**
+
+Your application will now use the new provider without any code changes.
+
+## Common Issues
+
+**Issue**: "Authentication failed" error
+
+- **Solution**: Verify you're using your Zuplo API key, not your provider's key
+
+**Issue**: Budget limit reached immediately
+
+- **Solution**: Check that sub-team limits don't exceed available budget from
+  parent team
+
+**Issue**: Semantic caching not working
+
+- **Solution**: Ensure caching is enabled in your application settings and
+  prompts are similar enough to match

package/docs/ai-gateway/guardrails.mdx

@@ -0,0 +1,65 @@
+---
+title: Zuplo AI Guardrails
+sidebar_label: Overview
+---
+
+The Zuplo AI Gateway supports guardrails to protect your AI-powered applications
+from security threats, ensure compliance, and maintain quality in both requests
+and responses flowing through the gateway.
+
+## Available Guardrail Policies
+
+### Akamai AI Firewall
+
+The [Akamai AI Firewall](./policies/akamai-ai-firewall.mdx) provides
+enterprise-grade security for AI applications, including:
+
+- **Prompt injection defense** - Protects against attackers manipulating AI
+  models through deceptive inputs
+- **Data loss prevention (DLP)** - Detects and blocks sensitive data leaks in
+  AI-generated responses and incoming requests
+- **Toxic content filtering** - Flags hate speech, misinformation, and offensive
+  content
+- **Adversarial AI security** - Protects against remote code execution, model
+  back doors, and data poisoning attacks
+
+## Observability & Tracing
+
+Guardrails work alongside observability policies to provide visibility into AI
+interactions:
+
+- [Comet Opik Tracing](./policies/comet-opik-tracing.mdx) - Trace and monitor AI
+  interactions with Comet's Opik platform
+- [Galileo Tracing](./policies/galileo-tracing.mdx) - Monitor AI quality and
+  performance with Galileo
+
+## How Guardrails Work
+
+Guardrails are applied as policies on your AI Gateway routes. They inspect both
+inbound requests (prompts sent to LLM providers) and outbound responses (content
+returned from LLM providers) in real-time.
+
+When a guardrail detects a policy violation:
+
+1. The request or response is blocked before reaching its destination
+2. An appropriate error response is returned to the caller
+3. The violation is logged for audit and monitoring purposes
+
+## Getting Started
+
+To add guardrails to your AI Gateway:
+
+1. Navigate to the API Gateway project associated with your AI Gateway in the
+   [Zuplo Portal](https://portal.zuplo.com)
+2. Open the **Code** tab and select your `routes.oas.json` file
+3. Select the route for your AI Gateway endpoint
+4. Click **Add Policy** and search for the guardrail you want to add
+5. Configure the policy settings and click **OK**
+6. Save your changes to deploy
+
+## Custom Guardrails
+
+You can build custom guardrails using Zuplo's programmable gateway. Create a
+custom inbound or outbound policy that inspects request/response content and
+applies your own rules. This allows you to implement organization-specific
+content policies, regulatory compliance checks, or domain-specific validation.

package/docs/ai-gateway/integrations/ai-sdk.mdx

@@ -0,0 +1,109 @@
+---
+title: AI SDK
+sidebar_label: AI SDK
+---
+
+The [AI SDK](https://ai-sdk.dev/) is a free open-source library that gives you
+the tools you need to build AI-powered products. It's compatible with a large
+selection of providers and models, and has a large selection of additional
+community supported providers being added regularly.
+
+## Prerequisites
+
+In order to use the AI Gateway with any AI SDK powered application you will need
+to complete these steps first:
+
+<Stepper>
+
+1. Create a [new provider](/ai-gateway/managing-providers) in the AI Gateway for
+   the provider you want to use with AI SDK
+
+2. [Set up a new team](/ai-gateway/managing-teams)
+
+3. Create a [new app](/ai-gateway/managing-apps) to use specifically with AI SDK
+   and assign it to the team you created
+
+4. Copy the API Key for the app you created, as well as the Gateway URL
+
+</Stepper>
+
+## Configure the AI SDK
+
+To route all AI SDK requests through Zuplo instead of directly to the API of the
+chosen provider, you must set the API `baseUrl` in the SDK configuration to
+point to the Gateway URL of your Zuplo AI Gateway.
+
+Additionally, you will need to change the value of `apiKey` to the API key of
+the app you have configured in Zuplo.
+
+### OpenAI
+
+```typescript
+import { createOpenAI } from "@ai-sdk/openai";
+import { generateText } from "ai";
+
+const openai = createOpenAI({
+  apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL: "https://my-ai-gateway.zuplo.app/v1",
+});
+
+const { text } = await generateText({
+  model: openai.chat("gpt-4o"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```
+
+### Anthropic
+
+```typescript
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { generateText } from "ai";
+
+const anthropic = createAnthropic({
+  apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL: "https://my-ai-gateway.zuplo.app/v1",
+  // Authorization header is also required
+  headers: {
+    Authorization: `Bearer ${process.env.ZUPLO_AI_GATEWAY_API_KEY}`,
+  },
+});
+
+const { text } = await generateText({
+  model: anthropic("claude-sonnet-4-5-20250929"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```
+
+### Google
+
+```typescript
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { generateText } from "ai";
+
+const google = createGoogleGenerativeAI({
+  apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL: "https://my-ai-gateway.zuplo.app/v1",
+});
+
+const { text } = await generateText({
+  model: google("gemini-2.5-flash"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```
+
+### Mistral
+
+```typescript
+import { createMistral } from "@ai-sdk/mistral";
+import { generateText } from "ai";
+
+const mistral = createMistral({
+  apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL: "https://my-ai-gateway.zuplo.app/v1",
+});
+
+const { text } = await generateText({
+  model: mistral("mistral-large-latest"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```

package/docs/ai-gateway/integrations/claude-code.mdx

@@ -0,0 +1,49 @@
+---
+title: Claude Code
+sidebar_label: Claude Code
+---
+
+The Zuplo AI Gateway supports the [Anthropic](https://docs.claude.com/en/home)
+`/v1/messages` API endpoint. This means that you can configure
+[Claude Code](https://www.claude.com/product/claude-code) to work seamlessly via
+the AI Gateway.
+
+## Claude Code Setup
+
+<Stepper>
+
+1. Create a [new provider](/ai-gateway/managing-providers) in the AI Gateway for
+   Anthropic
+
+2. [Set up a new team](/ai-gateway/managing-teams)
+
+3. Create a [new app](/ai-gateway/managing-apps) to use with Claude Code and
+   assign it to the team you created
+
+4. Copy the API Key for the app you created, as well as the Gateway URL
+
+5. Add the API key and Gateway URL to your environment, or Claude Code settings,
+   using either approach below
+
+</Stepper>
+
+### Environment
+
+```
+ANTHROPIC_AUTH_TOKEN=<your-ai-gateway-app-api-key>
+ANTHROPIC_BASE_URL=<your-ai-gateway-url>
+```
+
+### Using settings.json
+
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "<your-ai-gateway-app-api-key>",
+    "ANTHROPIC_BASE_URL": "<your-ai-gateway-url>"
+  }
+}
+```
+
+Restart Claude and it will switch to using your new AI Gateway configuration and
+all your Claude Code LLM requests will route through the AI Gateway.

package/docs/ai-gateway/integrations/codex.mdx

@@ -0,0 +1,78 @@
+---
+title: Codex
+sidebar_label: Codex
+---
+
+[Codex](https://developers.openai.com/codex) is a coding agent developed by
+OpenAI that you can run locally from your terminal and that can read, modify,
+and run code on your machine, in the chosen directory. It’s open-source, and
+built in Rust for speed and efficiency.
+
+## Prerequisites
+
+In order to use the AI Gateway with Codex you will need to complete these steps
+first:
+
+<Stepper>
+
+1. Create a [new provider](/ai-gateway/managing-providers) in the AI Gateway for
+   the provider you want to use with Codex
+
+2. [Set up a new team](/ai-gateway/managing-teams)
+
+3. Create a [new app](/ai-gateway/managing-apps) to use specifically with Codex
+   and assign it to the team you created
+
+4. Copy the API Key for the app you created, as well as the Gateway URL
+
+</Stepper>
+
+## Configure Codex CLI
+
+There are two approaches you can take to using Codex with Zuplo's AI Gateway.
+
+1. **Route OpenAI through AI Gateway** - This would configure your OpenAI
+   provider in Codex to route requests through the AI Gateway rather than
+   directly to OpenAI
+
+2. **Create a Zuplo specific provider** - Use Zuplo as a provider that be
+   selected in the Codex configuration and work with any OpenAI compatible
+   models
+
+Configuration steps for both options are below:
+
+### Route OpenAI through AI Gateway
+
+Open the [Codex configuration](https://developers.openai.com/codex/local-config)
+`~/.codex/config.toml` and modify the `model_providers.openai-chat-completions`
+entry so that the `base_url` points to your AI Gateway URL, and your `env_key`
+is set to the API Key of the app you created to use with Codex.
+
+```toml
+[model_providers.openai-chat-completions]
+name = "OpenAI using Chat Completions"
+base_url = "https://<your-ai-gateway-url>/v1"
+env_key = "ZUPLO_AI_GATEWAY_API_KEY"
+```
+
+Save the file and reload Codex. Your OpenAI requests will now be routed through
+the Zuplo AI Gateway.
+
+### Zuplo AI Gateway provider
+
+To add a specific provider for the AI Gateway you can add an additional entry to
+the Codex `config.toml` file.
+
+```toml
+[model_providers.zuplo]
+name = "Zuplo AI Gateway"
+base_url = "https://<your-ai-gateway-url>/v1"
+env_key = "ZUPLO_AI_GATEWAY_API_KEY"
+```
+
+Save the file and reload Codex. Your Zuplo AI Gateway provider will now be
+available and you can switch Codex over to use it at any time by running:
+
+```bash
+codex --config model_provider="zuplo"
+```