@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/README.md +6 -5
- package/api.md +132 -7
- package/dist/index.cjs +145 -10
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1105 -68
- package/dist/index.d.ts +1105 -68
- package/dist/index.js +145 -10
- package/dist/index.js.map +1 -1
- package/dist/testing.cjs +164 -0
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +164 -0
- package/dist/testing.js.map +1 -1
- package/manifest.json +63 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -68,6 +68,7 @@ Pass `apiKey` (a workspace key, `pcft_live_…`), or omit it and the client read
|
|
|
68
68
|
|
|
69
69
|
Full reference: [api.md](./api.md).
|
|
70
70
|
|
|
71
|
+
- `notify.batches`: `flush`, `list`, `retrieve`
|
|
71
72
|
- `notify.categories`: `create`, `delete`, `list`, `retrieve`, `update`
|
|
72
73
|
- `notify.channels`: `apns.deleteCredential`, `apns.uploadCredential`, `fcm.deleteCredential`, `fcm.uploadCredential`, `list`, `webpush.generateVapidKeys`, `webpush.importVapidKeys`, `webpush.retrieve`
|
|
73
74
|
- `notify.client(…).devices`: `delete`, `register`
|
|
@@ -79,7 +80,7 @@ Full reference: [api.md](./api.md).
|
|
|
79
80
|
- `notify.notificationTypes`: `archive`, `create`, `list`, `preview`, `replaceByKey`, `retrieve`, `templates.delete`, `templates.retrieve`, `templates.revert`, `templates.update`, `templates.versions`, `update`
|
|
80
81
|
- `notify.notifications`: `cancel`, `cancelByKey`, `list`, `retract`, `retrieve`, `send`
|
|
81
82
|
- `notify.recipientTokens`: `mint`
|
|
82
|
-
- `notify.recipients`: `bulkIdentify`, `delete`, `devices.create`, `devices.delete`, `devices.list`, `identify`, `inbox.list`, `list`, `preferences.replace`, `preferences.retrieve`, `preferences.update`, `retrieve`, `revokeTokens`, `timeline`, `update`
|
|
83
|
+
- `notify.recipients`: `bulkIdentify`, `createPreferenceLink`, `delete`, `devices.create`, `devices.delete`, `devices.list`, `identify`, `inbox.list`, `list`, `preferences.replace`, `preferences.retrieve`, `preferences.update`, `retrieve`, `revokeTokens`, `timeline`, `update`
|
|
83
84
|
- `notify.settings`: `retrieve`, `revokeAllTokens`, `update`
|
|
84
85
|
- `notify.setupStatus`: `retrieve`
|
|
85
86
|
- `notify.stats`: `retrieve`
|
|
@@ -106,7 +107,7 @@ Every failure is a class you can catch. `APIError` carries `status`, `code`, `me
|
|
|
106
107
|
import { Notify, NotFoundError, RateLimitError, APIError } from "@productcraft/notify";
|
|
107
108
|
const notify = new Notify();
|
|
108
109
|
try {
|
|
109
|
-
await notify.
|
|
110
|
+
await notify.batches.retrieve("00000000-0000-0000-0000-000000000000");
|
|
110
111
|
} catch (err) {
|
|
111
112
|
if (err instanceof NotFoundError) console.log(err.code, err.requestId, err.docUrl);
|
|
112
113
|
else if (err instanceof RateLimitError) console.log(err.retryAfter);
|
|
@@ -206,9 +207,9 @@ Every returned object has a non-enumerable `lastResponse` (`requestId`, `status`
|
|
|
206
207
|
import { Notify } from "@productcraft/notify";
|
|
207
208
|
const notify = new Notify({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
|
|
208
209
|
const id = "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b";
|
|
209
|
-
const obj = await notify.
|
|
210
|
+
const obj = await notify.batches.retrieve(id);
|
|
210
211
|
console.log(obj.lastResponse.requestId);
|
|
211
|
-
const { data, response, requestId, rateLimit } = await notify.
|
|
212
|
+
const { data, response, requestId, rateLimit } = await notify.batches.retrieve(id).withResponse();
|
|
212
213
|
console.log(data, response.status, requestId, rateLimit?.remaining);
|
|
213
214
|
```
|
|
214
215
|
|
|
@@ -232,7 +233,7 @@ console.log(fetch.calls.length);
|
|
|
232
233
|
```ts
|
|
233
234
|
import { Notify } from "@productcraft/notify";
|
|
234
235
|
const notify = new Notify({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
|
|
235
|
-
const { data, error } = await notify.client.GET("/v1/workspaces/{workspace_id}/
|
|
236
|
+
const { data, error } = await notify.client.GET("/v1/workspaces/{workspace_id}/batches", { params: { path: { workspace_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b" } } });
|
|
236
237
|
console.log(data, error);
|
|
237
238
|
```
|
|
238
239
|
|
package/api.md
CHANGED
|
@@ -5,6 +5,84 @@
|
|
|
5
5
|
|
|
6
6
|
Every method of `Notify`, grouped by resource. Types are under the `Notify` namespace (`import type { Notify } from "@productcraft/notify"`). Every method takes per-request options last (`{ idempotencyKey, timeout, maxRetries, headers, signal, workspaceId }`).
|
|
7
7
|
|
|
8
|
+
## batches
|
|
9
|
+
|
|
10
|
+
### `notify.batches.flush(batchId, options?)`
|
|
11
|
+
|
|
12
|
+
`POST /v1/workspaces/{workspace_id}/batches/{batch_id}/flush` → `Notify.FlushBatch`
|
|
13
|
+
|
|
14
|
+
Close a batch now.
|
|
15
|
+
|
|
16
|
+
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.
|
|
17
|
+
|
|
18
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
19
|
+
- Credential: [`bearer`](#bearer)
|
|
20
|
+
|
|
21
|
+
| Status | Error class | Codes | When |
|
|
22
|
+
|---|---|---|---|
|
|
23
|
+
| 401 | `AuthenticationError` | `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/…`). |
|
|
24
|
+
| 403 | `PermissionDeniedError` | `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). |
|
|
25
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `BATCH_NOT_FOUND` | `BATCH_NOT_FOUND`: no batch with this id in this workspace. |
|
|
26
|
+
| 409 | `ConflictError` | `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). |
|
|
27
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
const flushBatch = await notify.batches.flush("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-batches-batch-id-flush)
|
|
34
|
+
|
|
35
|
+
### `notify.batches.list(params?, options?)`
|
|
36
|
+
|
|
37
|
+
`GET /v1/workspaces/{workspace_id}/batches` → `PagePromise<Notify.BatchSummary>`
|
|
38
|
+
|
|
39
|
+
List batches.
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
- Params: `Notify.BatchListParams`
|
|
44
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
45
|
+
- Credential: [`bearer`](#bearer)
|
|
46
|
+
|
|
47
|
+
| Status | Error class | Codes | When |
|
|
48
|
+
|---|---|---|---|
|
|
49
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor. |
|
|
50
|
+
| 401 | `AuthenticationError` | `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/…`). |
|
|
51
|
+
| 403 | `PermissionDeniedError` | `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). |
|
|
52
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
for await (const batch of notify.batches.list()) {
|
|
56
|
+
console.log(batch);
|
|
57
|
+
}
|
|
58
|
+
const page = await notify.batches.list({}, { timeout: 5_000 });
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-batches)
|
|
62
|
+
|
|
63
|
+
### `notify.batches.retrieve(batchId, options?)`
|
|
64
|
+
|
|
65
|
+
`GET /v1/workspaces/{workspace_id}/batches/{batch_id}` → `Notify.BatchDetail`
|
|
66
|
+
|
|
67
|
+
Get a batch.
|
|
68
|
+
|
|
69
|
+
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.
|
|
70
|
+
|
|
71
|
+
- Credential: [`bearer`](#bearer)
|
|
72
|
+
|
|
73
|
+
| Status | Error class | Codes | When |
|
|
74
|
+
|---|---|---|---|
|
|
75
|
+
| 401 | `AuthenticationError` | `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/…`). |
|
|
76
|
+
| 403 | `PermissionDeniedError` | `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). |
|
|
77
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `BATCH_NOT_FOUND` | `BATCH_NOT_FOUND`: no batch with this id in this workspace. |
|
|
78
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
const batchDetail = await notify.batches.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-batches-batch-id)
|
|
85
|
+
|
|
8
86
|
## categories
|
|
9
87
|
|
|
10
88
|
### `notify.categories.create(params, options?)`
|
|
@@ -596,7 +674,18 @@ Changes the fields you send; `routing` is replaced whole. The key cannot change.
|
|
|
596
674
|
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
597
675
|
|
|
598
676
|
```ts
|
|
599
|
-
const notificationType = await notify.notificationTypes.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
677
|
+
const notificationType = await notify.notificationTypes.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
678
|
+
batch: {
|
|
679
|
+
inbox: "collapse",
|
|
680
|
+
key: "post_id",
|
|
681
|
+
max_items: 10,
|
|
682
|
+
max_window_seconds: 3600,
|
|
683
|
+
mode: "window",
|
|
684
|
+
schedule: { frequency: "daily", time: "09:00", weekday: "monday" },
|
|
685
|
+
sliding: false,
|
|
686
|
+
window_seconds: 300,
|
|
687
|
+
},
|
|
688
|
+
});
|
|
600
689
|
```
|
|
601
690
|
|
|
602
691
|
[HTTP reference](https://productcraft.co/docs/notify/api-reference#patch-v1-workspaces-workspace-id-notification-types-type-id)
|
|
@@ -762,13 +851,13 @@ Cancels every live notification sent with this `cancellation_key`: deliveries st
|
|
|
762
851
|
|
|
763
852
|
| Status | Error class | Codes | When |
|
|
764
853
|
|---|---|---|---|
|
|
765
|
-
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `cancellation_key` is missing. |
|
|
854
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `cancellation_key` is missing or not 1-255 characters of `A-Z a-z 0-9 . _ : @ \| -`. |
|
|
766
855
|
| 401 | `AuthenticationError` | `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/…`). |
|
|
767
856
|
| 403 | `PermissionDeniedError` | `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). |
|
|
768
857
|
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
769
858
|
|
|
770
859
|
```ts
|
|
771
|
-
const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite:inv_77" });
|
|
860
|
+
const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite.sent:inv_77" });
|
|
772
861
|
```
|
|
773
862
|
|
|
774
863
|
[HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications-cancel)
|
|
@@ -853,7 +942,7 @@ const notification = await notify.notifications.retrieve("0193a5f2-7c1e-7b3a-9f1
|
|
|
853
942
|
|
|
854
943
|
Send a notification.
|
|
855
944
|
|
|
856
|
-
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
|
|
945
|
+
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`.
|
|
857
946
|
|
|
858
947
|
- Params: `Notify.NotificationSendParams`
|
|
859
948
|
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
@@ -861,13 +950,13 @@ Notifies up to 1,000 recipients with one notification type, across the type's ch
|
|
|
861
950
|
|
|
862
951
|
| Status | Error class | Codes | When |
|
|
863
952
|
|---|---|---|---|
|
|
864
|
-
| 400 | `BadRequestError` | `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. |
|
|
953
|
+
| 400 | `BadRequestError` | `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). |
|
|
865
954
|
| 401 | `AuthenticationError` | `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/…`). |
|
|
866
955
|
| 403 | `PermissionDeniedError` | `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). |
|
|
867
956
|
| 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key. |
|
|
868
957
|
| 409 | `ConflictError` | `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). |
|
|
869
958
|
| 413 | `APIError` | `PAYLOAD_TOO_LARGE`, `DATA_TOO_LARGE` | `DATA_TOO_LARGE`: `data` is over 16 KB. |
|
|
870
|
-
| 422 | `UnprocessableEntityError` | `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. |
|
|
959
|
+
| 422 | `UnprocessableEntityError` | `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. |
|
|
871
960
|
| 429 | `RateLimitError` | `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. |
|
|
872
961
|
|
|
873
962
|
```ts
|
|
@@ -934,6 +1023,32 @@ const bulkUpsertRecipients = await notify.recipients.bulkIdentify({ recipients:
|
|
|
934
1023
|
|
|
935
1024
|
[HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-recipients-bulk)
|
|
936
1025
|
|
|
1026
|
+
### `notify.recipients.createPreferenceLink(externalId, params?, options?)`
|
|
1027
|
+
|
|
1028
|
+
`POST /v1/workspaces/{workspace_id}/recipients/{external_id}/preference-link` → `Notify.PreferenceLink`
|
|
1029
|
+
|
|
1030
|
+
Create a hosted preference page link.
|
|
1031
|
+
|
|
1032
|
+
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`.
|
|
1033
|
+
|
|
1034
|
+
- Params: `Notify.RecipientCreatePreferenceLinkParams`
|
|
1035
|
+
- Credential: [`bearer`](#bearer)
|
|
1036
|
+
|
|
1037
|
+
| Status | Error class | Codes | When |
|
|
1038
|
+
|---|---|---|---|
|
|
1039
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `category_key` is malformed. |
|
|
1040
|
+
| 401 | `AuthenticationError` | `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/…`). |
|
|
1041
|
+
| 403 | `PermissionDeniedError` | `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). |
|
|
1042
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
|
|
1043
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CATEGORY_NOT_FOUND` | `CATEGORY_NOT_FOUND`: no category with this key. |
|
|
1044
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1045
|
+
|
|
1046
|
+
```ts
|
|
1047
|
+
const preferenceLink = await notify.recipients.createPreferenceLink("user_123", { category_key: "product-updates" });
|
|
1048
|
+
```
|
|
1049
|
+
|
|
1050
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-recipients-external-id-preference-link)
|
|
1051
|
+
|
|
937
1052
|
### `notify.recipients.delete(externalId, options?)`
|
|
938
1053
|
|
|
939
1054
|
`DELETE /v1/workspaces/{workspace_id}/recipients/{external_id}` → `Notify.RecipientErasure`
|
|
@@ -1360,7 +1475,14 @@ Turn email on or off, set the default time zone and quiet hours (`null` clears e
|
|
|
1360
1475
|
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1361
1476
|
|
|
1362
1477
|
```ts
|
|
1363
|
-
const notifySettings = await notify.settings.update({
|
|
1478
|
+
const notifySettings = await notify.settings.update({
|
|
1479
|
+
branding: {
|
|
1480
|
+
accent_color: "#4f46e5",
|
|
1481
|
+
logo_url: "https://acme.example/logo.png",
|
|
1482
|
+
name: "Acme",
|
|
1483
|
+
privacy_url: "https://acme.example/privacy",
|
|
1484
|
+
},
|
|
1485
|
+
});
|
|
1364
1486
|
```
|
|
1365
1487
|
|
|
1366
1488
|
[HTTP reference](https://productcraft.co/docs/notify/api-reference#patch-v1-workspaces-workspace-id-settings)
|
|
@@ -2012,6 +2134,9 @@ A recipient token minted by your backend with `POST /v1/workspaces/{workspace_id
|
|
|
2012
2134
|
| `ORIGIN_NOT_ALLOWED` | The request origin is not in the workspace client origins. |
|
|
2013
2135
|
| `STREAM_LIMIT` | The recipient has the maximum number of open real-time streams. |
|
|
2014
2136
|
| `LIMIT_EXCEEDED` | A preview limit of the workspace was reached. |
|
|
2137
|
+
| `BATCHED_TYPE_NOT_SCHEDULABLE` | The notification type batches its notifications (`batch`): send it now, the batch window or digest decides when it goes out. |
|
|
2138
|
+
| `BATCH_NOT_FOUND` | No batch with this id in this workspace. |
|
|
2139
|
+
| `BATCH_NOT_OPEN` | The batch is already closed (flushed or cancelled), or closing right now. |
|
|
2015
2140
|
| `SEND_AT_OUT_OF_RANGE` | `send_at` or `delay_seconds` is in the past or beyond the type TTL. |
|
|
2016
2141
|
| `UNSAFE_URL` | A URL field does not use https (http is accepted only for localhost). |
|
|
2017
2142
|
| `AUTH_USER_ALREADY_LINKED` | The Auth end user is already linked to another recipient in this workspace. |
|
package/dist/index.cjs
CHANGED
|
@@ -16,6 +16,81 @@ var APIResource = class {
|
|
|
16
16
|
this._b = bound;
|
|
17
17
|
}
|
|
18
18
|
};
|
|
19
|
+
var BatchesResource = class extends APIResource {
|
|
20
|
+
/**
|
|
21
|
+
* Close a batch now
|
|
22
|
+
*
|
|
23
|
+
* 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.
|
|
24
|
+
*
|
|
25
|
+
* Credential: `bearer`.
|
|
26
|
+
*
|
|
27
|
+
* @param batchId - The batch id (from a delivery's `batch_id`, or the list).
|
|
28
|
+
* @param options - Per-request options (an Idempotency-Key is sent automatically; override with `idempotencyKey`).
|
|
29
|
+
* @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/…`).
|
|
30
|
+
* @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).
|
|
31
|
+
* @throws {NotFoundError} 404 NOT_FOUND, BATCH_NOT_FOUND: `BATCH_NOT_FOUND`: no batch with this id in this workspace.
|
|
32
|
+
* @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).
|
|
33
|
+
* @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.
|
|
34
|
+
* @see POST /v1/workspaces/{workspace_id}/batches/{batch_id}/flush
|
|
35
|
+
* @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-batches-batch-id-flush
|
|
36
|
+
* @example
|
|
37
|
+
* ```ts
|
|
38
|
+
* const flushBatch = await notify.batches.flush("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
39
|
+
* ```
|
|
40
|
+
*/
|
|
41
|
+
flush(batchId, options) {
|
|
42
|
+
return this._client.request({ method: "POST", path: "/v1/workspaces/{workspace_id}/batches/{batch_id}/flush", pathParams: { batch_id: batchId }, idempotent: true }, options);
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* List batches
|
|
46
|
+
*
|
|
47
|
+
* 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.
|
|
48
|
+
*
|
|
49
|
+
* Credential: `bearer`.
|
|
50
|
+
*
|
|
51
|
+
* @param params - `Notify.BatchListParams`.
|
|
52
|
+
* @param options - Per-request options.
|
|
53
|
+
* @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor.
|
|
54
|
+
* @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/…`).
|
|
55
|
+
* @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).
|
|
56
|
+
* @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.
|
|
57
|
+
* @see GET /v1/workspaces/{workspace_id}/batches
|
|
58
|
+
* @see https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-batches
|
|
59
|
+
* @example
|
|
60
|
+
* ```ts
|
|
61
|
+
* for await (const batch of notify.batches.list()) {
|
|
62
|
+
* console.log(batch);
|
|
63
|
+
* }
|
|
64
|
+
* const page = await notify.batches.list({}, { timeout: 5_000 });
|
|
65
|
+
* ```
|
|
66
|
+
*/
|
|
67
|
+
list(params, options) {
|
|
68
|
+
return this._client.list({ method: "GET", path: "/v1/workspaces/{workspace_id}/batches", query: params }, options);
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Get a batch
|
|
72
|
+
*
|
|
73
|
+
* 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.
|
|
74
|
+
*
|
|
75
|
+
* Credential: `bearer`.
|
|
76
|
+
*
|
|
77
|
+
* @param batchId - The batch id (from a delivery's `batch_id`, or the list).
|
|
78
|
+
* @param options - Per-request options.
|
|
79
|
+
* @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/…`).
|
|
80
|
+
* @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).
|
|
81
|
+
* @throws {NotFoundError} 404 NOT_FOUND, BATCH_NOT_FOUND: `BATCH_NOT_FOUND`: no batch with this id in this workspace.
|
|
82
|
+
* @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.
|
|
83
|
+
* @see GET /v1/workspaces/{workspace_id}/batches/{batch_id}
|
|
84
|
+
* @see https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-batches-batch-id
|
|
85
|
+
* @example
|
|
86
|
+
* ```ts
|
|
87
|
+
* const batchDetail = await notify.batches.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
88
|
+
* ```
|
|
89
|
+
*/
|
|
90
|
+
retrieve(batchId, options) {
|
|
91
|
+
return this._client.request({ method: "GET", path: "/v1/workspaces/{workspace_id}/batches/{batch_id}", pathParams: { batch_id: batchId } }, options);
|
|
92
|
+
}
|
|
93
|
+
};
|
|
19
94
|
var CategoriesResource = class extends APIResource {
|
|
20
95
|
/**
|
|
21
96
|
* Create a category
|
|
@@ -734,7 +809,18 @@ var NotificationTypesResource = class extends APIResource {
|
|
|
734
809
|
* @see https://productcraft.co/docs/notify/api-reference#patch-v1-workspaces-workspace-id-notification-types-type-id
|
|
735
810
|
* @example
|
|
736
811
|
* ```ts
|
|
737
|
-
* const notificationType = await notify.notificationTypes.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
812
|
+
* const notificationType = await notify.notificationTypes.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
813
|
+
* batch: {
|
|
814
|
+
* inbox: "collapse",
|
|
815
|
+
* key: "post_id",
|
|
816
|
+
* max_items: 10,
|
|
817
|
+
* max_window_seconds: 3600,
|
|
818
|
+
* mode: "window",
|
|
819
|
+
* schedule: { frequency: "daily", time: "09:00", weekday: "monday" },
|
|
820
|
+
* sliding: false,
|
|
821
|
+
* window_seconds: 300,
|
|
822
|
+
* },
|
|
823
|
+
* });
|
|
738
824
|
* ```
|
|
739
825
|
*/
|
|
740
826
|
update(typeId, params, options) {
|
|
@@ -774,7 +860,7 @@ var NotificationsResource = class extends APIResource {
|
|
|
774
860
|
*
|
|
775
861
|
* @param params - `Notify.NotificationCancelByKeyParams`.
|
|
776
862
|
* @param options - Per-request options.
|
|
777
|
-
* @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: `cancellation_key` is missing.
|
|
863
|
+
* @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 . _ : @ | -`.
|
|
778
864
|
* @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/…`).
|
|
779
865
|
* @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).
|
|
780
866
|
* @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.
|
|
@@ -782,7 +868,7 @@ var NotificationsResource = class extends APIResource {
|
|
|
782
868
|
* @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications-cancel
|
|
783
869
|
* @example
|
|
784
870
|
* ```ts
|
|
785
|
-
* const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite:inv_77" });
|
|
871
|
+
* const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite.sent:inv_77" });
|
|
786
872
|
* ```
|
|
787
873
|
*/
|
|
788
874
|
cancelByKey(params, options) {
|
|
@@ -863,19 +949,19 @@ var NotificationsResource = class extends APIResource {
|
|
|
863
949
|
/**
|
|
864
950
|
* Send a notification
|
|
865
951
|
*
|
|
866
|
-
* 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
|
|
952
|
+
* 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`.
|
|
867
953
|
*
|
|
868
954
|
* Credential: `bearer`.
|
|
869
955
|
*
|
|
870
956
|
* @param params - `Notify.NotificationSendParams`.
|
|
871
957
|
* @param options - Per-request options (an Idempotency-Key is sent automatically; override with `idempotencyKey`).
|
|
872
|
-
* @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.
|
|
958
|
+
* @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).
|
|
873
959
|
* @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/…`).
|
|
874
960
|
* @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).
|
|
875
961
|
* @throws {NotFoundError} 404 NOT_FOUND, NOTIFICATION_TYPE_NOT_FOUND: `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key.
|
|
876
962
|
* @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).
|
|
877
963
|
* @throws {APIError} 413 PAYLOAD_TOO_LARGE, DATA_TOO_LARGE: `DATA_TOO_LARGE`: `data` is over 16 KB.
|
|
878
|
-
* @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.
|
|
964
|
+
* @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.
|
|
879
965
|
* @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.
|
|
880
966
|
* @see POST /v1/workspaces/{workspace_id}/notifications
|
|
881
967
|
* @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications
|
|
@@ -1137,6 +1223,32 @@ var RecipientsResource = class extends APIResource {
|
|
|
1137
1223
|
bulkIdentify(params, options) {
|
|
1138
1224
|
return this._client.request({ method: "POST", path: "/v1/workspaces/{workspace_id}/recipients/bulk", body: params, idempotent: true }, options);
|
|
1139
1225
|
}
|
|
1226
|
+
/**
|
|
1227
|
+
* Create a hosted preference page link
|
|
1228
|
+
*
|
|
1229
|
+
* 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`.
|
|
1230
|
+
*
|
|
1231
|
+
* Credential: `bearer`.
|
|
1232
|
+
*
|
|
1233
|
+
* @param externalId - Your user id for the recipient (URL-encoded): 1-255 of `A-Z a-z 0-9 . _ : @ | -`.
|
|
1234
|
+
* @param params - `Notify.RecipientCreatePreferenceLinkParams`.
|
|
1235
|
+
* @param options - Per-request options.
|
|
1236
|
+
* @throws {BadRequestError} 400 BAD_REQUEST, VALIDATION_ERROR: `VALIDATION_ERROR`: `category_key` is malformed.
|
|
1237
|
+
* @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/…`).
|
|
1238
|
+
* @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).
|
|
1239
|
+
* @throws {NotFoundError} 404 NOT_FOUND, RECIPIENT_NOT_FOUND: `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace.
|
|
1240
|
+
* @throws {UnprocessableEntityError} 422 UNPROCESSABLE_ENTITY, CATEGORY_NOT_FOUND: `CATEGORY_NOT_FOUND`: no category with this key.
|
|
1241
|
+
* @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.
|
|
1242
|
+
* @see POST /v1/workspaces/{workspace_id}/recipients/{external_id}/preference-link
|
|
1243
|
+
* @see https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-recipients-external-id-preference-link
|
|
1244
|
+
* @example
|
|
1245
|
+
* ```ts
|
|
1246
|
+
* const preferenceLink = await notify.recipients.createPreferenceLink("user_123", { category_key: "product-updates" });
|
|
1247
|
+
* ```
|
|
1248
|
+
*/
|
|
1249
|
+
createPreferenceLink(externalId, params, options) {
|
|
1250
|
+
return this._client.request({ method: "POST", path: "/v1/workspaces/{workspace_id}/recipients/{external_id}/preference-link", pathParams: { external_id: externalId }, body: params }, options);
|
|
1251
|
+
}
|
|
1140
1252
|
/**
|
|
1141
1253
|
* Erase a recipient (GDPR)
|
|
1142
1254
|
*
|
|
@@ -1372,7 +1484,14 @@ var SettingsResource = class extends APIResource {
|
|
|
1372
1484
|
* @see https://productcraft.co/docs/notify/api-reference#patch-v1-workspaces-workspace-id-settings
|
|
1373
1485
|
* @example
|
|
1374
1486
|
* ```ts
|
|
1375
|
-
* const notifySettings = await notify.settings.update({
|
|
1487
|
+
* const notifySettings = await notify.settings.update({
|
|
1488
|
+
* branding: {
|
|
1489
|
+
* accent_color: "#4f46e5",
|
|
1490
|
+
* logo_url: "https://acme.example/logo.png",
|
|
1491
|
+
* name: "Acme",
|
|
1492
|
+
* privacy_url: "https://acme.example/privacy",
|
|
1493
|
+
* },
|
|
1494
|
+
* });
|
|
1376
1495
|
* ```
|
|
1377
1496
|
*/
|
|
1378
1497
|
update(params, options) {
|
|
@@ -1741,6 +1860,7 @@ var WebhooksResource = class extends APIResource {
|
|
|
1741
1860
|
}
|
|
1742
1861
|
};
|
|
1743
1862
|
var NotifyResources = class extends APIResource {
|
|
1863
|
+
#batches;
|
|
1744
1864
|
#categories;
|
|
1745
1865
|
#channels;
|
|
1746
1866
|
#deliveries;
|
|
@@ -1753,6 +1873,9 @@ var NotifyResources = class extends APIResource {
|
|
|
1753
1873
|
#setupStatus;
|
|
1754
1874
|
#stats;
|
|
1755
1875
|
#webhooks;
|
|
1876
|
+
get batches() {
|
|
1877
|
+
return this.#batches ??= new BatchesResource(this._client, this._b);
|
|
1878
|
+
}
|
|
1756
1879
|
get categories() {
|
|
1757
1880
|
return this.#categories ??= new CategoriesResource(this._client, this._b);
|
|
1758
1881
|
}
|
|
@@ -2054,15 +2177,21 @@ var DeviceState = { values: ["active", "invalid", "pruned"] };
|
|
|
2054
2177
|
var InboxItemStatusFilter = { values: ["active", "archived", "all"] };
|
|
2055
2178
|
var InboxMarkAction = { values: ["seen", "read", "unread", "archived", "unarchived"] };
|
|
2056
2179
|
var NotificationStatus = { values: ["scheduled", "accepted", "planned", "cancelled"] };
|
|
2180
|
+
var NotifyBatchInboxMode = { values: ["collapse", "each"] };
|
|
2181
|
+
var NotifyBatchMode = { values: ["window", "digest"] };
|
|
2182
|
+
var NotifyBatchState = { values: ["open", "flushed", "cancelled"] };
|
|
2057
2183
|
var NotifyChannel = { values: ["inbox", "email", "push", "webpush"] };
|
|
2058
|
-
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"] };
|
|
2184
|
+
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", "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"] };
|
|
2185
|
+
var NotifyDigestFrequency = { values: ["daily", "weekly"] };
|
|
2059
2186
|
var NotifyEmailPauseReason = { values: ["complaints", "bounces"] };
|
|
2187
|
+
var NotifyQuietHoursSource = { values: ["recipient", "workspace"] };
|
|
2060
2188
|
var NotifyRecipientDeletionCause = { values: ["api", "auth_user_deleted"] };
|
|
2061
2189
|
var NotifyStatsChannel = { values: ["inbox", "email", "push", "webpush"] };
|
|
2062
2190
|
var NotifyWebhookChannel = { values: ["inbox", "email", "push", "webpush"] };
|
|
2063
2191
|
var NotifyWebhookCredentialProvider = { values: ["apns", "fcm", "vapid"] };
|
|
2064
2192
|
var NotifyWebhookDeliveryState = { values: ["sent", "delivered", "failed", "bounced", "skipped", "pruned"] };
|
|
2065
2193
|
var NotifyWebhookDeviceChannel = { values: ["apns", "fcm", "webpush"] };
|
|
2194
|
+
var NotifyWeekday = { values: ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"] };
|
|
2066
2195
|
var PlanDecision = { values: ["deliver", "schedule", "skip"] };
|
|
2067
2196
|
var PreferenceChannel = { values: ["inbox", "email", "push", "webpush", "*"] };
|
|
2068
2197
|
var PreferenceScope = { values: ["all", "category", "type"] };
|
|
@@ -2078,7 +2207,7 @@ var WebhookEventStatus = { values: ["pending", "delivered", "failed", "not_sent"
|
|
|
2078
2207
|
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"] };
|
|
2079
2208
|
|
|
2080
2209
|
// src/_generated/client.ts
|
|
2081
|
-
var VERSION = "0.
|
|
2210
|
+
var VERSION = "0.3.0" ;
|
|
2082
2211
|
exports.default = class Notify extends NotifyResources {
|
|
2083
2212
|
/** The options this client was built with, for the token scopes' own clients. Never enumerable. */
|
|
2084
2213
|
#options;
|
|
@@ -2130,15 +2259,21 @@ exports.default = class Notify extends NotifyResources {
|
|
|
2130
2259
|
Notify2.InboxItemStatusFilter = InboxItemStatusFilter;
|
|
2131
2260
|
Notify2.InboxMarkAction = InboxMarkAction;
|
|
2132
2261
|
Notify2.NotificationStatus = NotificationStatus;
|
|
2262
|
+
Notify2.NotifyBatchInboxMode = NotifyBatchInboxMode;
|
|
2263
|
+
Notify2.NotifyBatchMode = NotifyBatchMode;
|
|
2264
|
+
Notify2.NotifyBatchState = NotifyBatchState;
|
|
2133
2265
|
Notify2.NotifyChannel = NotifyChannel;
|
|
2134
2266
|
Notify2.NotifyDeliveryReason = NotifyDeliveryReason;
|
|
2267
|
+
Notify2.NotifyDigestFrequency = NotifyDigestFrequency;
|
|
2135
2268
|
Notify2.NotifyEmailPauseReason = NotifyEmailPauseReason;
|
|
2269
|
+
Notify2.NotifyQuietHoursSource = NotifyQuietHoursSource;
|
|
2136
2270
|
Notify2.NotifyRecipientDeletionCause = NotifyRecipientDeletionCause;
|
|
2137
2271
|
Notify2.NotifyStatsChannel = NotifyStatsChannel;
|
|
2138
2272
|
Notify2.NotifyWebhookChannel = NotifyWebhookChannel;
|
|
2139
2273
|
Notify2.NotifyWebhookCredentialProvider = NotifyWebhookCredentialProvider;
|
|
2140
2274
|
Notify2.NotifyWebhookDeliveryState = NotifyWebhookDeliveryState;
|
|
2141
2275
|
Notify2.NotifyWebhookDeviceChannel = NotifyWebhookDeviceChannel;
|
|
2276
|
+
Notify2.NotifyWeekday = NotifyWeekday;
|
|
2142
2277
|
Notify2.PlanDecision = PlanDecision;
|
|
2143
2278
|
Notify2.PreferenceChannel = PreferenceChannel;
|
|
2144
2279
|
Notify2.PreferenceScope = PreferenceScope;
|
|
@@ -2153,7 +2288,7 @@ exports.default = class Notify extends NotifyResources {
|
|
|
2153
2288
|
Notify2.WebhookEventStatus = WebhookEventStatus;
|
|
2154
2289
|
Notify2.WebhookEventType = WebhookEventType;
|
|
2155
2290
|
})(exports.default || (exports.default = {}));
|
|
2156
|
-
var NotifyErrorCode = { values: ["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"] };
|
|
2291
|
+
var NotifyErrorCode = { values: ["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"] };
|
|
2157
2292
|
|
|
2158
2293
|
Object.defineProperty(exports, "APIConnectionError", {
|
|
2159
2294
|
enumerable: true,
|