@automate.ax/integration-contracts 0.147.0 → 0.148.0

package/src/kit/operation-manifest.ts

@@ -0,0 +1,771 @@
+/** Retry classification for one Kit operation. */
+export type KitReplaySafety = "safe" | "unsafe"
+
+/** HTTP method supported by one Kit operation. */
+export type KitHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT"
+
+/** Hand-authored public metadata bound to one official Kit V4 operation. */
+export interface KitOperationDefinition {
+  readonly alias: string
+  readonly description: string
+  readonly exportName: string
+  readonly method: KitHttpMethod
+  readonly oauthOnly: boolean
+  readonly path: string
+  readonly replaySafety: KitReplaySafety
+  readonly title: string
+}
+
+/** Complete practical Kit V4 action surface with verifiable request contracts. */
+export const KIT_OPERATION_DEFINITIONS = [
+  operation(
+    "getCurrentAccount",
+    "GET",
+    "/v4/account",
+    "getKitCurrentAccount",
+    "Get current Kit account",
+    "Returns the authenticated Kit account and user identity.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listColors",
+    "GET",
+    "/v4/account/colors",
+    "listKitColors",
+    "List Kit colors",
+    "Lists the account's saved brand color palette.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateColors",
+    "PUT",
+    "/v4/account/colors",
+    "updateKitColors",
+    "Update Kit colors",
+    "Replaces the account's saved brand color palette.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getCreatorProfile",
+    "GET",
+    "/v4/account/creator_profile",
+    "getKitCreatorProfile",
+    "Get Kit creator profile",
+    "Returns the account's public creator profile.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getEmailStats",
+    "GET",
+    "/v4/account/email_stats",
+    "getKitEmailStats",
+    "Get Kit email stats",
+    "Returns account-level email performance for the last 90 days.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getGrowthStats",
+    "GET",
+    "/v4/account/growth_stats",
+    "getKitGrowthStats",
+    "Get Kit growth stats",
+    "Returns subscriber growth statistics for a selected period.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listBroadcasts",
+    "GET",
+    "/v4/broadcasts",
+    "listKitBroadcasts",
+    "List Kit broadcasts",
+    "Lists broadcasts with cursor pagination and lifecycle filters.",
+    "safe",
+    false,
+  ),
+  operation(
+    "createBroadcast",
+    "POST",
+    "/v4/broadcasts",
+    "createKitBroadcast",
+    "Create Kit broadcast",
+    "Creates a draft or scheduled Kit broadcast.",
+    "unsafe",
+    false,
+  ),
+  operation(
+    "listBroadcastStats",
+    "GET",
+    "/v4/broadcasts/stats",
+    "listKitBroadcastStats",
+    "List Kit broadcast stats",
+    "Lists delivery and engagement statistics for broadcasts.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listBroadcastLinkClicks",
+    "GET",
+    "/v4/broadcasts/{broadcast_id}/clicks",
+    "listKitBroadcastLinkClicks",
+    "List Kit broadcast link clicks",
+    "Lists link-level click performance for a broadcast.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getBroadcastStats",
+    "GET",
+    "/v4/broadcasts/{broadcast_id}/stats",
+    "getKitBroadcastStats",
+    "Get Kit broadcast stats",
+    "Returns delivery and engagement statistics for one broadcast.",
+    "safe",
+    false,
+  ),
+  operation(
+    "deleteBroadcast",
+    "DELETE",
+    "/v4/broadcasts/{id}",
+    "deleteKitBroadcast",
+    "Delete Kit broadcast",
+    "Permanently deletes a draft or scheduled broadcast.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getBroadcast",
+    "GET",
+    "/v4/broadcasts/{id}",
+    "getKitBroadcast",
+    "Get Kit broadcast",
+    "Returns one broadcast with content, targeting, and publication settings.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateBroadcast",
+    "PUT",
+    "/v4/broadcasts/{id}",
+    "updateKitBroadcast",
+    "Update Kit broadcast",
+    "Updates a draft or scheduled broadcast.",
+    "safe",
+    false,
+  ),
+  operation(
+    "bulkCreateCustomFields",
+    "POST",
+    "/v4/bulk/custom_fields",
+    "bulkCreateKitCustomFields",
+    "Bulk create Kit custom fields",
+    "Creates custom fields synchronously or as an asynchronous bulk job.",
+    "unsafe",
+    true,
+  ),
+  operation(
+    "bulkUpdateSubscriberCustomFieldValues",
+    "POST",
+    "/v4/bulk/custom_fields/subscribers",
+    "bulkUpdateKitSubscriberCustomFieldValues",
+    "Bulk update Kit subscriber custom fields",
+    "Updates custom field values across subscribers in one bulk request.",
+    "safe",
+    true,
+  ),
+  operation(
+    "listCustomFields",
+    "GET",
+    "/v4/custom_fields",
+    "listKitCustomFields",
+    "List Kit custom fields",
+    "Lists custom fields with cursor pagination.",
+    "safe",
+    false,
+  ),
+  operation(
+    "createCustomField",
+    "POST",
+    "/v4/custom_fields",
+    "createKitCustomField",
+    "Create Kit custom field",
+    "Creates one account custom field.",
+    "unsafe",
+    false,
+  ),
+  operation(
+    "deleteCustomField",
+    "DELETE",
+    "/v4/custom_fields/{id}",
+    "deleteKitCustomField",
+    "Delete Kit custom field",
+    "Deletes a custom field and all subscriber values stored in it.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateCustomField",
+    "PUT",
+    "/v4/custom_fields/{id}",
+    "updateKitCustomField",
+    "Update Kit custom field",
+    "Renames one custom field.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listEmailTemplates",
+    "GET",
+    "/v4/email_templates",
+    "listKitEmailTemplates",
+    "List Kit email templates",
+    "Lists account email templates with cursor pagination.",
+    "safe",
+    false,
+  ),
+  operation(
+    "bulkAddSubscribersToForms",
+    "POST",
+    "/v4/bulk/forms/subscribers",
+    "bulkAddKitSubscribersToForms",
+    "Bulk add Kit subscribers to forms",
+    "Adds subscribers to forms synchronously or as an asynchronous bulk job.",
+    "safe",
+    true,
+  ),
+  operation(
+    "listForms",
+    "GET",
+    "/v4/forms",
+    "listKitForms",
+    "List Kit forms",
+    "Lists forms and landing pages with status and type filters.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listFormSubscribers",
+    "GET",
+    "/v4/forms/{form_id}/subscribers",
+    "listKitFormSubscribers",
+    "List Kit form subscribers",
+    "Lists subscribers associated with one form.",
+    "safe",
+    false,
+  ),
+  operation(
+    "addSubscriberToFormByEmailAddress",
+    "POST",
+    "/v4/forms/{form_id}/subscribers",
+    "addKitSubscriberToFormByEmailAddress",
+    "Add Kit subscriber to form by email",
+    "Adds an existing subscriber to a form by email address.",
+    "safe",
+    false,
+  ),
+  operation(
+    "addSubscriberToForm",
+    "POST",
+    "/v4/forms/{form_id}/subscribers/{id}",
+    "addKitSubscriberToForm",
+    "Add Kit subscriber to form",
+    "Adds an existing subscriber to a form by subscriber ID.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listPosts",
+    "GET",
+    "/v4/posts",
+    "listKitPosts",
+    "List Kit posts",
+    "Lists posts published to the creator's Kit site or email audience.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getPost",
+    "GET",
+    "/v4/posts/{id}",
+    "getKitPost",
+    "Get Kit post",
+    "Returns one post with content, publication, and SEO fields.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listPurchases",
+    "GET",
+    "/v4/purchases",
+    "listKitPurchases",
+    "List Kit purchases",
+    "Lists purchases recorded in the account.",
+    "safe",
+    true,
+  ),
+  operation(
+    "createPurchase",
+    "POST",
+    "/v4/purchases",
+    "createKitPurchase",
+    "Create Kit purchase",
+    "Records a purchase against a subscriber.",
+    "unsafe",
+    true,
+  ),
+  operation(
+    "getPurchase",
+    "GET",
+    "/v4/purchases/{id}",
+    "getKitPurchase",
+    "Get Kit purchase",
+    "Returns one recorded purchase.",
+    "safe",
+    true,
+  ),
+  operation(
+    "listSegments",
+    "GET",
+    "/v4/segments",
+    "listKitSegments",
+    "List Kit segments",
+    "Lists account segments with cursor pagination.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listSequenceEmails",
+    "GET",
+    "/v4/sequences/{sequence_id}/emails",
+    "listKitSequenceEmails",
+    "List Kit sequence emails",
+    "Lists the email steps in one sequence.",
+    "safe",
+    false,
+  ),
+  operation(
+    "createSequenceEmail",
+    "POST",
+    "/v4/sequences/{sequence_id}/emails",
+    "createKitSequenceEmail",
+    "Create Kit sequence email",
+    "Adds one email step to a sequence.",
+    "unsafe",
+    false,
+  ),
+  operation(
+    "deleteSequenceEmail",
+    "DELETE",
+    "/v4/sequences/{sequence_id}/emails/{id}",
+    "deleteKitSequenceEmail",
+    "Delete Kit sequence email",
+    "Permanently removes one email from a sequence.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getSequenceEmail",
+    "GET",
+    "/v4/sequences/{sequence_id}/emails/{id}",
+    "getKitSequenceEmail",
+    "Get Kit sequence email",
+    "Returns one sequence email with its full content.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateSequenceEmail",
+    "PUT",
+    "/v4/sequences/{sequence_id}/emails/{id}",
+    "updateKitSequenceEmail",
+    "Update Kit sequence email",
+    "Updates one sequence email's content, timing, position, or state.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listSequences",
+    "GET",
+    "/v4/sequences",
+    "listKitSequences",
+    "List Kit sequences",
+    "Lists automated email sequences.",
+    "safe",
+    false,
+  ),
+  operation(
+    "createSequence",
+    "POST",
+    "/v4/sequences",
+    "createKitSequence",
+    "Create Kit sequence",
+    "Creates an empty automated email sequence.",
+    "unsafe",
+    false,
+  ),
+  operation(
+    "deleteSequence",
+    "DELETE",
+    "/v4/sequences/{id}",
+    "deleteKitSequence",
+    "Delete Kit sequence",
+    "Soft-deletes a sequence and stops active delivery.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getSequence",
+    "GET",
+    "/v4/sequences/{id}",
+    "getKitSequence",
+    "Get Kit sequence",
+    "Returns one sequence and its delivery settings.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateSequence",
+    "PUT",
+    "/v4/sequences/{id}",
+    "updateKitSequence",
+    "Update Kit sequence",
+    "Updates one sequence's schedule and delivery settings.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listSequenceSubscribers",
+    "GET",
+    "/v4/sequences/{sequence_id}/subscribers",
+    "listKitSequenceSubscribers",
+    "List Kit sequence subscribers",
+    "Lists subscribers enrolled in one sequence.",
+    "safe",
+    false,
+  ),
+  operation(
+    "addSubscriberToSequenceByEmailAddress",
+    "POST",
+    "/v4/sequences/{sequence_id}/subscribers",
+    "addKitSubscriberToSequenceByEmailAddress",
+    "Add Kit subscriber to sequence by email",
+    "Adds an existing subscriber to a sequence by email address.",
+    "safe",
+    false,
+  ),
+  operation(
+    "addSubscriberToSequence",
+    "POST",
+    "/v4/sequences/{sequence_id}/subscribers/{id}",
+    "addKitSubscriberToSequence",
+    "Add Kit subscriber to sequence",
+    "Adds an existing subscriber to a sequence by subscriber ID.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listSnippets",
+    "GET",
+    "/v4/snippets",
+    "listKitSnippets",
+    "List Kit snippets",
+    "Lists reusable email snippets.",
+    "safe",
+    false,
+  ),
+  operation(
+    "createSnippet",
+    "POST",
+    "/v4/snippets",
+    "createKitSnippet",
+    "Create Kit snippet",
+    "Creates a reusable email snippet.",
+    "unsafe",
+    false,
+  ),
+  operation(
+    "getSnippet",
+    "GET",
+    "/v4/snippets/{id}",
+    "getKitSnippet",
+    "Get Kit snippet",
+    "Returns one reusable snippet with full content.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateSnippet",
+    "PUT",
+    "/v4/snippets/{id}",
+    "updateKitSnippet",
+    "Update Kit snippet",
+    "Updates a snippet's name, content, or archive state.",
+    "safe",
+    false,
+  ),
+  operation(
+    "bulkCreateSubscribers",
+    "POST",
+    "/v4/bulk/subscribers",
+    "bulkCreateKitSubscribers",
+    "Bulk create Kit subscribers",
+    "Creates or updates subscribers in one bulk request.",
+    "safe",
+    true,
+  ),
+  operation(
+    "listSubscribers",
+    "GET",
+    "/v4/subscribers",
+    "listKitSubscribers",
+    "List Kit subscribers",
+    "Lists subscribers with cursor, status, date, and engagement sorting filters.",
+    "safe",
+    false,
+  ),
+  operation(
+    "createSubscriber",
+    "POST",
+    "/v4/subscribers",
+    "createKitSubscriber",
+    "Create Kit subscriber",
+    "Creates or updates a subscriber by email address.",
+    "safe",
+    false,
+  ),
+  operation(
+    "filterSubscribers",
+    "POST",
+    "/v4/subscribers/filter",
+    "filterKitSubscribers",
+    "Filter Kit subscribers",
+    "Filters subscribers by engagement, signup, state, and tags.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getSubscriber",
+    "GET",
+    "/v4/subscribers/{id}",
+    "getKitSubscriber",
+    "Get Kit subscriber",
+    "Returns one subscriber and their custom field values.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateSubscriber",
+    "PUT",
+    "/v4/subscribers/{id}",
+    "updateKitSubscriber",
+    "Update Kit subscriber",
+    "Updates one subscriber and their custom field values.",
+    "safe",
+    false,
+  ),
+  operation(
+    "unsubscribeSubscriber",
+    "POST",
+    "/v4/subscribers/{id}/unsubscribe",
+    "unsubscribeKitSubscriber",
+    "Unsubscribe Kit subscriber",
+    "Unsubscribes a subscriber from all future Kit email.",
+    "safe",
+    false,
+  ),
+  operation(
+    "deleteSubscriberLocation",
+    "DELETE",
+    "/v4/subscribers/{subscriber_id}/location",
+    "deleteKitSubscriberLocation",
+    "Delete Kit subscriber location",
+    "Removes a subscriber's pinned location.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateSubscriberLocation",
+    "PATCH",
+    "/v4/subscribers/{subscriber_id}/location",
+    "updateKitSubscriberLocation",
+    "Update Kit subscriber location",
+    "Replaces a subscriber's pinned location.",
+    "safe",
+    false,
+  ),
+  operation(
+    "pinSubscriberLocation",
+    "POST",
+    "/v4/subscribers/{subscriber_id}/location",
+    "pinKitSubscriberLocation",
+    "Pin Kit subscriber location",
+    "Pins an explicit location to a subscriber.",
+    "safe",
+    false,
+  ),
+  operation(
+    "getSubscriberStats",
+    "GET",
+    "/v4/subscribers/{subscriber_id}/stats",
+    "getKitSubscriberStats",
+    "Get Kit subscriber stats",
+    "Returns delivery and engagement statistics for one subscriber.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listSubscriberTags",
+    "GET",
+    "/v4/subscribers/{subscriber_id}/tags",
+    "listKitSubscriberTags",
+    "List Kit subscriber tags",
+    "Lists tags currently applied to one subscriber.",
+    "safe",
+    false,
+  ),
+  operation(
+    "bulkDeleteTags",
+    "DELETE",
+    "/v4/bulk/tags",
+    "bulkDeleteKitTags",
+    "Bulk delete Kit tags",
+    "Deletes tags synchronously or as an asynchronous bulk job.",
+    "safe",
+    true,
+  ),
+  operation(
+    "bulkCreateTags",
+    "POST",
+    "/v4/bulk/tags",
+    "bulkCreateKitTags",
+    "Bulk create Kit tags",
+    "Creates tags synchronously or as an asynchronous bulk job.",
+    "safe",
+    true,
+  ),
+  operation(
+    "bulkTagSubscribers",
+    "POST",
+    "/v4/bulk/tags/subscribers",
+    "bulkTagKitSubscribers",
+    "Bulk tag Kit subscribers",
+    "Applies tags to subscribers in one bulk request.",
+    "safe",
+    true,
+  ),
+  operation(
+    "listTags",
+    "GET",
+    "/v4/tags",
+    "listKitTags",
+    "List Kit tags",
+    "Lists account tags with cursor pagination.",
+    "safe",
+    false,
+  ),
+  operation(
+    "createTag",
+    "POST",
+    "/v4/tags",
+    "createKitTag",
+    "Create Kit tag",
+    "Creates a tag or returns the existing case-insensitive name match.",
+    "safe",
+    false,
+  ),
+  operation(
+    "updateTag",
+    "PUT",
+    "/v4/tags/{id}",
+    "updateKitTag",
+    "Update Kit tag",
+    "Renames one tag without changing its memberships.",
+    "safe",
+    false,
+  ),
+  operation(
+    "listTagSubscribers",
+    "GET",
+    "/v4/tags/{tag_id}/subscribers",
+    "listKitTagSubscribers",
+    "List Kit tag subscribers",
+    "Lists subscribers that have one tag.",
+    "safe",
+    false,
+  ),
+  operation(
+    "tagSubscriberByEmailAddress",
+    "POST",
+    "/v4/tags/{tag_id}/subscribers",
+    "tagKitSubscriberByEmailAddress",
+    "Tag Kit subscriber by email",
+    "Applies a tag to an existing subscriber by email address.",
+    "safe",
+    false,
+  ),
+  operation(
+    "removeTagFromSubscriber",
+    "DELETE",
+    "/v4/tags/{tag_id}/subscribers/{id}",
+    "removeKitTagFromSubscriber",
+    "Remove Kit tag from subscriber",
+    "Removes one tag from a subscriber by ID.",
+    "safe",
+    false,
+  ),
+  operation(
+    "tagSubscriber",
+    "POST",
+    "/v4/tags/{tag_id}/subscribers/{id}",
+    "tagKitSubscriber",
+    "Tag Kit subscriber",
+    "Applies a tag to an existing subscriber by ID.",
+    "safe",
+    false,
+  ),
+] as const satisfies readonly KitOperationDefinition[]
+
+export type KitOperationKey =
+  (typeof KIT_OPERATION_DEFINITIONS)[number]["alias"]
+
+/**
+ * Preserves one Kit operation's public metadata.
+ *
+ * @param alias Public object alias and generated operation key.
+ * @param method Provider HTTP method.
+ * @param path Provider-relative V4 path.
+ * @param exportName Named SDK export.
+ * @param title Public action title.
+ * @param description Public action description.
+ * @param replaySafety Whether the provider operation can be replayed.
+ * @param oauthOnly Whether Kit rejects API-key authentication.
+ */
+function operation<
+  const TAlias extends string,
+  const TExportName extends string,
+>(
+  alias: TAlias,
+  method: KitHttpMethod,
+  path: string,
+  exportName: TExportName,
+  title: string,
+  description: string,
+  replaySafety: KitReplaySafety,
+  oauthOnly: boolean,
+) {
+  return {
+    alias,
+    description,
+    exportName,
+    method,
+    oauthOnly,
+    path,
+    replaySafety,
+    title,
+  } as const
+}