@automate.ax/integration-contracts 0.120.0 → 0.122.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/integration-contracts",
-  "version": "0.120.0",
+  "version": "0.122.0",
   "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
   "license": "MIT",
   "repository": {
@@ -27,10 +27,12 @@
       "./close": "./src/close/index.ts",
       "./gmail": "./src/gmail/index.ts",
       "./google-calendar": "./src/google-calendar/index.ts",
+      "./google-drive": "./src/google-drive/index.ts",
       "./google-forms": "./src/google-forms/index.ts",
       "./google-meet": "./src/google-meet/index.ts",
       "./google-sheets": "./src/google-sheets/index.ts",
       "./github": "./src/github/index.ts",
+      "./hubspot": "./src/hubspot/index.ts",
       "./jobnimbus": "./src/jobnimbus/index.ts",
       "./linear": "./src/linear/index.ts",
       "./millionverifier": "./src/millionverifier/index.ts",
@@ -53,7 +55,7 @@
     }
   },
   "dependencies": {
-    "@automate.ax/codec": "0.120.0",
+    "@automate.ax/codec": "0.122.0",
     "@cfworker/json-schema": "^4.1.1",
     "@googleapis/calendar": "^15.0.0",
     "@googleapis/forms": "^6.0.1",
@@ -86,7 +88,7 @@
   },
   "scripts": {
     "generate:github": "bun scripts/generate-github-webhook-schemas.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "resource-broker run --pool automate-ax-validation --limit 2 --weight 1 -- tsc --noEmit",
     "lint": "oxlint --type-aware --threads=2 && bun --bun eslint . --cache --cache-strategy content",
     "lint:fix": "oxlint --type-aware --threads=2 --fix --fix-suggestions && bun --bun eslint . --fix --cache --cache-strategy content",
     "check": "bun run typecheck && bun run lint",
@@ -149,6 +151,11 @@
       "types": "./dist/google-calendar/index.d.ts",
       "default": "./dist/google-calendar/index.js"
     },
+    "./google-drive": {
+      "bun": "./src/google-drive/index.ts",
+      "types": "./dist/google-drive/index.d.ts",
+      "default": "./dist/google-drive/index.js"
+    },
     "./google-forms": {
       "bun": "./src/google-forms/index.ts",
       "types": "./dist/google-forms/index.d.ts",
@@ -169,6 +176,11 @@
       "types": "./dist/github/index.d.ts",
       "default": "./dist/github/index.js"
     },
