fix(cloudflare): tag Turnstile missing widgets as NotFound

packages/cloudflare/patches/turnstile/deleteWidget.json

@@ -0,0 +1,5 @@
+{
+  "errors": {
+    "NotFound": [{ "status": 404 }]
+  }
+}

packages/cloudflare/patches/turnstile/getWidget.json

@@ -0,0 +1,5 @@
+{
+  "errors": {
+    "NotFound": [{ "status": 404 }]
+  }
+}

packages/cloudflare/scripts/generate.ts

@@ -180,7 +180,7 @@ interface OperationPatch {
   errors: Record<
     string,
     Array<{
-      code: number;
+      code?: number;
       status?: number;
       message?: { includes?: string; matches?: string };
     }>

packages/cloudflare/specs/cloudflare/turnstile.openapi.yml

@@ -215,6 +215,9 @@ paths:
                   - secret
                   - sitekey
       x-distilled-response-path: result
+      x-distilled-errors:
+        NotFound:
+          - status: 404
     put:
       operationId: updateWidget
       description: "Update the configuration of a widget.  @example ```ts const widget
@@ -464,6 +467,9 @@ paths:
                   - secret
                   - sitekey
       x-distilled-response-path: result
+      x-distilled-errors:
+        NotFound:
+          - status: 404
   /accounts/{account_id}/challenges/widgets:
     get:
       operationId: listWidgets

packages/cloudflare/src/client/api.ts

@@ -256,10 +256,59 @@ function findMatchingError(
   return bestMatch;
 }
 
+// Some Cloudflare endpoints return bare HTTP failures instead of the standard
+// `{ success: false, errors: [...] }` envelope. Generated operation schemas can
+// still declare status-based error matchers, so try those before falling back
+// to generic HTTP errors.
+function matchOperationError(
+  errors: readonly ApiErrorClass[] | undefined,
+  code: number | undefined,
+  status: number,
+  message: string,
+): Effect.Effect<never, unknown> | undefined {
+  if (!errors || errors.length === 0) return undefined;
+
+  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, code, status, message);
+  if (!matched) return undefined;
+
+  const errorData = {
+    _tag: matched.tag,
+    code: code ?? 0,
+    message,
+  };
+  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,
+            message,
+          }),
+        ),
+    ),
+  ) as Effect.Effect<never, unknown>;
+}
+
 /**
  * Match a Cloudflare API error response using per-operation error schemas.
  */
