create-zuplo-api 7.8.7 → 7.8.8

package/dist/shared/env.example

@@ -0,0 +1,12 @@
+# Environment variables for local development.
+#
+# Copy this file to .env and replace the sample values. `zuplo dev` loads .env
+# automatically. .env is gitignored, so real secrets stay out of source control.
+#
+# Reference a variable from config files as $env(EXAMPLE_API_KEY), or from code
+# as `environment.EXAMPLE_API_KEY` (import `environment` from "@zuplo/runtime").
+#
+# For deployed environments, set variables in the Zuplo Portal under
+# Settings > Environment Variables. Docs:
+# https://zuplo.com/docs/articles/environment-variables
+EXAMPLE_API_KEY=replace-me

package/dist/templates/ai-gateway/README-template.md

@@ -1,22 +1,85 @@
-# AI Gateway
-
-This project is a Zuplo AI Gateway. It exposes the canonical AI Gateway
-operations (`/v1/chat/completions`, `/v1/messages`, `/v1/responses`, and
-`/v1/embeddings`) through `aiGatewayHandlerV2` under `/{app_id}/*`. Only paths
-whose suffix is a supported `/v1/...` operation succeed; other paths under
-`/{app_id}` return 404.
-
-Each route invokes `ai-gateway-configuration-loader-v2-inbound`, which loads the
-application's configuration from the `app_id` path segment, then
-`ai-gateway-configuration-executor-v2-inbound`, which runs its
-`inboundPolicyChain`. Applications may select only from the policies
-pre-declared in `config/policies.json`. To require application API keys for a
-specific app, add `ai-gateway-auth-v2-inbound` to that application's
-`inboundPolicyChain`. Adding it on the route before the loader requires a key
-for every application on the route.
-
-## Customizing the gateway
-
-- Declare additional selectable policies (including custom code policies) in
-  `config/policies.json`.
-- Pushes to your default branch deploy the gateway to production.
+## Zuplo AI Gateway
+
+This is a Zuplo AI Gateway that was created with
+[`create-zuplo-api`](https://zuplo.com/docs). It gives your applications one
+OpenAI-compatible API in front of many AI providers, with per-app keys, model
+controls, budgets, caching, and guardrails.
+
+## Getting Started
+
+The gateway loads each app's configuration (providers, models, and policies)
+from your Zuplo account at request time, so the project must be linked to a
+Zuplo project before it can serve requests.
+
+1. Link the project. This writes your project's settings to `.env.zuplo`, which
+   is gitignored:
+
+   ```bash
+   npx zuplo link
+   ```
+
+2. In the [Zuplo Portal](https://portal.zuplo.com), add a provider and create an
+   app. Each app gets its own API URL and API key. See
+   [Apps](https://zuplo.com/docs/ai-gateway/apps).
+
+3. Start the development server:
+
+   ```bash
+   npm run dev
+   # or
+   yarn dev
+   # or
+   pnpm dev
+   ```
+
+4. Send a request to the local gateway. Replace `<app_id>` with the ID from your
+   app's API URL and set `ZUPLO_APP_API_KEY` to the app's API key:
+
+   ```bash
+   curl http://localhost:9000/<app_id>/v1/chat/completions \
+     -H "Authorization: Bearer $ZUPLO_APP_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "model": "openai/gpt-4o-mini",
+       "messages": [{ "role": "user", "content": "Say hi" }]
+     }'
+   ```
+
+## Endpoints
+
+Every request is scoped to an app by the first path segment, `/{app_id}`. For
+the supported endpoints and which providers serve each one, see the
+[AI Gateway documentation](https://zuplo.com/docs/ai-gateway/overview).
+
+## Project Structure
+
+| Path                       | What it does                                                           |
+| -------------------------- | ---------------------------------------------------------------------- |
+| `config/ai.oas.json`       | The catch-all route that sends `/{app_id}/*` to the AI Gateway handler |
+| `config/policies.json`     | The policies an app can select for its policy chain                    |
+| `modules/zuplo.runtime.ts` | Runtime plugins, such as tracing and logging                           |
+| `.env.example`             | Sample environment variables. Copy it to `.env` for local development  |
+
+An app runs only the policies listed in its policy chain, and it can select only
+policies declared in `config/policies.json`. To add your own policy, write it in
+`modules/` and declare it in `config/policies.json`.
+
+## Debugging
+
+In VS Code, open **Run and Debug**, select **Launch & Attach Zuplo**, and click
+the green play button.
+
+For other editors and more details, see the
+[debugging guide](https://zuplo.com/docs/articles/local-development-debugging).
+
+## Deploying
+
+Connect the project to source control in the Zuplo Portal. Pushes to your
+default branch deploy the gateway to production.
+
+## Learn More
+
+To learn more about the AI Gateway, visit the
+[AI Gateway documentation](https://zuplo.com/docs/ai-gateway/overview).
+
+To connect with the community join [Discord](https://discord.zuplo.com).

package/dist/templates/ai-gateway/modules/zuplo.runtime.ts

@@ -0,0 +1,42 @@
+import type { RuntimeExtensions } from "@zuplo/runtime";
+
+/**
+ * `runtimeInit` runs once when your gateway boots. Use it to register plugins
+ * and lifecycle hooks. Docs:
+ * https://zuplo.com/docs/programmable-api/runtime-extensions
+ */
+export function runtimeInit(runtime: RuntimeExtensions) {
+  // `runtime` is unused until you enable a plugin below. This reference keeps
+  // linters from flagging it; delete it once you call `runtime.addPlugin`.
+  void runtime;
+
+  // --- OpenTelemetry tracing (optional) ------------------------------------
+  // Send traces to Zuplo's built-in tracing. This can also be configured to
+  // send traces to a third-party service such as Honeycomb, Grafana, and
+  // others. Docs: https://zuplo.com/docs/articles/opentelemetry
+  //
+  // To enable, run `npm install @zuplo/otel`, then import `OpenTelemetryPlugin`
+  // from "@zuplo/otel" and `environment` from "@zuplo/runtime":
+  // const isWorkingCopy =
+  //   environment.ZUPLO_ENVIRONMENT_STAGE === "working-copy";
+  // runtime.addPlugin(
+  //   new OpenTelemetryPlugin({
+  //     sampling: {
+  //       headSampler: { ratio: isWorkingCopy ? 1 : 0.1 },
+  //     },
+  //   }),
+  // );
+  // --- Logging (optional) --------------------------------------------------
+  // Ship request logs to Datadog. Other log integrations (New Relic, Splunk,
+  // Loki, Dynatrace, and others) follow the same pattern — see the logging
+  // overview at https://zuplo.com/docs/articles/logging.
+  // Docs: https://zuplo.com/docs/articles/log-plugin-datadog
+  //
+  // To enable, import the plugin and `environment` from "@zuplo/runtime":
+  // runtime.addPlugin(
+  //   new DataDogLoggingPlugin({
+  //     apiKey: environment.DATADOG_API_KEY,
+  //     source: "my-ai-gateway",
+  //   }),
+  // );
+}

package/dist/templates/default-empty/README-template.md

@@ -23,7 +23,10 @@ server will automatically reload the API with your changes.
 
 ## Debugging
 
-To set breakpoints and attach a debugger to your local gateway, see the
+In VS Code, open **Run and Debug**, select **Launch & Attach Zuplo**, and click
+the green play button.
+
+For other editors and more details, see the
 [debugging guide](https://zuplo.com/docs/articles/local-development-debugging).
 
 ## Learn More

package/dist/templates/shared/env.example

@@ -0,0 +1,12 @@
+# Environment variables for local development.
+#
+# Copy this file to .env and replace the sample values. `zuplo dev` loads .env
+# automatically. .env is gitignored, so real secrets stay out of source control.
+#
+# Reference a variable from config files as $env(EXAMPLE_API_KEY), or from code
+# as `environment.EXAMPLE_API_KEY` (import `environment` from "@zuplo/runtime").
+#
+# For deployed environments, set variables in the Zuplo Portal under
+# Settings > Environment Variables. Docs:
+# https://zuplo.com/docs/articles/environment-variables
+EXAMPLE_API_KEY=replace-me

package/dist/templates/shared/vscode/launch.json

@@ -0,0 +1,30 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Launch Zuplo",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["zuplo", "dev", "--debug-port", "9229", "--port", "9000"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    },
+    {
+      "name": "Zuplo Gateway",
+      "type": "node",
+      "request": "attach",
+      "restart": true,
+      "port": 9229
+    }
+  ],
+  "compounds": [
+    {
+      "name": "Launch & Attach Zuplo",
+      "configurations": ["Launch Zuplo", "Zuplo Gateway"]
+    }
+  ]
+}

package/dist/templates/shared/vscode/settings.json

@@ -0,0 +1,20 @@
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["config/*.oas.json"],
+      "url": "https://cdn.zuplo.com/schemas/openapi-v3.1-zuplo.json"
+    },
+    {
+      "fileMatch": ["config/policies.json"],
+      "url": "https://cdn.zuplo.com/schemas/policies.json"
+    },
+    {
+      "fileMatch": ["config/dev-portal.json"],
+      "url": "https://cdn.zuplo.com/schemas/dev-portal.json"
+    },
+    {
+      "fileMatch": ["docs/sidebar.json"],
+      "url": "https://cdn.zuplo.com/schemas/sidebar.json"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zuplo-api",
-  "version": "7.8.7",
+  "version": "7.8.8",
   "keywords": [
     "api",
     "openapi",

package/dist/templates/ai-gateway/env.example

@@ -1,6 +0,0 @@
-# Optional credentials for the pre-declared AI Gateway policies in
-# config/policies.json. Only required when an application's policy chain
-# selects the matching policy. Configure these as environment variables on
-# your Zuplo project (Settings -> Environment Variables) for deployed
-# environments.
-

package/dist/templates/ai-gateway/gitignore

@@ -1,8 +0,0 @@
-.zuplo/
-.cache/
-dist/
-node_modules/
-
-# OS Stuff
-
-.DS_Store

package/dist/templates/default/env.example

@@ -1,2 +0,0 @@
-EXAMPLE_SECRET=👀 What you looking at?
-EXAMPLE_CONFIG=https://twitter.com/zuplo

package/dist/templates/default-empty/env.example

@@ -1,2 +0,0 @@
-EXAMPLE_SECRET=👀 What you looking at?
-EXAMPLE_CONFIG=https://twitter.com/zuplo