@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,140 @@
1
+ import { z } from 'zod';
2
+ import { Channel, DateTimeIn, Id, PageQuery, Purpose, Timestamp, pageResult } from './common.js';
3
+ export const ExperimentKind = z.enum(['message_variant', 'path_split', 'holdout', 'send_time']);
4
+ export const ExperimentMethod = z.enum(['bayesian_beta', 'frequentist_ztest']);
5
+ /** Opens are accepted but flagged unreliable (Apple MPP, prefetch). */
6
+ export const PrimaryMetric = z.enum(['clicks', 'replies', 'conversions', 'revenue', 'opens']);
7
+ export const GuardrailMetric = z.enum(['unsubscribe', 'complaint', 'bounce']);
8
+ export const VariantWeight = z.object({ key: z.string().min(1).max(32), weight: z.number().int().min(0).max(1000) });
9
+ export const ExperimentMetricSpec = z.object({
10
+ primary: PrimaryMetric.default('clicks'),
11
+ /** Absolute increase in the rate (vs control) that counts as harm, e.g. 0.002 = +0.2 percentage points. */
12
+ guardrails: z.array(z.object({ metric: GuardrailMetric, threshold: z.number().min(0).max(1) })).max(3).default([]),
13
+ });
14
+ export const AutoSelect = z.object({
15
+ enabled: z.boolean().default(false),
16
+ afterHours: z.number().int().min(1).max(24 * 30).default(4),
17
+ pBest: z.number().min(0.5).max(0.999).default(0.95),
18
+ /** End the test at this moment even without a clear winner: the variant that is ahead wins. */
19
+ stopAt: z.iso.datetime({ offset: true }).optional(),
20
+ /** While running, send more of the new traffic to the variants that look better (each keeps a share to keep learning). */
21
+ shift: z.boolean().optional(),
22
+ /** Stop early and keep the control when a variant (with the minimum sample) is likely worse on a guardrail, even before `afterHours`. Off = guardrails only block a winner. */
23
+ stopOnGuardrail: z.boolean().optional(),
24
+ });
25
+ export const CreateExperimentBody = z.object({
26
+ name: z.string().trim().min(1).max(200),
27
+ kind: ExperimentKind.default('message_variant'),
28
+ scopeType: z.enum(['campaign', 'workflow', 'form', 'workspace']),
29
+ scopeId: Id.nullish(),
30
+ key: z.string().max(64).default(''),
31
+ variants: z.array(VariantWeight).min(2).max(10),
32
+ control: z.string().max(32).optional(),
33
+ metric: ExperimentMetricSpec.default({ primary: 'clicks', guardrails: [] }),
34
+ method: ExperimentMethod.default('bayesian_beta'),
35
+ autoSelect: AutoSelect.nullish(),
36
+ minRecipients: z.number().int().min(1).max(1_000_000).default(100),
37
+ minConversions: z.number().int().min(1).max(1_000_000).default(20),
38
+ });
39
+ export const GuardrailResult = z.object({ metric: GuardrailMetric, rate: z.number(), pWorse: z.number().nullable(), failed: z.boolean() });
40
+ export const ReportArm = z.object({
41
+ key: z.string(),
42
+ n: z.number().int(),
43
+ conversions: z.number().int(),
44
+ rate: z.number(),
45
+ ci: z.tuple([z.number(), z.number()]),
46
+ pBest: z.number(),
47
+ expectedLoss: z.number(),
48
+ pValue: z.number().nullable(),
49
+ guardrails: z.array(GuardrailResult),
50
+ /** Attributed orders and revenue (minor units) for this variant, whatever the test is measured by. */
51
+ orders: z.number().int().optional(),
52
+ revenueMinor: z.number().optional(),
53
+ });
54
+ export const ExperimentReport = z.object({
55
+ arms: z.array(ReportArm),
56
+ recommendation: z.object({ kind: z.enum(['winner', 'keep_running', 'no_winner']), key: z.string().nullable() }),
57
+ reason: z.string(),
58
+ method: ExperimentMethod,
59
+ metric: PrimaryMetric,
60
+ /** True only when the decision rule is met; the UI must not say "significant" otherwise. */
61
+ significant: z.boolean(),
62
+ sampleSufficient: z.boolean(),
63
+ /** Set when the metric is approximate (opens). */
64
+ caveat: z.string().nullable(),
65
+ });
66
+ const Row = z.looseObject({ id: Id });
67
+ export const ExperimentDto = Row;
68
+ export const ExperimentPage = pageResult(ExperimentDto);
69
+ export const ExperimentListQuery = PageQuery.extend({ status: z.enum(['draft', 'running', 'concluded']).optional(), scopeId: Id.optional() });
70
+ export const ConcludeBody = z.object({ winnerKey: z.string().min(1).max(32) });
71
+ export const HoldoutScope = z.enum(['workspace', 'campaign', 'workflow']);
72
+ export const HoldoutBody = z.object({
73
+ name: z.string().trim().min(1).max(200),
74
+ percent: z.number().min(0).max(50),
75
+ scopeType: HoldoutScope.default('workspace'),
76
+ scopeId: Id.nullish(),
77
+ });
78
+ export const HoldoutDto = Row;
79
+ /** Incrementality: who of the held-back vs treated people did `event` after being assigned; the sample floors gate any recommendation. */
80
+ export const HoldoutReportQuery = z.object({
81
+ event: z.string().min(1).max(128).default('purchase'),
82
+ minPeople: z.coerce.number().int().min(1).max(1_000_000).default(100),
83
+ minConversions: z.coerce.number().int().min(1).max(1_000_000).default(20),
84
+ });
85
+ export const HoldoutPage = pageResult(HoldoutDto);
86
+ /** Frequency caps (T6.3). `windowHours` instead of ms so the API stays human-sized. */
87
+ export const FrequencyCapInput = z.object({
88
+ channel: Channel,
89
+ purpose: Purpose,
90
+ max: z.number().int().min(1).max(1000),
91
+ windowHours: z.number().int().min(1).max(24 * 30),
92
+ });
93
+ export const SmartSending = z.object({ hours: z.number().int().min(1).max(24 * 14), action: z.enum(['defer', 'skip']).default('skip') });
94
+ export const FrequencySettingsBody = z.object({
95
+ scopeType: z.enum(['workspace', 'campaign', 'workflow']).default('workspace'),
96
+ scopeId: Id.nullish(),
97
+ caps: z.array(FrequencyCapInput).max(20).default([]),
98
+ smartSending: SmartSending.nullish(),
99
+ /**
100
+ * One cap over prospecting + marketing sends to the same person on a channel together (workspace: off by default). Omitted = keep the saved value.
101
+ * Workspace row: null or `off` = off. Campaign/workflow override: null = follow the workspace, `off` = no cross-purpose cap for it, a cap = its own.
102
+ */
103
+ crossPurpose: z.union([z.object({ max: z.number().int().min(1).max(1000), windowHours: z.number().int().min(1).max(24 * 30) }), z.literal('off')]).nullish(),
104
+ });
105
+ export const FrequencySettingsDto = Row;
106
+ export const FrequencySettingsList = z.object({ items: z.array(FrequencySettingsDto) });
107
+ /** `hour` is local to `timezone`: the profile's own zone, else the workspace's. */
108
+ export const SendTimeRecommendation = z.object({ profileId: Id, hour: z.number().int().min(0).max(23), source: z.enum(['profile', 'workspace', 'default']), timezone: z.string().optional(), at: Timestamp });
109
+ /** `new_subscribers`: people in the audience now who were not sent the original; `non_purchasers`: recipients with no attributed order. */
110
+ export const ResendBody = z.object({
111
+ to: z.enum(['non_openers', 'non_clickers', 'new_subscribers', 'non_purchasers']),
112
+ subject: z.string().trim().min(1).max(998),
113
+ at: DateTimeIn().optional(),
114
+ });
115
+ export const AbTestConfig = z.object({
116
+ /** 100 = everyone gets a variant and you pick the winner by hand (nothing is held back). */
117
+ testPercent: z.number().int().min(1).max(100).default(20),
118
+ metric: PrimaryMetric.default('clicks'),
119
+ waitHours: z.number().int().min(1).max(48).default(4),
120
+ auto: z.boolean().default(true),
121
+ method: ExperimentMethod.default('bayesian_beta'),
122
+ /** Auto mode: chance of being best the leader needs before it is rolled out (unset = 0.95). */
123
+ confidence: z.number().min(0.5).max(0.999).optional(),
124
+ /** Guardrail: a variant whose unsubscribe/complaint/bounce rate is this much (absolute share) above control fails (unset = 0.005). */
125
+ guardrail: z.number().min(0.001).max(0.1).optional(),
126
+ });
127
+ export const RolloutBody = z.object({ winnerKey: z.string().min(1).max(32).optional() });
128
+ /** Multivariate: every combination of the listed values becomes one variant (at most 8). An empty dimension keeps the base value. */
129
+ export const MultivariateGridBody = z.object({
130
+ templateVersionIds: z.array(Id).max(8).default([]),
131
+ subjects: z.array(z.string().trim().min(1).max(998)).max(8).default([]),
132
+ fromNames: z.array(z.string().trim().min(1).max(200)).max(8).default([]),
133
+ previewTexts: z.array(z.string().trim().min(1).max(300)).max(8).default([]),
134
+ /** Used where `templateVersionIds` is empty. */
135
+ baseTemplateVersionId: Id,
136
+ });
137
+ export const MultivariateGridResult = z.object({
138
+ combinations: z.number().int(),
139
+ variants: z.array(z.object({ key: z.string(), templateVersionId: z.string(), subject: z.string().nullable(), fromName: z.string().nullable(), previewText: z.string().nullable() })),
140
+ });