@productcraft/notify 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -6
- package/api.md +199 -12
- package/dist/index.cjs +221 -16
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1842 -160
- package/dist/index.d.ts +1842 -160
- package/dist/index.js +221 -16
- package/dist/index.js.map +1 -1
- package/dist/testing.cjs +132 -0
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +2 -2
- package/dist/testing.d.ts +2 -2
- package/dist/testing.js +132 -0
- package/dist/testing.js.map +1 -1
- package/manifest.json +106 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -68,9 +68,11 @@ 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.approvals`: `cancel`, `create`, `list`, `recordDecision`, `retrieve`
|
|
71
72
|
- `notify.batches`: `flush`, `list`, `retrieve`
|
|
72
73
|
- `notify.categories`: `create`, `delete`, `list`, `retrieve`, `update`
|
|
73
74
|
- `notify.channels`: `apns.deleteCredential`, `apns.uploadCredential`, `fcm.deleteCredential`, `fcm.uploadCredential`, `list`, `webpush.generateVapidKeys`, `webpush.importVapidKeys`, `webpush.retrieve`
|
|
75
|
+
- `notify.client(…).approvals`: `decide`, `retrieve`
|
|
74
76
|
- `notify.client(…).devices`: `delete`, `register`
|
|
75
77
|
- `notify.client(…).inbox`: `counts`, `interact`, `list`, `mark`
|
|
76
78
|
- `notify.client(…).preferences`: `retrieve`, `update`
|
|
@@ -107,7 +109,7 @@ Every failure is a class you can catch. `APIError` carries `status`, `code`, `me
|
|
|
107
109
|
import { Notify, NotFoundError, RateLimitError, APIError } from "@productcraft/notify";
|
|
108
110
|
const notify = new Notify();
|
|
109
111
|
try {
|
|
110
|
-
await notify.
|
|
112
|
+
await notify.approvals.retrieve("00000000-0000-0000-0000-000000000000");
|
|
111
113
|
} catch (err) {
|
|
112
114
|
if (err instanceof NotFoundError) console.log(err.code, err.requestId, err.docUrl);
|
|
113
115
|
else if (err instanceof RateLimitError) console.log(err.retryAfter);
|
|
@@ -151,7 +153,7 @@ const notify = new Notify();
|
|
|
151
153
|
export async function POST(req: Request) {
|
|
152
154
|
const event = await notify.webhooks.unwrap({ payload: await req.text(), headers: req.headers });
|
|
153
155
|
switch (event.type) {
|
|
154
|
-
case "
|
|
156
|
+
case "approval.resolved":
|
|
155
157
|
console.log(event.data);
|
|
156
158
|
break;
|
|
157
159
|
default:
|
|
@@ -194,7 +196,7 @@ Testing a handler: `webhooks.sign()` signs an event the way ProductCraft does, s
|
|
|
194
196
|
```ts
|
|
195
197
|
import { Notify } from "@productcraft/notify";
|
|
196
198
|
const notify = new Notify({ webhookSecret: "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" });
|
|
197
|
-
const { payload, headers } = await notify.webhooks.sign({ payload: { id: "evt_test_1", type: "
|
|
199
|
+
const { payload, headers } = await notify.webhooks.sign({ payload: { id: "evt_test_1", type: "approval.resolved", created_at: new Date().toISOString(), data: {} } });
|
|
198
200
|
const event = await notify.webhooks.unwrap({ payload, headers });
|
|
199
201
|
console.log(event.type);
|
|
200
202
|
```
|
|
@@ -207,9 +209,9 @@ Every returned object has a non-enumerable `lastResponse` (`requestId`, `status`
|
|
|
207
209
|
import { Notify } from "@productcraft/notify";
|
|
208
210
|
const notify = new Notify({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
|
|
209
211
|
const id = "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b";
|
|
210
|
-
const obj = await notify.
|
|
212
|
+
const obj = await notify.approvals.retrieve(id);
|
|
211
213
|
console.log(obj.lastResponse.requestId);
|
|
212
|
-
const { data, response, requestId, rateLimit } = await notify.
|
|
214
|
+
const { data, response, requestId, rateLimit } = await notify.approvals.retrieve(id).withResponse();
|
|
213
215
|
console.log(data, response.status, requestId, rateLimit?.remaining);
|
|
214
216
|
```
|
|
215
217
|
|
|
@@ -233,7 +235,7 @@ console.log(fetch.calls.length);
|
|
|
233
235
|
```ts
|
|
234
236
|
import { Notify } from "@productcraft/notify";
|
|
235
237
|
const notify = new Notify({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
|
|
236
|
-
const { data, error } = await notify.client.GET("/v1/workspaces/{workspace_id}/
|
|
238
|
+
const { data, error } = await notify.client.GET("/v1/workspaces/{workspace_id}/approvals", { params: { path: { workspace_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b" } } });
|
|
237
239
|
console.log(data, error);
|
|
238
240
|
```
|
|
239
241
|
|
package/api.md
CHANGED
|
@@ -5,6 +5,144 @@
|
|
|
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
|
+
## approvals
|
|
9
|
+
|
|
10
|
+
### `notify.approvals.cancel(approvalId, options?)`
|
|
11
|
+
|
|
12
|
+
`POST /v1/workspaces/{workspace_id}/approvals/{approval_id}/cancel` → `Notify.Approval`
|
|
13
|
+
|
|
14
|
+
Cancel an approval request.
|
|
15
|
+
|
|
16
|
+
Withdraws a pending request: approvers see it as cancelled, nothing more is sent, and `approval.resolved` fires with `status: cancelled`. Takes no Idempotency-Key: cancelling twice is a 409 the second time.
|
|
17
|
+
|
|
18
|
+
- Credential: [`bearer`](#bearer)
|
|
19
|
+
|
|
20
|
+
| Status | Error class | Codes | When |
|
|
21
|
+
|---|---|---|---|
|
|
22
|
+
| 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/…`). |
|
|
23
|
+
| 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). |
|
|
24
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `APPROVAL_NOT_FOUND` | `APPROVAL_NOT_FOUND`: no approval request with this id in this workspace. |
|
|
25
|
+
| 409 | `ConflictError` | `CONFLICT`, `APPROVAL_NOT_PENDING` | `APPROVAL_NOT_PENDING`: it was already answered, expired or cancelled. |
|
|
26
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
const approval = await notify.approvals.cancel("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-approvals-approval-id-cancel)
|
|
33
|
+
|
|
34
|
+
### `notify.approvals.create(params, options?)`
|
|
35
|
+
|
|
36
|
+
`POST /v1/workspaces/{workspace_id}/approvals` → `Notify.Approval`
|
|
37
|
+
|
|
38
|
+
Request an approval.
|
|
39
|
+
|
|
40
|
+
Asks one or more people a yes/no question on the type's channels and records the first answer. In the inbox the item gets Approve and Reject buttons (or render it with `<NotifyApproval/>`); emails and pushes carry a signed link per approver (`approval.url`, `approval.approve_url`, `approval.reject_url`) to a hosted page that needs no sign-in. The answer arrives as the signed `approval.resolved` webhook and on `GET /approvals/{approval_id}`. Nobody answered by `expires_at`: the type's `timeout_outcome` applies (default `expired`). Pass `wait_seconds` (up to 15) to wait for the answer in this call. The type must have `approval` set; its notifications can only be sent here. An `Idempotency-Key` is required: the same key and body return the same request (200), a different body is a 409.
|
|
41
|
+
|
|
42
|
+
- Params: `Notify.ApprovalCreateParams`
|
|
43
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
44
|
+
- Credential: [`bearer`](#bearer)
|
|
45
|
+
|
|
46
|
+
| Status | Error class | Codes | When |
|
|
47
|
+
|---|---|---|---|
|
|
48
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `IDEMPOTENCY_KEY_REQUIRED` | `IDEMPOTENCY_KEY_REQUIRED`; `VALIDATION_ERROR`: a field is invalid. |
|
|
49
|
+
| 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/…`). |
|
|
50
|
+
| 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). |
|
|
51
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key. |
|
|
52
|
+
| 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). |
|
|
53
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `NOT_AN_APPROVAL_TYPE`, `NOTIFICATION_TYPE_ARCHIVED`, `RECIPIENT_NOT_FOUND` | `NOT_AN_APPROVAL_TYPE`: the type has no `approval`; `NOTIFICATION_TYPE_ARCHIVED`; `RECIPIENT_NOT_FOUND`: an approver is not a recipient (`details.missing`). |
|
|
54
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over the workspace send limit; 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. |
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const approval = await notify.approvals.create({
|
|
58
|
+
approvers: ["user_123"],
|
|
59
|
+
title: "Deploy api v2.14 to production?",
|
|
60
|
+
type: "deploy.approval",
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-approvals)
|
|
65
|
+
|
|
66
|
+
### `notify.approvals.list(params?, options?)`
|
|
67
|
+
|
|
68
|
+
`GET /v1/workspaces/{workspace_id}/approvals` → `PagePromise<Notify.Approval>`
|
|
69
|
+
|
|
70
|
+
List approval requests.
|
|
71
|
+
|
|
72
|
+
Newest first; filter by `status` and `type`. Pass `next_cursor` as `cursor` until `has_more` is false.
|
|
73
|
+
|
|
74
|
+
- Params: `Notify.ApprovalListParams`
|
|
75
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
76
|
+
- Credential: [`bearer`](#bearer)
|
|
77
|
+
|
|
78
|
+
| Status | Error class | Codes | When |
|
|
79
|
+
|---|---|---|---|
|
|
80
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor. |
|
|
81
|
+
| 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/…`). |
|
|
82
|
+
| 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). |
|
|
83
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
for await (const approval of notify.approvals.list()) {
|
|
87
|
+
console.log(approval);
|
|
88
|
+
}
|
|
89
|
+
const page = await notify.approvals.list({}, { timeout: 5_000 });
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-approvals)
|
|
93
|
+
|
|
94
|
+
### `notify.approvals.recordDecision(approvalId, params, options?)`
|
|
95
|
+
|
|
96
|
+
`POST /v1/workspaces/{workspace_id}/approvals/{approval_id}/decision` → `Notify.Approval`
|
|
97
|
+
|
|
98
|
+
Record an approver's answer.
|
|
99
|
+
|
|
100
|
+
For answers you collected yourself (your own UI, a phone call): records `approve` or `reject` for one of the approvers, exactly as if they had pressed the button (`decided_via: api`). Never give this to the agent that made the request: it is how a human's answer gets in, so it is not an MCP tool.
|
|
101
|
+
|
|
102
|
+
- Params: `Notify.ApprovalRecordDecisionParams`
|
|
103
|
+
- Credential: [`bearer`](#bearer)
|
|
104
|
+
|
|
105
|
+
| Status | Error class | Codes | When |
|
|
106
|
+
|---|---|---|---|
|
|
107
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
|
|
108
|
+
| 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/…`). |
|
|
109
|
+
| 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). |
|
|
110
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `APPROVAL_NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `APPROVAL_NOT_FOUND`, or `RECIPIENT_NOT_FOUND`: no recipient with that external id. |
|
|
111
|
+
| 409 | `ConflictError` | `CONFLICT`, `APPROVAL_NOT_PENDING` | `APPROVAL_NOT_PENDING`: already answered, expired or cancelled. |
|
|
112
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `NOT_AN_APPROVER`, `APPROVAL_REASON_REQUIRED` | `NOT_AN_APPROVER`: that recipient was not asked; `APPROVAL_REASON_REQUIRED`: the type needs a reason. |
|
|
113
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
const approval = await notify.approvals.recordDecision("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { approver: "user_123", decision: "approve" });
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-approvals-approval-id-decision)
|
|
120
|
+
|
|
121
|
+
### `notify.approvals.retrieve(approvalId, params?, options?)`
|
|
122
|
+
|
|
123
|
+
`GET /v1/workspaces/{workspace_id}/approvals/{approval_id}` → `Notify.ApprovalDetail`
|
|
124
|
+
|
|
125
|
+
Get an approval request.
|
|
126
|
+
|
|
127
|
+
Its status, the answer (who, when, why, from where) and its trail. With `wait_seconds` (up to 15) a pending request is long-polled: the call returns as soon as someone answers, or after that many seconds.
|
|
128
|
+
|
|
129
|
+
- Params: `Notify.ApprovalRetrieveParams`
|
|
130
|
+
- Credential: [`bearer`](#bearer)
|
|
131
|
+
|
|
132
|
+
| Status | Error class | Codes | When |
|
|
133
|
+
|---|---|---|---|
|
|
134
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `wait_seconds` out of range. |
|
|
135
|
+
| 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/…`). |
|
|
136
|
+
| 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). |
|
|
137
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `APPROVAL_NOT_FOUND` | `APPROVAL_NOT_FOUND`: no approval request with this id in this workspace. |
|
|
138
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
const approvalDetail = await notify.approvals.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-approvals-approval-id)
|
|
145
|
+
|
|
8
146
|
## batches
|
|
9
147
|
|
|
10
148
|
### `notify.batches.flush(batchId, options?)`
|
|
@@ -675,16 +813,7 @@ Changes the fields you send; `routing` is replaced whole. The key cannot change.
|
|
|
675
813
|
|
|
676
814
|
```ts
|
|
677
815
|
const notificationType = await notify.notificationTypes.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
678
|
-
|
|
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
|
-
},
|
|
816
|
+
approval: { default_expires_in_seconds: 86400, reason: "optional", timeout_outcome: "expired" },
|
|
688
817
|
});
|
|
689
818
|
```
|
|
690
819
|
|
|
@@ -956,7 +1085,7 @@ Notifies up to 1,000 recipients with one notification type, across the type's ch
|
|
|
956
1085
|
| 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key. |
|
|
957
1086
|
| 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). |
|
|
958
1087
|
| 413 | `APIError` | `PAYLOAD_TOO_LARGE`, `DATA_TOO_LARGE` | `DATA_TOO_LARGE`: `data` is over 16 KB. |
|
|
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. |
|
|
1088
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `RECIPIENT_NOT_FOUND`, `NOTIFICATION_TYPE_ARCHIVED`, `TEMPLATE_MISSING`, `SEND_AT_OUT_OF_RANGE`, `BATCHED_TYPE_NOT_SCHEDULABLE`, `APPROVAL_TYPE_SEND_REFUSED`, `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); `APPROVAL_TYPE_SEND_REFUSED`: an approval type, sent with `POST /approvals`; `UNSAFE_URL`; `VALIDATION_ERROR`: a channel outside the type's routing. |
|
|
960
1089
|
| 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. |
|
|
961
1090
|
|
|
962
1091
|
```ts
|
|
@@ -1541,7 +1670,7 @@ const notifyStats = await notify.stats.retrieve();
|
|
|
1541
1670
|
|
|
1542
1671
|
### `notify.webhooks.unwrap({ payload, headers, secret? })`
|
|
1543
1672
|
|
|
1544
|
-
Verifies the signature and returns `Notify.UnwrapWebhookEvent`. Events: `credential.invalid`, `delivery.bounced`, `delivery.delivered`, `delivery.failed`, `delivery.sent`, `delivery.skipped`, `device.moved`, `device.pruned`, `email.auto_paused`, `inbox_item.archived`, `inbox_item.interacted`, `inbox_item.read`, `notification.accepted`, `recipient.deleted`, plus `UnknownWebhookEvent` for types added later.
|
|
1673
|
+
Verifies the signature and returns `Notify.UnwrapWebhookEvent`. Events: `approval.resolved`, `credential.invalid`, `delivery.bounced`, `delivery.delivered`, `delivery.failed`, `delivery.sent`, `delivery.skipped`, `device.moved`, `device.pruned`, `email.auto_paused`, `inbox_item.archived`, `inbox_item.interacted`, `inbox_item.read`, `notification.accepted`, `notification.webhook`, `recipient.deleted`, plus `UnknownWebhookEvent` for types added later.
|
|
1545
1674
|
|
|
1546
1675
|
### `notify.webhooks.sign({ payload, secret?, id?, timestamp? })`
|
|
1547
1676
|
|
|
@@ -1837,6 +1966,58 @@ const webhookEventDetail = await notify.webhooks.events.retrieve("3f0c1a2b-4c5d-
|
|
|
1837
1966
|
|
|
1838
1967
|
[HTTP reference](https://productcraft.co/docs/notify/api-reference#get-v1-workspaces-workspace-id-webhooks-events-event-id)
|
|
1839
1968
|
|
|
1969
|
+
## client(…).approvals
|
|
1970
|
+
|
|
1971
|
+
### `notify.client({ token }).approvals.decide(approvalId, params, options?)`
|
|
1972
|
+
|
|
1973
|
+
`POST /v1/client/approvals/{approval_id}/decision` → `Notify.Approval`
|
|
1974
|
+
|
|
1975
|
+
Answer an approval request.
|
|
1976
|
+
|
|
1977
|
+
Approve or reject, with an optional reason (required when the type says so). The first answer of any approver decides; the requester gets the signed `approval.resolved` webhook. Answering again, or after the request expired, is a 409.
|
|
1978
|
+
|
|
1979
|
+
- Params: `Notify.MeApprovalDecideParams`
|
|
1980
|
+
- Credential: [`recipient_token`](#recipient_token)
|
|
1981
|
+
|
|
1982
|
+
| Status | Error class | Codes | When |
|
|
1983
|
+
|---|---|---|---|
|
|
1984
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `decision` must be `approve` or `reject`. |
|
|
1985
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
|
|
1986
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
|
|
1987
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `APPROVAL_NOT_FOUND` | `APPROVAL_NOT_FOUND`: no such request for this recipient. |
|
|
1988
|
+
| 409 | `ConflictError` | `CONFLICT`, `APPROVAL_NOT_PENDING` | `APPROVAL_NOT_PENDING`: already answered, expired or cancelled. |
|
|
1989
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `APPROVAL_REASON_REQUIRED` | `APPROVAL_REASON_REQUIRED`: a reason is required. |
|
|
1990
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1991
|
+
|
|
1992
|
+
```ts
|
|
1993
|
+
const approval = await notify.client({ token: "rt_example_recipient_token" }).approvals.decide("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { decision: "approve" });
|
|
1994
|
+
```
|
|
1995
|
+
|
|
1996
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-client-approvals-approval-id-decision)
|
|
1997
|
+
|
|
1998
|
+
### `notify.client({ token }).approvals.retrieve(approvalId, options?)`
|
|
1999
|
+
|
|
2000
|
+
`GET /v1/client/approvals/{approval_id}` → `Notify.Approval`
|
|
2001
|
+
|
|
2002
|
+
Get an approval request.
|
|
2003
|
+
|
|
2004
|
+
One request the recipient was asked to answer: the question, who asked, its status and, once decided, who answered and why.
|
|
2005
|
+
|
|
2006
|
+
- Credential: [`recipient_token`](#recipient_token)
|
|
2007
|
+
|
|
2008
|
+
| Status | Error class | Codes | When |
|
|
2009
|
+
|---|---|---|---|
|
|
2010
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
|
|
2011
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:read` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
|
|
2012
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `APPROVAL_NOT_FOUND` | `APPROVAL_NOT_FOUND`: no such request for this recipient. |
|
|
2013
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
2014
|
+
|
|
2015
|
+
```ts
|
|
2016
|
+
const approval = await notify.client({ token: "rt_example_recipient_token" }).approvals.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
2017
|
+
```
|
|
2018
|
+
|
|
2019
|
+
[HTTP reference](https://productcraft.co/docs/notify/api-reference#get-v1-client-approvals-approval-id)
|
|
2020
|
+
|
|
1840
2021
|
## client(…).devices
|
|
1841
2022
|
|
|
1842
2023
|
### `notify.client({ token }).devices.delete(deviceId, options?)`
|
|
@@ -2135,6 +2316,12 @@ A recipient token minted by your backend with `POST /v1/workspaces/{workspace_id
|
|
|
2135
2316
|
| `STREAM_LIMIT` | The recipient has the maximum number of open real-time streams. |
|
|
2136
2317
|
| `LIMIT_EXCEEDED` | A preview limit of the workspace was reached. |
|
|
2137
2318
|
| `BATCHED_TYPE_NOT_SCHEDULABLE` | The notification type batches its notifications (`batch`): send it now, the batch window or digest decides when it goes out. |
|
|
2319
|
+
| `APPROVAL_NOT_FOUND` | No approval request with this id in this workspace (or, on the client API, not one this recipient was asked). |
|
|
2320
|
+
| `APPROVAL_NOT_PENDING` | The approval request was already answered, expired or cancelled: the first answer decides. |
|
|
2321
|
+
| `APPROVAL_REASON_REQUIRED` | The approval type requires a reason for this answer. |
|
|
2322
|
+
| `APPROVAL_TYPE_SEND_REFUSED` | Notifications of an approval type are sent with POST /approvals, not POST /notifications. |
|
|
2323
|
+
| `NOT_AN_APPROVAL_TYPE` | The notification type has no `approval` config, so it cannot carry approval requests. |
|
|
2324
|
+
| `NOT_AN_APPROVER` | That recipient was not asked to answer this approval request. |
|
|
2138
2325
|
| `BATCH_NOT_FOUND` | No batch with this id in this workspace. |
|
|
2139
2326
|
| `BATCH_NOT_OPEN` | The batch is already closed (flushed or cancelled), or closing right now. |
|
|
2140
2327
|
| `SEND_AT_OUT_OF_RANGE` | `send_at` or `delay_seconds` is in the past or beyond the type TTL. |
|