@hermeticacomms/sdk-node 0.0.0-stage → 0.4.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 +363 -0
  6. package/dist/contracts/auth.js +130 -0
  7. package/dist/contracts/billing.d.ts +143 -0
  8. package/dist/contracts/billing.js +32 -0
  9. package/dist/contracts/campaigns.d.ts +915 -0
  10. package/dist/contracts/campaigns.js +276 -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 +628 -0
  16. package/dist/contracts/consent.js +194 -0
  17. package/dist/contracts/content-blocks.d.ts +165 -0
  18. package/dist/contracts/content-blocks.js +62 -0
  19. package/dist/contracts/content-library.d.ts +347 -0
  20. package/dist/contracts/content-library.js +52 -0
  21. package/dist/contracts/content.d.ts +955 -0
  22. package/dist/contracts/content.js +194 -0
  23. package/dist/contracts/delivery.d.ts +602 -0
  24. package/dist/contracts/delivery.js +220 -0
  25. package/dist/contracts/events.d.ts +514 -0
  26. package/dist/contracts/events.js +180 -0
  27. package/dist/contracts/experiments.d.ts +378 -0
  28. package/dist/contracts/experiments.js +140 -0
  29. package/dist/contracts/identity.d.ts +761 -0
  30. package/dist/contracts/identity.js +226 -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 +445 -0
  34. package/dist/contracts/integrations.js +139 -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 +465 -0
  38. package/dist/contracts/metrics.js +96 -0
  39. package/dist/contracts/outbound.d.ts +15535 -0
  40. package/dist/contracts/outbound.js +432 -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 +244 -0
  44. package/dist/contracts/platform-admin.js +98 -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 +3187 -0
  52. package/dist/contracts/segments.js +421 -0
  53. package/dist/contracts/workflow-nodes.d.ts +2130 -0
  54. package/dist/contracts/workflow-nodes.js +346 -0
  55. package/dist/contracts/workflows.d.ts +46811 -0
  56. package/dist/contracts/workflows.js +350 -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 +11631 -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 +1338 -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 +1608 -0
  70. package/dist/x10.js +66 -0
  71. package/dist/z10.d.ts +256 -0
  72. package/dist/z10.js +46 -0
  73. package/package.json +40 -4
