alchemy 0.50.0 → 0.51.0

package/src/cloudflare/api-gateway-operation.ts

@@ -0,0 +1,340 @@
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { handleApiError } from "./api-error.ts";
+import type { APIMitigation } from "./api-mitigation.ts";
+import {
+  createCloudflareApi,
+  type CloudflareApi,
+  type CloudflareApiOptions,
+} from "./api.ts";
+import type { Zone } from "./zone.ts";
+
+/**
+ * HTTP methods supported by API Gateway
+ */
+export type HTTPMethod =
+  | "get"
+  | "post"
+  | "put"
+  | "patch"
+  | "delete"
+  | "head"
+  | "options"
+  | "trace";
+
+/**
+ * Properties for creating or updating an API Operation
+ */
+export interface APIGatewayOperationProps extends CloudflareApiOptions {
+  /**
+   * The zone this operation belongs to
+   */
+  zone: string | Zone;
+
+  /**
+   * The API endpoint path (can contain path variables like /users/{id})
+   */
+  endpoint: string;
+
+  /**
+   * The host for this operation
+   */
+  host: string;
+
+  /**
+   * The HTTP method (GET, POST, PUT, DELETE, etc.)
+   */
+  method: string;
+
+  /**
+   * Mitigation action for this operation
+   * @default "none"
+   */
+  mitigation?: APIMitigation;
+}
+
+/**
+ * API Operation output
+ */
+export interface APIGatewayOperation
+  extends Resource<"cloudflare::APIGatewayOperation"> {
+  /**
+   * Zone ID
+   */
+  zoneId: string;
+
+  /**
+   * Zone name
+   */
+  zoneName: string;
+
+  /**
+   * Operation ID assigned by Cloudflare
+   */
+  operationId: string;
+
+  /**
+   * The API endpoint path
+   */
+  endpoint: string;
+
+  /**
+   * The host for this operation
+   */
+  host: string;
+
+  /**
+   * The HTTP method
+   */
+  method: string;
+
+  /**
+   * The mitigation action for this operation
+   */
+  action: APIMitigation;
+}
+
+/**
+ * Cloudflare API Gateway Operation manages individual API endpoints that can be
+ * monitored, secured, and configured through Cloudflare's API Shield.
+ *
+ * Operations are the building blocks for API management, representing specific
+ * HTTP method + endpoint + host combinations that your API exposes.
+ *
+ * @example
+ * ## Basic API operation
+ *
+ * Create a simple GET endpoint for user retrieval
+ *
+ * const getUserOp = await APIGatewayOperation("get-users", {
+ *   zone: myZone,
+ *   endpoint: "/users",
+ *   host: "api.example.com",
+ *   method: "GET"
+ * });
+ *
+ * @example
+ * ## API operation with path parameters
+ *
+ * Create an operation that includes path variables
+ *
+ * const getUserByIdOp = await APIGatewayOperation("get-user-by-id", {
+ *   zone: "api.example.com",
+ *   endpoint: "/users/{id}",
+ *   host: "api.example.com",
+ *   method: "GET"
+ * });
+ *
+ * @example
+ * ## RESTful CRUD operations
+ *
+ * Create a complete set of CRUD operations for a resource
+ *
+ * const createUserOp = await APIGatewayOperation("create-user", {
+ *   zone: myZone,
+ *   endpoint: "/users",
+ *   host: "api.example.com",
+ *   method: "POST"
+ * });
+ *
+ * const updateUserOp = await APIGatewayOperation("update-user", {
+ *   zone: myZone,
+ *   endpoint: "/users/{id}",
+ *   host: "api.example.com",
+ *   method: "PUT"
+ * });
+ *
+ * const deleteUserOp = await APIGatewayOperation("delete-user", {
+ *   zone: myZone,
+ *   endpoint: "/users/{id}",
+ *   host: "api.example.com",
+ *   method: "DELETE"
+ * });
+ *
+ * @see https://developers.cloudflare.com/api/resources/api_gateway/subresources/operations/
+ * @see https://developers.cloudflare.com/api-shield/management-and-monitoring/endpoint-management/
+ */
+export const APIGatewayOperation = Resource(
+  "cloudflare::APIGatewayOperation",
+  async function (
+    this: Context<APIGatewayOperation>,
+    _id: string,
+    props: APIGatewayOperationProps,
+  ): Promise<APIGatewayOperation> {
+    const api = await createCloudflareApi(props);
+
+    // Resolve zone ID and name
+    const zoneId = typeof props.zone === "string" ? props.zone : props.zone.id;
+    const zoneName =
+      typeof props.zone === "string" ? props.zone : props.zone.name;
+
+    if (this.phase === "delete") {
+      if (this.output?.operationId) {
+        await deleteOperation(api, zoneId, this.output.operationId);
+      }
+      return this.destroy();
+    }
+    let operationId: string;
+    if (this.phase === "update") {
+      if (
+        props.endpoint !== this.output?.endpoint ||
+        props.host !== this.output?.host ||
+        props.method !== this.output?.method
+      ) {
+        // delete and then re-create (cloudflare doesn't allow updating these properties)
+        this.replace(true);
+      }
+      if (props.mitigation !== this.output?.action) {
+        // we can update the mitigation action
+        await updateOperationSettings(api, zoneId, this.output.operationId, {
+          mitigation_action: props.mitigation ?? null,
+        });
+      }
+      operationId = this.output.operationId;
+    } else {
+      const operation = await createOperation(api, zoneId, props);
+      operationId = operation.operation_id;
+
+      if (props.mitigation) {
+        await updateOperationSettings(api, zoneId, operationId, {
+          mitigation_action: props.mitigation ?? "none",
+        });
+      }
+    }
+
+    return this({
+      zoneId,
+      zoneName,
+      operationId,
+      endpoint: props.endpoint,
+      host: props.host,
+      method: props.method.toUpperCase(),
+      action: props.mitigation ?? null,
+    });
+  },
+);
+
+async function createOperation(
+  api: CloudflareApi,
+  zoneId: string,
+  props: APIGatewayOperationProps,
+) {
+  // Create the operation
+  const response = await api.post(
+    `/zones/${zoneId}/api_gateway/operations/item`,
+    {
+      endpoint: props.endpoint,
+      host: props.host,
+      method: props.method.toUpperCase(),
+    },
+  );
+
+  if (!response.ok) {
+    await handleApiError(
+      response,
+      "creating",
+      "operation",
+      `${props.method} ${props.endpoint}`,
+    );
+  }
+
+  const data = (await response.json()) as {
+    result: {
+      operation_id: string;
+      endpoint: string;
+      host: string;
+      method: string;
+      last_updated: string;
+    };
+  };
+
+  return data.result;
+}
+
+async function deleteOperation(
+  api: CloudflareApi,
+  zoneId: string,
+  operationId: string,
+) {
+  const deleteResponse = await api.delete(
+    `/zones/${zoneId}/api_gateway/operations/${operationId}`,
+  );
+
+  if (!deleteResponse.ok && deleteResponse.status !== 404) {
+    await handleApiError(deleteResponse, "deleting", "operation", operationId);
+  }
+}
+
+/**
+ * Update validation settings for a specific operation
+ */
+async function updateOperationSettings(
+  api: CloudflareApi,
+  zoneId: string,
+  operationId: string,
+  params: {
+    mitigation_action: APIMitigation;
+  },
+): Promise<void> {
+  const response = await api.put(
+    `/zones/${zoneId}/schema_validation/settings/operations/${operationId}`,
+    params,
+  );
+
+  if (!response.ok) {
+    await handleApiError(
+      response,
+      "updating",
+      "operation settings",
+      operationId,
+    );
+  }
+}
+
+export interface CloudflareOperation {
+  operation_id: string;
+  method: string;
+  host: string;
+  endpoint: string;
+}
+
+export async function getOperations(
+  api: CloudflareApi,
+  zoneId: string,
+): Promise<CloudflareOperation[]> {
+  const response = await api.get(`/zones/${zoneId}/api_gateway/operations`);
+
+  if (!response.ok) {
+    await handleApiError(response, "getting", "operations");
+  }
+
+  return ((await response.json()) as { result: CloudflareOperation[] }).result;
+}
+
+export async function getOperationSchemaValidationSetting(
+  api: CloudflareApi,
+  zoneId: string,
+  operationId: string,
+) {
+  const response = await api.get(
+    `/zones/${zoneId}/schema_validation/settings/operations/${operationId}`,
+  );
+
+  if (!response.ok) {
+    await handleApiError(
+      response,
+      "getting",
+      "operation mitigation status",
+      operationId,
+    );
+  }
+
+  const data = (await response.json()) as {
+    result: {
+      mitigation_action: APIMitigation;
+      operation_id: string;
+    };
+  };
+
+  return data.result;
+}

