zilmate 1.8.1 → 1.9.1

package/.agents/skills/upstash/upstash-qstash-js/advanced/multi-region/verify-multi-region-setup.ts

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+/* eslint-disable no-console */
+
+/**
+ * Script to verify QStash environment variable setup
+ *
+ * This script checks:
+ * - Whether the setup is single-region or multi-region
+ * - Which region will be used for outgoing messages
+ * - Whether all required environment variables are present
+ *
+ * Usage:
+ *   npx tsx skills/advanced/scripts/verify-multi-region-setup.ts
+ *   # or with node
+ *   node skills/advanced/scripts/verify-multi-region-setup.js
+ *
+ * To load from .env file, install dotenv first:
+ *   npm install dotenv
+ *   npx tsx -r dotenv/config skills/advanced/scripts/verify-multi-region-setup.ts
+ */
+
+// // Try to load dotenv if available
+try {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-require-imports, unicorn/prefer-module
+  require("dotenv").config();
+} catch {
+  // dotenv not available, will use process.env directly
+}
+
+type QStashRegion = "EU_CENTRAL_1" | "US_EAST_1";
+
+const VALID_REGIONS = ["EU_CENTRAL_1", "US_EAST_1"] as const;
+const DEFAULT_QSTASH_URL = "https://qstash.upstash.io";
+
+type CheckResult = {
+  status: "success" | "warning" | "error";
+  message: string;
+};
+
+type VerificationResult = {
+  mode: "single-region" | "multi-region";
+  primaryRegion?: QStashRegion;
+  checks: CheckResult[];
+  outgoingConfig: {
+    url?: string;
+    token?: string;
+    source: string;
+  };
+  incomingConfig: {
+    currentKey?: string;
+    nextKey?: string;
+    source: string;
+  };
+};
+
+// Colors for terminal output
+const colors = {
+  reset: "\u001B[0m",
+  bright: "\u001B[1m",
+  red: "\u001B[31m",
+  green: "\u001B[32m",
+  yellow: "\u001B[33m",
+  blue: "\u001B[34m",
+  cyan: "\u001B[36m",
+};
+
+function colorize(color: keyof typeof colors, text: string): string {
+  return `${colors[color]}${text}${colors.reset}`;
+}
+
+function printHeader(text: string): void {
+  console.log("\n" + colorize("bright", colorize("cyan", text)));
+  console.log(colorize("cyan", "=".repeat(text.length)));
+}
+
+function printCheck(result: CheckResult): void {
+  const icon = result.status === "success" ? "✓" : result.status === "warning" ? "⚠" : "✗";
+  const color =
+    result.status === "success" ? "green" : result.status === "warning" ? "yellow" : "red";
+  console.log(`${colorize(color, icon)} ${result.message}`);
+}
+
+function normalizeRegion(region: string | undefined): QStashRegion | undefined {
+  if (!region) return undefined;
+
+  const normalized = region.replaceAll("-", "_").toUpperCase();
+  if (VALID_REGIONS.includes(normalized as QStashRegion)) {
+    return normalized as QStashRegion;
+  }
+
+  return undefined;
+}
+
+function checkEnvironmentVariable(name: string, required = false): CheckResult {
+  const value = process.env[name];
+
+  if (!value) {
+    return {
+      status: required ? "error" : "warning",
+      message: `${name} is ${required ? "required but " : ""}not set`,
+    };
+  }
+
+  const maskedValue = value.length > 10 ? `${value.slice(0, 4)}...${value.slice(-4)}` : "***";
+  return {
+    status: "success",
+    message: `${name} = ${maskedValue}`,
+  };
+}
+
+function verifySetup(): VerificationResult {
+  const checks: CheckResult[] = [];
+  const qstashRegion = process.env.QSTASH_REGION;
+  const normalizedRegion = normalizeRegion(qstashRegion);
+
+  // Determine mode
+  const mode = normalizedRegion ? "multi-region" : "single-region";
+  const primaryRegion = normalizedRegion;
+
+  printHeader("QStash Environment Verification");
+
+  // Check mode
+  if (mode === "multi-region" && primaryRegion) {
+    console.log(colorize("bright", `\nMode: `) + colorize("green", "Multi-Region"));
+    console.log(colorize("bright", `Primary Region: `) + colorize("green", primaryRegion));
+  } else {
+    console.log(colorize("bright", `\nMode: `) + colorize("blue", "Single-Region (Default)"));
+    if (qstashRegion && !normalizedRegion) {
+      checks.push({
+        status: "error",
+        message: `Invalid QSTASH_REGION="${qstashRegion}". Valid values: ${VALID_REGIONS.join(", ")}`,
+      });
+    }
+  }
+
+  let outgoingUrl: string | undefined;
+  let outgoingToken: string | undefined;
+  let outgoingSource: string;
+
+  if (mode === "multi-region" && primaryRegion) {
+    // Multi-region mode
+    const regionUrl = process.env[`${primaryRegion}_QSTASH_URL`];
+    const regionToken = process.env[`${primaryRegion}_QSTASH_TOKEN`];
+
+    if (regionUrl && regionToken) {
+      outgoingUrl = regionUrl;
+      outgoingToken = regionToken;
+      outgoingSource = `${primaryRegion}_QSTASH_*`;
+
+      checks.push(
+        {
+          status: "success",
+          message: `Using ${primaryRegion} credentials`,
+        },
+        checkEnvironmentVariable(`${primaryRegion}_QSTASH_URL`, true),
+        checkEnvironmentVariable(`${primaryRegion}_QSTASH_TOKEN`, true)
+      );
+    } else {
+      // In multi-region mode, missing region-specific credentials is an error
+      checks.push({
+        status: "error",
+        message: `${primaryRegion} credentials required in multi-region mode`,
+      });
+
+      if (!regionUrl) {
+        checks.push(checkEnvironmentVariable(`${primaryRegion}_QSTASH_URL`, true));
+      }
+      if (!regionToken) {
+        checks.push(checkEnvironmentVariable(`${primaryRegion}_QSTASH_TOKEN`, true));
+      }
+
+      // Still set fallback values for summary display
+      outgoingUrl = process.env.QSTASH_URL ?? DEFAULT_QSTASH_URL;
+      outgoingToken = process.env.QSTASH_TOKEN;
+      outgoingSource = "QSTASH_* (fallback - ERROR)";
+    }
+  } else {
+    // Single-region mode
+    outgoingUrl = process.env.QSTASH_URL ?? DEFAULT_QSTASH_URL;
+    outgoingToken = process.env.QSTASH_TOKEN;
+    outgoingSource = "QSTASH_*";
+
+    checks.push(
+      checkEnvironmentVariable("QSTASH_URL", false),
+      checkEnvironmentVariable("QSTASH_TOKEN", true)
+    );
+  }
+
+  let currentKey: string | undefined;
+  let nextKey: string | undefined;
+  let incomingSource: string;
+
+  if (mode === "multi-region" && primaryRegion) {
+    // In multi-region mode, check for region-specific keys
+    const usCurrentKey = process.env.US_EAST_1_QSTASH_CURRENT_SIGNING_KEY;
+    const usNextKey = process.env.US_EAST_1_QSTASH_NEXT_SIGNING_KEY;
+    const euCurrentKey = process.env.EU_CENTRAL_1_QSTASH_CURRENT_SIGNING_KEY;
+    const euNextKey = process.env.EU_CENTRAL_1_QSTASH_NEXT_SIGNING_KEY;
+
+    const hasUsKeys = usCurrentKey && usNextKey;
+    const hasEuKeys = euCurrentKey && euNextKey;
+
+    if (hasUsKeys && hasEuKeys) {
+      checks.push(
+        {
+          status: "success",
+          message: "Region-specific signing keys configured for both US and EU",
+        },
+        checkEnvironmentVariable("US_EAST_1_QSTASH_CURRENT_SIGNING_KEY", false),
+        checkEnvironmentVariable("US_EAST_1_QSTASH_NEXT_SIGNING_KEY", false),
+        checkEnvironmentVariable("EU_CENTRAL_1_QSTASH_CURRENT_SIGNING_KEY", false),
+        checkEnvironmentVariable("EU_CENTRAL_1_QSTASH_NEXT_SIGNING_KEY", false)
+      );
+
+      currentKey = primaryRegion === "US_EAST_1" ? usCurrentKey : euCurrentKey;
+      nextKey = primaryRegion === "US_EAST_1" ? usNextKey : euNextKey;
+      incomingSource = "Region-specific keys";
+    } else if (hasUsKeys) {
+      checks.push(
+        {
+          status: "warning",
+          message: "Only US region signing keys configured",
+        },
+        checkEnvironmentVariable("US_EAST_1_QSTASH_CURRENT_SIGNING_KEY", false),
+        checkEnvironmentVariable("US_EAST_1_QSTASH_NEXT_SIGNING_KEY", false),
+        {
+          status: "warning",
+          message: "EU signing keys not configured - EU messages will attempt to use keys",
+        }
+      );
+
+      currentKey = usCurrentKey;
+      nextKey = usNextKey;
+      incomingSource = "US-specific keys";
+    } else if (hasEuKeys) {
+      checks.push(
+        {
+          status: "warning",
+          message: "Only EU region signing keys configured",
+        },
+        checkEnvironmentVariable("EU_CENTRAL_1_QSTASH_CURRENT_SIGNING_KEY", false),
+        checkEnvironmentVariable("EU_CENTRAL_1_QSTASH_NEXT_SIGNING_KEY", false),
+        {
+          status: "warning",
+          message: "US signing keys not configured - US messages will attempt to use default keys",
+        }
+      );
+
+      currentKey = euCurrentKey;
+      nextKey = euNextKey;
+      incomingSource = "EU-specific keys";
+    } else {
+      checks.push({
+        status: "warning",
+        message: "No region-specific signing keys found, using default keys",
+      });
+
+      currentKey = process.env.QSTASH_CURRENT_SIGNING_KEY;
+      nextKey = process.env.QSTASH_NEXT_SIGNING_KEY;
+      incomingSource = "QSTASH_* (default)";
+
+      checks.push(
+        checkEnvironmentVariable("QSTASH_CURRENT_SIGNING_KEY", false),
+        checkEnvironmentVariable("QSTASH_NEXT_SIGNING_KEY", false)
+      );
+    }
+  } else {
+    // Single-region mode
+    currentKey = process.env.QSTASH_CURRENT_SIGNING_KEY;
+    nextKey = process.env.QSTASH_NEXT_SIGNING_KEY;
+    incomingSource = "QSTASH_*";
+
+    checks.push(
+      checkEnvironmentVariable("QSTASH_CURRENT_SIGNING_KEY", false),
+      checkEnvironmentVariable("QSTASH_NEXT_SIGNING_KEY", false)
+    );
+
+    if (!currentKey && !nextKey) {
+      checks.push({
+        status: "warning",
+        message:
+          "Signing keys not set - incoming message verification will fail if verifier is used",
+      });
+    }
+  }
+
+  return {
+    mode,
+    primaryRegion,
+    checks,
+    outgoingConfig: {
+      url: outgoingUrl,
+      token: outgoingToken,
+      source: outgoingSource,
+    },
+    incomingConfig: {
+      currentKey,
+      nextKey,
+      source: incomingSource,
+    },
+  };
+}
+
+function printSummary(result: VerificationResult): void {
+  console.log(colorize("bright", "\nOutgoing Messages:"));
+  console.log(`  URL: ${result.outgoingConfig.url ?? "not set"}`);
+  console.log(`  Token: ${result.outgoingConfig.token ? "✓ configured" : "✗ not set"}`);
+  console.log(`  Source: ${result.outgoingConfig.source}`);
+
+  console.log(colorize("bright", "\nIncoming Messages:"));
+  console.log(`  Current Key: ${result.incomingConfig.currentKey ? "✓ configured" : "✗ not set"}`);
+  console.log(`  Next Key: ${result.incomingConfig.nextKey ? "✓ configured" : "✗ not set"}`);
+  console.log(`  Source: ${result.incomingConfig.source}`);
+
+  printHeader("Verification Results");
+
+  const errors = result.checks.filter((c) => c.status === "error");
+  const warnings = result.checks.filter((c) => c.status === "warning");
+  const successes = result.checks.filter((c) => c.status === "success");
+
+  for (const element of result.checks) {
+    printCheck(element);
+  }
+
+  console.log(
+    `\n${colorize("bright", "Summary:")} ${colorize("green", `${successes.length} passed`)}, ${colorize("yellow", `${warnings.length} warnings`)}, ${colorize("red", `${errors.length} errors`)}`
+  );
+
+  if (errors.length > 0) {
+    console.log(
+      colorize("red", "\n✗ Configuration has errors. Please fix them before using QStash.")
+    );
+    process.exit(1);
+  } else if (warnings.length > 0) {
+    console.log(
+      colorize("yellow", "\n⚠ Configuration has warnings. Review them to ensure proper setup.")
+    );
+  } else {
+    console.log(colorize("green", "\n✓ Configuration looks good!"));
+  }
+
+  // Provide recommendations
+  if (result.mode === "multi-region") {
+    printHeader("Multi-Region Recommendations");
+
+    console.log("For optimal multi-region operation:");
+    console.log("1. Configure region-specific signing keys for both US and EU");
+    console.log("2. Always pass the 'upstashRegion' parameter in receiver.verify()");
+    console.log("3. Monitor SDK warnings in your application logs");
+    console.log("4. Test message delivery from both regions");
+
+    console.log(colorize("cyan", "\nExample verification code:"));
+    console.log(`
+  await receiver.verify({
+    signature: request.headers.get("upstash-signature")!,
+    body: await request.text(),
+    upstashRegion: request.headers.get("upstash-region") ?? undefined,
+  });
+    `);
+  } else {
+    printHeader("Recommendations");
+
+    if (!result.incomingConfig.currentKey || !result.incomingConfig.nextKey) {
+      console.log("Consider adding signing keys for incoming message verification:");
+      console.log("  QSTASH_CURRENT_SIGNING_KEY=your_current_key");
+      console.log("  QSTASH_NEXT_SIGNING_KEY=your_next_key");
+      console.log("\nGet keys from: https://console.upstash.com/qstash");
+    }
+
+    if (!process.env.QSTASH_URL) {
+      console.log("\nUsing default EU region. To specify a custom URL:");
+      console.log("  QSTASH_URL=https://qstash.upstash.io");
+    }
+  }
+  console.log("  Multi-Region: skills/advanced/multi-region.md");
+  console.log("  Verification: skills/verification/receiver.md");
+  console.log("");
+}
+
+// Main execution
+try {
+  const result = verifySetup();
+  printSummary(result);
+} catch (error) {
+  console.error(colorize("red", "\nError running verification:"), error);
+  process.exit(1);
+}

