memory-journal-mcp 8.0.1 → 9.1.0

package/skills/cloudflare/references/graphql-api/gotchas.md

@@ -1,111 +0,0 @@
-# GraphQL Analytics API Gotchas & Troubleshooting
-
-## Rate Limits
-
-| Limit                    | Value                                                     |
-| ------------------------ | --------------------------------------------------------- |
-| GraphQL queries per user | **Default 300 per 5 minutes** (max 320, at least 1/sec)   |
-| General API rate limit   | 1200 requests per 5 minutes (shared across all API calls) |
-| Zone scope per query     | Up to **10 zones**                                        |
-| Account scope per query  | Exactly **1 account**                                     |
-
-The GraphQL rate limit is separate from the general API limit. Exceeding either results in `HTTP 429` and blocks all API calls for 5 minutes. Enterprise customers can contact support to raise limits.
-
-### "429 Too Many Requests"
-
-**Cause:** Exceeded rate limit.
-
-**Solution:** Batch multiple datasets into single queries, cache results, increase intervals between queries. Use `{ viewer { budget } }` to monitor remaining budget.
-
-## Sampling & Data Accuracy
-
-### Adaptive Bit Rate (ABR) Sampling
-
-Datasets with `Adaptive` in the name use adaptive sampling:
-
-- Results are **statistically representative**, not exact
-- Same query may return **slightly different numbers** each run
-- Higher traffic = higher sampling rate = more accurate
-- `sampleInterval` dimension shows the ratio (1 = no sampling, 10 = ~1-in-10 sampled)
-
-For high-confidence numbers, use `confidence(level: 0.95)` to get estimate bounds. For exact counts, use rollup nodes (`httpRequests1hGroups`, `httpRequests1dGroups`) which are pre-aggregated without sampling.
-
-### Rollup vs. Adaptive
-
-| Feature     | Rollup (`*1hGroups`, `*1dGroups`) | Adaptive (`*AdaptiveGroups`) |
-| ----------- | --------------------------------- | ---------------------------- |
-| Sampling    | No (pre-aggregated)               | Yes (ABR)                    |
-| Flexibility | Fixed time buckets                | Any granularity              |
-| Dimensions  | Fewer                             | Many more                    |
-| Accuracy    | Exact                             | Statistical estimate         |
-
-## Common Errors
-
-### "Access denied" / "authentication error"
-
-**Cause:** Token lacks required permission or wrong scope.
-
-**Solution:** Account-scoped queries need **Account Analytics: Read**. Zone-scoped queries need **Zone Analytics: Read**. Verify: `curl -s https://api.cloudflare.com/client/v4/user/tokens/verify -H "Authorization: Bearer $TOKEN"`
-
-### "field not found" / "Cannot query field"
-
-**Cause:** Wrong dataset name, nonexistent field, or wrong scope (zone vs. account).
-
-**Solution:** Names are case-sensitive camelCase (`httpRequestsAdaptiveGroups`). Zone datasets go under `zones(...)`, account datasets under `accounts(...)`. Use introspection to verify.
-
-### "filter is required" / empty results
-
-**Cause:** Missing required time range filter or incorrect zone/account tag.
-
-**Solution:** Always include `datetime_gt` / `datetime_lt` (or `_geq` / `_leq`).
-
-### "limit is required" / "limit exceeds maximum"
-
-**Cause:** Missing `limit` or exceeding node's max page size.
-
-**Solution:** Always specify `limit`. Max varies by dataset (typically 10,000 for groups, 100 for raw events). Check via settings query.
-
-### "query is too complex" / "query exceeds budget"
-
-**Cause:** Too many fields, datasets, or too broad a time range.
-
-**Solution:** Reduce time range, request fewer dimensions/metrics, break into smaller queries. Monitor `cost` and `budget` in responses.
-
-### 200 Response with Errors
-
-GraphQL returns HTTP 200 even on failures. **Always check `response.errors`:**
-
-```json
-{ "data": null, "errors": [{ "message": "filter is required for httpRequestsAdaptiveGroups" }] }
-```
-
-## Plan-Based Availability
-
-Not all datasets are available on all plans. Higher plans get more datasets, longer retention (`notOlderThan`), wider time ranges (`maxDuration`), more fields, and larger page sizes.
-
-### "node is not available" / "node is disabled"
-
-**Cause:** Dataset not on your plan, or product not enabled.
-
-**Solution:** Check `settings { <nodeName> { enabled } }`. Some datasets require specific subscriptions (e.g., Network Analytics requires Magic Transit/Spectrum).
-
-## DateTime & Timezone Handling
-
-- All times are **UTC only** (ISO 8601: `"2025-01-15T10:30:00Z"`)
-- `Date` type: `"2025-01-15"` (used in `date_geq`/`date_leq` for storage datasets)
-- `Time` type: `"2025-01-15T10:30:00Z"` (used in `datetime_gt`/`datetime_lt`)
-- Filters are start-inclusive: events that start within the window are included
-
-## Performance Tips
-
-- **Narrow time ranges** are faster and cheaper
-- **Select only needed dimensions** — each additional dimension increases cost
-- **Use rollup nodes** (`*1dGroups`) for simple daily totals without dimension breakdowns
-- **Batch datasets** into one query instead of separate HTTP requests
-
-## See Also
-
-- [README.md](README.md) - Overview, decision tree, dataset index
-- [api.md](api.md) - Query structure, aggregation fields, filtering operators
-- [configuration.md](configuration.md) - Authentication, client setup, introspection queries
-- [patterns.md](patterns.md) - Common query patterns (time-series, top-N, per-product)

