@automate.ax/integration-contracts 0.120.0 → 0.122.0

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

@@ -8,9 +8,11 @@ import type { cloudflareTriggerContracts } from "./cloudflare"
 import type { githubTriggerContracts } from "./github"
 import type { gmailTriggerContracts } from "./gmail"
 import type { googleCalendarTriggerContracts } from "./google-calendar"
+import type { googleDriveTriggerContracts } from "./google-drive"
 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"
@@ -35,9 +37,11 @@ export type TriggerContractMap = typeof airtableTriggerContracts &
   typeof githubTriggerContracts &
   typeof gmailTriggerContracts &
   typeof googleCalendarTriggerContracts &
+  typeof googleDriveTriggerContracts &
   typeof googleFormsTriggerContracts &
   typeof googleMeetTriggerContracts &
   typeof googleSheetsTriggerContracts &
+  typeof hubspotTriggerContracts &
   typeof linearTriggerContracts &
   typeof millionVerifierTriggerContracts &
   typeof notionTriggerContracts &