@marlinjai/mail-sdk 0.2.0 → 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 (5) hide show
  1. package/dist/index.d.mts +64 -26
  2. package/dist/index.d.ts +64 -26
  3. package/dist/index.js +20 -3
  4. package/dist/index.mjs +22 -3
  5. package/package.json +2 -2
package/dist/index.d.mts CHANGED
@@ -42,6 +42,16 @@ interface RequestOpts {
42
42
  * status and request id. An exception thrown here propagates to the caller.
43
43
  */
44
44
  onResponse?: (meta: ResponseMeta) => void;
45
+ /**
46
+ * The person the caller's application is acting for, when the workspace API
47
+ * key is shared by everybody who uses that application: a name or an email
48
+ * address, sent as `ON_BEHALF_OF_HEADER`. The service records it on the
49
+ * audit entry as what the application reported, never verified; it changes
50
+ * nothing about what the key may do. Trimmed; empty is not sent; longer than
51
+ * `ON_BEHALF_OF_MAX_LENGTH` throws before any request is made. Ignored by
52
+ * the service on a dashboard client's calls.
53
+ */
54
+ onBehalfOf?: string;
45
55
  }
46
56
  interface ExecuteArgs<K extends OperationId> {
47
57
  params?: RouteParams<K>;
@@ -68,6 +78,13 @@ interface ExportedFile {
68
78
  }
69
79
  /** The `filename` of a `Content-Disposition` value (the `filename*` UTF-8 form first). */
70
80
  declare function dispositionFilename(value: string | null): string | null;
81
+ interface MultipartArgs<K extends OperationId> {
82
+ params?: RouteParams<K>;
83
+ file: Blob;
84
+ filename?: string;
85
+ /** For routes whose multipart form carries a second JSON field (e.g. `imports.create`). */
86
+ json?: unknown;
87
+ }
71
88
 
72
89
  /**
73
90
  * Namespaced, hand-written wrappers over `execute`/`executeMultipart`. Every
@@ -97,6 +114,8 @@ declare function createNamespaces(config: CoreConfig): {
97
114
  default_locale: string;
98
115
  locales: string[];
99
116
  tracking_enabled: boolean;
117
+ allowed_asset_hosts: string[];
118
+ merge_defaults: Record<string, string | number | boolean>;
100
119
  default_timezone: string | null;
101
120
  };
102
121
  company_id: string | null;
@@ -113,6 +132,8 @@ declare function createNamespaces(config: CoreConfig): {
113
132
  default_locale: string;
114
133
  locales: string[];
115
134
  tracking_enabled: boolean;
135
+ allowed_asset_hosts: string[];
136
+ merge_defaults: Record<string, string | number | boolean>;
116
137
  default_timezone: string | null;
117
138
  };
118
139
  company_id: string | null;
@@ -133,6 +154,8 @@ declare function createNamespaces(config: CoreConfig): {
133
154
  default_locale: string;
134
155
  locales: string[];
135
156
  tracking_enabled: boolean;
157
+ allowed_asset_hosts: string[];
158
+ merge_defaults: Record<string, string | number | boolean>;
136
159
  default_timezone: string | null;
137
160
  };
138
161
  company_id: string | null;
@@ -148,6 +171,8 @@ declare function createNamespaces(config: CoreConfig): {
148
171
  default_locale: string;
149
172
  locales: string[];
150
173
  tracking_enabled: boolean;
174
+ allowed_asset_hosts: string[];
175
+ merge_defaults: Record<string, string | number | boolean>;
151
176
  default_timezone: string | null;
152
177
  };
153
178
  company_id: string | null;
@@ -168,6 +193,8 @@ declare function createNamespaces(config: CoreConfig): {
168
193
  default_locale: string;
169
194
  locales: string[];
170
195
  tracking_enabled: boolean;
196
+ allowed_asset_hosts: string[];
197
+ merge_defaults: Record<string, string | number | boolean>;
171
198
  default_timezone: string | null;
172
199
  };
173
200
  company_id: string | null;
@@ -276,6 +303,8 @@ declare function createNamespaces(config: CoreConfig): {
276
303
  default_locale: string;
277
304
  locales: string[];
278
305
  tracking_enabled: boolean;
306
+ allowed_asset_hosts: string[];
307
+ merge_defaults: Record<string, string | number | boolean>;
279
308
  default_timezone: string | null;
280
309
  };
281
310
  company_id: string | null;
@@ -325,7 +354,7 @@ declare function createNamespaces(config: CoreConfig): {
325
354
  id: string;
326
355
  details: Record<string, unknown>;
327
356
  created_at: string;
328
- action: "workspace.created" | "workspace.updated" | "workspace.company_changed" | "member.added" | "member.role_changed" | "member.removed" | "member.invited" | "invite.revoked" | "api_key.created" | "api_key.revoked" | "provider.created" | "provider.updated" | "provider.deleted" | "provider.events_registered" | "provider.events_secret_set" | "provider.bounces_halted" | "provider.anomaly_cleared" | "topic.created" | "topic.updated" | "template.created" | "template.updated" | "template.deleted" | "saved_section.created" | "saved_section.updated" | "saved_section.deleted" | "asset.uploaded" | "asset.imported" | "contact.erased" | "suppression.created" | "suppression.deleted" | "mailing.created" | "mailing.sent" | "mailing.paused" | "mailing.resumed" | "mailing.cancelled" | "mailing.retried" | "webhook.created" | "webhook.updated" | "webhook.deleted" | "webhook.secret_rotated" | "webhook.redelivered" | "contact.unsubscribed" | "tag.created" | "tag.deleted" | "tag.assigned" | "tag.unassigned" | "contact_property.created" | "contact_property.deleted" | "segment.created" | "segment.updated" | "segment.deleted" | "signup_form.created" | "signup_form.updated" | "signup_form.deleted" | "contact.subscribed" | "import.created" | "import.mapped" | "import.committed" | "import.cancelled" | "import.finished" | "mailing.scheduled" | "mailing.unscheduled" | "mailing.schedule_failed" | "mailing.ab_test_updated" | "mailing.ab_winner_selected" | "tracking.updated" | "billing.checkout_started" | "billing.subscription_changed" | "billing.exemption_changed" | "automation.created" | "automation.updated" | "automation.published" | "automation.paused" | "automation.resumed" | "automation.archived" | "automation.deleted" | "automation.duplicated" | "automation.enrolled" | "automation.run_ended" | "event.recorded";
357
+ action: "workspace.created" | "workspace.updated" | "workspace.company_changed" | "member.added" | "member.role_changed" | "member.removed" | "member.invited" | "invite.revoked" | "api_key.created" | "api_key.revoked" | "provider.created" | "provider.updated" | "provider.deleted" | "provider.events_registered" | "provider.events_secret_set" | "provider.bounces_halted" | "provider.anomaly_cleared" | "topic.created" | "topic.updated" | "topic.deleted" | "template.created" | "template.updated" | "template.deleted" | "saved_section.created" | "saved_section.updated" | "saved_section.deleted" | "asset.uploaded" | "asset.imported" | "contact.erased" | "suppression.created" | "suppression.deleted" | "mailing.created" | "mailing.sent" | "mailing.paused" | "mailing.resumed" | "mailing.cancelled" | "mailing.retried" | "webhook.created" | "webhook.updated" | "webhook.deleted" | "webhook.secret_rotated" | "webhook.redelivered" | "contact.unsubscribed" | "tag.created" | "tag.deleted" | "tag.assigned" | "tag.unassigned" | "contact_property.created" | "contact_property.deleted" | "segment.created" | "segment.updated" | "segment.deleted" | "signup_form.created" | "signup_form.updated" | "signup_form.deleted" | "contact.subscribed" | "import.created" | "import.mapped" | "import.committed" | "import.cancelled" | "import.finished" | "mailing.scheduled" | "mailing.unscheduled" | "mailing.schedule_failed" | "mailing.ab_test_updated" | "mailing.ab_winner_selected" | "tracking.updated" | "billing.checkout_started" | "billing.subscription_changed" | "billing.exemption_changed" | "automation.created" | "automation.updated" | "automation.published" | "automation.paused" | "automation.resumed" | "automation.archived" | "automation.deleted" | "automation.duplicated" | "automation.enrolled" | "automation.run_ended" | "event.recorded";
329
358
  actor: {
330
359
  type: "member";
331
360
  subject: string;
@@ -333,6 +362,7 @@ declare function createNamespaces(config: CoreConfig): {
333
362
  } | {
334
363
  type: "api_key";
335
364
  api_key_id: string;
365
+ on_behalf_of?: string | undefined;
336
366
  } | {
337
367
  type: "system";
338
368
  reason: string;
@@ -609,7 +639,9 @@ declare function createNamespaces(config: CoreConfig): {
609
639
  /**
610
640
  * Copies a remote image into the workspace's assets and answers with the
611
641
  * new asset, whose `url` is the service's own. The workspace setting
612
- * `asset_policy: 'service_only'` accepts only such addresses in a mail.
642
+ * `asset_policy: 'service_only'` accepts only such addresses in a mail,
643
+ * plus any host in `settings.allowed_asset_hosts` (the workspace's own
644
+ * website, typically), whose images need no copy.
613
645
  */
614
646
  import: (body: RouteBody<"assets.import">, opts?: RequestOpts) => Promise<{
615
647
  id: string;
@@ -1118,6 +1150,10 @@ declare function createNamespaces(config: CoreConfig): {
1118
1150
  description: string | null;
1119
1151
  }>;
1120
1152
  }>;
1153
+ /** Refused with `conflict` while a mailing or an automation step still uses the topic. */
1154
+ delete: (id: string, opts?: RequestOpts) => Promise<{
1155
+ ok: true;
1156
+ }>;
1121
1157
  };