package/skills/cloudflare/references/graphql-api/patterns.md

@@ -1,276 +0,0 @@
-# GraphQL Analytics API Patterns & Best Practices
-
-## Time-Series Queries
-
-Use time dimension granularity matching your range (see Best Practices below).
-
-```graphql
-query TrafficTimeSeries($zoneTag: string!, $start: Time!, $end: Time!) {
-  viewer {
-    zones(filter: { zoneTag: $zoneTag }) {
-      httpRequestsAdaptiveGroups(
-        filter: { datetime_gt: $start, datetime_lt: $end }
-        limit: 1000
-        orderBy: [datetimeFiveMinutes_ASC] # or datetimeHour_ASC for longer ranges
-      ) {
-        count
-        dimensions {
-          datetimeFiveMinutes
-        }
-        sum {
-          edgeResponseBytes
-        }
-        ratio {
-          status4xx
-          status5xx
-        }
-      }
-    }
-  }
-}
-```
-
-## Top-N Queries
-
-### Top Countries by Request Count
-
-```graphql
-query TopCountries($zoneTag: string!, $start: Time!, $end: Time!) {
-  viewer {
-    zones(filter: { zoneTag: $zoneTag }) {
-      httpRequestsAdaptiveGroups(
-        filter: { datetime_gt: $start, datetime_lt: $end }
-        limit: 10
-        orderBy: [count_DESC]
-      ) {
-        count
-        dimensions {
-          clientCountryName
-        }
-      }
-    }
-  }
-}
-```
-
-Use `orderBy: [sum_edgeResponseBytes_DESC]` for top paths by bandwidth. Add `edgeResponseStatus_geq: 400` to the filter for top error status codes.
-
-## Workers Analytics
-
-```graphql
-query WorkersOverview($accountTag: string!, $start: Time!, $end: Time!) {
-  viewer {
-    accounts(filter: { accountTag: $accountTag }) {
-      workersInvocationsAdaptive(
-        filter: { datetime_gt: $start, datetime_lt: $end }
-        limit: 100
-        orderBy: [sum_requests_DESC]
-      ) {
-        sum {
-          requests
-          errors
-          subrequests
-          wallTime
-        }
-        quantiles {
-          cpuTimeP50
-          cpuTimeP99
-          wallTimeP50
-          wallTimeP99
-        }
-        dimensions {
-          scriptName
-        }
-      }
-    }
-  }
-}
-```
-
-Filter by `scriptName` for a specific Worker. Add `datetimeFiveMinutes` dimension + `orderBy: [datetimeFiveMinutes_ASC]` for error rate over time.
-
-## Firewall / Security
-
-```graphql
-query RecentFirewallEvents($zoneTag: string!, $start: Time!) {
-  viewer {
-    zones(filter: { zoneTag: $zoneTag }) {
-      firewallEventsAdaptive(filter: { datetime_gt: $start }, limit: 50, orderBy: [datetime_DESC]) {
-        action
-        source
-        clientIP
-        clientCountryName
-        userAgent
-        clientRequestHTTPHost
-        clientRequestPath
-        ruleId
-        datetime
-      }
-    }
-  }
-}
-```
-
-For aggregated firewall stats, use `firewallEventsAdaptiveGroups` with `action: "block"` filter and group by `ruleId`, `source`, `datetimeHour`.
-
-## DNS Analytics
-
-```graphql
-query DNSQueryVolume($zoneTag: string!, $start: Time!, $end: Time!) {
-  viewer {
-    zones(filter: { zoneTag: $zoneTag }) {
-      dnsAnalyticsAdaptiveGroups(
-        filter: { datetime_gt: $start, datetime_lt: $end }
-        limit: 500
-        orderBy: [datetimeFiveMinutes_ASC]
-      ) {
-        count
-        dimensions {
-          datetimeFiveMinutes
-        }
-      }
-    }
-  }
-}
-```
-
-## Storage Analytics (Account-Scoped)
-
-R2, KV, and D1 use `date` (Date type) filters instead of `datetime` (Time type).
-
-```graphql
-# R2 operations
-r2OperationsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
-  dimensions { date bucketName actionType }
-  sum { requests }
-}
-
-# KV operations
-kvOperationsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
-  dimensions { date actionType }
-  sum { requests }
-}
-
-# D1 analytics
-d1AnalyticsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
-  dimensions { date databaseId }
-  sum { readQueries writeQueries rowsRead rowsWritten }
-}
-```
-
-## Cache Analytics
-
-```graphql
-query CacheStatusBreakdown($zoneTag: string!, $start: Time!, $end: Time!) {
-  viewer {
-    zones(filter: { zoneTag: $zoneTag }) {
-      httpRequestsAdaptiveGroups(
-        filter: { datetime_gt: $start, datetime_lt: $end }
-        limit: 20
-        orderBy: [count_DESC]
-      ) {
-        count
-        dimensions {
-          cacheStatus
-        }
-        sum {
-          edgeResponseBytes
-        }
-      }
-    }
-  }
-}
-```
-
-For cache hit ratio over time, use aliases to query the same dataset twice — once with `cacheStatus: "hit"` filter and once without — then compute the ratio client-side.
-
-## Multi-Dataset Queries
-
-A single request can query multiple datasets, avoiding extra HTTP round-trips:
-
-```graphql
-query DashboardOverview($zoneTag: string!, $start: Time!, $end: Time!) {
-  viewer {
-    zones(filter: { zoneTag: $zoneTag }) {
-      httpTraffic: httpRequestsAdaptiveGroups(
-        filter: { datetime_gt: $start, datetime_lt: $end }
-        limit: 1
-      ) {
-        count
-        sum {
-          edgeResponseBytes
-        }
-        ratio {
-          status4xx
-          status5xx
-        }
-      }
-      firewallEvents: firewallEventsAdaptiveGroups(
-        filter: { datetime_gt: $start, datetime_lt: $end }
-        limit: 5
-        orderBy: [count_DESC]
-      ) {
-        count
-        dimensions {
-          action
-          source
-        }
-      }
-      dnsQueries: dnsAnalyticsAdaptiveGroups(
-        filter: { datetime_gt: $start, datetime_lt: $end }
-        limit: 1
-      ) {
-        count
-      }
-    }
-  }
-}
-```
-
-## AI & Gateway Analytics
-
-```graphql
-# Workers AI inference
-aiInferenceAdaptiveGroups(
-  filter: { datetime_gt: $start, datetime_lt: $end }, limit: 100, orderBy: [datetimeHour_DESC]
-) {
-  count
-  sum { totalInputTokens totalOutputTokens totalRequestBytesIn }
-  dimensions { modelId datetimeHour }
-}
-
-# AI Gateway requests
-aiGatewayRequestsAdaptiveGroups(
-  filter: { datetime_gt: $start, datetime_lt: $end }, limit: 100, orderBy: [datetimeHour_DESC]
-) {
-  count
-  dimensions { gateway provider model datetimeHour }
-  sum { cachedTokensIn cachedTokensOut uncachedTokensIn uncachedTokensOut }
-}
-```
-
-Both are account-scoped — nest under `accounts(filter: { accountTag: $accountTag })`.
-
-## Best Practices
-
-**Always include time filters.** Queries without time filters scan all data and are slow/expensive.
-
-**Match time granularity to range:**
-
-| Time Range | Recommended Dimension                             |
-| ---------- | ------------------------------------------------- |
-| < 6 hours  | `datetimeMinute` or `datetimeFiveMinutes`         |
-| 6-48 hours | `datetimeFiveMinutes` or `datetimeFifteenMinutes` |
-| 2-14 days  | `datetimeHour`                                    |
-| 14+ days   | `date`                                            |
-
-**Use aliases** for querying the same dataset with different filters in one request.
-
-**Request only needed fields.** Extra dimensions and metrics increase query cost.
-
-## See Also
-
-- [README.md](README.md) - Overview, decision tree, dataset index
-- [api.md](api.md) - Query structure, aggregation fields, filtering operators
-- [configuration.md](configuration.md) - Authentication, client setup, introspection queries
-- [gotchas.md](gotchas.md) - Rate limits, sampling, troubleshooting

