@kody/cloudflare

/**
 * Return Cloudflare package discovery metadata: exports, secrets, and usage notes.
 */
export default async function describeCloudflareToolkit() {
  return {
    packageId: 'cloudflare',
    exports: ['overview', 'api-v4', 'analytics', 'docs', 'observability-logs', 'rulesets'],
    helpers: [
      {
        export: 'api-v4',
        purpose: 'Call Cloudflare API v4 endpoints under /client/v4/ using the user secret cloudflareApiToken.',
        mutating: true,
        requiredSecrets: ['cloudflareApiToken'],
      },
      {
        export: 'analytics',
        purpose: 'Query Cloudflare GraphQL analytics for zone traffic summaries, request paths, statuses, user agents, and outage forensics.',
        mutating: false,
        requiredSecrets: ['cloudflareApiToken'],
      },
      {
        export: 'docs',
        purpose: 'Fetch allowlisted Cloudflare developer docs pages as markdown-oriented text.',
        mutating: false,
        requiredSecrets: [],
      },
      {
        export: 'observability-logs',
        purpose: 'Search Cloudflare Log Explorer datasets with structured filters or custom SQL, with an analytics fallback for missing entitlement.',
        mutating: false,
        requiredSecrets: ['cloudflareApiToken'],
      },
      {
        export: 'rulesets',
        purpose: 'Preview or apply Cloudflare Rulesets/WAF custom rules, including cheap bogus-route blocks before traffic reaches origin.',
        mutating: true,
        requiredSecrets: ['cloudflareApiToken'],
      },
    ],
    notes: [
      'Approve api.cloudflare.com for the cloudflareApiToken secret before using api-v4.',
      'Use analytics for zone HTTP request aggregates, especially when Log Explorer SQL is unavailable or returns missing entitlement.',
      'Use rulesets in dry-run mode first to preview WAF/custom-rule changes; pass apply: true only after review.',
      'Use observability-logs for Workers trace events, HTTP request forensics, Access requests, Ray IDs, errors, and slow-request investigations.',
      'Use docs for current Cloudflare documentation under allowlisted product prefixes.',
    ],
  }
}