@automate.ax/integration-contracts 0.120.0 → 0.121.0

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 }
+  }
+}

package/src/hubspot/events.ts

@@ -0,0 +1,193 @@
+import * as z from "zod"
+
+export const HUBSPOT_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const HUBSPOT_EVENT_ACTION_SCHEMA = z.enum([
+  "associationAdded",
+  "associationRemoved",
+  "created",
+  "deleted",
+  "merged",
+  "propertyChanged",
+  "restored",
+])
+
+export const HUBSPOT_EVENT_OBJECT_SCHEMA = z.enum([
+  "company",
+  "contact",
+  "deal",
+  "ticket",
+])
+
+const HUBSPOT_COMMON_EVENT_FIELDS = {
+  appId: z.number().int().positive().optional(),
+  attemptNumber: z.number().int().nonnegative(),
+  changeSource: z.string().optional(),
+  eventId: z.number().int(),
+  objectId: z.string(),
+  objectType: HUBSPOT_EVENT_OBJECT_SCHEMA,
+  occurredAt: z.date(),
+  portalId: z.number().int().positive(),
+  sourceId: z.string().optional(),
+  subscriptionId: z.number().int().positive(),
+}
+const HUBSPOT_ASSOCIATION_EVENT_FIELDS = {
+  associationCategory: z.string().optional(),
+  associationType: z.string(),
+  associationTypeId: z.number().int().positive().optional(),
+  fromObjectId: z.string(),
+  fromObjectTypeId: z.string().optional(),
+  isPrimaryAssociation: z.boolean().optional(),
+  toObjectId: z.string(),
+  toObjectTypeId: z.string().optional(),
+}
+
+export const HUBSPOT_CRM_EVENT_SCHEMA = z.discriminatedUnion("action", [
+  z.object({
+    ...HUBSPOT_COMMON_EVENT_FIELDS,
+    ...HUBSPOT_ASSOCIATION_EVENT_FIELDS,
+    action: z.literal("associationAdded"),
+    associationRemoved: z.literal(false),
+  }),
+  z.object({
+    ...HUBSPOT_COMMON_EVENT_FIELDS,
+    ...HUBSPOT_ASSOCIATION_EVENT_FIELDS,
+    action: z.literal("associationRemoved"),
+    associationRemoved: z.literal(true),
+  }),
+  z.object({ ...HUBSPOT_COMMON_EVENT_FIELDS, action: z.literal("created") }),
+  z.object({ ...HUBSPOT_COMMON_EVENT_FIELDS, action: z.literal("deleted") }),
+  z.object({
+    ...HUBSPOT_COMMON_EVENT_FIELDS,
+    action: z.literal("merged"),
+    mergedObjectIds: z.string().array().min(1),
+    newObjectId: z.string(),
+    numberOfPropertiesMoved: z.number().int().nonnegative().optional(),
+  }),
+  z.object({
+    ...HUBSPOT_COMMON_EVENT_FIELDS,
+    action: z.literal("propertyChanged"),
+    propertyName: z.string(),
+    propertyValue: z.string(),
+  }),
+  z.object({ ...HUBSPOT_COMMON_EVENT_FIELDS, action: z.literal("restored") }),
+])
+
+export type HubSpotCrmEvent = z.output<typeof HUBSPOT_CRM_EVENT_SCHEMA>
+
+type HubSpotEventAction = z.output<typeof HUBSPOT_EVENT_ACTION_SCHEMA>
+type HubSpotEventObject = z.output<typeof HUBSPOT_EVENT_OBJECT_SCHEMA>
+
+/** Every semantic HubSpot CRM trigger type. */
+type HubSpotSemanticTriggerType =
+  `hubspot.${HubSpotEventObject}.${HubSpotEventAction}`
+type HubSpotTriggerContract = {
+  readonly configSchema: typeof HUBSPOT_TRIGGER_CONFIG_SCHEMA
+  readonly eventSchema: z.ZodType<HubSpotCrmEvent>
+}
+
+/** Complete HubSpot broad and semantic trigger contract map. */
+type HubSpotTriggerContracts = {
+  readonly [TType in HubSpotSemanticTriggerType]: HubSpotTriggerContract
+} & {
+  readonly "hubspot.crm.event": HubSpotTriggerContract
+}
+
+/** Every broad and semantic HubSpot trigger contract. */
+export const hubspotTriggerContracts = {
+  "hubspot.company.associationAdded": semanticContract(
+    "company",
+    "associationAdded",
+  ),
+  "hubspot.company.associationRemoved": semanticContract(
+    "company",
+    "associationRemoved",
+  ),
+  "hubspot.company.created": semanticContract("company", "created"),
+  "hubspot.company.deleted": semanticContract("company", "deleted"),
+  "hubspot.company.merged": semanticContract("company", "merged"),
+  "hubspot.company.propertyChanged": semanticContract(
+    "company",
+    "propertyChanged",
+  ),
+  "hubspot.company.restored": semanticContract("company", "restored"),
+  "hubspot.contact.associationAdded": semanticContract(
+    "contact",
+    "associationAdded",
+  ),
+  "hubspot.contact.associationRemoved": semanticContract(
+    "contact",
+    "associationRemoved",
+  ),
+  "hubspot.contact.created": semanticContract("contact", "created"),
+  "hubspot.contact.deleted": semanticContract("contact", "deleted"),
+  "hubspot.contact.merged": semanticContract("contact", "merged"),
+  "hubspot.contact.propertyChanged": semanticContract(
+    "contact",
+    "propertyChanged",
+  ),
+  "hubspot.contact.restored": semanticContract("contact", "restored"),
+  "hubspot.crm.event": {
+    configSchema: HUBSPOT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: HUBSPOT_CRM_EVENT_SCHEMA,
+  },
+  "hubspot.deal.associationAdded": semanticContract("deal", "associationAdded"),
+  "hubspot.deal.associationRemoved": semanticContract(
+    "deal",
+    "associationRemoved",
+  ),
+  "hubspot.deal.created": semanticContract("deal", "created"),
+  "hubspot.deal.deleted": semanticContract("deal", "deleted"),
+  "hubspot.deal.merged": semanticContract("deal", "merged"),
+  "hubspot.deal.propertyChanged": semanticContract("deal", "propertyChanged"),
+  "hubspot.deal.restored": semanticContract("deal", "restored"),
+  "hubspot.ticket.associationAdded": semanticContract(
+    "ticket",
+    "associationAdded",
+  ),
+  "hubspot.ticket.associationRemoved": semanticContract(
+    "ticket",
+    "associationRemoved",
+  ),
+  "hubspot.ticket.created": semanticContract("ticket", "created"),
+  "hubspot.ticket.deleted": semanticContract("ticket", "deleted"),
+  "hubspot.ticket.merged": semanticContract("ticket", "merged"),
+  "hubspot.ticket.propertyChanged": semanticContract(
+    "ticket",
+    "propertyChanged",
+  ),
+  "hubspot.ticket.restored": semanticContract("ticket", "restored"),
+} satisfies HubSpotTriggerContracts
+
+/**
+ * Builds one semantic HubSpot lifecycle contract.
+ *
+ * @param objectType - Normalized CRM object type.
+ * @param action - Normalized CRM lifecycle action.
+ */
+function semanticContract<
+  const TObjectType extends HubSpotEventObject,
+  const TAction extends HubSpotEventAction,
+>(objectType: TObjectType, action: TAction) {
+  return {
+    configSchema: HUBSPOT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: HUBSPOT_CRM_EVENT_SCHEMA.and(
+      z.object({
+        action: z.literal(action),
+        objectType: z.literal(objectType),
+      }),
+    ),
+  }
+}
+
+/**
+ * Returns broad and semantic event types for one normalized callback.
+ *
+ * @param event - Normalized HubSpot CRM event.
+ */
+export function getHubSpotEventTypes(event: HubSpotCrmEvent) {
+  return [
+    `hubspot.${event.objectType}.${event.action}`,
+    "hubspot.crm.event",
+  ] as const
+}

