zilmate 1.8.1 → 1.9.1

package/.agents/skills/upstash-ratelimit-js/traffic-protection.md

@@ -0,0 +1,77 @@
+# Traffic Protection
+
+This skill documents how to use deny lists and automatic IP protection in the Upstash Ratelimit TypeScript SDK. It explains configuration, behavior, caching, update patterns, and common pitfalls.
+
+---
+
+## Deny Lists
+
+Deny lists block requests based on IP, user agent, country, or identifier. Enable protection by setting `enableProtection: true` when creating your Ratelimit client.
+
+Example usage:
+
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+  enableProtection: true,
+  analytics: true,
+});
+
+const result = await ratelimit.limit("userId", {
+  ip: "203.0.113.5",
+  userAgent: "malicious-bot",
+  country: "CN",
+});
+
+await result.pending; // analytics sync
+
+if (!result.success && result.reason === "denyList") {
+  console.log("Blocked value:", result.deniedValue);
+}
+```
+
+### Behavior & Pitfalls
+
+- Exact match only; pattern matching is **not supported**.
+- Denied values are cached for 1 minute to reduce Redis load. Removal from the deny list may take up to a minute to propagate.
+- Adding a value propagates instantly.
+- Dashboard manages all deny list entries; analytics can show aggregated blocks.
+
+---
+
+## Auto IP Deny List
+
+Automatically blocks IPs aggregated from >30 open‑source abuse lists (via GitHub's *ipsum* repository). Updates occur daily at **2 AM UTC**.
+
+Enable protection:
+
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+  enableProtection: true,
+});
+
+const { success, pending } = await ratelimit.limit("userId", { ip: "203.0.113.77" });
+await pending; // ensures async sync completion
+```
+
+### Update Flow
+
+- First call to `limit` after 2 AM UTC triggers asynchronous list refresh.
+- Request results are returned immediately; updates complete in the background.
+- Use the `pending` promise when accuracy depends on the sync.
+
+### Dashboard Integration
+
+- All auto‑blocked IPs appear in the "Denied" section.
+- Feature can be disabled from the Upstash Console without disabling standard deny lists.
+
+---
+
+## Common Mistakes
+
+- Forgetting to pass `ip`, `userAgent`, or `country` to `limit` → protection does not apply.
+- Expecting pattern or CIDR matches; only exact strings are checked.
+- Confusing auto IP deny list with manual deny list entries; both operate independently.

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