-const matchError = (
+export const matchCloudflareError = (
   status: number,
   errorBody: unknown,
   errors?: readonly ApiErrorClass[],
@@ -272,6 +321,12 @@ const matchError = (
     "_nonJsonError" in errorBody;
   if (isNonJsonError) {
     const message = String((errorBody as any).body);
+    // Some Cloudflare endpoints return bare HTTP errors without the standard
+    // `{ success: false, errors: [...] }` envelope. Give operation-specific
+    // status matchers a chance before falling back to generic HTTP errors.
+    const matched = matchOperationError(errors, undefined, status, message);
+    if (matched) return matched;
+
     // For 5xx errors, return a properly categorized error so retries work
     if (status >= 500) {
       return Effect.fail(httpStatusError(status, message, headers));
@@ -316,6 +371,12 @@ const matchError = (
     // For 5xx errors, return a properly categorized error so retries work
     const bodyStr =
       typeof errorBody === "string" ? errorBody : JSON.stringify(errorBody);
+    // Preserve per-operation error typing for endpoints whose error responses
+    // are JSON but not Cloudflare envelopes, such as Turnstile's missing-widget
+    // 404 response.
+    const matched = matchOperationError(errors, undefined, status, bodyStr);
+    if (matched) return matched;
+
     if (status >= 500) {
       return Effect.fail(httpStatusError(status, bodyStr, headers));
     }
@@ -329,51 +390,8 @@ const matchError = (
     );
   }
 
-  // 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>;
-    }
-  }
+  const matched = matchOperationError(errors, errorCode, status, errorMessage);
+  if (matched) return matched;
 
   // Check global error codes before falling through to unknown
   if (errorCode !== undefined && errorCode in GLOBAL_ERROR_CODE_MAP) {
@@ -462,7 +480,7 @@ const _API = makeAPI<Credentials>({
   credentials: Credentials as any,
   getBaseUrl: (creds: any) => creds.apiBaseUrl,
   getAuthHeaders: formatHeaders as any,
-  matchError,
+  matchError: matchCloudflareError,
   ParseError: CloudflareDecodeError as any,
   transformRequestParts: ({ pathTemplate, parts }) =>
     transformCloudflareRequestParts({ pathTemplate, parts }),

packages/cloudflare/src/services/turnstile.ts

@@ -12,6 +12,16 @@ import * as T from "../traits.ts";
 import type { Credentials } from "../credentials.ts";
 import { type DefaultErrors } from "../errors.ts";
 
+// =============================================================================
+// Errors
+// =============================================================================
+
+export class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+  code: Schema.Number,
+  message: Schema.String,
+}) {}
+T.applyErrorMatchers(NotFound, [{ status: 404 }]);
+
 // =============================================================================
 // SecretWidget
 // =============================================================================
@@ -201,7 +211,7 @@ export const GetWidgetResponse = /*@__PURE__*/ /*#__PURE__*/ Schema.Struct({
     T.ResponsePath("result"),
   ) as unknown as Schema.Schema<GetWidgetResponse>;
 
-export type GetWidgetError = DefaultErrors;
+export type GetWidgetError = DefaultErrors | NotFound;
 
 export const getWidget: API.OperationMethod<
   GetWidgetRequest,
@@ -211,7 +221,7 @@ export const getWidget: API.OperationMethod<
 > = /*@__PURE__*/ /*#__PURE__*/ API.make(() => ({
   input: GetWidgetRequest,
   output: GetWidgetResponse,
-  errors: [],
+  errors: [NotFound],
 }));
 
 export interface ListWidgetsRequest {
@@ -690,7 +700,7 @@ export const DeleteWidgetResponse = /*@__PURE__*/ /*#__PURE__*/ Schema.Struct({
     T.ResponsePath("result"),
   ) as unknown as Schema.Schema<DeleteWidgetResponse>;
 
-export type DeleteWidgetError = DefaultErrors;
+export type DeleteWidgetError = DefaultErrors | NotFound;
 
 export const deleteWidget: API.OperationMethod<
   DeleteWidgetRequest,
@@ -700,5 +710,5 @@ export const deleteWidget: API.OperationMethod<
 > = /*@__PURE__*/ /*#__PURE__*/ API.make(() => ({
   input: DeleteWidgetRequest,
   output: DeleteWidgetResponse,
-  errors: [],
+  errors: [NotFound],
 }));

packages/cloudflare/test/client-api.test.ts

@@ -1,8 +1,13 @@
 import { describe, expect, it } from "vitest";
 import { buildRequestParts, getHttpTrait } from "@distilled.cloud/core/traits";
+import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { transformCloudflareRequestParts } from "~/client/api";
+import {
+  matchCloudflareError,
+  transformCloudflareRequestParts,
+} from "~/client/api";
 import { CreateAssetUploadRequest, PutScriptRequest } from "~/services/workers";
+import { NotFound as TurnstileNotFound } from "~/services/turnstile";
 import {
   GetPhasResponse,
   PutPhasForAccountRequest,
@@ -60,6 +65,26 @@ describe("client api", () => {
     });
   });
 
+  it("matches operation errors on non-json Cloudflare error responses", () =>
+    matchCloudflareError(
+      404,
+      { _nonJsonError: true, body: "widget not found" },
+      [TurnstileNotFound],
+    ).pipe(
+      Effect.flip,
+      Effect.map((error) => expect(error._tag).toBe("NotFound")),
+      Effect.runPromise,
+    ));
+
+  it("matches operation errors on non-envelope Cloudflare error responses", () =>
+    matchCloudflareError(404, { error: "widget not found" }, [
+      TurnstileNotFound,
+    ]).pipe(
+      Effect.flip,
+      Effect.map((error) => expect(error._tag).toBe("NotFound")),
+      Effect.runPromise,
+    ));
+
   it("encodes Worker script uploads with ratelimit bindings", () => {
     const httpTrait = getHttpTrait(PutScriptRequest.ast);
     expect(httpTrait).toBeDefined();