@distilled.cloud/cloudflare 0.2.5-alpha2 → 0.3.0-alpha

package/src/client/api.ts

@@ -8,12 +8,20 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import type * as AST from "effect/SchemaAST";
+import * as Stream from "effect/Stream";
 import {
   makeAPI,
   type ApiErrorClass,
   type OperationMethod,
   type PaginatedOperationMethod,
 } from "@distilled.cloud/core/client";
+import {
+  paginateCursor,
+  paginateSingle,
+  paginateWithDefaults,
+  type PaginationStrategy,
+} from "@distilled.cloud/core/pagination";
+import { getPath, type RequestParts } from "@distilled.cloud/core/traits";
 import {
   CloudflareHttpError,
   HTTP_STATUS_MAP,
@@ -21,7 +29,7 @@ import {
   TooManyRequests,
   UnknownCloudflareError,
 } from "../errors.ts";
-import { Credentials } from "../credentials.ts";
+import { Credentials, formatHeaders } from "../credentials.ts";
 import { type ErrorMatcher, getErrorMatchers } from "../traits.ts";
 
 // ============================================================================
@@ -307,23 +315,107 @@ class CloudflareDecodeError extends CloudflareHttpError {
   }
 }
 
+const ASSET_UPLOAD_PATH = "/accounts/{account_id}/workers/assets/upload";
+
+export const transformCloudflareRequestParts = ({
+  pathTemplate,
+  parts,
+}: {
+  pathTemplate: string;
+  parts: RequestParts;
+}): RequestParts => {
+  if (pathTemplate !== ASSET_UPLOAD_PATH) {
+    return parts;
+  }
+
+  const authorization = parts.headers.Authorization;
+  if (!authorization || authorization.startsWith("Bearer ")) {
+    return parts;
+  }
+
+  return {
+    ...parts,
+    headers: {
+      ...parts.headers,
+      Authorization: `Bearer ${authorization}`,
+    },
+  };
+};
+
 const _API = makeAPI({
   credentials: Credentials as any,
   getBaseUrl: (creds: any) => creds.apiBaseUrl,
-  getAuthHeaders: (creds: any) => ({
-    Authorization: `Bearer ${creds.apiToken}`,
-  }),
+  getAuthHeaders: formatHeaders,
   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;
-  },
+  transformRequestParts: ({ pathTemplate, parts }) =>
+    transformCloudflareRequestParts({ pathTemplate, parts }),
 });
 
+const paginatePageByItems: PaginationStrategy = (
+  operation,
+  input,
+  pagination,
+) => {
+  const inputToken = pagination.inputToken;
+  if (!inputToken) {
+    return Stream.die(
+      new Error("Cloudflare page pagination requires an inputToken"),
+    );
+  }
+
+  type State = { page: number; done: boolean };
+  const startPage =
+    typeof input[inputToken] === "number" ? (input[inputToken] as number) : 1;
+
+  return Stream.unfold({ page: startPage, done: false } as State, (state) =>
+    Effect.gen(function* () {
+      if (state.done) return undefined;
+
+      const requestPayload = { ...input, [inputToken]: state.page };
+      const response = yield* operation(requestPayload);
+      const items =
+        pagination.items !== undefined
+          ? (getPath(response, pagination.items) as
+              | readonly unknown[]
+              | undefined)
+          : undefined;
+
+      return [
+        response,
+        {
+          page: state.page + 1,
+          done: (items ?? []).length === 0,
+        },
+      ] as const;
+    }),
+  );
+};
+
+const cloudflarePaginate: PaginationStrategy = (
+  operation,
+  input,
+  pagination,
+) => {
+  switch (pagination.mode) {
+    case "single":
+      return paginateSingle(operation, input, pagination);
+    case "page":
+      return paginatePageByItems(operation, input, pagination);
+    case "cursor":
+      return paginateCursor(operation, input, pagination);
+    case "token":
+    default:
+      return paginateWithDefaults(operation, input, pagination);
+  }
+};
+
 export const make = _API.make;
-export const makePaginated = _API.makePaginated;
+export const makePaginated = ((
+  configFn: any,
+  paginateFn?: PaginationStrategy,
+) =>
+  _API.makePaginated(
+    configFn,
+    paginateFn ?? cloudflarePaginate,
+  )) as typeof _API.makePaginated;

package/src/credentials.ts

