@automate.ax/integration-contracts 0.145.1 → 0.146.0

package/src/highlevel/api.ts

@@ -0,0 +1,294 @@
+import { encodableSchema, type Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+import type { HighLevelOperationKey } from "./operation-manifest"
+import { highLevelOperation, highLevelOperationOutputSchema } from "./schemas"
+import type { HighLevelOperationInput, HighLevelOperationOutput } from "./types"
+
+const HIGH_LEVEL_API_BASE_URL = "https://services.leadconnectorhq.com/"
+const HIGH_LEVEL_API_ORIGIN = new URL(HIGH_LEVEL_API_BASE_URL).origin
+const HIGH_LEVEL_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+  locationId: z.string().min(1),
+})
+
+/** Resolved account accepted by the shared HighLevel API client. */
+export interface HighLevelResolvedAccount {
+  connectionMethodId: string
+  secret: Record<string, unknown>
+  serviceId: "highlevel"
+}
+
+/** Structured error returned by a rejected HighLevel request. */
+export class HighLevelApiError extends Error {
+  readonly body?: Encodable
+  readonly retryAfter?: string
+  readonly status: number
+
+  /**
+   * Creates an error from one rejected HighLevel response.
+   *
+   * @param options - Rejected response details.
+   * @param options.body - Encodable provider error body.
+   * @param options.retryAfter - Provider retry timing.
+   * @param options.status - HTTP status.
+   */
+  constructor(options: {
+    body?: Encodable
+    retryAfter?: string
+    status: number
+  }) {
+    super(
+      getErrorMessage(options.body) ??
+        `HighLevel API request failed with status ${options.status}.`,
+    )
+    this.name = "HighLevelApiError"
+    this.body = options.body
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates an authenticated client for the frozen HighLevel action surface.
+ *
+ * @param account - Resolved HighLevel account.
+ * @throws When the connection method or secret is invalid.
+ */
+export function getHighLevelApi(account: HighLevelResolvedAccount) {
+  const credentials = HIGH_LEVEL_SECRET_SCHEMA.parse(account.secret)
+  if (
+    account.connectionMethodId !== "oauth" &&
+    account.connectionMethodId !== "private-integration-token"
+  ) {
+    throw new Error(
+      `Unsupported HighLevel connection method: ${account.connectionMethodId}`,
+    )
+  }
+
+  return {
+    /**
+     * Executes and validates one named HighLevel OpenAPI operation.
+     *
+     * @param key - Frozen operation key.
+     * @param input - Flattened operation input.
+     */
+    async operation<TKey extends HighLevelOperationKey>(
+      key: TKey,
+      input: HighLevelOperationInput<TKey>,
+    ): Promise<HighLevelOperationOutput<TKey>> {
+      const definition = highLevelOperation(key)
+      const pathValues = new Map<string, unknown>()
+      const queryValues = new Map<string, unknown>()
+      const bodyValues: Record<string, unknown> = {}
+      const inputRecord = input as Record<string, unknown>
+
+      for (const name of definition.pathParameters) {
+        pathValues.set(name, inputRecord[name])
+      }
+      for (const { name } of definition.queryParameters) {
+        queryValues.set(name, inputRecord[name])
+      }
+      for (const name of definition.bodyParameters) {
+        if (inputRecord[name] !== undefined)
+          bodyValues[name] = inputRecord[name]
+      }
+      for (const placement of definition.locationPlacements) {
+        if (placement === "path")
+          pathValues.set("locationId", credentials.locationId)
+        if (placement === "query")
+          queryValues.set("locationId", credentials.locationId)
+        if (placement === "body") bodyValues.locationId = credentials.locationId
+      }
+
+      // Resolve path placeholders before applying the fixed-origin guard.
+      const path = definition.path.replace(
+        /\{([^}]+)\}/g,
+        (_match, name: string) => encodePathSegment(pathValues.get(name), name),
+      )
+      const normalizedPath = path.replace(/^\/+/, "")
+      const url = new URL(normalizedPath, HIGH_LEVEL_API_BASE_URL)
+      if (
+        !normalizedPath ||
+        normalizedPath.includes("://") ||
+        normalizedPath.includes("\\") ||
+        normalizedPath.includes("?") ||
+        normalizedPath.includes("#") ||
+        url.origin !== HIGH_LEVEL_API_ORIGIN
+      ) {
+        throw new TypeError(
+          "HighLevel API paths must remain provider-relative.",
+        )
+      }
+      for (const parameter of definition.queryParameters) {
+        appendQuery(
+          url,
+          { ...parameter, name: parameter.providerName },
+          queryValues.get(parameter.name),
+        )
+      }
+      if (definition.locationPlacements.includes("query")) {
+        url.searchParams.set(
+          definition.locationParameterNames.query ?? "locationId",
+          credentials.locationId,
+        )
+      }
+
+      const hasBody =
+        definition.bodyParameters.length > 0 ||
+        definition.locationPlacements.includes("body")
+      const response = await fetch(url, {
+        body: hasBody ? JSON.stringify(bodyValues) : undefined,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${credentials.accessToken}`,
+          Version: definition.apiVersion,
+          ...(hasBody ? { "Content-Type": "application/json" } : {}),
+        },
+        method: definition.method,
+        redirect: "error",
+      })
+      const parsed =
+        response.ok && definition.responseMode === "binary"
+          ? {
+              contentType:
+                response.headers.get("Content-Type") ??
+                "application/octet-stream",
+              data: Buffer.from(await response.arrayBuffer()).toString(
+                "base64",
+              ),
+            }
+          : await parseResponseText(response)
+      if (!response.ok) {
+        const body = encodableSchema.safeParse(parsed)
+        throw new HighLevelApiError({
+          ...(body.success && { body: body.data }),
+          retryAfter: getRetryAfter(response.headers),
+          status: response.status,
+        })
+      }
+      return highLevelOperationOutputSchema(key).parse(parsed)
+    },
+  }
+}
+
+/**
+ * Encodes one required path parameter.
+ *
+ * @param value - Parameter value.
+ * @param name - Parameter name.
+ * @throws When the value is not scalar.
+ */
+function encodePathSegment(value: unknown, name: string) {
+  if (typeof value !== "number" && typeof value !== "string") {
+    throw new TypeError(`HighLevel path parameter ${name} is required.`)
+  }
+  return encodeURIComponent(String(value))
+}
+
+/**
+ * Appends one OpenAPI query parameter.
+ *
+ * @param url - Provider request URL.
+ * @param parameter - Query serialization metadata.
+ * @param parameter.explode - Whether array items repeat the query key.
+ * @param parameter.name - Query parameter name.
+ * @param parameter.style - OpenAPI serialization style.
+ * @param value - Parameter value.
+ * @throws When the value is not scalar or an array of scalars.
+ */
+function appendQuery(
+  url: URL,
+  parameter: { explode: boolean; name: string; style: string },
+  value: unknown,
+) {
+  if (value == null) return
+  if (Array.isArray(value)) {
+    if (parameter.style === "form" && parameter.explode) {
+      for (const item of value)
+        url.searchParams.append(parameter.name, stringifyQueryValue(item))
+    } else {
+      url.searchParams.set(
+        parameter.name,
+        value.map(stringifyQueryValue).join(","),
+      )
+    }
+    return
+  }
+  url.searchParams.set(parameter.name, stringifyQueryValue(value))
+}
+
+/**
+ * Converts one supported query value to text.
+ *
+ * @param value - Query value.
+ * @throws When the value is not scalar.
+ */
+function stringifyQueryValue(value: unknown) {
+  if (
+    typeof value !== "boolean" &&
+    typeof value !== "number" &&
+    typeof value !== "string"
+  ) {
+    throw new TypeError("HighLevel query parameters must be scalar.")
+  }
+  return String(value)
+}
+
+/**
+ * Reads provider-directed retry timing.
+ *
+ * @param headers - Rejected response headers.
+ */
+function getRetryAfter(headers: Headers) {
+  const retryAfter = headers.get("Retry-After")
+  if (retryAfter) return retryAfter
+  const interval = headers.get("X-RateLimit-Interval-Milliseconds")
+  if (!interval || !/^\d+$/.test(interval)) return undefined
+  return String(Math.ceil(Number(interval) / 1_000))
+}
+
+/**
+ * Extracts a provider error message.
+ *
+ * @param value - Encodable provider error body.
+ */
+function getErrorMessage(value: Encodable | undefined) {
+  if (!isPlainObject(value)) return undefined
+  for (const key of ["message", "error", "error_description"]) {
+    const candidate = value[key]
+    if (typeof candidate === "string" && candidate.trim()) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Narrows a value to a plain object.
+ *
+ * @param value - Candidate value.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Parses JSON while retaining non-JSON provider bodies.
+ *
+ * @param value - Response body text.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return { response: value }
+  }
+}
+
+/**
+ * Reads one text or JSON provider response.
+ *
+ * @param response - Provider response to decode.
+ */
+async function parseResponseText(response: Response) {
+  const text = await response.text()
+  return text ? parseJson(text) : null
+}

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"