Merge branch 'main' into ntotten-patch-2

Author: ntotten

.gitignore

@@ -64,6 +64,7 @@ public/robots.txt
 public/sitemap.xml
 public/sitemap-*.xml
 api.json
+api-preview.json
 build/
 .next/
 docs/dev-portal/zudoku/
@@ -85,7 +86,7 @@ docs/dev-portal/zudoku/
 !.styles/config/vocabularies/Base
 
 
-# Screenshots 
+# Screenshots
 auth.json
 
 # docs generation
@@ -95,4 +96,4 @@ auth.json
 /index.d.ts
 
 
-/.lycheecache
+/.lycheecache

.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-  "recommendations": ["prettier.prettier-vscode"]
+  "recommendations": ["esbenp.prettier-vscode"]
 }

.vscode/settings.json

@@ -1,5 +1,5 @@
 {
-  "editor.defaultFormatter": "prettier.prettier-vscode",
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
   "npm.packageManager": "npm",
   "editor.formatOnSave": true,
   "search.exclude": {

docs/articles/advanced-path-matching.mdx

@@ -16,6 +16,27 @@ However, you can opt to use a more advanced path matching approach based on the
 web standard
 [URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern).
 
+In order to use URLPattern matching you must set your route's
+`x-zuplo-path.pathMode` to `url-pattern`.
+
+The URLPattern matching mode can be set in the UI as shown below:
+
+![Route ](../../public/media/advanced-path-matching/image.png)
+
+Alternatively, you can set it in your OpenAPI file as follows:
+
+```json {4-6} title="config/routes.oas.json"
+{
+  "paths": {
+    "/files/:path*": {
+      "x-zuplo-path": {
+        "pathMode": "url-pattern"
+      }
+    }
+  }
+}
+```
+
 The most basic path is `/` which will simple match the root path. You can add
 other static paths like `/foo` and `/foo/bar`
 

docs/articles/logging.mdx

@@ -88,3 +88,28 @@ details.
   events in the environment where your API runs. It's provided in your logs for
   potential troubleshooting. Normally, it's recommended to rely on the
   `requestId` for tracing.
+
+## Custom Log Properties
+
+In addition to the default fields, you can also add custom fields to your logs.
+This can be done using the `context.log.setLogProperties!` method.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  context.log.setLogProperties!({ customProperty: "value" });
+  context.log.info("Hello World");
+  return request;
+}
+```
+
+These properties will be included in all subsequent log messages for that
+request. If the property already exists, it will be overwritten.
+
+The log properties will be exported in a format native to the plugin you are
+using. For example, in the case of the OpenTelemetry plugin, the properties will
+be included in the `attributes` field of the log record.

docs/articles/metrics-plugins.mdx

@@ -11,6 +11,7 @@ Zuplo supports logging to the following sources:
 - Datadog (Beta)
 - Dynatrace (Beta)
 - New Relic (Beta)
+- OpenTelemetry (Beta)
 
 If you would like to log to a different source, reach out to support@zuplo.com
 and we'd be happy to work with you to add a new logging plugin.
@@ -281,3 +282,90 @@ can use a tool like the
 aggregation.
 
 :::
+
+### OpenTelemetry (Beta)
+
+The OpenTelemetry metrics plugin sends metrics to any OpenTelemetry-compatible
+collector using the
+[OTLP HTTP JSON format](https://opentelemetry.io/docs/specs/otlp/#json-protobuf-encoding).
+This allows you to integrate with a wide variety of observability backends that
+support OpenTelemetry, including Grafana, Jaeger, Honeycomb, and many others.
+
+By default, we send all metrics to your OpenTelemetry collector. However, you
+have the option below to configure which metrics you want to send.
+
+```ts
+import {
+  RuntimeExtensions,
+  OTelMetricsPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new OTelMetricsPlugin({
+      // The OTLP HTTP endpoint URL for your collector
+      url: "https://otel-collector.example.com:4318/v1/metrics",
+      // Optional headers for authentication
+      headers: {
+        Authorization: `Bearer ${environment.OTEL_API_KEY}`,
+      },
+      // Resource attributes to include with all metrics
+      attributes: {
+        "service.name": "my-api",
+        "deployment.environment": environment.ENVIRONMENT ?? "development",
+      },
+      metrics: {
+        latency: true,
+        requestContentLength: true,
+        responseContentLength: true,
+      },
+      // You can also choose to add additional attributes to include in the metrics
+      include: {
+        country: false,
+        httpMethod: false,
+        statusCode: false,
+        path: false,
+      },
+    }),
+  );
+}
+```
+
+The plugin uses
+[OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/)
+for metric names and attributes:
+
+| Metric                  | Name                             | Unit |
+| ----------------------- | -------------------------------- | ---- |
+| Request latency         | `http.server.request.duration`   | ms   |
+| Request content length  | `http.server.request.body.size`  | By   |
+| Response content length | `http.server.response.body.size` | By   |
+
+When `include` options are enabled, the following attributes are added:
+
+| Option       | Attribute                     |
+| ------------ | ----------------------------- |
+| `country`    | `client.geo.country_iso_code` |
+| `httpMethod` | `http.request.method`         |
+| `statusCode` | `http.response.status_code`   |
+| `path`       | `http.route`                  |
+
+The above configuration applies globally for all metrics sent to your
+OpenTelemetry collector. If you wish to dynamically configure information for a
+particular ZuploContext, you can use the `OTelMetricsPlugin` in your code.
+Currently, the only configuration you can set is the attributes. The values you
+set here will be appended to those set globally in the `zuplo.runtime.ts` file.
+
+```ts
+import { ZuploContext, ZuploRequest, OTelMetricsPlugin } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const someValue = "hello";
+  OTelMetricsPlugin.setContext(context, {
+    attributes: { "my.custom.attribute": someValue },
+  });
+
+  return "What zup?";
+}
+```

docs/articles/monetization.mdx

@@ -65,6 +65,20 @@ combined with Zuplo's API management capabilities. You can:
 Learn how improving API quality can increase revenue in this blog post:
 [Increase Revenue by Improving API Quality](https://zuplo.com/blog/2024/02/02/increase-revenue-by-improving-api-quality)
 
+## Zuplo Monetization API (Preview)
+
+For teams who want a fully integrated, first-party metering solution, Zuplo now
+offers the Monetization API. Built from years of enterprise customer
+collaboration, this API provides:
+
+- **Native metering** - Track usage directly within Zuplo without external
+  services
+- **Product catalog** - Define meters, features, and plans via API
+- **Real-time queries** - Check usage instantly for billing or quota enforcement
+- **Simplified architecture** - One platform for gateway and monetization
+
+[Explore the Monetization API →](./monetization/index.mdx)
+
 ## Enterprise Solutions
 
 For organizations with complex monetization requirements that go beyond standard

docs/articles/monetization/api-access.mdx

@@ -0,0 +1,68 @@
+---
+title: API Access
+sidebar_label: API Access
+---
+
+:::warning
+
+The Monetization APIs are in preview and subject to change. Features and
+endpoints documented here may be modified as we refine the service based on
+customer feedback.
+
+:::
+
+## Buckets
+
+Each Zuplo project includes three isolated buckets that mirror your
+[environment structure](../environments.mdx):
+
+| Bucket           | Purpose                                                       |
+| ---------------- | ------------------------------------------------------------- |
+| **Working Copy** | Your development sandbox for building and testing             |
+| **Preview**      | Staging environments for validating changes before production |
+| **Production**   | Your live environment serving real customers                  |
+
+Meters, features, plans, and subscriptions are all scoped to a specific bucket.
+This isolation enables independent development workflows where you can:
+
+- **Experiment freely** - Test new pricing models or usage tracking in
+  development without affecting production data
+- **Validate changes** - Promote your product catalog configuration through
+  preview environments before going live
+- **Maintain separation** - Keep development test data completely isolated from
+  production customer usage
+
+When you're satisfied with your configuration in one bucket, you can recreate
+that same configuration in another bucket to promote changes through your
+deployment pipeline.
+
+## Authentication
+
+All Monetization API requests require authentication using a Zuplo API key.
+
+All examples in this documentation assume the following environment variables
+are set in your terminal:
+
+```bash
+# Your Bucket ID (could be working-copy, preview, or production)
+# (Found in Project Services > Bucket Details)
+export BUCKET_ID=your-bucket-id
+# Your Zuplo API Key (Found in Account Settings > Zuplo API Keys)
+export ZAPI_KEY=zpka_YOUR_API_KEY
+```
+
+Include your API key in the `Authorization` header:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/meters \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+## API Reference
+
+For complete API operations, see the API Reference documentation:
+
+- [Meters API](../../api/metering-meters)
+- [Features API](../../api/metering-features)
+- [Plans API](../../api/metering-plans)

docs/articles/monetization/features.mdx

@@ -0,0 +1,95 @@
+---
+title: Features
+sidebar_label: Features
+---
+
+:::warning
+
+The Monetization APIs are in preview and subject to change.
+
+:::
+
+Features describe what your API offers to customers. They represent the
+capabilities in your API product - access to specific endpoints, usage
+allowances, premium functionality, or any other aspect you want to track or
+gate.
+
+## Metered vs Static Features
+
+Features come in two types:
+
+- **Metered features** are linked to a meter and track consumption. Use these
+  for usage-based capabilities like API calls, tokens, or data transfer.
+- **Static features** have no meter attached. Use these for boolean capabilities
+  like "access to premium endpoints" or "priority support".
+
+## Feature Properties
+
+| Property    | Required | Description                                                            |
+| ----------- | -------- | ---------------------------------------------------------------------- |
+| `key`       | Yes      | Unique identifier (lowercase alphanumeric and underscores, 1-64 chars) |
+| `name`      | Yes      | Human-readable display name                                            |
+| `meterSlug` | No       | Links this feature to a meter for usage tracking                       |
+| `metadata`  | No       | Custom key-value pairs for your own use                                |
+
+:::note
+
+Features cannot be updated after creation - they can only be archived. Plan your
+feature structure carefully before creating them.
+
+:::
+
+## Creating a Feature
+
+Create a metered feature linked to an API requests meter:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/features \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "key": "api_calls",
+  "name": "API Calls",
+  "meterSlug": "api_requests"
+}
+EOF
+```
+
+The response includes the created feature:
+
+```json
+{
+  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+  "key": "api_calls",
+  "name": "API Calls",
+  "meterSlug": "api_requests",
+  "createdAt": "2024-01-01T01:01:01.001Z",
+  "updatedAt": "2024-01-01T01:01:01.001Z"
+}
+```
+
+### Creating a Static Feature
+
+For features without usage tracking, omit the `meterSlug`:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/features \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "key": "priority_support",
+  "name": "Priority Support"
+}
+EOF
+```
+
+## API Reference
+
+For complete API operations (list, get, archive), see the
+[Features API Reference](../../api/metering-features).