@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.
- package/LICENSE +9 -0
- package/README.md +12 -2
- package/dist/contracts/analytics.d.ts +405 -0
- package/dist/contracts/analytics.js +77 -0
- package/dist/contracts/auth.d.ts +363 -0
- package/dist/contracts/auth.js +130 -0
- package/dist/contracts/billing.d.ts +143 -0
- package/dist/contracts/billing.js +32 -0
- package/dist/contracts/campaigns.d.ts +915 -0
- package/dist/contracts/campaigns.js +276 -0
- package/dist/contracts/common.d.ts +57 -0
- package/dist/contracts/common.js +35 -0
- package/dist/contracts/connectors.d.ts +179 -0
- package/dist/contracts/connectors.js +46 -0
- package/dist/contracts/consent.d.ts +628 -0
- package/dist/contracts/consent.js +194 -0
- package/dist/contracts/content-blocks.d.ts +165 -0
- package/dist/contracts/content-blocks.js +62 -0
- package/dist/contracts/content-library.d.ts +347 -0
- package/dist/contracts/content-library.js +52 -0
- package/dist/contracts/content.d.ts +955 -0
- package/dist/contracts/content.js +194 -0
- package/dist/contracts/delivery.d.ts +602 -0
- package/dist/contracts/delivery.js +220 -0
- package/dist/contracts/events.d.ts +514 -0
- package/dist/contracts/events.js +180 -0
- package/dist/contracts/experiments.d.ts +378 -0
- package/dist/contracts/experiments.js +140 -0
- package/dist/contracts/identity.d.ts +761 -0
- package/dist/contracts/identity.js +226 -0
- package/dist/contracts/index.d.ts +15 -0
- package/dist/contracts/index.js +15 -0
- package/dist/contracts/integrations.d.ts +445 -0
- package/dist/contracts/integrations.js +139 -0
- package/dist/contracts/leads.d.ts +733 -0
- package/dist/contracts/leads.js +125 -0
- package/dist/contracts/metrics.d.ts +465 -0
- package/dist/contracts/metrics.js +96 -0
- package/dist/contracts/outbound.d.ts +15535 -0
- package/dist/contracts/outbound.js +432 -0
- package/dist/contracts/pickers.d.ts +12 -0
- package/dist/contracts/pickers.js +20 -0
- package/dist/contracts/platform-admin.d.ts +244 -0
- package/dist/contracts/platform-admin.js +98 -0
- package/dist/contracts/postcards.d.ts +79 -0
- package/dist/contracts/postcards.js +29 -0
- package/dist/contracts/push.d.ts +530 -0
- package/dist/contracts/push.js +102 -0
- package/dist/contracts/rcs.d.ts +39 -0
- package/dist/contracts/rcs.js +19 -0
- package/dist/contracts/segments.d.ts +3187 -0
- package/dist/contracts/segments.js +421 -0
- package/dist/contracts/workflow-nodes.d.ts +2130 -0
- package/dist/contracts/workflow-nodes.js +346 -0
- package/dist/contracts/workflows.d.ts +46811 -0
- package/dist/contracts/workflows.js +350 -0
- package/dist/contracts/x10-platform.d.ts +2603 -0
- package/dist/contracts/x10-platform.js +129 -0
- package/dist/http.d.ts +30 -0
- package/dist/http.js +65 -0
- package/dist/index.d.ts +11631 -0
- package/dist/index.js +63 -0
- package/dist/platform.d.ts +163 -0
- package/dist/platform.js +40 -0
- package/dist/resources.d.ts +1338 -0
- package/dist/resources.js +56 -0
- package/dist/signature.d.ts +5 -0
- package/dist/signature.js +19 -0
- package/dist/x10.d.ts +1608 -0
- package/dist/x10.js +66 -0
- package/dist/z10.d.ts +256 -0
- package/dist/z10.js +46 -0
- package/package.json +40 -4
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { BlockDoc } from './content-blocks.js';
|
|
3
|
+
import { Channel, DateTimeIn, Id, PageQuery, Purpose, ReplyToList, Timestamp, pageResult } from './common.js';
|
|
4
|
+
import { PushExtras } from './push.js';
|
|
5
|
+
import { PostcardDesign } from './postcards.js';
|
|
6
|
+
export const MessageStatus = z.enum([
|
|
7
|
+
'queued', 'deferred', 'blocked', 'sending', 'accepted', 'delivered', 'bounced', 'complained', 'failed', 'cancelled', 'needs_reconcile',
|
|
8
|
+
]);
|
|
9
|
+
export const MessageTag = z.string().min(1).max(50).regex(/^[\w.:-]+$/, 'tags use letters, digits and . _ : -');
|
|
10
|
+
export const MessageTags = z.array(MessageTag).max(10);
|
|
11
|
+
export const MessageMetadata = z.record(z.string().min(1).max(64), z.string().max(255)).refine((m) => Object.keys(m).length <= 10, { message: 'At most 10 metadata keys' });
|
|
12
|
+
/** Attachment already stored (key into object storage); the API converts base64 uploads into these. */
|
|
13
|
+
export const StoredAttachment = z.object({ filename: z.string().min(1).max(255), contentType: z.string().max(200), key: z.string().min(1).max(500), size: z.number().int().nonnegative(), cid: z.string().max(200).optional() });
|
|
14
|
+
/** Beyond X-*, only these informational headers may be set; transport, threading, auth and unsubscribe headers stay under the pipeline's control. */
|
|
15
|
+
export const ALLOWED_PLAIN_HEADERS = ['list-id', 'list-help', 'list-owner', 'list-archive', 'list-post', 'precedence', 'importance', 'sensitivity', 'organization', 'keywords', 'comments', 'content-language'];
|
|
16
|
+
const headerAllowed = (k) => (/^X-[\w-]{1,100}$/i.test(k) && !/^x-(hermetica|sg|mailgun|ses|pm)-/i.test(k)) || ALLOWED_PLAIN_HEADERS.includes(k.toLowerCase());
|
|
17
|
+
export const CustomHeaders = z.record(z.string().refine(headerAllowed, 'custom headers must start with X- (not a provider/internal prefix) or be one of: ' + ALLOWED_PLAIN_HEADERS.join(', ')), z.string().max(998).regex(/^[^\r\n]*$/)).refine((m) => Object.keys(m).length <= 20);
|
|
18
|
+
/** How merge tags in the content are written: Liquid `{{ vars.x }}` (default), Mailchimp `*|X|*`, or Handlebars-style `{{x}}` (vars at the top level). */
|
|
19
|
+
export const MergeLanguage = z.enum(['liquid', 'mailchimp', 'handlebars']);
|
|
20
|
+
/** `mc:edit="name"` region overrides for one send (Mandrill send-template `template_content`). */
|
|
21
|
+
export const TxTemplateContent = z.array(z.object({ name: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/), content: z.string().max(512_000) })).max(50);
|
|
22
|
+
export const SendSource = z.object({
|
|
23
|
+
kind: z.enum(['campaign', 'workflow', 'sequence', 'api']),
|
|
24
|
+
id: z.string().min(1).max(128),
|
|
25
|
+
stepKey: z.string().max(128).optional(),
|
|
26
|
+
});
|
|
27
|
+
/** Inline content is for internal callers (workflows/tests); the public API sends stored templates only. */
|
|
28
|
+
export const InlineContent = z.object({
|
|
29
|
+
subject: z.string().max(998).optional(),
|
|
30
|
+
text: z.string().min(1).max(100_000),
|
|
31
|
+
html: z.string().max(512_000).optional(),
|
|
32
|
+
/** A block design sent in place of `html` (Manual review edits of block-built emails keep the design). */
|
|
33
|
+
doc: BlockDoc.optional(),
|
|
34
|
+
});
|
|
35
|
+
/** 01-architecture §6 input. workspaceId comes from the caller's ctx, never from the payload. */
|
|
36
|
+
export const SendRequest = z.object({
|
|
37
|
+
purpose: Purpose,
|
|
38
|
+
channel: Channel,
|
|
39
|
+
profileId: Id,
|
|
40
|
+
templateId: Id.optional(),
|
|
41
|
+
versionId: Id.optional(),
|
|
42
|
+
inline: InlineContent.optional(),
|
|
43
|
+
route: z.object({ connectionId: Id.optional(), poolId: Id.optional(), routePolicyId: Id.optional() }),
|
|
44
|
+
source: SendSource,
|
|
45
|
+
/** Push only: image, deep link, data payload, badge, sound, TTL and per-platform overrides (title = subject, body = text). */
|
|
46
|
+
push: PushExtras.optional(),
|
|
47
|
+
idempotencyKey: z.string().min(1).max(200),
|
|
48
|
+
topicId: Id.optional(),
|
|
49
|
+
scheduledFor: DateTimeIn().optional(),
|
|
50
|
+
vars: z.record(z.string(), z.unknown()).optional(),
|
|
51
|
+
tracking: z.object({ clicks: z.boolean().optional(), opens: z.boolean().optional() }).optional(),
|
|
52
|
+
/** Campaign-level UTM defaults, appended to http(s) links that carry no utm_* yet. */
|
|
53
|
+
utm: z.record(z.string(), z.string()).optional(),
|
|
54
|
+
/** Campaign variant overrides; subject is rendered as liquid like the template's own. */
|
|
55
|
+
subjectOverride: z.string().max(998).optional(),
|
|
56
|
+
fromNameOverride: z.string().max(200).optional(),
|
|
57
|
+
/** Liquid template for the recipient's display name in the To header (for example `{{ first_name }} {{ last_name }}`); empty result = bare address. */
|
|
58
|
+
toNameTemplate: z.string().max(200).optional(),
|
|
59
|
+
/** Preview text (preheader) override, rendered as liquid like the template's own. */
|
|
60
|
+
preheaderOverride: z.string().max(300).optional(),
|
|
61
|
+
/** Reply in the thread of the latest message this source sent to the profile at that step (In-Reply-To/References, `Re:` subject). */
|
|
62
|
+
replyToStep: z.string().max(128).optional(),
|
|
63
|
+
/** Transactional threading: reply to this earlier message job of the same profile. */
|
|
64
|
+
inReplyToJobId: Id.optional(),
|
|
65
|
+
/** Answer a received email (inbound message id) of the same profile in its thread: In-Reply-To / References its Message-ID, from the mailbox it came in on. */
|
|
66
|
+
inReplyToInboundId: Id.optional(),
|
|
67
|
+
/** Outreach email without an HTML part or open pixel; `unsubscribeText` words the footer unsubscribe link. */
|
|
68
|
+
plainText: z.boolean().optional(),
|
|
69
|
+
unsubscribeText: z.string().max(120).optional(),
|
|
70
|
+
/** `{a|b}` wording: `random` per send (default) or `sequential` (rotate evenly across the sends of a source step). */
|
|
71
|
+
spintaxMode: z.enum(['random', 'sequential']).optional(),
|
|
72
|
+
/** ESP matching for this send's rotated route: a sequence's own choice; unset = the workspace's `matchRecipientProvider`. */
|
|
73
|
+
matchProvider: z.boolean().optional(),
|
|
74
|
+
/** Experiment/A-B variant this send belongs to; stamped on the job so rollups group by variant. */
|
|
75
|
+
variantKey: z.string().max(32).optional(),
|
|
76
|
+
/** Transactional envelope (B1/B2): searchable tags and metadata, stored attachments, X- headers, verified from/reply-to override. */
|
|
77
|
+
tags: MessageTags.optional(),
|
|
78
|
+
metadata: MessageMetadata.optional(),
|
|
79
|
+
attachments: z.array(StoredAttachment).max(10).optional(),
|
|
80
|
+
/** Per-recipient files: `ref` is the profile attribute's value (an https URL or an asset id), fetched at dispatch. Set from the source's send options. */
|
|
81
|
+
profileFiles: z.array(z.object({ name: z.string().max(100), ref: z.string().max(2048) })).max(5).optional(),
|
|
82
|
+
customHeaders: CustomHeaders.optional(),
|
|
83
|
+
senderIdentityId: Id.optional(),
|
|
84
|
+
/** Prefer the verified sender identity with this from-address (a list default). Never creates or verifies a sender: if none of the route's verified senders match, it is ignored. */
|
|
85
|
+
fromEmailPreference: z.string().email().max(320).optional(),
|
|
86
|
+
replyTo: ReplyToList.optional(),
|
|
87
|
+
/** Transactional / operational: also add RFC 8058 one-click unsubscribe headers (marketing and prospecting always have them). */
|
|
88
|
+
oneClickUnsubscribe: z.boolean().optional(),
|
|
89
|
+
/** Footer postal address for this message; wins over the brand kit and workspace address. */
|
|
90
|
+
footerAddress: z.string().max(600).optional(),
|
|
91
|
+
/** SMS only: public https image URLs sent as MMS media (providers without MMS ignore them). */
|
|
92
|
+
mediaUrls: z.array(z.url()).max(10).optional(),
|
|
93
|
+
/** Extra recipients (email only). Suppressed addresses are dropped at dispatch; providers without cc/bcc support fail the send cleanly. */
|
|
94
|
+
cc: z.array(z.string().email().max(320)).max(10).optional(),
|
|
95
|
+
bcc: z.array(z.string().email().max(320)).max(10).optional(),
|
|
96
|
+
/** Transactional email to an address not yet on the profile (address-change confirmation). Same suppression gates apply to this address; refused for any other purpose. */
|
|
97
|
+
destinationOverride: z.string().email().max(320).optional(),
|
|
98
|
+
/** Set by requestSend from a restricted API key; dispatch re-applies it so a re-route never leaves the allowed senders. */
|
|
99
|
+
senderScope: z.object({ connections: z.array(z.string()).optional(), domains: z.array(z.string()).optional() }).optional(),
|
|
100
|
+
/** Postcard only: the front/back design and size; postcards carry no template or inline body. */
|
|
101
|
+
postcard: PostcardDesign.optional(),
|
|
102
|
+
/** Transactional (Mandrill) options, see TxSendOptions: CSS inlining, query-string-free click reporting, a visible To list, no stored body copy. */
|
|
103
|
+
inlineCss: z.boolean().optional(),
|
|
104
|
+
urlStripQs: z.boolean().optional(),
|
|
105
|
+
displayTo: z.array(z.string().email().max(320)).max(100).optional(),
|
|
106
|
+
storeContent: z.boolean().optional(),
|
|
107
|
+
/** utm defaults go only to links on these domains (Mandrill google_analytics_domains). */
|
|
108
|
+
utmDomains: z.array(z.string().max(253)).max(50).optional(),
|
|
109
|
+
mergeLanguage: MergeLanguage.optional(),
|
|
110
|
+
templateContent: TxTemplateContent.optional(),
|
|
111
|
+
important: z.boolean().optional(),
|
|
112
|
+
/** Per-message branded hosts, already checked as verified in this workspace. */
|
|
113
|
+
trackingDomain: z.string().max(253).optional(),
|
|
114
|
+
signingDomain: z.string().max(253).optional(),
|
|
115
|
+
returnPathDomain: z.string().max(253).optional(),
|
|
116
|
+
/** send-raw: object-storage key of the MIME message relayed as given (headers we own are replaced); rendering only fills the log copy. */
|
|
117
|
+
rawMimeKey: z.string().max(500).optional(),
|
|
118
|
+
/** false = unknown variables render empty instead of blocking the send (required links such as unsubscribe still block). Default strict. */
|
|
119
|
+
strictLiquid: z.boolean().optional(),
|
|
120
|
+
/** The list a campaign send goes to: its default mailer is tried after the request's own route. */
|
|
121
|
+
listId: Id.optional(),
|
|
122
|
+
/** Set by the server only, on test sends to the operator's own seed addresses: skips quiet hours (consent, suppression and caps still apply). */
|
|
123
|
+
testSend: z.boolean().optional(),
|
|
124
|
+
}).refine((r) => (r.channel === 'postcard' ? !!r.postcard && !r.templateId && !r.inline : Boolean(r.templateId) !== Boolean(r.inline)), { message: 'Provide exactly one of templateId or inline (postcards: the postcard design only)' })
|
|
125
|
+
.refine((r) => Boolean(r.route.connectionId || r.route.poolId || r.route.routePolicyId), { message: 'No route: pick a sending connection, pool or route policy (route.connectionId, route.poolId or route.routePolicyId)', path: ['route'] });
|
|
126
|
+
export const SendOutcome = z.object({
|
|
127
|
+
jobId: Id,
|
|
128
|
+
status: z.enum(['queued', 'blocked', 'deferred', 'duplicate']),
|
|
129
|
+
reason: z.string().optional(),
|
|
130
|
+
/** `render_error`: what failed, e.g. the merge variable the send's vars leave unset. */
|
|
131
|
+
detail: z.string().optional(),
|
|
132
|
+
});
|
|
133
|
+
/** POST /v1/messages/send: stored templates only, source is always `api`. */
|
|
134
|
+
export const SendApiBody = z.object({
|
|
135
|
+
purpose: Purpose,
|
|
136
|
+
channel: Channel,
|
|
137
|
+
profileId: Id,
|
|
138
|
+
templateId: Id,
|
|
139
|
+
versionId: Id.optional(),
|
|
140
|
+
route: SendRequest.shape.route,
|
|
141
|
+
/** Either this or the `Idempotency-Key` header (header wins when the body omits it; both must agree). */
|
|
142
|
+
idempotencyKey: z.string().min(1).max(200).optional(),
|
|
143
|
+
topicId: Id.optional(),
|
|
144
|
+
scheduledFor: DateTimeIn().optional(),
|
|
145
|
+
vars: z.record(z.string(), z.unknown()).optional(),
|
|
146
|
+
});
|
|
147
|
+
export const MessageListQuery = PageQuery.extend({
|
|
148
|
+
/** Sort key; `order` gives the direction. Default createdAt. */
|
|
149
|
+
sort: z.enum(['createdAt', 'sentAt', 'status', 'destination']).optional(),
|
|
150
|
+
profileId: Id.optional(),
|
|
151
|
+
status: MessageStatus.optional(),
|
|
152
|
+
sourceKind: SendSource.shape.kind.optional(),
|
|
153
|
+
sourceId: z.string().max(128).optional(),
|
|
154
|
+
/** Recipient address / number, substring match; comma separated values match any. */
|
|
155
|
+
q: z.string().max(200).optional(),
|
|
156
|
+
/** Messages to everyone linked to this custom object (a "group"), e.g. objectType=company&objectId=<id>. */
|
|
157
|
+
objectType: z.string().max(64).optional(),
|
|
158
|
+
objectId: Id.optional(),
|
|
159
|
+
/** Oldest first instead of newest first. */
|
|
160
|
+
order: z.enum(['asc', 'desc']).default('desc'),
|
|
161
|
+
tag: MessageTag.optional(),
|
|
162
|
+
/** `key:value` pairs, repeated or comma separated. */
|
|
163
|
+
metadata: z.string().max(500).optional(),
|
|
164
|
+
senderIdentityId: Id.optional(),
|
|
165
|
+
templateId: Id.optional(),
|
|
166
|
+
channel: Channel.optional(),
|
|
167
|
+
from: DateTimeIn().optional(),
|
|
168
|
+
to: DateTimeIn().optional(),
|
|
169
|
+
/** Event / trigger properties passed as send vars: `path:value` pairs (dots walk objects, e.g. `trigger.orderId:123`), comma separated; all must match. */
|
|
170
|
+
vars: z.string().max(500).optional(),
|
|
171
|
+
/** Only messages that have at least one event of this kind (open, click, delivered, hard_bounce, ...). */
|
|
172
|
+
eventKind: z.string().max(40).optional(),
|
|
173
|
+
/** Only messages of this app: an `app:<slug>` tag or `metadata.app`. A key bound to an app always gets its own. */
|
|
174
|
+
app: z.string().max(63).optional(),
|
|
175
|
+
});
|
|
176
|
+
/** One policy stage of the send pipeline (destination, eligibility, caps, route, render, reserve, send, events). */
|
|
177
|
+
export const DecisionEntry = z.object({ stage: z.string(), outcome: z.enum(['allow', 'block', 'defer']), reason: z.string().nullish(), liaId: z.string().nullish(), at: Timestamp.nullish() });
|
|
178
|
+
export const MessageJobDto = z.object({
|
|
179
|
+
id: Id,
|
|
180
|
+
idempotencyKey: z.string(),
|
|
181
|
+
purpose: Purpose,
|
|
182
|
+
channel: Channel,
|
|
183
|
+
profileId: Id,
|
|
184
|
+
/** Resolved address / phone number the message went (or would go) to. */
|
|
185
|
+
destination: z.string().nullable(),
|
|
186
|
+
connectionId: Id.nullable(),
|
|
187
|
+
senderIdentityId: Id.nullable(),
|
|
188
|
+
sourceKind: SendSource.shape.kind,
|
|
189
|
+
sourceId: z.string(),
|
|
190
|
+
stepKey: z.string().nullable(),
|
|
191
|
+
templateVersionId: Id.nullable(),
|
|
192
|
+
variantKey: z.string().nullable(),
|
|
193
|
+
status: MessageStatus,
|
|
194
|
+
blockReason: z.string().nullable(),
|
|
195
|
+
errorClass: z.string().nullable(),
|
|
196
|
+
decisionLog: z.array(DecisionEntry),
|
|
197
|
+
scheduledFor: Timestamp.nullable(),
|
|
198
|
+
sentAt: Timestamp.nullable(),
|
|
199
|
+
providerMessageId: z.string().nullable(),
|
|
200
|
+
subject: z.string().nullable(),
|
|
201
|
+
tags: z.array(z.string()),
|
|
202
|
+
metadata: z.record(z.string(), z.string()).nullable(),
|
|
203
|
+
createdAt: Timestamp,
|
|
204
|
+
updatedAt: Timestamp,
|
|
205
|
+
});
|
|
206
|
+
export const MessageJobPage = pageResult(MessageJobDto);
|
|
207
|
+
export const MessageAttemptDto = z.object({
|
|
208
|
+
id: Id, jobId: Id, n: z.number().int(), status: z.string(), errorClass: z.string().nullable(), startedAt: Timestamp, finishedAt: Timestamp.nullable(),
|
|
209
|
+
});
|
|
210
|
+
export const MessageEventDto = z.object({
|
|
211
|
+
id: Id, jobId: Id, profileId: Id, kind: z.string(), source: z.string(), connectionId: Id.nullable(), url: z.string().nullable(), ua: z.string().nullable(),
|
|
212
|
+
isMachine: z.boolean(), occurredAt: Timestamp,
|
|
213
|
+
});
|
|
214
|
+
export const MessageDetailDto = z.object({
|
|
215
|
+
job: MessageJobDto,
|
|
216
|
+
attempts: z.array(MessageAttemptDto),
|
|
217
|
+
events: z.array(MessageEventDto),
|
|
218
|
+
decisionLog: z.array(DecisionEntry),
|
|
219
|
+
});
|
|
220
|
+
export const RetryOutcome = z.object({ jobId: Id, status: z.string(), at: Timestamp });
|