@theholocron/cloudflare-client 1.57.1-alpha.2 → 1.58.0-alpha.10

package/dist/index.d.mts

@@ -1,6 +1,8 @@
 import "@theholocron/http-client";
 import { ErrorSink, Logger } from "@theholocron/observability/core";
+/** Options for `createCloudflareClient`. */
 interface CloudflareClientOptions {
+  /** A Cloudflare API token, sent as a bearer token. */
   token: string;
   /** Override base URL for testing. Defaults to https://api.cloudflare.com/client/v4 */
   baseUrl?: string;
@@ -15,110 +17,190 @@ interface CloudflareClientOptions {
   /** Milliseconds before the first retry; each later one waits three times as long. Defaults to 300. */
   retryDelayMs?: number;
 }
+/** The `{ success, errors, result }` envelope Cloudflare wraps every JSON response in. */
 interface CfEnvelope<T> {
+  /** Whether Cloudflare reports the call as successful. */
   success: boolean;
+  /** The errors Cloudflare reports, empty on success. */
   errors: unknown[];
+  /** The payload of the call. */
   result: T;
 }
+/** The DNS record types the client accepts. */
 type CfDnsRecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "SRV" | "CAA";
+/** A DNS record in a Cloudflare zone. */
 interface CfDnsRecord {
+  /** The record's identifier. */
   id: string;
+  /** The record type. */
   type: CfDnsRecordType;
+  /** The record's name (hostname). */
   name: string;
+  /** The record's content, such as an IP address or target hostname. */
   content: string;
+  /** The time to live in seconds; `1` means automatic. */
   ttl: number;
+  /** Whether traffic goes through Cloudflare's proxy. */
   proxied: boolean;
 }
+/** The fields for creating or updating a DNS record. */
 interface CfDnsRecordInput {
+  /** The record type. */
   type: CfDnsRecordType;
+  /** The record's name (hostname). */
   name: string;
+  /** The record's content, such as an IP address or target hostname. */
   content: string;
+  /** The time to live in seconds. When creating, defaults to `1` (automatic). */
   ttl?: number;
+  /** Whether to proxy traffic through Cloudflare. When creating, defaults to `false`. */
   proxied?: boolean;
 }
+/** How a Pages environment variable is stored: as plain text or as an encrypted secret. */
 type CfPagesEnvVarType = "plain_text" | "secret_text";
+/** An environment variable on a Pages project. */
 interface CfPagesEnvVar {
+  /** The variable's value. */
   value: string;
+  /** Whether the variable is plain text or a secret. */
   type: CfPagesEnvVarType;
 }
+/** The configuration of one Pages deployment environment. */
 interface CfPagesEnvConfig {
+  /** The environment variables, keyed by name. */
   env_vars: Record<string, CfPagesEnvVar>;
 }
+/** A Cloudflare Pages project. */
 interface CfPagesProject {
+  /** The project's identifier. */
   id: string;
+  /** The project's name. */
   name: string;
+  /** The project's `pages.dev` subdomain. */
   subdomain: string;
+  /** The domains the project is served on. */
   domains: string[];
+  /** The branch that deploys to production. */
   production_branch: string;
+  /** The per-environment deployment configuration. */
   deployment_configs: {
+    /** The configuration used for preview deployments. */
     preview: CfPagesEnvConfig;
+    /** The configuration used for production deployments. */
     production: CfPagesEnvConfig;
   };
 }
+/** The fields for creating a Pages project. */
 interface CfPagesProjectInput {
+  /** The project's name. */
   name: string;
+  /** The branch that deploys to production. */
   production_branch: string;
 }
+/** One stage of a Pages deployment. */
 interface CfPagesDeploymentStage {
+  /** The stage's name. */
   name: string;
+  /** The stage's status. */
   status: "idle" | "active" | "canceled" | "success" | "failure";
 }
+/** A custom domain attached to a Pages project. */
 interface CfPagesDomain {
+  /** The domain's identifier. */
   id: string;
+  /** The domain's hostname. */
   name: string;
+  /** The domain's verification and certificate status. */
   status: "active" | "pending" | "blocked" | "error" | "moved" | "pending_tls";
 }
+/** A deployment of a Pages project. */
 interface CfPagesDeployment {
+  /** The deployment's identifier. */
   id: string;
+  /** The URL the deployment is served at. */
   url: string;
+  /** The environment the deployment belongs to. */
   environment: "preview" | "production";
+  /** What triggered the deployment. */
   deployment_trigger: {
+    /** The kind of trigger. */
     type: string;
+    /** Details of the commit that triggered the deployment. */
     metadata: {
+      /** The branch that was deployed. */
       branch: string;
+      /** The commit that was deployed. */
       commit_hash: string;
     };
   };
+  /** The deployment's most recent stage. */
   latest_stage: CfPagesDeploymentStage;
+  /** When the deployment was created, as an ISO 8601 string. */
   created_on: string;
 }
+/** A Cloudflare zone (a domain on the account). */
 interface CfZone {
+  /** The zone's identifier. */
   id: string;
+  /** The zone's domain name. */
   name: string;
+  /** The zone's status, as Cloudflare reports it. */
   status: string;
 }
+/** A Cloudflare Tunnel. */
 interface CfTunnel {
+  /** The tunnel's identifier. */
   id: string;
+  /** The tunnel's name. */
   name: string;
 }
+/** One ingress rule of a tunnel's configuration. */
 interface CfIngressRule {
+  /** The hostname the rule matches; omitted for the catch-all rule. */
   hostname?: string;
+  /** The origin service requests are sent to. */
   service: string;
+  /** The path the rule matches, when it is limited to one. */
   path?: string;
 }
+/** A tunnel's configuration. */
 interface CfTunnelConfig {
+  /** The ingress rules, evaluated in order. */
   ingress: CfIngressRule[];
 }
+/** The result of verifying the API token in use. */
 interface CfTokenVerification {
+  /** The token's identifier. */
   id: string;
+  /** Whether the token is active, disabled or expired. */
   status: "active" | "disabled" | "expired";
 }
+/** A route that sends matching requests to a Worker. */
 interface CfWorkerRoute {
+  /** The route's identifier. */
   id: string;
+  /** The URL pattern the route matches. */
   pattern: string;
+  /** The name of the Worker script, or `null` when the route is bound to none. */
   script: string | null;
 }
 /** https://developers.cloudflare.com/api/operations/worker-script-put-encrypted-secret-binding */
 interface CfWorkerSecret {
+  /** The secret's name. */
   name: string;
+  /** The binding type, always `"secret_text"`. */
   type: "secret_text";
 }
 /** https://developers.cloudflare.com/api/operations/worker-script-list-workers */
 interface CfWorkerScript {
+  /** The script's name. */
   id: string;
+  /** When the script was created, as an ISO 8601 string. */
   created_on?: string;
+  /** When the script was last modified, as an ISO 8601 string. */
   modified_on?: string;
 }
+/** Creates a Cloudflare API client with `dns`, `pages`, `zones`, `tunnels`, `tokens` and `workers` groups. */
 export declare function createCloudflareClient(opts: CloudflareClientOptions): {
   dns: {
     list: (zoneId: string, query?: {
@@ -177,5 +259,6 @@ export declare function createCloudflareClient(opts: CloudflareClientOptions): {
     deleteSecret: (accountId: string, scriptName: string, name: string) => Promise<void>;
   };
 };
+/** The client returned by `createCloudflareClient`. */
 export type CloudflareClient = ReturnType<typeof createCloudflareClient>;
 export type { CfDnsRecord, CfDnsRecordInput, CfDnsRecordType, CfEnvelope, CfIngressRule, CfPagesDeployment, CfPagesDeploymentStage, CfPagesDomain, CfPagesEnvConfig, CfPagesEnvVar, CfPagesEnvVarType, CfPagesProject, CfPagesProjectInput, CfTokenVerification, CfTunnel, CfTunnelConfig, CfWorkerRoute, CfWorkerScript, CfWorkerSecret, CfZone, CloudflareClientOptions };

package/dist/index.mjs

@@ -145,6 +145,7 @@ function zones(rest) {
 	}) };
 }
 // src/index.ts
+/** Creates a Cloudflare API client with `dns`, `pages`, `zones`, `tunnels`, `tokens` and `workers` groups. */
 function createCloudflareClient(opts) {
 	const rest = createCloudflareRestClient(opts);
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cloudflare-client",
-  "version": "1.57.1-alpha.2",
+  "version": "1.58.0-alpha.10",
   "description": "A TypeScript client for the Cloudflare API",
   "keywords": [
     "cloudflare",
@@ -32,23 +32,23 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/http-client": "^1.57.1-alpha.2",
-    "@theholocron/observability": "^0.6.1-alpha.1"
+    "@theholocron/http-client": "^1.58.0-alpha.10",
+    "@theholocron/observability": "^0.7.0-alpha.1"
   },
   "devDependencies": {
     "@types/node": "^26",
     "@vitest/coverage-v8": "^5.0.5",
-    "@vitest/eslint-plugin": "^1.6.27",
-    "eslint": "^10.8.1",
-    "eslint-plugin-n": "^18.3.0",
-    "globals": "^17.11.0",
-    "tsdown": "^0.23.3",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "eslint": "^10.14.0",
+    "eslint-plugin-n": "^18.5.0",
+    "globals": "^17.14.0",
+    "tsdown": "^0.23.4",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/eslint-config": "^8.9.0-alpha.3",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
-    "@theholocron/tsconfig": "^8.9.0-alpha.3",
-    "@theholocron/vitest-config": "^8.9.0-alpha.3"
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/tsconfig": "^8.9.0-alpha.8",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
+    "@theholocron/vitest-config": "^8.9.0-alpha.8"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -57,10 +57,10 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown && node ../scripts/check-bundle-size.mjs",
-    "sourceQuality.staticAnalysis": "eslint .",
+    "build": "tsdown && node ../scripts/check-bundle-size.mjs",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "verification.typeSafety": "tsc --noEmit",
-    "verification.unitTests": "vitest run"
+    "typecheck": "tsc --noEmit"
   }
 }