@distilled.cloud/cloudflare 0.0.0 → 0.2.3

package/src/client/api.ts

@@ -0,0 +1,329 @@
+/**
+ * Cloudflare API operations factory.
+ *
+ * This module is imported as `import * as API from "../client/api.ts"` by
+ * generated service files so that `API.make()`, `API.OperationMethod`, etc.
+ * are all accessible as namespace members.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type * as AST from "effect/SchemaAST";
+import {
+  makeAPI,
+  type ApiErrorClass,
+  type OperationMethod,
+  type PaginatedOperationMethod,
+} from "@distilled.cloud/core/client";
+import {
+  CloudflareHttpError,
+  HTTP_STATUS_MAP,
+  InternalServerError,
+  TooManyRequests,
+  UnknownCloudflareError,
+} from "../errors.ts";
+import { Credentials } from "../credentials.ts";
+import { type ErrorMatcher, getErrorMatchers } from "../traits.ts";
+
+// ============================================================================
+// Global Cloudflare error codes
+// ============================================================================
+
+/**
+ * Cloudflare error codes that map to global/default errors regardless of operation.
+ * These are infrastructure-level errors that can occur on any endpoint.
+ */
+const GLOBAL_ERROR_CODE_MAP: Record<number, (message: string) => unknown> = {
+  // "Please wait and consider throttling your request speed"
+  971: (message) => new TooManyRequests({ message }),
+};
+
+/**
+ * Create an appropriate error for an HTTP status code.
+ *
+ * For status codes in HTTP_STATUS_MAP (400, 401, 500, 502, 503, 504, etc.),
+ * returns the properly categorized error (with retry categories for 5xx).
+ * For unmapped 5xx codes (e.g., Cloudflare-specific 520-530), returns a
+ * CloudflareHttpError so the status is preserved.
+ */
+function httpStatusError(status: number, body?: string): unknown {
+  const ErrorClass = HTTP_STATUS_MAP[status as keyof typeof HTTP_STATUS_MAP];
+  if (ErrorClass) {
+    return new ErrorClass({ message: body ?? String(status) });
+  }
+  // For unmapped 5xx codes (e.g., Cloudflare-specific 520-530), use
+  // InternalServerError so they get ServerError + Retryable categories
+  if (status >= 500) {
+    return new InternalServerError({ message: body ?? String(status) });
+  }
+  return new CloudflareHttpError({
+    status,
+    statusText: String(status),
+    body,
+  });
+}
+
+export type { OperationMethod, PaginatedOperationMethod };
+
+// ============================================================================
+// Error matching
+// ============================================================================
+
+/**
+ * Extract the _tag literal value from a TaggedError schema AST.
+ */
+function extractTagFromAst(ast: AST.AST): string | undefined {
+  if (ast.encoding && ast.encoding.length > 0) {
+    return extractTagFromAst(ast.encoding[0].to);
+  }
+  if (ast._tag === "Objects") {
+    const tagProp = ast.propertySignatures.find(
+      (p: { name: PropertyKey }) => p.name === "_tag",
+    );
+    if (
+      tagProp &&
+      tagProp.type._tag === "Literal" &&
+      typeof tagProp.type.literal === "string"
+    ) {
+      return tagProp.type.literal;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Check if an error matches an expression-based matcher.
+ */
+function matchesExpression(
+  matcher: ErrorMatcher,
+  code: number | undefined,
+  status: number,
+  message: string,
+): boolean {
+  if (matcher.code === undefined && matcher.status === undefined) return false;
+  if (matcher.code !== undefined && matcher.code !== code) return false;
+  if (matcher.status !== undefined && matcher.status !== status) return false;
+  if (matcher.message !== undefined) {
+    if (typeof matcher.message === "string") {
+      if (matcher.message !== message) return false;
+    } else if (matcher.message.includes !== undefined) {
+      if (!message.includes(matcher.message.includes)) return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Calculate specificity score for a matcher.
+ */
+function matcherSpecificity(matcher: ErrorMatcher): number {
+  let score = 0;
+  if (matcher.code !== undefined) score += 1;
+  if (matcher.status !== undefined) score += 1;
+  if (matcher.message !== undefined) score += 1;
+  return score;
+}
+
+interface MatchedError {
+  schema: Schema.Top;
+  tag: string;
+}
+
+/**
+ * Find matching error schema using annotations from the schema AST.
+ */
+function findMatchingError(
+  errorSchemas: Map<string, Schema.Top>,
+  code: number | undefined,
+  status: number,
+  message: string,
+): MatchedError | undefined {
+  let bestMatch: MatchedError | undefined;
+  let bestScore = 0;
+
+  for (const [name, schema] of errorSchemas) {
+    const ast = schema.ast;
+    const matchers = getErrorMatchers(ast);
+    if (!matchers || matchers.length === 0) continue;
+
+    for (const matcher of matchers) {
+      if (matchesExpression(matcher, code, status, message)) {
+        const score = matcherSpecificity(matcher);
+        if (score > bestScore) {
+          bestScore = score;
+          bestMatch = { schema, tag: name };
+        }
+      }
+    }
+  }
+
+  return bestMatch;
+}
+
+/**
+ * Match a Cloudflare API error response using per-operation error schemas.
+ */
+const matchError = (
+  status: number,
+  errorBody: unknown,
+  errors?: readonly ApiErrorClass[],
+): Effect.Effect<never, unknown> => {
+  // Handle non-JSON error responses (e.g., HTML from malformed URLs, 520 pages)
+  const isNonJsonError =
+    typeof errorBody === "object" &&
+    errorBody !== null &&
+    "_nonJsonError" in errorBody;
+  if (isNonJsonError) {
+    // For 5xx errors, return a properly categorized error so retries work
+    if (status >= 500) {
+      return Effect.fail(
+        httpStatusError(status, String((errorBody as any).body)),
+      );
+    }
+    return Effect.fail(
+      new CloudflareHttpError({
+        status,
+        statusText: String(status),
+        body: String((errorBody as any).body),
+      }),
+    );
+  }
+
+  // Parse the Cloudflare error envelope
+  const envelope =
+    typeof errorBody === "object" && errorBody !== null ? errorBody : undefined;
+  const cfErrors =
+    envelope && "errors" in envelope && Array.isArray((envelope as any).errors)
+      ? ((envelope as any).errors as Array<{
+          code?: number;
+          message?: string;
+        }>)
+      : undefined;
+  const firstError = cfErrors?.[0];
+  // Cloudflare sometimes omits the code field entirely (e.g., webhook errors).
+  // Treat missing code as 0 (the default) so matchers with { code: 0 } can match.
+  const errorCode =
+    firstError && typeof firstError.code === "number"
+      ? firstError.code
+      : firstError
+        ? 0
+        : undefined;
+  const errorMessage = firstError?.message ?? String(status);
+
+  // Check if this is a valid Cloudflare envelope (has success field)
+  const isEnvelope =
+    envelope && "success" in envelope && (envelope as any).success === false;
+
+  if (!isEnvelope) {
+    // Not a Cloudflare envelope — HTTP-level error
+    // For 5xx errors, return a properly categorized error so retries work
+    const bodyStr =
+      typeof errorBody === "string" ? errorBody : JSON.stringify(errorBody);
+    if (status >= 500) {
+      return Effect.fail(httpStatusError(status, bodyStr));
+    }
+    return Effect.fail(
+      new CloudflareHttpError({
+        status,
+        statusText: String(status),
+        body: bodyStr,
+      }),
+    );
+  }
+
+  // Build error schema map from the per-operation errors
+  if (errors && errors.length > 0) {
+    const errorSchemas = new Map<string, Schema.Top>();
+    for (const errorSchema of errors) {
+      const identifier = extractTagFromAst(
+        (errorSchema as unknown as Schema.Top).ast,
+      );
+      if (identifier) {
+        errorSchemas.set(identifier, errorSchema as unknown as Schema.Top);
+      }
+    }
+
+    const matched = findMatchingError(
+      errorSchemas,
+      errorCode,
+      status,
+      errorMessage,
+    );
+
+    if (matched) {
+      // Decode using the schema - properly instantiates TaggedError classes
+      const errorData = {
+        _tag: matched.tag,
+        code: errorCode ?? 0,
+        message: errorMessage,
+      };
+      return Schema.decodeUnknownEffect(matched.schema)(errorData).pipe(
+        Effect.flatMap((decoded: unknown) => Effect.fail(decoded)),
+        Effect.catchIf(
+          (e: unknown) =>
+            typeof e === "object" &&
+            e !== null &&
+            "_tag" in e &&
+            (e as any)._tag === "SchemaError",
+          () =>
+            Effect.fail(
+              new UnknownCloudflareError({
+                code: errorCode,
+                message: errorMessage,
+              }),
+            ),
+        ),
+      ) as Effect.Effect<never, unknown>;
+    }
+  }
+
+  // Check global error codes before falling through to unknown
+  if (errorCode !== undefined && errorCode in GLOBAL_ERROR_CODE_MAP) {
+    return Effect.fail(GLOBAL_ERROR_CODE_MAP[errorCode](errorMessage));
+  }
+
+  // No match — return unknown Cloudflare error
+  return Effect.fail(
+    new UnknownCloudflareError({
+      code: errorCode,
+      message: errorMessage,
+    }),
+  );
+};
+
+/**
+ * Wrap schema decode failures as CloudflareHttpError to match the original's behavior.
+ * The original project maps all decode errors to CloudflareHttpError (not a separate parse error type).
+ */
+class CloudflareDecodeError extends CloudflareHttpError {
+  constructor(props: { body: unknown; cause: unknown }) {
+    super({
+      status: 200,
+      statusText: "Schema decode failed",
+      body:
+        typeof props.body === "string"
+          ? props.body
+          : JSON.stringify(props.body),
+    });
+  }
+}
+
+const _API = makeAPI({
+  credentials: Credentials as any,
+  getBaseUrl: (creds: any) => creds.apiBaseUrl,
+  getAuthHeaders: (creds: any) => ({
+    Authorization: `Bearer ${creds.apiToken}`,
+  }),
+  matchError,
+  ParseError: CloudflareDecodeError as any,
+  transformResponse: (body: unknown) => {
+    // Cloudflare API wraps responses in { result: <data>, success, errors, messages }
+    if (typeof body === "object" && body !== null && "result" in body) {
+      // result: null is common for delete operations — treat as empty object
+      return (body as any).result ?? {};
+    }
+    return body;
+  },
+});
+
+export const make = _API.make;
+export const makePaginated = _API.makePaginated;

package/src/client/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Cloudflare API Client.
+ *
+ * Re-exports the API operations factory for use by generated services
+ * and by external consumers.
+ */
+export * from "./api.ts";

package/src/credentials.ts

@@ -0,0 +1,30 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as ServiceMap from "effect/ServiceMap";
+import { ConfigError } from "@distilled.cloud/core/errors";
+
+export const DEFAULT_API_BASE_URL = "https://api.cloudflare.com/client/v4";
+
+export interface Config {
+  readonly apiToken: string;
+  readonly apiBaseUrl: string;
+}
+
+export class Credentials extends ServiceMap.Service<Credentials, Config>()(
+  "CloudflareCredentials",
+) {}
+
+export const CredentialsFromEnv = Layer.effect(
+  Credentials,
+  Effect.gen(function* () {
+    const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+
+    if (!apiToken) {
+      return yield* new ConfigError({
+        message: "CLOUDFLARE_API_TOKEN environment variable is required",
+      });
+    }
+
+    return { apiToken, apiBaseUrl: DEFAULT_API_BASE_URL };
+  }),
+);

package/src/errors.ts

@@ -0,0 +1,57 @@
+/**
+ * Cloudflare-specific error types.
+ */
+export {
+  BadGateway,
+  BadRequest,
+  Conflict,
+  ConfigError,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  UnprocessableEntity,
+  HTTP_STATUS_MAP,
+  DEFAULT_ERRORS,
+  API_ERRORS,
+} from "@distilled.cloud/core/errors";
+export type { DefaultErrors } from "@distilled.cloud/core/errors";
+
+import * as Schema from "effect/Schema";
+import * as Category from "@distilled.cloud/core/category";
+
+// Schema parse error wrapper
+export class CloudflareParseError extends Schema.TaggedErrorClass<CloudflareParseError>()(
+  "CloudflareParseError",
+  {
+    body: Schema.Unknown,
+    cause: Schema.Unknown,
+  },
+).pipe(Category.withParseError) {}
+
+/**
+ * Unknown Cloudflare error - returned when an error code is not recognized.
+ * Contains the raw error code for later cataloging.
+ */
+export class UnknownCloudflareError extends Schema.TaggedErrorClass<UnknownCloudflareError>()(
+  "UnknownCloudflareError",
+  {
+    code: Schema.optional(Schema.Number),
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * HTTP error - non-2xx response without a parseable Cloudflare error body.
+ */
+export class CloudflareHttpError extends Schema.TaggedErrorClass<CloudflareHttpError>()(
+  "CloudflareHttpError",
+  {
+    status: Schema.Number,
+    statusText: Schema.String,
+    body: Schema.optional(Schema.String),
+  },
+) {}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Cloudflare SDK for Effect
+ */
+export * from "./credentials.ts";
+export * as Category from "./category.ts";
+export * as T from "./traits.ts";
+export * as Retry from "./retry.ts";
+export * as API from "./client/api.ts";
+export * from "./errors.ts";

package/src/retry.ts

@@ -0,0 +1,35 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as ServiceMap from "effect/ServiceMap";
+export {
+  type Options,
+  type Factory,
+  type Policy,
+  makeDefault,
+  jittered,
+  capped,
+  throttlingOptions,
+  transientOptions,
+} from "@distilled.cloud/core/retry";
+import {
+  type Policy,
+  throttlingOptions,
+  transientOptions,
+} from "@distilled.cloud/core/retry";
+
+export class Retry extends ServiceMap.Service<Retry, Policy>()(
+  "CloudflareRetry",
+) {}
+
+export const policy = (optionsOrFactory: Policy) =>
+  Effect.provide(Layer.succeed(Retry, optionsOrFactory));
+
+export const none = Effect.provide(
+  Layer.succeed(Retry, { while: () => false }),
+);
+
+/** Apply throttling retry policy (retries throttling errors indefinitely) */
+export const throttling = policy(throttlingOptions);
+
+/** Apply transient retry policy (retries all transient errors indefinitely) */
+export const transient = policy(transientOptions);

package/src/schemas.ts

@@ -0,0 +1,51 @@
+/**
+ * Common schemas for Cloudflare API types.
+ *
+ * Includes file upload schemas for multipart form-data operations.
+ */
+
+import * as Schema from "effect/Schema";
+
+// =============================================================================
+// File Upload Schemas
+// =============================================================================
+
+/**
+ * Schema for File objects (browser File API).
+ *
+ * Used for multipart form-data file uploads.
+ */
+export const FileSchema = Schema.declare(
+  (input): input is File =>
+    typeof File !== "undefined" && input instanceof File,
+  {
+    identifier: "File",
+    description: "A File object for upload",
+  },
+);
+
+/**
+ * Schema for Blob objects.
+ *
+ * Used for binary data uploads.
+ */
+export const BlobSchema = Schema.declare(
+  (input): input is Blob =>
+    typeof Blob !== "undefined" && input instanceof Blob,
+  {
+    identifier: "Blob",
+    description: "A Blob object for upload",
+  },
+);
+
+/**
+ * Schema for uploadable content (File or Blob).
+ *
+ * Accepts any file-like object that can be uploaded via multipart form.
+ */
+export const UploadableSchema = Schema.Union([FileSchema, BlobSchema]);
+
+/**
+ * TypeScript type for uploadable content.
+ */
+export type Uploadable = File | Blob;