@automate.ax/integration-contracts 0.152.4 → 0.153.0

package/src/cloudflare/browser-rendering.ts

@@ -0,0 +1,466 @@
+import type { Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+
+const RESOURCE_TYPE_SCHEMA = z.enum([
+  "document",
+  "stylesheet",
+  "image",
+  "media",
+  "font",
+  "script",
+  "texttrack",
+  "xhr",
+  "fetch",
+  "prefetch",
+  "eventsource",
+  "websocket",
+  "manifest",
+  "signedexchange",
+  "ping",
+  "cspviolationreport",
+  "preflight",
+  "other",
+])
+const SCRIPT_TAG_SCHEMA = z.object({
+  content: z.string().optional(),
+  id: z.string().optional(),
+  type: z.string().optional(),
+  url: z.url().optional(),
+})
+const STYLE_TAG_SCHEMA = z.object({
+  content: z.string().optional(),
+  url: z.url().optional(),
+})
+const COOKIE_SCHEMA = z.object({
+  domain: z.string().optional(),
+  expires: z.number().optional(),
+  httpOnly: z.boolean().optional(),
+  name: z.string().min(1),
+  partitionKey: z.string().optional(),
+  path: z.string().optional(),
+  priority: z.enum(["Low", "Medium", "High"]).optional(),
+  sameParty: z.boolean().optional(),
+  sameSite: z.enum(["Strict", "Lax", "None"]).optional(),
+  secure: z.boolean().optional(),
+  sourcePort: z.number().int().min(0).max(65_535).optional(),
+  sourceScheme: z.enum(["Unset", "NonSecure", "Secure"]).optional(),
+  url: z.string().optional(),
+  value: z.string(),
+})
+const WAIT_UNTIL_SCHEMA = z.enum([
+  "load",
+  "domcontentloaded",
+  "networkidle0",
+  "networkidle2",
+])
+const GOTO_OPTIONS_SCHEMA = z.object({
+  referer: z.string().optional(),
+  referrerPolicy: z.string().optional(),
+  timeout: z.number().min(0).max(60_000).optional(),
+  waitUntil: z
+    .union([WAIT_UNTIL_SCHEMA, WAIT_UNTIL_SCHEMA.array().min(1)])
+    .optional(),
+})
+const VIEWPORT_SCHEMA = z.object({
+  deviceScaleFactor: z.number().positive().optional(),
+  hasTouch: z.boolean().optional(),
+  height: z.number().positive(),
+  isLandscape: z.boolean().optional(),
+  isMobile: z.boolean().optional(),
+  width: z.number().positive(),
+})
+const WAIT_FOR_SELECTOR_SCHEMA = z
+  .object({
+    hidden: z.literal(true).optional(),
+    selector: z.string().min(1),
+    timeout: z.number().min(0).max(120_000).optional(),
+    visible: z.literal(true).optional(),
+  })
+  .refine(({ hidden, visible }) => !(hidden && visible), {
+    message: "Choose hidden or visible, not both.",
+  })
+const SCREENSHOT_OPTIONS_SCHEMA = z
+  .object({
+    captureBeyondViewport: z.boolean().optional(),
+    clip: z
+      .object({
+        height: z.number().positive(),
+        scale: z.number().positive().optional(),
+        width: z.number().positive(),
+        x: z.number(),
+        y: z.number(),
+      })
+      .optional(),
+    fromSurface: z.boolean().optional(),
+    fullPage: z.boolean().optional(),
+    omitBackground: z.boolean().optional(),
+    optimizeForSpeed: z.boolean().optional(),
+    quality: z.number().min(0).max(100).optional(),
+    type: z.enum(["png", "jpeg", "webp"]).optional(),
+  })
+  .refine(({ quality, type }) => quality === undefined || type !== "png", {
+    message: "Screenshot quality requires jpeg or webp output.",
+    path: ["quality"],
+  })
+const PDF_DIMENSION_SCHEMA = z.union([z.number().positive(), z.string().min(1)])
+const PDF_OPTIONS_SCHEMA = z.object({
+  displayHeaderFooter: z.boolean().optional(),
+  footerTemplate: z.string().optional(),
+  format: z
+    .enum([
+      "letter",
+      "legal",
+      "tabloid",
+      "ledger",
+      "a0",
+      "a1",
+      "a2",
+      "a3",
+      "a4",
+      "a5",
+      "a6",
+    ])
+    .optional(),
+  headerTemplate: z.string().optional(),
+  height: PDF_DIMENSION_SCHEMA.optional(),
+  landscape: z.boolean().optional(),
+  margin: z
+    .object({
+      bottom: PDF_DIMENSION_SCHEMA.optional(),
+      left: PDF_DIMENSION_SCHEMA.optional(),
+      right: PDF_DIMENSION_SCHEMA.optional(),
+      top: PDF_DIMENSION_SCHEMA.optional(),
+    })
+    .optional(),
+  omitBackground: z.boolean().optional(),
+  outline: z.boolean().optional(),
+  pageRanges: z.string().optional(),
+  preferCSSPageSize: z.boolean().optional(),
+  printBackground: z.boolean().optional(),
+  scale: z.number().min(0.1).max(2).optional(),
+  tagged: z.boolean().optional(),
+  timeout: z.number().min(0).optional(),
+  width: PDF_DIMENSION_SCHEMA.optional(),
+})
+const JSON_EXTRACTION_OPTIONS = {
+  customAi: z
+    .object({
+      authorization: z.string().min(1).optional(),
+      model: z.string().min(1),
+    })
+    .array()
+    .min(1)
+    .optional(),
+  prompt: z.string().min(1).optional(),
+  responseFormat: z
+    .object({
+      jsonSchema: z.record(z.string(), z.json()).nullable().optional(),
+      type: z.string().min(1),
+    })
+    .optional(),
+}
+const COMMON_RENDERING_FIELDS = {
+  accountId: z.string().trim().min(1),
+  actionTimeout: z.number().min(0).max(120_000).optional(),
+  addScriptTag: SCRIPT_TAG_SCHEMA.array().optional(),
+  addStyleTag: STYLE_TAG_SCHEMA.array().optional(),
+  allowRequestPattern: z.string().min(1).array().min(1).optional(),
+  allowResourceTypes: RESOURCE_TYPE_SCHEMA.array().min(1).optional(),
+  authenticate: z
+    .object({ password: z.string().min(1), username: z.string().min(1) })
+    .optional(),
+  bestAttempt: z.boolean().optional(),
+  cacheTtl: z.number().int().min(0).max(86_400).optional(),
+  cookies: COOKIE_SCHEMA.array().optional(),
+  emulateMediaType: z.string().optional(),
+  gotoOptions: GOTO_OPTIONS_SCHEMA.optional(),
+  rejectRequestPattern: z.string().min(1).array().min(1).optional(),
+  rejectResourceTypes: RESOURCE_TYPE_SCHEMA.array().min(1).optional(),
+  setExtraHttpHeaders: z.record(z.string(), z.string()).optional(),
+  setJavaScriptEnabled: z.boolean().optional(),
+  viewport: VIEWPORT_SCHEMA.optional(),
+  waitForSelector: WAIT_FOR_SELECTOR_SCHEMA.optional(),
+  waitForTimeout: z.number().min(0).max(120_000).optional(),
+}
+const SOURCE_FIELDS = {
+  html: z.string().min(1).optional(),
+  url: z.url().optional(),
+}
+const QUICK_ACTION_RENDERING_FIELDS = {
+  ...COMMON_RENDERING_FIELDS,
+  userAgent: z.string().optional(),
+}
+
+/** Recursive accessibility node returned by Cloudflare Browser Run. */
+export interface CloudflareAccessibilityNode extends Record<string, Encodable> {
+  autocomplete?: string
+  checked?: boolean | "mixed"
+  children?: CloudflareAccessibilityNode[]
+  description?: string
+  disabled?: boolean
+  expanded?: boolean
+  focused?: boolean
+  haspopup?: string
+  invalid?: string
+  keyshortcuts?: string
+  level?: number
+  modal?: boolean
+  multiline?: boolean
+  multiselectable?: boolean
+  name?: string
+  orientation?: string
+  pressed?: boolean | "mixed"
+  readonly?: boolean
+  required?: boolean
+  role: string
+  roledescription?: string
+  selected?: boolean
+  value?: number | string
+  valuemax?: number
+  valuemin?: number
+  valuetext?: string
+}
+
+export const CLOUDFLARE_ACCESSIBILITY_NODE_SCHEMA: z.ZodType<CloudflareAccessibilityNode> =
+  z.lazy(() =>
+    z.object({
+      autocomplete: z.string().optional(),
+      checked: z.union([z.boolean(), z.literal("mixed")]).optional(),
+      children: CLOUDFLARE_ACCESSIBILITY_NODE_SCHEMA.array().optional(),
+      description: z.string().optional(),
+      disabled: z.boolean().optional(),
+      expanded: z.boolean().optional(),
+      focused: z.boolean().optional(),
+      haspopup: z.string().optional(),
+      invalid: z.string().optional(),
+      keyshortcuts: z.string().optional(),
+      level: z.number().optional(),
+      modal: z.boolean().optional(),
+      multiline: z.boolean().optional(),
+      multiselectable: z.boolean().optional(),
+      name: z.string().optional(),
+      orientation: z.string().optional(),
+      pressed: z.union([z.boolean(), z.literal("mixed")]).optional(),
+      readonly: z.boolean().optional(),
+      required: z.boolean().optional(),
+      role: z.string(),
+      roledescription: z.string().optional(),
+      selected: z.boolean().optional(),
+      value: z.union([z.number(), z.string()]).optional(),
+      valuemax: z.number().optional(),
+      valuemin: z.number().optional(),
+      valuetext: z.string().optional(),
+    }),
+  )
+
+export const CLOUDFLARE_BROWSER_CONTENT_INPUT_SCHEMA = browserRenderingInput({})
+export const CLOUDFLARE_BROWSER_MARKDOWN_INPUT_SCHEMA = browserRenderingInput(
+  {},
+)
+export const CLOUDFLARE_BROWSER_ACCESSIBILITY_INPUT_SCHEMA =
+  browserRenderingInput({
+    interestingOnly: z.boolean().optional(),
+    root: z.string().optional(),
+  })
+export const CLOUDFLARE_BROWSER_LINKS_INPUT_SCHEMA = browserRenderingInput({
+  excludeExternalLinks: z.boolean().optional(),
+  visibleLinksOnly: z.boolean().optional(),
+})
+export const CLOUDFLARE_BROWSER_SCRAPE_INPUT_SCHEMA = browserRenderingInput({
+  elements: z
+    .object({ selector: z.string().min(1) })
+    .array()
+    .min(1),
+})
+export const CLOUDFLARE_BROWSER_SCREENSHOT_INPUT_SCHEMA = browserRenderingInput(
+  {
+    screenshotOptions: SCREENSHOT_OPTIONS_SCHEMA.optional(),
+    scrollPage: z.boolean().optional(),
+    selector: z.string().min(1).optional(),
+  },
+)
+export const CLOUDFLARE_BROWSER_PDF_INPUT_SCHEMA = browserRenderingInput({
+  pdfOptions: PDF_OPTIONS_SCHEMA.optional(),
+})
+export const CLOUDFLARE_BROWSER_SNAPSHOT_INPUT_SCHEMA = browserRenderingInput({
+  formats: z
+    .enum(["content", "screenshot", "markdown", "accessibilityTree"])
+    .array()
+    .min(2)
+    .refine((formats) => new Set(formats).size === formats.length, {
+      message: "Choose each snapshot format once.",
+    })
+    .optional(),
+  screenshotOptions: SCREENSHOT_OPTIONS_SCHEMA.optional(),
+})
+export const CLOUDFLARE_BROWSER_JSON_INPUT_SCHEMA = browserRenderingInput(
+  JSON_EXTRACTION_OPTIONS,
+).superRefine(({ prompt, responseFormat }, context) => {
+  if (!prompt && !responseFormat)
+    context.addIssue({
+      code: "custom",
+      message: "Provide prompt or responseFormat.",
+    })
+})
+
+export const CLOUDFLARE_BROWSER_SCRAPE_RESULT_SCHEMA = z.object({
+  results: z.object({
+    attributes: z.object({ name: z.string(), value: z.string() }).array(),
+    height: z.number(),
+    html: z.string(),
+    left: z.number(),
+    text: z.string(),
+    top: z.number(),
+    width: z.number(),
+  }),
+  selector: z.string(),
+})
+export const CLOUDFLARE_BROWSER_SNAPSHOT_RESULT_SCHEMA = z.object({
+  accessibilityTree: CLOUDFLARE_ACCESSIBILITY_NODE_SCHEMA.optional(),
+  content: z.string().optional(),
+  markdown: z.string().optional(),
+  screenshot: z.base64().optional(),
+})
+
+const CRAWL_STATUS_SCHEMA = z.enum([
+  "queued",
+  "errored",
+  "completed",
+  "disallowed",
+  "skipped",
+  "cancelled",
+])
+const CRAWL_OPTIONS_SCHEMA = z.object({
+  excludePatterns: z.string().min(1).array().optional(),
+  includeExternalLinks: z.boolean().optional(),
+  includePatterns: z.string().min(1).array().optional(),
+  includeSubdomains: z.boolean().optional(),
+})
+const CRAWL_FIELDS = {
+  contentUse: z.enum(["reference", "full"]).optional(),
+  crawlPurposes: z
+    .enum(["search", "ai-input", "ai-train"])
+    .array()
+    .min(1)
+    .max(3)
+    .refine((purposes) => new Set(purposes).size === purposes.length, {
+      message: "Choose each crawl purpose once.",
+    })
+    .optional(),
+  depth: z.number().int().min(1).max(100_000).optional(),
+  formats: z
+    .enum(["html", "markdown", "json"])
+    .array()
+    .min(1)
+    .refine((formats) => new Set(formats).size === formats.length, {
+      message: "Choose each crawl format once.",
+    })
+    .optional(),
+  jsonOptions: z.object(JSON_EXTRACTION_OPTIONS).optional(),
+  limit: z.number().int().min(1).max(100_000).optional(),
+  maxAge: z.number().int().min(0).max(604_800).optional(),
+  modifiedSince: z.number().int().nonnegative().optional(),
+  options: CRAWL_OPTIONS_SCHEMA.optional(),
+  source: z.enum(["sitemaps", "links", "all"]).optional(),
+  url: z.url(),
+}
+export const CLOUDFLARE_BROWSER_CREATE_CRAWL_INPUT_SCHEMA = z
+  .object({
+    ...COMMON_RENDERING_FIELDS,
+    ...CRAWL_FIELDS,
+    render: z.boolean().prefault(true),
+  })
+  .superRefine((input, context) => {
+    if (
+      !input.render &&
+      (input.actionTimeout !== undefined ||
+        input.addScriptTag !== undefined ||
+        input.addStyleTag !== undefined ||
+        input.allowRequestPattern !== undefined ||
+        input.allowResourceTypes !== undefined ||
+        input.authenticate !== undefined ||
+        input.bestAttempt !== undefined ||
+        input.cookies !== undefined ||
+        input.emulateMediaType !== undefined ||
+        input.gotoOptions !== undefined ||
+        input.rejectRequestPattern !== undefined ||
+        input.rejectResourceTypes !== undefined ||
+        input.setExtraHttpHeaders !== undefined ||
+        input.setJavaScriptEnabled !== undefined ||
+        input.viewport !== undefined ||
+        input.waitForSelector !== undefined ||
+        input.waitForTimeout !== undefined)
+    )
+      context.addIssue({
+        code: "custom",
+        message: "Rendered-page options require render: true.",
+        path: ["render"],
+      })
+  })
+export const CLOUDFLARE_BROWSER_GET_CRAWL_INPUT_SCHEMA = z.object({
+  accountId: z.string().trim().min(1),
+  cacheTtl: z.number().int().min(0).max(86_400).optional(),
+  cursor: z.number().int().nonnegative().optional(),
+  jobId: z.string().trim().min(1),
+  limit: z.number().int().positive().optional(),
+  status: CRAWL_STATUS_SCHEMA.optional(),
+})
+export const CLOUDFLARE_BROWSER_CANCEL_CRAWL_INPUT_SCHEMA = z.object({
+  accountId: z.string().trim().min(1),
+  jobId: z.string().trim().min(1),
+})
+export const CLOUDFLARE_BROWSER_CRAWL_RESULT_SCHEMA = z.object({
+  browserSecondsUsed: z.number().nonnegative(),
+  cursor: z.string().optional(),
+  finished: z.number().int().nonnegative(),
+  id: z.string().min(1),
+  records: z
+    .object({
+      html: z.string().optional(),
+      json: z.record(z.string(), z.json()).optional(),
+      markdown: z.string().optional(),
+      metadata: z
+        .object({
+          status: z.number().int(),
+          title: z.string().optional(),
+          url: z.string(),
+        })
+        .optional(),
+      status: CRAWL_STATUS_SCHEMA,
+      url: z.string(),
+    })
+    .array(),
+  skipped: z.number().int().nonnegative(),
+  status: z.string(),
+  total: z.number().int().nonnegative(),
+})
+export const CLOUDFLARE_BROWSER_CANCEL_CRAWL_RESULT_SCHEMA = z.object({
+  jobId: z.string().min(1),
+  message: z.string(),
+})
+
+/**
+ * Builds a Browser Run input schema that requires exactly one page source.
+ *
+ * @param fields - Endpoint-specific input fields.
+ */
+function browserRenderingInput<TFields extends z.ZodRawShape>(fields: TFields) {
+  return z
+    .object({ ...QUICK_ACTION_RENDERING_FIELDS, ...SOURCE_FIELDS, ...fields })
+    .refine(hasExactlyOnePageSource, {
+      message: "Provide exactly one of url or html.",
+    })
+}
+
+/**
+ * Returns whether an input provides exactly one Browser Run page source.
+ *
+ * @param input - Candidate page source.
+ * @param input.html - Inline HTML source.
+ * @param input.url - URL source.
+ */
+function hasExactlyOnePageSource(input: { html?: unknown; url?: unknown }) {
+  return (
+    Number(input.html !== undefined) + Number(input.url !== undefined) === 1
+  )
+}

package/src/cloudflare/index.ts

@@ -1,3 +1,4 @@
 export * from "./api"
+export * from "./browser-rendering"
 export * from "./events"
 export * from "./schemas"