@productcraft/notify 0.2.0 → 0.3.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/dist/index.d.ts CHANGED
@@ -3,9 +3,9 @@ export { APIConnectionError, APIError, APIPromise, APITimeoutError, APIUserAbort
3
3
  import { Client } from 'openapi-fetch';
4
4
 
5
5
  /** Error codes this API documents. Open: codes added later still type-check. See https://productcraft.co/docs/errors. */
6
- type NotifyErrorCode = "BAD_REQUEST" | "VALIDATION_ERROR" | "UNAUTHORIZED" | "PAYMENT_REQUIRED" | "FORBIDDEN" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "NOT_ACCEPTABLE" | "REQUEST_TIMEOUT" | "CONFLICT" | "GONE" | "PRECONDITION_FAILED" | "PAYLOAD_TOO_LARGE" | "UNSUPPORTED_MEDIA_TYPE" | "UNPROCESSABLE_ENTITY" | "PRECONDITION_REQUIRED" | "RATE_LIMITED" | "INTERNAL_SERVER_ERROR" | "NOT_IMPLEMENTED" | "BAD_GATEWAY" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "SERVICE_NOT_ENABLED" | "INVALID_CREDENTIALS" | "SESSION_REVOKED" | "MCP_NOT_PERMITTED" | "MCP_WORKSPACE_MISMATCH" | "PAK_NOT_PERMITTED" | "ACTIONS_NOT_GRANTABLE" | "IDEMPOTENCY_KEY_REUSE" | "IDEMPOTENCY_KEY_REQUIRED" | "IDEMPOTENCY_IN_PROGRESS" | "WEBHOOK_ENDPOINT_LIMIT" | "WEBHOOK_ENDPOINT_NOT_FOUND" | "WEBHOOK_ENDPOINT_NOT_SUBSCRIBED" | "WEBHOOK_EVENT_NOT_FOUND" | "WEBHOOK_EVENT_TYPE_UNKNOWN" | "NOTIFICATION_TYPE_NOT_FOUND" | "NOTIFICATION_TYPE_ARCHIVED" | "RECIPIENT_NOT_FOUND" | "TOO_MANY_RECIPIENTS" | "DATA_TOO_LARGE" | "TEMPLATE_MISSING" | "TEMPLATE_INVALID" | "CHANNEL_NOT_CONFIGURED" | "CREDENTIAL_INVALID" | "CREDENTIAL_NOT_FOUND" | "CREDENTIAL_MISMATCH" | "DEVICE_TOKEN_INVALID" | "WEBPUSH_ENDPOINT_NOT_ALLOWED" | "RECIPIENT_TOKEN_INVALID" | "RECIPIENT_TOKEN_EXPIRED" | "RECIPIENT_TOKEN_SCOPE" | "ORIGIN_NOT_ALLOWED" | "STREAM_LIMIT" | "LIMIT_EXCEEDED" | "SEND_AT_OUT_OF_RANGE" | "UNSAFE_URL" | "AUTH_USER_ALREADY_LINKED" | "DEVICE_NOT_FOUND" | "CATEGORY_NOT_FOUND" | "CATEGORY_KEY_TAKEN" | "CATEGORY_IN_USE" | "NOTIFICATION_TYPE_KEY_TAKEN" | "TEMPLATE_NOT_FOUND" | "TEMPLATE_VERSION_NOT_FOUND" | "PREFERENCE_LOCKED" | "NOTIFICATION_NOT_FOUND" | "DELIVERY_NOT_FOUND" | "CONFIRMATION_REQUIRED" | "INBOX_ITEM_NOT_FOUND" | "RECIPIENT_ERASED" | "DEVICE_MOVE_LIMIT" | (string & {});
6
+ type NotifyErrorCode = "BAD_REQUEST" | "VALIDATION_ERROR" | "UNAUTHORIZED" | "PAYMENT_REQUIRED" | "FORBIDDEN" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "NOT_ACCEPTABLE" | "REQUEST_TIMEOUT" | "CONFLICT" | "GONE" | "PRECONDITION_FAILED" | "PAYLOAD_TOO_LARGE" | "UNSUPPORTED_MEDIA_TYPE" | "UNPROCESSABLE_ENTITY" | "PRECONDITION_REQUIRED" | "RATE_LIMITED" | "INTERNAL_SERVER_ERROR" | "NOT_IMPLEMENTED" | "BAD_GATEWAY" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "SERVICE_NOT_ENABLED" | "INVALID_CREDENTIALS" | "SESSION_REVOKED" | "MCP_NOT_PERMITTED" | "MCP_WORKSPACE_MISMATCH" | "PAK_NOT_PERMITTED" | "ACTIONS_NOT_GRANTABLE" | "IDEMPOTENCY_KEY_REUSE" | "IDEMPOTENCY_KEY_REQUIRED" | "IDEMPOTENCY_IN_PROGRESS" | "WEBHOOK_ENDPOINT_LIMIT" | "WEBHOOK_ENDPOINT_NOT_FOUND" | "WEBHOOK_ENDPOINT_NOT_SUBSCRIBED" | "WEBHOOK_EVENT_NOT_FOUND" | "WEBHOOK_EVENT_TYPE_UNKNOWN" | "NOTIFICATION_TYPE_NOT_FOUND" | "NOTIFICATION_TYPE_ARCHIVED" | "RECIPIENT_NOT_FOUND" | "TOO_MANY_RECIPIENTS" | "DATA_TOO_LARGE" | "TEMPLATE_MISSING" | "TEMPLATE_INVALID" | "CHANNEL_NOT_CONFIGURED" | "CREDENTIAL_INVALID" | "CREDENTIAL_NOT_FOUND" | "CREDENTIAL_MISMATCH" | "DEVICE_TOKEN_INVALID" | "WEBPUSH_ENDPOINT_NOT_ALLOWED" | "RECIPIENT_TOKEN_INVALID" | "RECIPIENT_TOKEN_EXPIRED" | "RECIPIENT_TOKEN_SCOPE" | "ORIGIN_NOT_ALLOWED" | "STREAM_LIMIT" | "LIMIT_EXCEEDED" | "BATCHED_TYPE_NOT_SCHEDULABLE" | "BATCH_NOT_FOUND" | "BATCH_NOT_OPEN" | "SEND_AT_OUT_OF_RANGE" | "UNSAFE_URL" | "AUTH_USER_ALREADY_LINKED" | "DEVICE_NOT_FOUND" | "CATEGORY_NOT_FOUND" | "CATEGORY_KEY_TAKEN" | "CATEGORY_IN_USE" | "NOTIFICATION_TYPE_KEY_TAKEN" | "TEMPLATE_NOT_FOUND" | "TEMPLATE_VERSION_NOT_FOUND" | "PREFERENCE_LOCKED" | "NOTIFICATION_NOT_FOUND" | "DELIVERY_NOT_FOUND" | "CONFIRMATION_REQUIRED" | "INBOX_ITEM_NOT_FOUND" | "RECIPIENT_ERASED" | "DEVICE_MOVE_LIMIT" | (string & {});
7
7
  declare const NotifyErrorCode: {
8
- values: readonly ["BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "NOT_ACCEPTABLE", "REQUEST_TIMEOUT", "CONFLICT", "GONE", "PRECONDITION_FAILED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "UNPROCESSABLE_ENTITY", "PRECONDITION_REQUIRED", "RATE_LIMITED", "INTERNAL_SERVER_ERROR", "NOT_IMPLEMENTED", "BAD_GATEWAY", "SERVICE_UNAVAILABLE", "GATEWAY_TIMEOUT", "SERVICE_NOT_ENABLED", "INVALID_CREDENTIALS", "SESSION_REVOKED", "MCP_NOT_PERMITTED", "MCP_WORKSPACE_MISMATCH", "PAK_NOT_PERMITTED", "ACTIONS_NOT_GRANTABLE", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_IN_PROGRESS", "WEBHOOK_ENDPOINT_LIMIT", "WEBHOOK_ENDPOINT_NOT_FOUND", "WEBHOOK_ENDPOINT_NOT_SUBSCRIBED", "WEBHOOK_EVENT_NOT_FOUND", "WEBHOOK_EVENT_TYPE_UNKNOWN", "NOTIFICATION_TYPE_NOT_FOUND", "NOTIFICATION_TYPE_ARCHIVED", "RECIPIENT_NOT_FOUND", "TOO_MANY_RECIPIENTS", "DATA_TOO_LARGE", "TEMPLATE_MISSING", "TEMPLATE_INVALID", "CHANNEL_NOT_CONFIGURED", "CREDENTIAL_INVALID", "CREDENTIAL_NOT_FOUND", "CREDENTIAL_MISMATCH", "DEVICE_TOKEN_INVALID", "WEBPUSH_ENDPOINT_NOT_ALLOWED", "RECIPIENT_TOKEN_INVALID", "RECIPIENT_TOKEN_EXPIRED", "RECIPIENT_TOKEN_SCOPE", "ORIGIN_NOT_ALLOWED", "STREAM_LIMIT", "LIMIT_EXCEEDED", "SEND_AT_OUT_OF_RANGE", "UNSAFE_URL", "AUTH_USER_ALREADY_LINKED", "DEVICE_NOT_FOUND", "CATEGORY_NOT_FOUND", "CATEGORY_KEY_TAKEN", "CATEGORY_IN_USE", "NOTIFICATION_TYPE_KEY_TAKEN", "TEMPLATE_NOT_FOUND", "TEMPLATE_VERSION_NOT_FOUND", "PREFERENCE_LOCKED", "NOTIFICATION_NOT_FOUND", "DELIVERY_NOT_FOUND", "CONFIRMATION_REQUIRED", "INBOX_ITEM_NOT_FOUND", "RECIPIENT_ERASED", "DEVICE_MOVE_LIMIT"];
8
+ values: readonly ["BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "NOT_ACCEPTABLE", "REQUEST_TIMEOUT", "CONFLICT", "GONE", "PRECONDITION_FAILED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "UNPROCESSABLE_ENTITY", "PRECONDITION_REQUIRED", "RATE_LIMITED", "INTERNAL_SERVER_ERROR", "NOT_IMPLEMENTED", "BAD_GATEWAY", "SERVICE_UNAVAILABLE", "GATEWAY_TIMEOUT", "SERVICE_NOT_ENABLED", "INVALID_CREDENTIALS", "SESSION_REVOKED", "MCP_NOT_PERMITTED", "MCP_WORKSPACE_MISMATCH", "PAK_NOT_PERMITTED", "ACTIONS_NOT_GRANTABLE", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_IN_PROGRESS", "WEBHOOK_ENDPOINT_LIMIT", "WEBHOOK_ENDPOINT_NOT_FOUND", "WEBHOOK_ENDPOINT_NOT_SUBSCRIBED", "WEBHOOK_EVENT_NOT_FOUND", "WEBHOOK_EVENT_TYPE_UNKNOWN", "NOTIFICATION_TYPE_NOT_FOUND", "NOTIFICATION_TYPE_ARCHIVED", "RECIPIENT_NOT_FOUND", "TOO_MANY_RECIPIENTS", "DATA_TOO_LARGE", "TEMPLATE_MISSING", "TEMPLATE_INVALID", "CHANNEL_NOT_CONFIGURED", "CREDENTIAL_INVALID", "CREDENTIAL_NOT_FOUND", "CREDENTIAL_MISMATCH", "DEVICE_TOKEN_INVALID", "WEBPUSH_ENDPOINT_NOT_ALLOWED", "RECIPIENT_TOKEN_INVALID", "RECIPIENT_TOKEN_EXPIRED", "RECIPIENT_TOKEN_SCOPE", "ORIGIN_NOT_ALLOWED", "STREAM_LIMIT", "LIMIT_EXCEEDED", "BATCHED_TYPE_NOT_SCHEDULABLE", "BATCH_NOT_FOUND", "BATCH_NOT_OPEN", "SEND_AT_OUT_OF_RANGE", "UNSAFE_URL", "AUTH_USER_ALREADY_LINKED", "DEVICE_NOT_FOUND", "CATEGORY_NOT_FOUND", "CATEGORY_KEY_TAKEN", "CATEGORY_IN_USE", "NOTIFICATION_TYPE_KEY_TAKEN", "TEMPLATE_NOT_FOUND", "TEMPLATE_VERSION_NOT_FOUND", "PREFERENCE_LOCKED", "NOTIFICATION_NOT_FOUND", "DELIVERY_NOT_FOUND", "CONFIRMATION_REQUIRED", "INBOX_ITEM_NOT_FOUND", "RECIPIENT_ERASED", "DEVICE_MOVE_LIMIT"];
9
9
  };
10
10
 
11
11
  // Generated by scripts/gen-sdk.mjs from Specs/notify.json. Do not edit.
@@ -194,6 +194,66 @@ type paths = {
194
194
  patch?: never;
195
195
  trace?: never;
196
196
  };
197
+ "/v1/workspaces/{workspace_id}/batches": {
198
+ parameters: {
199
+ query?: never;
200
+ header?: never;
201
+ path?: never;
202
+ cookie?: never;
203
+ };
204
+ /**
205
+ * List batches
206
+ * @description Batches of notification types with `batch` (a window or a digest), newest first: one per recipient and key value while collecting (`open`), then `flushed` once its one message went out. Filter by `recipient`, `type` and `state`. Pass `next_cursor` as `cursor` until `has_more` is false.
207
+ */
208
+ get: operations["BatchesController_list"];
209
+ put?: never;
210
+ post?: never;
211
+ delete?: never;
212
+ options?: never;
213
+ head?: never;
214
+ patch?: never;
215
+ trace?: never;
216
+ };
217
+ "/v1/workspaces/{workspace_id}/batches/{batch_id}": {
218
+ parameters: {
219
+ query?: never;
220
+ header?: never;
221
+ path?: never;
222
+ cookie?: never;
223
+ };
224
+ /**
225
+ * Get a batch
226
+ * @description The notifications collected in it, its deliveries (while open, `scheduled: batched`; after it closes, one carrier per channel with its outcome, the rest `skipped: batched_into`), and the `batch` data templates got.
227
+ */
228
+ get: operations["BatchesController_retrieve"];
229
+ put?: never;
230
+ post?: never;
231
+ delete?: never;
232
+ options?: never;
233
+ head?: never;
234
+ patch?: never;
235
+ trace?: never;
236
+ };
237
+ "/v1/workspaces/{workspace_id}/batches/{batch_id}/flush": {
238
+ parameters: {
239
+ query?: never;
240
+ header?: never;
241
+ path?: never;
242
+ cookie?: never;
243
+ };
244
+ get?: never;
245
+ put?: never;
246
+ /**
247
+ * Close a batch now
248
+ * @description Sends an open batch now instead of at its window end or digest time: one message per batched channel, rendered with everything collected so far. Preferences, quiet hours, the recipient budgets and the type throttle apply as for any send. Useful to test a digest template without waiting for the morning.
249
+ */
250
+ post: operations["BatchesController_flush"];
251
+ delete?: never;
252
+ options?: never;
253
+ head?: never;
254
+ patch?: never;
255
+ trace?: never;
256
+ };
197
257
  "/v1/workspaces/{workspace_id}/categories": {
198
258
  parameters: {
199
259
  query?: never;
@@ -877,6 +937,26 @@ type paths = {
877
937
  patch?: never;
878
938
  trace?: never;
879
939
  };
940
+ "/v1/workspaces/{workspace_id}/recipients/{external_id}/preference-link": {
941
+ parameters: {
942
+ query?: never;
943
+ header?: never;
944
+ path?: never;
945
+ cookie?: never;
946
+ };
947
+ get?: never;
948
+ put?: never;
949
+ /**
950
+ * Create a hosted preference page link
951
+ * @description Returns a signed link to a page, hosted by Notify in your workspace's branding (`branding` in settings), where this recipient switches each category on or off per channel, sets quiet hours and a time zone, or unsubscribes from everything except critical types. It needs no sign-in, so it works from any email, also for people who never open your app. The link is valid for 365 days. Changes are recorded in the recipient's consent history with source `hosted_page`. Each call returns a fresh link and changes nothing, so it takes no `Idempotency-Key`.
952
+ */
953
+ post: operations["PreferenceLinkController_create"];
954
+ delete?: never;
955
+ options?: never;
956
+ head?: never;
957
+ patch?: never;
958
+ trace?: never;
959
+ };
880
960
  "/v1/workspaces/{workspace_id}/recipients/{external_id}/preferences": {
881
961
  parameters: {
882
962
  query?: never;
@@ -1258,6 +1338,196 @@ type components = {
1258
1338
  ApnsCredentialEnvironment: "sandbox" | "production" | "both";
1259
1339
  /** @enum {string} */
1260
1340
  ApnsEnvironment: "sandbox" | "production";
1341
+ BatchDeliveryDto: {
1342
+ /** @description Channel. */
1343
+ channel: string;
1344
+ /**
1345
+ * Format: uuid
1346
+ * @description The delivery.
1347
+ */
1348
+ id: string;
1349
+ /**
1350
+ * Format: uuid
1351
+ * @description The notification it belongs to.
1352
+ */
1353
+ notification_id: string;
1354
+ /** @description Reason: `batched` while the batch is open; after it closes, the carrier has its send outcome and the others `batched_into`. */
1355
+ reason: string | null;
1356
+ /** @description State. */
1357
+ state: string;
1358
+ };
1359
+ BatchDetailDto: {
1360
+ /** @description Its deliveries on the batched channels: while open, one `scheduled: batched` per notification and channel; after the flush, the carrier per channel with its outcome. */
1361
+ deliveries: components["schemas"]["BatchDeliveryDto"][];
1362
+ /**
1363
+ * Format: date-time
1364
+ * @description When it closes (or closed): the window end or the digest time. A sliding window moves it.
1365
+ */
1366
+ flush_at: string;
1367
+ /**
1368
+ * Format: date-time
1369
+ * @description When it was closed.
1370
+ */
1371
+ flushed_at: string | null;
1372
+ /**
1373
+ * Format: uuid
1374
+ * @description The batch id.
1375
+ */
1376
+ id: string;
1377
+ /** @description Notifications in the batch. */
1378
+ item_count: number;
1379
+ /**
1380
+ * @description The value of the type's batch `key` in the sends (empty: one batch per recipient).
1381
+ * @example p_42
1382
+ */
1383
+ key: string;
1384
+ /** @description The notifications in the batch, oldest first (the first 100). */
1385
+ notification_ids: string[];
1386
+ /**
1387
+ * Format: date-time
1388
+ * @description When the first notification opened it.
1389
+ */
1390
+ opened_at: string;
1391
+ /** @description What templates got as `batch` when it closed (`count`, `items`, `actors`, …); null while open. */
1392
+ payload: {
1393
+ [key: string]: unknown;
1394
+ } | null;
1395
+ /**
1396
+ * @description The recipient external id (null once erased).
1397
+ * @example user_123
1398
+ */
1399
+ recipient: string | null;
1400
+ /** @description `open` (collecting), `flushed` (sent as one message), `cancelled` (every notification in it was cancelled). */
1401
+ state: components["schemas"]["NotifyBatchState"];
1402
+ /**
1403
+ * @description The notification type key.
1404
+ * @example comment.created
1405
+ */
1406
+ type: string;
1407
+ };
1408
+ BatchDto: {
1409
+ /**
1410
+ * @description `collapse`: the inbox shows one item per open batch, replaced (and unread again) as notifications join it, rendered with `batch.*`. `each`: every notification gets its own inbox item at once. Either way the inbox never waits.
1411
+ * @default collapse
1412
+ */
1413
+ inbox?: components["schemas"]["NotifyBatchInboxMode"];
1414
+ /**
1415
+ * @description A path into the send's `data` (`post_id`, `thread.id`): one batch per value, so "3 new comments on Post A" and "2 on Post B" stay apart. Left out: one batch per recipient.
1416
+ * @example post_id
1417
+ */
1418
+ key?: string | null;
1419
+ /**
1420
+ * @description How many notifications templates get in `batch.items` (newest first). `batch.count` always counts all of them.
1421
+ * @default 10
1422
+ */
1423
+ max_items?: number;
1424
+ /**
1425
+ * @description Sliding windows: the latest a batch closes, in seconds after its first notification. Default: `window_seconds`.
1426
+ * @example 3600
1427
+ */
1428
+ max_window_seconds?: number | null;
1429
+ /** @description `window`: collect for `window_seconds` after the first notification (or after the latest, with `sliding`), then send one message. `digest`: collect until the next `schedule` time in the recipient's time zone. */
1430
+ mode: components["schemas"]["NotifyBatchMode"];
1431
+ /** @description Digest mode: when the digest goes out. */
1432
+ schedule?: components["schemas"]["BatchScheduleDto"] | null;
1433
+ /**
1434
+ * @description Window mode: every new notification restarts the window (a burst goes out once it is quiet), up to `max_window_seconds` after the first.
1435
+ * @default false
1436
+ */
1437
+ sliding?: boolean;
1438
+ /**
1439
+ * @description Window mode: how long a batch collects, in seconds.
1440
+ * @example 300
1441
+ */
1442
+ window_seconds?: number | null;
1443
+ };
1444
+ BatchListResponseDto: {
1445
+ /** @description Batches, newest first. */
1446
+ data: components["schemas"]["BatchSummaryDto"][];
1447
+ /** @description The cursor for the next page. */
1448
+ pagination: components["schemas"]["PaginationDto"];
1449
+ };
1450
+ BatchScheduleDto: {
1451
+ /** @description `daily`, or `weekly` on `weekday`. */
1452
+ frequency: components["schemas"]["NotifyDigestFrequency"];
1453
+ /**
1454
+ * @description Local time the digest goes out, `HH:MM` 24-hour, in the recipient time zone (else the workspace default, else UTC).
1455
+ * @example 09:00
1456
+ */
1457
+ time: string;
1458
+ /** @description Weekly digests only: the day it goes out. */
1459
+ weekday?: components["schemas"]["NotifyWeekday"] | null;
1460
+ };
1461
+ BatchScheduleViewDto: {
1462
+ /** @description Daily or weekly. */
1463
+ frequency: components["schemas"]["NotifyDigestFrequency"];
1464
+ /**
1465
+ * @description Local time, `HH:MM`.
1466
+ * @example 09:00
1467
+ */
1468
+ time: string;
1469
+ /** @description Weekly: the day. */
1470
+ weekday: components["schemas"]["NotifyWeekday"] | null;
1471
+ };
1472
+ BatchSummaryDto: {
1473
+ /**
1474
+ * Format: date-time
1475
+ * @description When it closes (or closed): the window end or the digest time. A sliding window moves it.
1476
+ */
1477
+ flush_at: string;
1478
+ /**
1479
+ * Format: date-time
1480
+ * @description When it was closed.
1481
+ */
1482
+ flushed_at: string | null;
1483
+ /**
1484
+ * Format: uuid
1485
+ * @description The batch id.
1486
+ */
1487
+ id: string;
1488
+ /** @description Notifications in the batch. */
1489
+ item_count: number;
1490
+ /**
1491
+ * @description The value of the type's batch `key` in the sends (empty: one batch per recipient).
1492
+ * @example p_42
1493
+ */
1494
+ key: string;
1495
+ /**
1496
+ * Format: date-time
1497
+ * @description When the first notification opened it.
1498
+ */
1499
+ opened_at: string;
1500
+ /**
1501
+ * @description The recipient external id (null once erased).
1502
+ * @example user_123
1503
+ */
1504
+ recipient: string | null;
1505
+ /** @description `open` (collecting), `flushed` (sent as one message), `cancelled` (every notification in it was cancelled). */
1506
+ state: components["schemas"]["NotifyBatchState"];
1507
+ /**
1508
+ * @description The notification type key.
1509
+ * @example comment.created
1510
+ */
1511
+ type: string;
1512
+ };
1513
+ BatchViewDto: {
1514
+ /** @description How the inbox shows a batch. */
1515
+ inbox: components["schemas"]["NotifyBatchInboxMode"];
1516
+ /** @description Data path batches are keyed by; null: one per recipient. */
1517
+ key: string | null;
1518
+ /** @description Items templates get in `batch.items`. */
1519
+ max_items: number;
1520
+ /** @description Sliding cap in seconds. */
1521
+ max_window_seconds: number | null;
1522
+ /** @description Window or digest. */
1523
+ mode: components["schemas"]["NotifyBatchMode"];
1524
+ /** @description Digest schedule (digest mode). */
1525
+ schedule: components["schemas"]["BatchScheduleViewDto"] | null;
1526
+ /** @description Whether each notification restarts the window. */
1527
+ sliding: boolean;
1528
+ /** @description Window length in seconds (window mode). */
1529
+ window_seconds: number | null;
1530
+ };
1261
1531
  BulkRecipientDto: {
1262
1532
  /**
1263
1533
  * Format: uuid
@@ -1581,6 +1851,8 @@ type components = {
1581
1851
  transactional?: boolean;
1582
1852
  };
1583
1853
  CreateNotificationTypeDto: {
1854
+ /** @description Batch notifications of this type per recipient (a window, or a daily/weekly digest): email and push send one message per batch, rendered with `batch.count`, `batch.items` and `batch.actors`; the inbox collapses. Not for critical types, and only with `always` routing (no fallback steps). Null removes it; open batches still close as configured when they were opened. */
1855
+ batch?: components["schemas"]["BatchDto"] | null;
1584
1856
  /**
1585
1857
  * @description Key of the category the type belongs to.
1586
1858
  * @example billing
@@ -1624,6 +1896,13 @@ type components = {
1624
1896
  */
1625
1897
  ttl_seconds?: number;
1626
1898
  };
1899
+ CreatePreferenceLinkDto: {
1900
+ /**
1901
+ * @description A category key. The page then opens with a one-click "Unsubscribe from these emails" for that category, the way the `List-Unsubscribe` header of a Notify email does. Leave it out for a general link (an account settings page, a footer you write yourself).
1902
+ * @example product-updates
1903
+ */
1904
+ category_key?: string;
1905
+ };
1627
1906
  CreateRecipientTokenDto: {
1628
1907
  /**
1629
1908
  * @description Your user id for the recipient (`external_id`). A recipient that does not exist yet is created (bare, or with the `upsert` fields), so you can mint at sign-in without a separate call.
@@ -1852,6 +2131,11 @@ type components = {
1852
2131
  attempts: number;
1853
2132
  /** @description Provider calls, oldest first (no PII, no provider bodies). */
1854
2133
  attempts_log: components["schemas"]["DeliveryAttemptDto"][];
2134
+ /**
2135
+ * Format: uuid
2136
+ * @description The batch this delivery waits in or was sent with (types with `batch`); see `GET /batches/{batch_id}`.
2137
+ */
2138
+ batch_id: string | null;
1855
2139
  /** @description The channel. */
1856
2140
  channel: components["schemas"]["NotifyChannel"];
1857
2141
  /**
@@ -1922,6 +2206,11 @@ type components = {
1922
2206
  DeliveryDto: {
1923
2207
  /** @description Provider calls made. */
1924
2208
  attempts: number;
2209
+ /**
2210
+ * Format: uuid
2211
+ * @description The batch this delivery waits in or was sent with (types with `batch`); see `GET /batches/{batch_id}`.
2212
+ */
2213
+ batch_id: string | null;
1925
2214
  /** @description The channel. */
1926
2215
  channel: components["schemas"]["NotifyChannel"];
1927
2216
  /**
@@ -2479,6 +2768,8 @@ type components = {
2479
2768
  * @description When archived.
2480
2769
  */
2481
2770
  archived_at: string | null;
2771
+ /** @description Batching or digest config; null sends each notification on its own. */
2772
+ batch: components["schemas"]["BatchViewDto"] | null;
2482
2773
  /** @description Category key. */
2483
2774
  category_key: string;
2484
2775
  /** @description Critical. */
@@ -2576,6 +2867,12 @@ type components = {
2576
2867
  /** @description Advice about the uploaded account, e.g. when it is the Firebase Admin SDK account (`firebase-adminsdk-*`), which can do far more than send push. The upload is accepted either way. */
2577
2868
  warnings: string[];
2578
2869
  };
2870
+ FlushBatchResponseDto: {
2871
+ /** @description The batch after closing it. */
2872
+ batch: components["schemas"]["BatchDetailDto"];
2873
+ /** @description Deliveries merged into the carriers (`skipped: batched_into`). */
2874
+ merged: number;
2875
+ };
2579
2876
  GenerateVapidKeysDto: {
2580
2877
  /**
2581
2878
  * @description Required when the workspace already has a VAPID key: replacing it orphans every existing browser subscription (they were made with the old public key). Every web push device is marked `invalid` (`vapid_rotated`) and must subscribe again with the new key; the `@productcraft/notify-js` service worker does this on `pushsubscriptionchange`.
@@ -3058,6 +3355,8 @@ type components = {
3058
3355
  * @description When archived; archived types cannot be sent.
3059
3356
  */
3060
3357
  archived_at: string | null;
3358
+ /** @description Batching or digest config; null sends each notification on its own. */
3359
+ batch: components["schemas"]["BatchViewDto"] | null;
3061
3360
  /**
3062
3361
  * Format: uuid
3063
3362
  * @description Category id.
@@ -3113,6 +3412,58 @@ type components = {
3113
3412
  pagination: components["schemas"]["PaginationDto"];
3114
3413
  };
3115
3414
  /** @enum {string} */
3415
+ NotifyBatchInboxMode: "collapse" | "each";
3416
+ /** @enum {string} */
3417
+ NotifyBatchMode: "window" | "digest";
3418
+ /** @enum {string} */
3419
+ NotifyBatchState: "open" | "flushed" | "cancelled";
3420
+ NotifyBrandingDto: {
3421
+ /**
3422
+ * @description Accent colour for the switches and the Save button, `#rrggbb`. Text on it is black or white, whichever reads better.
3423
+ * @example #4f46e5
3424
+ */
3425
+ accent_color?: string | null;
3426
+ /**
3427
+ * Format: uri
3428
+ * @description An `https://` image shown at the top of the page (at most 32 px high). It is loaded by the visitor's browser from your host.
3429
+ * @example https://acme.example/logo.png
3430
+ */
3431
+ logo_url?: string | null;
3432
+ /**
3433
+ * @description Your product name, shown at the top of the page and in its title. Null: the page says "Notification preferences" only.
3434
+ * @example Acme
3435
+ */
3436
+ name?: string | null;
3437
+ /**
3438
+ * Format: uri
3439
+ * @description Your privacy policy, linked in the page footer (`https://`).
3440
+ * @example https://acme.example/privacy
3441
+ */
3442
+ privacy_url?: string | null;
3443
+ };
3444
+ NotifyBrandingViewDto: {
3445
+ /**
3446
+ * @description Accent colour, `#rrggbb`.
3447
+ * @example #4f46e5
3448
+ */
3449
+ accent_color: string | null;
3450
+ /**
3451
+ * Format: uri
3452
+ * @description Logo image (`https://`).
3453
+ */
3454
+ logo_url: string | null;
3455
+ /**
3456
+ * @description Product name shown on the page.
3457
+ * @example Acme
3458
+ */
3459
+ name: string | null;
3460
+ /**
3461
+ * Format: uri
3462
+ * @description Privacy policy linked in the footer.
3463
+ */
3464
+ privacy_url: string | null;
3465
+ };
3466
+ /** @enum {string} */
3116
3467
  NotifyChannel: "inbox" | "email" | "push" | "webpush";
3117
3468
  NotifyCredentialInvalidDataDto: {
3118
3469
  /**
@@ -3222,6 +3573,8 @@ type components = {
3222
3573
  * - `rate_limited`: The recipient already received the per-minute maximum of notifications. Fix: Send fewer notifications to one person, or batch them; critical types have their own budget.
3223
3574
  * - `throttled`: The type's own throttle for this recipient was reached. Fix: Raise or remove `throttle` on the notification type if every message must go out.
3224
3575
  * - `read_in_inbox`: The recipient read the inbox item first, so the follow-up was not needed. Fix: Nothing to fix: this is how `after_unread_seconds` works.
3576
+ * - `batched`: The type batches notifications: this one waits in the recipient's open batch, which closes at the delivery's next attempt time (the batch window end or the digest time) and then sends one message for everything in it. Fix: Nothing to fix. To send it sooner, flush the batch (POST /batches/{batch_id}/flush), or remove `batch` from the type.
3577
+ * - `batched_into`: Sent together with the rest of its batch: the batch's message went out in another delivery of the same batch (same recipient and channel). Fix: Nothing to fix. Look up the batch (GET /batches/{batch_id}) to see the delivery that carried it.
3225
3578
  * - `awaiting_unread`: A follow-up step waiting to see whether the recipient reads the inbox item first. Fix: Nothing to fix: it is sent when the `after_unread_seconds` timer ends and the item is still unread, and skipped as `read_in_inbox` otherwise.
3226
3579
  * - `actor_excluded`: The recipient is the actor who caused the notification. Fix: Pass `exclude_actor: false` to notify the actor too.
3227
3580
  * - `recipient_not_found`: No recipient with this external id exists in the workspace. Fix: Create the recipient first (`PUT /recipients/{external_id}`), pass it inline with an email, or send `create_missing: true`.
@@ -3237,7 +3590,7 @@ type components = {
3237
3590
  * - `provider_error`: The provider kept failing until retries ran out. Fix: Check the attempts for the provider status and code.
3238
3591
  * @enum {string}
3239
3592
  */
3240
- NotifyDeliveryReason: "suppressed_preference" | "default_off" | "unsubscribed_all" | "held_quiet_hours" | "scheduled_send" | "no_device" | "no_address" | "email_invalid" | "email_complained" | "email_paused" | "email_budget" | "email_backlog_full" | "channel_not_configured" | "channel_restricted" | "type_archived" | "credential_invalid" | "template_missing" | "rate_limited" | "throttled" | "read_in_inbox" | "awaiting_unread" | "actor_excluded" | "recipient_not_found" | "recipient_erased" | "mail_suppressed" | "mail_refused" | "pruned" | "payload_too_large" | "credential_error" | "circuit_open" | "expired" | "cancelled" | "provider_error";
3593
+ NotifyDeliveryReason: "suppressed_preference" | "default_off" | "unsubscribed_all" | "held_quiet_hours" | "scheduled_send" | "no_device" | "no_address" | "email_invalid" | "email_complained" | "email_paused" | "email_budget" | "email_backlog_full" | "channel_not_configured" | "channel_restricted" | "type_archived" | "credential_invalid" | "template_missing" | "rate_limited" | "throttled" | "read_in_inbox" | "awaiting_unread" | "batched" | "batched_into" | "actor_excluded" | "recipient_not_found" | "recipient_erased" | "mail_suppressed" | "mail_refused" | "pruned" | "payload_too_large" | "credential_error" | "circuit_open" | "expired" | "cancelled" | "provider_error";
3241
3594
  NotifyDeviceEventDataDto: {
3242
3595
  /**
3243
3596
  * @description The device channel.
@@ -3270,6 +3623,8 @@ type components = {
3270
3623
  /** @description The recipient the device belongs to now. */
3271
3624
  recipient: components["schemas"]["NotifyWebhookRecipientDto"];
3272
3625
  };
3626
+ /** @enum {string} */
3627
+ NotifyDigestFrequency: "daily" | "weekly";
3273
3628
  NotifyEmailAutoPausedDataDto: {
3274
3629
  /**
3275
3630
  * @description Hard bounces in the window.
@@ -3295,7 +3650,7 @@ type components = {
3295
3650
  /** @enum {string} */
3296
3651
  NotifyEmailPauseReason: "complaints" | "bounces";
3297
3652
  /** @description Error codes this API returns (open set: a client must accept codes it does not know; new codes are not a breaking change). Each is documented at https://productcraft.co/docs/errors#<code>. */
3298
- NotifyErrorCode: ("BAD_REQUEST" | "VALIDATION_ERROR" | "UNAUTHORIZED" | "PAYMENT_REQUIRED" | "FORBIDDEN" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "NOT_ACCEPTABLE" | "REQUEST_TIMEOUT" | "CONFLICT" | "GONE" | "PRECONDITION_FAILED" | "PAYLOAD_TOO_LARGE" | "UNSUPPORTED_MEDIA_TYPE" | "UNPROCESSABLE_ENTITY" | "PRECONDITION_REQUIRED" | "RATE_LIMITED" | "INTERNAL_SERVER_ERROR" | "NOT_IMPLEMENTED" | "BAD_GATEWAY" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "SERVICE_NOT_ENABLED" | "INVALID_CREDENTIALS" | "SESSION_REVOKED" | "MCP_NOT_PERMITTED" | "MCP_WORKSPACE_MISMATCH" | "PAK_NOT_PERMITTED" | "ACTIONS_NOT_GRANTABLE" | "IDEMPOTENCY_KEY_REUSE" | "IDEMPOTENCY_KEY_REQUIRED" | "IDEMPOTENCY_IN_PROGRESS" | "WEBHOOK_ENDPOINT_LIMIT" | "WEBHOOK_ENDPOINT_NOT_FOUND" | "WEBHOOK_ENDPOINT_NOT_SUBSCRIBED" | "WEBHOOK_EVENT_NOT_FOUND" | "WEBHOOK_EVENT_TYPE_UNKNOWN" | "NOTIFICATION_TYPE_NOT_FOUND" | "NOTIFICATION_TYPE_ARCHIVED" | "RECIPIENT_NOT_FOUND" | "TOO_MANY_RECIPIENTS" | "DATA_TOO_LARGE" | "TEMPLATE_MISSING" | "TEMPLATE_INVALID" | "CHANNEL_NOT_CONFIGURED" | "CREDENTIAL_INVALID" | "CREDENTIAL_NOT_FOUND" | "CREDENTIAL_MISMATCH" | "DEVICE_TOKEN_INVALID" | "WEBPUSH_ENDPOINT_NOT_ALLOWED" | "RECIPIENT_TOKEN_INVALID" | "RECIPIENT_TOKEN_EXPIRED" | "RECIPIENT_TOKEN_SCOPE" | "ORIGIN_NOT_ALLOWED" | "STREAM_LIMIT" | "LIMIT_EXCEEDED" | "SEND_AT_OUT_OF_RANGE" | "UNSAFE_URL" | "AUTH_USER_ALREADY_LINKED" | "DEVICE_NOT_FOUND" | "CATEGORY_NOT_FOUND" | "CATEGORY_KEY_TAKEN" | "CATEGORY_IN_USE" | "NOTIFICATION_TYPE_KEY_TAKEN" | "TEMPLATE_NOT_FOUND" | "TEMPLATE_VERSION_NOT_FOUND" | "PREFERENCE_LOCKED" | "NOTIFICATION_NOT_FOUND" | "DELIVERY_NOT_FOUND" | "CONFIRMATION_REQUIRED" | "INBOX_ITEM_NOT_FOUND" | "RECIPIENT_ERASED" | "DEVICE_MOVE_LIMIT") | string;
3653
+ NotifyErrorCode: ("BAD_REQUEST" | "VALIDATION_ERROR" | "UNAUTHORIZED" | "PAYMENT_REQUIRED" | "FORBIDDEN" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "NOT_ACCEPTABLE" | "REQUEST_TIMEOUT" | "CONFLICT" | "GONE" | "PRECONDITION_FAILED" | "PAYLOAD_TOO_LARGE" | "UNSUPPORTED_MEDIA_TYPE" | "UNPROCESSABLE_ENTITY" | "PRECONDITION_REQUIRED" | "RATE_LIMITED" | "INTERNAL_SERVER_ERROR" | "NOT_IMPLEMENTED" | "BAD_GATEWAY" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "SERVICE_NOT_ENABLED" | "INVALID_CREDENTIALS" | "SESSION_REVOKED" | "MCP_NOT_PERMITTED" | "MCP_WORKSPACE_MISMATCH" | "PAK_NOT_PERMITTED" | "ACTIONS_NOT_GRANTABLE" | "IDEMPOTENCY_KEY_REUSE" | "IDEMPOTENCY_KEY_REQUIRED" | "IDEMPOTENCY_IN_PROGRESS" | "WEBHOOK_ENDPOINT_LIMIT" | "WEBHOOK_ENDPOINT_NOT_FOUND" | "WEBHOOK_ENDPOINT_NOT_SUBSCRIBED" | "WEBHOOK_EVENT_NOT_FOUND" | "WEBHOOK_EVENT_TYPE_UNKNOWN" | "NOTIFICATION_TYPE_NOT_FOUND" | "NOTIFICATION_TYPE_ARCHIVED" | "RECIPIENT_NOT_FOUND" | "TOO_MANY_RECIPIENTS" | "DATA_TOO_LARGE" | "TEMPLATE_MISSING" | "TEMPLATE_INVALID" | "CHANNEL_NOT_CONFIGURED" | "CREDENTIAL_INVALID" | "CREDENTIAL_NOT_FOUND" | "CREDENTIAL_MISMATCH" | "DEVICE_TOKEN_INVALID" | "WEBPUSH_ENDPOINT_NOT_ALLOWED" | "RECIPIENT_TOKEN_INVALID" | "RECIPIENT_TOKEN_EXPIRED" | "RECIPIENT_TOKEN_SCOPE" | "ORIGIN_NOT_ALLOWED" | "STREAM_LIMIT" | "LIMIT_EXCEEDED" | "BATCHED_TYPE_NOT_SCHEDULABLE" | "BATCH_NOT_FOUND" | "BATCH_NOT_OPEN" | "SEND_AT_OUT_OF_RANGE" | "UNSAFE_URL" | "AUTH_USER_ALREADY_LINKED" | "DEVICE_NOT_FOUND" | "CATEGORY_NOT_FOUND" | "CATEGORY_KEY_TAKEN" | "CATEGORY_IN_USE" | "NOTIFICATION_TYPE_KEY_TAKEN" | "TEMPLATE_NOT_FOUND" | "TEMPLATE_VERSION_NOT_FOUND" | "PREFERENCE_LOCKED" | "NOTIFICATION_NOT_FOUND" | "DELIVERY_NOT_FOUND" | "CONFIRMATION_REQUIRED" | "INBOX_ITEM_NOT_FOUND" | "RECIPIENT_ERASED" | "DEVICE_MOVE_LIMIT") | string;
3299
3654
  NotifyInboxItemEventDataDto: {
3300
3655
  /**
3301
3656
  * Format: uuid
@@ -3373,6 +3728,8 @@ type components = {
3373
3728
  /** @enum {string} */
3374
3729
  NotifyRecipientDeletionCause: "api" | "auth_user_deleted";
3375
3730
  NotifySettingsDto: {
3731
+ /** @description Name, logo, accent colour and privacy link of the hosted preference page (`/v1/preferences/{token}`). Null: the page is unbranded. */
3732
+ branding: components["schemas"]["NotifyBrandingViewDto"] | null;
3376
3733
  /**
3377
3734
  * @description Browser origins allowed to call the client API (`/v1/client/…`) with a recipient token. Empty: only `http://localhost` (any port) is accepted, for development. Calls without an `Origin` header (native apps) are not origin-checked.
3378
3735
  * @example [
@@ -3524,15 +3881,35 @@ type components = {
3524
3881
  */
3525
3882
  id: string;
3526
3883
  };
3884
+ /** @enum {string} */
3885
+ NotifyWeekday: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday";
3527
3886
  PaginationDto: {
3528
3887
  /** @description Whether another page follows. */
3529
3888
  has_more: boolean;
3530
3889
  /** @description Pass as `cursor` to get the next page; null on the last page. */
3531
3890
  next_cursor: string | null;
3532
3891
  };
3892
+ PlanBatchDto: {
3893
+ /**
3894
+ * Format: uuid
3895
+ * @description The open batch it would join; null when it would open a new one.
3896
+ */
3897
+ batch_id: string | null;
3898
+ /**
3899
+ * Format: date-time
3900
+ * @description When the batch closes and sends one message (a sliding window may move it).
3901
+ */
3902
+ flush_at: string;
3903
+ /** @description Notifications in the batch once this one joins. */
3904
+ item_count: number;
3905
+ /** @description The batch key value (empty: one batch per recipient). */
3906
+ key: string;
3907
+ };
3533
3908
  /** @enum {string} */
3534
3909
  PlanDecision: "deliver" | "schedule" | "skip";
3535
3910
  PlanRowDto: {
3911
+ /** @description Batched types: the batch this channel would wait in (`reason: batched`). */
3912
+ batch?: components["schemas"]["PlanBatchDto"];
3536
3913
  /** @description The channel. */
3537
3914
  channel: components["schemas"]["NotifyChannel"];
3538
3915
  /** @description `deliver`, `schedule` (held, sent later) or `skip`. */
@@ -3594,6 +3971,21 @@ type components = {
3594
3971
  };
3595
3972
  /** @enum {string} */
3596
3973
  PreferenceChannel: "inbox" | "email" | "push" | "webpush" | "*";
3974
+ PreferenceLinkDto: {
3975
+ /** @description The category the link offers one-click unsubscribe from, if any. */
3976
+ category_key: string | null;
3977
+ /**
3978
+ * Format: date-time
3979
+ * @description When the link stops working (365 days after it was made). Make a new one per email; old ones keep working until then.
3980
+ */
3981
+ expires_at: string;
3982
+ /**
3983
+ * Format: uri
3984
+ * @description The hosted preference page for this recipient. Anyone holding it can change this recipient's preferences (never critical types), so send it only to the recipient, for example in an email footer. Opening it changes nothing; the page saves only when the person presses a button.
3985
+ * @example https://api.notify.productcraft.co/v1/preferences/p1.AQ…
3986
+ */
3987
+ url: string;
3988
+ };
3597
3989
  /** @enum {string} */
3598
3990
  PreferenceScope: "all" | "category" | "type";
3599
3991
  PreferenceSetDto: {
@@ -3891,6 +4283,8 @@ type components = {
3891
4283
  title: string;
3892
4284
  };
3893
4285
  ReplaceNotificationTypeDto: {
4286
+ /** @description Batch notifications of this type per recipient (a window, or a daily/weekly digest): email and push send one message per batch, rendered with `batch.count`, `batch.items` and `batch.actors`; the inbox collapses. Not for critical types, and only with `always` routing (no fallback steps). Null removes it; open batches still close as configured when they were opened. */
4287
+ batch?: components["schemas"]["BatchDto"] | null;
3894
4288
  /**
3895
4289
  * @description Key of the category; it must exist (create categories first, or apply an export).
3896
4290
  * @example billing
@@ -4261,6 +4655,11 @@ type components = {
4261
4655
  TimelineEntryDto: {
4262
4656
  /** @description Provider calls made. */
4263
4657
  attempts: number;
4658
+ /**
4659
+ * Format: uuid
4660
+ * @description The batch this delivery waits in or was sent with (types with `batch`); see `GET /batches/{batch_id}`.
4661
+ */
4662
+ batch_id: string | null;
4264
4663
  /** @description The channel. */
4265
4664
  channel: components["schemas"]["NotifyChannel"];
4266
4665
  /**
@@ -4377,6 +4776,8 @@ type components = {
4377
4776
  unsubscribed_all?: boolean;
4378
4777
  };
4379
4778
  UpdateNotificationTypeDto: {
4779
+ /** @description Batch notifications of this type per recipient (a window, or a daily/weekly digest): email and push send one message per batch, rendered with `batch.count`, `batch.items` and `batch.actors`; the inbox collapses. Not for critical types, and only with `always` routing (no fallback steps). Null removes it; open batches still close as configured when they were opened. */
4780
+ batch?: components["schemas"]["BatchDto"] | null;
4380
4781
  /**
4381
4782
  * @description Key of the category the type belongs to (preferences are per category).
4382
4783
  * @example billing
@@ -4416,6 +4817,8 @@ type components = {
4416
4817
  ttl_seconds?: number;
4417
4818
  };
4418
4819
  UpdateNotifySettingsDto: {
4820
+ /** @description Replaces the hosted preference page branding (fields you leave out are cleared). `null` removes it. */
4821
+ branding?: components["schemas"]["NotifyBrandingDto"] | null;
4419
4822
  /**
4420
4823
  * @description Replaces the browser origins allowed to call the client API: `https://host[:port]` (or `http://localhost[:port]`), no path. `[]` goes back to localhost only.
4421
4824
  * @example [
@@ -5648,7 +6051,263 @@ interface operations {
5648
6051
  "application/json": components["schemas"]["ErrorResponseDto"];
5649
6052
  };
5650
6053
  };
5651
- /** @description `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
6054
+ /** @description `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
6055
+ 429: {
6056
+ headers: {
6057
+ "Retry-After": components["headers"]["Retry-After"];
6058
+ "Retry-After-long": components["headers"]["Retry-After-long"];
6059
+ "Retry-After-short": components["headers"]["Retry-After-short"];
6060
+ "X-Request-Id": components["headers"]["RequestId"];
6061
+ [name: string]: unknown;
6062
+ };
6063
+ content: {
6064
+ "application/json": components["schemas"]["ErrorResponseDto"];
6065
+ };
6066
+ };
6067
+ };
6068
+ };
6069
+ ClientController_updatePreferences: {
6070
+ parameters: {
6071
+ query?: never;
6072
+ header?: never;
6073
+ path?: never;
6074
+ cookie?: never;
6075
+ };
6076
+ requestBody: {
6077
+ content: {
6078
+ "application/json": components["schemas"]["UpdateClientPreferencesDto"];
6079
+ };
6080
+ };
6081
+ responses: {
6082
+ /** @description The preferences after the change. */
6083
+ 200: {
6084
+ headers: {
6085
+ "X-RateLimit-Limit-long": components["headers"]["X-RateLimit-Limit-long"];
6086
+ "X-RateLimit-Limit-short": components["headers"]["X-RateLimit-Limit-short"];
6087
+ "X-RateLimit-Remaining-long": components["headers"]["X-RateLimit-Remaining-long"];
6088
+ "X-RateLimit-Remaining-short": components["headers"]["X-RateLimit-Remaining-short"];
6089
+ "X-RateLimit-Reset-long": components["headers"]["X-RateLimit-Reset-long"];
6090
+ "X-RateLimit-Reset-short": components["headers"]["X-RateLimit-Reset-short"];
6091
+ "X-Request-Id": components["headers"]["RequestId"];
6092
+ [name: string]: unknown;
6093
+ };
6094
+ content: {
6095
+ "application/json": components["schemas"]["ClientPreferencesDto"];
6096
+ };
6097
+ };
6098
+ /** @description `VALIDATION_ERROR`: a field is invalid (`errors` names it). */
6099
+ 400: {
6100
+ headers: {
6101
+ "X-Request-Id": components["headers"]["RequestId"];
6102
+ [name: string]: unknown;
6103
+ };
6104
+ content: {
6105
+ "application/json": components["schemas"]["ErrorResponseDto"];
6106
+ };
6107
+ };
6108
+ /** @description `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). */
6109
+ 401: {
6110
+ headers: {
6111
+ "X-Request-Id": components["headers"]["RequestId"];
6112
+ [name: string]: unknown;
6113
+ };
6114
+ content: {
6115
+ "application/json": components["schemas"]["ErrorResponseDto"];
6116
+ };
6117
+ };
6118
+ /** @description `RECIPIENT_TOKEN_SCOPE`: the token lacks the `preferences:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. */
6119
+ 403: {
6120
+ headers: {
6121
+ "X-Request-Id": components["headers"]["RequestId"];
6122
+ [name: string]: unknown;
6123
+ };
6124
+ content: {
6125
+ "application/json": components["schemas"]["ErrorResponseDto"];
6126
+ };
6127
+ };
6128
+ /** @description `PREFERENCE_LOCKED`: the channel is mandatory for the category; `CATEGORY_NOT_FOUND` / `NOTIFICATION_TYPE_NOT_FOUND`: no category or type with that key. */
6129
+ 422: {
6130
+ headers: {
6131
+ "X-Request-Id": components["headers"]["RequestId"];
6132
+ [name: string]: unknown;
6133
+ };
6134
+ content: {
6135
+ "application/json": components["schemas"]["ErrorResponseDto"];
6136
+ };
6137
+ };
6138
+ /** @description `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
6139
+ 429: {
6140
+ headers: {
6141
+ "Retry-After": components["headers"]["Retry-After"];
6142
+ "Retry-After-long": components["headers"]["Retry-After-long"];
6143
+ "Retry-After-short": components["headers"]["Retry-After-short"];
6144
+ "X-Request-Id": components["headers"]["RequestId"];
6145
+ [name: string]: unknown;
6146
+ };
6147
+ content: {
6148
+ "application/json": components["schemas"]["ErrorResponseDto"];
6149
+ };
6150
+ };
6151
+ };
6152
+ };
6153
+ ClientController_vapidPublicKey: {
6154
+ parameters: {
6155
+ query?: never;
6156
+ header?: never;
6157
+ path?: never;
6158
+ cookie?: never;
6159
+ };
6160
+ requestBody?: never;
6161
+ responses: {
6162
+ /** @description The public key. */
6163
+ 200: {
6164
+ headers: {
6165
+ "X-RateLimit-Limit-long": components["headers"]["X-RateLimit-Limit-long"];
6166
+ "X-RateLimit-Limit-short": components["headers"]["X-RateLimit-Limit-short"];
6167
+ "X-RateLimit-Remaining-long": components["headers"]["X-RateLimit-Remaining-long"];
6168
+ "X-RateLimit-Remaining-short": components["headers"]["X-RateLimit-Remaining-short"];
6169
+ "X-RateLimit-Reset-long": components["headers"]["X-RateLimit-Reset-long"];
6170
+ "X-RateLimit-Reset-short": components["headers"]["X-RateLimit-Reset-short"];
6171
+ "X-Request-Id": components["headers"]["RequestId"];
6172
+ [name: string]: unknown;
6173
+ };
6174
+ content: {
6175
+ "application/json": components["schemas"]["VapidPublicKeyDto"];
6176
+ };
6177
+ };
6178
+ /** @description `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). */
6179
+ 401: {
6180
+ headers: {
6181
+ "X-Request-Id": components["headers"]["RequestId"];
6182
+ [name: string]: unknown;
6183
+ };
6184
+ content: {
6185
+ "application/json": components["schemas"]["ErrorResponseDto"];
6186
+ };
6187
+ };
6188
+ /** @description `RECIPIENT_TOKEN_SCOPE`: the token lacks the `devices:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. */
6189
+ 403: {
6190
+ headers: {
6191
+ "X-Request-Id": components["headers"]["RequestId"];
6192
+ [name: string]: unknown;
6193
+ };
6194
+ content: {
6195
+ "application/json": components["schemas"]["ErrorResponseDto"];
6196
+ };
6197
+ };
6198
+ /** @description `CHANNEL_NOT_CONFIGURED`: the workspace has no web push key yet (generate one in the console or with `POST /channels/webpush/vapid-keys`). */
6199
+ 404: {
6200
+ headers: {
6201
+ "X-Request-Id": components["headers"]["RequestId"];
6202
+ [name: string]: unknown;
6203
+ };
6204
+ content: {
6205
+ "application/json": components["schemas"]["ErrorResponseDto"];
6206
+ };
6207
+ };
6208
+ /** @description `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
6209
+ 429: {
6210
+ headers: {
6211
+ "Retry-After": components["headers"]["Retry-After"];
6212
+ "Retry-After-long": components["headers"]["Retry-After-long"];
6213
+ "Retry-After-short": components["headers"]["Retry-After-short"];
6214
+ "X-Request-Id": components["headers"]["RequestId"];
6215
+ [name: string]: unknown;
6216
+ };
6217
+ content: {
6218
+ "application/json": components["schemas"]["ErrorResponseDto"];
6219
+ };
6220
+ };
6221
+ };
6222
+ };
6223
+ BatchesController_list: {
6224
+ parameters: {
6225
+ query?: {
6226
+ /**
6227
+ * @description Only this recipient (external id).
6228
+ * @example user_123
6229
+ */
6230
+ recipient?: string;
6231
+ /**
6232
+ * @description Only this notification type key.
6233
+ * @example comment.created
6234
+ */
6235
+ type?: string;
6236
+ /**
6237
+ * @description Only batches in this state.
6238
+ * @example open
6239
+ */
6240
+ state?: components["schemas"]["NotifyBatchState"];
6241
+ /**
6242
+ * @description Opaque cursor for pagination: the `next_cursor` of the previous page.
6243
+ * @example eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ
6244
+ */
6245
+ cursor?: string;
6246
+ /**
6247
+ * @description Page size.
6248
+ * @example 25
6249
+ */
6250
+ limit?: number;
6251
+ };
6252
+ header?: never;
6253
+ path: {
6254
+ /**
6255
+ * @description Id of the workspace.
6256
+ * @example 3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
6257
+ */
6258
+ workspace_id: string;
6259
+ };
6260
+ cookie?: never;
6261
+ };
6262
+ requestBody?: never;
6263
+ responses: {
6264
+ /** @description A page of batches. */
6265
+ 200: {
6266
+ headers: {
6267
+ "X-RateLimit-Limit-long": components["headers"]["X-RateLimit-Limit-long"];
6268
+ "X-RateLimit-Limit-short": components["headers"]["X-RateLimit-Limit-short"];
6269
+ "X-RateLimit-Remaining-long": components["headers"]["X-RateLimit-Remaining-long"];
6270
+ "X-RateLimit-Remaining-short": components["headers"]["X-RateLimit-Remaining-short"];
6271
+ "X-RateLimit-Reset-long": components["headers"]["X-RateLimit-Reset-long"];
6272
+ "X-RateLimit-Reset-short": components["headers"]["X-RateLimit-Reset-short"];
6273
+ "X-Request-Id": components["headers"]["RequestId"];
6274
+ [name: string]: unknown;
6275
+ };
6276
+ content: {
6277
+ "application/json": components["schemas"]["BatchListResponseDto"];
6278
+ };
6279
+ };
6280
+ /** @description `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor. */
6281
+ 400: {
6282
+ headers: {
6283
+ "X-Request-Id": components["headers"]["RequestId"];
6284
+ [name: string]: unknown;
6285
+ };
6286
+ content: {
6287
+ "application/json": components["schemas"]["ErrorResponseDto"];
6288
+ };
6289
+ };
6290
+ /** @description Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). */
6291
+ 401: {
6292
+ headers: {
6293
+ "X-Request-Id": components["headers"]["RequestId"];
6294
+ [name: string]: unknown;
6295
+ };
6296
+ content: {
6297
+ "application/json": components["schemas"]["ErrorResponseDto"];
6298
+ };
6299
+ };
6300
+ /** @description The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). */
6301
+ 403: {
6302
+ headers: {
6303
+ "X-Request-Id": components["headers"]["RequestId"];
6304
+ [name: string]: unknown;
6305
+ };
6306
+ content: {
6307
+ "application/json": components["schemas"]["ErrorResponseDto"];
6308
+ };
6309
+ };
6310
+ /** @description More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
5652
6311
  429: {
5653
6312
  headers: {
5654
6313
  "Retry-After": components["headers"]["Retry-After"];
@@ -5663,20 +6322,27 @@ interface operations {
5663
6322
  };
5664
6323
  };
5665
6324
  };
5666
- ClientController_updatePreferences: {
6325
+ BatchesController_retrieve: {
5667
6326
  parameters: {
5668
6327
  query?: never;
5669
6328
  header?: never;
5670
- path?: never;
5671
- cookie?: never;
5672
- };
5673
- requestBody: {
5674
- content: {
5675
- "application/json": components["schemas"]["UpdateClientPreferencesDto"];
6329
+ path: {
6330
+ /**
6331
+ * @description Id of the workspace.
6332
+ * @example 3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
6333
+ */
6334
+ workspace_id: string;
6335
+ /**
6336
+ * @description The batch id (from a delivery's `batch_id`, or the list).
6337
+ * @example 3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
6338
+ */
6339
+ batch_id: string;
5676
6340
  };
6341
+ cookie?: never;
5677
6342
  };
6343
+ requestBody?: never;
5678
6344
  responses: {
5679
- /** @description The preferences after the change. */
6345
+ /** @description The batch. */
5680
6346
  200: {
5681
6347
  headers: {
5682
6348
  "X-RateLimit-Limit-long": components["headers"]["X-RateLimit-Limit-long"];
@@ -5689,20 +6355,10 @@ interface operations {
5689
6355
  [name: string]: unknown;
5690
6356
  };
5691
6357
  content: {
5692
- "application/json": components["schemas"]["ClientPreferencesDto"];
5693
- };
5694
- };
5695
- /** @description `VALIDATION_ERROR`: a field is invalid (`errors` names it). */
5696
- 400: {
5697
- headers: {
5698
- "X-Request-Id": components["headers"]["RequestId"];
5699
- [name: string]: unknown;
5700
- };
5701
- content: {
5702
- "application/json": components["schemas"]["ErrorResponseDto"];
6358
+ "application/json": components["schemas"]["BatchDetailDto"];
5703
6359
  };
5704
6360
  };
5705
- /** @description `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). */
6361
+ /** @description Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). */
5706
6362
  401: {
5707
6363
  headers: {
5708
6364
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5712,7 +6368,7 @@ interface operations {
5712
6368
  "application/json": components["schemas"]["ErrorResponseDto"];
5713
6369
  };
5714
6370
  };
5715
- /** @description `RECIPIENT_TOKEN_SCOPE`: the token lacks the `preferences:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. */
6371
+ /** @description The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). */
5716
6372
  403: {
5717
6373
  headers: {
5718
6374
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5722,8 +6378,8 @@ interface operations {
5722
6378
  "application/json": components["schemas"]["ErrorResponseDto"];
5723
6379
  };
5724
6380
  };
5725
- /** @description `PREFERENCE_LOCKED`: the channel is mandatory for the category; `CATEGORY_NOT_FOUND` / `NOTIFICATION_TYPE_NOT_FOUND`: no category or type with that key. */
5726
- 422: {
6381
+ /** @description `BATCH_NOT_FOUND`: no batch with this id in this workspace. */
6382
+ 404: {
5727
6383
  headers: {
5728
6384
  "X-Request-Id": components["headers"]["RequestId"];
5729
6385
  [name: string]: unknown;
@@ -5732,7 +6388,7 @@ interface operations {
5732
6388
  "application/json": components["schemas"]["ErrorResponseDto"];
5733
6389
  };
5734
6390
  };
5735
- /** @description `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
6391
+ /** @description More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
5736
6392
  429: {
5737
6393
  headers: {
5738
6394
  "Retry-After": components["headers"]["Retry-After"];
@@ -5747,18 +6403,34 @@ interface operations {
5747
6403
  };
5748
6404
  };
5749
6405
  };
5750
- ClientController_vapidPublicKey: {
6406
+ BatchesController_flush: {
5751
6407
  parameters: {
5752
6408
  query?: never;
5753
- header?: never;
5754
- path?: never;
6409
+ header?: {
6410
+ /** @description Optional: the same key returns the first response. */
6411
+ "Idempotency-Key"?: string;
6412
+ };
6413
+ path: {
6414
+ /**
6415
+ * @description Id of the workspace.
6416
+ * @example 3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
6417
+ */
6418
+ workspace_id: string;
6419
+ /**
6420
+ * @description The batch id (from a delivery's `batch_id`, or the list).
6421
+ * @example 3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
6422
+ */
6423
+ batch_id: string;
6424
+ };
5755
6425
  cookie?: never;
5756
6426
  };
5757
6427
  requestBody?: never;
5758
6428
  responses: {
5759
- /** @description The public key. */
6429
+ /** @description Closed; the carriers are on their way. */
5760
6430
  200: {
5761
6431
  headers: {
6432
+ /** @description `true` when this response is a replay of an earlier request with the same `Idempotency-Key`. */
6433
+ "Idempotent-Replay"?: "true";
5762
6434
  "X-RateLimit-Limit-long": components["headers"]["X-RateLimit-Limit-long"];
5763
6435
  "X-RateLimit-Limit-short": components["headers"]["X-RateLimit-Limit-short"];
5764
6436
  "X-RateLimit-Remaining-long": components["headers"]["X-RateLimit-Remaining-long"];
@@ -5769,10 +6441,10 @@ interface operations {
5769
6441
  [name: string]: unknown;
5770
6442
  };
5771
6443
  content: {
5772
- "application/json": components["schemas"]["VapidPublicKeyDto"];
6444
+ "application/json": components["schemas"]["FlushBatchResponseDto"];
5773
6445
  };
5774
6446
  };
5775
- /** @description `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). */
6447
+ /** @description Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). */
5776
6448
  401: {
5777
6449
  headers: {
5778
6450
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5782,7 +6454,7 @@ interface operations {
5782
6454
  "application/json": components["schemas"]["ErrorResponseDto"];
5783
6455
  };
5784
6456
  };
5785
- /** @description `RECIPIENT_TOKEN_SCOPE`: the token lacks the `devices:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. */
6457
+ /** @description The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). */
5786
6458
  403: {
5787
6459
  headers: {
5788
6460
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5792,7 +6464,7 @@ interface operations {
5792
6464
  "application/json": components["schemas"]["ErrorResponseDto"];
5793
6465
  };
5794
6466
  };
5795
- /** @description `CHANNEL_NOT_CONFIGURED`: the workspace has no web push key yet (generate one in the console or with `POST /channels/webpush/vapid-keys`). */
6467
+ /** @description `BATCH_NOT_FOUND`: no batch with this id in this workspace. */
5796
6468
  404: {
5797
6469
  headers: {
5798
6470
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5802,7 +6474,19 @@ interface operations {
5802
6474
  "application/json": components["schemas"]["ErrorResponseDto"];
5803
6475
  };
5804
6476
  };
5805
- /** @description `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
6477
+ /** @description `BATCH_NOT_OPEN`: the batch already closed, or is closing right now. `IDEMPOTENCY_KEY_REUSE`: the key was used for another request. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). */
6478
+ 409: {
6479
+ headers: {
6480
+ /** @description Seconds to wait before retrying with the same key (sent with `IDEMPOTENCY_IN_PROGRESS`). */
6481
+ "Retry-After"?: number;
6482
+ "X-Request-Id": components["headers"]["RequestId"];
6483
+ [name: string]: unknown;
6484
+ };
6485
+ content: {
6486
+ "application/json": components["schemas"]["ErrorResponseDto"];
6487
+ };
6488
+ };
6489
+ /** @description More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
5806
6490
  429: {
5807
6491
  headers: {
5808
6492
  "Retry-After": components["headers"]["Retry-After"];
@@ -8686,7 +9370,7 @@ interface operations {
8686
9370
  "application/json": components["schemas"]["ErrorResponseDto"];
8687
9371
  };
8688
9372
  };
8689
- /** @description `RECIPIENT_NOT_FOUND`: no recipient can be notified (`details.skipped` lists why); `NOTIFICATION_TYPE_ARCHIVED`; `TEMPLATE_MISSING`: no template for any requested channel; `SEND_AT_OUT_OF_RANGE`; `UNSAFE_URL`; `VALIDATION_ERROR`: a channel outside the type's routing. */
9373
+ /** @description `RECIPIENT_NOT_FOUND`: no recipient can be notified (`details.skipped` lists why); `NOTIFICATION_TYPE_ARCHIVED`; `TEMPLATE_MISSING`: no template for any requested channel; `SEND_AT_OUT_OF_RANGE`; `BATCHED_TYPE_NOT_SCHEDULABLE`: the type batches (send it now); `UNSAFE_URL`; `VALIDATION_ERROR`: a channel outside the type's routing. */
8690
9374
  422: {
8691
9375
  headers: {
8692
9376
  "X-Request-Id": components["headers"]["RequestId"];
@@ -10117,6 +10801,111 @@ interface operations {
10117
10801
  };
10118
10802
  };
10119
10803
  };
10804
+ PreferenceLinkController_create: {
10805
+ parameters: {
10806
+ query?: never;
10807
+ header?: never;
10808
+ path: {
10809
+ /**
10810
+ * @description Id of the workspace.
10811
+ * @example 3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f
10812
+ */
10813
+ workspace_id: string;
10814
+ /**
10815
+ * @description Your user id for the recipient (URL-encoded): 1-255 of `A-Z a-z 0-9 . _ : @ | -`.
10816
+ * @example user_123
10817
+ */
10818
+ external_id: string;
10819
+ };
10820
+ cookie?: never;
10821
+ };
10822
+ requestBody: {
10823
+ content: {
10824
+ "application/json": components["schemas"]["CreatePreferenceLinkDto"];
10825
+ };
10826
+ };
10827
+ responses: {
10828
+ /** @description The link. */
10829
+ 201: {
10830
+ headers: {
10831
+ "X-RateLimit-Limit-long": components["headers"]["X-RateLimit-Limit-long"];
10832
+ "X-RateLimit-Limit-short": components["headers"]["X-RateLimit-Limit-short"];
10833
+ "X-RateLimit-Remaining-long": components["headers"]["X-RateLimit-Remaining-long"];
10834
+ "X-RateLimit-Remaining-short": components["headers"]["X-RateLimit-Remaining-short"];
10835
+ "X-RateLimit-Reset-long": components["headers"]["X-RateLimit-Reset-long"];
10836
+ "X-RateLimit-Reset-short": components["headers"]["X-RateLimit-Reset-short"];
10837
+ "X-Request-Id": components["headers"]["RequestId"];
10838
+ [name: string]: unknown;
10839
+ };
10840
+ content: {
10841
+ "application/json": components["schemas"]["PreferenceLinkDto"];
10842
+ };
10843
+ };
10844
+ /** @description `VALIDATION_ERROR`: `category_key` is malformed. */
10845
+ 400: {
10846
+ headers: {
10847
+ "X-Request-Id": components["headers"]["RequestId"];
10848
+ [name: string]: unknown;
10849
+ };
10850
+ content: {
10851
+ "application/json": components["schemas"]["ErrorResponseDto"];
10852
+ };
10853
+ };
10854
+ /** @description Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). */
10855
+ 401: {
10856
+ headers: {
10857
+ "X-Request-Id": components["headers"]["RequestId"];
10858
+ [name: string]: unknown;
10859
+ };
10860
+ content: {
10861
+ "application/json": components["schemas"]["ErrorResponseDto"];
10862
+ };
10863
+ };
10864
+ /** @description The caller lacks `notify.recipient.write`, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). */
10865
+ 403: {
10866
+ headers: {
10867
+ "X-Request-Id": components["headers"]["RequestId"];
10868
+ [name: string]: unknown;
10869
+ };
10870
+ content: {
10871
+ "application/json": components["schemas"]["ErrorResponseDto"];
10872
+ };
10873
+ };
10874
+ /** @description `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. */
10875
+ 404: {
10876
+ headers: {
10877
+ "X-Request-Id": components["headers"]["RequestId"];
10878
+ [name: string]: unknown;
10879
+ };
10880
+ content: {
10881
+ "application/json": components["schemas"]["ErrorResponseDto"];
10882
+ };
10883
+ };
10884
+ /** @description `CATEGORY_NOT_FOUND`: no category with this key. */
10885
+ 422: {
10886
+ headers: {
10887
+ "X-Request-Id": components["headers"]["RequestId"];
10888
+ [name: string]: unknown;
10889
+ };
10890
+ content: {
10891
+ "application/json": components["schemas"]["ErrorResponseDto"];
10892
+ };
10893
+ };
10894
+ /** @description More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. */
10895
+ 429: {
10896
+ headers: {
10897
+ "Retry-After": components["headers"]["Retry-After"];
10898
+ "Retry-After-long": components["headers"]["Retry-After-long"];
10899
+ "Retry-After-short": components["headers"]["Retry-After-short"];
10900
+ "X-Request-Id": components["headers"]["RequestId"];
10901
+ [name: string]: unknown;
10902
+ };
10903
+ content: {
10904
+ "application/json": components["schemas"]["ErrorResponseDto"];
10905
+ };
10906
+ };
10907
+ };
10908
+ };
10120
10909
  PreferencesController_retrieve: {
10121
10910
  parameters: {
10122
10911
  query?: never;
@@ -12116,6 +12905,18 @@ type NotificationStatus = components["schemas"]["NotificationStatus"];
12116
12905
  declare const NotificationStatus: {
12117
12906
  values: readonly ["scheduled", "accepted", "planned", "cancelled"];
12118
12907
  };
12908
+ type NotifyBatchInboxMode = components["schemas"]["NotifyBatchInboxMode"];
12909
+ declare const NotifyBatchInboxMode: {
12910
+ values: readonly ["collapse", "each"];
12911
+ };
12912
+ type NotifyBatchMode = components["schemas"]["NotifyBatchMode"];
12913
+ declare const NotifyBatchMode: {
12914
+ values: readonly ["window", "digest"];
12915
+ };
12916
+ type NotifyBatchState = components["schemas"]["NotifyBatchState"];
12917
+ declare const NotifyBatchState: {
12918
+ values: readonly ["open", "flushed", "cancelled"];
12919
+ };
12119
12920
  type NotifyChannel = components["schemas"]["NotifyChannel"];
12120
12921
  declare const NotifyChannel: {
12121
12922
  values: readonly ["inbox", "email", "push", "webpush"];
@@ -12143,6 +12944,8 @@ declare const NotifyChannel: {
12143
12944
  * - `rate_limited`: The recipient already received the per-minute maximum of notifications. Fix: Send fewer notifications to one person, or batch them; critical types have their own budget.
12144
12945
  * - `throttled`: The type's own throttle for this recipient was reached. Fix: Raise or remove `throttle` on the notification type if every message must go out.
12145
12946
  * - `read_in_inbox`: The recipient read the inbox item first, so the follow-up was not needed. Fix: Nothing to fix: this is how `after_unread_seconds` works.
12947
+ * - `batched`: The type batches notifications: this one waits in the recipient's open batch, which closes at the delivery's next attempt time (the batch window end or the digest time) and then sends one message for everything in it. Fix: Nothing to fix. To send it sooner, flush the batch (POST /batches/{batch_id}/flush), or remove `batch` from the type.
12948
+ * - `batched_into`: Sent together with the rest of its batch: the batch's message went out in another delivery of the same batch (same recipient and channel). Fix: Nothing to fix. Look up the batch (GET /batches/{batch_id}) to see the delivery that carried it.
12146
12949
  * - `awaiting_unread`: A follow-up step waiting to see whether the recipient reads the inbox item first. Fix: Nothing to fix: it is sent when the `after_unread_seconds` timer ends and the item is still unread, and skipped as `read_in_inbox` otherwise.
12147
12950
  * - `actor_excluded`: The recipient is the actor who caused the notification. Fix: Pass `exclude_actor: false` to notify the actor too.
12148
12951
  * - `recipient_not_found`: No recipient with this external id exists in the workspace. Fix: Create the recipient first (`PUT /recipients/{external_id}`), pass it inline with an email, or send `create_missing: true`.
@@ -12159,7 +12962,11 @@ declare const NotifyChannel: {
12159
12962
  */
12160
12963
  type NotifyDeliveryReason = components["schemas"]["NotifyDeliveryReason"];
12161
12964
  declare const NotifyDeliveryReason: {
12162
- values: readonly ["suppressed_preference", "default_off", "unsubscribed_all", "held_quiet_hours", "scheduled_send", "no_device", "no_address", "email_invalid", "email_complained", "email_paused", "email_budget", "email_backlog_full", "channel_not_configured", "channel_restricted", "type_archived", "credential_invalid", "template_missing", "rate_limited", "throttled", "read_in_inbox", "awaiting_unread", "actor_excluded", "recipient_not_found", "recipient_erased", "mail_suppressed", "mail_refused", "pruned", "payload_too_large", "credential_error", "circuit_open", "expired", "cancelled", "provider_error"];
12965
+ values: readonly ["suppressed_preference", "default_off", "unsubscribed_all", "held_quiet_hours", "scheduled_send", "no_device", "no_address", "email_invalid", "email_complained", "email_paused", "email_budget", "email_backlog_full", "channel_not_configured", "channel_restricted", "type_archived", "credential_invalid", "template_missing", "rate_limited", "throttled", "read_in_inbox", "awaiting_unread", "batched", "batched_into", "actor_excluded", "recipient_not_found", "recipient_erased", "mail_suppressed", "mail_refused", "pruned", "payload_too_large", "credential_error", "circuit_open", "expired", "cancelled", "provider_error"];
12966
+ };
12967
+ type NotifyDigestFrequency = components["schemas"]["NotifyDigestFrequency"];
12968
+ declare const NotifyDigestFrequency: {
12969
+ values: readonly ["daily", "weekly"];
12163
12970
  };
12164
12971
  type NotifyEmailPauseReason = components["schemas"]["NotifyEmailPauseReason"];
12165
12972
  declare const NotifyEmailPauseReason: {
@@ -12193,6 +13000,10 @@ type NotifyWebhookDeviceChannel = components["schemas"]["NotifyWebhookDeviceChan
12193
13000
  declare const NotifyWebhookDeviceChannel: {
12194
13001
  values: readonly ["apns", "fcm", "webpush"];
12195
13002
  };
13003
+ type NotifyWeekday = components["schemas"]["NotifyWeekday"];
13004
+ declare const NotifyWeekday: {
13005
+ values: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
13006
+ };
12196
13007
  type PlanDecision = components["schemas"]["PlanDecision"];
12197
13008
  declare const PlanDecision: {
12198
13009
  values: readonly ["deliver", "schedule", "skip"];
@@ -12250,6 +13061,18 @@ declare const WebhookEventType: {
12250
13061
  };
12251
13062
  interface ApnsCredential extends Open<components["schemas"]["ApnsCredentialDto"]> {
12252
13063
  }
13064
+ interface BatchDelivery extends Open<components["schemas"]["BatchDeliveryDto"]> {
13065
+ }
13066
+ interface BatchDetail extends Open<components["schemas"]["BatchDetailDto"]> {
13067
+ }
13068
+ interface BatchList extends Open<components["schemas"]["BatchListResponseDto"]> {
13069
+ }
13070
+ interface BatchScheduleView extends Open<components["schemas"]["BatchScheduleViewDto"]> {
13071
+ }
13072
+ interface BatchSummary extends Open<components["schemas"]["BatchSummaryDto"]> {
13073
+ }
13074
+ interface BatchView extends Open<components["schemas"]["BatchViewDto"]> {
13075
+ }
12253
13076
  interface BulkRowError extends Open<components["schemas"]["BulkRowErrorDto"]> {
12254
13077
  }
12255
13078
  interface BulkRowResult extends Open<components["schemas"]["BulkRowResultDto"]> {
@@ -12306,6 +13129,8 @@ interface FallbackStepView extends Open<components["schemas"]["FallbackStepViewD
12306
13129
  }
12307
13130
  interface FcmCredential extends Open<components["schemas"]["FcmCredentialDto"]> {
12308
13131
  }
13132
+ interface FlushBatch extends Open<components["schemas"]["FlushBatchResponseDto"]> {
13133
+ }
12309
13134
  interface InboxAction extends Open<components["schemas"]["InboxActionDto"]> {
12310
13135
  }
12311
13136
  interface InboxCounts extends Open<components["schemas"]["InboxCountsDto"]> {
@@ -12334,6 +13159,8 @@ interface NotificationType extends Open<components["schemas"]["NotificationTypeD
12334
13159
  }
12335
13160
  interface NotificationTypeList extends Open<components["schemas"]["NotificationTypeListResponseDto"]> {
12336
13161
  }
13162
+ interface NotifyBrandingView extends Open<components["schemas"]["NotifyBrandingViewDto"]> {
13163
+ }
12337
13164
  interface NotifyCredentialInvalidData extends Open<components["schemas"]["NotifyCredentialInvalidDataDto"]> {
12338
13165
  }
12339
13166
  interface NotifyDeliveryEventData extends Open<components["schemas"]["NotifyDeliveryEventDataDto"]> {
@@ -12360,10 +13187,14 @@ interface NotifyWebhookRecipient extends Open<components["schemas"]["NotifyWebho
12360
13187
  }
12361
13188
  interface Pagination extends Open<components["schemas"]["PaginationDto"]> {
12362
13189
  }
13190
+ interface PlanBatch extends Open<components["schemas"]["PlanBatchDto"]> {
13191
+ }
12363
13192
  interface PlanRow extends Open<components["schemas"]["PlanRowDto"]> {
12364
13193
  }
12365
13194
  interface PreferenceCell extends Open<components["schemas"]["PreferenceCellDto"]> {
12366
13195
  }
13196
+ interface PreferenceLink extends Open<components["schemas"]["PreferenceLinkDto"]> {
13197
+ }
12367
13198
  interface PreferenceSet extends Open<components["schemas"]["PreferenceSetDto"]> {
12368
13199
  }
12369
13200
  interface PreviewChannel extends Open<components["schemas"]["PreviewChannelDto"]> {
@@ -12450,6 +13281,8 @@ type MeInboxMarkParams = NonNullable<paths["/v1/client/inbox/mark"]["post"]["req
12450
13281
  type MeInboxInteractParams = NonNullable<paths["/v1/client/inbox/{item_id}/interact"]["post"]["requestBody"]>["content"]["application/json"];
12451
13282
  /** Params for `me.preferences.update` (PATCH /v1/client/preferences). */
12452
13283
  type MePreferenceUpdateParams = NonNullable<paths["/v1/client/preferences"]["patch"]["requestBody"]>["content"]["application/json"];
13284
+ /** Params for `batches.list` (GET /v1/workspaces/{workspace_id}/batches). */
13285
+ type BatchListParams = NonNullable<paths["/v1/workspaces/{workspace_id}/batches"]["get"]["parameters"]["query"]>;
12453
13286
  /** Params for `categories.list` (GET /v1/workspaces/{workspace_id}/categories). */
12454
13287
  type CategoryListParams = NonNullable<paths["/v1/workspaces/{workspace_id}/categories"]["get"]["parameters"]["query"]>;
12455
13288
  /** Params for `categories.create` (POST /v1/workspaces/{workspace_id}/categories). */
@@ -12502,6 +13335,8 @@ type RecipientUpdateParams = NonNullable<paths["/v1/workspaces/{workspace_id}/re
12502
13335
  type RecipientDeviceCreateParams = NonNullable<paths["/v1/workspaces/{workspace_id}/recipients/{external_id}/devices"]["post"]["requestBody"]>["content"]["application/json"];
12503
13336
  /** Params for `recipients.inbox.list` (GET /v1/workspaces/{workspace_id}/recipients/{external_id}/inbox). */
12504
13337
  type RecipientInboxListParams = NonNullable<paths["/v1/workspaces/{workspace_id}/recipients/{external_id}/inbox"]["get"]["parameters"]["query"]>;
13338
+ /** Params for `recipients.createPreferenceLink` (POST /v1/workspaces/{workspace_id}/recipients/{external_id}/preference-link). */
13339
+ type RecipientCreatePreferenceLinkParams = NonNullable<paths["/v1/workspaces/{workspace_id}/recipients/{external_id}/preference-link"]["post"]["requestBody"]>["content"]["application/json"];
12505
13340
  /** Params for `recipients.preferences.replace` (PUT /v1/workspaces/{workspace_id}/recipients/{external_id}/preferences). */
12506
13341
  type RecipientPreferenceReplaceParams = NonNullable<paths["/v1/workspaces/{workspace_id}/recipients/{external_id}/preferences"]["put"]["requestBody"]>["content"]["application/json"];
12507
13342
  /** Params for `recipients.preferences.update` (PATCH /v1/workspaces/{workspace_id}/recipients/{external_id}/preferences). */
@@ -12679,6 +13514,76 @@ declare class APIResource {
12679
13514
  protected readonly _b: Bound;
12680
13515
  constructor(client: APIClient, bound?: Bound);
12681
13516
  }
13517
+ /** `batches` */
13518
+ declare class BatchesResource extends APIResource {
13519
+ /**
13520
+ * Close a batch now
13521
+ *
13522
+ * Sends an open batch now instead of at its window end or digest time: one message per batched channel, rendered with everything collected so far. Preferences, quiet hours, the recipient budgets and the type throttle apply as for any send. Useful to test a digest template without waiting for the morning.
13523
+ *
13524
+ * Credential: `bearer`.
13525
+ *
13526
+ * @param batchId - The batch id (from a delivery's `batch_id`, or the list).
13527
+ * @param options - Per-request options (an Idempotency-Key is sent automatically; override with `idempotencyKey`).
13528
+ * @throws {AuthenticationError} 401 UNAUTHORIZED, RECIPIENT_TOKEN_INVALID: Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`).
13529
+ * @throws {PermissionDeniedError} 403 FORBIDDEN, SERVICE_NOT_ENABLED: The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID).
13530
+ * @throws {NotFoundError} 404 NOT_FOUND, BATCH_NOT_FOUND: `BATCH_NOT_FOUND`: no batch with this id in this workspace.
13531
+ * @throws {ConflictError} 409 CONFLICT, BATCH_NOT_OPEN, IDEMPOTENCY_KEY_REUSE, IDEMPOTENCY_IN_PROGRESS: `BATCH_NOT_OPEN`: the batch already closed, or is closing right now. `IDEMPOTENCY_KEY_REUSE`: the key was used for another request. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key).
13532
+ * @throws {RateLimitError} 429 RATE_LIMITED: More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds.
13533
+ * @see POST /v1/workspaces/{workspace_id}/batches/{batch_id}/flush
13534
+ * @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-batches-batch-id-flush
13535
+ * @example
13536
+ * ```ts
13537
+ * const flushBatch = await notify.batches.flush("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
13538
+ * ```
13539
+ */
13540
+ flush(batchId: string, options?: RequestOptions): APIPromise<WithLastResponse<FlushBatch>>;
13541
+ /**
13542
+ * List batches
13543
+ *
13544
+ * Batches of notification types with `batch` (a window or a digest), newest first: one per recipient and key value while collecting (`open`), then `flushed` once its one message went out. Filter by `recipient`, `type` and `state`. Pass `next_cursor` as `cursor` until `has_more` is false.
13545
+ *
13546
+ * Credential: `bearer`.
13547
+ *
13548
+ * @param params - `Notify.BatchListParams`.
13549
+ * @param options - Per-request options.
13550
+ * @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor.
13551
+ * @throws {AuthenticationError} 401 UNAUTHORIZED, RECIPIENT_TOKEN_INVALID: Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`).
13552
+ * @throws {PermissionDeniedError} 403 FORBIDDEN, SERVICE_NOT_ENABLED: The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID).
13553
+ * @throws {RateLimitError} 429 RATE_LIMITED: More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds.
13554
+ * @see GET /v1/workspaces/{workspace_id}/batches
13555
+ * @see https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-batches
13556
+ * @example
13557
+ * ```ts
13558
+ * for await (const batch of notify.batches.list()) {
13559
+ * console.log(batch);
13560
+ * }
13561
+ * const page = await notify.batches.list({}, { timeout: 5_000 });
13562
+ * ```
13563
+ */
13564
+ list(params?: BatchListParams, options?: RequestOptions): PagePromise<BatchSummary>;
13565
+ /**
13566
+ * Get a batch
13567
+ *
13568
+ * The notifications collected in it, its deliveries (while open, `scheduled: batched`; after it closes, one carrier per channel with its outcome, the rest `skipped: batched_into`), and the `batch` data templates got.
13569
+ *
13570
+ * Credential: `bearer`.
13571
+ *
13572
+ * @param batchId - The batch id (from a delivery's `batch_id`, or the list).
13573
+ * @param options - Per-request options.
13574
+ * @throws {AuthenticationError} 401 UNAUTHORIZED, RECIPIENT_TOKEN_INVALID: Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`).
13575
+ * @throws {PermissionDeniedError} 403 FORBIDDEN, SERVICE_NOT_ENABLED: The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID).
13576
+ * @throws {NotFoundError} 404 NOT_FOUND, BATCH_NOT_FOUND: `BATCH_NOT_FOUND`: no batch with this id in this workspace.
13577
+ * @throws {RateLimitError} 429 RATE_LIMITED: More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds.
13578
+ * @see GET /v1/workspaces/{workspace_id}/batches/{batch_id}
13579
+ * @see https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-batches-batch-id
13580
+ * @example
13581
+ * ```ts
13582
+ * const batchDetail = await notify.batches.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
13583
+ * ```
13584
+ */
13585
+ retrieve(batchId: string, options?: RequestOptions): APIPromise<WithLastResponse<BatchDetail>>;
13586
+ }
12682
13587
  /** `categories` */
12683
13588
  declare class CategoriesResource extends APIResource {
12684
13589
  /**
@@ -13342,7 +14247,18 @@ declare class NotificationTypesResource extends APIResource {
13342
14247
  * @see https://productcraft.co/docs/notify/api-reference#patch-v1-workspaces-workspace-id-notification-types-type-id
13343
14248
  * @example
13344
14249
  * ```ts
13345
- * const notificationType = await notify.notificationTypes.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { category_key: "billing" });
14250
+ * const notificationType = await notify.notificationTypes.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
14251
+ * batch: {
14252
+ * inbox: "collapse",
14253
+ * key: "post_id",
14254
+ * max_items: 10,
14255
+ * max_window_seconds: 3600,
14256
+ * mode: "window",
14257
+ * schedule: { frequency: "daily", time: "09:00", weekday: "monday" },
14258
+ * sliding: false,
14259
+ * window_seconds: 300,
14260
+ * },
14261
+ * });
13346
14262
  * ```
13347
14263
  */
13348
14264
  update(typeId: string, params?: NotificationTypeUpdateParams, options?: RequestOptions): APIPromise<WithLastResponse<NotificationType>>;
@@ -13472,7 +14388,7 @@ declare class NotificationsResource extends APIResource {
13472
14388
  * @throws {NotFoundError} 404 NOT_FOUND, NOTIFICATION_TYPE_NOT_FOUND: `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key.
13473
14389
  * @throws {ConflictError} 409 CONFLICT, IDEMPOTENCY_KEY_REUSE, IDEMPOTENCY_IN_PROGRESS: `IDEMPOTENCY_KEY_REUSE`: the key was used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key).
13474
14390
  * @throws {APIError} 413 PAYLOAD_TOO_LARGE, DATA_TOO_LARGE: `DATA_TOO_LARGE`: `data` is over 16 KB.
13475
- * @throws {UnprocessableEntityError} 422 UNPROCESSABLE_ENTITY, RECIPIENT_NOT_FOUND, NOTIFICATION_TYPE_ARCHIVED, TEMPLATE_MISSING, SEND_AT_OUT_OF_RANGE, UNSAFE_URL, VALIDATION_ERROR: `RECIPIENT_NOT_FOUND`: no recipient can be notified (`details.skipped` lists why); `NOTIFICATION_TYPE_ARCHIVED`; `TEMPLATE_MISSING`: no template for any requested channel; `SEND_AT_OUT_OF_RANGE`; `UNSAFE_URL`; `VALIDATION_ERROR`: a channel outside the type's routing.
14391
+ * @throws {UnprocessableEntityError} 422 UNPROCESSABLE_ENTITY, RECIPIENT_NOT_FOUND, NOTIFICATION_TYPE_ARCHIVED, TEMPLATE_MISSING, SEND_AT_OUT_OF_RANGE, BATCHED_TYPE_NOT_SCHEDULABLE, UNSAFE_URL, VALIDATION_ERROR: `RECIPIENT_NOT_FOUND`: no recipient can be notified (`details.skipped` lists why); `NOTIFICATION_TYPE_ARCHIVED`; `TEMPLATE_MISSING`: no template for any requested channel; `SEND_AT_OUT_OF_RANGE`; `BATCHED_TYPE_NOT_SCHEDULABLE`: the type batches (send it now); `UNSAFE_URL`; `VALIDATION_ERROR`: a channel outside the type's routing.
13476
14392
  * @throws {RateLimitError} 429 RATE_LIMITED: `RATE_LIMITED`: over 3,000 recipients a minute in this workspace; see `Retry-After`. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds.
13477
14393
  * @see POST /v1/workspaces/{workspace_id}/notifications
13478
14394
  * @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications
@@ -13711,6 +14627,30 @@ declare class RecipientsResource extends APIResource {
13711
14627
  * ```
13712
14628
  */
13713
14629
  bulkIdentify(params: RecipientBulkIdentifyParams, options?: RequestOptions): APIPromise<WithLastResponse<BulkUpsertRecipients>>;
14630
+ /**
14631
+ * Create a hosted preference page link
14632
+ *
14633
+ * Returns a signed link to a page, hosted by Notify in your workspace's branding (`branding` in settings), where this recipient switches each category on or off per channel, sets quiet hours and a time zone, or unsubscribes from everything except critical types. It needs no sign-in, so it works from any email, also for people who never open your app. The link is valid for 365 days. Changes are recorded in the recipient's consent history with source `hosted_page`. Each call returns a fresh link and changes nothing, so it takes no `Idempotency-Key`.
14634
+ *
14635
+ * Credential: `bearer`.
14636
+ *
14637
+ * @param externalId - Your user id for the recipient (URL-encoded): 1-255 of `A-Z a-z 0-9 . _ : @ | -`.
14638
+ * @param params - `Notify.RecipientCreatePreferenceLinkParams`.
14639
+ * @param options - Per-request options.
14640
+ * @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: `category_key` is malformed.
14641
+ * @throws {AuthenticationError} 401 UNAUTHORIZED, RECIPIENT_TOKEN_INVALID: Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`).
14642
+ * @throws {PermissionDeniedError} 403 FORBIDDEN, SERVICE_NOT_ENABLED: The caller lacks `notify.recipient.write`, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID).
14643
+ * @throws {NotFoundError} 404 NOT_FOUND, RECIPIENT_NOT_FOUND: `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace.
14644
+ * @throws {UnprocessableEntityError} 422 UNPROCESSABLE_ENTITY, CATEGORY_NOT_FOUND: `CATEGORY_NOT_FOUND`: no category with this key.
14645
+ * @throws {RateLimitError} 429 RATE_LIMITED: More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds.
14646
+ * @see POST /v1/workspaces/{workspace_id}/recipients/{external_id}/preference-link
14647
+ * @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-recipients-external-id-preference-link
14648
+ * @example
14649
+ * ```ts
14650
+ * const preferenceLink = await notify.recipients.createPreferenceLink("user_123", { category_key: "product-updates" });
14651
+ * ```
14652
+ */
14653
+ createPreferenceLink(externalId: string, params?: RecipientCreatePreferenceLinkParams, options?: RequestOptions): APIPromise<WithLastResponse<PreferenceLink>>;
13714
14654
  /**
13715
14655
  * Erase a recipient (GDPR)
13716
14656
  *
@@ -13929,7 +14869,14 @@ declare class SettingsResource extends APIResource {
13929
14869
  * @see https://productcraft.co/docs/notify/api-reference#patch-v1-workspaces-workspace-id-settings
13930
14870
  * @example
13931
14871
  * ```ts
13932
- * const notifySettings = await notify.settings.update({ client_origins: ["https://app.example.com", "https://www.example.com"] });
14872
+ * const notifySettings = await notify.settings.update({
14873
+ * branding: {
14874
+ * accent_color: "#4f46e5",
14875
+ * logo_url: "https://acme.example/logo.png",
14876
+ * name: "Acme",
14877
+ * privacy_url: "https://acme.example/privacy",
14878
+ * },
14879
+ * });
13933
14880
  * ```
13934
14881
  */
13935
14882
  update(params?: SettingsUpdateParams, options?: RequestOptions): APIPromise<WithLastResponse<NotifySettings>>;
@@ -14266,6 +15213,7 @@ declare class WebhooksResource extends APIResource {
14266
15213
  /** `notify` */
14267
15214
  declare class NotifyResources extends APIResource {
14268
15215
  #private;
15216
+ get batches(): BatchesResource;
14269
15217
  get categories(): CategoriesResource;
14270
15218
  get channels(): ChannelsResource;
14271
15219
  get deliveries(): DeliveriesResource;
@@ -14527,8 +15475,12 @@ type __DeviceState = DeviceState;
14527
15475
  type __InboxItemStatusFilter = InboxItemStatusFilter;
14528
15476
  type __InboxMarkAction = InboxMarkAction;
14529
15477
  type __NotificationStatus = NotificationStatus;
15478
+ type __NotifyBatchInboxMode = NotifyBatchInboxMode;
15479
+ type __NotifyBatchMode = NotifyBatchMode;
15480
+ type __NotifyBatchState = NotifyBatchState;
14530
15481
  type __NotifyChannel = NotifyChannel;
14531
15482
  type __NotifyDeliveryReason = NotifyDeliveryReason;
15483
+ type __NotifyDigestFrequency = NotifyDigestFrequency;
14532
15484
  type __NotifyEmailPauseReason = NotifyEmailPauseReason;
14533
15485
  type __NotifyQuietHoursSource = NotifyQuietHoursSource;
14534
15486
  type __NotifyRecipientDeletionCause = NotifyRecipientDeletionCause;
@@ -14537,6 +15489,7 @@ type __NotifyWebhookChannel = NotifyWebhookChannel;
14537
15489
  type __NotifyWebhookCredentialProvider = NotifyWebhookCredentialProvider;
14538
15490
  type __NotifyWebhookDeliveryState = NotifyWebhookDeliveryState;
14539
15491
  type __NotifyWebhookDeviceChannel = NotifyWebhookDeviceChannel;
15492
+ type __NotifyWeekday = NotifyWeekday;
14540
15493
  type __PlanDecision = PlanDecision;
14541
15494
  type __PreferenceChannel = PreferenceChannel;
14542
15495
  type __PreferenceScope = PreferenceScope;
@@ -14551,6 +15504,12 @@ type __WebhookEndpointStatus = WebhookEndpointStatus;
14551
15504
  type __WebhookEventStatus = WebhookEventStatus;
14552
15505
  type __WebhookEventType = WebhookEventType;
14553
15506
  type __ApnsCredential = ApnsCredential;
15507
+ type __BatchDelivery = BatchDelivery;
15508
+ type __BatchDetail = BatchDetail;
15509
+ type __BatchList = BatchList;
15510
+ type __BatchScheduleView = BatchScheduleView;
15511
+ type __BatchSummary = BatchSummary;
15512
+ type __BatchView = BatchView;
14554
15513
  type __BulkRowError = BulkRowError;
14555
15514
  type __BulkRowResult = BulkRowResult;
14556
15515
  type __BulkUpsertRecipients = BulkUpsertRecipients;
@@ -14579,6 +15538,7 @@ type __ExportNotificationType = ExportNotificationType;
14579
15538
  type __ExportSettings = ExportSettings;
14580
15539
  type __FallbackStepView = FallbackStepView;
14581
15540
  type __FcmCredential = FcmCredential;
15541
+ type __FlushBatch = FlushBatch;
14582
15542
  type __InboxAction = InboxAction;
14583
15543
  type __InboxCounts = InboxCounts;
14584
15544
  type __InboxItem = InboxItem;
@@ -14596,6 +15556,7 @@ type __Notification = Notification;
14596
15556
  type __NotificationList = NotificationList;
14597
15557
  type __NotificationType = NotificationType;
14598
15558
  type __NotificationTypeList = NotificationTypeList;
15559
+ type __NotifyBrandingView = NotifyBrandingView;
14599
15560
  type __NotifyCredentialInvalidData = NotifyCredentialInvalidData;
14600
15561
  type __NotifyDeliveryEventData = NotifyDeliveryEventData;
14601
15562
  type __NotifyDeviceEventData = NotifyDeviceEventData;
@@ -14609,8 +15570,10 @@ type __NotifyStatsDay = NotifyStatsDay;
14609
15570
  type __NotifyStats = NotifyStats;
14610
15571
  type __NotifyWebhookRecipient = NotifyWebhookRecipient;
14611
15572
  type __Pagination = Pagination;
15573
+ type __PlanBatch = PlanBatch;
14612
15574
  type __PlanRow = PlanRow;
14613
15575
  type __PreferenceCell = PreferenceCell;
15576
+ type __PreferenceLink = PreferenceLink;
14614
15577
  type __PreferenceSet = PreferenceSet;
14615
15578
  type __PreviewChannel = PreviewChannel;
14616
15579
  type __Preview = Preview;
@@ -14655,6 +15618,7 @@ type __MeInboxListParams = MeInboxListParams;
14655
15618
  type __MeInboxMarkParams = MeInboxMarkParams;
14656
15619
  type __MeInboxInteractParams = MeInboxInteractParams;
14657
15620
  type __MePreferenceUpdateParams = MePreferenceUpdateParams;
15621
+ type __BatchListParams = BatchListParams;
14658
15622
  type __CategoryListParams = CategoryListParams;
14659
15623
  type __CategoryCreateParams = CategoryCreateParams;
14660
15624
  type __CategoryUpdateParams = CategoryUpdateParams;
@@ -14681,6 +15645,7 @@ type __RecipientIdentifyParams = RecipientIdentifyParams;
14681
15645
  type __RecipientUpdateParams = RecipientUpdateParams;
14682
15646
  type __RecipientDeviceCreateParams = RecipientDeviceCreateParams;
14683
15647
  type __RecipientInboxListParams = RecipientInboxListParams;
15648
+ type __RecipientCreatePreferenceLinkParams = RecipientCreatePreferenceLinkParams;
14684
15649
  type __RecipientPreferenceReplaceParams = RecipientPreferenceReplaceParams;
14685
15650
  type __RecipientPreferenceUpdateParams = RecipientPreferenceUpdateParams;
14686
15651
  type __RecipientTimelineParams = RecipientTimelineParams;
@@ -14821,13 +15786,29 @@ declare namespace Notify {
14821
15786
  const NotificationStatus: {
14822
15787
  values: readonly ["scheduled", "accepted", "planned", "cancelled"];
14823
15788
  };
15789
+ type NotifyBatchInboxMode = __NotifyBatchInboxMode;
15790
+ const NotifyBatchInboxMode: {
15791
+ values: readonly ["collapse", "each"];
15792
+ };
15793
+ type NotifyBatchMode = __NotifyBatchMode;
15794
+ const NotifyBatchMode: {
15795
+ values: readonly ["window", "digest"];
15796
+ };
15797
+ type NotifyBatchState = __NotifyBatchState;
15798
+ const NotifyBatchState: {
15799
+ values: readonly ["open", "flushed", "cancelled"];
15800
+ };
14824
15801
  type NotifyChannel = __NotifyChannel;
14825
15802
  const NotifyChannel: {
14826
15803
  values: readonly ["inbox", "email", "push", "webpush"];
14827
15804
  };
14828
15805
  type NotifyDeliveryReason = __NotifyDeliveryReason;
14829
15806
  const NotifyDeliveryReason: {
14830
- values: readonly ["suppressed_preference", "default_off", "unsubscribed_all", "held_quiet_hours", "scheduled_send", "no_device", "no_address", "email_invalid", "email_complained", "email_paused", "email_budget", "email_backlog_full", "channel_not_configured", "channel_restricted", "type_archived", "credential_invalid", "template_missing", "rate_limited", "throttled", "read_in_inbox", "awaiting_unread", "actor_excluded", "recipient_not_found", "recipient_erased", "mail_suppressed", "mail_refused", "pruned", "payload_too_large", "credential_error", "circuit_open", "expired", "cancelled", "provider_error"];
15807
+ values: readonly ["suppressed_preference", "default_off", "unsubscribed_all", "held_quiet_hours", "scheduled_send", "no_device", "no_address", "email_invalid", "email_complained", "email_paused", "email_budget", "email_backlog_full", "channel_not_configured", "channel_restricted", "type_archived", "credential_invalid", "template_missing", "rate_limited", "throttled", "read_in_inbox", "awaiting_unread", "batched", "batched_into", "actor_excluded", "recipient_not_found", "recipient_erased", "mail_suppressed", "mail_refused", "pruned", "payload_too_large", "credential_error", "circuit_open", "expired", "cancelled", "provider_error"];
15808
+ };
15809
+ type NotifyDigestFrequency = __NotifyDigestFrequency;
15810
+ const NotifyDigestFrequency: {
15811
+ values: readonly ["daily", "weekly"];
14831
15812
  };
14832
15813
  type NotifyEmailPauseReason = __NotifyEmailPauseReason;
14833
15814
  const NotifyEmailPauseReason: {
@@ -14861,6 +15842,10 @@ declare namespace Notify {
14861
15842
  const NotifyWebhookDeviceChannel: {
14862
15843
  values: readonly ["apns", "fcm", "webpush"];
14863
15844
  };
15845
+ type NotifyWeekday = __NotifyWeekday;
15846
+ const NotifyWeekday: {
15847
+ values: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
15848
+ };
14864
15849
  type PlanDecision = __PlanDecision;
14865
15850
  const PlanDecision: {
14866
15851
  values: readonly ["deliver", "schedule", "skip"];
@@ -14914,6 +15899,12 @@ declare namespace Notify {
14914
15899
  values: readonly ["notification.accepted", "delivery.sent", "delivery.delivered", "delivery.failed", "delivery.bounced", "delivery.skipped", "inbox_item.read", "inbox_item.archived", "inbox_item.interacted", "device.pruned", "device.moved", "credential.invalid", "email.auto_paused", "recipient.deleted"];
14915
15900
  };
14916
15901
  type ApnsCredential = __ApnsCredential;
15902
+ type BatchDelivery = __BatchDelivery;
15903
+ type BatchDetail = __BatchDetail;
15904
+ type BatchList = __BatchList;
15905
+ type BatchScheduleView = __BatchScheduleView;
15906
+ type BatchSummary = __BatchSummary;
15907
+ type BatchView = __BatchView;
14917
15908
  type BulkRowError = __BulkRowError;
14918
15909
  type BulkRowResult = __BulkRowResult;
14919
15910
  type BulkUpsertRecipients = __BulkUpsertRecipients;
@@ -14942,6 +15933,7 @@ declare namespace Notify {
14942
15933
  type ExportSettings = __ExportSettings;
14943
15934
  type FallbackStepView = __FallbackStepView;
14944
15935
  type FcmCredential = __FcmCredential;
15936
+ type FlushBatch = __FlushBatch;
14945
15937
  type InboxAction = __InboxAction;
14946
15938
  type InboxCounts = __InboxCounts;
14947
15939
  type InboxItem = __InboxItem;
@@ -14962,6 +15954,7 @@ declare namespace Notify {
14962
15954
  type NotificationList = __NotificationList;
14963
15955
  type NotificationType = __NotificationType;
14964
15956
  type NotificationTypeList = __NotificationTypeList;
15957
+ type NotifyBrandingView = __NotifyBrandingView;
14965
15958
  type NotifyCredentialInvalidData = __NotifyCredentialInvalidData;
14966
15959
  type NotifyDeliveryEventData = __NotifyDeliveryEventData;
14967
15960
  type NotifyDeviceEventData = __NotifyDeviceEventData;
@@ -14975,8 +15968,10 @@ declare namespace Notify {
14975
15968
  type NotifyStats = __NotifyStats;
14976
15969
  type NotifyWebhookRecipient = __NotifyWebhookRecipient;
14977
15970
  type Pagination = __Pagination;
15971
+ type PlanBatch = __PlanBatch;
14978
15972
  type PlanRow = __PlanRow;
14979
15973
  type PreferenceCell = __PreferenceCell;
15974
+ type PreferenceLink = __PreferenceLink;
14980
15975
  type PreferenceSet = __PreferenceSet;
14981
15976
  type PreviewChannel = __PreviewChannel;
14982
15977
  type Preview = __Preview;
@@ -15022,6 +16017,7 @@ declare namespace Notify {
15022
16017
  type MeInboxMarkParams = __MeInboxMarkParams;
15023
16018
  type MeInboxInteractParams = __MeInboxInteractParams;
15024
16019
  type MePreferenceUpdateParams = __MePreferenceUpdateParams;
16020
+ type BatchListParams = __BatchListParams;
15025
16021
  type CategoryListParams = __CategoryListParams;
15026
16022
  type CategoryCreateParams = __CategoryCreateParams;
15027
16023
  type CategoryUpdateParams = __CategoryUpdateParams;
@@ -15048,6 +16044,7 @@ declare namespace Notify {
15048
16044
  type RecipientUpdateParams = __RecipientUpdateParams;
15049
16045
  type RecipientDeviceCreateParams = __RecipientDeviceCreateParams;
15050
16046
  type RecipientInboxListParams = __RecipientInboxListParams;
16047
+ type RecipientCreatePreferenceLinkParams = __RecipientCreatePreferenceLinkParams;
15051
16048
  type RecipientPreferenceReplaceParams = __RecipientPreferenceReplaceParams;
15052
16049
  type RecipientPreferenceUpdateParams = __RecipientPreferenceUpdateParams;
15053
16050
  type RecipientTimelineParams = __RecipientTimelineParams;