@productcraft/notify 0.1.1 → 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;
@@ -632,7 +692,7 @@ type paths = {
632
692
  put?: never;
633
693
  /**
634
694
  * Send a notification
635
- * @description Notifies up to 1,000 recipients with one notification type, across the type's channels (in-app inbox, email, push, web push), honouring each recipient's preferences. Returns 202 as soon as the send is stored; delivery happens in the background (see `GET /deliveries`). Unknown external ids do not fail the call: they are listed in `skipped` (`create_missing: true` creates them instead); the call fails only when no recipient can be notified. An `Idempotency-Key` is **required** (a deterministic one such as `invoice.paid:inv_123` is best): the same key and body return the same notification, even when retried much later; the same key with a different body is a 409. `dry_run: true` returns the plan per recipient and channel with the reason for every skip, and stores nothing (200, no key needed). Limits: 3,000 recipients per minute per workspace; 30 notifications per minute per recipient (critical types have a separate 30), beyond which deliveries are skipped as `rate_limited`.
695
+ * @description Notifies up to 1,000 recipients with one notification type, across the type's channels (in-app inbox, email, push, web push), honouring each recipient's preferences. Returns 202 as soon as the send is stored; delivery happens in the background (see `GET /deliveries`). Unknown external ids do not fail the call: they are listed in `skipped` (`create_missing: true` creates them instead); the call fails only when no recipient can be notified. An `Idempotency-Key` is **required** (a deterministic one built from your event, such as `invoice.paid:inv_123`, is best; dots are fine): the same key and body return the same notification, even when retried much later; the same key with a different body is a 409. `dry_run: true` returns the plan per recipient and channel with the reason for every skip, and stores nothing (200, no key needed). Limits: 3,000 recipients per minute per workspace; 30 notifications per minute per recipient (critical types have a separate 30), beyond which deliveries are skipped as `rate_limited`.
636
696
  */
637
697
  post: operations["NotificationsController_send"];
638
698
  delete?: 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
@@ -1354,7 +1624,7 @@ type components = {
1354
1624
  CancelByKeyDto: {
1355
1625
  /**
1356
1626
  * @description The `cancellation_key` given at send.
1357
- * @example invite:inv_77
1627
+ * @example invite.sent:inv_77
1358
1628
  */
1359
1629
  cancellation_key: string;
1360
1630
  };
@@ -1541,9 +1811,11 @@ type components = {
1541
1811
  ClientPreferencesDto: {
1542
1812
  /** @description The workspace's categories in display order, with their defaults. */
1543
1813
  categories: components["schemas"]["ClientCategoryDto"][];
1814
+ /** @description The quiet window that applies: the recipient's own (`source: recipient`), else the workspace default (`source: workspace`). Null: no quiet hours apply. Show this, not `quiet_hours`, as the current state; setting `quiet_hours` replaces the default for this recipient. */
1815
+ effective_quiet_hours: components["schemas"]["EffectiveQuietHoursDto"] | null;
1544
1816
  /** @description Cells the recipient set (anything else follows the category defaults). */
1545
1817
  preferences: components["schemas"]["PreferenceCellDto"][];
1546
- /** @description Quiet window. */
1818
+ /** @description The recipient's own quiet window; null when they set none (the workspace default then applies, see `effective_quiet_hours`). */
1547
1819
  quiet_hours: components["schemas"]["QuietHoursDto"] | null;
1548
1820
  /** @description IANA time zone. */
1549
1821
  timezone: string | null;
@@ -1579,6 +1851,8 @@ type components = {
1579
1851
  transactional?: boolean;
1580
1852
  };
1581
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;
1582
1856
  /**
1583
1857
  * @description Key of the category the type belongs to.
1584
1858
  * @example billing
@@ -1622,6 +1896,13 @@ type components = {
1622
1896
  */
1623
1897
  ttl_seconds?: number;
1624
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
+ };
1625
1906
  CreateRecipientTokenDto: {
1626
1907
  /**
1627
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.
@@ -1850,6 +2131,11 @@ type components = {
1850
2131
  attempts: number;
1851
2132
  /** @description Provider calls, oldest first (no PII, no provider bodies). */
1852
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;
1853
2139
  /** @description The channel. */
1854
2140
  channel: components["schemas"]["NotifyChannel"];
1855
2141
  /**
@@ -1920,6 +2206,11 @@ type components = {
1920
2206
  DeliveryDto: {
1921
2207
  /** @description Provider calls made. */
1922
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;
1923
2214
  /** @description The channel. */
1924
2215
  channel: components["schemas"]["NotifyChannel"];
1925
2216
  /**
@@ -2340,6 +2631,25 @@ type components = {
2340
2631
  /** @description The notification type key. */
2341
2632
  type: string;
2342
2633
  };
2634
+ EffectiveQuietHoursDto: {
2635
+ /**
2636
+ * @description End of the window, `HH:MM`. An end before the start spans midnight.
2637
+ * @example 08:00
2638
+ */
2639
+ end: string;
2640
+ /** @description `recipient`: their own window (`quiet_hours`). `workspace`: they set none, so the workspace default applies; setting their own window replaces it. */
2641
+ source: components["schemas"]["NotifyQuietHoursSource"];
2642
+ /**
2643
+ * @description Start of the window, `HH:MM` 24-hour.
2644
+ * @example 22:00
2645
+ */
2646
+ start: string;
2647
+ /**
2648
+ * @description The time zone the window is read in: the recipient's, else the workspace default. Null: none is known, so only devices that registered a time zone are held.
2649
+ * @example Europe/Lisbon
2650
+ */
2651
+ timezone: string | null;
2652
+ };
2343
2653
  /**
2344
2654
  * EmailAutoPausedEvent
2345
2655
  * @description Notify paused email for the workspace: more than 0.1 % complaints or 5 % hard bounces among recent emails. Fix the cause, then resume it in the settings.
@@ -2458,6 +2768,8 @@ type components = {
2458
2768
  * @description When archived.
2459
2769
  */
2460
2770
  archived_at: string | null;
2771
+ /** @description Batching or digest config; null sends each notification on its own. */
2772
+ batch: components["schemas"]["BatchViewDto"] | null;
2461
2773
  /** @description Category key. */
2462
2774
  category_key: string;
2463
2775
  /** @description Critical. */
@@ -2555,6 +2867,12 @@ type components = {
2555
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. */
2556
2868
  warnings: string[];
2557
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
+ };
2558
2876
  GenerateVapidKeysDto: {
2559
2877
  /**
2560
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`.
@@ -3037,6 +3355,8 @@ type components = {
3037
3355
  * @description When archived; archived types cannot be sent.
3038
3356
  */
3039
3357
  archived_at: string | null;
3358
+ /** @description Batching or digest config; null sends each notification on its own. */
3359
+ batch: components["schemas"]["BatchViewDto"] | null;
3040
3360
  /**
3041
3361
  * Format: uuid
3042
3362
  * @description Category id.
@@ -3092,6 +3412,58 @@ type components = {
3092
3412
  pagination: components["schemas"]["PaginationDto"];
3093
3413
  };
3094
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} */
3095
3467
  NotifyChannel: "inbox" | "email" | "push" | "webpush";
3096
3468
  NotifyCredentialInvalidDataDto: {
3097
3469
  /**
@@ -3182,6 +3554,7 @@ type components = {
3182
3554
  * @description Why a delivery was skipped, held, retried or failed. Open enum: new reasons may be added.
3183
3555
  *
3184
3556
  * - `suppressed_preference`: The recipient turned this channel off for this type or its category. Fix: Nothing to fix: the recipient chose this. Mark the category channel `mandatory` only for messages they must receive.
3557
+ * - `default_off`: This channel is off by default for the category, and the recipient has not turned it on. Fix: Nothing to fix if the channel is opt-in by design: it is sent once the recipient turns it on in their preferences. Set the category default to `on` to send it without an opt-in.
3185
3558
  * - `unsubscribed_all`: The recipient unsubscribed from all non-critical notifications. Fix: Only types marked `critical` still reach them; otherwise the recipient has to opt back in.
3186
3559
  * - `held_quiet_hours`: Held until the recipient's quiet hours end. Fix: It is sent when the window ends. Mark the type `critical` if it must not wait.
3187
3560
  * - `scheduled_send`: Waiting for the send time given in `send_at` or `delay_seconds`. Fix: It is sent at that time. Cancel it with the notification id or its `cancellation_key`.
@@ -3200,6 +3573,8 @@ type components = {
3200
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.
3201
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.
3202
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.
3203
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.
3204
3579
  * - `actor_excluded`: The recipient is the actor who caused the notification. Fix: Pass `exclude_actor: false` to notify the actor too.
3205
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`.
@@ -3215,7 +3590,7 @@ type components = {
3215
3590
  * - `provider_error`: The provider kept failing until retries ran out. Fix: Check the attempts for the provider status and code.
3216
3591
  * @enum {string}
3217
3592
  */
3218
- NotifyDeliveryReason: "suppressed_preference" | "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";
3219
3594
  NotifyDeviceEventDataDto: {
3220
3595
  /**
3221
3596
  * @description The device channel.
@@ -3248,6 +3623,8 @@ type components = {
3248
3623
  /** @description The recipient the device belongs to now. */
3249
3624
  recipient: components["schemas"]["NotifyWebhookRecipientDto"];
3250
3625
  };
3626
+ /** @enum {string} */
3627
+ NotifyDigestFrequency: "daily" | "weekly";
3251
3628
  NotifyEmailAutoPausedDataDto: {
3252
3629
  /**
3253
3630
  * @description Hard bounces in the window.
@@ -3273,7 +3650,7 @@ type components = {
3273
3650
  /** @enum {string} */
3274
3651
  NotifyEmailPauseReason: "complaints" | "bounces";
3275
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>. */
3276
- 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;
3277
3654
  NotifyInboxItemEventDataDto: {
3278
3655
  /**
3279
3656
  * Format: uuid
@@ -3334,6 +3711,8 @@ type components = {
3334
3711
  */
3335
3712
  type_key: string;
3336
3713
  };
3714
+ /** @enum {string} */
3715
+ NotifyQuietHoursSource: "recipient" | "workspace";
3337
3716
  NotifyRecipientDeletedDataDto: {
3338
3717
  /**
3339
3718
  * @description `api`: erased through `DELETE /recipients/{external_id}`; `auth_user_deleted`: the linked Auth end user was deleted.
@@ -3349,6 +3728,8 @@ type components = {
3349
3728
  /** @enum {string} */
3350
3729
  NotifyRecipientDeletionCause: "api" | "auth_user_deleted";
3351
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;
3352
3733
  /**
3353
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.
3354
3735
  * @example [
@@ -3500,15 +3881,35 @@ type components = {
3500
3881
  */
3501
3882
  id: string;
3502
3883
  };
3884
+ /** @enum {string} */
3885
+ NotifyWeekday: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday";
3503
3886
  PaginationDto: {
3504
3887
  /** @description Whether another page follows. */
3505
3888
  has_more: boolean;
3506
3889
  /** @description Pass as `cursor` to get the next page; null on the last page. */
3507
3890
  next_cursor: string | null;
3508
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
+ };
3509
3908
  /** @enum {string} */
3510
3909
  PlanDecision: "deliver" | "schedule" | "skip";
3511
3910
  PlanRowDto: {
3911
+ /** @description Batched types: the batch this channel would wait in (`reason: batched`). */
3912
+ batch?: components["schemas"]["PlanBatchDto"];
3512
3913
  /** @description The channel. */
3513
3914
  channel: components["schemas"]["NotifyChannel"];
3514
3915
  /** @description `deliver`, `schedule` (held, sent later) or `skip`. */
@@ -3570,14 +3971,31 @@ type components = {
3570
3971
  };
3571
3972
  /** @enum {string} */
3572
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
+ };
3573
3989
  /** @enum {string} */
3574
3990
  PreferenceScope: "all" | "category" | "type";
3575
3991
  PreferenceSetDto: {
3992
+ /** @description The quiet window that applies: the recipient's own, else the workspace default. Null: no quiet hours apply. */
3993
+ effective_quiet_hours: components["schemas"]["EffectiveQuietHoursDto"] | null;
3576
3994
  /** @description The recipient external id. */
3577
3995
  external_id: string;
3578
3996
  /** @description Cells the recipient set (anything else follows the category defaults). */
3579
3997
  preferences: components["schemas"]["PreferenceCellDto"][];
3580
- /** @description Quiet window. */
3998
+ /** @description The recipient's own quiet window; null when they set none (the workspace default then applies, see `effective_quiet_hours`). */
3581
3999
  quiet_hours: components["schemas"]["QuietHoursDto"] | null;
3582
4000
  /** @description IANA time zone. */
3583
4001
  timezone: string | null;
@@ -3865,6 +4283,8 @@ type components = {
3865
4283
  title: string;
3866
4284
  };
3867
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;
3868
4288
  /**
3869
4289
  * @description Key of the category; it must exist (create categories first, or apply an export).
3870
4290
  * @example billing
@@ -3971,8 +4391,8 @@ type components = {
3971
4391
  /** @description Who caused the notification. */
3972
4392
  actor?: components["schemas"]["ActorDto"];
3973
4393
  /**
3974
- * @description Your key for cancelling later without storing our id (`POST /notifications/cancel`).
3975
- * @example invite:inv_77
4394
+ * @description Your key for cancelling later without storing our id (`POST /notifications/cancel`): 1-255 characters of `A-Z a-z 0-9 . _ : @ | -`, so it can embed a type key and an id (`invite.sent:inv_77`).
4395
+ * @example invite.sent:inv_77
3976
4396
  */
3977
4397
  cancellation_key?: string;
3978
4398
  /** @description Only these channels (a subset of the type's routing). */
@@ -4235,6 +4655,11 @@ type components = {
4235
4655
  TimelineEntryDto: {
4236
4656
  /** @description Provider calls made. */
4237
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;
4238
4663
  /** @description The channel. */
4239
4664
  channel: components["schemas"]["NotifyChannel"];
4240
4665
  /**
@@ -4351,6 +4776,8 @@ type components = {
4351
4776
  unsubscribed_all?: boolean;
4352
4777
  };
4353
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;
4354
4781
  /**
4355
4782
  * @description Key of the category the type belongs to (preferences are per category).
4356
4783
  * @example billing
@@ -4390,6 +4817,8 @@ type components = {
4390
4817
  ttl_seconds?: number;
4391
4818
  };
4392
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;
4393
4822
  /**
4394
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.
4395
4824
  * @example [
@@ -5637,20 +6066,283 @@ interface operations {
5637
6066
  };
5638
6067
  };
5639
6068
  };
5640
- ClientController_updatePreferences: {
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. */
6311
+ 429: {
6312
+ headers: {
6313
+ "Retry-After": components["headers"]["Retry-After"];
6314
+ "Retry-After-long": components["headers"]["Retry-After-long"];
6315
+ "Retry-After-short": components["headers"]["Retry-After-short"];
6316
+ "X-Request-Id": components["headers"]["RequestId"];
6317
+ [name: string]: unknown;
6318
+ };
6319
+ content: {
6320
+ "application/json": components["schemas"]["ErrorResponseDto"];
6321
+ };
6322
+ };
6323
+ };
6324
+ };
6325
+ BatchesController_retrieve: {
5641
6326
  parameters: {
5642
6327
  query?: never;
5643
6328
  header?: never;
5644
- path?: never;
5645
- cookie?: never;
5646
- };
5647
- requestBody: {
5648
- content: {
5649
- "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;
5650
6340
  };
6341
+ cookie?: never;
5651
6342
  };
6343
+ requestBody?: never;
5652
6344
  responses: {
5653
- /** @description The preferences after the change. */
6345
+ /** @description The batch. */
5654
6346
  200: {
5655
6347
  headers: {
5656
6348
  "X-RateLimit-Limit-long": components["headers"]["X-RateLimit-Limit-long"];
@@ -5663,20 +6355,10 @@ interface operations {
5663
6355
  [name: string]: unknown;
5664
6356
  };
5665
6357
  content: {
5666
- "application/json": components["schemas"]["ClientPreferencesDto"];
5667
- };
5668
- };
5669
- /** @description `VALIDATION_ERROR`: a field is invalid (`errors` names it). */
5670
- 400: {
5671
- headers: {
5672
- "X-Request-Id": components["headers"]["RequestId"];
5673
- [name: string]: unknown;
5674
- };
5675
- content: {
5676
- "application/json": components["schemas"]["ErrorResponseDto"];
6358
+ "application/json": components["schemas"]["BatchDetailDto"];
5677
6359
  };
5678
6360
  };
5679
- /** @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/…`). */
5680
6362
  401: {
5681
6363
  headers: {
5682
6364
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5686,7 +6368,7 @@ interface operations {
5686
6368
  "application/json": components["schemas"]["ErrorResponseDto"];
5687
6369
  };
5688
6370
  };
5689
- /** @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). */
5690
6372
  403: {
5691
6373
  headers: {
5692
6374
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5696,8 +6378,8 @@ interface operations {
5696
6378
  "application/json": components["schemas"]["ErrorResponseDto"];
5697
6379
  };
5698
6380
  };
5699
- /** @description `PREFERENCE_LOCKED`: the channel is mandatory for the category; `CATEGORY_NOT_FOUND` / `NOTIFICATION_TYPE_NOT_FOUND`: no category or type with that key. */
5700
- 422: {
6381
+ /** @description `BATCH_NOT_FOUND`: no batch with this id in this workspace. */
6382
+ 404: {
5701
6383
  headers: {
5702
6384
  "X-Request-Id": components["headers"]["RequestId"];
5703
6385
  [name: string]: unknown;
@@ -5706,7 +6388,7 @@ interface operations {
5706
6388
  "application/json": components["schemas"]["ErrorResponseDto"];
5707
6389
  };
5708
6390
  };
5709
- /** @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. */
5710
6392
  429: {
5711
6393
  headers: {
5712
6394
  "Retry-After": components["headers"]["Retry-After"];
@@ -5721,18 +6403,34 @@ interface operations {
5721
6403
  };
5722
6404
  };
5723
6405
  };
5724
- ClientController_vapidPublicKey: {
6406
+ BatchesController_flush: {
5725
6407
  parameters: {
5726
6408
  query?: never;
5727
- header?: never;
5728
- 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
+ };
5729
6425
  cookie?: never;
5730
6426
  };
5731
6427
  requestBody?: never;
5732
6428
  responses: {
5733
- /** @description The public key. */
6429
+ /** @description Closed; the carriers are on their way. */
5734
6430
  200: {
5735
6431
  headers: {
6432
+ /** @description `true` when this response is a replay of an earlier request with the same `Idempotency-Key`. */
6433
+ "Idempotent-Replay"?: "true";
5736
6434
  "X-RateLimit-Limit-long": components["headers"]["X-RateLimit-Limit-long"];
5737
6435
  "X-RateLimit-Limit-short": components["headers"]["X-RateLimit-Limit-short"];
5738
6436
  "X-RateLimit-Remaining-long": components["headers"]["X-RateLimit-Remaining-long"];
@@ -5743,10 +6441,10 @@ interface operations {
5743
6441
  [name: string]: unknown;
5744
6442
  };
5745
6443
  content: {
5746
- "application/json": components["schemas"]["VapidPublicKeyDto"];
6444
+ "application/json": components["schemas"]["FlushBatchResponseDto"];
5747
6445
  };
5748
6446
  };
5749
- /** @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/…`). */
5750
6448
  401: {
5751
6449
  headers: {
5752
6450
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5756,7 +6454,7 @@ interface operations {
5756
6454
  "application/json": components["schemas"]["ErrorResponseDto"];
5757
6455
  };
5758
6456
  };
5759
- /** @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). */
5760
6458
  403: {
5761
6459
  headers: {
5762
6460
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5766,7 +6464,7 @@ interface operations {
5766
6464
  "application/json": components["schemas"]["ErrorResponseDto"];
5767
6465
  };
5768
6466
  };
5769
- /** @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. */
5770
6468
  404: {
5771
6469
  headers: {
5772
6470
  "X-Request-Id": components["headers"]["RequestId"];
@@ -5776,7 +6474,19 @@ interface operations {
5776
6474
  "application/json": components["schemas"]["ErrorResponseDto"];
5777
6475
  };
5778
6476
  };
5779
- /** @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. */
5780
6490
  429: {
5781
6491
  headers: {
5782
6492
  "Retry-After": components["headers"]["Retry-After"];
@@ -5882,7 +6592,7 @@ interface operations {
5882
6592
  parameters: {
5883
6593
  query?: never;
5884
6594
  header?: {
5885
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
6595
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
5886
6596
  "Idempotency-Key"?: string;
5887
6597
  };
5888
6598
  path: {
@@ -6320,7 +7030,7 @@ interface operations {
6320
7030
  parameters: {
6321
7031
  query?: never;
6322
7032
  header?: {
6323
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
7033
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
6324
7034
  "Idempotency-Key"?: string;
6325
7035
  };
6326
7036
  path: {
@@ -6516,7 +7226,7 @@ interface operations {
6516
7226
  parameters: {
6517
7227
  query?: never;
6518
7228
  header?: {
6519
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
7229
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
6520
7230
  "Idempotency-Key"?: string;
6521
7231
  };
6522
7232
  path: {
@@ -6878,7 +7588,7 @@ interface operations {
6878
7588
  parameters: {
6879
7589
  query?: never;
6880
7590
  header?: {
6881
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
7591
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
6882
7592
  "Idempotency-Key"?: string;
6883
7593
  };
6884
7594
  path: {
@@ -7323,7 +8033,7 @@ interface operations {
7323
8033
  parameters: {
7324
8034
  query?: never;
7325
8035
  header?: {
7326
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
8036
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
7327
8037
  "Idempotency-Key"?: string;
7328
8038
  };
7329
8039
  path: {
@@ -8544,7 +9254,7 @@ interface operations {
8544
9254
  parameters: {
8545
9255
  query?: never;
8546
9256
  header: {
8547
- /** @description Required unless `dry_run` is true. 1..256 chars of [A-Za-z0-9_\-:]; the same key with the same body returns the original notification. */
9257
+ /** @description Required unless `dry_run` is true. 1 to 256 characters of `A-Z a-z 0-9 . _ : -` (`invoice.paid:inv_123`); the same key with the same body returns the original notification. Any other character is a 400 that names it: a send is never dropped silently. */
8548
9258
  "Idempotency-Key": string;
8549
9259
  };
8550
9260
  path: {
@@ -8598,7 +9308,7 @@ interface operations {
8598
9308
  "application/json": components["schemas"]["SendNotificationResponseDto"];
8599
9309
  };
8600
9310
  };
8601
- /** @description `IDEMPOTENCY_KEY_REQUIRED`: no `Idempotency-Key`; `TOO_MANY_RECIPIENTS`: over 1,000; `VALIDATION_ERROR`: a field is invalid. */
9311
+ /** @description `IDEMPOTENCY_KEY_REQUIRED`: no `Idempotency-Key`; `BAD_REQUEST`: the `Idempotency-Key` is over 256 characters or has a character outside `A-Z a-z 0-9 . _ : -` (the message names it); `TOO_MANY_RECIPIENTS`: over 1,000; `VALIDATION_ERROR`: a field is invalid (an invalid `cancellation_key` included). */
8602
9312
  400: {
8603
9313
  headers: {
8604
9314
  "X-Request-Id": components["headers"]["RequestId"];
@@ -8660,7 +9370,7 @@ interface operations {
8660
9370
  "application/json": components["schemas"]["ErrorResponseDto"];
8661
9371
  };
8662
9372
  };
8663
- /** @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. */
8664
9374
  422: {
8665
9375
  headers: {
8666
9376
  "X-Request-Id": components["headers"]["RequestId"];
@@ -8720,7 +9430,7 @@ interface operations {
8720
9430
  "application/json": components["schemas"]["CancelByKeyResponseDto"];
8721
9431
  };
8722
9432
  };
8723
- /** @description `VALIDATION_ERROR`: `cancellation_key` is missing. */
9433
+ /** @description `VALIDATION_ERROR`: `cancellation_key` is missing or not 1-255 characters of `A-Z a-z 0-9 . _ : @ | -`. */
8724
9434
  400: {
8725
9435
  headers: {
8726
9436
  "X-Request-Id": components["headers"]["RequestId"];
@@ -9206,7 +9916,7 @@ interface operations {
9206
9916
  parameters: {
9207
9917
  query?: never;
9208
9918
  header?: {
9209
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original result for 24 h. */
9919
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original result for 24 h. */
9210
9920
  "Idempotency-Key"?: string;
9211
9921
  };
9212
9922
  path: {
@@ -9762,7 +10472,7 @@ interface operations {
9762
10472
  parameters: {
9763
10473
  query?: never;
9764
10474
  header?: {
9765
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
10475
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
9766
10476
  "Idempotency-Key"?: string;
9767
10477
  };
9768
10478
  path: {
@@ -10091,6 +10801,111 @@ interface operations {
10091
10801
  };
10092
10802
  };
10093
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
+ };
10094
10909
  PreferencesController_retrieve: {
10095
10910
  parameters: {
10096
10911
  query?: never;
@@ -11005,7 +11820,7 @@ interface operations {
11005
11820
  parameters: {
11006
11821
  query?: never;
11007
11822
  header?: {
11008
- /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9_-:]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
11823
+ /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
11009
11824
  "Idempotency-Key"?: string;
11010
11825
  };
11011
11826
  path: {
@@ -11290,7 +12105,7 @@ interface operations {
11290
12105
  parameters: {
11291
12106
  query?: never;
11292
12107
  header?: {
11293
- /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9_-:]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
12108
+ /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
11294
12109
  "Idempotency-Key"?: string;
11295
12110
  };
11296
12111
  path: {
@@ -11411,7 +12226,7 @@ interface operations {
11411
12226
  parameters: {
11412
12227
  query?: never;
11413
12228
  header?: {
11414
- /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9_-:]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
12229
+ /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
11415
12230
  "Idempotency-Key"?: string;
11416
12231
  };
11417
12232
  path: {
@@ -11522,7 +12337,7 @@ interface operations {
11522
12337
  parameters: {
11523
12338
  query?: never;
11524
12339
  header?: {
11525
- /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9_-:]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
12340
+ /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
11526
12341
  "Idempotency-Key"?: string;
11527
12342
  };
11528
12343
  path: {
@@ -11905,7 +12720,7 @@ interface operations {
11905
12720
  endpoint_id?: string;
11906
12721
  };
11907
12722
  header?: {
11908
- /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9_-:]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
12723
+ /** @description Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`. */
11909
12724
  "Idempotency-Key"?: string;
11910
12725
  };
11911
12726
  path: {
@@ -12090,6 +12905,18 @@ type NotificationStatus = components["schemas"]["NotificationStatus"];
12090
12905
  declare const NotificationStatus: {
12091
12906
  values: readonly ["scheduled", "accepted", "planned", "cancelled"];
12092
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
+ };
12093
12920
  type NotifyChannel = components["schemas"]["NotifyChannel"];
12094
12921
  declare const NotifyChannel: {
12095
12922
  values: readonly ["inbox", "email", "push", "webpush"];
@@ -12098,6 +12925,7 @@ declare const NotifyChannel: {
12098
12925
  * Why a delivery was skipped, held, retried or failed. Open enum: new reasons may be added.
12099
12926
  *
12100
12927
  * - `suppressed_preference`: The recipient turned this channel off for this type or its category. Fix: Nothing to fix: the recipient chose this. Mark the category channel `mandatory` only for messages they must receive.
12928
+ * - `default_off`: This channel is off by default for the category, and the recipient has not turned it on. Fix: Nothing to fix if the channel is opt-in by design: it is sent once the recipient turns it on in their preferences. Set the category default to `on` to send it without an opt-in.
12101
12929
  * - `unsubscribed_all`: The recipient unsubscribed from all non-critical notifications. Fix: Only types marked `critical` still reach them; otherwise the recipient has to opt back in.
12102
12930
  * - `held_quiet_hours`: Held until the recipient's quiet hours end. Fix: It is sent when the window ends. Mark the type `critical` if it must not wait.
12103
12931
  * - `scheduled_send`: Waiting for the send time given in `send_at` or `delay_seconds`. Fix: It is sent at that time. Cancel it with the notification id or its `cancellation_key`.
@@ -12116,6 +12944,8 @@ declare const NotifyChannel: {
12116
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.
12117
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.
12118
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.
12119
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.
12120
12950
  * - `actor_excluded`: The recipient is the actor who caused the notification. Fix: Pass `exclude_actor: false` to notify the actor too.
12121
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`.
@@ -12132,12 +12962,20 @@ declare const NotifyChannel: {
12132
12962
  */
12133
12963
  type NotifyDeliveryReason = components["schemas"]["NotifyDeliveryReason"];
12134
12964
  declare const NotifyDeliveryReason: {
12135
- values: readonly ["suppressed_preference", "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"];
12136
12970
  };
12137
12971
  type NotifyEmailPauseReason = components["schemas"]["NotifyEmailPauseReason"];
12138
12972
  declare const NotifyEmailPauseReason: {
12139
12973
  values: readonly ["complaints", "bounces"];
12140
12974
  };
12975
+ type NotifyQuietHoursSource = components["schemas"]["NotifyQuietHoursSource"];
12976
+ declare const NotifyQuietHoursSource: {
12977
+ values: readonly ["recipient", "workspace"];
12978
+ };
12141
12979
  type NotifyRecipientDeletionCause = components["schemas"]["NotifyRecipientDeletionCause"];
12142
12980
  declare const NotifyRecipientDeletionCause: {
12143
12981
  values: readonly ["api", "auth_user_deleted"];
@@ -12162,6 +13000,10 @@ type NotifyWebhookDeviceChannel = components["schemas"]["NotifyWebhookDeviceChan
12162
13000
  declare const NotifyWebhookDeviceChannel: {
12163
13001
  values: readonly ["apns", "fcm", "webpush"];
12164
13002
  };
13003
+ type NotifyWeekday = components["schemas"]["NotifyWeekday"];
13004
+ declare const NotifyWeekday: {
13005
+ values: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
13006
+ };
12165
13007
  type PlanDecision = components["schemas"]["PlanDecision"];
12166
13008
  declare const PlanDecision: {
12167
13009
  values: readonly ["deliver", "schedule", "skip"];
@@ -12219,6 +13061,18 @@ declare const WebhookEventType: {
12219
13061
  };
12220
13062
  interface ApnsCredential extends Open<components["schemas"]["ApnsCredentialDto"]> {
12221
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
+ }
12222
13076
  interface BulkRowError extends Open<components["schemas"]["BulkRowErrorDto"]> {
12223
13077
  }
12224
13078
  interface BulkRowResult extends Open<components["schemas"]["BulkRowResultDto"]> {
@@ -12263,6 +13117,8 @@ interface DeviceMove extends Open<components["schemas"]["DeviceMoveDto"]> {
12263
13117
  }
12264
13118
  interface DryRun extends Open<components["schemas"]["DryRunResponseDto"]> {
12265
13119
  }
13120
+ interface EffectiveQuietHours extends Open<components["schemas"]["EffectiveQuietHoursDto"]> {
13121
+ }
12266
13122
  interface Export extends Open<components["schemas"]["ExportDto"]> {
12267
13123
  }
12268
13124
  interface ExportNotificationType extends Open<components["schemas"]["ExportNotificationTypeDto"]> {
@@ -12273,6 +13129,8 @@ interface FallbackStepView extends Open<components["schemas"]["FallbackStepViewD
12273
13129
  }
12274
13130
  interface FcmCredential extends Open<components["schemas"]["FcmCredentialDto"]> {
12275
13131
  }
13132
+ interface FlushBatch extends Open<components["schemas"]["FlushBatchResponseDto"]> {
13133
+ }
12276
13134
  interface InboxAction extends Open<components["schemas"]["InboxActionDto"]> {
12277
13135
  }
12278
13136
  interface InboxCounts extends Open<components["schemas"]["InboxCountsDto"]> {
@@ -12301,6 +13159,8 @@ interface NotificationType extends Open<components["schemas"]["NotificationTypeD
12301
13159
  }
12302
13160
  interface NotificationTypeList extends Open<components["schemas"]["NotificationTypeListResponseDto"]> {
12303
13161
  }
13162
+ interface NotifyBrandingView extends Open<components["schemas"]["NotifyBrandingViewDto"]> {
13163
+ }
12304
13164
  interface NotifyCredentialInvalidData extends Open<components["schemas"]["NotifyCredentialInvalidDataDto"]> {
12305
13165
  }
12306
13166
  interface NotifyDeliveryEventData extends Open<components["schemas"]["NotifyDeliveryEventDataDto"]> {
@@ -12327,10 +13187,14 @@ interface NotifyWebhookRecipient extends Open<components["schemas"]["NotifyWebho
12327
13187
  }
12328
13188
  interface Pagination extends Open<components["schemas"]["PaginationDto"]> {
12329
13189
  }
13190
+ interface PlanBatch extends Open<components["schemas"]["PlanBatchDto"]> {
13191
+ }
12330
13192
  interface PlanRow extends Open<components["schemas"]["PlanRowDto"]> {
12331
13193
  }
12332
13194
  interface PreferenceCell extends Open<components["schemas"]["PreferenceCellDto"]> {
12333
13195
  }
13196
+ interface PreferenceLink extends Open<components["schemas"]["PreferenceLinkDto"]> {
13197
+ }
12334
13198
  interface PreferenceSet extends Open<components["schemas"]["PreferenceSetDto"]> {
12335
13199
  }
12336
13200
  interface PreviewChannel extends Open<components["schemas"]["PreviewChannelDto"]> {
@@ -12417,6 +13281,8 @@ type MeInboxMarkParams = NonNullable<paths["/v1/client/inbox/mark"]["post"]["req
12417
13281
  type MeInboxInteractParams = NonNullable<paths["/v1/client/inbox/{item_id}/interact"]["post"]["requestBody"]>["content"]["application/json"];
12418
13282
  /** Params for `me.preferences.update` (PATCH /v1/client/preferences). */
12419
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"]>;
12420
13286
  /** Params for `categories.list` (GET /v1/workspaces/{workspace_id}/categories). */
12421
13287
  type CategoryListParams = NonNullable<paths["/v1/workspaces/{workspace_id}/categories"]["get"]["parameters"]["query"]>;
12422
13288
  /** Params for `categories.create` (POST /v1/workspaces/{workspace_id}/categories). */
@@ -12469,6 +13335,8 @@ type RecipientUpdateParams = NonNullable<paths["/v1/workspaces/{workspace_id}/re
12469
13335
  type RecipientDeviceCreateParams = NonNullable<paths["/v1/workspaces/{workspace_id}/recipients/{external_id}/devices"]["post"]["requestBody"]>["content"]["application/json"];
12470
13336
  /** Params for `recipients.inbox.list` (GET /v1/workspaces/{workspace_id}/recipients/{external_id}/inbox). */
12471
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"];
12472
13340
  /** Params for `recipients.preferences.replace` (PUT /v1/workspaces/{workspace_id}/recipients/{external_id}/preferences). */
12473
13341
  type RecipientPreferenceReplaceParams = NonNullable<paths["/v1/workspaces/{workspace_id}/recipients/{external_id}/preferences"]["put"]["requestBody"]>["content"]["application/json"];
12474
13342
  /** Params for `recipients.preferences.update` (PATCH /v1/workspaces/{workspace_id}/recipients/{external_id}/preferences). */
@@ -12646,6 +13514,76 @@ declare class APIResource {
12646
13514
  protected readonly _b: Bound;
12647
13515
  constructor(client: APIClient, bound?: Bound);
12648
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
+ }
12649
13587
  /** `categories` */
12650
13588
  declare class CategoriesResource extends APIResource {
12651
13589
  /**
@@ -13309,7 +14247,18 @@ declare class NotificationTypesResource extends APIResource {
13309
14247
  * @see https://productcraft.co/docs/notify/api-reference#patch-v1-workspaces-workspace-id-notification-types-type-id
13310
14248
  * @example
13311
14249
  * ```ts
13312
- * 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
+ * });
13313
14262
  * ```
13314
14263
  */
13315
14264
  update(typeId: string, params?: NotificationTypeUpdateParams, options?: RequestOptions): APIPromise<WithLastResponse<NotificationType>>;
@@ -13346,7 +14295,7 @@ declare class NotificationsResource extends APIResource {
13346
14295
  *
13347
14296
  * @param params - `Notify.NotificationCancelByKeyParams`.
13348
14297
  * @param options - Per-request options.
13349
- * @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: `cancellation_key` is missing.
14298
+ * @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: `cancellation_key` is missing or not 1-255 characters of `A-Z a-z 0-9 . _ : @ | -`.
13350
14299
  * @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/…`).
13351
14300
  * @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).
13352
14301
  * @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.
@@ -13354,7 +14303,7 @@ declare class NotificationsResource extends APIResource {
13354
14303
  * @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications-cancel
13355
14304
  * @example
13356
14305
  * ```ts
13357
- * const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite:inv_77" });
14306
+ * const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite.sent:inv_77" });
13358
14307
  * ```
13359
14308
  */
13360
14309
  cancelByKey(params: NotificationCancelByKeyParams, options?: RequestOptions): APIPromise<WithLastResponse<CancelByKey>>;
@@ -13427,19 +14376,19 @@ declare class NotificationsResource extends APIResource {
13427
14376
  /**
13428
14377
  * Send a notification
13429
14378
  *
13430
- * Notifies up to 1,000 recipients with one notification type, across the type's channels (in-app inbox, email, push, web push), honouring each recipient's preferences. Returns 202 as soon as the send is stored; delivery happens in the background (see `GET /deliveries`). Unknown external ids do not fail the call: they are listed in `skipped` (`create_missing: true` creates them instead); the call fails only when no recipient can be notified. An `Idempotency-Key` is **required** (a deterministic one such as `invoice.paid:inv_123` is best): the same key and body return the same notification, even when retried much later; the same key with a different body is a 409. `dry_run: true` returns the plan per recipient and channel with the reason for every skip, and stores nothing (200, no key needed). Limits: 3,000 recipients per minute per workspace; 30 notifications per minute per recipient (critical types have a separate 30), beyond which deliveries are skipped as `rate_limited`.
14379
+ * Notifies up to 1,000 recipients with one notification type, across the type's channels (in-app inbox, email, push, web push), honouring each recipient's preferences. Returns 202 as soon as the send is stored; delivery happens in the background (see `GET /deliveries`). Unknown external ids do not fail the call: they are listed in `skipped` (`create_missing: true` creates them instead); the call fails only when no recipient can be notified. An `Idempotency-Key` is **required** (a deterministic one built from your event, such as `invoice.paid:inv_123`, is best; dots are fine): the same key and body return the same notification, even when retried much later; the same key with a different body is a 409. `dry_run: true` returns the plan per recipient and channel with the reason for every skip, and stores nothing (200, no key needed). Limits: 3,000 recipients per minute per workspace; 30 notifications per minute per recipient (critical types have a separate 30), beyond which deliveries are skipped as `rate_limited`.
13431
14380
  *
13432
14381
  * Credential: `bearer`.
13433
14382
  *
13434
14383
  * @param params - `Notify.NotificationSendParams`.
13435
14384
  * @param options - Per-request options (an Idempotency-Key is sent automatically; override with `idempotencyKey`).
13436
- * @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR, IDEMPOTENCY_KEY_REQUIRED, TOO_MANY_RECIPIENTS: `IDEMPOTENCY_KEY_REQUIRED`: no `Idempotency-Key`; `TOO_MANY_RECIPIENTS`: over 1,000; `VALIDATION_ERROR`: a field is invalid.
14385
+ * @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR, IDEMPOTENCY_KEY_REQUIRED, TOO_MANY_RECIPIENTS: `IDEMPOTENCY_KEY_REQUIRED`: no `Idempotency-Key`; `BAD_REQUEST`: the `Idempotency-Key` is over 256 characters or has a character outside `A-Z a-z 0-9 . _ : -` (the message names it); `TOO_MANY_RECIPIENTS`: over 1,000; `VALIDATION_ERROR`: a field is invalid (an invalid `cancellation_key` included).
13437
14386
  * @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/…`).
13438
14387
  * @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).
13439
14388
  * @throws {NotFoundError} 404 NOT_FOUND, NOTIFICATION_TYPE_NOT_FOUND: `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key.
13440
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).
13441
14390
  * @throws {APIError} 413 PAYLOAD_TOO_LARGE, DATA_TOO_LARGE: `DATA_TOO_LARGE`: `data` is over 16 KB.
13442
- * @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.
13443
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.
13444
14393
  * @see POST /v1/workspaces/{workspace_id}/notifications
13445
14394
  * @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications
@@ -13678,6 +14627,30 @@ declare class RecipientsResource extends APIResource {
13678
14627
  * ```
13679
14628
  */
13680
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>>;
13681
14654
  /**
13682
14655
  * Erase a recipient (GDPR)
13683
14656
  *
@@ -13896,7 +14869,14 @@ declare class SettingsResource extends APIResource {
13896
14869
  * @see https://productcraft.co/docs/notify/api-reference#patch-v1-workspaces-workspace-id-settings
13897
14870
  * @example
13898
14871
  * ```ts
13899
- * 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
+ * });
13900
14880
  * ```
13901
14881
  */
13902
14882
  update(params?: SettingsUpdateParams, options?: RequestOptions): APIPromise<WithLastResponse<NotifySettings>>;
@@ -14233,6 +15213,7 @@ declare class WebhooksResource extends APIResource {
14233
15213
  /** `notify` */
14234
15214
  declare class NotifyResources extends APIResource {
14235
15215
  #private;
15216
+ get batches(): BatchesResource;
14236
15217
  get categories(): CategoriesResource;
14237
15218
  get channels(): ChannelsResource;
14238
15219
  get deliveries(): DeliveriesResource;
@@ -14494,15 +15475,21 @@ type __DeviceState = DeviceState;
14494
15475
  type __InboxItemStatusFilter = InboxItemStatusFilter;
14495
15476
  type __InboxMarkAction = InboxMarkAction;
14496
15477
  type __NotificationStatus = NotificationStatus;
15478
+ type __NotifyBatchInboxMode = NotifyBatchInboxMode;
15479
+ type __NotifyBatchMode = NotifyBatchMode;
15480
+ type __NotifyBatchState = NotifyBatchState;
14497
15481
  type __NotifyChannel = NotifyChannel;
14498
15482
  type __NotifyDeliveryReason = NotifyDeliveryReason;
15483
+ type __NotifyDigestFrequency = NotifyDigestFrequency;
14499
15484
  type __NotifyEmailPauseReason = NotifyEmailPauseReason;
15485
+ type __NotifyQuietHoursSource = NotifyQuietHoursSource;
14500
15486
  type __NotifyRecipientDeletionCause = NotifyRecipientDeletionCause;
14501
15487
  type __NotifyStatsChannel = NotifyStatsChannel;
14502
15488
  type __NotifyWebhookChannel = NotifyWebhookChannel;
14503
15489
  type __NotifyWebhookCredentialProvider = NotifyWebhookCredentialProvider;
14504
15490
  type __NotifyWebhookDeliveryState = NotifyWebhookDeliveryState;
14505
15491
  type __NotifyWebhookDeviceChannel = NotifyWebhookDeviceChannel;
15492
+ type __NotifyWeekday = NotifyWeekday;
14506
15493
  type __PlanDecision = PlanDecision;
14507
15494
  type __PreferenceChannel = PreferenceChannel;
14508
15495
  type __PreferenceScope = PreferenceScope;
@@ -14517,6 +15504,12 @@ type __WebhookEndpointStatus = WebhookEndpointStatus;
14517
15504
  type __WebhookEventStatus = WebhookEventStatus;
14518
15505
  type __WebhookEventType = WebhookEventType;
14519
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;
14520
15513
  type __BulkRowError = BulkRowError;
14521
15514
  type __BulkRowResult = BulkRowResult;
14522
15515
  type __BulkUpsertRecipients = BulkUpsertRecipients;
@@ -14539,11 +15532,13 @@ type __Device = Device;
14539
15532
  type __DeviceList = DeviceList;
14540
15533
  type __DeviceMove = DeviceMove;
14541
15534
  type __DryRun = DryRun;
15535
+ type __EffectiveQuietHours = EffectiveQuietHours;
14542
15536
  type __Export = Export;
14543
15537
  type __ExportNotificationType = ExportNotificationType;
14544
15538
  type __ExportSettings = ExportSettings;
14545
15539
  type __FallbackStepView = FallbackStepView;
14546
15540
  type __FcmCredential = FcmCredential;
15541
+ type __FlushBatch = FlushBatch;
14547
15542
  type __InboxAction = InboxAction;
14548
15543
  type __InboxCounts = InboxCounts;
14549
15544
  type __InboxItem = InboxItem;
@@ -14561,6 +15556,7 @@ type __Notification = Notification;
14561
15556
  type __NotificationList = NotificationList;
14562
15557
  type __NotificationType = NotificationType;
14563
15558
  type __NotificationTypeList = NotificationTypeList;
15559
+ type __NotifyBrandingView = NotifyBrandingView;
14564
15560
  type __NotifyCredentialInvalidData = NotifyCredentialInvalidData;
14565
15561
  type __NotifyDeliveryEventData = NotifyDeliveryEventData;
14566
15562
  type __NotifyDeviceEventData = NotifyDeviceEventData;
@@ -14574,8 +15570,10 @@ type __NotifyStatsDay = NotifyStatsDay;
14574
15570
  type __NotifyStats = NotifyStats;
14575
15571
  type __NotifyWebhookRecipient = NotifyWebhookRecipient;
14576
15572
  type __Pagination = Pagination;
15573
+ type __PlanBatch = PlanBatch;
14577
15574
  type __PlanRow = PlanRow;
14578
15575
  type __PreferenceCell = PreferenceCell;
15576
+ type __PreferenceLink = PreferenceLink;
14579
15577
  type __PreferenceSet = PreferenceSet;
14580
15578
  type __PreviewChannel = PreviewChannel;
14581
15579
  type __Preview = Preview;
@@ -14620,6 +15618,7 @@ type __MeInboxListParams = MeInboxListParams;
14620
15618
  type __MeInboxMarkParams = MeInboxMarkParams;
14621
15619
  type __MeInboxInteractParams = MeInboxInteractParams;
14622
15620
  type __MePreferenceUpdateParams = MePreferenceUpdateParams;
15621
+ type __BatchListParams = BatchListParams;
14623
15622
  type __CategoryListParams = CategoryListParams;
14624
15623
  type __CategoryCreateParams = CategoryCreateParams;
14625
15624
  type __CategoryUpdateParams = CategoryUpdateParams;
@@ -14646,6 +15645,7 @@ type __RecipientIdentifyParams = RecipientIdentifyParams;
14646
15645
  type __RecipientUpdateParams = RecipientUpdateParams;
14647
15646
  type __RecipientDeviceCreateParams = RecipientDeviceCreateParams;
14648
15647
  type __RecipientInboxListParams = RecipientInboxListParams;
15648
+ type __RecipientCreatePreferenceLinkParams = RecipientCreatePreferenceLinkParams;
14649
15649
  type __RecipientPreferenceReplaceParams = RecipientPreferenceReplaceParams;
14650
15650
  type __RecipientPreferenceUpdateParams = RecipientPreferenceUpdateParams;
14651
15651
  type __RecipientTimelineParams = RecipientTimelineParams;
@@ -14786,18 +15786,38 @@ declare namespace Notify {
14786
15786
  const NotificationStatus: {
14787
15787
  values: readonly ["scheduled", "accepted", "planned", "cancelled"];
14788
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
+ };
14789
15801
  type NotifyChannel = __NotifyChannel;
14790
15802
  const NotifyChannel: {
14791
15803
  values: readonly ["inbox", "email", "push", "webpush"];
14792
15804
  };
14793
15805
  type NotifyDeliveryReason = __NotifyDeliveryReason;
14794
15806
  const NotifyDeliveryReason: {
14795
- values: readonly ["suppressed_preference", "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"];
14796
15812
  };
14797
15813
  type NotifyEmailPauseReason = __NotifyEmailPauseReason;
14798
15814
  const NotifyEmailPauseReason: {
14799
15815
  values: readonly ["complaints", "bounces"];
14800
15816
  };
15817
+ type NotifyQuietHoursSource = __NotifyQuietHoursSource;
15818
+ const NotifyQuietHoursSource: {
15819
+ values: readonly ["recipient", "workspace"];
15820
+ };
14801
15821
  type NotifyRecipientDeletionCause = __NotifyRecipientDeletionCause;
14802
15822
  const NotifyRecipientDeletionCause: {
14803
15823
  values: readonly ["api", "auth_user_deleted"];
@@ -14822,6 +15842,10 @@ declare namespace Notify {
14822
15842
  const NotifyWebhookDeviceChannel: {
14823
15843
  values: readonly ["apns", "fcm", "webpush"];
14824
15844
  };
15845
+ type NotifyWeekday = __NotifyWeekday;
15846
+ const NotifyWeekday: {
15847
+ values: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
15848
+ };
14825
15849
  type PlanDecision = __PlanDecision;
14826
15850
  const PlanDecision: {
14827
15851
  values: readonly ["deliver", "schedule", "skip"];
@@ -14875,6 +15899,12 @@ declare namespace Notify {
14875
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"];
14876
15900
  };
14877
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;
14878
15908
  type BulkRowError = __BulkRowError;
14879
15909
  type BulkRowResult = __BulkRowResult;
14880
15910
  type BulkUpsertRecipients = __BulkUpsertRecipients;
@@ -14897,11 +15927,13 @@ declare namespace Notify {
14897
15927
  type DeviceList = __DeviceList;
14898
15928
  type DeviceMove = __DeviceMove;
14899
15929
  type DryRun = __DryRun;
15930
+ type EffectiveQuietHours = __EffectiveQuietHours;
14900
15931
  type Export = __Export;
14901
15932
  type ExportNotificationType = __ExportNotificationType;
14902
15933
  type ExportSettings = __ExportSettings;
14903
15934
  type FallbackStepView = __FallbackStepView;
14904
15935
  type FcmCredential = __FcmCredential;
15936
+ type FlushBatch = __FlushBatch;
14905
15937
  type InboxAction = __InboxAction;
14906
15938
  type InboxCounts = __InboxCounts;
14907
15939
  type InboxItem = __InboxItem;
@@ -14922,6 +15954,7 @@ declare namespace Notify {
14922
15954
  type NotificationList = __NotificationList;
14923
15955
  type NotificationType = __NotificationType;
14924
15956
  type NotificationTypeList = __NotificationTypeList;
15957
+ type NotifyBrandingView = __NotifyBrandingView;
14925
15958
  type NotifyCredentialInvalidData = __NotifyCredentialInvalidData;
14926
15959
  type NotifyDeliveryEventData = __NotifyDeliveryEventData;
14927
15960
  type NotifyDeviceEventData = __NotifyDeviceEventData;
@@ -14935,8 +15968,10 @@ declare namespace Notify {
14935
15968
  type NotifyStats = __NotifyStats;
14936
15969
  type NotifyWebhookRecipient = __NotifyWebhookRecipient;
14937
15970
  type Pagination = __Pagination;
15971
+ type PlanBatch = __PlanBatch;
14938
15972
  type PlanRow = __PlanRow;
14939
15973
  type PreferenceCell = __PreferenceCell;
15974
+ type PreferenceLink = __PreferenceLink;
14940
15975
  type PreferenceSet = __PreferenceSet;
14941
15976
  type PreviewChannel = __PreviewChannel;
14942
15977
  type Preview = __Preview;
@@ -14982,6 +16017,7 @@ declare namespace Notify {
14982
16017
  type MeInboxMarkParams = __MeInboxMarkParams;
14983
16018
  type MeInboxInteractParams = __MeInboxInteractParams;
14984
16019
  type MePreferenceUpdateParams = __MePreferenceUpdateParams;
16020
+ type BatchListParams = __BatchListParams;
14985
16021
  type CategoryListParams = __CategoryListParams;
14986
16022
  type CategoryCreateParams = __CategoryCreateParams;
14987
16023
  type CategoryUpdateParams = __CategoryUpdateParams;
@@ -15008,6 +16044,7 @@ declare namespace Notify {
15008
16044
  type RecipientUpdateParams = __RecipientUpdateParams;
15009
16045
  type RecipientDeviceCreateParams = __RecipientDeviceCreateParams;
15010
16046
  type RecipientInboxListParams = __RecipientInboxListParams;
16047
+ type RecipientCreatePreferenceLinkParams = __RecipientCreatePreferenceLinkParams;
15011
16048
  type RecipientPreferenceReplaceParams = __RecipientPreferenceReplaceParams;
15012
16049
  type RecipientPreferenceUpdateParams = __RecipientPreferenceUpdateParams;
15013
16050
  type RecipientTimelineParams = __RecipientTimelineParams;