package/src/cloudflare/api-mitigation.ts

@@ -0,0 +1,22 @@
+import type { OpenAPIV3 } from "openapi-types";
+
+/**
+ * Specifies the mitigation action to apply when a request does not conform to
+ * the schema for this operation:
+ * - `"log"`: Log the request.
+ * - `"block"`: Deny access to the site.
+ * - `"none"`: Skip mitigation for this operation.
+ * - `null`: Clear any mitigation action.
+ */
+export type APIMitigation = "none" | "log" | "block" | null;
+
+/**
+ * Mitigation actions for a given API schema.
+ */
+export type APIMitigations<S extends OpenAPIV3.Document> = {
+  [path in keyof S["paths"]]?:
+    | APIMitigation
+    | {
+        [method in keyof S["paths"][path]]?: APIMitigation;
+      };
+};

package/src/cloudflare/api-schema.ts

@@ -0,0 +1,364 @@
+import type { OpenAPIV3 } from "openapi-types";
+import * as yaml from "yaml";
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { CloudflareApiError, handleApiError } from "./api-error.ts";
+import {
+  createCloudflareApi,
+  type CloudflareApi,
+  type CloudflareApiOptions,
+} from "./api.ts";
+import type { Zone } from "./zone.ts";
+import { findZoneForHostname } from "./zone.ts";
+
+/**
+ * Properties for creating or updating a Schema
+ */
+export interface APISchemaProps<S extends OpenAPIV3.Document>
+  extends CloudflareApiOptions {
+  /**
+   * The zone to upload the schema to
+   */
+  zone: string | Zone;
+
+  /**
+   * OpenAPI v3.0.x schema content (YAML string, JSON string, or OpenAPI object)
+   * Provide either this or schemaFile
+   *
+   * Note: Cloudflare only supports OpenAPI v3.0.x, not v3.1
+   */
+  schema: S;
+
+  /**
+   * Name for the schema
+   * @default resource id
+   */
+  name?: string;
+
+  /**
+   * Enable validation immediately after upload
+   *
+   * Warning: will trigger a replace when disabling validation.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * APISchema resource attributes.
+ */
+export interface APISchema<S extends OpenAPIV3.Document = OpenAPIV3.Document>
+  extends Resource<"cloudflare::APISchema"> {
+  /**
+   * Schema ID
+   */
+  id: string;
+
+  /**
+   * Name for the schema
+   */
+  name: string;
+
+  /**
+   * The API Schema
+   */
+  schema: S;
+
+  /**
+   * Source of the schema
+   */
+  source: string;
+
+  /**
+   * Whether validation is enabled
+   */
+  enabled: boolean;
+}
+
+/**
+ * Cloudflare API Gateway Schema manages OpenAPI v3 schemas for API validation.
+ *
+ * @example
+ * ## Basic schema upload with inline YAML
+ *
+ * const apiSchema = await APISchema("my-api-schema", {
+ *   zone: myZone,
+ *   name: "my-api-v1"
+ *   schema: `
+ *     openapi: 3.0.0
+ *     info:
+ *       title: My API
+ *       version: 1.0.0
+ *     servers:
+ *       - url: https://api.example.com
+ *     paths:
+ *       /users:
+ *         get:
+ *           operationId: getUsers
+ *           responses:
+ *             '200':
+ *               description: Success
+ *   `,
+ * });
+ *
+ * @example
+ * ## Schema upload from file
+ *
+ * const fileSchema = await APISchema("api-schema-from-file", {
+ *   zone: "example.com",
+ *   schemaFile: "./openapi.yaml",
+ *   name: "production-api-v2",
+ *   enabled: false  // Upload but don't enable validation yet
+ * });
+ *
+ * @example
+ * ## Schema with typed OpenAPI object
+ *
+ * import type { OpenAPIV3 } from "openapi-types";
+ *
+ * const typedSchema: OpenAPIV3.Document = {
+ *   openapi: "3.0.0",
+ *   info: { title: "Typed API", version: "1.0.0" },
+ *   paths: {
+ *     "/health": {
+ *       get: {
+ *         operationId: "healthCheck",
+ *         responses: { "200": { description: "OK" } }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const schema = await APISchema("typed-schema", {
+ *   zone: myZone,
+ *   schema: typedSchema
+ * });
+ */
+export const APISchema = Resource("cloudflare::APISchema", async function <
+  S extends OpenAPIV3.Document,
+>(this: Context<APISchema<S>>, id: string, props: APISchemaProps<S>): Promise<
+  APISchema<S>
+> {
+  const api = await createCloudflareApi(props);
+
+  // Resolve zone ID and name
+  const zoneId =
+    typeof props.zone === "string"
+      ? (await findZoneForHostname(api, props.zone)).zoneId
+      : props.zone.id;
+
+  if (this.phase === "delete") {
+    if (this.output?.id) {
+      await deleteSchema(api, zoneId, this.output.id);
+    }
+    return this.destroy();
+  }
+
+  // Load schema content
+  const parsedSchema = props.schema;
+
+  let schemaDetails: CloudflareSchemaDetails;
+
+  if (this.phase === "update" && this.output?.id) {
+    // Check if we need to replace due to name, schema content change, or disabling validation
+    if (
+      props.name !== this.output.name ||
+      JSON.stringify(parsedSchema) !== JSON.stringify(this.output.schema) ||
+      (this.output.enabled === true && props.enabled === false)
+    ) {
+      // Name, schema content changed, or trying to disable validation - need to replace
+      this.replace();
+    }
+
+    // Update existing schema (can only update validation_enabled)
+    schemaDetails = await updateSchema(api, zoneId, this.output.id, {
+      validation_enabled: props.enabled !== false,
+    });
+  } else {
+    // Create new schema
+    schemaDetails = await uploadSchema(api, zoneId, {
+      file: yaml.stringify(parsedSchema),
+      name: props.name || id,
+      validation_enabled: props.enabled !== false,
+    });
+  }
+
+  return this({
+    id: schemaDetails.id,
+    name: schemaDetails.name,
+    schema: parsedSchema as any,
+    source: schemaDetails.source,
+    enabled: schemaDetails.validationEnabled,
+  });
+});
+
+// API helper functions
+
+interface CloudflareSchemaDetails {
+  id: string;
+  name: string;
+  source: string;
+  validationEnabled: boolean;
+  createdAt: string;
+}
+
+interface CloudflareSchema {
+  schema_id: string;
+  name: string;
+  kind: string;
+  source: string;
+  validation_enabled: boolean;
+  created_at: string;
+  size?: number;
+  is_learned?: boolean;
+}
+
+async function uploadSchema(
+  api: CloudflareApi,
+  zoneId: string,
+  params: {
+    file: string;
+    name: string;
+    validation_enabled?: boolean;
+  },
+): Promise<CloudflareSchemaDetails> {
+  const body = {
+    source: params.file,
+    name: params.name,
+    kind: "openapi_v3",
+    validation_enabled: params.validation_enabled ?? true,
+  };
+
+  const response = await api.post(
+    `/zones/${zoneId}/schema_validation/schemas`,
+    body,
+  );
+
+  if (!response.ok) {
+    await handleApiError(response, "uploading", "schema", params.name);
+  }
+
+  const data = (await response.json()) as {
+    result: CloudflareSchema;
+  };
+  return {
+    id: data.result.schema_id,
+    name: data.result.name,
+    source: data.result.source,
+    validationEnabled: data.result.validation_enabled,
+    createdAt: data.result.created_at,
+  };
+}
+
+async function updateSchema(
+  api: CloudflareApi,
+  zoneId: string,
+  schemaId: string,
+  params: {
+    validation_enabled: boolean;
+  },
+): Promise<CloudflareSchemaDetails> {
+  const response = await api.patch(
+    `/zones/${zoneId}/schema_validation/schemas/${schemaId}`,
+    params,
+  );
+
+  if (!response.ok) {
+    await handleApiError(response, "updating", "schema", schemaId);
+  }
+
+  const data = (await response.json()) as { result: CloudflareSchema };
+  return {
+    id: data.result.schema_id,
+    name: data.result.name,
+    source: data.result.source,
+    validationEnabled: data.result.validation_enabled,
+    createdAt: data.result.created_at,
+  };
+}
+
+export async function deleteSchema(
+  api: CloudflareApi,
+  zoneId: string,
+  schemaId: string,
+): Promise<void> {
+  const response = await api.delete(
+    `/zones/${zoneId}/schema_validation/schemas/${schemaId}`,
+  );
+  const data = (await response.json()) as {
+    success: boolean;
+    errors: {
+      code: number;
+      message: string;
+    }[];
+  };
+  if (response.status === 404) {
+    return;
+  } else if (response.status === 400 && data.errors[0].code === 19400) {
+    // Bad request: schema with this ID does not exist
+    return;
+  }
+
+  if (!response.ok) {
+    await handleApiError(response, "deleting", "schema", schemaId);
+  } else if (!data.success) {
+    throw new CloudflareApiError(data.errors[0].message, response);
+  }
+}
+
+/**
+ * Get schema details
+ */
+export async function getSchema(
+  api: CloudflareApi,
+  zoneId: string,
+  schemaId: string,
+): Promise<CloudflareSchemaDetails | null> {
+  const response = await api.get(
+    `/zones/${zoneId}/schema_validation/schemas/${schemaId}`,
+  );
+
+  if (response.status === 404) {
+    return null;
+  }
+
+  if (!response.ok) {
+    await handleApiError(response, "getting", "schema", schemaId);
+  }
+
+  const data = (await response.json()) as { result: CloudflareSchema };
+  return {
+    id: data.result.schema_id,
+    name: data.result.name,
+    source: data.result.source,
+    validationEnabled: data.result.validation_enabled,
+    createdAt: data.result.created_at,
+  };
+}
+
+/**
+ * List all schemas in a zone
+ */
+export async function listSchemas(
+  api: CloudflareApi,
+  zoneId: string,
+): Promise<CloudflareSchemaDetails[]> {
+  const response = await api.get(`/zones/${zoneId}/schema_validation/schemas`);
+
+  if (!response.ok) {
+    await handleApiError(response, "listing", "schemas", zoneId);
+  }
+
+  const data = (await response.json()) as {
+    result: CloudflareSchema[];
+  };
+
+  return data.result.map((schema) => ({
+    id: schema.schema_id,
+    name: schema.name,
+    source: schema.source,
+    validationEnabled: schema.validation_enabled,
+    createdAt: schema.created_at,
+  }));
+}