zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash/upstash-cli/overview.md

@@ -0,0 +1,138 @@
+The Upstash CLI (`upstash`) manages Upstash services via the Upstash Developer API. All commands are non-interactive and emit JSON on stdout. Errors go to stderr as `{ "error": "..." }` with exit code `1`.
+
+## Install
+
+```bash
+npm i -g @upstash/cli
+```
+
+## Authentication
+
+Recommended: run `upstash login` once per machine. Prompts for email and a Developer API key (create one at https://console.upstash.com/account/api), verifies them, and saves to `~/.config/upstash/config.json`.
+
+```bash
+upstash login
+```
+
+Alternatives — env vars (also auto-loaded from a `.env` in cwd), or `--email` / `--api-key` inline, or `--env-path <path>` to point at a specific `.env`:
+
+```bash
+export UPSTASH_EMAIL=you@example.com
+export UPSTASH_API_KEY=your_api_key
+```
+
+Precedence: flags > env vars > `.env` > saved config. Prefer a **read-only** API key for agents when possible — mutations fail at the API, the same way they would in the console.
+
+## Resource ID flags
+
+| Flag | Products |
+|------|----------|
+| `--db-id <id>` | Redis |
+| `--index-id <id>` | Vector, Search |
+| `--qstash-id <id>` | QStash |
+| `--team-id <id>` | Team |
+
+## Redis
+
+```bash
+upstash redis list
+upstash redis get --db-id <id> [--hide-credentials]
+upstash redis create --name <name> --region <region> [--read-regions <r1> <r2>]
+upstash redis delete --db-id <id> [--dry-run]
+upstash redis rename --db-id <id> --name <new-name>
+upstash redis reset-password --db-id <id>
+upstash redis stats --db-id <id>
+
+upstash redis enable-tls --db-id <id>
+upstash redis {enable,disable}-eviction --db-id <id>
+upstash redis {enable,disable}-autoupgrade --db-id <id>
+upstash redis change-plan --db-id <id> --plan <free|payg|pro|paid>
+upstash redis update-budget --db-id <id> --budget <cents>
+upstash redis update-regions --db-id <id> --read-regions <r1> <r2>
+upstash redis move-to-team --db-id <id> --team-id <id>
+```
+
+Regions — AWS: `us-east-1`, `us-east-2`, `us-west-1`, `us-west-2`, `ca-central-1`, `eu-central-1`, `eu-west-1`, `eu-west-2`, `sa-east-1`, `ap-south-1`, `ap-northeast-1`, `ap-southeast-1`, `ap-southeast-2`, `af-south-1`. GCP: `us-central1`, `us-east4`, `europe-west1`, `asia-northeast1`.
+
+### Redis backups
+
+```bash
+upstash redis backup list --db-id <id>
+upstash redis backup create --db-id <id> --name <name>
+upstash redis backup delete --db-id <id> --backup-id <id> [--dry-run]
+upstash redis backup restore --db-id <id> --backup-id <id>
+upstash redis backup {enable,disable}-daily --db-id <id>
+```
+
+### Redis exec (REST, not the Developer API key)
+
+```bash
+upstash redis exec --db-url <url> --db-token <token> SET key value
+upstash redis exec --db-url <url> --db-token <token> --json '["SET","key","value"]'
+```
+
+`--db-url` / `--db-token` fall back to `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN`. Get both from `endpoint` and `rest_token` in `upstash redis get --db-id <id>`.
+
+## Team
+
+```bash
+upstash team list
+upstash team create --name <name> [--copy-cc]
+upstash team delete --team-id <id> [--dry-run]
+upstash team members --team-id <id>
+upstash team add-member --team-id <id> --member-email <email> --role <admin|dev|finance>
+upstash team remove-member --team-id <id> --member-email <email> [--dry-run]
+```
+
+## Vector
+
+```bash
+upstash vector list
+upstash vector get --index-id <id>
+upstash vector create --name <name> --region <region> --similarity-function <fn> --dimension-count <n> [--type payg] [--index-type <type>] [--embedding-model <m>] [--sparse-embedding-model <m>]
+upstash vector delete --index-id <id> [--dry-run]
+upstash vector rename --index-id <id> --name <new-name>
+upstash vector reset-password --index-id <id>
+upstash vector set-plan --index-id <id> --plan <free|payg|fixed>
+upstash vector transfer --index-id <id> --target-account <id>
+upstash vector stats                             # aggregate across all indexes
+upstash vector index-stats --index-id <id> [--period <1h|3h|12h|1d|3d|7d|30d>]
+```
+
+Regions: `eu-west-1`, `us-east-1`, `us-central1`. Similarity: `COSINE`, `EUCLIDEAN`, `DOT_PRODUCT`. Index types: `DENSE`, `SPARSE`, `HYBRID`. Dense models: `BGE_SMALL_EN_V1_5`, `BGE_BASE_EN_V1_5`, `BGE_LARGE_EN_V1_5`, `BGE_M3`. Sparse models: `BM25`, `BGE_M3`. For `HYBRID` with managed embeddings, set `--dimension-count 0`.
+
+## Search
+
+```bash
+upstash search list
+upstash search get --index-id <id>
+upstash search create --name <name> --region <region> --type <free|payg|fixed>
+upstash search delete --index-id <id> [--dry-run]
+upstash search rename --index-id <id> --name <new-name>
+upstash search reset-password --index-id <id>
+upstash search transfer --index-id <id> --target-account <id>
+upstash search stats
+upstash search index-stats --index-id <id> [--period <1h|3h|12h|1d|3d|7d|30d>]
+```
+
+Regions: `eu-west-1`, `us-central1`.
+
+## QStash
+
+```bash
+upstash qstash list                              # run first; maps region → id
+upstash qstash get --qstash-id <id>
+upstash qstash rotate-token --qstash-id <id>
+upstash qstash set-plan --qstash-id <id> --plan <paid|qstash_fixed_1m|qstash_fixed_10m|qstash_fixed_100m>
+upstash qstash stats --qstash-id <id> [--period <1h|3h|12h|1d|3d|7d|30d>]
+upstash qstash ipv4                              # CIDR blocks for allowlisting
+upstash qstash move-to-team --qstash-id <id> --target-team-id <id>
+upstash qstash update-budget --qstash-id <id> --budget <dollars>    # 0 = no limit
+upstash qstash {enable,disable}-prodpack --qstash-id <id>
+```
+
+## Conventions
+
+- Pipe any output to `jq` for field extraction, e.g. `upstash redis list | jq '.[].database_id'`.
+- Use `--dry-run` first on any `delete` or `remove-member`.
+- Use `--hide-credentials` on `redis get` when the password isn't needed.

package/.agents/skills/upstash/upstash-qstash-js/advanced/callbacks.md

@@ -0,0 +1,147 @@
+# Callbacks
+
+Callbacks let you receive delivery results without waiting for the HTTP request to complete. QStash calls your callback URL with the response after delivering the message.
+
+## Why Use Callbacks?
+
+Serverless functions have execution time limits. Callbacks allow you to:
+
+- Publish long-running tasks without blocking
+- Receive delivery confirmation asynchronously
+- Handle failures separately with failure callbacks
+
+You can use callbacks individually or together:
+
+```typescript
+await client.publishJSON({
+  url: "https://api.example.com/webhook",
+  body: { order: "12345" },
+  callback: "https://api.example.com/callback",
+  failureCallback: "https://api.example.com/failure",
+});
+```
+
+## callback
+
+Called after each delivery attempt (success or failure):
+
+The callback is invoked after every retry attempt until the destination returns a 2XX status or retries are exhausted. Check `retried === maxRetries` in the callback body to detect final failure.
+
+## failureCallback
+
+Called only when all retries are exhausted:
+
+Use this as a serverless alternative to polling the DLQ. See [DLQ](dlq.md) for more options.
+
+## Callback Payload
+
+### Success Callback Body
+
+```json
+{
+  "status": 200,
+  "header": { "content-type": ["application/json"] },
+  "body": "YmFzZTY0IGVuY29kZWQgcm9keQ==",
+  "retried": 2,
+  "maxRetries": 3,
+  "sourceMessageId": "msg_xxx",
+  "topicName": "myTopic",
+  "endpointName": "myEndpoint",
+  "url": "https://api.example.com/webhook",
+  "method": "POST",
+  "sourceHeader": { "content-type": "application/json" },
+  "sourceBody": "YmFzZTY0IGVuY29kZWQgcm9keQ==",
+  "notBefore": 1701198458025,
+  "createdAt": 1701198447054,
+  "scheduleId": "scd_xxx",
+  "callerIP": "178.247.74.179"
+}
+```
+
+### Failure Callback Body
+
+```json
+{
+  "status": 500,
+  "header": { "content-type": ["text/plain"] },
+  "body": "RXJyb3IgbWVzc2FnZQ==",
+  "retried": 3,
+  "maxRetries": 3,
+  "dlqId": "1725323658779-0",
+  "sourceMessageId": "msg_xxx",
+  "topicName": "myTopic",
+  "endpointName": "myEndpoint",
+  "url": "https://api.example.com/webhook",
+  "method": "POST",
+  "sourceHeader": { "content-type": "application/json" },
+  "sourceBody": "YmFzZTY0IGVuY29kZWQgcm9keQ==",
+  "notBefore": 1701198458025,
+  "createdAt": 1701198447054,
+  "scheduleId": "scd_xxx",
+  "callerIP": "178.247.74.179"
+}
+```
+
+### Field Descriptions
+
+- `status` - HTTP status code from destination
+- `header` - Response headers from destination
+- `body` - Base64-encoded response body (may be truncated per plan limits)
+- `retried` - Number of retry attempts made
+- `maxRetries` - Maximum retry limit
+- `dlqId` - Dead Letter Queue ID (failure callbacks only)
+- `sourceMessageId` - Original message ID
+- `topicName` - URL group name (if applicable)
+- `endpointName` - Endpoint name within URL group (if applicable)
+- `url` - Destination URL
+- `method` - HTTP method used
+- `sourceHeader` - Original message headers
+- `sourceBody` - Base64-encoded original message body
+- `notBefore` - Scheduled delivery time (Unix ms)
+- `createdAt` - Message creation time (Unix ms)
+- `scheduleId` - Schedule ID (if from schedule)
+- `callerIP` - IP address that published the message
+
+## Callback Configuration
+
+Callbacks are themselves QStash messages and can be configured with the same options. Use the `Upstash-Callback-*` or `Upstash-Failure-Callback-*` header prefix:
+
+**Not available via SDK parameters** - requires custom headers:
+
+```typescript
+await client.publish({
+  url: "https://api.example.com/webhook",
+  body: "data",
+  callback: "https://api.example.com/callback",
+  headers: {
+    // Configure callback behavior
+    "Upstash-Callback-Retries": "3",
+    "Upstash-Callback-Timeout": "30",
+    "Upstash-Callback-Method": "PUT",
+    "Upstash-Callback-Delay": "60",
+
+    // Forward custom headers to callback
+    "Upstash-Callback-Forward-Authorization": "Bearer token",
+    "Upstash-Callback-Forward-X-Custom": "value",
+
+    // Configure failure callback
+    "Upstash-Failure-Callback-Retries": "5",
+    "Upstash-Failure-Callback-Forward-Authorization": "Bearer token",
+  },
+});
+```
+
+Available configuration headers:
+
+- `Upstash-Callback-Retries` / `Upstash-Failure-Callback-Retries`
+- `Upstash-Callback-Timeout` / `Upstash-Failure-Callback-Timeout`
+- `Upstash-Callback-Delay` / `Upstash-Failure-Callback-Delay`
+- `Upstash-Callback-Method` / `Upstash-Failure-Callback-Method`
+- `Upstash-Callback-Forward-*` / `Upstash-Failure-Callback-Forward-*`
+
+## Notes
+
+- Callbacks are charged as regular messages
+- Callbacks retry until the callback URL returns 2XX or retries are exhausted
+- Response body may be truncated if it exceeds your plan's message size limit
+- Both URLs must be publicly accessible

package/.agents/skills/upstash/upstash-qstash-js/advanced/deduplication.md

@@ -0,0 +1,86 @@
+# Message Deduplication
+
+Prevent duplicate message delivery within a 90-day window using deduplication IDs.
+
+## Why Deduplication?
+
+Duplicate messages can occur when:
+
+- User retries a failed request
+- Network issues cause message resubmission
+- Application logic triggers multiple publishes for the same event
+
+Deduplication ensures QStash accepts but doesn't enqueue duplicate messages.
+
+## Deduplication Methods
+
+### deduplicationId
+
+Provide a custom identifier to detect duplicates:
+
+```typescript
+import { Client } from "@upstash/qstash";
+
+const client = new Client({ token: process.env.QSTASH_TOKEN! });
+
+await client.publishJSON({
+  url: "https://api.example.com/webhook",
+  deduplicationId: `order-${orderId}-payment`,
+  body: { orderId, status: "paid" },
+});
+```
+
+If a message with the same `deduplicationId` was published in the last 90 days, the new message is accepted but not enqueued.
+
+**Use cases:**
+
+- Order processing: `order-${orderId}`
+- User events: `user-${userId}-signup`
+- Payment transactions: `payment-${transactionId}`
+
+### contentBasedDeduplication
+
+Automatically generate a deduplication ID from message content:
+
+```typescript
+await client.publishJSON({
+  url: "https://api.example.com/webhook",
+  contentBasedDeduplication: true,
+  body: { userId: "123", event: "signup" },
+});
+```
+
+The hash includes:
+
+- All headers (except authorization)
+- Request body
+- Destination URL
+
+## Deduplication Window
+
+Deduplication IDs are stored for **90 days**. After this period, a message with the same ID can be delivered again.
+
+## Response Handling
+
+When a duplicate is detected, the response includes the original message ID:
+
+```typescript
+const result = await client.publishJSON({
+  url: "https://api.example.com/webhook",
+  deduplicationId: "order-123",
+  body: { order: "data" },
+});
+
+if (result.deduplicated) {
+  console.log("Duplicate detected");
+  console.log("Original message ID:", result.messageId);
+}
+```
+
+## Best Practices
+
+- Use descriptive, deterministic deduplication IDs
+- Include relevant context in custom IDs: `${entity}-${id}-${action}`
+- Don't rely on deduplication for critical data consistency
+- Monitor deduplicated messages in logs to detect issues
+- Document your deduplication strategy for team reference

package/.agents/skills/upstash/upstash-qstash-js/advanced/dlq.md

@@ -0,0 +1,164 @@
+# Dead Letter Queue (DLQ)
+
+Messages that fail after all retries are moved to the Dead Letter Queue for manual inspection and recovery.
+
+## What is the DLQ?
+
+When a message fails delivery after exhausting all retries, QStash moves it to the DLQ instead of discarding it. This lets you:
+
+- Investigate failure reasons
+- Manually retry after fixing issues
+- Delete permanently failed messages
+- Track patterns in failures
+
+Common failure reasons:
+
+- Destination endpoint errors (5XX responses)
+- Timeouts
+- Network issues
+- Invalid responses from destination
+
+## Listing DLQ Messages
+
+```typescript
+import { Client } from "@upstash/qstash";
+
+const client = new Client({ token: process.env.QSTASH_TOKEN! });
+
+const result = await client.dlq.listMessages();
+
+console.log(`Found ${result.messages.length} failed messages`);
+
+result.messages.forEach((msg) => {
+  console.log(`Message ${msg.messageId} to ${msg.url}`);
+  console.log(`Status: ${msg.responseStatus}`);
+  console.log(`DLQ ID: ${msg.dlqId}`);
+});
+```
+
+## Pagination
+
+Use cursor-based pagination for large DLQ:
+
+```typescript
+let cursor: string | undefined;
+const allMessages = [];
+
+do {
+  const result = await client.dlq.listMessages({
+    cursor,
+    count: 50, // Return up to 50 messages
+  });
+  allMessages.push(...result.messages);
+  cursor = result.cursor;
+} while (cursor);
+
+console.log(`Total failed messages: ${allMessages.length}`);
+```
+
+## Filtering DLQ Messages
+
+Filter by various criteria:
+
+```typescript
+const result = await client.dlq.listMessages({
+  filter: {
+    messageId: "msg_123...",
+    url: "https://api.example.com/webhook",
+    urlGroup: "payment-webhooks",
+    queueName: "order-processing",
+    scheduleId: "scd_123...",
+    label: "payment-processing",
+    responseStatus: 500,
+    fromDate: oneDayAgo,
+    toDate: Date.now(),
+    callerIp: "192.168.1.1",
+  },
+});
+```
+
+## Message Details
+
+Each DLQ message includes:
+
+```typescript
+type DlqMessage = {
+  dlqId: string; // Unique DLQ identifier
+  messageId: string; // Original message ID
+  url: string; // Destination URL
+  method?: string; // HTTP method
+  header?: Record<string, string[]>; // Request headers
+  body?: string; // Request body
+  urlGroup?: string; // URL group name
+  queueName?: string; // Queue name
+  scheduleId?: string; // Schedule ID
+  createdAt: number; // Creation timestamp (ms)
+  notBefore?: number; // Scheduled delivery time (ms)
+  label?: string; // Message label
+
+  // Failure details
+  responseStatus?: number; // HTTP status from destination
+  responseHeader?: Record<string, string[]>; // Response headers
+  responseBody?: string; // Response body (UTF-8)
+  responseBodyBase64?: string; // Response body (base64 if non-UTF-8)
+};
+```
+
+## Deleting Messages
+
+```typescript
+await client.dlq.delete("1725323658779-0");
+await client.dlq.deleteMany({
+  dlqIds: ["1725323658779-0", "1725323658780-1", "1725323658781-2"],
+});
+```
+
+## Understanding Failures
+
+Inspect failure details:
+
+```typescript
+const result = await client.dlq.listMessages();
+
+for (const msg of result.messages) {
+  console.log(`\nMessage ${msg.messageId}:`);
+  console.log(`URL: ${msg.url}`);
+  console.log(`Status: ${msg.responseStatus}`);
+
+  if (msg.responseBody) {
+    console.log(`Response: ${msg.responseBody}`);
+  } else if (msg.responseBodyBase64) {
+    const decoded = Buffer.from(msg.responseBodyBase64, "base64").toString();
+    console.log(`Response: ${decoded}`);
+  }
+
+  if (msg.responseHeader) {
+    console.log(`Headers:`, msg.responseHeader);
+  }
+}
+```
+
+## Using Failure Callbacks
+
+Instead of polling the DLQ, use failure callbacks for real-time notifications:
+
+See [Callbacks](callbacks.md) for more details.
+
+## DLQ Retention
+
+Messages remain in the DLQ based on your plan:
+
+- **Free**: 7 days
+- **Paid**: Check your plan on [QStash Pricing](https://upstash.com/pricing/qstash)
+
+Messages are automatically deleted when retention expires.
+
+## Best Practices
+
+- Set up failure callbacks for critical messages
+- Regularly monitor DLQ for patterns
+- Delete non-retriable messages to keep DLQ clean
+- Use labels to categorize and filter failures
+- Alert on DLQ message count thresholds
+- Document common failure scenarios and resolutions
+- Consider automated retries for known transient issues