@productcraft/notify 0.1.1 → 0.2.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
@@ -632,7 +632,7 @@ type paths = {
632
632
  put?: never;
633
633
  /**
634
634
  * 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`.
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 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
636
  */
637
637
  post: operations["NotificationsController_send"];
638
638
  delete?: never;
@@ -1354,7 +1354,7 @@ type components = {
1354
1354
  CancelByKeyDto: {
1355
1355
  /**
1356
1356
  * @description The `cancellation_key` given at send.
1357
- * @example invite:inv_77
1357
+ * @example invite.sent:inv_77
1358
1358
  */
1359
1359
  cancellation_key: string;
1360
1360
  };
@@ -1541,9 +1541,11 @@ type components = {
1541
1541
  ClientPreferencesDto: {
1542
1542
  /** @description The workspace's categories in display order, with their defaults. */
1543
1543
  categories: components["schemas"]["ClientCategoryDto"][];
1544
+ /** @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. */
1545
+ effective_quiet_hours: components["schemas"]["EffectiveQuietHoursDto"] | null;
1544
1546
  /** @description Cells the recipient set (anything else follows the category defaults). */
1545
1547
  preferences: components["schemas"]["PreferenceCellDto"][];
1546
- /** @description Quiet window. */
1548
+ /** @description The recipient's own quiet window; null when they set none (the workspace default then applies, see `effective_quiet_hours`). */
1547
1549
  quiet_hours: components["schemas"]["QuietHoursDto"] | null;
1548
1550
  /** @description IANA time zone. */
1549
1551
  timezone: string | null;
@@ -2340,6 +2342,25 @@ type components = {
2340
2342
  /** @description The notification type key. */
2341
2343
  type: string;
2342
2344
  };
2345
+ EffectiveQuietHoursDto: {
2346
+ /**
2347
+ * @description End of the window, `HH:MM`. An end before the start spans midnight.
2348
+ * @example 08:00
2349
+ */
2350
+ end: string;
2351
+ /** @description `recipient`: their own window (`quiet_hours`). `workspace`: they set none, so the workspace default applies; setting their own window replaces it. */
2352
+ source: components["schemas"]["NotifyQuietHoursSource"];
2353
+ /**
2354
+ * @description Start of the window, `HH:MM` 24-hour.
2355
+ * @example 22:00
2356
+ */
2357
+ start: string;
2358
+ /**
2359
+ * @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.
2360
+ * @example Europe/Lisbon
2361
+ */
2362
+ timezone: string | null;
2363
+ };
2343
2364
  /**
2344
2365
  * EmailAutoPausedEvent
2345
2366
  * @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.
@@ -3182,6 +3203,7 @@ type components = {
3182
3203
  * @description Why a delivery was skipped, held, retried or failed. Open enum: new reasons may be added.
3183
3204
  *
3184
3205
  * - `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.
3206
+ * - `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
3207
  * - `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
3208
  * - `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
3209
  * - `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`.
@@ -3215,7 +3237,7 @@ type components = {
3215
3237
  * - `provider_error`: The provider kept failing until retries ran out. Fix: Check the attempts for the provider status and code.
3216
3238
  * @enum {string}
3217
3239
  */
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";
3240
+ NotifyDeliveryReason: "suppressed_preference" | "default_off" | "unsubscribed_all" | "held_quiet_hours" | "scheduled_send" | "no_device" | "no_address" | "email_invalid" | "email_complained" | "email_paused" | "email_budget" | "email_backlog_full" | "channel_not_configured" | "channel_restricted" | "type_archived" | "credential_invalid" | "template_missing" | "rate_limited" | "throttled" | "read_in_inbox" | "awaiting_unread" | "actor_excluded" | "recipient_not_found" | "recipient_erased" | "mail_suppressed" | "mail_refused" | "pruned" | "payload_too_large" | "credential_error" | "circuit_open" | "expired" | "cancelled" | "provider_error";
3219
3241
  NotifyDeviceEventDataDto: {
3220
3242
  /**
3221
3243
  * @description The device channel.
@@ -3334,6 +3356,8 @@ type components = {
3334
3356
  */
3335
3357
  type_key: string;
3336
3358
  };
3359
+ /** @enum {string} */
3360
+ NotifyQuietHoursSource: "recipient" | "workspace";
3337
3361
  NotifyRecipientDeletedDataDto: {
3338
3362
  /**
3339
3363
  * @description `api`: erased through `DELETE /recipients/{external_id}`; `auth_user_deleted`: the linked Auth end user was deleted.
@@ -3573,11 +3597,13 @@ type components = {
3573
3597
  /** @enum {string} */
3574
3598
  PreferenceScope: "all" | "category" | "type";
3575
3599
  PreferenceSetDto: {
3600
+ /** @description The quiet window that applies: the recipient's own, else the workspace default. Null: no quiet hours apply. */
3601
+ effective_quiet_hours: components["schemas"]["EffectiveQuietHoursDto"] | null;
3576
3602
  /** @description The recipient external id. */
3577
3603
  external_id: string;
3578
3604
  /** @description Cells the recipient set (anything else follows the category defaults). */
3579
3605
  preferences: components["schemas"]["PreferenceCellDto"][];
3580
- /** @description Quiet window. */
3606
+ /** @description The recipient's own quiet window; null when they set none (the workspace default then applies, see `effective_quiet_hours`). */
3581
3607
  quiet_hours: components["schemas"]["QuietHoursDto"] | null;
3582
3608
  /** @description IANA time zone. */
3583
3609
  timezone: string | null;
@@ -3971,8 +3997,8 @@ type components = {
3971
3997
  /** @description Who caused the notification. */
3972
3998
  actor?: components["schemas"]["ActorDto"];
3973
3999
  /**
3974
- * @description Your key for cancelling later without storing our id (`POST /notifications/cancel`).
3975
- * @example invite:inv_77
4000
+ * @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`).
4001
+ * @example invite.sent:inv_77
3976
4002
  */
3977
4003
  cancellation_key?: string;
3978
4004
  /** @description Only these channels (a subset of the type's routing). */
@@ -5882,7 +5908,7 @@ interface operations {
5882
5908
  parameters: {
5883
5909
  query?: never;
5884
5910
  header?: {
5885
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
5911
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
5886
5912
  "Idempotency-Key"?: string;
5887
5913
  };
5888
5914
  path: {
@@ -6320,7 +6346,7 @@ interface operations {
6320
6346
  parameters: {
6321
6347
  query?: never;
6322
6348
  header?: {
6323
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
6349
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
6324
6350
  "Idempotency-Key"?: string;
6325
6351
  };
6326
6352
  path: {
@@ -6516,7 +6542,7 @@ interface operations {
6516
6542
  parameters: {
6517
6543
  query?: never;
6518
6544
  header?: {
6519
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
6545
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
6520
6546
  "Idempotency-Key"?: string;
6521
6547
  };
6522
6548
  path: {
@@ -6878,7 +6904,7 @@ interface operations {
6878
6904
  parameters: {
6879
6905
  query?: never;
6880
6906
  header?: {
6881
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
6907
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
6882
6908
  "Idempotency-Key"?: string;
6883
6909
  };
6884
6910
  path: {
@@ -7323,7 +7349,7 @@ interface operations {
7323
7349
  parameters: {
7324
7350
  query?: never;
7325
7351
  header?: {
7326
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
7352
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
7327
7353
  "Idempotency-Key"?: string;
7328
7354
  };
7329
7355
  path: {
@@ -8544,7 +8570,7 @@ interface operations {
8544
8570
  parameters: {
8545
8571
  query?: never;
8546
8572
  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. */
8573
+ /** @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
8574
  "Idempotency-Key": string;
8549
8575
  };
8550
8576
  path: {
@@ -8598,7 +8624,7 @@ interface operations {
8598
8624
  "application/json": components["schemas"]["SendNotificationResponseDto"];
8599
8625
  };
8600
8626
  };
8601
- /** @description `IDEMPOTENCY_KEY_REQUIRED`: no `Idempotency-Key`; `TOO_MANY_RECIPIENTS`: over 1,000; `VALIDATION_ERROR`: a field is invalid. */
8627
+ /** @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
8628
  400: {
8603
8629
  headers: {
8604
8630
  "X-Request-Id": components["headers"]["RequestId"];
@@ -8720,7 +8746,7 @@ interface operations {
8720
8746
  "application/json": components["schemas"]["CancelByKeyResponseDto"];
8721
8747
  };
8722
8748
  };
8723
- /** @description `VALIDATION_ERROR`: `cancellation_key` is missing. */
8749
+ /** @description `VALIDATION_ERROR`: `cancellation_key` is missing or not 1-255 characters of `A-Z a-z 0-9 . _ : @ | -`. */
8724
8750
  400: {
8725
8751
  headers: {
8726
8752
  "X-Request-Id": components["headers"]["RequestId"];
@@ -9206,7 +9232,7 @@ interface operations {
9206
9232
  parameters: {
9207
9233
  query?: never;
9208
9234
  header?: {
9209
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original result for 24 h. */
9235
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original result for 24 h. */
9210
9236
  "Idempotency-Key"?: string;
9211
9237
  };
9212
9238
  path: {
@@ -9762,7 +9788,7 @@ interface operations {
9762
9788
  parameters: {
9763
9789
  query?: never;
9764
9790
  header?: {
9765
- /** @description A key (1..256 chars, [A-Za-z0-9_\-:]) makes retries safe: a replay returns the original response for 24 h. */
9791
+ /** @description A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h. */
9766
9792
  "Idempotency-Key"?: string;
9767
9793
  };
9768
9794
  path: {
@@ -11005,7 +11031,7 @@ interface operations {
11005
11031
  parameters: {
11006
11032
  query?: never;
11007
11033
  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`. */
11034
+ /** @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
11035
  "Idempotency-Key"?: string;
11010
11036
  };
11011
11037
  path: {
@@ -11290,7 +11316,7 @@ interface operations {
11290
11316
  parameters: {
11291
11317
  query?: never;
11292
11318
  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`. */
11319
+ /** @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
11320
  "Idempotency-Key"?: string;
11295
11321
  };
11296
11322
  path: {
@@ -11411,7 +11437,7 @@ interface operations {
11411
11437
  parameters: {
11412
11438
  query?: never;
11413
11439
  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`. */
11440
+ /** @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
11441
  "Idempotency-Key"?: string;
11416
11442
  };
11417
11443
  path: {
@@ -11522,7 +11548,7 @@ interface operations {
11522
11548
  parameters: {
11523
11549
  query?: never;
11524
11550
  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`. */
11551
+ /** @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
11552
  "Idempotency-Key"?: string;
11527
11553
  };
11528
11554
  path: {
@@ -11905,7 +11931,7 @@ interface operations {
11905
11931
  endpoint_id?: string;
11906
11932
  };
11907
11933
  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`. */
11934
+ /** @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
11935
  "Idempotency-Key"?: string;
11910
11936
  };
11911
11937
  path: {
@@ -12098,6 +12124,7 @@ declare const NotifyChannel: {
12098
12124
  * Why a delivery was skipped, held, retried or failed. Open enum: new reasons may be added.
12099
12125
  *
12100
12126
  * - `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.
12127
+ * - `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
12128
  * - `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
12129
  * - `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
12130
  * - `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`.
@@ -12132,12 +12159,16 @@ declare const NotifyChannel: {
12132
12159
  */
12133
12160
  type NotifyDeliveryReason = components["schemas"]["NotifyDeliveryReason"];
12134
12161
  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"];
12162
+ values: readonly ["suppressed_preference", "default_off", "unsubscribed_all", "held_quiet_hours", "scheduled_send", "no_device", "no_address", "email_invalid", "email_complained", "email_paused", "email_budget", "email_backlog_full", "channel_not_configured", "channel_restricted", "type_archived", "credential_invalid", "template_missing", "rate_limited", "throttled", "read_in_inbox", "awaiting_unread", "actor_excluded", "recipient_not_found", "recipient_erased", "mail_suppressed", "mail_refused", "pruned", "payload_too_large", "credential_error", "circuit_open", "expired", "cancelled", "provider_error"];
12136
12163
  };
12137
12164
  type NotifyEmailPauseReason = components["schemas"]["NotifyEmailPauseReason"];
12138
12165
  declare const NotifyEmailPauseReason: {
12139
12166
  values: readonly ["complaints", "bounces"];
12140
12167
  };
12168
+ type NotifyQuietHoursSource = components["schemas"]["NotifyQuietHoursSource"];
12169
+ declare const NotifyQuietHoursSource: {
12170
+ values: readonly ["recipient", "workspace"];
12171
+ };
12141
12172
  type NotifyRecipientDeletionCause = components["schemas"]["NotifyRecipientDeletionCause"];
12142
12173
  declare const NotifyRecipientDeletionCause: {
12143
12174
  values: readonly ["api", "auth_user_deleted"];
@@ -12263,6 +12294,8 @@ interface DeviceMove extends Open<components["schemas"]["DeviceMoveDto"]> {
12263
12294
  }
12264
12295
  interface DryRun extends Open<components["schemas"]["DryRunResponseDto"]> {
12265
12296
  }
12297
+ interface EffectiveQuietHours extends Open<components["schemas"]["EffectiveQuietHoursDto"]> {
12298
+ }
12266
12299
  interface Export extends Open<components["schemas"]["ExportDto"]> {
12267
12300
  }
12268
12301
  interface ExportNotificationType extends Open<components["schemas"]["ExportNotificationTypeDto"]> {
@@ -13346,7 +13379,7 @@ declare class NotificationsResource extends APIResource {
13346
13379
  *
13347
13380
  * @param params - `Notify.NotificationCancelByKeyParams`.
13348
13381
  * @param options - Per-request options.
13349
- * @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: `cancellation_key` is missing.
13382
+ * @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
13383
  * @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
13384
  * @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
13385
  * @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 +13387,7 @@ declare class NotificationsResource extends APIResource {
13354
13387
  * @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications-cancel
13355
13388
  * @example
13356
13389
  * ```ts
13357
- * const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite:inv_77" });
13390
+ * const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite.sent:inv_77" });
13358
13391
  * ```
13359
13392
  */
13360
13393
  cancelByKey(params: NotificationCancelByKeyParams, options?: RequestOptions): APIPromise<WithLastResponse<CancelByKey>>;
@@ -13427,13 +13460,13 @@ declare class NotificationsResource extends APIResource {
13427
13460
  /**
13428
13461
  * Send a notification
13429
13462
  *
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`.
13463
+ * 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
13464
  *
13432
13465
  * Credential: `bearer`.
13433
13466
  *
13434
13467
  * @param params - `Notify.NotificationSendParams`.
13435
13468
  * @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.
13469
+ * @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
13470
  * @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
13471
  * @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
13472
  * @throws {NotFoundError} 404 NOT_FOUND, NOTIFICATION_TYPE_NOT_FOUND: `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key.
@@ -14497,6 +14530,7 @@ type __NotificationStatus = NotificationStatus;
14497
14530
  type __NotifyChannel = NotifyChannel;
14498
14531
  type __NotifyDeliveryReason = NotifyDeliveryReason;
14499
14532
  type __NotifyEmailPauseReason = NotifyEmailPauseReason;
14533
+ type __NotifyQuietHoursSource = NotifyQuietHoursSource;
14500
14534
  type __NotifyRecipientDeletionCause = NotifyRecipientDeletionCause;
14501
14535
  type __NotifyStatsChannel = NotifyStatsChannel;
14502
14536
  type __NotifyWebhookChannel = NotifyWebhookChannel;
@@ -14539,6 +14573,7 @@ type __Device = Device;
14539
14573
  type __DeviceList = DeviceList;
14540
14574
  type __DeviceMove = DeviceMove;
14541
14575
  type __DryRun = DryRun;
14576
+ type __EffectiveQuietHours = EffectiveQuietHours;
14542
14577
  type __Export = Export;
14543
14578
  type __ExportNotificationType = ExportNotificationType;
14544
14579
  type __ExportSettings = ExportSettings;
@@ -14792,12 +14827,16 @@ declare namespace Notify {
14792
14827
  };
14793
14828
  type NotifyDeliveryReason = __NotifyDeliveryReason;
14794
14829
  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"];
14830
+ values: readonly ["suppressed_preference", "default_off", "unsubscribed_all", "held_quiet_hours", "scheduled_send", "no_device", "no_address", "email_invalid", "email_complained", "email_paused", "email_budget", "email_backlog_full", "channel_not_configured", "channel_restricted", "type_archived", "credential_invalid", "template_missing", "rate_limited", "throttled", "read_in_inbox", "awaiting_unread", "actor_excluded", "recipient_not_found", "recipient_erased", "mail_suppressed", "mail_refused", "pruned", "payload_too_large", "credential_error", "circuit_open", "expired", "cancelled", "provider_error"];
14796
14831
  };
14797
14832
  type NotifyEmailPauseReason = __NotifyEmailPauseReason;
14798
14833
  const NotifyEmailPauseReason: {
14799
14834
  values: readonly ["complaints", "bounces"];
14800
14835
  };
14836
+ type NotifyQuietHoursSource = __NotifyQuietHoursSource;
14837
+ const NotifyQuietHoursSource: {
14838
+ values: readonly ["recipient", "workspace"];
14839
+ };
14801
14840
  type NotifyRecipientDeletionCause = __NotifyRecipientDeletionCause;
14802
14841
  const NotifyRecipientDeletionCause: {
14803
14842
  values: readonly ["api", "auth_user_deleted"];
@@ -14897,6 +14936,7 @@ declare namespace Notify {
14897
14936
  type DeviceList = __DeviceList;
14898
14937
  type DeviceMove = __DeviceMove;
14899
14938
  type DryRun = __DryRun;
14939
+ type EffectiveQuietHours = __EffectiveQuietHours;
14900
14940
  type Export = __Export;
14901
14941
  type ExportNotificationType = __ExportNotificationType;
14902
14942
  type ExportSettings = __ExportSettings;
package/dist/index.js CHANGED
@@ -771,7 +771,7 @@ var NotificationsResource = class extends APIResource {
771
771
  *
772
772
  * @param params - `Notify.NotificationCancelByKeyParams`.
773
773
  * @param options - Per-request options.
774
- * @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: `cancellation_key` is missing.
774
+ * @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 . _ : @ | -`.
775
775
  * @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/…`).
776
776
  * @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).
777
777
  * @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.
@@ -779,7 +779,7 @@ var NotificationsResource = class extends APIResource {
779
779
  * @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications-cancel
780
780
  * @example
781
781
  * ```ts
782
- * const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite:inv_77" });
782
+ * const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite.sent:inv_77" });
783
783
  * ```
784
784
  */
785
785
  cancelByKey(params, options) {
@@ -860,13 +860,13 @@ var NotificationsResource = class extends APIResource {
860
860
  /**
861
861
  * Send a notification
862
862
  *
863
- * 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`.
863
+ * 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`.
864
864
  *
865
865
  * Credential: `bearer`.
866
866
  *
867
867
  * @param params - `Notify.NotificationSendParams`.
868
868
  * @param options - Per-request options (an Idempotency-Key is sent automatically; override with `idempotencyKey`).
869
- * @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.
869
+ * @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).
870
870
  * @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/…`).
871
871
  * @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).
872
872
  * @throws {NotFoundError} 404 NOT_FOUND, NOTIFICATION_TYPE_NOT_FOUND: `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key.
@@ -2052,8 +2052,9 @@ var InboxItemStatusFilter = { values: ["active", "archived", "all"] };
2052
2052
  var InboxMarkAction = { values: ["seen", "read", "unread", "archived", "unarchived"] };
2053
2053
  var NotificationStatus = { values: ["scheduled", "accepted", "planned", "cancelled"] };
2054
2054
  var NotifyChannel = { values: ["inbox", "email", "push", "webpush"] };
2055
- var NotifyDeliveryReason = { values: ["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"] };
2055
+ var NotifyDeliveryReason = { values: ["suppressed_preference", "default_off", "unsubscribed_all", "held_quiet_hours", "scheduled_send", "no_device", "no_address", "email_invalid", "email_complained", "email_paused", "email_budget", "email_backlog_full", "channel_not_configured", "channel_restricted", "type_archived", "credential_invalid", "template_missing", "rate_limited", "throttled", "read_in_inbox", "awaiting_unread", "actor_excluded", "recipient_not_found", "recipient_erased", "mail_suppressed", "mail_refused", "pruned", "payload_too_large", "credential_error", "circuit_open", "expired", "cancelled", "provider_error"] };
2056
2056
  var NotifyEmailPauseReason = { values: ["complaints", "bounces"] };
2057
+ var NotifyQuietHoursSource = { values: ["recipient", "workspace"] };
2057
2058
  var NotifyRecipientDeletionCause = { values: ["api", "auth_user_deleted"] };
2058
2059
  var NotifyStatsChannel = { values: ["inbox", "email", "push", "webpush"] };
2059
2060
  var NotifyWebhookChannel = { values: ["inbox", "email", "push", "webpush"] };
@@ -2075,7 +2076,7 @@ var WebhookEventStatus = { values: ["pending", "delivered", "failed", "not_sent"
2075
2076
  var WebhookEventType = { values: ["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"] };
2076
2077
 
2077
2078
  // src/_generated/client.ts
2078
- var VERSION = "0.1.1" ;
2079
+ var VERSION = "0.2.0" ;
2079
2080
  var Notify = class extends NotifyResources {
2080
2081
  /** The options this client was built with, for the token scopes' own clients. Never enumerable. */
2081
2082
  #options;
@@ -2130,6 +2131,7 @@ var Notify = class extends NotifyResources {
2130
2131
  Notify2.NotifyChannel = NotifyChannel;
2131
2132
  Notify2.NotifyDeliveryReason = NotifyDeliveryReason;
2132
2133
  Notify2.NotifyEmailPauseReason = NotifyEmailPauseReason;
2134
+ Notify2.NotifyQuietHoursSource = NotifyQuietHoursSource;
2133
2135
  Notify2.NotifyRecipientDeletionCause = NotifyRecipientDeletionCause;
2134
2136
  Notify2.NotifyStatsChannel = NotifyStatsChannel;
2135
2137
  Notify2.NotifyWebhookChannel = NotifyWebhookChannel;