@hermeticacomms/sdk-node 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +9 -0
  2. package/README.md +12 -2
  3. package/dist/contracts/analytics.d.ts +405 -0
  4. package/dist/contracts/analytics.js +77 -0
  5. package/dist/contracts/auth.d.ts +359 -0
  6. package/dist/contracts/auth.js +121 -0
  7. package/dist/contracts/billing.d.ts +141 -0
  8. package/dist/contracts/billing.js +31 -0
  9. package/dist/contracts/campaigns.d.ts +918 -0
  10. package/dist/contracts/campaigns.js +269 -0
  11. package/dist/contracts/common.d.ts +57 -0
  12. package/dist/contracts/common.js +35 -0
  13. package/dist/contracts/connectors.d.ts +179 -0
  14. package/dist/contracts/connectors.js +46 -0
  15. package/dist/contracts/consent.d.ts +604 -0
  16. package/dist/contracts/consent.js +180 -0
  17. package/dist/contracts/content-blocks.d.ts +164 -0
  18. package/dist/contracts/content-blocks.js +60 -0
  19. package/dist/contracts/content-library.d.ts +339 -0
  20. package/dist/contracts/content-library.js +50 -0
  21. package/dist/contracts/content.d.ts +949 -0
  22. package/dist/contracts/content.js +192 -0
  23. package/dist/contracts/delivery.d.ts +599 -0
  24. package/dist/contracts/delivery.js +214 -0
  25. package/dist/contracts/events.d.ts +513 -0
  26. package/dist/contracts/events.js +178 -0
  27. package/dist/contracts/experiments.d.ts +376 -0
  28. package/dist/contracts/experiments.js +136 -0
  29. package/dist/contracts/identity.d.ts +756 -0
  30. package/dist/contracts/identity.js +225 -0
  31. package/dist/contracts/index.d.ts +15 -0
  32. package/dist/contracts/index.js +15 -0
  33. package/dist/contracts/integrations.d.ts +381 -0
  34. package/dist/contracts/integrations.js +112 -0
  35. package/dist/contracts/leads.d.ts +733 -0
  36. package/dist/contracts/leads.js +125 -0
  37. package/dist/contracts/metrics.d.ts +460 -0
  38. package/dist/contracts/metrics.js +90 -0
  39. package/dist/contracts/outbound.d.ts +15510 -0
  40. package/dist/contracts/outbound.js +423 -0
  41. package/dist/contracts/pickers.d.ts +12 -0
  42. package/dist/contracts/pickers.js +20 -0
  43. package/dist/contracts/platform-admin.d.ts +230 -0
  44. package/dist/contracts/platform-admin.js +91 -0
  45. package/dist/contracts/postcards.d.ts +79 -0
  46. package/dist/contracts/postcards.js +29 -0
  47. package/dist/contracts/push.d.ts +530 -0
  48. package/dist/contracts/push.js +102 -0
  49. package/dist/contracts/rcs.d.ts +39 -0
  50. package/dist/contracts/rcs.js +19 -0
  51. package/dist/contracts/segments.d.ts +3182 -0
  52. package/dist/contracts/segments.js +416 -0
  53. package/dist/contracts/workflow-nodes.d.ts +2118 -0
  54. package/dist/contracts/workflow-nodes.js +341 -0
  55. package/dist/contracts/workflows.d.ts +46413 -0
  56. package/dist/contracts/workflows.js +341 -0
  57. package/dist/contracts/x10-platform.d.ts +2603 -0
  58. package/dist/contracts/x10-platform.js +129 -0
  59. package/dist/http.d.ts +30 -0
  60. package/dist/http.js +65 -0
  61. package/dist/index.d.ts +11507 -0
  62. package/dist/index.js +63 -0
  63. package/dist/platform.d.ts +163 -0
  64. package/dist/platform.js +40 -0
  65. package/dist/resources.d.ts +1318 -0
  66. package/dist/resources.js +56 -0
  67. package/dist/signature.d.ts +5 -0
  68. package/dist/signature.js +19 -0
  69. package/dist/x10.d.ts +1607 -0
  70. package/dist/x10.js +66 -0
  71. package/dist/z10.d.ts +251 -0
  72. package/dist/z10.js +46 -0
  73. package/package.json +40 -4
