@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 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.batches.retrieve("00000000-0000-0000-0000-000000000000");
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 "credential.invalid":
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: "credential.invalid", created_at: new Date().toISOString(), data: {} } });
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.batches.retrieve(id);
212
+ const obj = await notify.approvals.retrieve(id);
211
213
  console.log(obj.lastResponse.requestId);
212
- const { data, response, requestId, rateLimit } = await notify.batches.retrieve(id).withResponse();
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}/batches", { params: { path: { workspace_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b" } } });
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
- 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
- },
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. |