@automate.ax/integration-contracts 0.145.2 → 0.146.0

package/src/highlevel/events.ts

@@ -0,0 +1,355 @@
+/* oxlint-disable typescript/no-unsafe-type-assertion -- Object.keys and Object.fromEntries erase the exact generated webhook key correlation. */
+import { encodableSchema } from "@automate.ax/codec"
+import * as z from "zod"
+
+export const HIGH_LEVEL_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+const BASE_EVENT_FIELDS = {
+  locationId: z.string().min(1),
+  timestamp: z.iso.datetime({ offset: true }),
+  webhookId: z.string().min(1),
+} as const
+const CONTACT_FIELDS = {
+  ...BASE_EVENT_FIELDS,
+  address1: z.string().optional(),
+  assignedTo: z.string().optional(),
+  attachments: encodableSchema.array().optional(),
+  city: z.string().optional(),
+  companyName: z.string().optional(),
+  country: z.string().optional(),
+  customFields: encodableSchema.array().optional(),
+  dateAdded: z.string().optional(),
+  dateOfBirth: z.string().optional(),
+  dnd: z.boolean().optional(),
+  dndSettings: encodableSchema.optional(),
+  email: z.string().optional(),
+  firstName: z.string().optional(),
+  id: z.string().min(1),
+  lastName: z.string().optional(),
+  name: z.string().optional(),
+  phone: z.string().optional(),
+  postalCode: z.string().optional(),
+  source: z.string().optional(),
+  state: z.string().optional(),
+  tags: z.string().array().optional(),
+  website: z.string().optional(),
+} as const
+const OPPORTUNITY_FIELDS = {
+  ...BASE_EVENT_FIELDS,
+  assignedTo: z.string().optional(),
+  contactId: z.string().optional(),
+  dateAdded: z.string().optional(),
+  id: z.string().min(1),
+  monetaryValue: z.number().optional(),
+  name: z.string().optional(),
+  pipelineId: z.string().optional(),
+  pipelineStageId: z.string().optional(),
+  source: z.string().optional(),
+  status: z.string().optional(),
+} as const
+const TASK_FIELDS = {
+  ...BASE_EVENT_FIELDS,
+  assignedTo: z.string().optional(),
+  body: z.string().optional(),
+  contactId: z.string().optional(),
+  dateAdded: z.string().optional(),
+  dueDate: z.string().optional(),
+  id: z.string().min(1),
+  title: z.string().optional(),
+} as const
+const NOTE_FIELDS = {
+  ...BASE_EVENT_FIELDS,
+  body: z.string().optional(),
+  contactId: z.string().optional(),
+  dateAdded: z.string().optional(),
+  id: z.string().min(1),
+} as const
+const MESSAGE_FIELDS = {
+  ...BASE_EVENT_FIELDS,
+  attachments: encodableSchema.array().optional(),
+  bcc: z.union([z.string(), z.string().array()]).optional(),
+  bccList: z.string().array().optional(),
+  body: z.string().optional(),
+  callDuration: z.number().optional(),
+  callStatus: z.string().optional(),
+  cc: z.union([z.string(), z.string().array()]).optional(),
+  ccList: z.string().array().optional(),
+  chatWidgetId: z.string().optional(),
+  contactId: z.string().optional(),
+  contentType: z.string().optional(),
+  conversationId: z.string().optional(),
+  conversationProviderId: z.string().optional(),
+  dateAdded: z.string().optional(),
+  direction: z.string().optional(),
+  emailMessageId: z.string().optional(),
+  from: z.string().optional(),
+  messageId: z.string().optional(),
+  messageType: z.string().optional(),
+  messageTypeId: z.string().optional(),
+  messageTypeString: z.string().optional(),
+  provider: z.string().optional(),
+  source: z.string().optional(),
+  status: z.string().optional(),
+  subject: z.string().optional(),
+  threadId: z.string().optional(),
+  to: z.union([z.string(), z.string().array()]).optional(),
+  userId: z.string().optional(),
+} as const
+const USER_FIELDS = {
+  ...BASE_EVENT_FIELDS,
+  companyId: z.string().optional(),
+  email: z.string().optional(),
+  extension: z.string().optional(),
+  firstName: z.string().optional(),
+  id: z.string().min(1),
+  lastName: z.string().optional(),
+  locations: z.string().array().optional(),
+  permissions: encodableSchema.optional(),
+  phone: z.string().optional(),
+  role: z.string().optional(),
+  scopes: z.string().array().optional(),
+} as const
+const APPOINTMENT_FIELDS = {
+  ...BASE_EVENT_FIELDS,
+  appointment: z
+    .object({
+      address: z.string().optional(),
+      appointmentStatus: z.string().optional(),
+      assignedUserId: z.string().optional(),
+      calendarId: z.string().optional(),
+      contactId: z.string().optional(),
+      dateAdded: z.string().optional(),
+      dateUpdated: z.string().optional(),
+      endTime: z.string().optional(),
+      groupId: z.string().optional(),
+      id: z.string().min(1),
+      notes: z.string().optional(),
+      source: z.string().optional(),
+      startTime: z.string().optional(),
+      title: z.string().optional(),
+      users: z.string().array().optional(),
+    })
+    .catchall(encodableSchema),
+} as const
+
+export const HIGH_LEVEL_EVENT_SCHEMAS = {
+  AppointmentCreate: eventSchema("AppointmentCreate", APPOINTMENT_FIELDS),
+  AppointmentDelete: eventSchema("AppointmentDelete", APPOINTMENT_FIELDS),
+  AppointmentUpdate: eventSchema("AppointmentUpdate", APPOINTMENT_FIELDS),
+  CampaignStatusUpdate: eventSchema("CampaignStatusUpdate", {
+    ...BASE_EVENT_FIELDS,
+    contactId: z.string().optional(),
+    dateAdded: z.string().optional(),
+    id: z.string().min(1),
+    replied: z.string().optional(),
+    status: z.string().optional(),
+    templateId: z.string().optional(),
+  }),
+  ContactCreate: eventSchema("ContactCreate", CONTACT_FIELDS),
+  ContactDelete: eventSchema("ContactDelete", CONTACT_FIELDS),
+  ContactDndUpdate: eventSchema("ContactDndUpdate", CONTACT_FIELDS),
+  ContactTagUpdate: eventSchema("ContactTagUpdate", CONTACT_FIELDS),
+  ContactUpdate: eventSchema("ContactUpdate", CONTACT_FIELDS),
+  ConversationUnreadUpdate: eventSchema("ConversationUnreadUpdate", {
+    ...BASE_EVENT_FIELDS,
+    contactId: z.string().optional(),
+    deleted: z.boolean().optional(),
+    id: z.string().min(1),
+    inbox: z.boolean().optional(),
+    starred: z.boolean().optional(),
+    unreadCount: z.number().int().nonnegative().optional(),
+  }),
+  ConversationUpdate: eventSchema("ConversationUpdate", {
+    ...BASE_EVENT_FIELDS,
+    companyId: z.string().optional(),
+    contactId: z.string().optional(),
+    newConversationId: z.string().min(1),
+    oldConversationId: z.string().min(1),
+  }),
+  InboundMessage: eventSchema("InboundMessage", MESSAGE_FIELDS),
+  LocationUpdate: eventSchema("LocationUpdate", {
+    companyId: z.string().optional(),
+    email: z.string().optional(),
+    id: z.string().min(1),
+    locationId: z.string().min(1).optional(),
+    name: z.string().optional(),
+    stripeProductId: z.string().optional(),
+    timestamp: BASE_EVENT_FIELDS.timestamp,
+    webhookId: BASE_EVENT_FIELDS.webhookId,
+  }),
+  NoteCreate: eventSchema("NoteCreate", NOTE_FIELDS),
+  NoteDelete: eventSchema("NoteDelete", NOTE_FIELDS),
+  NoteUpdate: eventSchema("NoteUpdate", NOTE_FIELDS),
+  OpportunityAssignedToUpdate: eventSchema(
+    "OpportunityAssignedToUpdate",
+    OPPORTUNITY_FIELDS,
+  ),
+  OpportunityCreate: eventSchema("OpportunityCreate", OPPORTUNITY_FIELDS),
+  OpportunityDelete: eventSchema("OpportunityDelete", OPPORTUNITY_FIELDS),
+  OpportunityMonetaryValueUpdate: eventSchema(
+    "OpportunityMonetaryValueUpdate",
+    OPPORTUNITY_FIELDS,
+  ),
+  OpportunityStageUpdate: eventSchema(
+    "OpportunityStageUpdate",
+    OPPORTUNITY_FIELDS,
+  ),
+  OpportunityStatusUpdate: eventSchema(
+    "OpportunityStatusUpdate",
+    OPPORTUNITY_FIELDS,
+  ),
+  OpportunityUpdate: eventSchema("OpportunityUpdate", OPPORTUNITY_FIELDS),
+  OutboundMessage: eventSchema("OutboundMessage", MESSAGE_FIELDS),
+  TaskComplete: eventSchema("TaskComplete", TASK_FIELDS),
+  TaskCreate: eventSchema("TaskCreate", TASK_FIELDS),
+  TaskDelete: eventSchema("TaskDelete", TASK_FIELDS),
+  UserCreate: eventSchema("UserCreate", USER_FIELDS),
+  UserDelete: eventSchema("UserDelete", USER_FIELDS),
+  UserUpdate: eventSchema("UserUpdate", USER_FIELDS),
+} as const
+
+export const HIGH_LEVEL_WEBHOOK_EVENT_TYPES = Object.keys(
+  HIGH_LEVEL_EVENT_SCHEMAS,
+) as HighLevelWebhookEventType[]
+
+export type HighLevelWebhookEventType = keyof typeof HIGH_LEVEL_EVENT_SCHEMAS
+export type HighLevelWebhookEvent = z.output<
+  (typeof HIGH_LEVEL_EVENT_SCHEMAS)[HighLevelWebhookEventType]
+>
+
+export const HIGH_LEVEL_EVENT_SCHEMA = z.discriminatedUnion("type", [
+  HIGH_LEVEL_EVENT_SCHEMAS.AppointmentCreate,
+  HIGH_LEVEL_EVENT_SCHEMAS.AppointmentDelete,
+  HIGH_LEVEL_EVENT_SCHEMAS.AppointmentUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.CampaignStatusUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.ContactCreate,
+  HIGH_LEVEL_EVENT_SCHEMAS.ContactDelete,
+  HIGH_LEVEL_EVENT_SCHEMAS.ContactDndUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.ContactTagUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.ContactUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.ConversationUnreadUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.ConversationUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.InboundMessage,
+  HIGH_LEVEL_EVENT_SCHEMAS.LocationUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.NoteCreate,
+  HIGH_LEVEL_EVENT_SCHEMAS.NoteDelete,
+  HIGH_LEVEL_EVENT_SCHEMAS.NoteUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.OpportunityAssignedToUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.OpportunityCreate,
+  HIGH_LEVEL_EVENT_SCHEMAS.OpportunityDelete,
+  HIGH_LEVEL_EVENT_SCHEMAS.OpportunityMonetaryValueUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.OpportunityStageUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.OpportunityStatusUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.OpportunityUpdate,
+  HIGH_LEVEL_EVENT_SCHEMAS.OutboundMessage,
+  HIGH_LEVEL_EVENT_SCHEMAS.TaskComplete,
+  HIGH_LEVEL_EVENT_SCHEMAS.TaskCreate,
+  HIGH_LEVEL_EVENT_SCHEMAS.TaskDelete,
+  HIGH_LEVEL_EVENT_SCHEMAS.UserCreate,
+  HIGH_LEVEL_EVENT_SCHEMAS.UserDelete,
+  HIGH_LEVEL_EVENT_SCHEMAS.UserUpdate,
+])
+
+export const HIGH_LEVEL_APP_LIFECYCLE_EVENT_SCHEMA = z
+  .discriminatedUnion("type", [
+    eventSchema("INSTALL", {
+      appId: z.string().min(1),
+      companyId: z.string().min(1).optional(),
+      companyName: z.string().optional(),
+      isWhitelabelCompany: z.boolean().optional(),
+      locationId: z.string().min(1).optional(),
+      planId: z.string().optional(),
+      trial: encodableSchema.optional(),
+      userId: z.string().optional(),
+      whitelabelDetails: encodableSchema.optional(),
+    }),
+    eventSchema("UNINSTALL", {
+      appId: z.string().min(1),
+      companyId: z.string().min(1).optional(),
+      locationId: z.string().min(1).optional(),
+    }),
+  ])
+  .refine((event) => event.locationId || event.companyId, {
+    message: "HighLevel app lifecycle events require a location or company ID.",
+  })
+
+export type HighLevelAppLifecycleEvent = z.output<
+  typeof HIGH_LEVEL_APP_LIFECYCLE_EVENT_SCHEMA
+>
+
+export const highLevelEventTypeMap = {
+  AppointmentCreate: "highlevel.appointment.created",
+  AppointmentDelete: "highlevel.appointment.deleted",
+  AppointmentUpdate: "highlevel.appointment.updated",
+  CampaignStatusUpdate: "highlevel.campaign.statusUpdated",
+  ContactCreate: "highlevel.contact.created",
+  ContactDelete: "highlevel.contact.deleted",
+  ContactDndUpdate: "highlevel.contact.dndUpdated",
+  ContactTagUpdate: "highlevel.contact.tagsUpdated",
+  ContactUpdate: "highlevel.contact.updated",
+  ConversationUnreadUpdate: "highlevel.conversation.unreadUpdated",
+  ConversationUpdate: "highlevel.conversation.updated",
+  InboundMessage: "highlevel.message.received",
+  LocationUpdate: "highlevel.location.updated",
+  NoteCreate: "highlevel.note.created",
+  NoteDelete: "highlevel.note.deleted",
+  NoteUpdate: "highlevel.note.updated",
+  OpportunityAssignedToUpdate: "highlevel.opportunity.assigneeUpdated",
+  OpportunityCreate: "highlevel.opportunity.created",
+  OpportunityDelete: "highlevel.opportunity.deleted",
+  OpportunityMonetaryValueUpdate: "highlevel.opportunity.valueUpdated",
+  OpportunityStageUpdate: "highlevel.opportunity.stageUpdated",
+  OpportunityStatusUpdate: "highlevel.opportunity.statusUpdated",
+  OpportunityUpdate: "highlevel.opportunity.updated",
+  OutboundMessage: "highlevel.message.sent",
+  TaskComplete: "highlevel.task.completed",
+  TaskCreate: "highlevel.task.created",
+  TaskDelete: "highlevel.task.deleted",
+  UserCreate: "highlevel.user.created",
+  UserDelete: "highlevel.user.deleted",
+  UserUpdate: "highlevel.user.updated",
+} as const satisfies Record<HighLevelWebhookEventType, `highlevel.${string}`>
+
+type HighLevelTriggerContract<TEvent> = {
+  readonly configSchema: typeof HIGH_LEVEL_TRIGGER_CONFIG_SCHEMA
+  readonly eventSchema: z.ZodType<TEvent>
+}
+
+/** Typed semantic contracts derived from provider webhook discriminators. */
+type HighLevelSemanticTriggerContracts = {
+  readonly [TType in HighLevelWebhookEventType as (typeof highLevelEventTypeMap)[TType]]: HighLevelTriggerContract<
+    z.output<(typeof HIGH_LEVEL_EVENT_SCHEMAS)[TType]>
+  >
+}
+
+export const highLevelTriggerContracts = {
+  "highlevel.event": {
+    configSchema: HIGH_LEVEL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: HIGH_LEVEL_EVENT_SCHEMA,
+  },
+  ...Object.fromEntries(
+    Object.entries(highLevelEventTypeMap).map(([providerType, eventType]) => [
+      eventType,
+      {
+        configSchema: HIGH_LEVEL_TRIGGER_CONFIG_SCHEMA,
+        eventSchema:
+          HIGH_LEVEL_EVENT_SCHEMAS[providerType as HighLevelWebhookEventType],
+      },
+    ]),
+  ),
+} as unknown as HighLevelSemanticTriggerContracts & {
+  readonly "highlevel.event": HighLevelTriggerContract<HighLevelWebhookEvent>
+}
+
+/**
+ * Creates an extensible schema for one HighLevel webhook discriminator.
+ *
+ * @param type - Provider event discriminator.
+ * @param shape - Known fields for the event.
+ */
+function eventSchema<
+  const TType extends string,
+  TShape extends Record<string, z.ZodType>,
+>(type: TType, shape: TShape) {
+  return z.object({ ...shape, type: z.literal(type) }).catchall(encodableSchema)
+}

package/src/highlevel/index.ts

@@ -0,0 +1,6 @@
+export * from "./api"
+export * from "./events"
+export * from "./operation-manifest"
+export * from "./schemas"
+export type { HighLevelOperationMap } from "./openapi-types.generated"
+export type * from "./types"