zuplo 6.70.57 → 6.70.59

package/docs/articles/step-3-add-api-key-auth-local.mdx

@@ -3,11 +3,6 @@ title: Step 3 - API Key Authentication
 sidebar_label: "3 - API Key Auth"
 ---
 
-<QuickstartPicker
-  mode="local"
-  alternateLink="/articles/step-3-add-api-key-auth"
-/>
-
 In this guide we'll add API Key authentication to a route. You can do this for
 any Zuplo project but will need a route, consider completing
 [Step 1](./step-1-setup-basic-gateway-local.mdx) first.
@@ -30,171 +25,126 @@ Let's get started.
 
 <Stepper>
 
-1.  Link your Local Project
-
-    When developing locally with Zuplo, you can "link" your local project to
-    your Zuplo project using the `zuplo link` command. This allows you to test
-    your changes in a real environment.
-
-    When you run the command you will be prompted to select your Zuplo account,
-    project, and environment. You can pick any environment.
-
-    ```bash
-    npx zuplo link
-    ```
-
-    After your project is linked, environment variables and other configuration
-    from your Zuplo project will be available in your local development
-    environment.
-
-1.  Start your Project
-
-    You can start your project using the following command:
-
-    ```bash
-    npx zuplo dev
-    ```
-
-    After your project is started, you can open the local route designer at
-    http://localhost:9100.
-
-1.  Add the API Key Authentication Policy
+1. Add the API Key Authentication Policy
 
-    Open the local **Route Designer** by navigating to http://localhost:9100/.
-    Select your route and click **Add Policy** on the incoming request policies
-    section.
+   Open the local **Route Designer** at http://localhost:9100. If your gateway
+   isn't already running, start it from your project directory with
+   `npm run dev`.
 
-    <BrowserScreenshot url="http://localhost:9100/?path=routes.oas.json">
+   Select your route and click **Add Policy** on the incoming request policies
+   section.
 
-    ![Add Policy](../../public/media/step-3-add-api-key-auth-local/image.png)
+   <BrowserScreenshot url="http://localhost:9100/?path=routes.oas.json">
 
-    </BrowserScreenshot>
+   ![Add Policy](../../public/media/step-3-add-api-key-auth-local/image.png)
 
-    Search for the API key authentication policy, click on it, and then click
-    **Create Policy** to accept the default policy JSON.
+   </BrowserScreenshot>
 
-    <ModalScreenshot>
+   Search for the API key authentication policy, click on it, and then click
+   **Create Policy** to accept the default policy JSON.
 
-    ![Add API Key Authentication](../../public/media/step-3-add-api-key-auth/choose-policy.png)
+   <ModalScreenshot>
 
-    </ModalScreenshot>
+   ![Add API Key Authentication](../../public/media/step-3-add-api-key-auth/choose-policy.png)
 
-    :::tip
+   </ModalScreenshot>
 
-    The API key authentication policy should usually be one of the first
-    policies executed. If you came here from
-    [Step 2](./step-2-add-rate-limiting.mdx) then you will want to drag it above
-    the rate limiting policy.
+   :::tip
 
-    :::
+   The API key authentication policy should usually be one of the first policies
+   executed. If you came here from
+   [Step 2](./step-2-add-rate-limiting-local.mdx) then you will want to drag it
+   above the rate limiting policy.
 
-    ![reorder policies](../../public/media/step-3-add-api-key-auth/image-1.gif)
+   :::
 
-    If you test your route, you should get a 401 Unauthorized response
+   ![reorder policies](../../public/media/step-3-add-api-key-auth/image-1.gif)
 
-    ```json
-    {
-      "status": 401,
-      "title": "Unauthorized",
-      "type": "https://httpproblems.com/http-status/401"
-    }
-    ```
+   If you test your route, you should get a 401 Unauthorized response
 
-1.  Set up an API Key
+   ```json
+   {
+     "status": 401,
+     "title": "Unauthorized",
+     "type": "https://httpproblems.com/http-status/401"
+   }
+   ```
 