package/skills/cloudflare/references/hyperdrive/README.md

@@ -1,84 +0,0 @@
-# Hyperdrive
-
-Accelerates database queries from Workers via connection pooling, edge setup, query caching.
-
-## Key Features
-
-- **Connection Pooling**: Persistent connections eliminate TCP/TLS/auth handshakes (~7 round-trips)
-- **Edge Setup**: Connection negotiation at edge, pooling near origin
-- **Query Caching**: Auto-cache non-mutating queries (default 60s TTL)
-- **Support**: PostgreSQL, MySQL + compatibles (CockroachDB, Timescale, PlanetScale, Neon, Supabase)
-
-## Architecture
-
-```
-Worker → Edge (setup) → Pool (near DB) → Origin
-         ↓ cached reads
-         Cache
-```
-
-## Quick Start
-
-```bash
-# Create config
-npx wrangler hyperdrive create my-db \
-  --connection-string="postgres://user:pass@host:5432/db"
-
-# wrangler.jsonc
-{
-  "compatibility_flags": ["nodejs_compat"],
-  "hyperdrive": [{"binding": "HYPERDRIVE", "id": "<ID>"}]
-}
-```
-
-```typescript
-import { Client } from 'pg'
-
-export default {
-  async fetch(req: Request, env: Env): Promise<Response> {
-    const client = new Client({
-      connectionString: env.HYPERDRIVE.connectionString,
-    })
-    await client.connect()
-    const result = await client.query('SELECT * FROM users WHERE id = $1', [123])
-    await client.end()
-    return Response.json(result.rows)
-  },
-}
-```
-
-## When to Use
-
-✅ Global access to single-region DBs, high read ratios, popular queries, connection-heavy loads
-❌ Write-heavy, real-time data (<1s), single-region apps close to DB
-
-**💡 Pair with Smart Placement** for Workers making multiple queries - executes near DB to minimize latency.
-
-## Driver Choice
-
-| Driver               | Use When                                         | Notes                                       |
-| -------------------- | ------------------------------------------------ | ------------------------------------------- |
-| **pg** (recommended) | General use, TypeScript, ecosystem compatibility | Stable, widely used, works with most ORMs   |
-| **postgres.js**      | Advanced features, template literals, streaming  | Lighter than pg, `prepare: true` is default |
-| **mysql2**           | MySQL/MariaDB/PlanetScale                        | MySQL only, less mature support             |
-
-## Reading Order
-
-| New to Hyperdrive                         | Implementing                              | Troubleshooting                 |
-| ----------------------------------------- | ----------------------------------------- | ------------------------------- |
-| 1. README (this)                          | 1. [configuration.md](./configuration.md) | 1. [gotchas.md](./gotchas.md)   |
-| 2. [configuration.md](./configuration.md) | 2. [api.md](./api.md)                     | 2. [patterns.md](./patterns.md) |
-| 3. [api.md](./api.md)                     | 3. [patterns.md](./patterns.md)           | 3. [api.md](./api.md)           |
-
-## In This Reference
-
-- [configuration.md](./configuration.md) - Setup, wrangler config, Smart Placement
-- [api.md](./api.md) - Binding APIs, query patterns, driver usage
-- [patterns.md](./patterns.md) - Use cases, ORMs, multi-query optimization
-- [gotchas.md](./gotchas.md) - Limits, troubleshooting, connection management
-
-## See Also
-
-- [smart-placement](../smart-placement/) - Optimize multi-query Workers near databases
-- [d1](../d1/) - Serverless SQLite alternative for edge-native apps
-- [workers](../workers/) - Worker runtime with database bindings