package/.agents/skills/upstash/upstash-qstash-js/fundamentals/local-development.md

@@ -0,0 +1,106 @@
+# Local Development
+
+Use the QStash dev server to test publishing and signature verification end-to-end on your machine — no public tunnel, no real QStash account, no real signing keys.
+
+## Automatic dev server (recommended)
+
+Pass `devMode: true` to the `Client` (and the matching verifier). The SDK will download the QStash CLI binary, start it, and wire credentials for you.
+
+```typescript
+import { Client } from "@upstash/qstash";
+
+const client = new Client({ devMode: true });
+
+await client.publishJSON({
+  url: "https://example.com/webhook",
+  body: { hello: "world" },
+});
+```
+
+When `devMode` is on:
+
+- The SDK downloads the latest `qstash` binary on first use, caches it under the OS cache directory, and reuses it across projects.
+- Spawns the dev server on port `8080` (override via `QSTASH_DEV_PORT`).
+- Reuses an already-running server on the configured port instead of spawning a duplicate.
+- Injects deterministic dev `baseUrl`, `token`, and signing keys. **Any explicit `token` / `baseUrl` / signing keys you pass are ignored** (a warning is printed). To use real credentials, set `devMode: false`.
+- Forwards dev server logs to stdout/stderr with a dim `[QStash CLI]` prefix.
+- No-ops in production (`NODE_ENV=production`), during `next build`, and in browser/edge runtimes.
+
+### Environment variable
+
+Instead of hard-coding `devMode: true`, leave the option unset and toggle via env:
+
+```bash
+QSTASH_DEV=true       # or "1"
+QSTASH_DEV_PORT=8080  # optional, default 8080
+```
+
+The resolution order is: explicit `devMode` boolean > `QSTASH_DEV` env var > off. Use this so production code never accidentally turns the dev server on.
+
+### Verifying signatures in dev
+
+The receiving side also needs `devMode: true` so it verifies against the dev server's deterministic signing keys instead of your real ones.
+
+```typescript
+import { Receiver } from "@upstash/qstash";
+
+const receiver = new Receiver({ devMode: true });
+
+await receiver.verify({
+  signature: request.headers.get("upstash-signature")!,
+  body: await request.text(),
+});
+```
+
+For Next.js, the wrappers accept the same flag:
+
+```typescript
+// app/api/webhook/route.ts
+import { verifySignatureAppRouter } from "@upstash/qstash/nextjs";
+
+export const POST = verifySignatureAppRouter(
+  async (request) => new Response("ok"),
+  { devMode: true }
+);
+```
+
+### Next.js: starting the server before edge routes
+
+Edge runtimes cannot spawn child processes. If a route in the Edge Runtime is the first thing to use QStash, the SDK can only check whether the server is reachable — it cannot start it. Call `registerQStashDev()` from `instrumentation.ts` to spawn the server during Next.js startup, before any request hits:
+
+```typescript
+// instrumentation.ts
+import { registerQStashDev } from "@upstash/qstash/nextjs";
+
+export function register() {
+  registerQStashDev();
+}
+```
+
+`registerQStashDev` is itself a no-op in production and during `next build`.
+
+### Common pitfalls
+
+- **Passing `token` alongside `devMode: true`** — the explicit token is ignored and you get a console warning. Drop the `token` field, or set `devMode: false` to use it.
+- **Hitting build-time errors in `next build`** — if a route module is evaluated at build time and instantiates the `Client`, mark the route `export const dynamic = "force-dynamic"` so it isn't pre-rendered.
+- **Port 8080 already in use** — the SDK errors with a clear message; either stop the other process or set `QSTASH_DEV_PORT` to a free port (matched on both client and receiver sides).
+- **Calling QStash from an edge route without `instrumentation.ts`** — the edge runtime can't spawn the binary. Either move the call to a Node-runtime route or wire `registerQStashDev()` as shown above.
+
+## Manual dev server
+
+If you cannot use the automatic flow (non-Node runtime, CI without internet, custom binary), run the CLI yourself:
+
+```bash
+npx @upstash/qstash-cli dev
+```
+
+Then construct the client with the printed dev credentials explicitly and **leave `devMode` unset/false**:
+
+```typescript
+const client = new Client({
+  baseUrl: "http://127.0.0.1:8080",
+  token: "eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0=",
+});
+```
+
+See the [Local Development docs](https://upstash.com/docs/qstash/howto/local-development) for the full list of test users and CLI options.

package/.agents/skills/upstash/upstash-qstash-js/fundamentals/publishing-messages.md

@@ -0,0 +1,144 @@
+# Publishing Messages
+
+Publish HTTP messages to destinations using the QStash SDK. Messages are delivered asynchronously with built-in retries and monitoring.
+
+## Basic Publishing
+
+### publishJSON()
+
+```typescript
+import { Client } from "@upstash/qstash";
+
+const client = new Client({ token: process.env.QSTASH_TOKEN! });
+
+const result = await client.publishJSON({
+  url: "https://api.example.com/webhook",
+  body: { userId: "123", event: "order.completed" },
+});
+
+console.log(result.messageId); // "msg_123..."
+```
+
+## Destination Options
+
+Specify where to send the message using one of these mutually exclusive options:
+
+```typescript
+await client.publishJSON({
+  // Send to a single HTTP endpoint:
+  url: "https://api.example.com/webhook",
+  // Send to all endpoints in a URL group. Creates one message per endpoint:
+  // Learn more in [URL Groups](url-groups.md).
+  urlGroup: "my-api-group",
+  // ...
+});
+```
+
+## Message Options
+
+```typescript
+// JSON object
+await client.publishJSON({
+  url: "https://api.example.com/webhook",
+  // The message payload
+  body: { order_id: "123", items: [1, 2, 3] },
+  // Send to a FIFO queue for ordered processing:
+  // Learn more in [Queues and Flow Control](queues-and-flow-control.md).
+  queueName: "my-fifo-queue",
+  // Send with a flow control key to limit rate/parallelism:
+  flowControl: {
+    key: "user-123",
+    parallelism: 2,
+    rate: 10,
+    period: 60,
+  },
+  // request headers
+  headers: {
+    "Content-Type": "application/json",
+    "X-Custom-Header": "value",
+    Authorization: "Bearer token", // auth token for the destination
+  },
+  // request method
+  method: "PUT",
+  // Delay message delivery by a duration in seconds:
+  delay: 60,
+  // alternative of delay, deliver at a specific Unix timestamp in seconds:
+  notBefore: 1700000000,
+  // retries
+  retries: 10,
+  // Customize the delay between retries using a mathematical expression.
+  // Default is exponential backoff.
+  // Supported functions: `pow`, `sqrt`, `abs`, `exp`, `floor`, `ceil`, `round`, `min`, `max`.
+  retryDelay: "5000",
+  // Maximum duration for the HTTP request in seconds:
+  timeout: 15,
+  // URL called if the message is successfully delivered:
+  callback: "https://api.example.com/qstash-callback",
+  // URL called only when all retries are exhausted:
+  failureCallback: "https://api.example.com/failure-handler",
+  // id for deduplicating messages
+  deduplicationId: "custom-id-123",
+  // enable content-based deduplication
+  contentBasedDeduplication: true,
+  // label for filtering logs, dlq, cancellation
+  label: "order-webhook",
+});
+```
+
+## Batch Publishing
+
+Publish multiple messages in a single request:
+
+```typescript
+const results = await client.batchJSON([
+  {
+    url: "https://api.example.com/webhook-1",
+    body: { event: "first" },
+  },
+  {
+    url: "https://api.example.com/webhook-2",
+    body: { event: "second" },
+    delay: 60,
+  },
+  {
+    urlGroup: "my-group",
+    body: { event: "third" },
+  },
+]);
+```
+
+Each message in the batch can have different options.
+
+## Response Types
+
+### Single URL
+
+When publishing to a `url`, response contains:
+
+```typescript
+{
+  messageId: string;    // Unique message identifier
+  url: string;          // Destination URL
+  deduplicated?: boolean; // true if message was deduplicated
+}
+```
+
+### URL Group
+
+When publishing to a `urlGroup`, response contains an array:
+
+```typescript
+[
+  {
+    messageId: string;
+    url: string;          // First endpoint URL
+    deduplicated?: boolean;
+  },
+  {
+    messageId: string;
+    url: string;          // Second endpoint URL
+    deduplicated?: boolean;
+  },
+  // ... one per endpoint
+]
+```