zuplo 6.67.32 → 6.68.0

package/docs/articles/sharing-code-across-projects.mdx

@@ -0,0 +1,412 @@
+---
+title: Sharing Code Across Zuplo Projects
+sidebar_label: Sharing Code Across Projects
+description:
+  Learn how to create a shared npm package containing TypeScript modules that
+  can be reused across multiple Zuplo projects.
+tags:
+  - custom-code
+  - deployment
+---
+
+When you have multiple Zuplo projects that share common functionality like
+custom policies, handlers, or utility functions, you can create a shared npm
+package to avoid duplicating code. This guide shows how to create a reusable
+TypeScript module package and automatically copy the source files into your
+Zuplo projects.
+
+## Overview
+
+The approach is straightforward:
+
+1. Create an npm package containing your shared TypeScript code and a
+   `postinstall` script that copies files to the consumer's `modules` folder
+2. Publish it to npm or a private registry (or reference it directly via Git)
+3. Install the package in your Zuplo projects - the `postinstall` script
+   automatically copies the `.ts` files into `./modules`
+
+:::note
+
+Since Zuplo compiles TypeScript at deployment time, you ship raw TypeScript
+source files rather than pre-compiled JavaScript. This ensures your shared code
+integrates seamlessly with Zuplo's build process.
+
+:::
+
+## Creating the Shared Package
+
+### Project Structure
+
+Create a new npm package with the following structure:
+
+```
+my-shared-zuplo-modules/
+├── package.json
+├── scripts/
+│   └── copy-to-modules.mjs
+├── src/
+│   ├── policies/
+│   │   └── custom-auth-policy.ts
+│   ├── handlers/
+│   │   └── custom-handler.ts
+│   └── utils/
+│       └── helpers.ts
+└── README.md
+```
+
+### Package Configuration
+
+Configure your `package.json` to include the TypeScript source files and a
+`postinstall` script that copies them to the consumer's `modules` folder:
+
+```json title="my-shared-zuplo-modules/package.json"
+{
+  "name": "@your-org/shared-zuplo-modules",
+  "version": "1.0.0",
+  "description": "Shared Zuplo modules for custom policies and handlers",
+  "files": ["src/**/*.ts", "scripts/**/*.mjs"],
+  "scripts": {
+    "postinstall": "node ./scripts/copy-to-modules.mjs"
+  },
+  "peerDependencies": {
+    "@zuplo/runtime": "^1.0.0"
+  },
+  "devDependencies": {
+    "@zuplo/runtime": "^1.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+Key points:
+
+- The `files` array includes both the source files and the copy script
+- The `postinstall` script runs automatically when the package is installed
+- Use `peerDependencies` for `@zuplo/runtime` since consumers provide this
+- No build step is needed because you're shipping raw TypeScript
+
+### Copy Script
+
+Create a script in your shared package that copies files to the consumer's
+`modules` folder. The script adds a header comment to each file indicating it
+was auto-generated and should not be edited directly:
+
+```js title="my-shared-zuplo-modules/scripts/copy-to-modules.mjs"
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Source: the src directory in this package
+const sourceDir = resolve(__dirname, "..", "src");
+
+// Destination: the modules/shared folder in the consuming project
+// Navigate up from node_modules/@your-org/shared-zuplo-modules/scripts
+const projectRoot = resolve(__dirname, "..", "..", "..", "..");
+const destDir = join(projectRoot, "modules", "shared");
+
+// Read package.json to get package name and version
+const packageJson = JSON.parse(
+  readFileSync(resolve(__dirname, "..", "package.json"), "utf-8"),
+);
+const packageInfo = `${packageJson.name}@${packageJson.version}`;
+
+// Header comment to add to copied files
+const header = `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ *
+ * This file was copied from ${packageInfo}
+ * Any changes made here will be overwritten when the package is updated.
+ *
+ * To modify this code, edit the source in the shared package and republish.
+ */
+
+`;
+
+// Recursively process and copy files
+function copyWithHeader(src, dest) {
+  if (!existsSync(dest)) {
+    mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = readdirSync(src);
+
+  for (const entry of entries) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+
+    if (statSync(srcPath).isDirectory()) {
+      copyWithHeader(srcPath, destPath);
+    } else if (entry.endsWith(".ts")) {
+      // Add header to TypeScript files
+      const content = readFileSync(srcPath, "utf-8");
+      writeFileSync(destPath, header + content);
+    } else {
+      // Copy other files as-is
+      cpSync(srcPath, destPath);
+    }
+  }
+}
+
+// Copy all files with headers
+if (existsSync(sourceDir)) {
+  copyWithHeader(sourceDir, destDir);
+  console.log(`✅ Copied shared modules to ${destDir}`);
+} else {
+  console.warn(`⚠️ Source directory not found: ${sourceDir}`);
+}
+```
+
+This script runs automatically when someone installs your package, copying your
+TypeScript source files directly into their Zuplo project's `modules/shared`
+folder with a header comment indicating the source.
+
+### Example Shared Code
+
+Create your shared modules using standard Zuplo patterns:
+
+```ts title="my-shared-zuplo-modules/src/policies/custom-auth-policy.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export interface CustomAuthOptions {
+  headerName: string;
+  allowedValues: string[];
+}
+
+export default async function customAuthPolicy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: CustomAuthOptions,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  const headerValue = request.headers.get(options.headerName);
+
+  if (!headerValue) {
+    return new Response(`Missing ${options.headerName} header`, {
+      status: 401,
+    });
+  }
+
+  if (!options.allowedValues.includes(headerValue)) {
+    return new Response("Unauthorized", { status: 403 });
+  }
+
+  return request;
+}
+```
+
+```ts title="my-shared-zuplo-modules/src/utils/helpers.ts"
+import { ZuploContext } from "@zuplo/runtime";
+
+export function formatRequestId(context: ZuploContext): string {
+  return `req-${context.requestId.slice(0, 8)}`;
+}
+
+export function parseJsonSafely<T>(text: string): T | null {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return null;
+  }
+}
+```
+
+### Publishing the Package
+
+Publish to npm or your private registry:
+
+```bash
+# Public npm
+npm publish --access public
+
+# Private npm registry
+npm publish --registry https://your-registry.example.com
+
+# Or use npm link for local development
+npm link
+```
+
+Alternatively, you can reference the package directly from a Git repository
+without publishing:
+
+```json title="package.json"
+{
+  "dependencies": {
+    "@your-org/shared-zuplo-modules": "github:your-org/shared-zuplo-modules#v1.0.0"
+  }
+}
+```
+
+## Using the Shared Package in Zuplo Projects
+
+### Install the Package
+
+In your Zuplo project, install the shared package:
+
+```bash
+npm install @your-org/shared-zuplo-modules
+```
+
+The package's `postinstall` script automatically copies the TypeScript files to
+your `modules/shared` folder. After installation, your project structure looks
+like this:
+
+```
+your-zuplo-project/
+├── modules/
+│   ├── shared/           # Automatically copied from the shared package
+│   │   ├── policies/
+│   │   │   └── custom-auth-policy.ts
+│   │   ├── handlers/
+│   │   │   └── custom-handler.ts
+│   │   └── utils/
+│   │       └── helpers.ts
+│   └── my-handler.ts     # Your project-specific modules
+├── config/
+│   ├── routes.oas.json
+│   └── policies.json
+└── package.json
+```
+
+### Import and Use the Shared Code
+
+Import the shared modules using relative paths from your project modules:
+
+```ts title="modules/my-handler.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+import { formatRequestId, parseJsonSafely } from "./shared/utils/helpers";
+
+export default async function myHandler(
+  request: ZuploRequest,
+  context: ZuploContext,
+): Promise<Response> {
+  const requestId = formatRequestId(context);
+  context.log.info(`Processing request: ${requestId}`);
+
+  const body = parseJsonSafely<{ name: string }>(await request.text());
+
+  return new Response(JSON.stringify({ requestId, data: body }), {
+    headers: { "content-type": "application/json" },
+  });
+}
+```
+
+Reference shared policies in your `policies.json`:
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "custom-auth",
+      "policyType": "custom-code-inbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/shared/policies/custom-auth-policy)",
+        "options": {
+          "headerName": "x-api-key",
+          "allowedValues": ["key1", "key2"]
+        }
+      }
+    }
+  ]
+}
+```
+
+## Version Management
+
+To ensure consistency, pin your shared package versions:
+
+```json title="package.json"
+{
+  "dependencies": {
+    "@your-org/shared-zuplo-modules": "1.2.3"
+  }
+}
+```
+
+Use a lockfile (`package-lock.json` or `pnpm-lock.yaml`) and commit it to ensure
+all team members and CI/CD pipelines use the same version.
+
+## Source Control
+
+### Commit the Copied Files
+
+The copied shared modules must be committed to your Git repository. Zuplo
+deployments require all source files to be present in the repository - they are
+not generated during the build process.
+
+After installing or updating the shared package, commit the changes:
+
+```bash
+npm install @your-org/shared-zuplo-modules
+git add modules/shared/
+git commit -m "Update shared modules to v1.2.3"
+```
+
+The header comments added by the copy script help identify these files as
+generated code that should not be edited directly. If you need to make changes,
+update the source in the shared package and republish.
+
+### Updating Shared Modules
+
+When you update the shared package version, the `postinstall` script overwrites
+the existing files with the new version. Review the changes before committing:
+
+```bash
+npm update @your-org/shared-zuplo-modules
+git diff modules/shared/
+git add modules/shared/
+git commit -m "Update shared modules to v1.3.0"
+```
+
+## Troubleshooting
+
+### Files Not Copying
+
+If files aren't being copied after installing the shared package:
+
+1. Verify the shared package is installed:
+   `ls node_modules/@your-org/shared-zuplo-modules`
+2. Check the package's `postinstall` script ran by looking for the success
+   message in the install output
+3. Verify the `scripts/copy-to-modules.mjs` file is included in the package's
+   `files` array
+4. Check the path calculations in the copy script are correct for your package
+   structure
+
+### TypeScript Errors
+
+If you see TypeScript errors after copying:
+
+1. Ensure `@zuplo/runtime` versions match between the shared package and your
+   project
+2. Check that all required dependencies are available
+3. Run `npm run typecheck` to identify specific issues
+
+### Import Path Issues
+
+Use relative imports from your modules:
+
+```ts
+// ✅ Correct - relative path from your module
+import { helper } from "./shared/utils/helpers";
+
+// ❌ Incorrect - absolute or package-style import
+import { helper } from "@your-org/shared-zuplo-modules/utils/helpers";
+```
+
+## Related Resources
+
+- [Share code across request handlers and policies](../programmable-api/reusing-code.mdx)
+- [Node Modules](../programmable-api/node-modules.mdx)
+- [Custom Code Inbound Policy](../policies/custom-code-inbound.mdx)
+- [Custom Handler](../handlers/custom-handler.mdx)