@@ -0,0 +1,276 @@
1
+ import { z } from 'zod';
2
+ import { AppSlug, Channel, DateTimeIn, Id, PageQuery, Purpose, ReplyToList, Timestamp, pageResult } from './common.js';
3
+ import { AbTestConfig } from './experiments.js';
4
+ import { PushTestTarget } from './push.js';
5
+ import { MetricCounts, AvailabilityMap } from './analytics.js';
6
+ /** `failed`: fan-out errored out after its retries; nothing more is sent (messages already queued still go). */
7
+ export const CampaignStatus = z.enum(['draft', 'scheduled', 'sending', 'paused', 'completed', 'cancelled', 'failed']);
8
+ export const CampaignAction = z.enum(['schedule', 'unschedule', 'start', 'pause', 'resume', 'complete', 'cancel', 'fail']);
9
+ /** Who smart audience leaves out: any past complaint in `windowDays`, or this many ignored marketing sends (fewer for predicted-lapsed customers). */
10
+ export const SmartAudienceRules = z.object({
11
+ windowDays: z.number().int().min(14).max(365).optional(), // default 90
12
+ unengagedSends: z.number().int().min(2).max(50).optional(), // default 5
13
+ churnRisk: z.number().min(0.5).max(1).optional(), // default 0.8
14
+ churnedSends: z.number().int().min(1).max(50).optional(), // default 3
15
+ });
16
+ export const CampaignAudience = z.object({
17
+ includeSegmentIds: z.array(Id).max(50).default([]),
18
+ includeListIds: z.array(Id).max(50).default([]),
19
+ excludeSegmentIds: z.array(Id).max(50).default([]),
20
+ excludeListIds: z.array(Id).max(50).default([]),
21
+ /** Send to one contact per company (the lowest profile id); people without a company are all kept. */
22
+ onePerCompany: z.boolean().optional(),
23
+ /** Everyone in the workspace (not deleted or archived); exclusions still apply. */
24
+ everyone: z.boolean().optional(),
25
+ /** People carrying any of these profile tags (by name, as everywhere in the tag API). */
26
+ includeTags: z.array(z.string().trim().min(1).max(64)).max(50).optional(),
27
+ excludeTags: z.array(z.string().trim().min(1).max(64)).max(50).optional(),
28
+ /** Smart audience thresholds (used when the campaign's smartAudience is on); unset keys keep the defaults. */
29
+ smart: SmartAudienceRules.optional(),
30
+ });
31
+ const Minutes = z.number().int().min(0).max(1440);
32
+ export const CampaignSchedule = z.object({
33
+ /** Fixed instant, or (recipientLocal) the wall-clock time read in `tz` and re-applied in each recipient's zone. */
34
+ at: DateTimeIn(),
35
+ tz: z.string().min(1).max(64).default('UTC'),
36
+ recipientLocal: z.boolean().default(false),
37
+ throttlePerHour: z.number().int().min(1).max(1_000_000).optional(),
38
+ /** Allowed send window, minutes-of-day in the recipient zone (or `tz` when not recipientLocal). */
39
+ window: z.object({ startMin: Minutes, endMin: Minutes }).optional(),
40
+ /** `optimized`: each recipient's own best hour (T6.4) within 24 h of `at`; falls back to the workspace best hour. Ignores throttle. */
41
+ sendTime: z.enum(['fixed', 'optimized']).default('fixed'),
42
+ /** Optimized send time: local hour used for people (and audiences) with no reading history (unset = 10). */
43
+ fallbackHour: z.number().int().min(0).max(23).optional(),
44
+ /** Recipient-local sends: where the local time has already passed, send `immediately` (default) or at that time `tomorrow`. */
45
+ pastZones: z.enum(['immediately', 'tomorrow']).optional(),
46
+ /** Recipients frozen per page and sent per fan-out transaction (default 100; sends commit at most 100 per transaction). Smaller batches hold locks for less time. */
47
+ batchSize: z.number().int().min(10).max(1000).optional(),
48
+ });
49
+ export const CampaignRoute = z.object({ connectionId: Id.optional(), poolId: Id.optional(), routePolicyId: Id.optional() });
50
+ export const VariantInput = z.object({
51
+ key: z.string().min(1).max(32),
52
+ templateVersionId: Id,
53
+ subject: z.string().max(998).nullish(),
54
+ fromName: z.string().max(200).nullish(),
55
+ previewText: z.string().max(300).nullish(),
56
+ replyTo: ReplyToList.nullish(),
57
+ imageAssetId: Id.nullish(),
58
+ sendOffset: z.number().int().min(0).max(10_080).default(0),
59
+ weight: z.number().int().min(1).max(1000).default(1),
60
+ });
61
+ /** Per-campaign tracking toggles; an unset key falls back to the workspace default. */
62
+ export const CampaignTracking = z.object({ opens: z.boolean().optional(), clicks: z.boolean().optional() });
63
+ /** Fanout pauses itself when failed or bounced sends pass these shares of the attempted sends (after `minSample` attempts). Unset = defaults. */
64
+ export const CampaignAutoPause = z.object({
65
+ enabled: z.boolean().default(true),
66
+ maxFailureRate: z.number().min(0).max(1).default(0.25),
67
+ maxBounceRate: z.number().min(0).max(1).default(0.1),
68
+ minSample: z.number().int().min(10).max(100_000).default(50),
69
+ });
70
+ /** Archive page path segment: `/p/a/<list>/<slug>`. */
71
+ export const CampaignSlug = z.string().min(1).max(80).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'lowercase letters, digits and dashes');
72
+ /** Review drafts nobody decided within `hours` of fan-out are sent (consent and suppression still apply) or skipped. */
73
+ export const ReviewDeadline = z.object({ hours: z.number().int().min(1).max(720), action: z.enum(['send', 'skip']) });
74
+ /** D-SEND-3: a campaign (and every newsletter send, which is a campaign) is bulk mail, so it is never transactional/operational. */
75
+ export const CampaignPurpose = z.enum(['marketing', 'prospecting']);
76
+ export const CreateCampaignBody = z.object({
77
+ name: z.string().trim().min(1).max(200),
78
+ channel: Channel,
79
+ purpose: CampaignPurpose.default('marketing'),
80
+ audience: CampaignAudience.default({ includeSegmentIds: [], includeListIds: [], excludeSegmentIds: [], excludeListIds: [] }),
81
+ templateId: Id.nullish(),
82
+ route: CampaignRoute.default({}),
83
+ schedule: CampaignSchedule.nullish(),
84
+ utm: z.record(z.string(), z.string()).nullish(),
85
+ topicId: Id.nullish(),
86
+ tracking: CampaignTracking.nullish(),
87
+ autoPause: CampaignAutoPause.nullish(),
88
+ slug: CampaignSlug.nullish(),
89
+ /** Values the public archive/web-version page shows in place of the recipient's (for example first_name: friend). */
90
+ archiveProfile: z.record(z.string().max(60), z.string().max(200)).nullish(),
91
+ /** List the sent campaign on the public archive page of its audience lists. */
92
+ inArchive: z.boolean().optional(),
93
+ variants: z.array(VariantInput).max(8).default([]),
94
+ /** Test-then-send: `testPercent` of the audience gets the variants; the winner goes to the rest. */
95
+ abTest: AbTestConfig.nullish(),
96
+ /** Hold every recipient's message as a draft to review, edit and send (GET /v1/campaigns/:id/drafts). */
97
+ reviewDrafts: z.boolean().optional(),
98
+ reviewDeadline: ReviewDeadline.nullish(),
99
+ /** Smart audience: at send time, leave out people predicted to unsubscribe or complain (past complaint, or long unengaged). */
100
+ smartAudience: z.boolean().optional(),
101
+ /** Product (app slug) that owns the campaign; an app-bound API key stamps its own. Its messages carry `app:<slug>`, so webhook endpoints of other apps skip their events. */
102
+ app: AppSlug.nullish(),
103
+ });
104
+ /** Explicit (no defaults): a PATCH must only touch the fields it names. */
105
+ export const UpdateCampaignBody = z.object({
106
+ name: CreateCampaignBody.shape.name.optional(),
107
+ purpose: CampaignPurpose.optional(),
108
+ audience: CampaignAudience.optional(),
109
+ templateId: Id.nullish(),
110
+ route: CampaignRoute.optional(),
111
+ schedule: CampaignSchedule.nullish(),
112
+ utm: z.record(z.string(), z.string()).nullish(),
113
+ topicId: Id.nullish(),
114
+ tracking: CampaignTracking.nullish(),
115
+ autoPause: CampaignAutoPause.nullish(),
116
+ slug: CampaignSlug.nullish(),
117
+ archiveProfile: z.record(z.string().max(60), z.string().max(200)).nullable().optional(),
118
+ inArchive: z.boolean().optional(),
119
+ variants: z.array(VariantInput).max(8).optional(),
120
+ abTest: AbTestConfig.nullish(),
121
+ reviewDrafts: z.boolean().optional(),
122
+ reviewDeadline: ReviewDeadline.nullish(),
123
+ smartAudience: z.boolean().optional(),
124
+ /** Move the campaign to another product (app slug), or null to share it. App-bound keys cannot. */
125
+ app: AppSlug.nullable().optional(),
126
+ });
127
+ /** Planning details, editable at any status. Dates are calendar days; the campaign's real send time is its schedule. */
128
+ export const CampaignDetailsBody = z.object({
129
+ ownerId: Id.nullable(),
130
+ startsOn: z.iso.date().nullable(),
131
+ endsOn: z.iso.date().nullable(),
132
+ notes: z.string().max(5000).nullable(),
133
+ }).refine((b) => !b.startsOn || !b.endsOn || b.endsOn >= b.startsOn, { message: 'The end date cannot be before the start date', path: ['endsOn'] });
134
+ export const CampaignDetailsDto = z.object({ id: Id, ownerId: Id.nullable(), startsOn: z.string().nullable(), endsOn: z.string().nullable(), notes: z.string().nullable() });
135
+ export const CampaignScheduleDto = CampaignSchedule.extend({ at: Timestamp });
136
+ export const CampaignDto = z.object({
137
+ id: Id,
138
+ name: z.string(),
139
+ channel: Channel,
140
+ purpose: Purpose,
141
+ status: CampaignStatus,
142
+ audience: CampaignAudience,
143
+ /** Set once the audience was frozen into recipients (fanout started). */
144
+ audienceFrozenAt: Timestamp.nullable(),
145
+ templateId: Id.nullable(),
146
+ topicId: Id.nullable(),
147
+ route: CampaignRoute,
148
+ schedule: CampaignScheduleDto.nullable(),
149
+ abTest: AbTestConfig.nullable(),
150
+ /** Only on GET /v1/campaigns/:id. */
151
+ variants: z.array(VariantInput).optional(),
152
+ utm: z.record(z.string(), z.string()).nullable(),
153
+ tracking: CampaignTracking.nullable(),
154
+ autoPause: CampaignAutoPause.nullable(),
155
+ slug: z.string().nullable(),
156
+ archiveProfile: z.record(z.string(), z.string()).nullable(),
157
+ inArchive: z.boolean(),
158
+ ownerId: Id.nullish(),
159
+ startsOn: z.string().nullish(),
160
+ endsOn: z.string().nullish(),
161
+ notes: z.string().nullish(),
162
+ /** not_required | pending | approved | rejected (POST /v1/campaigns/:id/approval/submit|approve|reject). */
163
+ approvalStatus: z.string(),
164
+ approvedBy: z.string().nullable(),
165
+ approvalSubmittedBy: z.string().nullish(),
166
+ approvalComment: z.string().nullish(),
167
+ startedAt: Timestamp.nullable(),
168
+ completedAt: Timestamp.nullable(),
169
+ testSentAt: Timestamp.nullable(),
170
+ /** Set when the content of a sent campaign was erased. */
171
+ contentErasedAt: Timestamp.nullish(),
172
+ /** Free-form counters; `audience` is the frozen audience size once known. */
173
+ stats: z.record(z.string(), z.number()),
174
+ /** Hidden from the default list; still reportable. */
175
+ archivedAt: Timestamp.nullish(),
176
+ /** The campaign this one was made from: a resend's original, or an RSS issue's feed campaign. */
177
+ parentCampaignId: Id.nullish(),
178
+ reviewDrafts: z.boolean().optional(),
179
+ reviewDeadline: ReviewDeadline.nullish(),
180
+ /** Why fan-out failed (status `failed`). */
181
+ failureReason: z.string().nullish(),
182
+ smartAudience: z.boolean().optional(),
183
+ app: z.string().nullable().optional(),
184
+ createdAt: Timestamp,
185
+ updatedAt: Timestamp,
186
+ });
187
+ export const CampaignEraseResult = z.object({ outcome: z.enum(['deleted', 'content_erased']) });
188
+ export const CampaignPage = pageResult(CampaignDto);
189
+ /** Shared by the list and search routes. `q` matches name, message subject and message content. */
190
+ export const CampaignListQuery = PageQuery.extend({
191
+ /** One status or a comma-separated list (`failed,paused,sending`). */
192
+ status: z.string().max(120).refine((s) => s.split(',').every((x) => CampaignStatus.safeParse(x).success), { message: `Each status must be one of ${CampaignStatus.options.join(', ')}` }).optional(),
193
+ q: z.string().max(200).optional(),
194
+ channel: Channel.optional(),
195
+ purpose: Purpose.optional(),
196
+ folderId: Id.optional(),
197
+ app: AppSlug.optional(),
198
+ tag: z.string().max(80).optional(),
199
+ listId: Id.optional(),
200
+ /** Created-at range. */
201
+ from: DateTimeIn().optional(),
202
+ to: DateTimeIn().optional(),
203
+ scheduledFrom: DateTimeIn().optional(),
204
+ scheduledTo: DateTimeIn().optional(),
205
+ updatedFrom: DateTimeIn().optional(),
206
+ updatedTo: DateTimeIn().optional(),
207
+ /** Send-time range: when sending started. */
208
+ sentFrom: DateTimeIn().optional(),
209
+ sentTo: DateTimeIn().optional(),
210
+ /** Campaigns sent to this member (they are a frozen recipient). */
211
+ profileId: Id.optional(),
212
+ /** `true` lists only archived campaigns; default hides them. */
213
+ archived: z.enum(['true', 'false']).transform((v) => v === 'true').optional(),
214
+ /** `true` lists soft-deleted drafts (for restore). */
215
+ deleted: z.enum(['true', 'false']).transform((v) => v === 'true').optional(),
216
+ sort: z.enum(['created', 'updated', 'name', 'scheduled']).default('created'),
217
+ order: z.enum(['asc', 'desc']).default('desc'),
218
+ });
219
+ export const ChecklistItem = z.object({
220
+ key: z.string(),
221
+ severity: z.enum(['error', 'warning']),
222
+ ok: z.boolean(),
223
+ message: z.string(),
224
+ });
225
+ export const ChecklistResult = z.object({ items: z.array(ChecklistItem), canSchedule: z.boolean() });
226
+ /** A saved seed list, addresses typed in for this one test, or both. */
227
+ export const TestSendBody = z.object({
228
+ seedListId: Id.optional(),
229
+ emails: z.array(z.email()).max(20).default([]),
230
+ phones: z.array(z.string().min(5).max(32)).max(20).default([]),
231
+ /** Push campaigns: the devices of this profile, or one pasted device token. */
232
+ profileId: Id.optional(),
233
+ pushToken: PushTestTarget.shape.pushToken,
234
+ }).refine((b) => b.seedListId || b.emails.length + b.phones.length > 0 || b.profileId || b.pushToken, 'Name a seed list, an address, a test profile or a device token');
235
+ export const TestSendResult = z.object({ sent: z.number().int(), blocked: z.number().int(), jobIds: z.array(Id) });
236
+ export const SeedListBody = z.object({
237
+ name: z.string().trim().min(1).max(200),
238
+ emails: z.array(z.email()).max(200).default([]),
239
+ phones: z.array(z.string().min(5).max(32)).max(200).default([]),
240
+ });
241
+ export const SeedListDto = z.object({ id: Id, name: z.string(), emails: z.array(z.string()), phones: z.array(z.string()), createdAt: Timestamp, updatedAt: Timestamp });
242
+ export const SeedListPage = pageResult(SeedListDto);
243
+ export const CalendarQuery = z.object({ from: DateTimeIn(), to: DateTimeIn() });
244
+ export const CalendarItem = z.object({
245
+ /** `workflow`: one occurrence of a live workflow's `schedule` (cron) trigger. */
246
+ kind: z.enum(['campaign', 'workflow']),
247
+ id: Id,
248
+ name: z.string(),
249
+ channel: Channel.nullable(),
250
+ /** Campaign status, or the workflow status (`live`). */
251
+ status: z.string(),
252
+ at: Timestamp,
253
+ /** Estimated completion: actual `completedAt`, else `at` + audience / throttle; equals `at` when there is no basis to estimate. */
254
+ endAt: Timestamp,
255
+ endEstimated: z.boolean(),
256
+ });
257
+ export const CalendarResult = z.object({ items: z.array(CalendarItem) });
258
+ export const CampaignReport = z.object({
259
+ campaignId: Id,
260
+ recipients: z.number().int(),
261
+ byStatus: z.record(z.string(), z.number().int()),
262
+ /** Analytics rollup for this campaign (counts + per-metric availability for its sending connections). */
263
+ analytics: z.object({ totals: MetricCounts, availability: AvailabilityMap }),
264
+ /** Smart audience: who was left out at freeze time and why (null when the option was off or the audience is not frozen yet). */
265
+ smartAudience: z.object({ dropped: z.number().int(), /** complained | unengaged | churned_unengaged -> people. */ reasons: z.record(z.string(), z.number().int()) }).nullish(),
266
+ });
267
+ export const CampaignInsights = z.object({
268
+ timeline: z.array(z.object({ hour: z.number().int(), opens: z.number().int(), clicks: z.number().int(), unsubscribes: z.number().int() })),
269
+ links: z.array(z.object({ url: z.string(), total: z.number().int(), unique: z.number().int() })),
270
+ domains: z.array(z.object({ group: z.enum(['gmail', 'outlook', 'yahoo', 'icloud', 'other']), sent: z.number().int(), opened: z.number().int(), clicked: z.number().int() })),
271
+ devices: z.array(z.object({ device: z.enum(['mobile', 'desktop', 'webmail', 'unknown']), opens: z.number().int(), clicks: z.number().int() })),
272
+ machineEvents: z.number().int(),
273
+ problems: z.object({ unsubscribes: z.number().int(), complaints: z.number().int(), bounces: z.number().int() }),
274
+ /** Attributed conversions; amounts in minor units (the workspace currency is not carried per conversion). */
275
+ revenue: z.object({ orders: z.number().int(), revenueMinor: z.number().int() }),
276
+ });
@@ -0,0 +1,57 @@
1
+ import { z } from 'zod';
2
+ export declare const Id: z.ZodUUID;
3
+ export declare const IdParams: z.ZodObject<{
4
+ id: z.ZodUUID;
5
+ }, z.core.$strip>;
6
+ export declare const PageQuery: z.ZodObject<{
7
+ limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
8
+ cursor: z.ZodOptional<z.ZodUUID>;
9
+ }, z.core.$strip>;
10
+ export type PageQuery = z.infer<typeof PageQuery>;
11
+ type Undefaulted<T> = T extends z.ZodDefault<infer I extends z.core.SomeType> ? I : T;
12
+ /** `.partial()` without the `.default()`s: zod 4 keeps them, so a PATCH would reset every key the caller left out. */
13
+ export declare const patchOf: <S extends z.ZodRawShape, C extends z.core.$ZodObjectConfig>(schema: z.ZodObject<S, C>) => z.ZodObject<{ -readonly [K in keyof S]: z.ZodOptional<Undefaulted<S[K]>>; }, C>;
14
+ export declare const pageResult: <T extends z.ZodType>(item: T) => z.ZodObject<{
15
+ items: z.ZodArray<T>;
16
+ nextCursor: z.ZodNullable<z.ZodUUID>;
17
+ }, z.core.$strip>;
18
+ /** One Reply-To address, or up to 5 separated by commas (replies go to all of them). */
19
+ export declare const ReplyToList: z.ZodString;
20
+ export declare const Timestamp: z.ZodISODateTime;
21
+ /** A calendar day `YYYY-MM-DD`; an ISO 8601 date-time is accepted too and reduced to its date part. */
22
+ export declare const IsoDay: z.ZodCodec<z.ZodString, z.ZodString>;
23
+ /** An instant (ISO 8601 date-time with offset); a bare `YYYY-MM-DD` is accepted and read as midnight UTC. */
24
+ export declare const TimestampIn: z.ZodCodec<z.ZodUnion<readonly [z.ZodISODateTime, z.ZodString]>, z.ZodISODateTime>;
25
+ /** `z.coerce.date()` (still takes everything `Date` parses) documented as an ISO 8601 date-time, with a readable error. */
26
+ export declare const DateTimeIn: () => z.ZodCoercedDate<unknown>;
27
+ /** `postcard`: printed mail through a bring-your-own print vendor; the destination is the profile (its postal address is read at send time). */
28
+ /** Which of your products sent an event, when several share one workspace (`forgedeck`, `formflow`). Lowercase slug. */
29
+ export declare const AppSlug: z.ZodString;
30
+ export declare const Channel: z.ZodEnum<{
31
+ email: "email";
32
+ postcard: "postcard";
33
+ push: "push";
34
+ sms: "sms";
35
+ whatsapp: "whatsapp";
36
+ }>;
37
+ /** Channels whose address is a phone number (E.164). */
38
+ export declare const isPhoneChannel: (c: Channel) => boolean;
39
+ export type Channel = z.infer<typeof Channel>;
40
+ /** Every send has exactly one purpose; purpose selects policy (brief §10.1). */
41
+ export declare const Purpose: z.ZodEnum<{
42
+ marketing: "marketing";
43
+ operational: "operational";
44
+ prospecting: "prospecting";
45
+ transactional: "transactional";
46
+ }>;
47
+ export type Purpose = z.infer<typeof Purpose>;
48
+ /** Free-form typed attribute bag (profiles, events, objects). */
49
+ export declare const Attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
50
+ export declare const ErrorBody: z.ZodObject<{
51
+ error: z.ZodObject<{
52
+ code: z.ZodString;
53
+ message: z.ZodString;
54
+ details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
55
+ }, z.core.$strip>;
56
+ }, z.core.$strip>;
57
+ export {};
@@ -0,0 +1,35 @@
1
+ import { z } from 'zod';
2
+ export const Id = z.uuid();
3
+ export const IdParams = z.object({ id: Id });
4
+ export const PageQuery = z.object({
5
+ limit: z.coerce.number().int().min(1).max(200).default(50),
6
+ cursor: z.uuid().optional(),
7
+ });
8
+ /** `.partial()` without the `.default()`s: zod 4 keeps them, so a PATCH would reset every key the caller left out. */
9
+ export const patchOf = (schema) => schema.extend(Object.fromEntries(Object.entries(schema.shape).map(([k, s]) => [k, s instanceof z.ZodDefault ? s.unwrap() : s]))).partial();
10
+ export const pageResult = (item) => z.object({ items: z.array(item), nextCursor: z.uuid().nullable() });
11
+ /** One Reply-To address, or up to 5 separated by commas (replies go to all of them). */
12
+ export const ReplyToList = z.string().trim().max(1000).refine((v) => { const p = v.split(',').map((x) => x.trim()); return p.length <= 5 && p.every((x) => z.email().safeParse(x).success); }, { message: 'Enter up to 5 valid email addresses separated by commas' });
13
+ export const Timestamp = z.iso.datetime({ offset: true });
14
+ // D-PLAT-21 / D-MKT-17: every date input takes ISO 8601, typed in the OpenAPI. Codecs (not transforms) so DTOs that reuse them still encode.
15
+ const DAY = /^\d{4}-\d{2}-\d{2}$/;
16
+ const DAY_OR_TIME = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
17
+ /** A calendar day `YYYY-MM-DD`; an ISO 8601 date-time is accepted too and reduced to its date part. */
18
+ export const IsoDay = z.codec(z.string().regex(DAY_OR_TIME, 'Use a date like 2026-11-30 (an ISO 8601 date-time also works)').meta({ format: 'date' }), z.string().regex(DAY), { decode: (s) => s.slice(0, 10), encode: (s) => s });
19
+ /** An instant (ISO 8601 date-time with offset); a bare `YYYY-MM-DD` is accepted and read as midnight UTC. */
20
+ export const TimestampIn = z.codec(z.union([Timestamp, z.string().regex(DAY)], { error: 'Use an ISO 8601 date-time like 2026-11-04T15:00:00Z, or a date like 2026-11-04' }).meta({ type: 'string', format: 'date-time' }), Timestamp, { decode: (s) => (DAY.test(s) ? `${s}T00:00:00Z` : s), encode: (s) => s });
21
+ /** `z.coerce.date()` (still takes everything `Date` parses) documented as an ISO 8601 date-time, with a readable error. */
22
+ export const DateTimeIn = () => z.coerce.date({ error: 'Use an ISO 8601 date-time like 2026-11-04T15:00:00Z' }).meta({ type: 'string', format: 'date-time' });
23
+ /** `postcard`: printed mail through a bring-your-own print vendor; the destination is the profile (its postal address is read at send time). */
24
+ /** Which of your products sent an event, when several share one workspace (`forgedeck`, `formflow`). Lowercase slug. */
25
+ export const AppSlug = z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, 'Use a lowercase slug like forgedeck or form-flow');
26
+ export const Channel = z.enum(['email', 'sms', 'whatsapp', 'push', 'postcard']);
27
+ /** Channels whose address is a phone number (E.164). */
28
+ export const isPhoneChannel = (c) => c === 'sms' || c === 'whatsapp';
29
+ /** Every send has exactly one purpose; purpose selects policy (brief §10.1). */
30
+ export const Purpose = z.enum(['marketing', 'prospecting', 'transactional', 'operational']);
31
+ /** Free-form typed attribute bag (profiles, events, objects). */
32
+ export const Attributes = z.record(z.string().max(128), z.unknown());
33
+ export const ErrorBody = z.object({
34
+ error: z.object({ code: z.string(), message: z.string(), details: z.record(z.string(), z.unknown()).optional() }),
35
+ });
@@ -0,0 +1,179 @@
1
+ import { z } from 'zod';
2
+ export declare const ConnectorKind: z.ZodEnum<{
3
+ bigcommerce: "bigcommerce";
4
+ bigquery: "bigquery";
5
+ dynamics: "dynamics";
6
+ hubspot: "hubspot";
7
+ pipedrive: "pipedrive";
8
+ posthog: "posthog";
9
+ s3: "s3";
10
+ salesforce: "salesforce";
11
+ segment: "segment";
12
+ shopify: "shopify";
13
+ snowflake: "snowflake";
14
+ stripe: "stripe";
15
+ woocommerce: "woocommerce";
16
+ zendesk: "zendesk";
17
+ }>;
18
+ /** Credentials are validated per kind in the integrations module and are never echoed back. */
19
+ export declare const CreateConnectorBody: z.ZodObject<{
20
+ kind: z.ZodEnum<{
21
+ bigcommerce: "bigcommerce";
22
+ bigquery: "bigquery";
23
+ dynamics: "dynamics";
24
+ hubspot: "hubspot";
25
+ pipedrive: "pipedrive";
26
+ posthog: "posthog";
27
+ s3: "s3";
28
+ salesforce: "salesforce";
29
+ segment: "segment";
30
+ shopify: "shopify";
31
+ snowflake: "snowflake";
32
+ stripe: "stripe";
33
+ woocommerce: "woocommerce";
34
+ zendesk: "zendesk";
35
+ }>;
36
+ name: z.ZodString;
37
+ credentials: z.ZodRecord<z.ZodString, z.ZodString>;
38
+ config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
39
+ }, z.core.$strip>;
40
+ export declare const ConnectorDto: z.ZodObject<{
41
+ id: z.ZodUUID;
42
+ kind: z.ZodUnion<readonly [z.ZodEnum<{
43
+ bigcommerce: "bigcommerce";
44
+ bigquery: "bigquery";
45
+ dynamics: "dynamics";
46
+ hubspot: "hubspot";
47
+ pipedrive: "pipedrive";
48
+ posthog: "posthog";
49
+ s3: "s3";
50
+ salesforce: "salesforce";
51
+ segment: "segment";
52
+ shopify: "shopify";
53
+ snowflake: "snowflake";
54
+ stripe: "stripe";
55
+ woocommerce: "woocommerce";
56
+ zendesk: "zendesk";
57
+ }>, z.ZodString]>;
58
+ name: z.ZodString;
59
+ config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
60
+ status: z.ZodEnum<{
61
+ active: "active";
62
+ disabled: "disabled";
63
+ error: "error";
64
+ }>;
65
+ lastSyncAt: z.ZodNullable<z.ZodISODateTime>;
66
+ lastError: z.ZodNullable<z.ZodString>;
67
+ createdAt: z.ZodISODateTime;
68
+ }, z.core.$strip>;
69
+ export declare const ConnectorTestResult: z.ZodObject<{
70
+ ok: z.ZodBoolean;
71
+ message: z.ZodString;
72
+ }, z.core.$strip>;
73
+ export declare const ConnectorWebhookUrl: z.ZodObject<{
74
+ url: z.ZodURL;
75
+ }, z.core.$strip>;
76
+ export declare const ConnectorList: z.ZodObject<{
77
+ items: z.ZodArray<z.ZodObject<{
78
+ id: z.ZodUUID;
79
+ kind: z.ZodUnion<readonly [z.ZodEnum<{
80
+ bigcommerce: "bigcommerce";
81
+ bigquery: "bigquery";
82
+ dynamics: "dynamics";
83
+ hubspot: "hubspot";
84
+ pipedrive: "pipedrive";
85
+ posthog: "posthog";
86
+ s3: "s3";
87
+ salesforce: "salesforce";
88
+ segment: "segment";
89
+ shopify: "shopify";
90
+ snowflake: "snowflake";
91
+ stripe: "stripe";
92
+ woocommerce: "woocommerce";
93
+ zendesk: "zendesk";
94
+ }>, z.ZodString]>;
95
+ name: z.ZodString;
96
+ config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
97
+ status: z.ZodEnum<{
98
+ active: "active";
99
+ disabled: "disabled";
100
+ error: "error";
101
+ }>;
102
+ lastSyncAt: z.ZodNullable<z.ZodISODateTime>;
103
+ lastError: z.ZodNullable<z.ZodString>;
104
+ createdAt: z.ZodISODateTime;
105
+ }, z.core.$strip>>;
106
+ }, z.core.$strip>;
107
+ export declare const ShopifyInstallQuery: z.ZodObject<{
108
+ shop: z.ZodString;
109
+ }, z.core.$strip>;
110
+ export declare const ShopifyInstallResult: z.ZodObject<{
111
+ url: z.ZodURL;
112
+ }, z.core.$strip>;
113
+ /** One-click WooCommerce connect: the store site (https) and, from the WordPress plugin, where WooCommerce should send the merchant back. */
114
+ export declare const WooConnectQuery: z.ZodObject<{
115
+ site: z.ZodURL;
116
+ returnUrl: z.ZodOptional<z.ZodURL>;
117
+ }, z.core.$strip>;
118
+ /** What WooCommerce POSTs to the callback after the merchant approves (`user_id` carries our signed state). */
119
+ export declare const WooConnectCallbackBody: z.ZodObject<{
120
+ key_id: z.ZodOptional<z.ZodNumber>;
121
+ user_id: z.ZodString;
122
+ consumer_key: z.ZodString;
123
+ consumer_secret: z.ZodString;
124
+ key_permissions: z.ZodOptional<z.ZodString>;
125
+ }, z.core.$strip>;
126
+ export declare const ShopifyDiscountBody: z.ZodObject<{
127
+ poolId: z.ZodUUID;
128
+ count: z.ZodNumber;
129
+ percentOff: z.ZodNumber;
130
+ prefix: z.ZodOptional<z.ZodString>;
131
+ endsAt: z.ZodOptional<z.ZodISODateTime>;
132
+ }, z.core.$strip>;
133
+ export declare const ShopifyDiscountResult: z.ZodObject<{
134
+ created: z.ZodNumber;
135
+ addedToPool: z.ZodNumber;
136
+ }, z.core.$strip>;
137
+ /** Reverse-ETL rows. Events need a `dedupeKey` so a re-run of the warehouse sync is a no-op. */
138
+ export declare const WarehouseRowsBody: z.ZodObject<{
139
+ rows: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
140
+ email: z.ZodOptional<z.ZodString>;
141
+ phone: z.ZodOptional<z.ZodString>;
142
+ externalId: z.ZodOptional<z.ZodString>;
143
+ type: z.ZodLiteral<"profile">;
144
+ firstName: z.ZodOptional<z.ZodString>;
145
+ lastName: z.ZodOptional<z.ZodString>;
146
+ attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
147
+ }, z.core.$strip>, z.ZodObject<{
148
+ email: z.ZodOptional<z.ZodString>;
149
+ phone: z.ZodOptional<z.ZodString>;
150
+ externalId: z.ZodOptional<z.ZodString>;
151
+ type: z.ZodLiteral<"event">;
152
+ name: z.ZodString;
153
+ occurredAt: z.ZodOptional<z.ZodISODateTime>;
154
+ properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
155
+ dedupeKey: z.ZodString;
156
+ }, z.core.$strip>], "type">>;
157
+ }, z.core.$strip>;
158
+ export declare const WarehouseRowsResult: z.ZodObject<{
159
+ applied: z.ZodNumber;
160
+ failed: z.ZodArray<z.ZodObject<{
161
+ index: z.ZodNumber;
162
+ reason: z.ZodString;
163
+ }, z.core.$strip>>;
164
+ }, z.core.$strip>;
165
+ /** HubSpot install: each workspace brings its own HubSpot app, so its credentials come with the request (sealed, never echoed). */
166
+ export declare const HubSpotInstallBody: z.ZodObject<{
167
+ name: z.ZodString;
168
+ clientId: z.ZodString;
169
+ clientSecret: z.ZodString;
170
+ appId: z.ZodOptional<z.ZodString>;
171
+ developerApiKey: z.ZodOptional<z.ZodString>;
172
+ }, z.core.$strip>;
173
+ export declare const HubSpotInstallResult: z.ZodObject<{
174
+ connectionId: z.ZodUUID;
175
+ url: z.ZodURL;
176
+ }, z.core.$strip>;
177
+ export declare const HubSpotWebhooksResult: z.ZodObject<{
178
+ registered: z.ZodBoolean;
179
+ }, z.core.$strip>;
@@ -0,0 +1,46 @@
1
+ import { z } from 'zod';
2
+ import { Id, Timestamp } from './common.js';
3
+ export const ConnectorKind = z.enum(['hubspot', 'shopify', 'salesforce', 'pipedrive', 'dynamics', 'zendesk', 'segment', 'posthog', 'woocommerce', 'bigcommerce', 'stripe', 's3', 'bigquery', 'snowflake']);
4
+ /** Credentials are validated per kind in the integrations module and are never echoed back. */
5
+ export const CreateConnectorBody = z.object({
6
+ kind: ConnectorKind,
7
+ name: z.string().min(1).max(120),
8
+ credentials: z.record(z.string(), z.string().max(4096)),
9
+ /** shopify: `{ shop: "<name>.myshopify.com" }` */
10
+ config: z.record(z.string(), z.unknown()).optional(),
11
+ });
12
+ export const ConnectorDto = z.object({
13
+ id: Id, kind: z.union([ConnectorKind, z.string().regex(/^x:[a-z0-9-]+$/)]), name: z.string(), config: z.record(z.string(), z.unknown()), status: z.enum(['active', 'error', 'disabled']),
14
+ lastSyncAt: Timestamp.nullable(), lastError: z.string().nullable(), createdAt: Timestamp,
15
+ });
16
+ export const ConnectorTestResult = z.object({ ok: z.boolean(), message: z.string() });
17
+ export const ConnectorWebhookUrl = z.object({ url: z.url() });
18
+ export const ConnectorList = z.object({ items: z.array(ConnectorDto) });
19
+ export const ShopifyInstallQuery = z.object({ shop: z.string().regex(/^[a-z0-9][a-z0-9-]{0,60}\.myshopify\.com$/, 'Use <name>.myshopify.com') });
20
+ export const ShopifyInstallResult = z.object({ url: z.url() });
21
+ /** One-click WooCommerce connect: the store site (https) and, from the WordPress plugin, where WooCommerce should send the merchant back. */
22
+ export const WooConnectQuery = z.object({ site: z.url().max(512), returnUrl: z.url().max(1024).optional() });
23
+ /** What WooCommerce POSTs to the callback after the merchant approves (`user_id` carries our signed state). */
24
+ export const WooConnectCallbackBody = z.object({ key_id: z.number().int().optional(), user_id: z.string().min(1).max(2048), consumer_key: z.string().min(1).max(256), consumer_secret: z.string().min(1).max(256), key_permissions: z.string().max(32).optional() });
25
+ export const ShopifyDiscountBody = z.object({
26
+ poolId: Id, count: z.number().int().min(1).max(2000), percentOff: z.number().min(1).max(100),
27
+ prefix: z.string().max(12).optional(), endsAt: Timestamp.optional(),
28
+ });
29
+ export const ShopifyDiscountResult = z.object({ created: z.number().int(), addedToPool: z.number().int() });
30
+ const RowIdentity = { email: z.string().max(320).optional(), phone: z.string().max(32).optional(), externalId: z.string().max(200).optional() };
31
+ /** Reverse-ETL rows. Events need a `dedupeKey` so a re-run of the warehouse sync is a no-op. */
32
+ export const WarehouseRowsBody = z.object({
33
+ rows: z.array(z.discriminatedUnion('type', [
34
+ z.object({ type: z.literal('profile'), ...RowIdentity, firstName: z.string().max(200).optional(), lastName: z.string().max(200).optional(), attributes: z.record(z.string(), z.unknown()).optional() }),
35
+ z.object({ type: z.literal('event'), ...RowIdentity, name: z.string().min(1).max(128), occurredAt: Timestamp.optional(), properties: z.record(z.string(), z.unknown()).optional(), dedupeKey: z.string().min(1).max(256) }),
36
+ ])).min(1).max(1000),
37
+ });
38
+ export const WarehouseRowsResult = z.object({ applied: z.number().int(), failed: z.array(z.object({ index: z.number().int(), reason: z.string() })) });
39
+ /** HubSpot install: each workspace brings its own HubSpot app, so its credentials come with the request (sealed, never echoed). */
40
+ export const HubSpotInstallBody = z.object({
41
+ name: z.string().min(1).max(120), clientId: z.string().min(1).max(200), clientSecret: z.string().min(1).max(200),
42
+ /** With both, Hermeticor registers the contact webhook subscriptions on the app after the install. */
43
+ appId: z.string().min(1).max(40).optional(), developerApiKey: z.string().min(1).max(200).optional(),
44
+ });
45
+ export const HubSpotInstallResult = z.object({ connectionId: Id, url: z.url() });
46
+ export const HubSpotWebhooksResult = z.object({ registered: z.boolean() });