zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash-qstash-js/verification/receiver.md

@@ -0,0 +1,213 @@
+# Receiver - Message Verification
+
+## Overview
+
+The `Receiver` class verifies that incoming requests are genuinely from QStash by validating JWT signatures. This prevents unauthorized requests from reaching your endpoints.
+
+## Getting Your Signing Keys
+
+Sign in to the [Upstash Console](https://console.upstash.com/qstash) and navigate to your QStash instance to find:
+
+- **Current Signing Key**: Active key for signature verification
+- **Next Signing Key**: Key to use after rotation
+
+Store these as environment variables:
+
+```bash
+QSTASH_CURRENT_SIGNING_KEY="your_current_key"
+QSTASH_NEXT_SIGNING_KEY="your_next_key"
+```
+
+## Creating a Receiver Instance
+
+### Basic Setup
+
+```typescript
+import { Receiver } from "@upstash/qstash";
+
+const receiver = new Receiver({
+  currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY!,
+  nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY!,
+});
+```
+
+### Multi-Region Mode
+
+If you're using multi-region QStash (with `QSTASH_REGION` environment variable set), signature verification requires additional configuration. The SDK automatically detects the region from the `upstash-region` header and uses region-specific signing keys.
+
+> **Important:** Multi-region signature verification requires careful setup. See [Multi-Region Setup](../advanced/multi-region.md) for complete details on environment variables, region detection, and verification strategies.
+
+## Verifying Incoming Requests
+
+### Basic Verification
+
+```typescript
+try {
+  await receiver.verify({
+    signature: request.headers.get("upstash-signature")!,
+    body: await request.text(),
+  });
+
+  // Request is valid - process it
+  return new Response("OK", { status: 200 });
+} catch (error) {
+  // Invalid signature
+  return new Response("Unauthorized", { status: 401 });
+}
+```
+
+### With URL Verification
+
+For extra security, verify the request was sent to the correct URL:
+
+```typescript
+await receiver.verify({
+  signature: request.headers.get("upstash-signature")!,
+  body: await request.text(),
+  url: "https://my-api.example.com/webhook",
+});
+```
+
+### With Clock Tolerance
+
+Handle minor clock differences between servers:
+
+```typescript
+await receiver.verify({
+  signature: request.headers.get("upstash-signature")!,
+  body: await request.text(),
+  clockTolerance: 5, // Allow 5 seconds difference
+});
+```
+
+## Required Headers
+
+QStash sends these headers with every request:
+
+- `Upstash-Signature`: JWT signature to verify
+
+> **Note:** In multi-region mode, QStash also sends an `Upstash-Region` header. See [Multi-Region Setup](../advanced/multi-region.md) for details.
+
+## Handling Verification Failures
+
+### SignatureError
+
+The `verify()` method throws `SignatureError` for invalid signatures:
+
+```typescript
+import { Receiver, SignatureError } from "@upstash/qstash";
+
+try {
+  await receiver.verify({
+    signature: request.headers.get("upstash-signature")!,
+    body: await request.text(),
+  });
+} catch (error) {
+  if (error instanceof SignatureError) {
+    console.error("Invalid signature:", error.message);
+    return new Response("Invalid signature", { status: 401 });
+  }
+  throw error;
+}
+```
+
+### Common Failure Reasons
+
+1. **Missing or wrong signing keys**
+   - Verify keys in Upstash Console match environment variables
+2. **Body mismatch**
+
+   - Ensure you pass the raw request body (not parsed JSON)
+   - Don't modify the body before verification
+
+3. **Expired signature**
+
+   - QStash signatures expire after 5 minutes
+   - Check server clock is synchronized
+   - Use `clockTolerance` if needed
+
+4. **URL mismatch**
+   - Ensure the `url` parameter matches the destination URL
+   - Include protocol, domain, and path
+
+## Key Rotation
+
+The Receiver supports seamless key rotation:
+
+1. Verification tries `currentSigningKey` first
+2. If that fails, tries `nextSigningKey`
+3. Only throws error if both fail
+
+To rotate keys:
+
+1. Set new key as `QSTASH_NEXT_SIGNING_KEY`
+2. Wait for all in-flight requests to complete
+3. Update `QSTASH_CURRENT_SIGNING_KEY` to the new key
+4. Generate a new `QSTASH_NEXT_SIGNING_KEY`
+
+## Best Practices
+
+### Always Verify
+
+Never trust incoming requests without verification:
+
+```typescript
+// ❌ Don't do this
+app.post("/webhook", async (req) => {
+  const data = await req.json();
+  processWebhook(data); // Unverified!
+});
+
+// ✅ Do this
+app.post("/webhook", async (req) => {
+  const body = await req.text();
+
+  await receiver.verify({
+    signature: req.headers.get("upstash-signature")!,
+    body,
+  });
+
+  const data = JSON.parse(body);
+  processWebhook(data);
+});
+```
+
+### Use Environment Variables
+
+Never hardcode signing keys:
+
+```typescript
+// ❌ Don't do this
+const receiver = new Receiver({
+  currentSigningKey: "sig_abc123...",
+});
+
+// ✅ Do this
+const receiver = new Receiver({
+  currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY!,
+  nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY!,
+});
+```
+
+### Read Body Once
+
+Request bodies can only be read once. Save it for reuse:
+
+```typescript
+const body = await request.text();
+
+// Verify with raw body
+await receiver.verify({
+  signature: request.headers.get("upstash-signature")!,
+  body,
+});
+
+// Parse after verification
+const data = JSON.parse(body);
+```
+
+## Platform-Specific Verification
+
+For framework-specific implementations, see:
+
+- [Next.js Verification](platform-specific/nextjs.md)

package/.agents/skills/upstash-ratelimit-js/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: upstash-ratelimit-js
+description: Lightweight guidance for using the Upstash Redis RateLimit TypeScript/JavaScript SDK, including setup steps, basic usage, and pointers to advanced algorithm, features, pricing, and traffic‑protection docs.
+---
+
+# Rate Limit TS SDK
+
+## Quick Start
+- Install the SDK and connect to Redis.
+- Create a rate limiter and apply it to incoming operations.
+
+Example:
+```ts
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+const redis = new Redis({ url: "<url>", token: "<token>" });
+const limiter = new Ratelimit({ redis, limiter: Ratelimit.slidingWindow(5, "10s") });
+
+const { success } = await limiter.limit("user-id");
+if (!success) {
+  // throttled
+}
+```
+
+## Other Skill Files
+- **algorithms.md**: Describes all available rate‑limiting algorithms and how they behave.
+- **pricing-cost.md**: Explains pricing, Redis cost implications, and operational considerations.
+- **features.md**: Lists SDK features such as prefixes, custom keys, and behavioral options.
+- **methods-getting-started.md**: Full method reference for the SDK's API and getting started guide.
+- **traffic-protection.md**: Guidance on applying rate limiting for traffic shaping, abuse prevention, and protection patterns.

package/.agents/skills/upstash-ratelimit-js/algorithms.md

@@ -0,0 +1,84 @@
+# Ratelimiting Algorithms
+
+This documentation explains the three algorithms supported by the ratelimit‑ts SDK: Fixed Window, Sliding Window, and Token Bucket. It focuses on practical usage, pitfalls, and choosing the right algorithm.
+
+## Fixed Window
+
+Divides time into fixed periods (for example, 10‑second windows). Requests increment a counter for the current window and are rejected once the limit is exceeded.
+
+**Pitfalls**
+- Burst leakage: many requests at the boundary may bypass intended behavior.
+- Stampedes: large client populations may all retry at the start of a window.
+- Reset time is based on fixed boundaries, not on the first request.
+
+**When to use**
+- When performance and low computational cost are important.
+- When small inaccuracies at boundaries are acceptable.
+
+**Example**
+```ts
+// 10 requests per 10 seconds
+const regional = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.fixedWindow(10, "10 s"),
+});
+
+const multi = new MultiRegionRatelimit({
+  redis: [new Redis({/* auth */}), new Redis({/* auth */})],
+  limiter: MultiRegionRatelimit.fixedWindow(10, "10 s"),
+});
+```
+
+## Sliding Window
+
+Uses rolling time windows to smooth boundary behavior. Counts requests in the previous window proportionally based on elapsed time.
+
+**Pitfalls**
+- Slightly more expensive to compute and approximate.
+- Assumes uniform distribution of past requests.
+- In multi‑region mode, generates many Redis commands and can slow down operations.
+- Reset time exposed via `limit` and `getRemaining` is only the start of the next full window.
+
+**When to use**
+- When smoother behavior around window boundaries is important.
+- Avoid in multi‑region setups if command count is a concern.
+
+**Example**
+```ts
+// 10 requests per 10 seconds
+const regional = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+});
+
+// Multi-region is possible but inefficient
+const multi = new MultiRegionRatelimit({
+  redis: [new Redis({/* auth */}), new Redis({/* auth */})],
+  limiter: MultiRegionRatelimit.slidingWindow(10, "10 s"),
+});
+```
+
+## Token Bucket
+
+Maintains a bucket of tokens that refill at a defined rate. Each request consumes one token; if none remain, requests are rejected.
+
+**Advantages**
+- Smooths bursts naturally.
+- Allows high initial burst capacity (`maxTokens > refillRate`).
+
+**Pitfalls**
+- Higher computational cost.
+- Not yet supported for multi‑region.
+
+**When to use**
+- When smoothing request traffic and allowing controlled bursts is important.
+
+**Example**
+```ts
+// Bucket with max 10 tokens, refilling 5 tokens every 10s
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.tokenBucket(5, "10 s", 10),
+  analytics: true,
+});
+```

package/.agents/skills/upstash-ratelimit-js/features.md

@@ -0,0 +1,117 @@
+# Features
+
+This Skill documents the core features of the Upstash Rate Limiter for TypeScript. It highlights how to apply caching, timeouts, analytics, multiple limit strategies, dynamic limits, and multi-region setups.
+
+## Caching
+
+Caching prevents unnecessary Redis calls when identifiers are already blocked.
+
+Key points:
+- Use an in-memory `Map<string, number>` as `ephemeralCache`.
+- Default: a new `Map()` is created automatically.
+- Disable by setting `ephemeralCache: false`.
+- Works only when the cache or rate limiter is created outside serverless handlers.
+- Responses blocked by cache return `reason: cacheBlock`.
+
+Example:
+```ts
+const cache = new Map();
+const ratelimit = new Ratelimit({
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+  ephemeralCache: cache,
+});
+```
+
+## Timeout
+
+A timeout allows requests to proceed if Redis is slow or unreachable.
+- Default timeout: 5 seconds
+- On timeout success, `reason` reflects this
+
+Example:
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+  timeout: 1000,
+});
+```
+
+## Analytics & Dashboard
+
+Analytics collect counts of success/blocked requests.
+- Disabled by default; enable via `analytics: true`
+- Data is viewable in the Upstash Rate Limit Dashboard
+- In edge runtimes, ensure analytics requests complete using `pending` from `limit()`
+
+Example:
+```ts
+const { pending } = await ratelimit.limit("id");
+context.waitUntil(pending);
+```
+
+## Using Multiple Limits
+
+Different user tiers can use different limiters.
+
+Example:
+```ts
+const ratelimit = {
+  free: new Ratelimit({ prefix: "free", limiter: Ratelimit.slidingWindow(10, "10s") }),
+  paid: new Ratelimit({ prefix: "paid", limiter: Ratelimit.slidingWindow(60, "10s") }),
+};
+
+await ratelimit.free.limit(ip);
+await ratelimit.paid.limit(userId);
+```
+
+## Custom Rates
+
+Specify how many tokens to subtract per request using `rate`.
+
+Example:
+```ts
+await ratelimit.limit("identifier", { rate: batchSize });
+```
+
+## Multi Region
+
+Multi-region rate limiting provides lower latency and state replication via CRDTs.
+- Uses multiple Redis instances
+- Trades strict accuracy for global performance
+
+Example:
+```ts
+const ratelimit = new MultiRegionRatelimit({
+  redis: [redisUS, redisEU],
+  limiter: MultiRegionRatelimit.slidingWindow(10, "10 s"),
+});
+
+const { pending } = await ratelimit.limit("id");
+context.waitUntil(pending);
+```
+
+## Dynamic Limits
+
+Update rate limits at runtime without recreating the limiter.
+- Works only for single-region limiters (fixedWindow, slidingWindow, tokenBucket)
+
+Example:
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10s"),
+  dynamicLimits: true,
+});
+
+await ratelimit.setDynamicLimit({ limit: 5 });
+const current = await ratelimit.getDynamicLimit();
+await ratelimit.setDynamicLimit({ limit: false });
+```
+
+## Common Pitfalls
+
+- Forgetting to place the cache outside serverless handlers disables effective caching.
+- Not calling `context.waitUntil(pending)` in edge runtimes may cause lost analytics/sync requests.
+- Multi-region setups cannot guarantee strict limit enforcement.
+- Dynamic limits do not work with multi-region limiters.