-    In order to call your API, you need to configure an API consumer. In the
-    Zuplo Portal, open the
-    [**Services**](https://portal.zuplo.com/+/account/project/services) tab for
-    your project, then click **Configure** on the "API Key Service".
+1. Set up an API Key
 
-    :::warning
+   In order to call your API, you need to configure an API consumer. In the
+   Zuplo Portal, open the
+   [**Services**](https://portal.zuplo.com/+/account/project/services) tab for
+   your project, then click **Configure** on the "API Key Service".
 
-    Be sure to select the appropriate environment in the dropdown on the top
-    right of the services page. You must select the environment type you linked
-    your local project to. If you only have a single environment, you should
-    select "Production". Later we will create new environments for preview.
+   :::warning
 
-    :::
+   Be sure to select the appropriate environment in the dropdown on the top
+   right of the services page. You must select the environment type your local
+   project is linked to. If you only have a single environment, you should
+   select "Production". Later we will create new environments for preview.
 
-    ![API Key Service](../../public/media/step-3-add-api-key-auth/image-2.png)
+   :::
 
-    Then click **Create Consumer**.
+   ![API Key Service](../../public/media/step-3-add-api-key-auth/image-2.png)
 
-    ![Create Consumer](../../public/media/step-2-add-api-key-auth/image-8.png)
+   Then click **Create Consumer**.
 
-    Let's break down the configuration needed.
-    - Subject: Also known as `sub`. This is a unique identifier of the API
-      consumer. This is commonly the name of the user or organization consuming
-      your API
-    - Key managers: The email addresses of those who will be managing this API
-      key.
-    - Metadata: JSON metadata that will be made available to the runtime when a
-      key is used to authenticate. Common properties include the consumer's
-      subscription plan, organization, etc.
+   ![Create Consumer](../../public/media/step-2-add-api-key-auth/image-8.png)
 
-    Go ahead and fill in `test-consumer` for the Subject. Add your own email as
-    a Key manager, and leave the metadata empty for now. Click **Save consumer**
-    once you're done.
+   Let's break down the configuration needed.
+   - Subject: Also known as `sub`. This is a unique identifier of the API
+     consumer. This is commonly the name of the user or organization consuming
+     your API
+   - Key managers: The email addresses of those who will be managing this API
+     key.
+   - Metadata: JSON metadata that will be made available to the runtime when a
+     key is used to authenticate. Common properties include the consumer's
+     subscription plan, organization, etc.
 
-    <ModalScreenshot>
+   Go ahead and fill in `test-consumer` for the Subject. Add your own email as a
+   Key manager, and leave the metadata empty for now. Click **Save consumer**
+   once you're done.
 
-    ![New Consumer](../../public/media/step-3-add-api-key-auth/image-3.png)
+   <ModalScreenshot>
 
-    </ModalScreenshot>
+   ![New Consumer](../../public/media/step-3-add-api-key-auth/image-3.png)
 
-1.  Copy your API Key
+   </ModalScreenshot>
 
-    After your API Key consumer is created, copy your new API Key by clicking
-    the copy button (next to the eye icon).
+1. Copy your API Key
 
-    ![Copy Key](../../public/media/step-3-add-api-key-auth/image-4.png)
+   After your API Key consumer is created, copy your new API Key by clicking the
+   copy button (next to the eye icon).
 
-1.  Test out your API Key
+   ![Copy Key](../../public/media/step-3-add-api-key-auth/image-4.png)
 
-    Using any HTTP client (like Postman or curl), make a request to your API.
+1. Test out your API Key
 
-    ```bash
-    curl --request GET \
-    --url http://localhost:9000/path-1 \
-    --header 'Authorization: Bearer zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx'
-    ```
+   Using any HTTP client (like Postman or curl), make a request to your API.
 
-    You should get a 401 Unauthorized response - as we haven't supplied the API
-    key yet. Add a new `authorization` header with the value
-    `Bearer <YOUR_API_KEY>` and insert the API Key you got from the developer
-    portal.
+   ```bash
+   curl --request GET \
+     --url http://localhost:9000/todos \
+     --header 'Authorization: Bearer <YOUR_API_KEY>'
+   ```
 
-    You should now get a 200 OK.
+   First, try without an authorization header — you should get a 401
+   Unauthorized response since the API Key policy is rejecting the request.
 
-    ```json
-    {
-      "url": "https://echo.zuplo.io/path-1",
-      "method": "GET",
-      "query": {},
-      "headers": {
-        "accept": "*/*",
-        "accept-encoding": "gzip, br",
-        "connection": "Keep-Alive",
-        "host": "echo.zuplo.io",
-        "true-client-ip": "12.63.237.42",
-        "user-agent": "curl/8.7.1",
-        "x-forwarded-proto": "https",
-        "x-real-ip": "12.63.237.42",
-        "zp-rid": "ecfac0de-f039-4ced-997c-b17c9babc944"
-      }
-    }
-    ```
+   Now include `Authorization: Bearer <YOUR_API_KEY>` with the key you just
+   copied. You should get a `200 OK` with the JSON list of todos.
 
-    :::note
+   :::note
 
-    We also offer an API for our API key service that allows you to
-    programmatically create consumers and even create your own developer portal
-    or integrate key management into your existing dashboard. See
-    [this document for details](./api-key-api.mdx).
+   We also offer an API for our API key service that allows you to
+   programmatically create consumers and even create your own developer portal
+   or integrate key management into your existing dashboard. See
+   [this document for details](./api-key-api.mdx).
 
-    :::
+   :::
 
 </Stepper>
 
 **NEXT** Try
-[Step 4 - Connect Source Control and Deploy to the Edge](./step-4-deploying-to-the-edge.mdx).
+[Step 4 - Deploy to the Edge](./step-4-deploying-to-the-edge-local.mdx).

package/docs/articles/step-3-add-api-key-auth.mdx

@@ -3,11 +3,6 @@ title: Step 3 - API Key Authentication
 sidebar_label: "3 - API Key Auth"
 ---
 
-<QuickstartPicker
-  mode="portal"
-  alternateLink="/articles/step-3-add-api-key-auth-local"
-/>
-
 In this guide we'll add API Key authentication to a route. You can do this for
 any Zuplo project but will need a route, consider completing
 [Step 1](./step-1-setup-basic-gateway.mdx) first.

package/docs/articles/step-4-deploying-to-the-edge-local.mdx

@@ -0,0 +1,106 @@
+---
+title: Step 4 - Deploy to the Edge
+sidebar_label: "4 - Deploy"
+---
+
+In this guide we'll deploy your locally-developed gateway to the edge, at over
+300 data-centers around the world. Zuplo deploys from Git source control — once
+your project is connected to a GitHub repository, every push deploys
+automatically, with no CI/CD configuration required.
+
+The act of deployment creates new [environments](./environments.mdx), so it's
+worth familiarizing yourself with [how environments work](./environments.mdx).
+
+To follow this tutorial you'll need a GitHub account (it's free, sign up at
+[github.com](https://github.com)).
+
+<Stepper>
+
+1. **Check your project status**
+
+   From your project directory, run `zuplo info` to see how your local project
+   maps to Zuplo:
+
+   ```bash
+   npx zuplo info
+   ```
+
+   ```bash
+   Project: example-project
+   Account: your-account
+   Portal: https://portal.zuplo.com/your-account/example-project
+   Environment Type: working-copy
+   Source Control: none, connect at https://portal.zuplo.com/your-account/example-project/settings/source-control-settings
+   ```
+
+   Notice the **Source Control** line shows `none` — your project isn't
+   connected to a repository yet. The next steps walk through connecting one so
+   your changes deploy automatically.
+
+1. **Create a GitHub repository**
+
+   In GitHub, [create a new repository](https://github.com/new). Leave it
+   **empty** — don't add a README, `.gitignore`, or license — since your project
+   already contains those files.
+
+1. **Push your project to GitHub**
+
+   `create-zuplo-api` already initialized your project as a Git repository.
+   Stage and commit your work (if you haven't already), then point your local
+   repo at the new GitHub repository and push:
+
+   ```bash
+   git add .
+   git commit -m "Initial commit"
+   git remote add origin https://github.com/your-account/example-project.git
+   git branch -M main
+   git push -u origin main
+   ```
+
+1. **Connect the repository in Zuplo**
+
+   Open the source-control settings link from the `zuplo info` output, or in the
+   Zuplo Portal open **Settings → Source Control**.
+
+   If this is your first time, click **Connect to GitHub** and authorize the
+   Zuplo GitHub app — see [GitHub Setup](./source-control-setup-github.mdx) for
+   a detailed walkthrough of the authorization flow and permissions.
+
+   Once the app has access to your repositories, find the repository you just
+   pushed to in the list and click **Connect**.
+
+   :::note{title="Non-empty repository warning"}
+
+   Because you already pushed your project, the portal will show a dialog
+   warning that the repository isn't empty and that connecting will only create
+   an association — no changes will be pushed or pulled automatically. That's
+   exactly what we want here, so click **Connect** to proceed.
+
+   :::
+
+1. **Verify your deployment**
+
+   As soon as the repository is connected, Zuplo deploys your `main` branch. In
+   GitHub you'll see a status check next to your commit; when it succeeds, the
+   deployment links to your new environment.
+
+   Run `zuplo info` again to confirm your project is now connected to source
+   control:
+
+   ```bash
+   npx zuplo info
+   ```
+
+   :::tip{title="Branch environments"}
+
+   Every branch you push gets its own isolated environment. Create a
+   `development` branch, push it, and Zuplo deploys a matching environment
+   automatically. See [Branch-Based Deployments](./branch-based-deployments.mdx)
+   to learn how branches map to environments.
+
+   :::
+
+</Stepper>
+
+**NEXT** Try
+[Step 5 - Add Dynamic Rate Limiting](./step-5-dynamic-rate-limiting-local.mdx).

package/docs/articles/step-5-dynamic-rate-limiting-local.mdx

@@ -0,0 +1,180 @@
+---
+title: Step 5 - Dynamic Rate Limiting
+sidebar_label: "5 - Dynamic Rate Limiting"
+---
+
+Fortune favors the bold. In this bonus getting started guide we'll show you how
+to add dynamic rate limiting to your API, all from your local project.
+
+To follow this tutorial you'll need to have completed
+[Step 1](./step-1-setup-basic-gateway-local.mdx) for a Zuplo project,
+[Step 2](./step-2-add-rate-limiting-local.mdx) to add rate limiting to a route,
+and [Step 3](./step-3-add-api-key-auth-local.mdx) to add API key authentication
+to that same route.
+
+:::info{title="What's Dynamic Rate Limiting?"}
+
+Traditionally, rate limits are static and the same for everyone. This approach
+doesn't let you tailor your rate limiting to your API user - you might want to
+offer higher rate limits for customers that pay more. Dynamic rate limiting
+allows you to determine an appropriate rate limit at request time.
+
+:::
+
+Let's get started.
+
+<Stepper>
+
+1. Add Consumer Metadata
+
+   Let's make our rate-limiting policy more dynamic, based on properties of the
+   customer. In the Zuplo Portal,
+   [create a new consumer](./step-3-add-api-key-auth-local.mdx) (Services → API
+   Key Service → Configure → Create Consumer), and in the Metadata field set the
+   following:
+
+   ```json
+   {
+     "customerType": "free"
+   }
+   ```
+
+   Update the metadata of your other API Key consumer (3-dot menu → Edit) from
+   Step 3 to:
+
+   ```json
+   {
+     "customerType": "premium"
+   }
+   ```
+
+   Now that there are users with different `customerType`, this information can
+   be used to rate limit them differently.
+
+1. Add a Custom Code Module
+
+   In your editor, create a new file at `modules/rate-limit.ts` in your project.
+
+   :::info{title="What's a Module?"}
+
+   Modules are TypeScript functions that you can execute within Zuplo. They're
+   typically used to add custom code within the request/response pipeline (for
+   example custom policies or request handlers). You can even perform network
+   requests and use libraries within these modules.
+
+   :::
+
+   Add the following code to your module:
+
+   ```ts
+   import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+   export function rateLimit(request: ZuploRequest, context: ZuploContext) {
+     const user = request.user;
+
+     // premium customers get 1000 requests per minute
+     if (user.data.customerType === "premium") {
+       return {
+         key: user.sub,
+         requestsAllowed: 1000,
+         timeWindowMinutes: 1,
+       };
+     }
+
+     // free customers get 5 requests per minute
+     if (user.data.customerType === "free") {
+       return {
+         key: user.sub,
+         requestsAllowed: 5,
+         timeWindowMinutes: 1,
+       };
+     }
+
+     // everybody else gets 30 requests per minute
+     return {
+       key: user.sub,
+       requestsAllowed: 30,
+       timeWindowMinutes: 1,
+     };
+   }
+   ```
+
+1. Update your Policy
+
+   Now we'll reconfigure the rate-limiting policy to wire up our custom
+   function. Open the local **Route Designer** at http://localhost:9100, find
+   the policy, and click **Edit** — or edit `config/policies.json` directly in
+   your editor.
+
+   Update the configuration to:
+
+   ```json
+   {
+     "export": "RateLimitInboundPolicy",
+     "module": "$import(@zuplo/runtime)",
+     "options": {
+       "rateLimitBy": "function",
+       "requestsAllowed": 2,
+       "timeWindowMinutes": 1,
+       "identifier": {
+         "export": "rateLimit",
+         "module": "$import(./modules/rate-limit)"
+       }
+     }
+   }
+   ```
+
+   By changing the `rateLimitBy` to `function` you are indicating the rate limit
+   will be determined by a module at runtime. The `identifier` property
+   indicates the module and function to run. Make sure to save once you've made
+   your changes.
+
+   :::tip
+
+   Dynamic rate limiting reads from `request.user`, so the API key
+   authentication policy from [Step 3](./step-3-add-api-key-auth-local.mdx) must
+   run **before** the rate-limiting policy.
+
+   :::
+
+1. Test your Policy
+
+   With your gateway running (`npm run dev`), try your dynamic rate limiting.
+   Grab the key for each consumer back in the Services tab where you created
+   them, then make calls with each key until you hit its limit.
+
+   ```bash
+   # free consumer — limited to 5 requests per minute
+   curl http://localhost:9000/todos \
+     --header 'Authorization: Bearer <FREE_CONSUMER_KEY>'
+
+   # premium consumer — allowed 1000 requests per minute
+   curl http://localhost:9000/todos \
+     --header 'Authorization: Bearer <PREMIUM_CONSUMER_KEY>'
+   ```
+
+   Observe the difference in rate limits between the two consumers.
+
+</Stepper>
+
+## Wrapping up
+
+Congratulations - you've just successfully built an API that's:
+
+- Protected by API key Authentication
+- Dynamically Rate Limited
+- Deployed to the Edge for superior performance
+- and fully documented via your Developer Portal
+
+This is an API experience most companies dream of, and you've just built it in
+less than an hour.
+
+### Next Steps
+
+- Continue exploring our docs to learn about customizing your
+  [Developer Portal](../dev-portal/introduction.mdx), or explore our various
+  [Integrations](https://zuplo.com/integrations)
+- [Grab time](https://zuplo.com/meeting) with the Zuplo team to have your
+  questions answered
+- Start generating revenue from your new API with our
+  [Monetization tutorial](./monetization/index.mdx)

package/docs/articles/support.mdx

@@ -26,21 +26,21 @@ are provided with every support plan:
 
 Zuplo offers the following support plans:
 
-| Support Offer     | Available to                                                                   |
-| ----------------- | ------------------------------------------------------------------------------ |
-| Community Support | All customers                                                                  |
-| Standard Support  | Customers with any paid subscription plan or those in the initial trial period |
-| Premium Support   | Customers who have purchased support as part of an enterprise plan             |
+| Support Offer     | Available to                                                       |
+| ----------------- | ------------------------------------------------------------------ |
+| Community Support | All customers                                                      |
+| Standard Support  | Included for customers on an enterprise plan                       |
+| Premium Support   | Customers who have purchased support as part of an enterprise plan |
 
 ### Community support
 
-Customers with Zuplo's free subscription plan can seek support through the Zuplo
+Customers on Zuplo's Free and Builder plans receive support through the Zuplo
 Community. Response times may vary and aren't guaranteed.
 
 ### Standard support
 
-Customers with a paid Zuplo subscription plan receive standard support which
-offers access to the following channels:
+Customers on a Zuplo enterprise plan receive standard support which offers
+access to the following channels:
 
 - Zuplo Community
 - Zuplo Email Support (best effort response times)