@@ -0,0 +1,188 @@
+---
+name: upstash-redis-js
+description: Work with the Upstash Redis TypeScript/JavaScript SDK for serverless Redis operations. Use for caching, session storage, rate limiting, leaderboards, full-text search (querying, filtering, aggregating) with Upstash Redis Search (different from regular FT.SEARCH), and all Redis data structures. Supports automatic serialization/deserialization of JavaScript types. Upstash Redis Search also available via @upstash/search-redis and @upstash/search-ioredis adapters for TCP clients.
+---
+
+# Upstash Redis SDK - Complete Skills Guide
+
+This directory contains comprehensive guides for using the `@upstash/redis` SDK. These skill files are designed to help developers and AI assistants understand and use the SDK effectively.
+
+## Installation
+
+```bash
+npm install @upstash/redis
+```
+
+## Quick Start
+
+### Basic Initialization
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+// Initialize with explicit credentials
+const redis = new Redis({
+  url: "UPSTASH_REDIS_REST_URL",
+  token: "UPSTASH_REDIS_REST_TOKEN",
+});
+
+// Or initialize from environment variables
+const redis = Redis.fromEnv();
+```
+
+### Environment Variables
+
+Set these in your `.env` file:
+
+```bash
+UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
+UPSTASH_REDIS_REST_TOKEN=your-token-here
+```
+
+> **No credentials yet?** If you're an agent that needs scratch Redis and the user hasn't provided a database, you can mint a temporary one with a single POST to `https://upstash.com/start-redis` (3-day TTL, no signup).
+
+## Skill Files Overview
+
+### Data Structures (data-structures/)
+
+Redis data types with auto-serialization examples:
+
+- **strings.md** - GET, SET, INCR, DECR, APPEND with automatic type handling
+- **hashes.md** - HSET, HGET, HMGET with object serialization
+- **lists.md** - LPUSH, RPUSH, LRANGE with array handling
+- **sets.md** - SADD, SMEMBERS, set operations
+- **sorted-sets.md** - ZADD, ZRANGE, ZRANK, leaderboard patterns
+- **json.md** - JSON.SET, JSON.GET, JSONPath queries for nested objects
+- **streams.md** - XADD, XREAD, XGROUP, consumer groups
+
+### Advanced Features (advanced-features/)
+
+Complex operations and optimizations:
+
+- **auto-pipeline.md** - Automatic request batching, performance optimization
+- **pipeline-and-transactions.md** - Manual pipelines, MULTI/EXEC for atomic operations
+- **scripting.md** - Lua scripts, EVAL, EVALSHA for server-side logic
+
+### Patterns (patterns/)
+
+Common use cases and architectural patterns:
+
+- **caching.md** - Cache-aside, write-through, TTL strategies
+- **rate-limiting.md** - Integration with @upstash/ratelimit package
+- **session-management.md** - Session storage and user state management
+- **distributed-locks.md** - Lock implementations, deadlock prevention
+- **leaderboard.md** - Sorted set leaderboards, real-time rankings
+
+### Performance (performance/)
+
+Optimization techniques and best practices:
+
+- **batching-operations.md** - MGET, MSET, batch operations
+- **pipeline-optimization.md** - When to use pipelines, performance tips
+- **ttl-expiration.md** - Key expiration strategies, memory management
+- **data-serialization.md** - Deep dive into auto serialization, custom serializers, edge cases
+- **error-handling.md** - Error types, retry strategies, timeout handling, debugging tips
+- **redis-replicas.md** - Global database setup, read replicas, read-your-writes consistency
+
+### Search (search/)
+
+Full-text search, filtering, and aggregation extension for Redis:
+
+- **overview.md** - Schema definition, field types, pitfalls, package overview
+- **commands/querying.md** - Query and count with filters, pagination, sorting, highlighting
+- **commands/aggregating.md** - Metric aggregations ($avg, $sum, $stats), bucket aggregations ($terms, $range, $histogram, $facet)
+- **commands/index-management.md** - Create, describe, drop indexes, waitIndexing
+- **commands/aliases.md** - Index aliases for zero-downtime reindexing
+- **adapters.md** - Using search with node-redis and ioredis via @upstash/search-redis and @upstash/search-ioredis
+
+### Migrations (migrations/)
+
+Migration guides from other libraries:
+
+- **from-ioredis.md** - Migration from ioredis, key differences, serialization changes
+- **from-redis-node.md** - Migration from node-redis, API differences
+
+## Common Mistakes (Especially for LLMs)
+
+### ❌ Mistake 1: Treating Everything as Strings
+
+```typescript
+// ❌ WRONG - Don't do this with @upstash/redis
+await redis.set("count", "42"); // Stored as string "42"
+const count = await redis.get("count");
+const incremented = parseInt(count) + 1; // Manual parsing needed
+
+// ✅ CORRECT - Let the SDK handle it
+await redis.set("count", 42); // Stored as number
+const count = await redis.get("count");
+const incremented = count + 1; // Just use it
+```
+
+### ❌ Mistake 2: Manual JSON Serialization
+
+```typescript
+// ❌ WRONG - Unnecessary with @upstash/redis
+await redis.set("user", JSON.stringify({ name: "Alice" }));
+const user = JSON.parse(await redis.get("user"));
+
+// ✅ CORRECT - Automatic handling
+await redis.set("user", { name: "Alice" });
+const user = await redis.get("user");
+```
+
+## Quick Command Reference
+
+```typescript
+// Strings
+await redis.set("key", "value");
+await redis.get("key");
+await redis.incr("counter");
+await redis.decr("counter");
+
+// Hashes
+await redis.hset("user:1", { name: "Alice", age: 30 });
+await redis.hget("user:1", "name");
+await redis.hgetall("user:1");
+
+// Lists
+await redis.lpush("tasks", "task1", "task2");
+await redis.rpush("tasks", "task3");
+await redis.lrange("tasks", 0, -1);
+
+// Sets
+await redis.sadd("tags", "javascript", "redis");
+await redis.smembers("tags");
+
+// Sorted Sets
+await redis.zadd("leaderboard", { score: 100, member: "player1" });
+await redis.zrange("leaderboard", 0, -1);
+
+// JSON
+await redis.json.set("user:1", "$", { name: "Alice", address: { city: "NYC" } });
+await redis.json.get("user:1");
+
+// Expiration
+await redis.setex("session", 3600, { userId: "123" });
+await redis.expire("key", 60);
+await redis.ttl("key");
+```
+
+## Best Practices
+
+1. **Use environment variables** for credentials, never hardcode
+2. **Leverage auto-serialization** - pass native JavaScript types
+3. **Use TypeScript types** for better type safety
+4. **Set appropriate TTLs** to manage memory
+5. **Use pipelines** for multiple operations
+6. **Namespace your keys** (e.g., `user:123`, `session:abc`)
+
+## Resources
+
+- [Official Documentation](https://upstash.com/docs/redis)
+- [GitHub Repository](https://github.com/upstash/redis-js)
+- [API Reference](https://upstash.com/docs/redis/sdks/ts/overview)
+- [Examples](https://github.com/upstash/redis-js/tree/main/examples)
+
+## Getting Help
+
+For detailed information on specific topics, refer to the individual skill files in the `skills/` directory. Each file contains comprehensive examples, use cases, and best practices for its topic.

package/.agents/skills/upstash-redis-js/advanced-features/auto-pipeline.md

@@ -0,0 +1,49 @@
+# Automatic Pipelining
+
+## Overview
+
+Automatic pipelining batches multiple Redis commands into a single HTTP request, reducing round-trip latency for independent operations.
+
+It's enabled by default. Use `enableAutoPipelining: false` to disable automatic pipelining.
+
+## Good For
+
+- Multiple independent GET/SET operations
+- Batch reads across different keys
+- Reducing latency in high-latency networks
+- Serverless environments with cold starts
+
+## Limitations
+
+- Only works with independent commands (no command depends on another's result)
+- Not beneficial for single commands
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+});
+
+// Without auto-pipeline: 3 separate HTTP requests
+// With auto-pipeline: 1 HTTP request containing all 3 commands
+const [user, posts, comments] = await Promise.all([
+  redis.get("user:1"),
+  redis.get("posts:1"),
+  redis.get("comments:1"),
+]);
+
+// Auto-pipeline batches these independent operations
+async function fetchUserData(userId: string) {
+  const [profile, settings, activity] = await Promise.all([
+    redis.hgetall(`user:${userId}:profile`),
+    redis.hgetall(`user:${userId}:settings`),
+    redis.zrange(`user:${userId}:activity`, 0, 9),
+  ]);
+
+  return { profile, settings, activity };
+}
+```

package/.agents/skills/upstash-redis-js/advanced-features/pipeline-and-transactions.md

@@ -0,0 +1,42 @@
+# Pipelines and Transactions
+
+## Overview
+
+**Pipelines** batch multiple commands for efficiency. **Transactions** (MULTI/EXEC) execute commands atomically.
+
+## Good For
+
+- **Pipelines**: Reducing round trips for independent operations
+- **Transactions**: Atomic operations that must succeed or fail together
+
+## Limitations
+
+- Pipeline commands execute independently (no atomicity)
+- No WATCH / optimistic locking over the REST client — use a Lua script (`redis.eval`) for atomic check-and-set
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Manual Pipeline - batch operations for efficiency
+const pipeline = redis.pipeline();
+pipeline.set("user:1:name", "Alice");
+pipeline.set("user:1:email", "alice@example.com");
+pipeline.incr("user:count");
+pipeline.lpush("recent:users", "user:1");
+
+const results = await pipeline.exec();
+// Returns array of results: [OK, OK, 1, 1]
+
+// Transaction (MULTI/EXEC) - atomic operations
+const tx = redis.multi();
+tx.decrby("inventory:item:1", 5); // Deduct inventory
+tx.incrby("user:123:purchases", 5); // Add to user purchases
+tx.lpush("orders", JSON.stringify({ userId: 123, itemId: 1, qty: 5 }));
+
+const txResults = await tx.exec();
+// All commands succeed together or all fail
+```

package/.agents/skills/upstash-redis-js/advanced-features/scripting.md

@@ -0,0 +1,124 @@
+# Lua Scripting
+
+## Overview
+
+Execute Lua scripts atomically on Redis server. Scripts run as a single atomic operation with access to all Redis commands.
+
+## Good For
+
+- Complex atomic operations
+- Conditional logic on the server
+- Reducing round trips for multi-step operations
+
+## Limitations
+
+- Blocks other operations while executing
+- Scripts should be fast (avoid heavy computation)
+- Debugging can be challenging
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Simple script: conditional increment
+const script = `
+  local current = redis.call('GET', KEYS[1])
+  if current and tonumber(current) < tonumber(ARGV[1]) then
+    return redis.call('INCR', KEYS[1])
+  end
+  return current
+`;
+
+const result = await redis.eval(script, ["counter"], [100]);
+// Increments only if current value < 100
+
+// Atomic rate limiter
+const rateLimitScript = `
+  local key = KEYS[1]
+  local limit = tonumber(ARGV[1])
+  local window = tonumber(ARGV[2])
+  
+  local current = redis.call('INCR', key)
+  
+  if current == 1 then
+    redis.call('EXPIRE', key, window)
+  end
+  
+  if current > limit then
+    return 0
+  end
+  
+  return 1
+`;
+
+const allowed = await redis.eval<number>(
+  rateLimitScript,
+  ["ratelimit:user:123"],
+  [10, 60] // 10 requests per 60 seconds
+);
+
+if (allowed === 1) {
+  console.log("Request allowed");
+} else {
+  console.log("Rate limit exceeded");
+}
+
+// Script with multiple operations
+const purchaseScript = `
+  local inventory = KEYS[1]
+  local userBalance = KEYS[2]
+  local qty = tonumber(ARGV[1])
+  local price = tonumber(ARGV[2])
+  
+  local stock = tonumber(redis.call('GET', inventory) or 0)
+  local balance = tonumber(redis.call('GET', userBalance) or 0)
+  
+  local cost = qty * price
+  
+  if stock < qty then
+    return {err = "insufficient_stock"}
+  end
+  
+  if balance < cost then
+    return {err = "insufficient_balance"}
+  end
+  
+  redis.call('DECRBY', inventory, qty)
+  redis.call('DECRBY', userBalance, cost)
+  
+  return {ok = "success"}
+`;
+
+const purchase = await redis.eval<{ err?: string; ok?: string }>(
+  purchaseScript,
+  ["inventory:item:1", "balance:user:123"],
+  [5, 20] // Buy 5 items at 20 each
+);
+
+// Cache script with EVALSHA for better performance
+const scriptSha = await redis.scriptLoad(rateLimitScript);
+
+// Use cached script (faster)
+const allowed2 = await redis.evalsha<number>(scriptSha, ["ratelimit:user:456"], [10, 60]);
+
+// Conditional update script
+const setIfHigherScript = `
+  local key = KEYS[1]
+  local newValue = tonumber(ARGV[1])
+  local current = tonumber(redis.call('GET', key) or 0)
+  
+  if newValue > current then
+    redis.call('SET', key, newValue)
+    return 1
+  end
+  
+  return 0
+`;
+
+const updated = await redis.eval<number>(setIfHigherScript, ["high_score:user:123"], [1500]);
+
+console.log(updated === 1 ? "New high score!" : "Score not higher");
+```

package/.agents/skills/upstash-redis-js/data-structures/hashes.md

@@ -0,0 +1,71 @@
+# Hashes
+
+## Overview
+
+Hashes store field-value pairs under a single key. They're optimized for storing objects with multiple attributes.
+
+## Good For
+
+- User profiles
+- Product details
+- Configuration settings
+- Any structured data with named fields
+
+## Limitations
+
+- For nested objects, use JSON data type instead
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+await redis.hset("user:1", {
+  name: "Alice",
+  email: "alice@example.com",
+  age: 30,
+});
+
+// Get single field
+const name = await redis.hget("user:1", "name"); // "Alice"
+
+// Get multiple fields
+const fields = await redis.hmget("user:1", "name", "email"); // ["Alice", "alice@example.com"]
+
+// Get all fields and values
+const user = await redis.hgetall("user:1");
+// { name: "Alice", email: "alice@example.com", age: 30 }
+
+// Get all field names
+const fieldNames = await redis.hkeys("user:1"); // ["name", "email", "age"]
+
+// Get all values
+const values = await redis.hvals("user:1"); // ["Alice", "alice@example.com", 30]
+
+// Check if field exists
+const hasEmail = await redis.hexists("user:1", "email"); // 1 if exists, 0 if not
+
+// Get number of fields
+const fieldCount = await redis.hlen("user:1"); // 3
+
+// Increment numeric field
+await redis.hset("user:1", { loginCount: 0 });
+await redis.hincrby("user:1", "loginCount", 1); // 1
+await redis.hincrby("user:1", "loginCount", 5); // 6
+
+// Increment float field
+await redis.hset("user:1", { balance: 100.5 });
+await redis.hincrbyfloat("user:1", "balance", 25.75); // 126.25
+
+// Set only if field doesn't exist
+await redis.hsetnx("user:1", "verified", "true"); // Returns 1 if set, 0 if exists
+
+// Delete fields
+await redis.hdel("user:1", "age");
+await redis.hdel("user:1", "loginCount", "balance"); // Delete multiple fields
+
+// Delete entire hash
+await redis.del("user:1");
+```

package/.agents/skills/upstash-redis-js/data-structures/json.md

@@ -0,0 +1,133 @@
+# JSON
+
+## Overview
+
+JSON data type stores JSON documents with support for nested objects and arrays. It enables operations on specific paths within the document using JSONPath syntax.
+
+## Good For
+
+- Complex nested objects
+- Document storage (user profiles, product catalogs)
+- Partial updates of large objects
+- Querying nested data
+
+## Limitations
+
+- Maximum document size: 512 MB
+- JSONPath queries have performance cost on deeply nested structures
+- Some JSONPath features may not be supported
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Set entire JSON document
+await redis.json.set("user:1", "$", {
+  name: "Alice",
+  age: 30,
+  email: "alice@example.com",
+  address: {
+    city: "New York",
+    country: "USA",
+    zip: "10001",
+  },
+  hobbies: ["reading", "coding"],
+  metadata: {
+    registered: "2024-01-15",
+    verified: true,
+  },
+});
+
+// Get entire document
+const user = await redis.json.get("user:1");
+// Returns the full object
+
+// Get specific path
+const name = await redis.json.get("user:1", "$.name"); // ["Alice"]
+const city = await redis.json.get("user:1", "$.address.city"); // ["New York"]
+
+// Get multiple paths
+const details = await redis.json.get("user:1", "$.name", "$.email");
+// { "$.name": ["Alice"], "$.email": ["alice@example.com"] }
+
+// Set nested field
+await redis.json.set("user:1", "$.address.city", "San Francisco");
+
+// Set multiple fields (overwrites at path)
+await redis.json.set("user:1", "$.metadata", {
+  registered: "2024-01-15",
+  verified: true,
+  lastLogin: "2024-01-23",
+});
+
+// Type-specific operations on JSON
+await redis.json.set("product:1", "$", {
+  name: "Laptop",
+  price: 999.99,
+  stock: 50,
+  tags: ["electronics", "computers"],
+});
+
+// Increment numeric field
+await redis.json.numincrby("product:1", "$.price", 100); // 1099.99
+await redis.json.numincrby("product:1", "$.stock", -5); // 45
+
+// String append
+await redis.json.strappend("product:1", "$.name", " Pro"); // "Laptop Pro"
+
+// Get string length
+const nameLength = await redis.json.strlen("product:1", "$.name"); // [10]
+
+// Array operations
+await redis.json.set("cart:1", "$", {
+  items: ["item1", "item2"],
+  quantities: [1, 2],
+});
+
+// Append to array
+await redis.json.arrappend("cart:1", "$.items", "item3", "item4");
+// items: ["item1", "item2", "item3", "item4"]
+
+// Insert into array at index
+await redis.json.arrinsert("cart:1", "$.items", 1, "item-new");
+// items: ["item1", "item-new", "item2", "item3", "item4"]
+
+// Get array length
+const itemCount = await redis.json.arrlen("cart:1", "$.items"); // [5]
+
+// Get element by index
+const firstItem = await redis.json.arrindex("cart:1", "$.items", "item1"); // [0]
+
+// Pop from array
+const lastItem = await redis.json.arrpop("cart:1", "$.items"); // ["item4"]
+const firstFromItems = await redis.json.arrpop("cart:1", "$.items", 0); // ["item1"]
+
+// Trim array to range
+await redis.json.arrtrim("cart:1", "$.items", 0, 1); // Keep first 2 elements
+
+// Object operations
+await redis.json.set("config:1", "$", {
+  database: { host: "localhost", port: 5432 },
+  cache: { enabled: true },
+});
+
+// Get object keys
+const dbKeys = await redis.json.objkeys("config:1", "$.database");
+// [["host", "port"]]
+
+// Get object length (number of keys)
+const dbKeyCount = await redis.json.objlen("config:1", "$.database"); // [2]
+
+// Delete path
+await redis.json.del("user:1", "$.metadata.lastLogin");
+
+// Delete entire document
+await redis.json.del("user:1");
+
+// Type checking
+await redis.json.set("data:1", "$", { str: "hello", num: 42, bool: true, arr: [1, 2] });
+const type = await redis.json.type("data:1", "$.num"); // ["number"]
+```