package/.agents/skills/upstash-ratelimit-js/methods-getting-started.md

@@ -0,0 +1,77 @@
+# Upstash Ratelimit Methods (TypeScript)
+
+This document provides a focused, practical reference for all Ratelimit methods. Each section includes direct examples, usage patterns, and common pitfalls.
+
+## limit
+Primary method for checking and consuming tokens.
+
+```ts
+const { success, remaining, reset, reason, pending } = await ratelimit.limit(
+  identifier,
+  {
+    rate: 2,          // optional: consume N tokens
+    ip: req.ip,       // optional: used for deny‑list checks
+    userAgent: ua,    // optional
+    country: geo?.country,
+  }
+);
+
+if (!success) return "blocked";
+
+// In Cloudflare/Vercel Edge, flush async work
+context.waitUntil(pending);
+```
+
+Notes:
+- `rate` lets a request consume more than 1 token.
+- `reason` can be: `timeout`, `cacheBlock`, `denyList`, or undefined.
+- When analytics or MultiRegion is enabled, **always handle `pending`** in serverless environments.
+
+## blockUntilReady
+Waits for a request to become allowed instead of rejecting immediately.
+
+```ts
+const { success } = await ratelimit.blockUntilReady("id", 30_000);
+if (!success) return "still blocked after timeout";
+```
+
+## resetUsedTokens
+Clears the state for an identifier.
+
+```ts
+await ratelimit.resetUsedTokens("user123");
+```
+
+Useful when granting temporary resets or admin overrides.
+
+## getRemaining
+Read-only view of remaining quota.
+
+```ts
+const { remaining, reset } = await ratelimit.getRemaining("user123");
+```
+
+Common use cases:
+- Dashboard queries
+- Showing users their remaining quota
+
+## setDynamicLimit
+Overrides the global limit at runtime.
+
+```ts
+await ratelimit.setDynamicLimit({ limit: 5 });   // set
+await ratelimit.setDynamicLimit({ limit: false }); // remove
+```
+
+Notes:
+- Requires `dynamicLimits: true` in constructor.
+- Applies to all future rate checks.
+
+## getDynamicLimit
+Fetch the currently active dynamic limit.
+
+```ts
+const { dynamicLimit } = await ratelimit.getDynamicLimit();
+```
+
+Returns `null` when no override is active.