@@ -1,30 +1,271 @@
+import { ConfigError } from "@distilled.cloud/core/errors";
+import * as Config from "effect/Config";
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
 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 {
+const CREDENTIAL_REFRESH_WINDOW_MS = 5 * 60 * 1000;
+
+export interface ApiTokenConfig {
   readonly apiToken: string;
+  readonly apiBaseUrl?: string;
+}
+
+export interface ApiKeyConfig {
+  readonly apiKey: string;
+  readonly email: string;
+  readonly apiBaseUrl?: string;
+}
+
+export interface OAuthConfig {
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+  readonly expiresAt?: number;
+}
+
+export interface OAuthProvider<R = never> {
+  readonly load: Effect.Effect<OAuthConfig, unknown, R>;
+  readonly refresh: (
+    credentials: OAuthConfig,
+  ) => Effect.Effect<OAuthConfig, unknown, R>;
+  readonly apiBaseUrl?: string;
+}
+
+export interface ApiTokenCredentials {
+  readonly type: "apiToken";
+  readonly apiToken: Redacted.Redacted<string>;
+  readonly apiBaseUrl: string;
+}
+
+export interface ApiKeyCredentials {
+  readonly type: "apiKey";
+  readonly apiKey: Redacted.Redacted<string>;
+  readonly email: string;
+  readonly apiBaseUrl: string;
+}
+
+export interface OAuthCredentials {
+  readonly type: "oauth";
+  readonly accessToken: Redacted.Redacted<string>;
+  readonly refreshToken: Redacted.Redacted<string> | undefined;
+  readonly expiresAt?: number;
   readonly apiBaseUrl: string;
 }
 
-export class Credentials extends ServiceMap.Service<Credentials, Config>()(
-  "CloudflareCredentials",
-) {}
+export type ResolvedCredentials =
+  | ApiTokenCredentials
+  | ApiKeyCredentials
+  | OAuthCredentials;
 
-export const CredentialsFromEnv = Layer.effect(
+export class OAuthRefreshError extends Data.TaggedError(
+  "CloudflareOAuthRefreshError",
+)<{
+  message: string;
+  cause?: unknown;
+}> {}
+
+export type CredentialsError = ConfigError | OAuthRefreshError;
+
+export class Credentials extends ServiceMap.Service<
   Credentials,
+  Effect.Effect<ResolvedCredentials, CredentialsError, any>
+>()("CloudflareCredentials") {}
+
+const resolveApiBaseUrl = (apiBaseUrl?: string): string =>
+  apiBaseUrl ?? DEFAULT_API_BASE_URL;
+
+export const apiTokenCredentials = (
+  config: ApiTokenConfig,
+): ApiTokenCredentials => ({
+  type: "apiToken",
+  apiToken: Redacted.make(config.apiToken),
+  apiBaseUrl: resolveApiBaseUrl(config.apiBaseUrl),
+});
+
+export const apiKeyCredentials = (config: ApiKeyConfig): ApiKeyCredentials => ({
+  type: "apiKey",
+  apiKey: Redacted.make(config.apiKey),
+  email: config.email,
+  apiBaseUrl: resolveApiBaseUrl(config.apiBaseUrl),
+});
+
+export const oauthCredentials = (
+  config: OAuthConfig,
+  apiBaseUrl?: string,
+): OAuthCredentials => ({
+  type: "oauth",
+  accessToken: Redacted.make(config.accessToken),
+  refreshToken: config.refreshToken
+    ? Redacted.make(config.refreshToken)
+    : undefined,
+  expiresAt: config.expiresAt,
+  apiBaseUrl: resolveApiBaseUrl(apiBaseUrl),
+});
+
+const getRefreshAt = (credentials: ResolvedCredentials): number => {
+  if (credentials.type !== "oauth" || credentials.expiresAt === undefined) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return credentials.expiresAt <= Date.now() + CREDENTIAL_REFRESH_WINDOW_MS
+    ? credentials.expiresAt
+    : credentials.expiresAt - CREDENTIAL_REFRESH_WINDOW_MS;
+};
+
+const isExpired = (expiresAt?: number): boolean =>
+  expiresAt !== undefined &&
+  Date.now() >= expiresAt - CREDENTIAL_REFRESH_WINDOW_MS;
+
+const createCachedCredentialsEffect = <E, R>(
+  resolve: Effect.Effect<ResolvedCredentials, E, R>,
+): Effect.Effect<ResolvedCredentials, E, R> => {
+  let cachedCreds: ResolvedCredentials | undefined;
+  let refreshAt = 0;
+
+  return Effect.suspend(() => {
+    const now = Date.now();
+    if (cachedCreds && now < refreshAt) {
+      return Effect.succeed(cachedCreds);
+    }
+
+    return Effect.map(resolve, (credentials) => {
+      cachedCreds = credentials;
+      refreshAt = getRefreshAt(credentials);
+      return credentials;
+    });
+  });
+};
+
+const wrapOAuthError = <A, R>(
+  message: string,
+  effect: Effect.Effect<A, unknown, R>,
+): Effect.Effect<A, OAuthRefreshError, R> =>
+  effect.pipe(
+    Effect.mapError(
+      (cause) =>
+        new OAuthRefreshError({
+          message,
+          cause,
+        }),
+    ),
+  );
+
+export const fromApiToken = (
+  config: ApiTokenConfig,
+): Layer.Layer<Credentials> =>
+  Layer.succeed(Credentials, Effect.succeed(apiTokenCredentials(config)));
+
+export const fromApiKey = (config: ApiKeyConfig): Layer.Layer<Credentials> =>
+  Layer.succeed(Credentials, Effect.succeed(apiKeyCredentials(config)));
+
+export const fromOAuth = <R>(
+  provider: OAuthProvider<R>,
+): Layer.Layer<Credentials, never, R> => {
+  let currentCredentials: OAuthConfig | undefined;
+
+  const resolve = Effect.gen(function* () {
+    const loadedCredentials =
+      currentCredentials ??
+      (yield* wrapOAuthError(
+        "Failed to load Cloudflare OAuth credentials.",
+        provider.load,
+      ));
+
+    const credentials = isExpired(loadedCredentials.expiresAt)
+      ? yield* wrapOAuthError(
+          "Failed to refresh Cloudflare OAuth credentials.",
+          provider.refresh(loadedCredentials),
+        )
+      : loadedCredentials;
+
+    currentCredentials = credentials;
+    return oauthCredentials(credentials, provider.apiBaseUrl);
+  });
+
+  return Layer.succeed(Credentials, createCachedCredentialsEffect(resolve));
+};
+
+const fromConfigError = (message: string) => () =>
+  new ConfigError({
+    message,
+  });
+
+const envConfig = Config.all({
+  apiToken: Config.option(Config.string("CLOUDFLARE_API_TOKEN")),
+  apiKey: Config.option(Config.string("CLOUDFLARE_API_KEY")),
+  email: Config.option(Config.string("CLOUDFLARE_EMAIL")),
+  apiBaseUrl: Config.string("CLOUDFLARE_API_BASE_URL").pipe(
+    Config.withDefault(DEFAULT_API_BASE_URL),
+  ),
+});
+
+export const resolveFromEnv: Effect.Effect<ResolvedCredentials, ConfigError> =
   Effect.gen(function* () {
-    const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+    const config = yield* envConfig
+      .asEffect()
+      .pipe(
+        Effect.mapError(
+          fromConfigError("Failed to load Cloudflare credentials from config"),
+        ),
+      );
+    const apiToken = Option.getOrUndefined(config.apiToken);
+    const apiKey = Option.getOrUndefined(config.apiKey);
+    const email = Option.getOrUndefined(config.email);
+    const apiBaseUrl = config.apiBaseUrl;
+
+    if (apiToken) {
+      return apiTokenCredentials({ apiToken, apiBaseUrl });
+    }
+
+    if (apiKey && email) {
+      return apiKeyCredentials({ apiKey, email, apiBaseUrl });
+    }
+
+    if (apiKey && !email) {
+      return yield* new ConfigError({
+        message:
+          "CLOUDFLARE_EMAIL environment variable is required when using CLOUDFLARE_API_KEY",
+      });
+    }
 
-    if (!apiToken) {
+    if (!apiKey && email) {
       return yield* new ConfigError({
-        message: "CLOUDFLARE_API_TOKEN environment variable is required",
+        message:
+          "CLOUDFLARE_API_KEY environment variable is required when using CLOUDFLARE_EMAIL",
       });
     }
 
-    return { apiToken, apiBaseUrl: DEFAULT_API_BASE_URL };
-  }),
-);
+    return yield* new ConfigError({
+      message:
+        "Either CLOUDFLARE_API_TOKEN or CLOUDFLARE_API_KEY+CLOUDFLARE_EMAIL environment variables are required",
+    });
+  });
+
+export const fromEnv = (): Layer.Layer<Credentials> =>
+  Layer.succeed(Credentials, resolveFromEnv);
+
+export const CredentialsFromEnv = fromEnv();
+
+export const formatHeaders = (
+  credentials: ResolvedCredentials,
+): Record<string, string> => {
+  switch (credentials.type) {
+    case "apiKey":
+      return {
+        "X-Auth-Key": Redacted.value(credentials.apiKey),
+        "X-Auth-Email": credentials.email,
+      };
+    case "apiToken":
+      return {
+        Authorization: `Bearer ${Redacted.value(credentials.apiToken)}`,
+      };
+    case "oauth":
+      return {
+        Authorization: `Bearer ${Redacted.value(credentials.accessToken)}`,
+      };
+  }
+};

