zuplo 6.67.32 → 6.68.0

package/docs/programmable-api/zuplo-request.mdx

@@ -0,0 +1,200 @@
+---
+title: ZuploRequest
+---
+
+The ZuploRequest object is the main parameter passed to both
+[Request Handlers](../handlers/custom-handler.mdx) and
+[Policies](../articles/policies.mdx). It represents the incoming request.
+
+ZuploRequest inherits from the web standard `Request` class used with `fetch` -
+you can read more about this on MDN including an explanation of how all of its
+properties and methods work:
+[https://developer.mozilla.org/en-US/docs/Web/API/Request](https://developer.mozilla.org/en-US/docs/Web/API/Request).
+
+In addition to the standard properties, the following are added for convenience.
+
+## Properties
+
+- `params` - if you use tokens in your route’s URL, we automatically parse them
+  into properties on the `params` property of your request. For example, imagine
+  a route with path `/products/:productId/vendors/:vendorId`. A match on this
+  would yield values as follows:
+
+```ts
+const productId = request.params.productId;
+const vendorId = request.params.vendorId;
+```
+
+- `user` - an optional object identifying a ‘user’. If `undefined` this
+  typically means the request is anonymous. If present, the user object will
+  have a `sub` property that's a unique identifier for that user. There is also
+  an optional `data` property that's of `any` type that typically contains other
+  information about the user. When using JWT tokens you’ll usually find all the
+  claims here.
+- `query` - a dictionary of query-string values. For example, a URL with a query
+  string like `https://example.com?foo=bar` would present as follows:
+
+```ts
+const foo = request.query.foo;
+```
+
+## Constructor
+
+It can be useful to create a new ZuploRequest inside a policy (see
+[policies](../articles/policies.mdx)) to forward to the next policy or handler
+in the chain.
+
+### Basic Constructor
+
+```ts
+const newRequest = new ZuploRequest("http://new-host.com/", {
+  method: "POST",
+  headers: {
+    "content-type": "application/json",
+  },
+  body: "test",
+});
+```
+
+### Constructor with Zuplo-specific Options
+
+The constructor accepts a `ZuploRequestInit` object that extends the standard
+`RequestInit` with additional properties:
+
+```ts
+const newRequest = new ZuploRequest("http://example.com/products/123", {
+  method: "GET",
+  headers: request.headers,
+  // Zuplo-specific options
+  params: {
+    productId: "123",
+  },
+  user: {
+    sub: "user-456",
+    data: {
+      email: "user@example.com",
+      role: "admin",
+    },
+  },
+});
+```
+
+This is particularly useful when creating internal requests or modifying the
+current request while preserving user context.
+
+## Request Query
+
+The `request.query` property is a helper that takes your QueryString and
+converts it into a JavaScript dictionary (for example `Record<string, string>`
+in TypeScript). This helper property doesn't support multiple values for the
+same key on a QueryString, for example:
+
+`?foo=bar&foo=wibble`
+
+To access the array of values in this case you can instead use the URL type and
+`searchParams`:
+
+```ts
+const url = new URL(request.url);
+const foo = url.searchParams.get("foo");
+// foo will be an array here
+```
+
+## Cloning and Modifying Requests
+
+When you need to create a modified version of an existing request, you can use
+the ZuploRequest constructor with the existing request:
+
+```ts
+// Clone with modified headers
+const modifiedRequest = new ZuploRequest(request, {
+  headers: {
+    ...Object.fromEntries(request.headers.entries()),
+    "x-custom-header": "new-value",
+  },
+});
+
+// Clone with different URL but preserve user context
+const internalRequest = new ZuploRequest(
+  "https://internal-api.example.com/data",
+  {
+    method: request.method,
+    headers: request.headers,
+    body: request.body,
+    // Preserve Zuplo-specific properties
+    user: request.user,
+    params: request.params,
+  },
+);
+```
+
+## Type Safety with Parameters
+
+ZuploRequest supports TypeScript generics for type-safe access to route
+parameters, query parameters, and user data:
+
+```ts
+interface MyRequestOptions {
+  Params: {
+    productId: string;
+    vendorId: string;
+  };
+  Query: {
+    limit?: string;
+    offset?: string;
+  };
+  UserData: {
+    role: string;
+    permissions: string[];
+  };
+}
+
+export default async function handler(
+  request: ZuploRequest<MyRequestOptions>,
+  context: ZuploContext,
+) {
+  // TypeScript knows these types
+  const productId = request.params.productId; // string
+  const limit = request.query.limit; // string | undefined
+  const role = request.user?.data.role; // string | undefined
+}
+```
+
+You can also use shorthands to just define a subset of these types:
+
+```ts
+new ZuploRequest<{ Query: { limit?: string } }>(request);
+```
+
+## Type Safety with User Data
+
+For better type safety with user data, define interfaces for your user
+structure:
+
+```ts
+interface MyUserData {
+  email: string;
+  roles: string[];
+  organizationId: string;
+}
+
+export default async function handler(
+  request: ZuploRequest<{ UserData: MyUserData }>,
+  context: ZuploContext,
+) {
+  // TypeScript knows the shape of user data
+  if (request.user) {
+    const email = request.user.data.email; // string
+    const isAdmin = request.user.data.roles.includes("admin"); // boolean
+  }
+}
+```
+
+## See Also
+
+- [Request User](./request-user.mdx) - Working with authenticated users
+- [ZuploContext](./zuplo-context.mdx) - The context object
+- [Safely Clone a Request or Response](./safely-clone-a-request-or-response.mdx) -
+  Best practices for cloning
+- [MDN Request Documentation](https://developer.mozilla.org/en-US/docs/Web/API/Request) -
+  Web standard Request API

package/docs/sample-apis.mdx

@@ -0,0 +1,78 @@
+---
+title: Sample APIs
+---
+
+Zuplo maintains a variety of sample APIs that are all built with Zuplo. These
+are free for anyone to use for testing or demos.
+
+## Echo API
+
+The echo API will accept any request and will return a JSON object with details
+of that request. This API accepts all HTTP methods and any body content.
+
+URL: https://echo.zuplo.io
+
+GitHub: https://github.com/zuplo/echo-api
+
+**Request**
+
+```txt
+POST https://echo.zuplo.io/my/path
+content-type: application/json
+
+{
+  "hello": "world"
+}
+```
+
+**Response**
+
+```json
+{
+  "url": "https://echo.zuplo.io/my/path",
+  "method": "POST",
+  "query": {},
+  "body": {
+    "hello": "world"
+  },
+  "headers": {
+    "accept-encoding": "gzip",
+    "connection": "Keep-Alive",
+    "content-length": "22",
+    "content-type": "application/json",
+    "host": "echo.zuplo.io"
+  }
+}
+```
+
+## E-Commerce API
+
+This API is a large collection of fake e-commerce-type data.
+
+URL: https://ecommerce-api.zuplo.io
+
+GitHub: https://github.com/zuplo/ecommerce-api
+
+Endpoints:
+
+- `GET /users`: Returns a collection of user objects
+- `GET /users/:id`: Returns a single user by `id`
+- `GET /products`: Returns a collection of products
+- `GET /products/:id`: Returns a single product by `id`
+- `GET /transactions`: Returns a collection of transactions
+
+## E-Commerce "Legacy" API
+
+This is very similar to the E-Commerce API but with a different URL structure.
+
+URL: https://ecommerce-legacy.zuplo.io
+
+GitHub: https://github.com/zuplo/ecommerce-legacy
+
+Endpoints:
+
+- `GET /objects?type=OBJECT_TYPE`: Returns a collection of the object type
+- `GET /objects?type=OBJECT_TYPE&id=OBJECT_ID`: Returns a single object based on
+  ID
+
+Valid `type` values are `product`, `user`, and `transaction`.

package/docs/self-hosted/overview.md

@@ -0,0 +1,60 @@
+---
+title: Zuplo Self-Hosted
+sidebar_label: Overview
+---
+
+Zuplo Self-Hosted (also known as on-premises) is a deployment model where you
+run Zuplo on your own infrastructure in any cloud or private data center. Zuplo
+Self-Hosted runs exclusively on Kubernetes and can be deployed to any Kubernetes
+environment. Deployment is simple and uses Helm charts.
+
+Self-hosted deployment might be the right choice for you if you need:
+
+- Complete control over your infrastructure and deployment environment
+- To run Zuplo in a private data center or on-premises environment
+- To meet strict data sovereignty or regulatory requirements that require data
+  to remain within your infrastructure
+- To integrate with existing on-premises systems and networks
+- To customize the deployment architecture to match your organization's specific
+  requirements
+
+## Deployment Options
+
+Zuplo Self-Hosted offers two deployment models:
+
+### Hybrid Deployment
+
+In a hybrid deployment, you run the Zuplo API Gateway on your infrastructure
+while leveraging shared services for features such as rate limiting. This
+approach provides a balance between control and operational simplicity, allowing
+you to maintain your gateway infrastructure while benefiting from managed
+services for specific features.
+
+### Full Self-Hosted
+
+In a full self-hosted deployment, you run all Zuplo components on your
+infrastructure. This provides complete control and isolation, ensuring that all
+data and processing remain within your environment.
+
+## Features
+
+The self-hosted deployment model provides the same core features as other Zuplo
+deployment models. You can use all the same policies, integrations, and features
+as you would with edge-based or managed dedicated deployments.
+
+In addition to the standard features, self-hosted deployment provides:
+
+- **Kubernetes-Based**: Deploy to any Kubernetes environment using simple Helm
+  charts
+- **Complete Control**: Full control over your infrastructure, networking, and
+  security configurations
+- **Data Sovereignty**: Keep all data and processing within your infrastructure
+- **Custom Networking**: Integrate with your existing network architecture and
+  security policies
+- **Compliance**: Meet regulatory and compliance requirements that require
+  on-premises deployment
+
+## Getting Started
+
+To learn more about self-hosting Zuplo or to discuss your specific requirements,
+[book a meeting](https://zuplo.com/meeting) with us.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.67.32",
+  "version": "6.68.0",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -8,7 +8,8 @@
   "files": [
     "README.md",
     "LICENSE.txt",
-    "zuplo.js"
+    "zuplo.js",
+    "docs"
   ],
   "engines": {
     "node": ">=20.16.0",
@@ -18,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.67.32",
-    "@zuplo/core": "6.67.32",
-    "@zuplo/runtime": "6.67.32",
+    "@zuplo/cli": "6.68.0",
+    "@zuplo/core": "6.68.0",
+    "@zuplo/runtime": "6.68.0",
     "@zuplo/test": "1.4.0"
   }
 }