@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
package/LICENSE ADDED
@@ -0,0 +1,9 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hermetica
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,13 @@
1
- # Temporary Holding Version
1
+ # @hermeticacomms/sdk-node
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Typed Node.js client for the Hermetica API (Node 20+).
4
+
5
+ ```ts
6
+ import { createClient } from '@hermeticacomms/sdk-node';
7
+
8
+ const hm = createClient({ apiKey: process.env.HERMETICA_API_KEY!, baseUrl: 'https://api.example.com' });
9
+ ```
10
+
11
+ Every non-GET call sends an `Idempotency-Key`. Consent and suppression are enforced by the API; the client cannot bypass them.
12
+
13
+ Generated from the Hermetica monorepo; open issues here, changes land upstream.
@@ -0,0 +1,405 @@
1
+ import { z } from 'zod';
2
+ export declare const METRICS: readonly ['queued', 'sent', 'delivered', 'bounced', 'complained', 'failed', 'opened', 'opened_unique', 'clicked', 'clicked_unique', 'replied', 'unsubscribed'];
3
+ export declare const Metric: z.ZodEnum<{
4
+ bounced: "bounced";
5
+ clicked: "clicked";
6
+ clicked_unique: "clicked_unique";
7
+ complained: "complained";
8
+ delivered: "delivered";
9
+ failed: "failed";
10
+ opened: "opened";
11
+ opened_unique: "opened_unique";
12
+ queued: "queued";
13
+ replied: "replied";
14
+ sent: "sent";
15
+ unsubscribed: "unsubscribed";
16
+ }>;
17
+ export type Metric = z.infer<typeof Metric>;
18
+ export declare const MetricAvailability: z.ZodEnum<{
19
+ approximate: "approximate";
20
+ available: "available";
21
+ unavailable: "unavailable";
22
+ }>;
23
+ export type MetricAvailability = z.infer<typeof MetricAvailability>;
24
+ export declare const AvailabilityMap: z.ZodRecord<z.ZodEnum<{
25
+ bounced: "bounced";
26
+ clicked: "clicked";
27
+ clicked_unique: "clicked_unique";
28
+ complained: "complained";
29
+ delivered: "delivered";
30
+ failed: "failed";
31
+ opened: "opened";
32
+ opened_unique: "opened_unique";
33
+ queued: "queued";
34
+ replied: "replied";
35
+ sent: "sent";
36
+ unsubscribed: "unsubscribed";
37
+ }>, z.ZodEnum<{
38
+ approximate: "approximate";
39
+ available: "available";
40
+ unavailable: "unavailable";
41
+ }>>;
42
+ export declare const MessageAnalyticsQuery: z.ZodObject<{
43
+ from: z.ZodCodec<z.ZodString, z.ZodString>;
44
+ to: z.ZodCodec<z.ZodString, z.ZodString>;
45
+ groupBy: z.ZodDefault<z.ZodEnum<{
46
+ channel: "channel";
47
+ day: "day";
48
+ source: "source";
49
+ variant: "variant";
50
+ }>>;
51
+ sourceKind: z.ZodOptional<z.ZodString>;
52
+ sourceId: z.ZodOptional<z.ZodString>;
53
+ channel: z.ZodOptional<z.ZodEnum<{
54
+ email: "email";
55
+ postcard: "postcard";
56
+ push: "push";
57
+ sms: "sms";
58
+ whatsapp: "whatsapp";
59
+ }>>;
60
+ includeMachineOpens: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
61
+ false: "false";
62
+ true: "true";
63
+ }>, z.ZodTransform<boolean, "false" | "true">>>;
64
+ }, z.core.$strip>;
65
+ export type MessageAnalyticsQuery = z.infer<typeof MessageAnalyticsQuery>;
66
+ export declare const SummaryQuery: z.ZodObject<{
67
+ includeMachineOpens: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
68
+ false: "false";
69
+ true: "true";
70
+ }>, z.ZodTransform<boolean, "false" | "true">>>;
71
+ }, z.core.$strip>;
72
+ /** Every kind a message job can come from (D-PLAT-25: anything else is 400). */
73
+ export declare const SourceParams: z.ZodObject<{
74
+ kind: z.ZodEnum<{
75
+ api: "api";
76
+ campaign: "campaign";
77
+ in_app: "in_app";
78
+ sequence: "sequence";
79
+ workflow: "workflow";
80
+ }>;
81
+ id: z.ZodString;
82
+ }, z.core.$strip>;
83
+ export declare const MetricCounts: z.ZodRecord<z.ZodEnum<{
84
+ bounced: "bounced";
85
+ clicked: "clicked";
86
+ clicked_unique: "clicked_unique";
87
+ complained: "complained";
88
+ delivered: "delivered";
89
+ failed: "failed";
90
+ opened: "opened";
91
+ opened_unique: "opened_unique";
92
+ queued: "queued";
93
+ replied: "replied";
94
+ sent: "sent";
95
+ unsubscribed: "unsubscribed";
96
+ }>, z.ZodNumber>;
97
+ export declare const SeriesPoint: z.ZodObject<{
98
+ key: z.ZodString;
99
+ counts: z.ZodRecord<z.ZodEnum<{
100
+ bounced: "bounced";
101
+ clicked: "clicked";
102
+ clicked_unique: "clicked_unique";
103
+ complained: "complained";
104
+ delivered: "delivered";
105
+ failed: "failed";
106
+ opened: "opened";
107
+ opened_unique: "opened_unique";
108
+ queued: "queued";
109
+ replied: "replied";
110
+ sent: "sent";
111
+ unsubscribed: "unsubscribed";
112
+ }>, z.ZodNumber>;
113
+ }, z.core.$strip>;
114
+ export declare const MessageAnalytics: z.ZodObject<{
115
+ groupBy: z.ZodString;
116
+ series: z.ZodArray<z.ZodObject<{
117
+ key: z.ZodString;
118
+ counts: z.ZodRecord<z.ZodEnum<{
119
+ bounced: "bounced";
120
+ clicked: "clicked";
121
+ clicked_unique: "clicked_unique";
122
+ complained: "complained";
123
+ delivered: "delivered";
124
+ failed: "failed";
125
+ opened: "opened";
126
+ opened_unique: "opened_unique";
127
+ queued: "queued";
128
+ replied: "replied";
129
+ sent: "sent";
130
+ unsubscribed: "unsubscribed";
131
+ }>, z.ZodNumber>;
132
+ }, z.core.$strip>>;
133
+ totals: z.ZodRecord<z.ZodEnum<{
134
+ bounced: "bounced";
135
+ clicked: "clicked";
136
+ clicked_unique: "clicked_unique";
137
+ complained: "complained";
138
+ delivered: "delivered";
139
+ failed: "failed";
140
+ opened: "opened";
141
+ opened_unique: "opened_unique";
142
+ queued: "queued";
143
+ replied: "replied";
144
+ sent: "sent";
145
+ unsubscribed: "unsubscribed";
146
+ }>, z.ZodNumber>;
147
+ availability: z.ZodRecord<z.ZodEnum<{
148
+ bounced: "bounced";
149
+ clicked: "clicked";
150
+ clicked_unique: "clicked_unique";
151
+ complained: "complained";
152
+ delivered: "delivered";
153
+ failed: "failed";
154
+ opened: "opened";
155
+ opened_unique: "opened_unique";
156
+ queued: "queued";
157
+ replied: "replied";
158
+ sent: "sent";
159
+ unsubscribed: "unsubscribed";
160
+ }>, z.ZodEnum<{
161
+ approximate: "approximate";
162
+ available: "available";
163
+ unavailable: "unavailable";
164
+ }>>;
165
+ }, z.core.$strip>;
166
+ export type MessageAnalytics = z.infer<typeof MessageAnalytics>;
167
+ export declare const SourceSummary: z.ZodObject<{
168
+ totals: z.ZodRecord<z.ZodEnum<{
169
+ bounced: "bounced";
170
+ clicked: "clicked";
171
+ clicked_unique: "clicked_unique";
172
+ complained: "complained";
173
+ delivered: "delivered";
174
+ failed: "failed";
175
+ opened: "opened";
176
+ opened_unique: "opened_unique";
177
+ queued: "queued";
178
+ replied: "replied";
179
+ sent: "sent";
180
+ unsubscribed: "unsubscribed";
181
+ }>, z.ZodNumber>;
182
+ availability: z.ZodRecord<z.ZodEnum<{
183
+ bounced: "bounced";
184
+ clicked: "clicked";
185
+ clicked_unique: "clicked_unique";
186
+ complained: "complained";
187
+ delivered: "delivered";
188
+ failed: "failed";
189
+ opened: "opened";
190
+ opened_unique: "opened_unique";
191
+ queued: "queued";
192
+ replied: "replied";
193
+ sent: "sent";
194
+ unsubscribed: "unsubscribed";
195
+ }>, z.ZodEnum<{
196
+ approximate: "approximate";
197
+ available: "available";
198
+ unavailable: "unavailable";
199
+ }>>;
200
+ }, z.core.$strip>;
201
+ export type SourceSummary = z.infer<typeof SourceSummary>;
202
+ export declare const PredictionDto: z.ZodObject<{
203
+ profileId: z.ZodUUID;
204
+ model: z.ZodString;
205
+ orderCount: z.ZodNumber;
206
+ avgOrderMinor: z.ZodNumber;
207
+ avgIntervalDays: z.ZodNumber;
208
+ historicClvMinor: z.ZodNumber;
209
+ predictedClvMinor: z.ZodNumber;
210
+ expectedNextOrderAt: z.ZodISODateTime;
211
+ churnRisk: z.ZodNumber;
212
+ why: z.ZodString;
213
+ computedAt: z.ZodISODateTime;
214
+ pAlive: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
215
+ expectedOrders: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
216
+ }, z.core.$strip>;
217
+ /** Inference from the first name against US birth records; shown to staff and in templates, never shared with ad platforms or benchmarks. */
218
+ export declare const PredictedGenderDto: z.ZodObject<{
219
+ gender: z.ZodEnum<{
220
+ likely_female: "likely_female";
221
+ likely_male: "likely_male";
222
+ uncertain: "uncertain";
223
+ }>;
224
+ confidence: z.ZodNumber;
225
+ computedAt: z.ZodISODateTime;
226
+ }, z.core.$strip>;
227
+ export declare const PredictionHoldout: z.ZodObject<{
228
+ holdoutWeeks: z.ZodNumber;
229
+ customers: z.ZodNumber;
230
+ mae: z.ZodNumber;
231
+ baselineMae: z.ZodNumber;
232
+ customerMae: z.ZodNumber;
233
+ baselineCustomerMae: z.ZodNumber;
234
+ priorMae: z.ZodNumber;
235
+ totalPredicted: z.ZodNumber;
236
+ totalActual: z.ZodNumber;
237
+ beatsBaseline: z.ZodBoolean;
238
+ calibration: z.ZodArray<z.ZodObject<{
239
+ bucket: z.ZodString;
240
+ customers: z.ZodNumber;
241
+ predicted: z.ZodNumber;
242
+ actual: z.ZodNumber;
243
+ baseline: z.ZodNumber;
244
+ }, z.core.$strip>>;
245
+ }, z.core.$strip>;
246
+ export declare const PredictionFit: z.ZodObject<{
247
+ version: z.ZodString;
248
+ fittedAt: z.ZodISODateTime;
249
+ customers: z.ZodNumber;
250
+ repeatBuyers: z.ZodNumber;
251
+ priorUsed: z.ZodString;
252
+ priorWeight: z.ZodNumber;
253
+ networkCohort: z.ZodNullable<z.ZodString>;
254
+ params: z.ZodObject<{
255
+ r: z.ZodNumber;
256
+ alpha: z.ZodNumber;
257
+ a: z.ZodNumber;
258
+ b: z.ZodNumber;
259
+ }, z.core.$strip>;
260
+ spendParams: z.ZodObject<{
261
+ p: z.ZodNumber;
262
+ q: z.ZodNumber;
263
+ v: z.ZodNumber;
264
+ }, z.core.$strip>;
265
+ holdout: z.ZodNullable<z.ZodObject<{
266
+ holdoutWeeks: z.ZodNumber;
267
+ customers: z.ZodNumber;
268
+ mae: z.ZodNumber;
269
+ baselineMae: z.ZodNumber;
270
+ customerMae: z.ZodNumber;
271
+ baselineCustomerMae: z.ZodNumber;
272
+ priorMae: z.ZodNumber;
273
+ totalPredicted: z.ZodNumber;
274
+ totalActual: z.ZodNumber;
275
+ beatsBaseline: z.ZodBoolean;
276
+ calibration: z.ZodArray<z.ZodObject<{
277
+ bucket: z.ZodString;
278
+ customers: z.ZodNumber;
279
+ predicted: z.ZodNumber;
280
+ actual: z.ZodNumber;
281
+ baseline: z.ZodNumber;
282
+ }, z.core.$strip>>;
283
+ }, z.core.$strip>>;
284
+ }, z.core.$strip>;
285
+ export declare const PredictionStatus: z.ZodObject<{
286
+ model: z.ZodString;
287
+ orderEvent: z.ZodString;
288
+ eligible: z.ZodBoolean;
289
+ reason: z.ZodNullable<z.ZodString>;
290
+ repeatCustomers: z.ZodNumber;
291
+ spanDays: z.ZodNumber;
292
+ minRepeatCustomers: z.ZodNumber;
293
+ minSpanDays: z.ZodNumber;
294
+ predictedProfiles: z.ZodNumber;
295
+ lastComputedAt: z.ZodNullable<z.ZodISODateTime>;
296
+ sufficiency: z.ZodEnum<{
297
+ fitted: "fitted";
298
+ none: "none";
299
+ prior_only: "prior_only";
300
+ }>;
301
+ fit: z.ZodNullable<z.ZodObject<{
302
+ version: z.ZodString;
303
+ fittedAt: z.ZodISODateTime;
304
+ customers: z.ZodNumber;
305
+ repeatBuyers: z.ZodNumber;
306
+ priorUsed: z.ZodString;
307
+ priorWeight: z.ZodNumber;
308
+ networkCohort: z.ZodNullable<z.ZodString>;
309
+ params: z.ZodObject<{
310
+ r: z.ZodNumber;
311
+ alpha: z.ZodNumber;
312
+ a: z.ZodNumber;
313
+ b: z.ZodNumber;
314
+ }, z.core.$strip>;
315
+ spendParams: z.ZodObject<{
316
+ p: z.ZodNumber;
317
+ q: z.ZodNumber;
318
+ v: z.ZodNumber;
319
+ }, z.core.$strip>;
320
+ holdout: z.ZodNullable<z.ZodObject<{
321
+ holdoutWeeks: z.ZodNumber;
322
+ customers: z.ZodNumber;
323
+ mae: z.ZodNumber;
324
+ baselineMae: z.ZodNumber;
325
+ customerMae: z.ZodNumber;
326
+ baselineCustomerMae: z.ZodNumber;
327
+ priorMae: z.ZodNumber;
328
+ totalPredicted: z.ZodNumber;
329
+ totalActual: z.ZodNumber;
330
+ beatsBaseline: z.ZodBoolean;
331
+ calibration: z.ZodArray<z.ZodObject<{
332
+ bucket: z.ZodString;
333
+ customers: z.ZodNumber;
334
+ predicted: z.ZodNumber;
335
+ actual: z.ZodNumber;
336
+ baseline: z.ZodNumber;
337
+ }, z.core.$strip>>;
338
+ }, z.core.$strip>>;
339
+ }, z.core.$strip>>;
340
+ lastAttempt: z.ZodNullable<z.ZodObject<{
341
+ fittedAt: z.ZodISODateTime;
342
+ promoted: z.ZodBoolean;
343
+ note: z.ZodString;
344
+ }, z.core.$strip>>;
345
+ }, z.core.$strip>;
346
+ export declare const RecommendationDto: z.ZodObject<{
347
+ productId: z.ZodString;
348
+ title: z.ZodNullable<z.ZodString>;
349
+ score: z.ZodNumber;
350
+ rank: z.ZodNumber;
351
+ basis: z.ZodEnum<{
352
+ co_purchase: "co_purchase";
353
+ popular: "popular";
354
+ }>;
355
+ }, z.core.$strip>;
356
+ export declare const RecommendationList: z.ZodObject<{
357
+ profileId: z.ZodUUID;
358
+ computedAt: z.ZodNullable<z.ZodISODateTime>;
359
+ items: z.ZodArray<z.ZodObject<{
360
+ productId: z.ZodString;
361
+ title: z.ZodNullable<z.ZodString>;
362
+ score: z.ZodNumber;
363
+ rank: z.ZodNumber;
364
+ basis: z.ZodEnum<{
365
+ co_purchase: "co_purchase";
366
+ popular: "popular";
367
+ }>;
368
+ }, z.core.$strip>>;
369
+ }, z.core.$strip>;
370
+ export declare const PredictionRunResult: z.ZodObject<{
371
+ ran: z.ZodBoolean;
372
+ profiles: z.ZodNumber;
373
+ reason: z.ZodNullable<z.ZodString>;
374
+ }, z.core.$strip>;
375
+ export declare const FunnelQuery: z.ZodObject<{
376
+ steps: z.ZodArray<z.ZodString>;
377
+ from: z.ZodCodec<z.ZodString, z.ZodString>;
378
+ to: z.ZodCodec<z.ZodString, z.ZodString>;
379
+ windowDays: z.ZodDefault<z.ZodNumber>;
380
+ }, z.core.$strip>;
381
+ export type FunnelQuery = z.infer<typeof FunnelQuery>;
382
+ export declare const FunnelResult: z.ZodObject<{
383
+ steps: z.ZodArray<z.ZodObject<{
384
+ name: z.ZodString;
385
+ profiles: z.ZodNumber;
386
+ conversionFromPrevious: z.ZodNullable<z.ZodNumber>;
387
+ conversionFromFirst: z.ZodNullable<z.ZodNumber>;
388
+ }, z.core.$strip>>;
389
+ }, z.core.$strip>;
390
+ export declare const CohortQuery: z.ZodObject<{
391
+ anchorEvent: z.ZodString;
392
+ returnEvent: z.ZodString;
393
+ from: z.ZodCodec<z.ZodString, z.ZodString>;
394
+ to: z.ZodCodec<z.ZodString, z.ZodString>;
395
+ weeks: z.ZodDefault<z.ZodNumber>;
396
+ }, z.core.$strip>;
397
+ export type CohortQuery = z.infer<typeof CohortQuery>;
398
+ export declare const CohortResult: z.ZodObject<{
399
+ weeks: z.ZodNumber;
400
+ cohorts: z.ZodArray<z.ZodObject<{
401
+ cohort: z.ZodString;
402
+ size: z.ZodNumber;
403
+ retained: z.ZodArray<z.ZodNumber>;
404
+ }, z.core.$strip>>;
405
+ }, z.core.$strip>;
@@ -0,0 +1,77 @@
1
+ import { z } from 'zod';
2
+ import { Channel, IsoDay } from './common.js';
3
+ export const METRICS = [
4
+ 'queued', 'sent', 'delivered', 'bounced', 'complained', 'failed', 'opened', 'opened_unique', 'clicked', 'clicked_unique', 'replied', 'unsubscribed',
5
+ ];
6
+ export const Metric = z.enum(METRICS);
7
+ export const MetricAvailability = z.enum(['available', 'unavailable', 'approximate']);
8
+ export const AvailabilityMap = z.record(Metric, MetricAvailability);
9
+ const Bool = z.enum(['true', 'false']).transform((v) => v === 'true');
10
+ const Day = IsoDay;
11
+ export const MessageAnalyticsQuery = z.object({
12
+ from: Day, to: Day,
13
+ groupBy: z.enum(['day', 'channel', 'source', 'variant']).default('day'),
14
+ sourceKind: z.string().min(1).max(64).optional(),
15
+ sourceId: z.string().min(1).max(128).optional(),
16
+ channel: Channel.optional(),
17
+ /** Count machine opens (Apple MPP, scanners) in opened / opened_unique. Off by default. */
18
+ includeMachineOpens: Bool.optional(),
19
+ });
20
+ export const SummaryQuery = z.object({ includeMachineOpens: Bool.optional() });
21
+ /** Every kind a message job can come from (D-PLAT-25: anything else is 400). */
22
+ export const SourceParams = z.object({ kind: z.enum(['campaign', 'workflow', 'sequence', 'api', 'in_app']), id: z.string().min(1).max(128) });
23
+ export const MetricCounts = z.record(Metric, z.number().int());
24
+ export const SeriesPoint = z.object({ key: z.string(), counts: MetricCounts });
25
+ export const MessageAnalytics = z.object({
26
+ groupBy: z.string(),
27
+ series: z.array(SeriesPoint),
28
+ totals: MetricCounts,
29
+ availability: AvailabilityMap,
30
+ });
31
+ export const SourceSummary = z.object({ totals: MetricCounts, availability: AvailabilityMap });
32
+ // ---- predictive analytics ----------------------------------------------------------------------------------------------
33
+ export const PredictionDto = z.object({
34
+ profileId: z.uuid(), model: z.string(), orderCount: z.number().int(), avgOrderMinor: z.number(), avgIntervalDays: z.number(),
35
+ historicClvMinor: z.number(), predictedClvMinor: z.number(), expectedNextOrderAt: z.iso.datetime({ offset: true }), churnRisk: z.number(),
36
+ why: z.string(), computedAt: z.iso.datetime({ offset: true }),
37
+ /** BG/NBD models only: probability still active and expected orders in the next 365 days. */
38
+ pAlive: z.number().nullish(), expectedOrders: z.number().nullish(),
39
+ });
40
+ /** Inference from the first name against US birth records; shown to staff and in templates, never shared with ad platforms or benchmarks. */
41
+ export const PredictedGenderDto = z.object({
42
+ gender: z.enum(['likely_female', 'likely_male', 'uncertain']), confidence: z.number(), computedAt: z.iso.datetime({ offset: true }),
43
+ });
44
+ export const PredictionHoldout = z.object({
45
+ holdoutWeeks: z.number(), customers: z.number().int(), mae: z.number(), baselineMae: z.number(), customerMae: z.number(), baselineCustomerMae: z.number(), priorMae: z.number(),
46
+ totalPredicted: z.number(), totalActual: z.number(), beatsBaseline: z.boolean(),
47
+ calibration: z.array(z.object({ bucket: z.string(), customers: z.number().int(), predicted: z.number(), actual: z.number(), baseline: z.number() })),
48
+ });
49
+ export const PredictionFit = z.object({
50
+ version: z.string(), fittedAt: z.iso.datetime({ offset: true }), customers: z.number().int(), repeatBuyers: z.number().int(), priorUsed: z.string(), priorWeight: z.number(), networkCohort: z.string().nullable(),
51
+ params: z.object({ r: z.number(), alpha: z.number(), a: z.number(), b: z.number() }), spendParams: z.object({ p: z.number(), q: z.number(), v: z.number() }), holdout: PredictionHoldout.nullable(),
52
+ });
53
+ export const PredictionStatus = z.object({
54
+ model: z.string(), orderEvent: z.string(), eligible: z.boolean(), reason: z.string().nullable(),
55
+ repeatCustomers: z.number().int(), spanDays: z.number(), minRepeatCustomers: z.number().int(), minSpanDays: z.number().int(),
56
+ predictedProfiles: z.number().int(), lastComputedAt: z.iso.datetime({ offset: true }).nullable(),
57
+ /** none: no model yet; prior_only: too little data to fit, population prior in use; fitted: model fitted on this workspace's customers */
58
+ sufficiency: z.enum(['none', 'prior_only', 'fitted']),
59
+ fit: PredictionFit.nullable(),
60
+ lastAttempt: z.object({ fittedAt: z.iso.datetime({ offset: true }), promoted: z.boolean(), note: z.string() }).nullable(),
61
+ });
62
+ export const RecommendationDto = z.object({ productId: z.string(), title: z.string().nullable(), score: z.number(), rank: z.number().int(), basis: z.enum(['co_purchase', 'popular']) });
63
+ export const RecommendationList = z.object({ profileId: z.uuid(), computedAt: z.iso.datetime({ offset: true }).nullable(), items: z.array(RecommendationDto) });
64
+ export const PredictionRunResult = z.object({ ran: z.boolean(), profiles: z.number().int(), reason: z.string().nullable() });
65
+ // ---- funnels and cohorts -----------------------------------------------------------------------------------------------
66
+ const DayStr = IsoDay;
67
+ export const FunnelQuery = z.object({
68
+ steps: z.array(z.string().min(1).max(128)).min(2).max(6),
69
+ from: DayStr, to: DayStr,
70
+ windowDays: z.number().int().min(1).max(365).default(30),
71
+ });
72
+ export const FunnelResult = z.object({ steps: z.array(z.object({ name: z.string(), profiles: z.number().int(), conversionFromPrevious: z.number().nullable(), conversionFromFirst: z.number().nullable() })) });
73
+ export const CohortQuery = z.object({
74
+ anchorEvent: z.string().min(1).max(128), returnEvent: z.string().min(1).max(128),
75
+ from: DayStr, to: DayStr, weeks: z.number().int().min(1).max(12).default(8),
76
+ });
77
+ export const CohortResult = z.object({ weeks: z.number().int(), cohorts: z.array(z.object({ cohort: z.string(), size: z.number().int(), retained: z.array(z.number().int()) })) });