package/src/errors.ts

@@ -18,7 +18,7 @@ export {
   DEFAULT_ERRORS,
   API_ERRORS,
 } from "@distilled.cloud/core/errors";
-export type { DefaultErrors } from "@distilled.cloud/core/errors";
+import type { DefaultErrors as CoreDefaultErrors } from "@distilled.cloud/core/errors";
 
 import * as Schema from "effect/Schema";
 import * as Category from "@distilled.cloud/core/category";
@@ -55,3 +55,19 @@ export class CloudflareHttpError extends Schema.TaggedErrorClass<CloudflareHttpE
     body: Schema.optional(Schema.String),
   },
 ) {}
+
+/**
+ * Errors that any Cloudflare operation may surface in addition to status/code-
+ * matched API errors declared per endpoint.
+ */
+export type ClientErrors =
+  | CloudflareHttpError
+  | CloudflareParseError
+  | UnknownCloudflareError;
+
+/**
+ * Default Cloudflare operation errors include the shared HTTP status errors from
+ * core plus the client-level fallback/decode errors that the Cloudflare client
+ * can emit at runtime.
+ */
+export type DefaultErrors = CoreDefaultErrors | ClientErrors;

package/src/sensitive.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export sensitive data schemas from sdk-core.
+ */
+export * from "@distilled.cloud/core/sensitive";