@automate.ax/integration-contracts 0.147.1 → 0.148.0

package/src/kit/events.ts

@@ -0,0 +1,352 @@
+import { encodableSchema, type Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+
+/** Kit webhook event types currently available for endpoint subscriptions. */
+export const KIT_WEBHOOK_EVENT_TYPES = [
+  "subscriber.created",
+  "subscriber.activated",
+  "subscriber.unsubscribed",
+  "subscriber.bounced",
+  "subscriber.complained",
+  "subscriber.subscribed_to_form",
+  "subscriber.added_to_sequence",
+  "subscriber.sequence_completed",
+  "subscriber.tag_added",
+  "subscriber.tag_removed",
+  "subscriber.custom_field_value_updated",
+  "tag.created",
+  "tag.deleted",
+  "custom_field.created",
+  "custom_field.deleted",
+  "sequence.created",
+  "sequence.deleted",
+  "sequence.published",
+  "sequence.disabled",
+  "broadcast.created",
+  "broadcast.sent",
+  "broadcast.deleted",
+  "post.published",
+] as const
+
+export type KitWebhookEventType = (typeof KIT_WEBHOOK_EVENT_TYPES)[number]
+
+const KIT_SUBSCRIBER_SCHEMA = z
+  .looseObject({
+    createdAt: z.iso.datetime({ offset: true }),
+    emailAddress: z.email(),
+    fields: z.record(z.string(), z.string().nullable()),
+    firstName: z.string().nullable(),
+    id: z.number().int(),
+    state: z.enum(["active", "bounced", "cancelled", "complained", "inactive"]),
+  })
+  .catchall(encodableSchema)
+const KIT_FORM_SCHEMA = z
+  .looseObject({
+    archived: z.boolean(),
+    createdAt: z.iso.datetime({ offset: true }),
+    format: z.string(),
+    id: z.number().int(),
+    name: z.string(),
+    type: z.enum(["embed", "hosted"]),
+    uid: z.string(),
+  })
+  .catchall(encodableSchema)
+const KIT_SEQUENCE_SCHEMA = z
+  .looseObject({
+    active: z.boolean(),
+    createdAt: z.iso.datetime({ offset: true }),
+    emailTemplateId: z.number().int().nullable(),
+    hold: z.boolean(),
+    id: z.number().int(),
+    name: z.string(),
+    repeat: z.boolean(),
+    updatedAt: z.iso.datetime({ offset: true }),
+  })
+  .catchall(encodableSchema)
+const KIT_TAG_SCHEMA = z
+  .looseObject({
+    createdAt: z.iso.datetime({ offset: true }),
+    id: z.number().int(),
+    name: z.string(),
+  })
+  .catchall(encodableSchema)
+const KIT_CUSTOM_FIELD_SCHEMA = z
+  .looseObject({
+    id: z.number().int(),
+    key: z.string(),
+    label: z.string(),
+    name: z.string(),
+    value: z.string().nullable().optional(),
+  })
+  .catchall(encodableSchema)
+const KIT_BROADCAST_SCHEMA = z
+  .looseObject({
+    createdAt: z.iso.datetime({ offset: true }),
+    description: z.string().nullable(),
+    id: z.number().int(),
+    previewText: z.string().nullable(),
+    public: z.boolean(),
+    publicationId: z.number().int(),
+    publishedAt: z.iso.datetime({ offset: true }).nullable(),
+    sendAt: z.iso.datetime({ offset: true }).nullable(),
+    status: z.string(),
+    subject: z.string(),
+  })
+  .catchall(encodableSchema)
+const KIT_POST_SCHEMA = z
+  .looseObject({
+    id: z.number().int(),
+    isPaid: z.boolean(),
+    publicUrl: z.url(),
+    publicationId: z.number().int(),
+    publishedAt: z.iso.datetime({ offset: true }),
+    slug: z.string(),
+    title: z.string(),
+  })
+  .catchall(encodableSchema)
+
+const SUBSCRIBER_DATA_SCHEMA = z
+  .looseObject({ subscriber: KIT_SUBSCRIBER_SCHEMA })
+  .catchall(encodableSchema)
+
+const KIT_EVENT_DATA_SCHEMAS = {
+  "broadcast.created": z.looseObject({ broadcast: KIT_BROADCAST_SCHEMA }),
+  "broadcast.deleted": z.looseObject({ broadcast: KIT_BROADCAST_SCHEMA }),
+  "broadcast.sent": z.looseObject({ broadcast: KIT_BROADCAST_SCHEMA }),
+  "custom_field.created": z.looseObject({
+    customField: KIT_CUSTOM_FIELD_SCHEMA,
+  }),
+  "custom_field.deleted": z.looseObject({
+    customField: KIT_CUSTOM_FIELD_SCHEMA,
+  }),
+  "post.published": z.looseObject({ post: KIT_POST_SCHEMA }),
+  "sequence.created": z.looseObject({ sequence: KIT_SEQUENCE_SCHEMA }),
+  "sequence.deleted": z.looseObject({ sequence: KIT_SEQUENCE_SCHEMA }),
+  "sequence.disabled": z.looseObject({ sequence: KIT_SEQUENCE_SCHEMA }),
+  "sequence.published": z.looseObject({ sequence: KIT_SEQUENCE_SCHEMA }),
+  "subscriber.activated": SUBSCRIBER_DATA_SCHEMA,
+  "subscriber.added_to_sequence": SUBSCRIBER_DATA_SCHEMA.extend({
+    sequence: KIT_SEQUENCE_SCHEMA,
+  }),
+  "subscriber.bounced": SUBSCRIBER_DATA_SCHEMA,
+  "subscriber.complained": SUBSCRIBER_DATA_SCHEMA,
+  "subscriber.created": SUBSCRIBER_DATA_SCHEMA,
+  "subscriber.custom_field_value_updated": SUBSCRIBER_DATA_SCHEMA.extend({
+    customField: KIT_CUSTOM_FIELD_SCHEMA,
+  }),
+  "subscriber.sequence_completed": SUBSCRIBER_DATA_SCHEMA.extend({
+    sequence: KIT_SEQUENCE_SCHEMA,
+  }),
+  "subscriber.subscribed_to_form": SUBSCRIBER_DATA_SCHEMA.extend({
+    form: KIT_FORM_SCHEMA,
+  }),
+  "subscriber.tag_added": SUBSCRIBER_DATA_SCHEMA.extend({
+    tag: KIT_TAG_SCHEMA,
+  }),
+  "subscriber.tag_removed": SUBSCRIBER_DATA_SCHEMA.extend({
+    tag: KIT_TAG_SCHEMA,
+  }),
+  "subscriber.unsubscribed": SUBSCRIBER_DATA_SCHEMA,
+  "tag.created": z.looseObject({ tag: KIT_TAG_SCHEMA }),
+  "tag.deleted": z.looseObject({ tag: KIT_TAG_SCHEMA }),
+} as const satisfies Record<KitWebhookEventType, z.ZodType>
+
+/** One normalized Kit webhook event narrowed by provider type. */
+export type KitEvent<TType extends KitWebhookEventType = KitWebhookEventType> =
+  TType extends KitWebhookEventType
+    ? {
+        readonly [key: string]: Encodable
+        created: string
+        data: z.output<(typeof KIT_EVENT_DATA_SCHEMAS)[TType]> & {
+          readonly [key: string]: Encodable
+        }
+        id: string
+        type: TType
+      }
+    : never
+
+/** One parsed Kit webhook delivery containing one to 100 same-type events. */
+export interface KitWebhookEnvelope {
+  readonly [key: string]: Encodable
+  deliveryId: number
+  events: KitEvent[]
+}
+
+export const KIT_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+/** Validates any currently available normalized Kit event. */
+export const KIT_EVENT_SCHEMA: z.ZodType<KitEvent> = z.custom<KitEvent>(
+  (value) => {
+    if (
+      typeof value !== "object" ||
+      value === null ||
+      !("type" in value) ||
+      typeof value.type !== "string" ||
+      !isKitWebhookEventType(value.type)
+    ) {
+      return false
+    }
+    return kitSemanticEventSchema(value.type).safeParse(value).success
+  },
+)
+
+/** Parses and normalizes Kit's provider-native delivery envelope. */
+export const KIT_WEBHOOK_ENVELOPE_SCHEMA: z.ZodType<KitWebhookEnvelope> = z
+  .preprocess(
+    (value) => camelizeKitWebhookValue(value),
+    z
+      .looseObject({
+        deliveryId: z.number().int(),
+        events: KIT_EVENT_SCHEMA.array().min(1).max(100),
+      })
+      .catchall(encodableSchema),
+  )
+  .refine(
+    (delivery) =>
+      delivery.events.every((event) => event.type === delivery.events[0]?.type),
+    { message: "Kit webhook deliveries must contain one event type." },
+  )
+
+/** Platform event type emitted for each exact Kit provider event. */
+export const KIT_EVENT_TYPE_MAP = {
+  "broadcast.created": "kit.broadcast.created",
+  "broadcast.deleted": "kit.broadcast.deleted",
+  "broadcast.sent": "kit.broadcast.sent",
+  "custom_field.created": "kit.customField.created",
+  "custom_field.deleted": "kit.customField.deleted",
+  "post.published": "kit.post.published",
+  "sequence.created": "kit.sequence.created",
+  "sequence.deleted": "kit.sequence.deleted",
+  "sequence.disabled": "kit.sequence.disabled",
+  "sequence.published": "kit.sequence.published",
+  "subscriber.activated": "kit.subscriber.activated",
+  "subscriber.added_to_sequence": "kit.subscriber.addedToSequence",
+  "subscriber.bounced": "kit.subscriber.bounced",
+  "subscriber.complained": "kit.subscriber.complained",
+  "subscriber.created": "kit.subscriber.created",
+  "subscriber.custom_field_value_updated":
+    "kit.subscriber.customFieldValueUpdated",
+  "subscriber.sequence_completed": "kit.subscriber.sequenceCompleted",
+  "subscriber.subscribed_to_form": "kit.subscriber.subscribedToForm",
+  "subscriber.tag_added": "kit.subscriber.tagAdded",
+  "subscriber.tag_removed": "kit.subscriber.tagRemoved",
+  "subscriber.unsubscribed": "kit.subscriber.unsubscribed",
+  "tag.created": "kit.tag.created",
+  "tag.deleted": "kit.tag.deleted",
+} as const satisfies Record<KitWebhookEventType, string>
+
+type KitTriggerContract<TEvent> = {
+  readonly configSchema: typeof KIT_TRIGGER_CONFIG_SCHEMA
+  readonly eventSchema: z.ZodType<TEvent>
+}
+
+/** Semantic contracts keyed by every public Kit platform event type. */
+type KitSemanticContracts = {
+  readonly [TType in KitWebhookEventType as (typeof KIT_EVENT_TYPE_MAP)[TType]]: KitTriggerContract<
+    KitEvent<TType>
+  >
+} & { readonly "kit.event": KitTriggerContract<KitEvent> }
+
+/** Exact provider-to-platform Kit trigger contract map. */
+export const kitTriggerContracts: KitSemanticContracts = {
+  "kit.broadcast.created": contract("broadcast.created"),
+  "kit.broadcast.deleted": contract("broadcast.deleted"),
+  "kit.broadcast.sent": contract("broadcast.sent"),
+  "kit.customField.created": contract("custom_field.created"),
+  "kit.customField.deleted": contract("custom_field.deleted"),
+  "kit.event": {
+    configSchema: KIT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: KIT_EVENT_SCHEMA,
+  },
+  "kit.post.published": contract("post.published"),
+  "kit.sequence.created": contract("sequence.created"),
+  "kit.sequence.deleted": contract("sequence.deleted"),
+  "kit.sequence.disabled": contract("sequence.disabled"),
+  "kit.sequence.published": contract("sequence.published"),
+  "kit.subscriber.activated": contract("subscriber.activated"),
+  "kit.subscriber.addedToSequence": contract("subscriber.added_to_sequence"),
+  "kit.subscriber.bounced": contract("subscriber.bounced"),
+  "kit.subscriber.complained": contract("subscriber.complained"),
+  "kit.subscriber.created": contract("subscriber.created"),
+  "kit.subscriber.customFieldValueUpdated": contract(
+    "subscriber.custom_field_value_updated",
+  ),
+  "kit.subscriber.sequenceCompleted": contract("subscriber.sequence_completed"),
+  "kit.subscriber.subscribedToForm": contract("subscriber.subscribed_to_form"),
+  "kit.subscriber.tagAdded": contract("subscriber.tag_added"),
+  "kit.subscriber.tagRemoved": contract("subscriber.tag_removed"),
+  "kit.subscriber.unsubscribed": contract("subscriber.unsubscribed"),
+  "kit.tag.created": contract("tag.created"),
+  "kit.tag.deleted": contract("tag.deleted"),
+}
+
+/**
+ * Builds a schema narrowed to one exact Kit webhook event.
+ *
+ * @param type Provider event type.
+ */
+export function kitSemanticEventSchema<TType extends KitWebhookEventType>(
+  type: TType,
+): z.ZodType<KitEvent<TType>> {
+  const schema = z
+    .looseObject({
+      created: z.iso.datetime({ offset: true }),
+      data: KIT_EVENT_DATA_SCHEMAS[type],
+      id: z.uuid(),
+      type: z.literal(type),
+    })
+    .catchall(encodableSchema)
+  return z.custom<KitEvent<TType>>((value) => schema.safeParse(value).success)
+}
+
+/**
+ * Returns the broad and exact platform types for one Kit event.
+ *
+ * @param type Provider event type.
+ */
+export function getKitEventTypes(type: KitWebhookEventType) {
+  return ["kit.event", KIT_EVENT_TYPE_MAP[type]] as const
+}
+
+/**
+ * Builds one semantic trigger contract.
+ *
+ * @param type Provider event type.
+ */
+function contract<TType extends KitWebhookEventType>(type: TType) {
+  return {
+    configSchema: KIT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: kitSemanticEventSchema(type),
+  }
+}
+
+/**
+ * Narrows a provider string to a supported Kit event type.
+ *
+ * @param value Candidate event type.
+ */
+function isKitWebhookEventType(value: string): value is KitWebhookEventType {
+  return (KIT_WEBHOOK_EVENT_TYPES as readonly string[]).includes(value)
+}
+
+/**
+ * Converts webhook keys to public camelCase while preserving field names.
+ *
+ * @param value Provider webhook value.
+ * @param parentKey Parent provider key.
+ */
+function camelizeKitWebhookValue(value: unknown, parentKey?: string): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => camelizeKitWebhookValue(item))
+  }
+  if (typeof value !== "object" || value === null) return value
+  if (parentKey === "fields") return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key.replace(/_([a-z\d])/g, (_match, letter: string) =>
+        letter.toUpperCase(),
+      ),
+      camelizeKitWebhookValue(item, key),
+    ]),
+  )
+}

package/src/kit/index.ts

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