@@ -0,0 +1,341 @@
1
+ import { z } from 'zod';
2
+ import { Channel, DateTimeIn, Id, Purpose, ReplyToList } from './common.js';
3
+ import { PropertyCondition } from './metrics.js';
4
+ import { PushExtras, PushPlatform } from './push.js';
5
+ import { PostcardDesign } from './postcards.js';
6
+ import { SegmentDefinition } from './segments.js';
7
+ import { pick } from './pickers.js';
8
+ import { TaskKind } from './outbound.js';
9
+ export const NodeId = z.string().min(1).max(64);
10
+ /** Config values that name another entity carry a picker hint (pickers.ts) so the builder offers live choices. */
11
+ export const refId = (kind) => pick(Id, kind);
12
+ export const EventRef = pick(z.string().min(1).max(128), 'event');
13
+ export const TagRef = pick(z.string().min(1).max(64), 'tag');
14
+ export const FieldRef = pick(z.string().min(1).max(128), 'field');
15
+ export const ZoneRef = pick(z.string().max(64), 'timezone');
16
+ const StepRef = pick(NodeId, 'node');
17
+ /** A dot path into the trigger event, e.g. `properties.items`. */
18
+ const EventPath = pick(z.string().min(1).max(128), 'event_path');
19
+ const Pos = z.object({ x: z.number(), y: z.number() }).optional();
20
+ const Route = z.object({ connectionId: refId('connection').optional(), poolId: refId('sender_pool').optional(), routePolicyId: refId('route_policy').optional() });
21
+ export const Duration = z.object({ amount: z.number().int().min(0).max(3650 * 24 * 60), unit: z.enum(['minutes', 'hours', 'days', 'weeks']) });
22
+ const Cmp = { op: z.enum(['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'contains', 'exists', 'not_exists']), value: z.unknown().optional() };
23
+ export const Condition = z.discriminatedUnion('kind', [
24
+ z.object({ kind: z.literal('field'), field: FieldRef, ...Cmp }),
25
+ z.object({ kind: z.literal('tag'), name: TagRef }),
26
+ z.object({ kind: z.literal('in_list'), listId: refId('list') }),
27
+ z.object({ kind: z.literal('in_segment'), segmentId: refId('segment') }),
28
+ z.object({ kind: z.literal('consent'), channel: Channel, purpose: Purpose.default('marketing') }),
29
+ z.object({ kind: z.literal('trigger'), path: EventPath, ...Cmp }),
30
+ z.object({ kind: z.literal('var'), key: z.string().min(1).max(64), ...Cmp }),
31
+ z.object({ kind: z.literal('definition'), definition: SegmentDefinition }),
32
+ /** The triggering profile update touched `field` (and, with `from` / `to`, the recorded old / new value of that field equal them). Only meaningful for profile_updated entries. */
33
+ z.object({ kind: z.literal('field_changed'), field: FieldRef, from: z.unknown().optional(), to: z.unknown().optional() }),
34
+ /** Is (or was) the profile inside another journey? `ever` = any enrollment, `completed` = finished it. */
35
+ z.object({ kind: z.literal('in_workflow'), workflowId: refId('workflow'), state: z.enum(['active', 'completed', 'ever']).default('active') }),
36
+ /** Weekday (1 = Monday .. 7 = Sunday) and/or time-of-day window in `tz` (default: the flow zone). Window may wrap midnight. */
37
+ z.object({ kind: z.literal('time'), weekdays: z.array(z.number().int().min(1).max(7)).optional(), startMin: z.number().int().min(0).max(1440).optional(), endMin: z.number().int().min(0).max(1440).optional(), tz: ZoneRef.optional() }),
38
+ /** Compare a date (profile field, trigger path or var) with now: before/after/today, within N days either way, or an anniversary (month and day) within N days. */
39
+ /** The contact has at least one push device that can receive (a valid token with notifications allowed), optionally on one platform. */
40
+ z.object({ kind: z.literal('push_token'), platform: PushPlatform.optional() }),
41
+ z.object({
42
+ kind: z.literal('date'), source: z.enum(['field', 'trigger', 'var']).default('field'), path: z.string().min(1).max(128),
43
+ op: z.enum(['before', 'after', 'today', 'within_next_days', 'within_past_days', 'anniversary_within_days']), days: z.number().int().min(0).max(3660).default(0),
44
+ }),
45
+ ]);
46
+ const Send = {
47
+ templateId: refId('template'),
48
+ versionId: Id.optional(),
49
+ route: Route,
50
+ topicId: refId('topic').optional(),
51
+ /** Sequences: continue the thread of this earlier email step. */
52
+ replyToStep: StepRef.optional(),
53
+ /** What to do when delivery blocks the send (no consent, suppressed, ...). `continue` follows `on_blocked` if wired, else `next`. */
54
+ onBlocked: z.enum(['continue', 'exit']).default('continue'),
55
+ /** When the send itself errors (render failure, provider rejection raised synchronously) carry on to `next` instead of failing the enrollment. */
56
+ skipOnFailure: z.boolean().optional(),
57
+ /** Per-message smart sending: skip this message (continue to `next`) when the person already got any message from this flow's sender inside this many hours. */
58
+ skipIfMessagedWithinHours: z.number().int().min(1).max(24 * 30).optional(),
59
+ /** Additional message filter: people who do not match skip just this message and carry on. Same conditions as the segment builder. */
60
+ filter: SegmentDefinition.optional(),
61
+ /** Retry a send that errors (render failure, provider refusal) up to this many times, 5 min apart and doubling, before `skipOnFailure` or failing. */
62
+ retries: z.number().int().min(0).max(5).optional(),
63
+ /** Send from this verified sender of the route instead of its default. */
64
+ senderIdentityId: refId('sender').optional(),
65
+ replyTo: ReplyToList.optional(),
66
+ /** Transactional / operational only: add RFC 8058 one-click unsubscribe headers. Marketing and prospecting always carry them. */
67
+ oneClickUnsubscribe: z.boolean().optional(),
68
+ };
69
+ const Empty = z.object({}).default({});
70
+ /** What reaching a goal means: an event (with property filter) or a segment definition. */
71
+ export const GoalMatch = z.object({ kind: z.enum(['event', 'segment']), eventName: pick(z.string().max(128), 'event').optional(), filter: z.record(z.string(), z.unknown()).optional(), definition: SegmentDefinition.optional() });
72
+ /** Targeted notification: in-app always, plus email to members/addresses, Slack incoming webhook, or any webhook. Title, subject and body are liquid. */
73
+ const Notify = z.object({
74
+ title: z.string().max(200).optional(),
75
+ subject: z.string().max(200).optional(),
76
+ body: z.string().max(5000).optional(),
77
+ to: z.object({
78
+ userIds: z.array(refId('user')).max(20).default([]), emails: z.array(z.email()).max(20).default([]),
79
+ slackWebhookUrl: z.url().optional(), webhookUrl: z.url().optional(),
80
+ /** Discord channel webhook (https://discord.com/api/webhooks/...). */
81
+ discordWebhookUrl: z.url().regex(/^https:\/\/(discord\.com|discordapp\.com|ptb\.discord\.com|canary\.discord\.com)\/api\/webhooks\//).optional(),
82
+ }).default({ userIds: [], emails: [] }),
83
+ params: z.record(z.string(), z.unknown()).default({}),
84
+ }).default({ to: { userIds: [], emails: [] }, params: {} });
85
+ const OnExceed = z.enum(['hold', 'branch', 'exit']).default('hold');
86
+ const Weight = z.number().int().min(0).max(1000);
87
+ /** `onClosed: exit` ends the journey when the window is closed instead of waiting for it to open. */
88
+ const Hours = z.object({ startMin: z.number().int().min(0).max(1440), endMin: z.number().int().min(0).max(1440), weekdays: z.array(z.number().int().min(1).max(7)).optional(), tz: ZoneRef.optional(), onClosed: z.enum(['wait', 'exit']).optional() });
89
+ const Action = z.object({ title: z.string().max(200).optional(), params: z.record(z.string(), z.unknown()).default({}) }).default({ params: {} });
90
+ /** Task steps: the kind, who does it (empty = the contact's owner) and notes; `params` keeps the older free-form inputs (LinkedIn steps, voicemail clips). */
91
+ const TaskAction = z.object({
92
+ title: z.string().max(200).optional(), kind: TaskKind.optional(), assigneeUserId: refId('user').optional(), notes: z.string().max(5000).optional(),
93
+ params: z.record(z.string(), z.unknown()).default({}),
94
+ }).default({ params: {} });
95
+ const OwnerAction = z.object({ title: z.string().max(200).optional(), userId: refId('user').optional(), params: z.record(z.string(), z.unknown()).default({}) }).default({ params: {} });
96
+ /** `name`: the step's display name on the canvas (the type's label when empty). */
97
+ const node = (type, config) => z.object({ id: NodeId, type: z.literal(type), config, position: Pos, name: z.string().trim().max(80).optional() });
98
+ export const WorkflowNode = z.discriminatedUnion('type', [
99
+ // messaging
100
+ node('send_email', z.object(Send)),
101
+ /** `purpose` lets a prospecting sequence send SMS under the consent-based `marketing` purpose; otherwise SMS stays blocked for prospecting. */
102
+ node('send_sms', z.object({ ...Send, purpose: Purpose.optional() })),
103
+ /** Approved WhatsApp template (a content template of channel whatsapp). Needs explicit WhatsApp consent; free text is never sent from a flow. */
104
+ node('send_whatsapp', z.object({ ...Send, purpose: Purpose.optional() })),
105
+ /** Mobile or web push (a content template of channel push: title = subject, body = text). Needs push consent; fans out to every valid device token. */
106
+ node('send_push', z.object({ ...Send, purpose: Purpose.optional(), push: PushExtras.optional() })),
107
+ node('send_transactional_email', z.object(Send)),
108
+ /**
109
+ * Printed postcard through a print connection (Lob, PostGrid). Front and back are liquid HTML; people without a complete postal address,
110
+ * with a revoked consent or a suppression are skipped (`on_blocked`). One card per visit: the step's action key is the idempotency key.
111
+ */
112
+ node('send_postcard', z.object({
113
+ design: PostcardDesign, route: Route, purpose: Purpose.optional(),
114
+ onBlocked: z.enum(['continue', 'exit']).default('continue'), skipOnFailure: z.boolean().optional(),
115
+ })),
116
+ node('notify_internal', Notify),
117
+ node('create_task', TaskAction),
118
+ node('send_webhook', z.object({
119
+ /** Saved call (Settings > Webhooks > Call templates): its url, method, headers, body and secrets are the defaults; fields set here win. */
120
+ webhookTemplateId: refId('webhook_template').optional(),
121
+ url: z.url().optional(),
122
+ method: z.enum(['POST', 'PUT', 'PATCH', 'DELETE', 'GET', 'HEAD', 'OPTIONS']).optional(),
123
+ /** How the body is sent: JSON (default), form-encoded fields of `body`, or `rawBody` as plain text or XML (liquid, so `{{ profile.email }}` works). */
124
+ bodyFormat: z.enum(['json', 'form', 'text', 'xml']).default('json'),
125
+ rawBody: z.string().max(100_000).optional(),
126
+ /** Extra headers whose values come from named integration secrets (Settings > Integrations), opened at send time. */
127
+ authHeaders: z.array(z.object({ header: z.string().regex(/^[A-Za-z0-9-]{1,64}$/), secretName: pick(z.string().min(1).max(100), 'secret'), prefix: z.string().max(40).optional() })).max(10).optional(),
128
+ body: z.record(z.string(), z.unknown()).optional(), headers: z.record(z.string(), z.string()).optional(),
129
+ /** Total attempts including the first; transient failures (network, 5xx, 429) are retried with backoff. */
130
+ maxAttempts: z.number().int().min(1).max(8).default(5),
131
+ /** When set, the body is signed: `x-hermetica-signature: t=<unix>,v1=<hmac-sha256 of "t.body">`. */
132
+ /** Write-only: the API seals it into `signingSecretSealed` and never returns either (reads show `signingSecretSet`). */
133
+ signingSecret: z.string().min(8).max(200).optional(),
134
+ signingSecretSealed: z.string().max(2000).optional(),
135
+ signingSecretSet: z.boolean().optional(),
136
+ /** Copy values out of a JSON response onto the profile: `path` is a dot path into the response. */
137
+ responseMap: z.array(z.object({ path: z.string().min(1).max(200), field: FieldRef })).max(20).default([]),
138
+ /** Values for the inputs a custom-action call template declares; liquid, so `{{ profile.email }}` maps a profile field in. */
139
+ inputFields: z.record(z.string(), z.string().max(2000)).default({}),
140
+ /** Hold the contact until the call finishes so later steps see the mapped attributes; `failed` (optional edge) is followed on give-up or timeout. */
141
+ awaitResponse: z.boolean().default(false),
142
+ /** Hold the contact until the outside system calls back (POST /v1/workflow-actions/callbacks/{callbackId}/complete) with its output values; the body carries `callbackId`. */
143
+ awaitCallback: z.boolean().default(false),
144
+ responseTimeout: Duration.default({ amount: 10, unit: 'minutes' }),
145
+ }).refine((c) => c.url || c.webhookTemplateId, { message: 'Give a url or choose a call template', path: ['url'] })),
146
+ node('add_note', z.object({ body: z.string().min(1).max(5000) })),
147
+ /** Queue an in-app message for the contact: shown on their next app/site visit (the app asks for messages) unless it expires first. */
148
+ node('show_in_app', z.object({ messageId: refId('in_app'), expiresInHours: z.number().int().min(1).max(24 * 30).default(24) })),
149
+ // logic
150
+ node('if_else', z.object({ condition: Condition })),
151
+ /** `first`: first matching path wins. `weighted`: among all matching paths pick one by weight (persisted per profile); none match -> else. */
152
+ node('multi_branch', z.object({
153
+ branches: z.array(z.object({ key: z.string().min(1).max(32), condition: Condition, weight: Weight.default(1) })).min(1).max(25),
154
+ pick: z.enum(['first', 'weighted']).default('first'),
155
+ })),
156
+ node('random_split', z.object({ splits: z.array(z.object({ key: z.string().min(1).max(32), weight: Weight })).min(2).max(26) })),
157
+ node('ab_test', z.object({
158
+ experimentId: refId('experiment').optional(),
159
+ variants: z.array(z.object({ key: z.string().min(1).max(32), weight: Weight })).min(2).max(26),
160
+ /** Pick the winner by `metric` once `afterHours` have passed, each variant has `minRecipients` sends and the best one is ahead with confidence `pBest`; later entrants then all take the winner. Applies when the test first runs. */
161
+ autoWinner: z.object({
162
+ metric: z.enum(['clicks', 'opens', 'conversions', 'revenue', 'replies']).default('clicks'),
163
+ afterHours: z.number().int().min(1).max(24 * 30).default(48),
164
+ minRecipients: z.number().int().min(1).max(1_000_000).default(100),
165
+ minConversions: z.number().int().min(1).max(1_000_000).default(20),
166
+ pBest: z.number().min(0.5).max(0.999).default(0.95),
167
+ /** End the test at this moment; the variant ahead wins even without a clear result. */
168
+ stopAt: z.iso.datetime({ offset: true }).optional(),
169
+ /** Gradually send more new people to the better-looking variants while the test runs. */
170
+ shift: z.boolean().optional(),
171
+ /** Harm checks against the first variant (the control): a variant likely worse on one is never picked. */
172
+ guardrails: z.array(z.object({ metric: z.enum(['unsubscribe', 'complaint', 'bounce']), threshold: z.number().min(0).max(1).default(0) })).max(3).optional(),
173
+ /** End the test early on the control when a variant trips a guardrail. */
174
+ stopOnGuardrail: z.boolean().optional(),
175
+ }).optional(),
176
+ })),
177
+ /** Loop over a list in the trigger event (e.g. `properties.items` of an order): each pass exits `item` with `vars.item` set; wire the body back to this step. `done` runs after the last one. */
178
+ node('for_each_item', z.object({ path: EventPath, max: z.number().int().min(1).max(25).default(10) })),
179
+ /** Look up one row in an uploaded collection (a table of rows) by a column value; `found` / `not_found` branch. The row is kept as `vars.lookup_<saveAs>` for later conditions and messages. */
180
+ node('query_collection', z.object({
181
+ collectionId: refId('collection'),
182
+ column: pick(z.string().min(1).max(128), 'collection_column'),
183
+ /** Liquid, compared as text without regard to case, for example `{{ profile.country }}`. */
184
+ value: z.string().min(1).max(500).default('{{ profile.emailPrimary }}'),
185
+ saveAs: z.string().regex(/^[a-z][a-z0-9_]{0,31}$/, 'lowercase letters, digits, underscore').default('row'),
186
+ })),
187
+ node('switch', z.object({ field: FieldRef, cases: z.array(pick(z.string().max(128), 'field_value')).min(1).max(25) })),
188
+ node('merge', Empty),
189
+ /** With `condition`: jump only when it holds, otherwise continue on `next` (optional edge). */
190
+ node('goto', z.object({ target: StepRef, condition: Condition.optional() })),
191
+ /** Remove the profile from another journey (the mirror of enroll_workflow). */
192
+ node('exit_workflow', z.object({ workflowId: refId('workflow'), reason: z.string().max(64).default('exited_by_journey') })),
193
+ node('exit', z.object({ reason: z.string().max(64).default('exit_node') }).default({ reason: 'exit_node' })),
194
+ node('enroll_workflow', z.object({ workflowId: refId('workflow') })),
195
+ // timing
196
+ /** After the wait, optionally move on to a time of day (`atTime`, 24-hour) and/or the next allowed weekday (1 = Monday .. 7 = Sunday), in the recipient's zone. */
197
+ node('delay', z.object({
198
+ duration: Duration, mode: z.enum(['calendar', 'exact']).default('calendar'),
199
+ atTime: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, 'Use 24-hour HH:MM').optional(),
200
+ weekdays: z.array(z.number().int().min(1).max(7)).max(7).optional(),
201
+ /** Time zone for the time of day and the days; empty = the recipient's own (falling back to the journey's zone). */
202
+ tz: ZoneRef.optional(),
203
+ })),
204
+ /** `yearly`: wait for the next occurrence of the date's month and day (birthdays, renewals). */
205
+ node('wait_until_date', z.object({ attribute: pick(z.string().max(128), 'field').optional(), at: DateTimeIn().optional(), offsetDays: z.number().int().default(0), yearly: z.boolean().default(false) })),
206
+ /** Collect contacts into shared release windows (aligned to the clock) and let each window go together. */
207
+ node('batch', z.object({ window: Duration })),
208
+ /** Hold until the hour this person most often engages (campaign send-time optimisation), within the next 24 h. */
209
+ node('wait_best_send_time', Empty),
210
+ /** `filter` is equality only; `conditions` add operators (neq, gt, contains, exists, between, ...) over the event properties. */
211
+ node('wait_for_event', z.object({ eventName: EventRef, filter: z.record(z.string(), z.unknown()).optional(), conditions: z.array(PropertyCondition).max(10).optional(), timeout: Duration })),
212
+ /** Resume on whichever listed event arrives first (path `event:<key>`), or `timeout`. */
213
+ node('wait_for_any_event', z.object({
214
+ events: z.array(z.object({ key: z.string().min(1).max(32), eventName: EventRef, filter: z.record(z.string(), z.unknown()).optional(), conditions: z.array(PropertyCondition).max(10).optional() })).min(2).max(10),
215
+ timeout: Duration,
216
+ })),
217
+ node('wait_until_condition', z.object({ definition: SegmentDefinition, timeout: Duration })),
218
+ /** Race of 2-10 segment definitions: the first the profile enters wins and its `key` edge is followed; else `timeout`. */
219
+ node('wait_for_segments', z.object({
220
+ branches: z.array(z.object({ key: z.string().min(1).max(32), definition: SegmentDefinition })).min(2).max(10), timeout: Duration,
221
+ })),
222
+ /** Wait until the profile's `field` changes (optionally from / to a value, compared with the recorded old / new values); else `timeout`. Only changes made after the wait begins count. */
223
+ node('wait_for_attribute_change', z.object({ field: FieldRef, from: z.unknown().optional(), to: z.unknown().optional(), timeout: Duration })),
224
+ /** Hold until the next listed weekday (1 = Monday .. 7 = Sunday) at `time` in `tz` (default: the recipient's / flow zone). */
225
+ node('wait_until_weekday', z.object({ weekdays: z.array(z.number().int().min(1).max(7)).min(1).max(7), time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, 'Use 24-hour HH:MM'), tz: ZoneRef.optional() })),
226
+ /** Wait until this person is predicted to need the product again: the product's typical gap between orders (a per-product number set here wins, else measured from this product's order history, else from all products' repeat orders, else `fallbackDays`), minus `bufferDays`. */
227
+ node('wait_until_reorder', z.object({
228
+ overrides: z.array(z.object({ productId: pick(z.string().min(1).max(128), 'product'), days: z.number().int().min(1).max(3650) })).max(100).default([]),
229
+ fallbackDays: z.number().int().min(1).max(3650).default(30),
230
+ minOrders: z.number().int().min(2).max(50).default(3),
231
+ bufferDays: z.number().int().min(0).max(365).default(0),
232
+ })),
233
+ node('random_delay', z.object({ min: Duration, max: Duration })),
234
+ /** Wait until the profile opens/clicks/replies to a message from this journey (optionally one specific send step). */
235
+ node('wait_for_engagement', z.object({ kind: z.enum(['open', 'click', 'reply', 'delivered', 'bounced', 'complained']), stepKey: StepRef.optional(), timeout: Duration })),
236
+ node('business_hours', Hours),
237
+ node('send_window', Hours),
238
+ /** Only let people through between two dates: before `from` hold (or exit), after `to` exit. */
239
+ node('date_window', z.object({ from: z.iso.datetime({ offset: true }).optional(), to: z.iso.datetime({ offset: true }).optional(), beforeStart: z.enum(['wait', 'exit']).default('wait') })
240
+ .refine((c) => c.from || c.to, { message: 'Give a start date, an end date, or both', path: ['from'] })
241
+ .refine((c) => !c.from || !c.to || c.from < c.to, { message: 'The end must be after the start', path: ['to'] })),
242
+ // state
243
+ node('add_tag', z.object({ name: TagRef })),
244
+ node('remove_tag', z.object({ name: TagRef })),
245
+ /** `set` is the simple form; `ops` adds increment / append / unset. String values are liquid (`{{ event.properties.plan }}`). */
246
+ node('update_profile', z.object({
247
+ set: z.record(z.string(), z.unknown()).default({}),
248
+ ops: z.array(z.object({ op: z.enum(['set', 'increment', 'append', 'unset']), field: FieldRef, value: z.unknown().optional() })).max(30).default([]),
249
+ })),
250
+ node('add_to_list', z.object({ listId: refId('list') })),
251
+ node('remove_from_list', z.object({ listId: refId('list') })),
252
+ /** Copy a value from the trigger event (dot path into the event, e.g. `properties.plan`) onto a profile field. */
253
+ node('update_by_event', z.object({ field: FieldRef, path: EventPath })),
254
+ node('set_field', z.object({ field: FieldRef, value: z.unknown() })),
255
+ node('score', z.object({ delta: z.number().int().min(-1000).max(1000), field: pick(z.string(), 'field').default('score') })),
256
+ /** Move the contact's score in a published score model by `delta` (history reason `journey`). */
257
+ node('adjust_score', z.object({ modelId: refId('score'), delta: z.number().int().min(-1000).max(1000) })),
258
+ /** Company of the contact (leads module); skipped when the contact has none. */
259
+ node('update_company', z.object({ set: z.object({ name: z.string().max(200).optional(), industry: z.string().max(100).optional(), sizeBand: z.string().max(50).optional(), country: z.string().length(2).optional() }) })),
260
+ /** Put the contact at an existing company (replaces its current link). */
261
+ node('add_to_company', z.object({ companyId: refId('company') })),
262
+ /** Push the contact to a connected CRM now (same upsert the sync uses); skipped when unchanged. */
263
+ node('push_integration', z.object({ integrationId: refId('integration') })),
264
+ /** Syntax, disposable-domain and MX check on the primary address (no paid lookup). `rejectRole` also sends info@/sales@ style addresses down `invalid`. */
265
+ node('validate_email', z.object({ rejectRole: z.boolean().default(false) })),
266
+ /** Erases the contact for good (the DSAR erase: address stays suppressed). Runs after this step commits; `confirm` must be ticked so a journey never deletes people by accident. */
267
+ node('delete_contact', z.object({ confirm: z.boolean().default(false).refine((v) => v, 'Tick to confirm this journey may permanently delete contacts') })),
268
+ node('company_branch', z.object({ field: z.enum(['name', 'domain', 'industry', 'sizeBand', 'country', 'stage', 'suppressed']), ...Cmp })),
269
+ node('set_lifecycle', z.object({ stage: pick(z.string().min(1).max(64), 'lifecycle_stage') })),
270
+ node('update_consent', z.object({ channel: Channel, purpose: Purpose.default('marketing'), status: z.enum(['granted', 'revoked']), proofSource: z.enum(['trigger_event', 'form']).optional() })),
271
+ // control
272
+ /** `skipAhead`: a contact who meets `match` (or the flow goal) anywhere earlier in the journey jumps straight here. */
273
+ node('goal', z.object({ name: z.string().max(64).default('goal'), skipAhead: z.boolean().default(false), match: GoalMatch.optional() })),
274
+ /** Counts this profile's sends (delivery data) in the window. Over the cap: `hold` waits until room opens, `branch` follows the `limited` edge, `exit` ends the enrollment. */
275
+ node('frequency_cap', z.object({ maxSends: z.number().int().min(1), windowHours: z.number().int().min(1), channel: Channel.optional(), onExceed: OnExceed })),
276
+ node('suppression_check', z.object({ channel: Channel, purpose: Purpose.default('marketing') })),
277
+ /**
278
+ * At most `perHour` enrollments through this node per clock-aligned window (`windowMinutes`, default an hour). Nodes with the same `slot`
279
+ * share one counter; `perMailbox` splits that counter by the enrollment's pinned mailbox.
280
+ */
281
+ node('rate_limit', z.object({
282
+ perHour: z.number().int().min(1), windowMinutes: z.number().int().min(1).max(10080).default(60), onExceed: OnExceed,
283
+ slot: z.string().min(1).max(64).optional(), perMailbox: z.boolean().optional(),
284
+ })),
285
+ node('add_suppression', z.object({ channel: Channel, reason: z.string().max(64).default('workflow') })),
286
+ /** Lifts only manual suppressions; bounces, complaints and STOPs stay. */
287
+ node('remove_suppression', z.object({ channel: Channel })),
288
+ node('approval_gate', Empty),
289
+ node('pause', Empty),
290
+ node('end', Empty),
291
+ // outbound (P7 consumes the requested actions)
292
+ node('stop_on_reply', Empty),
293
+ node('stop_on_bounce', Empty),
294
+ node('stop_on_unsubscribe', Empty),
295
+ node('classify_reply', Action),
296
+ node('assign_owner', OwnerAction),
297
+ node('rotate_mailbox', Action),
298
+ node('follow_up_task', TaskAction),
299
+ /** Add (or take) points on the account score of the contact's primary company (leads module). */
300
+ node('score_company', z.object({ delta: z.number().int().min(-1000).max(1000) })),
301
+ /** Score the contact's company when the journey was started by a form submission (optionally only that form); otherwise skipped. */
302
+ node('score_company_from_form', z.object({ delta: z.number().int().min(-1000).max(1000), formId: refId('form').optional() })),
303
+ /** WS09: show a content-only site message to this contact on their next visit (held until `expiresInHours`). */
304
+ node('send_site_message', z.object({ siteMessageId: refId('site_message'), expiresInHours: z.number().int().min(1).max(720).default(168) })),
305
+ /** WS09: put content into this contact's web content slot `slotKey`; it wins over the slot's rules until it expires. */
306
+ node('push_slot_content', z.object({ slotKey: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/), html: z.string().min(1).max(20_000), expiresInHours: z.number().int().min(1).max(720).default(168) })),
307
+ // WS04: object journeys, code and user-defined actions, native app actions. Text values are liquid (`{{ profile.email }}`).
308
+ /** Create, or update when it exists, the custom object of `typeKey` with this external id; `link` also relates it to the contact. */
309
+ node('upsert_object', z.object({
310
+ typeKey: pick(z.string().min(1).max(64), 'object_type'), externalId: z.string().min(1).max(500), name: z.string().max(500).optional(),
311
+ attributes: z.record(z.string(), z.string().max(2000)).default({}), link: z.boolean().default(true), role: z.string().max(64).optional(),
312
+ })),
313
+ /** Add or remove the contact's relationship to an existing custom object (by external id). `failed` (optional edge) when the object does not exist. */
314
+ node('relate_object', z.object({ typeKey: pick(z.string().min(1).max(64), 'object_type'), externalId: z.string().min(1).max(500), op: z.enum(['link', 'unlink']).default('link'), role: z.string().max(64).optional() })),
315
+ /** Run a code action (Settings > Webhooks > Call templates, kind code) and wait for it; its outputs land on the profile for later steps. `failed` on FAIL_CONTINUE, give-up or timeout. */
316
+ node('run_code', z.object({
317
+ webhookTemplateId: refId('webhook_template'), inputFields: z.record(z.string(), z.string().max(2000)).default({}), maxAttempts: z.number().int().min(1).max(8).default(3),
318
+ responseTimeout: Duration.default({ amount: 10, unit: 'minutes' }),
319
+ })),
320
+ /** A workspace-defined action type (Automation > Custom types): fills its fields and runs the action behind it, waiting for the outcome. */
321
+ node('custom_action', z.object({ typeKey: pick(z.string().regex(/^[a-z][a-z0-9_]{0,47}$/), 'custom_action'), values: z.record(z.string(), z.string().max(2000)).default({}), responseTimeout: Duration.default({ amount: 10, unit: 'minutes' }) })),
322
+ /** Google Sheets: append one row. `secretName` holds a Google access token with the spreadsheets scope. */
323
+ node('sheets_append_row', z.object({ spreadsheetId: z.string().regex(/^[A-Za-z0-9_-]{20,100}$/), sheet: z.string().min(1).max(100).default('Sheet1'), values: z.array(z.string().max(2000)).min(1).max(50), secretName: pick(z.string().min(1).max(100), 'secret') })),
324
+ /** Calendly: create a single-use scheduling link for an event type and save its URL on the profile (`field`) for the next message. `secretName` holds a Calendly personal access token. */
325
+ node('calendly_link', z.object({ eventTypeUri: z.url().max(500), secretName: pick(z.string().min(1).max(100), 'secret'), field: pick(z.string().min(1).max(128), 'field').default('calendly_link'), maxEventCount: z.number().int().min(1).max(10).default(1) })),
326
+ // WS14 channels
327
+ /** Slack message from an installed workspace app: to a channel, or as a DM to the contact (looked up by their email). Text is liquid. */
328
+ node('send_slack', z.object({ installId: refId('slack_install'), slackTemplateId: refId('slack_template').optional(), text: z.string().max(3000).optional(), to: z.enum(['channel', 'contact']).default('channel'), channel: z.string().max(80).optional() })),
329
+ /** Send a WhatsApp Flow and wait for the answer: branches match one answer field; `timeout` when no answer, `blocked` when it could not be sent. */
330
+ node('send_whatsapp_flow', z.object({
331
+ flowId: refId('wa_flow'), purpose: Purpose.default('marketing'), timeout: Duration.default({ amount: 1, unit: 'days' }),
332
+ branches: z.array(z.object({ key: z.string().regex(/^[a-z][a-z0-9_]{0,31}$/), field: z.string().min(1).max(64), value: z.string().max(200) })).max(10).default([]),
333
+ })),
334
+ /** Show a developer-defined component in the app and wait until it reports one of `events` (handle event:<name>) or `timeout`. */
335
+ node('in_app_tracker', z.object({
336
+ componentKey: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/), fields: z.record(z.string(), z.string().max(2000)).default({}),
337
+ events: z.array(z.string().regex(/^[a-z][a-z0-9_]{0,63}$/)).min(1).max(10), timeout: Duration.default({ amount: 7, unit: 'days' }),
338
+ })),
339
+ /** Add the contact to, or remove them from, an ad platform custom audience. Contacts who opted out of ads are never added. */
340
+ node('ad_audience', z.object({ adAccountId: refId('ad_account'), audienceId: z.string().min(1).max(200), op: z.enum(['add', 'remove']).default('add') })),
341
+ ]);