package/src/hubspot/index.ts

@@ -0,0 +1,3 @@
+export * from "./api"
+export * from "./events"
+export * from "./schemas"

package/src/hubspot/schemas.ts

@@ -0,0 +1,189 @@
+import * as z from "zod"
+
+export const HUBSPOT_CORE_OBJECT_TYPE_SCHEMA = z.enum([
+  "companies",
+  "contacts",
+  "deals",
+  "tickets",
+])
+
+export const HUBSPOT_DATE_SCHEMA = z.iso
+  .datetime({ offset: true })
+  .transform((value) => new Date(value))
+
+export const HUBSPOT_PROPERTY_VALUE_SCHEMA = z.object({
+  /** HubSpot internal property name. */
+  name: z.string().trim().min(1),
+
+  /** Serialized property value. An empty string clears a writable property. */
+  value: z.string().nullable(),
+})
+
+export const HUBSPOT_PROPERTY_VALUES_SCHEMA =
+  HUBSPOT_PROPERTY_VALUE_SCHEMA.array().superRefine((properties, context) => {
+    const seen = new Set<string>()
+    for (const [index, property] of properties.entries()) {
+      if (seen.has(property.name)) {
+        context.addIssue({
+          code: "custom",
+          message: `Duplicate HubSpot property: ${property.name}`,
+          path: [index, "name"],
+        })
+      }
+      seen.add(property.name)
+    }
+  })
+
+export const HUBSPOT_ASSOCIATION_TYPE_SCHEMA = z.object({
+  associationCategory: z.enum([
+    "HUBSPOT_DEFINED",
+    "INTEGRATOR_DEFINED",
+    "USER_DEFINED",
+  ]),
+  associationTypeId: z.number().int().positive(),
+})
+
+export const HUBSPOT_ASSOCIATION_INPUT_SCHEMA = z.object({
+  toRecordId: z.string().trim().min(1),
+  types: HUBSPOT_ASSOCIATION_TYPE_SCHEMA.array().min(1),
+})
+
+export const HUBSPOT_ASSOCIATED_RECORD_SCHEMA = z.object({
+  id: z.string(),
+  type: z.string().optional(),
+})
+
+export const HUBSPOT_ASSOCIATION_RESULT_SCHEMA = z.object({
+  objectType: z.string(),
+  records: HUBSPOT_ASSOCIATED_RECORD_SCHEMA.array(),
+})
+
+export const HUBSPOT_PROPERTY_HISTORY_VALUE_SCHEMA = z.object({
+  sourceId: z.string().optional(),
+  sourceType: z.string(),
+  timestamp: HUBSPOT_DATE_SCHEMA,
+  updatedByUserId: z.number().int().optional(),
+  value: z.string().nullable(),
+})
+
+export const HUBSPOT_PROPERTY_HISTORY_SCHEMA = z.object({
+  name: z.string(),
+  values: HUBSPOT_PROPERTY_HISTORY_VALUE_SCHEMA.array(),
+})
+
+export const HUBSPOT_RECORD_SCHEMA = z.object({
+  archived: z.boolean(),
+  archivedAt: HUBSPOT_DATE_SCHEMA.optional(),
+  associations: HUBSPOT_ASSOCIATION_RESULT_SCHEMA.array().prefault([]),
+  createdAt: HUBSPOT_DATE_SCHEMA,
+  id: z.string(),
+  properties: HUBSPOT_PROPERTY_VALUES_SCHEMA,
+  propertiesWithHistory: HUBSPOT_PROPERTY_HISTORY_SCHEMA.array().prefault([]),
+  updatedAt: HUBSPOT_DATE_SCHEMA,
+})
+
+export const HUBSPOT_PAGE_INFO_SCHEMA = z.object({
+  after: z.string().optional(),
+})
+
+export const HUBSPOT_RECORD_PAGE_SCHEMA = z.object({
+  pageInfo: HUBSPOT_PAGE_INFO_SCHEMA,
+  records: HUBSPOT_RECORD_SCHEMA.array(),
+  total: z.number().int().nonnegative().optional(),
+})
+
+const HUBSPOT_PROVIDER_HISTORY_VALUE_SCHEMA = z.looseObject({
+  sourceId: z.string().optional(),
+  sourceType: z.string(),
+  timestamp: z.iso.datetime({ offset: true }),
+  updatedByUserId: z.number().int().optional(),
+  value: z.string().nullable(),
+})
+
+export const HUBSPOT_PROVIDER_RECORD_SCHEMA = z.looseObject({
+  archived: z.boolean(),
+  archivedAt: z.iso.datetime({ offset: true }).optional(),
+  associations: z
+    .record(
+      z.string(),
+      z.looseObject({
+        results: z
+          .looseObject({ id: z.string(), type: z.string().optional() })
+          .array(),
+      }),
+    )
+    .optional(),
+  createdAt: z.iso.datetime({ offset: true }),
+  id: z.string(),
+  properties: z.record(z.string(), z.string().nullable()),
+  propertiesWithHistory: z
+    .record(z.string(), HUBSPOT_PROVIDER_HISTORY_VALUE_SCHEMA.array())
+    .optional(),
+  updatedAt: z.iso.datetime({ offset: true }),
+})
+
+export const HUBSPOT_PROVIDER_RECORD_PAGE_SCHEMA = z.looseObject({
+  paging: z
+    .looseObject({ next: z.looseObject({ after: z.string() }).optional() })
+    .optional(),
+  results: HUBSPOT_PROVIDER_RECORD_SCHEMA.array(),
+  total: z.number().int().nonnegative().optional(),
+})
+
+/**
+ * Converts HubSpot's dynamic property maps into structurally typed entries.
+ *
+ * @param record - Provider CRM record.
+ */
+export function toHubSpotRecord(
+  record: z.output<typeof HUBSPOT_PROVIDER_RECORD_SCHEMA>,
+): z.input<typeof HUBSPOT_RECORD_SCHEMA> {
+  return {
+    archived: record.archived,
+    ...(record.archivedAt ? { archivedAt: record.archivedAt } : {}),
+    associations: Object.entries(record.associations ?? {}).map(
+      ([objectType, association]) => ({
+        objectType,
+        records: association.results,
+      }),
+    ),
+    createdAt: record.createdAt,
+    id: record.id,
+    properties: Object.entries(record.properties).map(([name, value]) => ({
+      name,
+      value,
+    })),
+    propertiesWithHistory: Object.entries(
+      record.propertiesWithHistory ?? {},
+    ).map(([name, values]) => ({ name, values })),
+    updatedAt: record.updatedAt,
+  }
+}
+
+/**
+ * Converts HubSpot's record-page envelope into public pagination.
+ *
+ * @param page - Provider record page.
+ */
+export function toHubSpotRecordPage(
+  page: z.output<typeof HUBSPOT_PROVIDER_RECORD_PAGE_SCHEMA>,
+): z.input<typeof HUBSPOT_RECORD_PAGE_SCHEMA> {
+  return {
+    pageInfo: { after: page.paging?.next?.after },
+    records: page.results.map(toHubSpotRecord),
+    ...(page.total === undefined ? {} : { total: page.total }),
+  }
+}
+
+/**
+ * Converts typed property entries to HubSpot's provider property map.
+ *
+ * @param properties - Public property entries.
+ */
+export function toHubSpotProperties(
+  properties: z.output<typeof HUBSPOT_PROPERTY_VALUES_SCHEMA>,
+) {
+  return Object.fromEntries(
+    properties.map(({ name, value }) => [name, value ?? ""]),
+  )
+}

package/src/triggers.ts

@@ -11,6 +11,7 @@ import type { googleCalendarTriggerContracts } from "./google-calendar"
 import type { googleFormsTriggerContracts } from "./google-forms"
 import type { googleMeetTriggerContracts } from "./google-meet"
 import type { googleSheetsTriggerContracts } from "./google-sheets"
+import type { hubspotTriggerContracts } from "./hubspot"
 import type { linearTriggerContracts } from "./linear"
 import type { millionVerifierTriggerContracts } from "./millionverifier"
 import type { notionTriggerContracts } from "./notion"
@@ -38,6 +39,7 @@ export type TriggerContractMap = typeof airtableTriggerContracts &
   typeof googleFormsTriggerContracts &
   typeof googleMeetTriggerContracts &
   typeof googleSheetsTriggerContracts &
+  typeof hubspotTriggerContracts &
   typeof linearTriggerContracts &
   typeof millionVerifierTriggerContracts &
   typeof notionTriggerContracts &