package/docs/articles/source-control-setup-azure.mdx

@@ -0,0 +1,13 @@
+---
+title: Azure DevOps Setup
+sidebar_label: Setup
+---
+
+Azure DevOps integration is available on
+[enterprise plans](https://zuplo.com/pricing). Contact
+[support@zuplo.com](mailto:support@zuplo.com) to enable Azure DevOps for your
+account.
+
+Azure DevOps provides source control integration (push/pull between portal and
+repository) but does not include automatic deployments. Use
+[Azure Pipelines](./custom-ci-cd-azure.mdx) to deploy your API.

package/docs/articles/source-control-setup-bitbucket.mdx

@@ -0,0 +1,43 @@
+---
+title: Bitbucket Setup
+sidebar_label: Setup
+---
+
+Bitbucket integration is available on
+[enterprise plans](https://zuplo.com/pricing). Bitbucket provides source control
+integration (push/pull between portal and repository) but does not include
+automatic deployments. Use [Bitbucket Pipelines](./custom-ci-cd-bitbucket.mdx)
+to deploy your API.
+
+## Bitbucket.org
+
+If you are using the SaaS Bitbucket hosted at bitbucket.org, contact
+[support@zuplo.com](mailto:support@zuplo.com) to enable Bitbucket on your
+account.
+
+Provide support with your Bitbucket Workspace ID, found on your Workspace
+Settings page.
+
+## Self-Hosted Bitbucket
+
+For self-hosted Bitbucket, you need to
+[set up a custom Bitbucket OAuth App](https://support.atlassian.com/bitbucket-cloud/docs/integrate-another-application-through-oauth/)
+and provide Zuplo support with the following values:
+
+- **Bitbucket Server URL** — Something like `https://bitbucket.example.com`
+- **Client ID** — The client ID of the Bitbucket app you created
+- **Client Secret** — The client secret of the Bitbucket app you created
+
+When configuring your app you will need to set the following values:
+
+- **Callback URL** - `https://portal.zuplo.com`
+- **Permissions** - `repo user read:org`
+
+## Limiting Access
+
+Bitbucket doesn't support scoping OAuth app access to specific repositories.
+This is a Bitbucket limitation. To limit Zuplo's access:
+
+1. Create a new workspace and install the Zuplo app only in that workspace
+2. Create a service account user with limited repository access and use that
+   user to connect Bitbucket to Zuplo

package/docs/articles/source-control-setup-github.mdx

@@ -0,0 +1,172 @@
+---
+title: GitHub Setup
+sidebar_label: Setup
+---
+
+Connect your Zuplo project to GitHub for source control and automatic
+deployments. Every push to your repository deploys automatically — no CI/CD
+configuration required.
+
+## Connect Your Project to GitHub
+
+This guide assumes you have a Zuplo project created. If you don't have one yet,
+follow the steps in
+[Step 1 - Setup a Basic Gateway](./step-1-setup-basic-gateway.mdx) to create a
+new Zuplo project.
+
+<Stepper>
+
+1. Connect to GitHub
+
+   Go to your project in the Zuplo portal, click **Settings**, then select
+   **Source Control**. If your project isn't already connected to GitHub click
+   the **Connect to GitHub** button and follow the auth flow. You'll need to
+   grant permissions for any GitHub organizations you want to work with.
+
+   ![Connect GitHub](../../public/media/step-4-deploying-to-the-edge/image-1.png)
+
+1. **Authorize Zuplo**
+
+   A dialog will open asking you to authorize Zuplo. Click the **Authorize
+   Zuplo** button.
+
+   <Framed size="sm">
+
+   ![Zuplo GitHub permission](../../public/media/source-control-setup-github/d6194a80-b6d6-429e-85a6-ae1cb4a3375e.png)
+
+   </Framed>
+
+   :::tip{title="GitHub Permissions"}
+
+   The permission "Act on your behalf" sounds a bit scary - however, this is a
+   standard GitHub permission and by default Zuplo can't actually do anything
+   with this. In order to perform actions on your behalf you must grant Zuplo
+   access to a specific repository (shown in the next steps).
+
+   You can
+   [read more about this permission on GitHub's docs](https://docs.github.com/en/apps/using-github-apps/authorizing-github-apps#about-github-apps-acting-on-your-behalf).
+
+   :::
+
+1. **Select a GitHub organization**
+
+   After you have connected the GitHub app, it needs to be granted permission to
+   edit a repository. If this is your first time connecting Zuplo, you will be
+   immediately asked to select a GitHub Org to install Zuplo. Select the org you
+   want to use.
+
+   <Framed size="sm">
+
+   ![Installing Zuplo app](../../public/media/source-control-setup-github/eef76bd7-4d26-4f86-96e8-89ebede03beb.png)
+
+   </Framed>
+
+1. **Select repositories**
+
+   You will be asked to select the repositories that you want Zuplo to access.
+   The easiest thing is to just select **All Repositories**, but if you want
+   fine-grain control, you can select a specific repository.
+
+   <Framed size="sm">
+
+   ![Giving Zuplo repository access](../../public/media/source-control-setup-github/ff482269-9aa2-44c3-8266-b2682b3d6ea5.png)
+
+   </Framed>
+
+   :::caution{title="Existing Installation"}
+
+   If you weren't prompted to select a GitHub org, it's likely that you are
+   already a member of an account that has authorized Zuplo. To add Zuplo to a
+   new organization click **Add GitHub Account** in the org picker list.
+
+   ![Connect Org](../../public/media/step-4-deploying-to-the-edge/image-2.png)
+
+   :::
+
+1. **Create a repository**
+
+   With your GitHub App configured, return to the Zuplo portal. In the **Source
+   Control** settings you should now see a list of GitHub repositories. Create a
+   new repository by clicking the **Create new repository** button. You will be
+   prompted that this will open GitHub. Click to continue.
+
+   ![Create Repository](../../public/media/step-4-deploying-to-the-edge/image-3.png)
+
+   In the GitHub UI, you can rename your repository if you want. Click the
+   **Create repository** button at the bottom of the page and return to the
+   Zuplo Portal.
+
+1. **Connect your repository**
+
+   The portal will reload and you will see your new repository listed. Click
+   **Connect** to connect Zuplo to that repository.
+
+   ![Connect](../../public/media/step-4-deploying-to-the-edge/image-4.png)
+
+   After the connection succeeds you will see a link to your GitHub repository.
+
+   ![Connected Repository](../../public/media/step-4-deploying-to-the-edge/image-5.png)
+
+1. **Verify deployment**
+
+   Click the link to return to GitHub. You should see a green check next to the
+   commit hash (1). When you hover your mouse over that you'll see the Zuplo
+   deployment was successful. Click **Details** (2) to open the deployment info.
+
+   ![Zuplo deployment running](../../public/media/source-control-setup-github/0a9932eb-7c16-49cf-9720-0beb450724eb.png)
+
+   On the deployment page, you will see **Deployment has Completed!!** and below
+   that's the link to your new environment.
+
+   ![Zuplo deployment result](../../public/media/source-control-setup-github/26fa58b6-7a5a-4627-bd9f-246972639f12.png)
+
+</Stepper>
+
+## Connecting Existing Repositories
+
+If you have an existing GitHub repository that contains a Zuplo project, you can
+connect to that repository when you create a new project. Select **Import
+existing project** then select your GitHub organization and repository.
+
+![Import existing project to Zuplo](../../public/media/source-control/image-1.png)
+
+## What's Included
+
+With GitHub connected, you get:
+
+- **Automatic deployments** — Every push deploys to Zuplo automatically
+- **Branch environments** — Each branch gets its own isolated environment
+- **Deployment status** — See deploy results as GitHub checks on commits and PRs
+- **Portal sync** — Push and pull changes between the Zuplo portal and GitHub
+
+## Next Steps
+
+- **[Testing Deployments](./github-deployment-testing.mdx)** — Run tests
+  automatically after each deploy
+- **[Custom GitHub Actions](./custom-ci-cd-github.mdx)** — Advanced workflows
+  with approval gates and multi-stage deployments
+- **[Branch-Based Deployments](./branch-based-deployments.mdx)** — How branches
+  map to environments
+
+## Frequently Asked Questions
+
+<Faq>
+  <FaqItem question="What happens if I disconnect my repository?">
+    If you disconnect your repository, you can go back to source control
+    settings and reconnect it.
+  </FaqItem>
+  <FaqItem question="What happens if I rename my repository?">
+    Renaming your repository will break the connection. You must disconnect and
+    reconnect to restore the link.
+  </FaqItem>
+  <FaqItem question="Can I connect multiple Zuplo projects to the same repo?">
+    No, each Zuplo project must be connected to a unique GitHub repository.
+  </FaqItem>
+  <FaqItem question="My project isn't deploying, what do I do?">
+    First, check the deployment status in GitHub. If there is an error message,
+    follow the instructions to resolve it. Next, check that the [Zuplo GitHub
+    app](https://github.com/apps/zuplo) is installed in your organization and
+    has access to the repository where your Zuplo projects are located. If you
+    need help, contact Zuplo support.
+  </FaqItem>
+</Faq>

package/docs/articles/source-control-setup-gitlab.mdx

@@ -0,0 +1,12 @@
+---
+title: GitLab Setup
+sidebar_label: Setup
+---
+
+GitLab integration is available on
+[enterprise plans](https://zuplo.com/pricing). Contact
+[support@zuplo.com](mailto:support@zuplo.com) to enable GitLab for your account.
+
+GitLab provides source control integration (push/pull between portal and
+repository) but does not include automatic deployments. Use
+[GitLab CI/CD pipelines](./custom-ci-cd-gitlab.mdx) to deploy your API.