+    "./hubspot": {
+      "bun": "./src/hubspot/index.ts",
+      "types": "./dist/hubspot/index.d.ts",
+      "default": "./dist/hubspot/index.js"
+    },
     "./jobnimbus": {
       "bun": "./src/jobnimbus/index.ts",
       "types": "./dist/jobnimbus/index.d.ts",

package/src/google-drive/index.ts

@@ -0,0 +1,329 @@
+import { z } from "zod"
+
+export const GOOGLE_DRIVE_TRIGGER_CONFIG_SCHEMA = z.object({
+  includeDescendants: z.boolean().optional(),
+  resourceId: z.string().min(1),
+  resourceType: z.enum(["file", "drive"]),
+})
+
+const GOOGLE_DRIVE_ACTION_SCHEMA = z.enum([
+  "cancelled",
+  "completed",
+  "contentChanged",
+  "created",
+  "deleted",
+  "edited",
+  "moved",
+  "reopened",
+  "renamed",
+  "reset",
+  "resolved",
+  "responded",
+  "reviewersChanged",
+  "trashed",
+  "untrashed",
+])
+
+const GOOGLE_DRIVE_RESOURCE_TYPE_SCHEMA = z.enum([
+  "accessProposal",
+  "approval",
+  "comment",
+  "file",
+  "permission",
+  "reply",
+])
+
+const GOOGLE_DRIVE_EVENT_BASE_SCHEMA = z.object({
+  action: GOOGLE_DRIVE_ACTION_SCHEMA,
+  assigneeEmailAddress: z.email().optional(),
+  commentId: z.string().optional(),
+  dueAt: z.date().optional(),
+  eventId: z.string(),
+  eventType: z.string(),
+  fileId: z.string().min(1),
+  initiatorEmailAddress: z.email().optional(),
+  mentionedEmailAddresses: z.email().array(),
+  mimeType: z.string().optional(),
+  occurredAt: z.date(),
+  parentId: z.string().optional(),
+  previousParentId: z.string().optional(),
+  resourceId: z.string().optional(),
+  resourceIds: z.string().array(),
+  resourceType: GOOGLE_DRIVE_RESOURCE_TYPE_SCHEMA,
+  reviewerEmailAddresses: z.email().array(),
+  reviewerResponse: z.string().optional(),
+  status: z.string().optional(),
+  version: z.string().optional(),
+})
+
+const GOOGLE_DRIVE_TRIGGER_TYPES = [
+  "googleDrive.accessProposal.created",
+  "googleDrive.accessProposal.resolved",
+  "googleDrive.approval.cancelled",
+  "googleDrive.approval.completed",
+  "googleDrive.approval.created",
+  "googleDrive.approval.reset",
+  "googleDrive.approval.responded",
+  "googleDrive.approval.reviewersChanged",
+  "googleDrive.comment.created",
+  "googleDrive.comment.deleted",
+  "googleDrive.comment.edited",
+  "googleDrive.comment.reopened",
+  "googleDrive.comment.resolved",
+  "googleDrive.file.contentChanged",
+  "googleDrive.file.created",
+  "googleDrive.file.deleted",
+  "googleDrive.file.moved",
+  "googleDrive.file.renamed",
+  "googleDrive.file.trashed",
+  "googleDrive.file.untrashed",
+  "googleDrive.permission.created",
+  "googleDrive.permission.deleted",
+  "googleDrive.permission.edited",
+  "googleDrive.reply.created",
+  "googleDrive.reply.deleted",
+  "googleDrive.reply.edited",
+] as const
+
+export type GoogleDriveTriggerType = (typeof GOOGLE_DRIVE_TRIGGER_TYPES)[number]
+
+export const GOOGLE_DRIVE_PROVIDER_EVENT_TYPES = {
+  "googleDrive.accessProposal.created":
+    "google.workspace.drive.accessproposal.v3.created",
+  "googleDrive.accessProposal.resolved":
+    "google.workspace.drive.accessproposal.v3.resolved",
+  "googleDrive.approval.cancelled":
+    "google.workspace.drive.approval.v3.cancelled",
+  "googleDrive.approval.completed":
+    "google.workspace.drive.approval.v3.completed",
+  "googleDrive.approval.created": "google.workspace.drive.approval.v3.created",
+  "googleDrive.approval.reset": "google.workspace.drive.approval.v3.reset",
+  "googleDrive.approval.responded":
+    "google.workspace.drive.approval.v3.responded",
+  "googleDrive.approval.reviewersChanged":
+    "google.workspace.drive.approval.v3.reviewersChanged",
+  "googleDrive.comment.created": "google.workspace.drive.comment.v3.created",
+  "googleDrive.comment.deleted": "google.workspace.drive.comment.v3.deleted",
+  "googleDrive.comment.edited": "google.workspace.drive.comment.v3.edited",
+  "googleDrive.comment.reopened": "google.workspace.drive.comment.v3.reopened",
+  "googleDrive.comment.resolved": "google.workspace.drive.comment.v3.resolved",
+  "googleDrive.file.contentChanged":
+    "google.workspace.drive.file.v3.contentChanged",
+  "googleDrive.file.created": "google.workspace.drive.file.v3.created",
+  "googleDrive.file.deleted": "google.workspace.drive.file.v3.deleted",
+  "googleDrive.file.moved": "google.workspace.drive.file.v3.moved",
+  "googleDrive.file.renamed": "google.workspace.drive.file.v3.renamed",
+  "googleDrive.file.trashed": "google.workspace.drive.file.v3.trashed",
+  "googleDrive.file.untrashed": "google.workspace.drive.file.v3.untrashed",
+  "googleDrive.permission.created":
+    "google.workspace.drive.permission.v3.created",
+  "googleDrive.permission.deleted":
+    "google.workspace.drive.permission.v3.deleted",
+  "googleDrive.permission.edited":
+    "google.workspace.drive.permission.v3.edited",
+  "googleDrive.reply.created": "google.workspace.drive.reply.v3.created",
+  "googleDrive.reply.deleted": "google.workspace.drive.reply.v3.deleted",
+  "googleDrive.reply.edited": "google.workspace.drive.reply.v3.edited",
+} as const satisfies Record<GoogleDriveTriggerType, string>
+
+export type GoogleDriveProviderEventType =
+  (typeof GOOGLE_DRIVE_PROVIDER_EVENT_TYPES)[GoogleDriveTriggerType]
+
+export const GOOGLE_DRIVE_EVENT_SCHEMA = GOOGLE_DRIVE_EVENT_BASE_SCHEMA.extend({
+  eventType: z.enum(GOOGLE_DRIVE_TRIGGER_TYPES),
+})
+
+/**
+ * Builds one semantic Drive trigger contract with literal discriminants.
+ *
+ * @param eventType - Exact internal event type.
+ * @param resourceType - Exact event resource family.
+ * @param action - Exact event action.
+ */
+function googleDriveSemanticTriggerContract<
+  const TEventType extends GoogleDriveTriggerType,
+  const TResourceType extends z.output<
+    typeof GOOGLE_DRIVE_RESOURCE_TYPE_SCHEMA
+  >,
+  const TAction extends z.output<typeof GOOGLE_DRIVE_ACTION_SCHEMA>,
+>(eventType: TEventType, resourceType: TResourceType, action: TAction) {
+  return {
+    configSchema: GOOGLE_DRIVE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: GOOGLE_DRIVE_EVENT_BASE_SCHEMA.extend({
+      action: z.literal(action),
+      eventType: z.literal(eventType),
+      resourceType: z.literal(resourceType),
+    }),
+  }
+}
+
+/** Exact semantic trigger contract map used by authoring inference. */
+const googleDriveSemanticTriggerContracts = {
+  "googleDrive.accessProposal.created": googleDriveSemanticTriggerContract(
+    "googleDrive.accessProposal.created",
+    "accessProposal",
+    "created",
+  ),
+  "googleDrive.accessProposal.resolved": googleDriveSemanticTriggerContract(
+    "googleDrive.accessProposal.resolved",
+    "accessProposal",
+    "resolved",
+  ),
+  "googleDrive.approval.cancelled": googleDriveSemanticTriggerContract(
+    "googleDrive.approval.cancelled",
+    "approval",
+    "cancelled",
+  ),
+  "googleDrive.approval.completed": googleDriveSemanticTriggerContract(
+    "googleDrive.approval.completed",
+    "approval",
+    "completed",
+  ),
+  "googleDrive.approval.created": googleDriveSemanticTriggerContract(
+    "googleDrive.approval.created",
+    "approval",
+    "created",
+  ),
+  "googleDrive.approval.reset": googleDriveSemanticTriggerContract(
+    "googleDrive.approval.reset",
+    "approval",
+    "reset",
+  ),
+  "googleDrive.approval.responded": googleDriveSemanticTriggerContract(
+    "googleDrive.approval.responded",
+    "approval",
+    "responded",
+  ),
+  "googleDrive.approval.reviewersChanged": googleDriveSemanticTriggerContract(
+    "googleDrive.approval.reviewersChanged",
+    "approval",
+    "reviewersChanged",
+  ),
+  "googleDrive.comment.created": googleDriveSemanticTriggerContract(
+    "googleDrive.comment.created",
+    "comment",
+    "created",
+  ),
+  "googleDrive.comment.deleted": googleDriveSemanticTriggerContract(
+    "googleDrive.comment.deleted",
+    "comment",
+    "deleted",
+  ),
+  "googleDrive.comment.edited": googleDriveSemanticTriggerContract(
+    "googleDrive.comment.edited",
+    "comment",
+    "edited",
+  ),
+  "googleDrive.comment.reopened": googleDriveSemanticTriggerContract(
+    "googleDrive.comment.reopened",
+    "comment",
+    "reopened",
+  ),
+  "googleDrive.comment.resolved": googleDriveSemanticTriggerContract(
+    "googleDrive.comment.resolved",
+    "comment",
+    "resolved",
+  ),
+  "googleDrive.file.contentChanged": googleDriveSemanticTriggerContract(
+    "googleDrive.file.contentChanged",
+    "file",
+    "contentChanged",
+  ),
+  "googleDrive.file.created": googleDriveSemanticTriggerContract(
+    "googleDrive.file.created",
+    "file",
+    "created",
+  ),
+  "googleDrive.file.deleted": googleDriveSemanticTriggerContract(
+    "googleDrive.file.deleted",
+    "file",
+    "deleted",
+  ),
+  "googleDrive.file.moved": googleDriveSemanticTriggerContract(
+    "googleDrive.file.moved",
+    "file",
+    "moved",
+  ),
+  "googleDrive.file.renamed": googleDriveSemanticTriggerContract(
+    "googleDrive.file.renamed",
+    "file",
+    "renamed",
+  ),
+  "googleDrive.file.trashed": googleDriveSemanticTriggerContract(
+    "googleDrive.file.trashed",
+    "file",
+    "trashed",
+  ),
+  "googleDrive.file.untrashed": googleDriveSemanticTriggerContract(
+    "googleDrive.file.untrashed",
+    "file",
+    "untrashed",
+  ),
+  "googleDrive.permission.created": googleDriveSemanticTriggerContract(
+    "googleDrive.permission.created",
+    "permission",
+    "created",
+  ),
+  "googleDrive.permission.deleted": googleDriveSemanticTriggerContract(
+    "googleDrive.permission.deleted",
+    "permission",
+    "deleted",
+  ),
+  "googleDrive.permission.edited": googleDriveSemanticTriggerContract(
+    "googleDrive.permission.edited",
+    "permission",
+    "edited",
+  ),
+  "googleDrive.reply.created": googleDriveSemanticTriggerContract(
+    "googleDrive.reply.created",
+    "reply",
+    "created",
+  ),
+  "googleDrive.reply.deleted": googleDriveSemanticTriggerContract(
+    "googleDrive.reply.deleted",
+    "reply",
+    "deleted",
+  ),
+  "googleDrive.reply.edited": googleDriveSemanticTriggerContract(
+    "googleDrive.reply.edited",
+    "reply",
+    "edited",
+  ),
+} satisfies Record<GoogleDriveTriggerType, unknown>
+
+export const googleDriveTriggerContracts = {
+  "googleDrive.event": {
+    configSchema: GOOGLE_DRIVE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: GOOGLE_DRIVE_EVENT_SCHEMA,
+  },
+  ...googleDriveSemanticTriggerContracts,
+}
+
+/**
+ * Resolves an internal semantic event type from a provider CloudEvent type.
+ *
+ * @param providerEventType - Provider CloudEvent type.
+ */
+export function toGoogleDriveTriggerType(
+  providerEventType: string,
+): GoogleDriveTriggerType | undefined {
+  // Keep the candidate separate so Zod performs the only narrowing.
+  const candidate = Object.entries(GOOGLE_DRIVE_PROVIDER_EVENT_TYPES).find(
+    ([, value]) => value === providerEventType,
+  )?.[0]
+  const result = z.enum(GOOGLE_DRIVE_TRIGGER_TYPES).safeParse(candidate)
+  return result.success ? result.data : undefined
+}
+
+/**
+ * Splits one internal event type into its resource and action discriminants.
+ *
+ * @param eventType - Stable internal semantic event type.
+ */
+export function parseGoogleDriveTriggerType(eventType: GoogleDriveTriggerType) {
+  const [, resourceType, ...actionParts] = eventType.split(".")
+  return {
+    action: GOOGLE_DRIVE_ACTION_SCHEMA.parse(actionParts.join(".")),
+    resourceType: GOOGLE_DRIVE_RESOURCE_TYPE_SCHEMA.parse(resourceType),
+  }
+}

package/src/hubspot/api.ts

@@ -0,0 +1,147 @@
+import { isEncodable, type Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+
+const HUBSPOT_API_ORIGIN = "https://api.hubapi.com/"
+const HUBSPOT_API_URL = new URL(HUBSPOT_API_ORIGIN)
+const HUBSPOT_SECRET_SCHEMA = z.object({ accessToken: z.string().min(1) })
+const HUBSPOT_ERROR_SCHEMA = z.looseObject({
+  category: z.string().optional(),
+  correlationId: z.string().optional(),
+  message: z.string().optional(),
+  subCategory: z.string().optional(),
+})
+
+export const HUBSPOT_VALUE_SCHEMA = z.custom<Encodable>(isEncodable, {
+  message: "Expected a codec-safe HubSpot value.",
+})
+
+interface HubSpotRequestOptions<TSchema extends z.ZodType> {
+  body?: Encodable
+  method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT"
+  query?: Record<
+    string,
+    boolean | number | string | readonly string[] | null | undefined
+  >
+  responseSchema: TSchema
+}
+
+/** Error returned by a rejected HubSpot API request. */
+export class HubSpotApiError extends Error {
+  readonly category?: string
+  readonly correlationId?: string
+  readonly details: Encodable
+  readonly retryAfter?: string
+  readonly status: number
+  readonly subCategory?: string
+
+  /**
+   * Creates an error from one rejected HubSpot response.
+   *
+   * @param status - HTTP response status.
+   * @param details - Codec-safe provider response.
+   * @param retryAfter - Provider retry timing, when present.
+   */
+  constructor(status: number, details: Encodable, retryAfter?: string) {
+    const providerError = HUBSPOT_ERROR_SCHEMA.safeParse(details)
+    super(
+      providerError.success && providerError.data.message
+        ? `HubSpot API request failed (${status}): ${providerError.data.message}`
+        : `HubSpot API request failed (${status}).`,
+    )
+    this.name = "HubSpotApiError"
+    this.category = providerError.success
+      ? providerError.data.category
+      : undefined
+    this.correlationId = providerError.success
+      ? providerError.data.correlationId
+      : undefined
+    this.details = details
+    this.retryAfter = retryAfter
+    this.status = status
+    this.subCategory = providerError.success
+      ? providerError.data.subCategory
+      : undefined
+  }
+}
+
+/**
+ * Creates a minimal authenticated HubSpot REST client.
+ *
+ * @param secret - Stored OAuth or private-app token.
+ */
+export function getHubSpotApi(secret: unknown) {
+  const { accessToken } = HUBSPOT_SECRET_SCHEMA.parse(secret)
+
+  return {
+    /**
+     * Sends one request below HubSpot's API origin.
+     *
+     * @param path - Relative provider API path.
+     * @param options - Method, query, body, and response schema.
+     */
+    async request<TSchema extends z.ZodType>(
+      path: string,
+      options: HubSpotRequestOptions<TSchema>,
+    ): Promise<z.output<TSchema>> {
+      const normalizedPath = path.replace(/^\/+/, "")
+      if (
+        !normalizedPath ||
+        normalizedPath.includes("://") ||
+        normalizedPath.includes("\\")
+      ) {
+        throw new TypeError("HubSpot API paths must be relative.")
+      }
+
+      const url = new URL(normalizedPath, HUBSPOT_API_ORIGIN)
+      if (url.origin !== HUBSPOT_API_URL.origin) {
+        throw new TypeError("HubSpot API paths must remain on api.hubapi.com.")
+      }
+      for (const [key, value] of Object.entries(options.query ?? {})) {
+        if (value == null) continue
+        url.searchParams.set(
+          key,
+          Array.isArray(value) ? value.join(",") : String(value),
+        )
+      }
+
+      const headers = new Headers({
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      })
+      if (options.body !== undefined) {
+        headers.set("Content-Type", "application/json")
+      }
+      const response = await fetch(url, {
+        body:
+          options.body === undefined ? undefined : JSON.stringify(options.body),
+        headers,
+        method: options.method ?? "GET",
+      })
+      const text = await response.text()
+      const parsed = text ? parseJson(text) : undefined
+      if (response.ok && !text) return options.responseSchema.parse(undefined)
+      const encodable = HUBSPOT_VALUE_SCHEMA.safeParse(parsed)
+      if (!response.ok || !encodable.success) {
+        throw new HubSpotApiError(
+          response.status,
+          encodable.success ? encodable.data : { response: text },
+          response.headers.get("Retry-After") ?? undefined,
+        )
+      }
+      return options.responseSchema.parse(parsed)
+    },
+  }
+}
+
+/**
+ * Parses a response body while preserving non-JSON error text.
+ *
+ * @param value - Raw response body.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return { response: value }
+  }
+}