1122
1158
  contacts: {
1123
1159
  upsert: (body: RouteBody<"contacts.upsert">, opts?: RequestOpts) => Promise<{
@@ -1257,7 +1293,7 @@ declare function createNamespaces(config: CoreConfig): {
1257
1293
  subject: string;
1258
1294
  kind: "broadcast" | "automation" | "notification";
1259
1295
  preheader: string | null;
1260
- topic: string;
1296
+ topic: string | null;
1261
1297
  provider_id: string;
1262
1298
  counts: {
1263
1299
  sending: number;
@@ -1307,7 +1343,7 @@ declare function createNamespaces(config: CoreConfig): {
1307
1343
  subject: string;
1308
1344
  kind: "broadcast" | "automation" | "notification";
1309
1345
  preheader: string | null;
1310
- topic: string;
1346
+ topic: string | null;
1311
1347
  provider_id: string;
1312
1348
  counts: {
1313
1349
  sending: number;
@@ -1355,7 +1391,7 @@ declare function createNamespaces(config: CoreConfig): {
1355
1391
  subject: string;
1356
1392
  kind: "broadcast" | "automation" | "notification";
1357
1393
  preheader: string | null;
1358
- topic: string;
1394
+ topic: string | null;
1359
1395
  provider_id: string;
1360
1396
  counts: {
1361
1397
  sending: number;
@@ -1405,7 +1441,7 @@ declare function createNamespaces(config: CoreConfig): {
1405
1441
  subject: string;
1406
1442
  kind: "broadcast" | "automation" | "notification";
1407
1443
  preheader: string | null;
1408
- topic: string;
1444
+ topic: string | null;
1409
1445
  provider_id: string;
1410
1446
  counts: {
1411
1447
  sending: number;
@@ -1482,7 +1518,7 @@ declare function createNamespaces(config: CoreConfig): {
1482
1518
  subject: string;
1483
1519
  kind: "broadcast" | "automation" | "notification";
1484
1520
  preheader: string | null;
1485
- topic: string;
1521
+ topic: string | null;
1486
1522
  provider_id: string;
1487
1523
  counts: {
1488
1524
  sending: number;
@@ -1530,7 +1566,7 @@ declare function createNamespaces(config: CoreConfig): {
1530
1566
  subject: string;
1531
1567
  kind: "broadcast" | "automation" | "notification";
1532
1568
  preheader: string | null;
1533
- topic: string;
1569
+ topic: string | null;
1534
1570
  provider_id: string;
1535
1571
  counts: {
1536
1572
  sending: number;
@@ -1578,7 +1614,7 @@ declare function createNamespaces(config: CoreConfig): {
1578
1614
  subject: string;
1579
1615
  kind: "broadcast" | "automation" | "notification";
1580
1616
  preheader: string | null;
1581
- topic: string;
1617
+ topic: string | null;
1582
1618
  provider_id: string;
1583
1619
  counts: {
1584
1620
  sending: number;
@@ -1626,7 +1662,7 @@ declare function createNamespaces(config: CoreConfig): {
1626
1662
  subject: string;
1627
1663
  kind: "broadcast" | "automation" | "notification";
1628
1664
  preheader: string | null;
1629
- topic: string;
1665
+ topic: string | null;
1630
1666
  provider_id: string;
1631
1667
  counts: {
1632
1668
  sending: number;
@@ -1674,7 +1710,7 @@ declare function createNamespaces(config: CoreConfig): {
1674
1710
  subject: string;
1675
1711
  kind: "broadcast" | "automation" | "notification";
1676
1712
  preheader: string | null;
1677
- topic: string;
1713
+ topic: string | null;
1678
1714
  provider_id: string;
1679
1715
  counts: {
1680
1716
  sending: number;
@@ -1722,7 +1758,7 @@ declare function createNamespaces(config: CoreConfig): {
1722
1758
  subject: string;
1723
1759
  kind: "broadcast" | "automation" | "notification";
1724
1760
  preheader: string | null;
1725
- topic: string;
1761
+ topic: string | null;
1726
1762
  provider_id: string;
1727
1763
  counts: {
1728
1764
  sending: number;
@@ -1778,7 +1814,7 @@ declare function createNamespaces(config: CoreConfig): {
1778
1814
  subject: string;
1779
1815
  kind: "broadcast" | "automation" | "notification";
1780
1816
  preheader: string | null;
1781
- topic: string;
1817
+ topic: string | null;
1782
1818
  provider_id: string;
1783
1819
  counts: {
1784
1820
  sending: number;
@@ -1826,7 +1862,7 @@ declare function createNamespaces(config: CoreConfig): {
1826
1862
  subject: string;
1827
1863
  kind: "broadcast" | "automation" | "notification";
1828
1864
  preheader: string | null;
1829
- topic: string;
1865
+ topic: string | null;
1830
1866
  provider_id: string;
1831
1867
  counts: {
1832
1868
  sending: number;
@@ -1874,7 +1910,7 @@ declare function createNamespaces(config: CoreConfig): {
1874
1910
  subject: string;
1875
1911
  kind: "broadcast" | "automation" | "notification";
1876
1912
  preheader: string | null;
1877
- topic: string;
1913
+ topic: string | null;
1878
1914
  provider_id: string;
1879
1915
  counts: {
1880
1916
  sending: number;
@@ -1922,7 +1958,7 @@ declare function createNamespaces(config: CoreConfig): {
1922
1958
  subject: string;
1923
1959
  kind: "broadcast" | "automation" | "notification";
1924
1960
  preheader: string | null;
1925
- topic: string;
1961
+ topic: string | null;
1926
1962
  provider_id: string;
1927
1963
  counts: {
1928
1964
  sending: number;
@@ -1970,7 +2006,7 @@ declare function createNamespaces(config: CoreConfig): {
1970
2006
  subject: string;
1971
2007
  kind: "broadcast" | "automation" | "notification";
1972
2008
  preheader: string | null;
1973
- topic: string;
2009
+ topic: string | null;
1974
2010
  provider_id: string;
1975
2011
  counts: {
1976
2012
  sending: number;
@@ -2077,7 +2113,7 @@ declare function createNamespaces(config: CoreConfig): {
2077
2113
  created_at: string;
2078
2114
  updated_at: string;
2079
2115
  url: string;
2080
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2116
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2081
2117
  enabled: boolean;
2082
2118
  }[];
2083
2119
  next_cursor: string | null;
@@ -2089,7 +2125,7 @@ declare function createNamespaces(config: CoreConfig): {
2089
2125
  created_at: string;
2090
2126
  updated_at: string;
2091
2127
  url: string;
2092
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2128
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2093
2129
  enabled: boolean;
2094
2130
  };
2095
2131
  secret: string;
@@ -2100,7 +2136,7 @@ declare function createNamespaces(config: CoreConfig): {
2100
2136
  created_at: string;
2101
2137
  updated_at: string;
2102
2138
  url: string;
2103
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2139
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2104
2140
  enabled: boolean;
2105
2141
  }>;
2106
2142
  update: (id: string, body: RouteBody<"webhooks.update">, opts?: RequestOpts) => Promise<{
@@ -2109,7 +2145,7 @@ declare function createNamespaces(config: CoreConfig): {
2109
2145
  created_at: string;
2110
2146
  updated_at: string;
2111
2147
  url: string;
2112
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2148
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2113
2149
  enabled: boolean;
2114
2150
  }>;
2115
2151
  delete: (id: string, opts?: RequestOpts) => Promise<{
@@ -2122,7 +2158,7 @@ declare function createNamespaces(config: CoreConfig): {
2122
2158
  created_at: string;
2123
2159
  updated_at: string;
2124
2160
  url: string;
2125
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2161
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2126
2162
  enabled: boolean;
2127
2163
  };
2128
2164
  secret: string;
@@ -2136,7 +2172,7 @@ declare function createNamespaces(config: CoreConfig): {
2136
2172
  last_error: string | null;
2137
2173
  endpoint_id: string;
2138
2174
  event_id: string;
2139
- event_type: "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook";
2175
+ event_type: "template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook";
2140
2176
  last_status_code: number | null;
2141
2177
  next_attempt_at: string | null;
2142
2178
  delivered_at: string | null;
@@ -2151,7 +2187,7 @@ declare function createNamespaces(config: CoreConfig): {
2151
2187
  last_error: string | null;
2152
2188
  endpoint_id: string;
2153
2189
  event_id: string;
2154
- event_type: "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook";
2190
+ event_type: "template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook";
2155
2191
  last_status_code: number | null;
2156
2192
  next_attempt_at: string | null;
2157
2193
  delivered_at: string | null;
@@ -4378,9 +4414,11 @@ interface MailClientOptions extends BaseClientOptions {
4378
4414
  /** A workspace API key (`Authorization: Bearer <key>`), scoped to one workspace and to `full`, `send` or `read`. */
4379
4415
  apiKey: string;
4380
4416
  }
4381
- /** Every namespaced method, plus the two escape hatches: `request` for any operation id, `paginate` for cursor lists. */
4417
+ /** Every namespaced method, plus the escape hatches: `request` for any JSON operation id, `upload` for a multipart one, `paginate` for cursor lists. */
4382
4418
  interface MailClient extends MailNamespaces {
4383
4419
  request<K extends OperationId>(operationId: K, args?: ExecuteArgs<K>, opts?: RequestOpts): Promise<RouteResponse<K>>;
4420
+ /** The multipart routes (`assets.upload`, `imports.create`) by operation id, for a caller that dispatches generically. */
4421
+ upload<K extends OperationId>(operationId: K, args: MultipartArgs<K>, opts?: RequestOpts): Promise<RouteResponse<K>>;
4384
4422
  paginate<K extends PaginatableOperationId>(operationId: K, args?: PaginateArgs<K>, opts?: RequestOpts): AsyncGenerator<PageItem<K>, void, void>;
4385
4423
  /**
4386
4424
  * Checks the service's liveness probe (`HEALTH_PATH`, outside `/v1`, no
@@ -4477,4 +4515,4 @@ declare class MailResponseValidationError extends Error {
4477
4515
  /** A fresh idempotency key, reused across every retry of the same call. */
4478
4516
  declare function generateIdempotencyKey(): string;
4479
4517
 
4480
- export { type BaseClientOptions, type DashboardMailClient, type DashboardMailClientOptions, type DashboardUserContext, type ExecuteArgs, type ExportedFile, MailApiError, type MailClient, type MailClientOptions, MailNetworkError, MailResponseValidationError, MailTimeoutError, type PageItem, type PaginatableOperationId, type PaginateArgs, type RequestOpts, type ResponseMeta, createDashboardMailClient, createMailClient, dispositionFilename, generateIdempotencyKey };
4518
+ export { type BaseClientOptions, type DashboardMailClient, type DashboardMailClientOptions, type DashboardUserContext, type ExecuteArgs, type ExportedFile, MailApiError, type MailClient, type MailClientOptions, MailNetworkError, MailResponseValidationError, MailTimeoutError, type MultipartArgs, type PageItem, type PaginatableOperationId, type PaginateArgs, type RequestOpts, type ResponseMeta, createDashboardMailClient, createMailClient, dispositionFilename, generateIdempotencyKey };
package/dist/index.d.ts CHANGED
@@ -42,6 +42,16 @@ interface RequestOpts {
42
42
  * status and request id. An exception thrown here propagates to the caller.
43
43
  */
44
44
  onResponse?: (meta: ResponseMeta) => void;
45
+ /**
46
+ * The person the caller's application is acting for, when the workspace API
47
+ * key is shared by everybody who uses that application: a name or an email
48
+ * address, sent as `ON_BEHALF_OF_HEADER`. The service records it on the
49
+ * audit entry as what the application reported, never verified; it changes
50
+ * nothing about what the key may do. Trimmed; empty is not sent; longer than
51
+ * `ON_BEHALF_OF_MAX_LENGTH` throws before any request is made. Ignored by
52
+ * the service on a dashboard client's calls.
53
+ */
54
+ onBehalfOf?: string;
45
55
  }
46
56
  interface ExecuteArgs<K extends OperationId> {
47
57
  params?: RouteParams<K>;
@@ -68,6 +78,13 @@ interface ExportedFile {
68
78
  }
69
79
  /** The `filename` of a `Content-Disposition` value (the `filename*` UTF-8 form first). */
70
80
  declare function dispositionFilename(value: string | null): string | null;
81
+ interface MultipartArgs<K extends OperationId> {
82
+ params?: RouteParams<K>;
83
+ file: Blob;
84
+ filename?: string;
85
+ /** For routes whose multipart form carries a second JSON field (e.g. `imports.create`). */
86
+ json?: unknown;
87
+ }
71
88
 
72
89
  /**
73
90
  * Namespaced, hand-written wrappers over `execute`/`executeMultipart`. Every
@@ -97,6 +114,8 @@ declare function createNamespaces(config: CoreConfig): {
97
114
  default_locale: string;
98
115
  locales: string[];
99
116
  tracking_enabled: boolean;
117
+ allowed_asset_hosts: string[];
118
+ merge_defaults: Record<string, string | number | boolean>;
100
119
  default_timezone: string | null;
101
120
  };
102
121
  company_id: string | null;
@@ -113,6 +132,8 @@ declare function createNamespaces(config: CoreConfig): {
113
132
  default_locale: string;
114
133
  locales: string[];
115
134
  tracking_enabled: boolean;
135
+ allowed_asset_hosts: string[];
136
+ merge_defaults: Record<string, string | number | boolean>;
116
137
  default_timezone: string | null;
117
138
  };
118
139
  company_id: string | null;
@@ -133,6 +154,8 @@ declare function createNamespaces(config: CoreConfig): {
133
154
  default_locale: string;
134
155
  locales: string[];
135
156
  tracking_enabled: boolean;
157
+ allowed_asset_hosts: string[];
158
+ merge_defaults: Record<string, string | number | boolean>;
136
159
  default_timezone: string | null;
137
160
  };
138
161
  company_id: string | null;
@@ -148,6 +171,8 @@ declare function createNamespaces(config: CoreConfig): {
148
171
  default_locale: string;
149
172
  locales: string[];
150
173
  tracking_enabled: boolean;
174
+ allowed_asset_hosts: string[];
175
+ merge_defaults: Record<string, string | number | boolean>;
151
176
  default_timezone: string | null;
152
177
  };
153
178
  company_id: string | null;
@@ -168,6 +193,8 @@ declare function createNamespaces(config: CoreConfig): {
168
193
  default_locale: string;
169
194
  locales: string[];
170
195
  tracking_enabled: boolean;
196
+ allowed_asset_hosts: string[];
197
+ merge_defaults: Record<string, string | number | boolean>;
171
198
  default_timezone: string | null;
172
199
  };
173
200
  company_id: string | null;
@@ -276,6 +303,8 @@ declare function createNamespaces(config: CoreConfig): {
276
303
  default_locale: string;
277
304
  locales: string[];
278
305
  tracking_enabled: boolean;
306
+ allowed_asset_hosts: string[];
307
+ merge_defaults: Record<string, string | number | boolean>;
279
308
  default_timezone: string | null;
280
309
  };
281
310
  company_id: string | null;
@@ -325,7 +354,7 @@ declare function createNamespaces(config: CoreConfig): {
325
354
  id: string;
326
355
  details: Record<string, unknown>;
327
356
  created_at: string;
328
- action: "workspace.created" | "workspace.updated" | "workspace.company_changed" | "member.added" | "member.role_changed" | "member.removed" | "member.invited" | "invite.revoked" | "api_key.created" | "api_key.revoked" | "provider.created" | "provider.updated" | "provider.deleted" | "provider.events_registered" | "provider.events_secret_set" | "provider.bounces_halted" | "provider.anomaly_cleared" | "topic.created" | "topic.updated" | "template.created" | "template.updated" | "template.deleted" | "saved_section.created" | "saved_section.updated" | "saved_section.deleted" | "asset.uploaded" | "asset.imported" | "contact.erased" | "suppression.created" | "suppression.deleted" | "mailing.created" | "mailing.sent" | "mailing.paused" | "mailing.resumed" | "mailing.cancelled" | "mailing.retried" | "webhook.created" | "webhook.updated" | "webhook.deleted" | "webhook.secret_rotated" | "webhook.redelivered" | "contact.unsubscribed" | "tag.created" | "tag.deleted" | "tag.assigned" | "tag.unassigned" | "contact_property.created" | "contact_property.deleted" | "segment.created" | "segment.updated" | "segment.deleted" | "signup_form.created" | "signup_form.updated" | "signup_form.deleted" | "contact.subscribed" | "import.created" | "import.mapped" | "import.committed" | "import.cancelled" | "import.finished" | "mailing.scheduled" | "mailing.unscheduled" | "mailing.schedule_failed" | "mailing.ab_test_updated" | "mailing.ab_winner_selected" | "tracking.updated" | "billing.checkout_started" | "billing.subscription_changed" | "billing.exemption_changed" | "automation.created" | "automation.updated" | "automation.published" | "automation.paused" | "automation.resumed" | "automation.archived" | "automation.deleted" | "automation.duplicated" | "automation.enrolled" | "automation.run_ended" | "event.recorded";
357
+ action: "workspace.created" | "workspace.updated" | "workspace.company_changed" | "member.added" | "member.role_changed" | "member.removed" | "member.invited" | "invite.revoked" | "api_key.created" | "api_key.revoked" | "provider.created" | "provider.updated" | "provider.deleted" | "provider.events_registered" | "provider.events_secret_set" | "provider.bounces_halted" | "provider.anomaly_cleared" | "topic.created" | "topic.updated" | "topic.deleted" | "template.created" | "template.updated" | "template.deleted" | "saved_section.created" | "saved_section.updated" | "saved_section.deleted" | "asset.uploaded" | "asset.imported" | "contact.erased" | "suppression.created" | "suppression.deleted" | "mailing.created" | "mailing.sent" | "mailing.paused" | "mailing.resumed" | "mailing.cancelled" | "mailing.retried" | "webhook.created" | "webhook.updated" | "webhook.deleted" | "webhook.secret_rotated" | "webhook.redelivered" | "contact.unsubscribed" | "tag.created" | "tag.deleted" | "tag.assigned" | "tag.unassigned" | "contact_property.created" | "contact_property.deleted" | "segment.created" | "segment.updated" | "segment.deleted" | "signup_form.created" | "signup_form.updated" | "signup_form.deleted" | "contact.subscribed" | "import.created" | "import.mapped" | "import.committed" | "import.cancelled" | "import.finished" | "mailing.scheduled" | "mailing.unscheduled" | "mailing.schedule_failed" | "mailing.ab_test_updated" | "mailing.ab_winner_selected" | "tracking.updated" | "billing.checkout_started" | "billing.subscription_changed" | "billing.exemption_changed" | "automation.created" | "automation.updated" | "automation.published" | "automation.paused" | "automation.resumed" | "automation.archived" | "automation.deleted" | "automation.duplicated" | "automation.enrolled" | "automation.run_ended" | "event.recorded";
329
358
  actor: {
330
359
  type: "member";
331
360
  subject: string;
@@ -333,6 +362,7 @@ declare function createNamespaces(config: CoreConfig): {
333
362
  } | {
334
363
  type: "api_key";
335
364
  api_key_id: string;
365
+ on_behalf_of?: string | undefined;
336
366
  } | {
337
367
  type: "system";
338
368
  reason: string;
@@ -609,7 +639,9 @@ declare function createNamespaces(config: CoreConfig): {
609
639
  /**
610
640
  * Copies a remote image into the workspace's assets and answers with the
611
641
  * new asset, whose `url` is the service's own. The workspace setting
612
- * `asset_policy: 'service_only'` accepts only such addresses in a mail.
642
+ * `asset_policy: 'service_only'` accepts only such addresses in a mail,
643
+ * plus any host in `settings.allowed_asset_hosts` (the workspace's own
644
+ * website, typically), whose images need no copy.
613
645
  */
614
646
  import: (body: RouteBody<"assets.import">, opts?: RequestOpts) => Promise<{
615
647
  id: string;
@@ -1118,6 +1150,10 @@ declare function createNamespaces(config: CoreConfig): {
1118
1150
  description: string | null;
1119
1151
  }>;
1120
1152
  }>;
1153
+ /** Refused with `conflict` while a mailing or an automation step still uses the topic. */
1154
+ delete: (id: string, opts?: RequestOpts) => Promise<{
1155
+ ok: true;
1156
+ }>;
1121
1157
  };
1122
1158
  contacts: {
1123
1159
  upsert: (body: RouteBody<"contacts.upsert">, opts?: RequestOpts) => Promise<{
@@ -1257,7 +1293,7 @@ declare function createNamespaces(config: CoreConfig): {
1257
1293
  subject: string;
1258
1294
  kind: "broadcast" | "automation" | "notification";
1259
1295
  preheader: string | null;
1260
- topic: string;
1296
+ topic: string | null;
1261
1297
  provider_id: string;
1262
1298
  counts: {
1263
1299
  sending: number;
@@ -1307,7 +1343,7 @@ declare function createNamespaces(config: CoreConfig): {
1307
1343
  subject: string;
1308
1344
  kind: "broadcast" | "automation" | "notification";
1309
1345
  preheader: string | null;
1310
- topic: string;
1346
+ topic: string | null;
1311
1347
  provider_id: string;
1312
1348
  counts: {
1313
1349
  sending: number;
@@ -1355,7 +1391,7 @@ declare function createNamespaces(config: CoreConfig): {
1355
1391
  subject: string;
1356
1392
  kind: "broadcast" | "automation" | "notification";
1357
1393
  preheader: string | null;
1358
- topic: string;
1394
+ topic: string | null;
1359
1395
  provider_id: string;
1360
1396
  counts: {
1361
1397
  sending: number;
@@ -1405,7 +1441,7 @@ declare function createNamespaces(config: CoreConfig): {
1405
1441
  subject: string;
1406
1442
  kind: "broadcast" | "automation" | "notification";
1407
1443
  preheader: string | null;
1408
- topic: string;
1444
+ topic: string | null;
1409
1445
  provider_id: string;
1410
1446
  counts: {
1411
1447
  sending: number;
@@ -1482,7 +1518,7 @@ declare function createNamespaces(config: CoreConfig): {
1482
1518
  subject: string;
1483
1519
  kind: "broadcast" | "automation" | "notification";
1484
1520
  preheader: string | null;
1485
- topic: string;
1521
+ topic: string | null;
1486
1522
  provider_id: string;
1487
1523
  counts: {
1488
1524
  sending: number;
@@ -1530,7 +1566,7 @@ declare function createNamespaces(config: CoreConfig): {
1530
1566
  subject: string;
1531
1567
  kind: "broadcast" | "automation" | "notification";
1532
1568
  preheader: string | null;
1533
- topic: string;
1569
+ topic: string | null;
1534
1570
  provider_id: string;
1535
1571
  counts: {
1536
1572
  sending: number;
@@ -1578,7 +1614,7 @@ declare function createNamespaces(config: CoreConfig): {
1578
1614
  subject: string;
1579
1615
  kind: "broadcast" | "automation" | "notification";
1580
1616
  preheader: string | null;
1581
- topic: string;
1617
+ topic: string | null;
1582
1618
  provider_id: string;
1583
1619
  counts: {
1584
1620
  sending: number;
@@ -1626,7 +1662,7 @@ declare function createNamespaces(config: CoreConfig): {
1626
1662
  subject: string;
1627
1663
  kind: "broadcast" | "automation" | "notification";
1628
1664
  preheader: string | null;
1629
- topic: string;
1665
+ topic: string | null;
1630
1666
  provider_id: string;
1631
1667
  counts: {
1632
1668
  sending: number;
@@ -1674,7 +1710,7 @@ declare function createNamespaces(config: CoreConfig): {
1674
1710
  subject: string;
1675
1711
  kind: "broadcast" | "automation" | "notification";
1676
1712
  preheader: string | null;
1677
- topic: string;
1713
+ topic: string | null;
1678
1714
  provider_id: string;
1679
1715
  counts: {
1680
1716
  sending: number;
@@ -1722,7 +1758,7 @@ declare function createNamespaces(config: CoreConfig): {
1722
1758
  subject: string;
1723
1759
  kind: "broadcast" | "automation" | "notification";
1724
1760
  preheader: string | null;
1725
- topic: string;
1761
+ topic: string | null;
1726
1762
  provider_id: string;
1727
1763
  counts: {
1728
1764
  sending: number;
@@ -1778,7 +1814,7 @@ declare function createNamespaces(config: CoreConfig): {
1778
1814
  subject: string;
1779
1815
  kind: "broadcast" | "automation" | "notification";
1780
1816
  preheader: string | null;
1781
- topic: string;
1817
+ topic: string | null;
1782
1818
  provider_id: string;
1783
1819
  counts: {
1784
1820
  sending: number;
@@ -1826,7 +1862,7 @@ declare function createNamespaces(config: CoreConfig): {
1826
1862
  subject: string;
1827
1863
  kind: "broadcast" | "automation" | "notification";
1828
1864
  preheader: string | null;
1829
- topic: string;
1865
+ topic: string | null;
1830
1866
  provider_id: string;
1831
1867
  counts: {
1832
1868
  sending: number;
@@ -1874,7 +1910,7 @@ declare function createNamespaces(config: CoreConfig): {
1874
1910
  subject: string;
1875
1911
  kind: "broadcast" | "automation" | "notification";
1876
1912
  preheader: string | null;
1877
- topic: string;
1913
+ topic: string | null;
1878
1914
  provider_id: string;
1879
1915
  counts: {
1880
1916
  sending: number;
@@ -1922,7 +1958,7 @@ declare function createNamespaces(config: CoreConfig): {
1922
1958
  subject: string;
1923
1959
  kind: "broadcast" | "automation" | "notification";
1924
1960
  preheader: string | null;
1925
- topic: string;
1961
+ topic: string | null;
1926
1962
  provider_id: string;
1927
1963
  counts: {
1928
1964
  sending: number;
@@ -1970,7 +2006,7 @@ declare function createNamespaces(config: CoreConfig): {
1970
2006
  subject: string;
1971
2007
  kind: "broadcast" | "automation" | "notification";
1972
2008
  preheader: string | null;
1973
- topic: string;
2009
+ topic: string | null;
1974
2010
  provider_id: string;
1975
2011
  counts: {
1976
2012
  sending: number;
@@ -2077,7 +2113,7 @@ declare function createNamespaces(config: CoreConfig): {
2077
2113
  created_at: string;
2078
2114
  updated_at: string;
2079
2115
  url: string;
2080
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2116
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2081
2117
  enabled: boolean;
2082
2118
  }[];
2083
2119
  next_cursor: string | null;
@@ -2089,7 +2125,7 @@ declare function createNamespaces(config: CoreConfig): {
2089
2125
  created_at: string;
2090
2126
  updated_at: string;
2091
2127
  url: string;
2092
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2128
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2093
2129
  enabled: boolean;
2094
2130
  };
2095
2131
  secret: string;
@@ -2100,7 +2136,7 @@ declare function createNamespaces(config: CoreConfig): {
2100
2136
  created_at: string;
2101
2137
  updated_at: string;
2102
2138
  url: string;
2103
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2139
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2104
2140
  enabled: boolean;
2105
2141
  }>;
2106
2142
  update: (id: string, body: RouteBody<"webhooks.update">, opts?: RequestOpts) => Promise<{
@@ -2109,7 +2145,7 @@ declare function createNamespaces(config: CoreConfig): {
2109
2145
  created_at: string;
2110
2146
  updated_at: string;
2111
2147
  url: string;
2112
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2148
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2113
2149
  enabled: boolean;
2114
2150
  }>;
2115
2151
  delete: (id: string, opts?: RequestOpts) => Promise<{
@@ -2122,7 +2158,7 @@ declare function createNamespaces(config: CoreConfig): {
2122
2158
  created_at: string;
2123
2159
  updated_at: string;
2124
2160
  url: string;
2125
- events: ("contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2161
+ events: ("template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook")[];
2126
2162
  enabled: boolean;
2127
2163
  };
2128
2164
  secret: string;
@@ -2136,7 +2172,7 @@ declare function createNamespaces(config: CoreConfig): {
2136
2172
  last_error: string | null;
2137
2173
  endpoint_id: string;
2138
2174
  event_id: string;
2139
- event_type: "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook";
2175
+ event_type: "template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook";
2140
2176
  last_status_code: number | null;
2141
2177
  next_attempt_at: string | null;
2142
2178
  delivered_at: string | null;
@@ -2151,7 +2187,7 @@ declare function createNamespaces(config: CoreConfig): {
2151
2187
  last_error: string | null;
2152
2188
  endpoint_id: string;
2153
2189
  event_id: string;
2154
- event_type: "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook";
2190
+ event_type: "template.created" | "template.updated" | "template.deleted" | "contact.unsubscribed" | "contact.subscribed" | "import.finished" | "mailing.scheduled" | "mailing.schedule_failed" | "mailing.ab_winner_selected" | "message.sent" | "message.failed" | "contact.resubscribed" | "contact.bounced" | "mailing.finished" | "mailing.started" | "contact.tagged" | "contact.updated" | "automation.run_started" | "automation.run_completed" | "automation.run_exited" | "automation.run_failed" | "automation.webhook";
2155
2191
  last_status_code: number | null;
2156
2192
  next_attempt_at: string | null;
2157
2193
  delivered_at: string | null;
@@ -4378,9 +4414,11 @@ interface MailClientOptions extends BaseClientOptions {
4378
4414
  /** A workspace API key (`Authorization: Bearer <key>`), scoped to one workspace and to `full`, `send` or `read`. */
4379
4415
  apiKey: string;
4380
4416
  }
4381
- /** Every namespaced method, plus the two escape hatches: `request` for any operation id, `paginate` for cursor lists. */
4417
+ /** Every namespaced method, plus the escape hatches: `request` for any JSON operation id, `upload` for a multipart one, `paginate` for cursor lists. */
4382
4418
  interface MailClient extends MailNamespaces {
4383
4419
  request<K extends OperationId>(operationId: K, args?: ExecuteArgs<K>, opts?: RequestOpts): Promise<RouteResponse<K>>;
4420
+ /** The multipart routes (`assets.upload`, `imports.create`) by operation id, for a caller that dispatches generically. */
4421
+ upload<K extends OperationId>(operationId: K, args: MultipartArgs<K>, opts?: RequestOpts): Promise<RouteResponse<K>>;
4384
4422
  paginate<K extends PaginatableOperationId>(operationId: K, args?: PaginateArgs<K>, opts?: RequestOpts): AsyncGenerator<PageItem<K>, void, void>;
4385
4423
  /**
4386
4424
  * Checks the service's liveness probe (`HEALTH_PATH`, outside `/v1`, no
@@ -4477,4 +4515,4 @@ declare class MailResponseValidationError extends Error {
4477
4515
  /** A fresh idempotency key, reused across every retry of the same call. */
4478
4516
  declare function generateIdempotencyKey(): string;
4479
4517
 
4480
- export { type BaseClientOptions, type DashboardMailClient, type DashboardMailClientOptions, type DashboardUserContext, type ExecuteArgs, type ExportedFile, MailApiError, type MailClient, type MailClientOptions, MailNetworkError, MailResponseValidationError, MailTimeoutError, type PageItem, type PaginatableOperationId, type PaginateArgs, type RequestOpts, type ResponseMeta, createDashboardMailClient, createMailClient, dispositionFilename, generateIdempotencyKey };
4518
+ export { type BaseClientOptions, type DashboardMailClient, type DashboardMailClientOptions, type DashboardUserContext, type ExecuteArgs, type ExportedFile, MailApiError, type MailClient, type MailClientOptions, MailNetworkError, MailResponseValidationError, MailTimeoutError, type MultipartArgs, type PageItem, type PaginatableOperationId, type PaginateArgs, type RequestOpts, type ResponseMeta, createDashboardMailClient, createMailClient, dispositionFilename, generateIdempotencyKey };
package/dist/index.js CHANGED
@@ -129,6 +129,15 @@ function parseRetryAfterMs(header, now = Date.now) {
129
129
  }
130
130
 
131
131
  // src/core.ts
132
+ function onBehalfOfHeader(opts) {
133
+ if (opts.onBehalfOf === void 0) return {};
134
+ const label = opts.onBehalfOf.trim();
135
+ if (label.length === 0) return {};
136
+ if (label.length > import_mail_contract.ON_BEHALF_OF_MAX_LENGTH) {
137
+ throw new RangeError(`onBehalfOf is ${label.length} characters; the service accepts at most ${import_mail_contract.ON_BEHALF_OF_MAX_LENGTH}`);
138
+ }
139
+ return { [import_mail_contract.ON_BEHALF_OF_HEADER]: label };
140
+ }
132
141
  function responseMeta(response, requestId) {
133
142
  return {
134
143
  status: response.status,
@@ -178,6 +187,7 @@ async function send(config, operationId, args, opts, accept) {
178
187
  const hasJsonBody = route.body !== void 0;
179
188
  const bodyText = hasJsonBody ? JSON.stringify(args.body ?? {}) : void 0;
180
189
  const idempotencyKey = (0, import_mail_contract.acceptsIdempotencyKey)(route) ? opts.idempotencyKey ?? generateIdempotencyKey() : void 0;
190
+ const onBehalfOf = onBehalfOfHeader(opts);
181
191
  let lastError;
182
192
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
183
193
  const timeoutController = new AbortController();
@@ -187,6 +197,7 @@ async function send(config, operationId, args, opts, accept) {
187
197
  try {
188
198
  const headers = {
189
199
  ...config.authHeaders(),
200
+ ...onBehalfOf,
190
201
  accept
191
202
  };
192
203
  if (hasJsonBody) headers["content-type"] = "application/json";
@@ -296,6 +307,7 @@ async function executeMultipart(config, operationId, args, opts = {}) {
296
307
  const path = (0, import_mail_contract.buildPath)(route.path, args.params ?? {});
297
308
  const url = `${config.baseUrl.replace(/\/+$/, "")}${path}`;
298
309
  const idempotencyKey = (0, import_mail_contract.acceptsIdempotencyKey)(route) ? opts.idempotencyKey ?? generateIdempotencyKey() : void 0;
310
+ const onBehalfOf = onBehalfOfHeader(opts);
299
311
  let lastError;
300
312
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
301
313
  const timeoutController = new AbortController();
@@ -308,7 +320,7 @@ async function executeMultipart(config, operationId, args, opts = {}) {
308
320
  if (route.multipart.jsonField) {
309
321
  form.set(route.multipart.jsonField, JSON.stringify(args.json ?? {}));
310
322
  }
311
- const headers = { ...config.authHeaders(), accept: "application/json" };
323
+ const headers = { ...config.authHeaders(), ...onBehalfOf, accept: "application/json" };
312
324
  if (idempotencyKey) headers[import_mail_contract.IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
313
325
  if (config.userAgent) headers["user-agent"] = config.userAgent;
314
326
  let response;
@@ -470,7 +482,9 @@ function createNamespaces(config) {
470
482
  /**
471
483
  * Copies a remote image into the workspace's assets and answers with the
472
484
  * new asset, whose `url` is the service's own. The workspace setting
473
- * `asset_policy: 'service_only'` accepts only such addresses in a mail.
485
+ * `asset_policy: 'service_only'` accepts only such addresses in a mail,
486
+ * plus any host in `settings.allowed_asset_hosts` (the workspace's own
487
+ * website, typically), whose images need no copy.
474
488
  */
475
489
  import: (body, opts) => execute(config, "assets.import", { body }, opts),
476
490
  get: (id, opts) => execute(config, "assets.get", { params: { id } }, opts)
@@ -491,7 +505,9 @@ function createNamespaces(config) {
491
505
  topics: {
492
506
  list: (query, opts) => execute(config, "topics.list", { query }, opts),
493
507
  create: (body, opts) => execute(config, "topics.create", { body }, opts),
494
- update: (id, body, opts) => execute(config, "topics.update", { params: { id }, body }, opts)
508
+ update: (id, body, opts) => execute(config, "topics.update", { params: { id }, body }, opts),
509
+ /** Refused with `conflict` while a mailing or an automation step still uses the topic. */
510
+ delete: (id, opts) => execute(config, "topics.delete", { params: { id } }, opts)
495
511
  },
496
512
  contacts: {
497
513
  upsert: (body, opts) => execute(config, "contacts.upsert", { body }, opts),
@@ -698,6 +714,7 @@ function buildClient(config) {
698
714
  return {
699
715
  ...createNamespaces(config),
700
716
  request: (operationId, args, opts) => execute(config, operationId, args ?? {}, opts),
717
+ upload: (operationId, args, opts) => executeMultipart(config, operationId, args, opts),
701
718
  paginate: (operationId, args, opts) => paginate(config, operationId, args ?? {}, opts),
702
719
  health: (opts) => checkHealth(config, opts)
703
720
  };
package/dist/index.mjs CHANGED
@@ -7,6 +7,8 @@ import {
7
7
  BEARER_PREFIX,
8
8
  ErrorBody,
9
9
  IDEMPOTENCY_KEY_HEADER,
10
+ ON_BEHALF_OF_HEADER,
11
+ ON_BEHALF_OF_MAX_LENGTH,
10
12
  REQUEST_ID_HEADER,
11
13
  RETRY_AFTER_HEADER,
12
14
  USAGE_WARNING_HEADER,
@@ -111,6 +113,15 @@ function parseRetryAfterMs(header, now = Date.now) {
111
113
  }
112
114
 
113
115
  // src/core.ts
116
+ function onBehalfOfHeader(opts) {
117
+ if (opts.onBehalfOf === void 0) return {};
118
+ const label = opts.onBehalfOf.trim();
119
+ if (label.length === 0) return {};
120
+ if (label.length > ON_BEHALF_OF_MAX_LENGTH) {
121
+ throw new RangeError(`onBehalfOf is ${label.length} characters; the service accepts at most ${ON_BEHALF_OF_MAX_LENGTH}`);
122
+ }
123
+ return { [ON_BEHALF_OF_HEADER]: label };
124
+ }
114
125
  function responseMeta(response, requestId) {
115
126
  return {
116
127
  status: response.status,
@@ -160,6 +171,7 @@ async function send(config, operationId, args, opts, accept) {
160
171
  const hasJsonBody = route.body !== void 0;
161
172
  const bodyText = hasJsonBody ? JSON.stringify(args.body ?? {}) : void 0;
162
173
  const idempotencyKey = acceptsIdempotencyKey(route) ? opts.idempotencyKey ?? generateIdempotencyKey() : void 0;
174
+ const onBehalfOf = onBehalfOfHeader(opts);
163
175
  let lastError;
164
176
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
165
177
  const timeoutController = new AbortController();
@@ -169,6 +181,7 @@ async function send(config, operationId, args, opts, accept) {
169
181
  try {
170
182
  const headers = {
171
183
  ...config.authHeaders(),
184
+ ...onBehalfOf,
172
185
  accept
173
186
  };
174
187
  if (hasJsonBody) headers["content-type"] = "application/json";
@@ -278,6 +291,7 @@ async function executeMultipart(config, operationId, args, opts = {}) {
278
291
  const path = buildPath(route.path, args.params ?? {});
279
292
  const url = `${config.baseUrl.replace(/\/+$/, "")}${path}`;
280
293
  const idempotencyKey = acceptsIdempotencyKey(route) ? opts.idempotencyKey ?? generateIdempotencyKey() : void 0;
294
+ const onBehalfOf = onBehalfOfHeader(opts);
281
295
  let lastError;
282
296
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
283
297
  const timeoutController = new AbortController();
@@ -290,7 +304,7 @@ async function executeMultipart(config, operationId, args, opts = {}) {
290
304
  if (route.multipart.jsonField) {
291
305
  form.set(route.multipart.jsonField, JSON.stringify(args.json ?? {}));
292
306
  }
293
- const headers = { ...config.authHeaders(), accept: "application/json" };
307
+ const headers = { ...config.authHeaders(), ...onBehalfOf, accept: "application/json" };
294
308
  if (idempotencyKey) headers[IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
295
309
  if (config.userAgent) headers["user-agent"] = config.userAgent;
296
310
  let response;
@@ -452,7 +466,9 @@ function createNamespaces(config) {
452
466
  /**
453
467
  * Copies a remote image into the workspace's assets and answers with the
454
468
  * new asset, whose `url` is the service's own. The workspace setting
455
- * `asset_policy: 'service_only'` accepts only such addresses in a mail.
469
+ * `asset_policy: 'service_only'` accepts only such addresses in a mail,
470
+ * plus any host in `settings.allowed_asset_hosts` (the workspace's own
471
+ * website, typically), whose images need no copy.
456
472
  */
457
473
  import: (body, opts) => execute(config, "assets.import", { body }, opts),
458
474
  get: (id, opts) => execute(config, "assets.get", { params: { id } }, opts)
@@ -473,7 +489,9 @@ function createNamespaces(config) {
473
489
  topics: {
474
490
  list: (query, opts) => execute(config, "topics.list", { query }, opts),
475
491
  create: (body, opts) => execute(config, "topics.create", { body }, opts),
476
- update: (id, body, opts) => execute(config, "topics.update", { params: { id }, body }, opts)
492
+ update: (id, body, opts) => execute(config, "topics.update", { params: { id }, body }, opts),
493
+ /** Refused with `conflict` while a mailing or an automation step still uses the topic. */
494
+ delete: (id, opts) => execute(config, "topics.delete", { params: { id } }, opts)
477
495
  },
478
496
  contacts: {
479
497
  upsert: (body, opts) => execute(config, "contacts.upsert", { body }, opts),
@@ -680,6 +698,7 @@ function buildClient(config) {
680
698
  return {
681
699
  ...createNamespaces(config),
682
700
  request: (operationId, args, opts) => execute(config, operationId, args ?? {}, opts),
701
+ upload: (operationId, args, opts) => executeMultipart(config, operationId, args, opts),
683
702
  paginate: (operationId, args, opts) => paginate(config, operationId, args ?? {}, opts),
684
703
  health: (opts) => checkHealth(config, opts)
685
704
  };
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "publishConfig": {
4
4
  "access": "public"
5
5
  },
6
- "version": "0.2.0",
6
+ "version": "0.4.0",
7
7
  "description": "Typed client for the Lumitra Mail v1 API: Node and edge runtimes, retries with idempotency, cursor pagination, webhook verification",
8
8
  "license": "MIT",
9
9
  "repository": {
@@ -32,7 +32,7 @@
32
32
  "LICENSE"
33
33
  ],
34
34
  "dependencies": {
35
- "@marlinjai/mail-contract": "^0.2.0"
35
+ "@marlinjai/mail-contract": "^0.4.0"
36
36
  },
37
37
  "peerDependencies": {
38
38
  "zod": "^3.25.0"