package/skills/cloudflare/references/hyperdrive/api.md

@@ -1,149 +0,0 @@
-# API Reference
-
-See [README.md](./README.md) for overview, [configuration.md](./configuration.md) for setup.
-
-## Binding Interface
-
-```typescript
-interface Hyperdrive {
-  connectionString: string // PostgreSQL
-  // MySQL properties:
-  host: string
-  port: number
-  user: string
-  password: string
-  database: string
-}
-
-interface Env {
-  HYPERDRIVE: Hyperdrive
-}
-```
-
-**Generate types:** `npx wrangler types` (auto-creates worker-configuration.d.ts from wrangler.jsonc)
-
-## PostgreSQL (node-postgres) - RECOMMENDED
-
-```typescript
-import { Client } from 'pg' // pg@^8.17.2
-
-export default {
-  async fetch(req: Request, env: Env): Promise<Response> {
-    const client = new Client({ connectionString: env.HYPERDRIVE.connectionString })
-    try {
-      await client.connect()
-      const result = await client.query('SELECT * FROM users WHERE id = $1', [123])
-      return Response.json(result.rows)
-    } finally {
-      await client.end()
-    }
-  },
-}
-```
-
-**⚠️ Workers connection limit: 6 per Worker invocation** - use connection pooling wisely.
-
-## PostgreSQL (postgres.js)
-
-```typescript
-import postgres from 'postgres' // postgres@^3.4.8
-
-const sql = postgres(env.HYPERDRIVE.connectionString, {
-  max: 5, // Limit per Worker (Workers max: 6)
-  prepare: true, // Enabled by default, required for caching
-  fetch_types: false, // Reduce latency if not using arrays
-})
-
-const users = await sql`SELECT * FROM users WHERE active = ${true} LIMIT 10`
-```
-
-**⚠️ `prepare: true` is enabled by default and required for Hyperdrive caching.** Setting to `false` disables prepared statements + cache.
-
-## MySQL (mysql2)
-
-```typescript
-import { createConnection } from 'mysql2/promise' // mysql2@^3.16.2
-
-const conn = await createConnection({
-  host: env.HYPERDRIVE.host,
-  user: env.HYPERDRIVE.user,
-  password: env.HYPERDRIVE.password,
-  database: env.HYPERDRIVE.database,
-  port: env.HYPERDRIVE.port,
-  disableEval: true, // ⚠️ REQUIRED for Workers
-})
-
-const [results] = await conn.query('SELECT * FROM users WHERE active = ? LIMIT ?', [true, 10])
-ctx.waitUntil(conn.end())
-```
-
-**⚠️ MySQL support is less mature than PostgreSQL** - expect fewer optimizations and potential edge cases.
-
-## Query Caching
-
-**Cacheable:**
-
-```sql
-SELECT * FROM posts WHERE published = true;
-SELECT COUNT(*) FROM users;
-```
-
-**NOT cacheable:**
-
-```sql
--- Writes
-INSERT/UPDATE/DELETE
-
--- Volatile functions
-SELECT NOW();
-SELECT random();
-SELECT LASTVAL();  -- PostgreSQL
-SELECT UUID();     -- MySQL
-```
-
-**Cache config:**
-
-- Default: `max_age=60s`, `swr=15s`
-- Max `max_age`: 3600s
-- Disable: `--caching-disabled=true`
-
-**Multiple configs pattern:**
-
-```typescript
-// Reads: cached
-const sqlCached = postgres(env.HYPERDRIVE_CACHED.connectionString)
-const posts = await sqlCached`SELECT * FROM posts ORDER BY views DESC LIMIT 10`
-
-// Writes/time-sensitive: no cache
-const sqlNoCache = postgres(env.HYPERDRIVE_NO_CACHE.connectionString)
-const orders = await sqlNoCache`SELECT * FROM orders WHERE created_at > NOW() - INTERVAL 5 MINUTE`
-```
-
-## ORMs
-
-**Drizzle:**
-
-```typescript
-import { drizzle } from 'drizzle-orm/postgres-js' // drizzle-orm@^0.45.1
-import postgres from 'postgres'
-
-const client = postgres(env.HYPERDRIVE.connectionString, { max: 5, prepare: true })
-const db = drizzle(client)
-const users = await db.select().from(users).where(eq(users.active, true)).limit(10)
-```
-
-**Kysely:**
-
-```typescript
-import { Kysely, PostgresDialect } from 'kysely' // kysely@^0.27+
-import postgres from 'postgres'
-
-const db = new Kysely({
-  dialect: new PostgresDialect({
-    postgres: postgres(env.HYPERDRIVE.connectionString, { max: 5, prepare: true }),
-  }),
-})
-const users = await db.selectFrom('users').selectAll().where('active', '=', true).execute()
-```
-
-See [patterns.md](./patterns.md) for use cases, [gotchas.md](./gotchas.md) for limits.