package/.agents/skills/upstash-ratelimit-js/pricing-cost.md

@@ -0,0 +1,146 @@
+# Pricing & Cost Considerations for Ratelimit Operations
+
+This document explains how Redis command costs vary across Ratelimit algorithms, cache states, and optional features. Use it to reason about latency, throughput, and pricing impacts when designing systems with Upstash Ratelimit.
+
+---
+
+## Overview
+
+Redis command usage depends on:
+- Algorithm type (Fixed Window, Sliding Window, Token Bucket)
+- Algorithm state for a given identifier (first request, intermediate, rate‑limited)
+- Cache hit/miss in the runtime environment
+- Optional features (deny lists, analytics, dynamic limits, multi‑region replication)
+
+A Global Upstash Redis setup multiplies write commands by `(1 + readRegionCount)` and adds 1 extra command when analytics is enabled.
+
+---
+
+## Algorithm States
+
+Each identifier (e.g., an IP or user ID) has an associated state:
+- **First**: No existing key; creates state and sets expiry
+- **Intermediate**: Key exists; normal operation
+- **Rate‑Limited**: Request blocked; may avoid Redis if cache contains an unexpired block timestamp
+
+Cache hits allow skipping Redis entirely for rate‑limited requests.
+
+---
+
+## Cache Behavior
+
+- **Hit**: Identifier found in in‑memory cache → request may be denied without Redis calls.
+- **Miss**: Cache empty or value does not indicate a block → algorithm consults Redis.
+
+Only rate‑limited results populate the cache.
+
+---
+
+## Command Costs by Operation
+
+### `limit()`
+Costs depend on algorithm, cache state, and identifier state.
+
+**Fixed Window:**
+- First: 3 commands (EVAL, INCR, PEXPIRE)
+- Intermediate: 2 commands (EVAL, INCR)
+- Rate‑limited miss: 2 commands (EVAL, INCR)
+- Rate‑limited hit: 0 commands
+
+**Sliding Window:**
+- First: 5 commands (EVAL, GET, GET, INCR, PEXPIRE)
+- Intermediate: 4 commands (EVAL, GET, GET, INCR)
+- Rate‑limited miss: 3 commands (EVAL, GET, GET)
+- Rate‑limited hit: 0 commands
+
+**Token Bucket:**
+- First/Intermediate: 4 commands (EVAL, HMGET, HSET, PEXPIRE)
+- Rate‑limited miss: 2 commands (EVAL, HMGET)
+- Rate‑limited hit: 0 commands
+
+### `getRemaining()`
+Always deterministic, no cache effects:
+- Fixed Window: 2 commands (EVAL, GET)
+- Sliding Window: 3 commands (EVAL, GET, GET)
+- Token Bucket: 2 commands (EVAL, HMGET)
+
+### `resetUsedTokens()`
+Starts with SCAN and deletes all matching keys:
+- Fixed Window: 3 commands (EVAL, SCAN, DEL)
+- Sliding Window: 4 commands (EVAL, SCAN, DEL, DEL)
+- Token Bucket: 3 commands (EVAL, SCAN, DEL)
+
+### `blockUntilReady()`
+Same cost model as `limit()`.
+
+---
+
+## Optional Features Impact
+
+### Deny List
+Adds **2 commands per `limit()` call**:
+- One `SMISMEMBER` check
+- One TTL fetch for deny list validity
+
+Auto‑IP deny list refresh uses **9 commands once per day** (first limit call after 02:00 UTC).
+
+A deny‑listed identifier is cached for a minute, skipping Redis for subsequent checks.
+
+### Analytics
+Adds **1 Redis command per `limit()`** via `ZINCRBY`.
+
+### Dynamic Limits
+Adds **1 command** to each `limit()` and `getRemaining()` call.
+- `setDynamicLimit()` = 1 command
+- `getDynamicLimit()` = 1 command
+
+### Multi‑Region
+Effective cost becomes:
+```
+(1 + readRegionCount) * writeCommandCount + readCommandCount
++1 if analytics is enabled
+```
+
+---
+
+## Example Usage
+
+```ts
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+const redis = new Redis({ url: process.env.UPSTASH_URL!, token: process.env.UPSTASH_TOKEN! });
+
+const limiter = new Ratelimit({
+  redis,
+  limiter: Ratelimit.slidingWindow(10, "60 s"),
+  analytics: true,            // adds +1 ZINCRBY per call
+  enableProtection: true,     // adds +2 per call
+  dynamicLimits: true         // adds +1 per call
+});
+
+async function handle(ip) {
+  const { success, reset } = await limiter.limit(ip);
+  if (!success) {
+    return { status: 429, retryAfter: reset - Date.now() };
+  }
+
+  const remaining = await limiter.getRemaining(ip);
+  return { status: 200, remaining };
+}
+```
+
+This example shows all cost‑impacting features enabled. Sliding Window + deny list + analytics + dynamic limits can increase the base 4–5 command cost per `limit()`.
+
+---
+
+## Common Pitfalls
+
+- **Ignoring cold starts**: Serverless environments often start with empty caches → initial calls incur higher Redis usage.
+- **Using Sliding Window when cost‑sensitive**: It requires multiple GET operations, making it the most expensive algorithm.
+- **Unexpected multi‑region amplification**: Write commands scale with region count; cost can rise significantly.
+- **Assuming deny list is free**: Even when no identifier is blocked, two extra commands execute per request.
+
+---
+
+This file provides an operational reference for estimating Redis usage and optimizing Ratelimit performance and cost.