@supacloud/js 0.16.0 → 0.16.1
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 +69 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -34,6 +34,12 @@ const supacloud = createSupaCloudClient({
|
|
|
34
34
|
const task = await supacloud.tasks.submit("aorist-ai/generate/crop", {
|
|
35
35
|
body: { image_id: "img_123" },
|
|
36
36
|
idempotencyKey: "crop-img_123-v1",
|
|
37
|
+
correlationId: "workflow-run-123",
|
|
38
|
+
businessTaskId: "aorist-task-123",
|
|
39
|
+
metadata: {
|
|
40
|
+
workflow_id: "workflow-123",
|
|
41
|
+
billing_subject: "user-123",
|
|
42
|
+
},
|
|
37
43
|
});
|
|
38
44
|
|
|
39
45
|
const finalState = await task.wait();
|
|
@@ -50,6 +56,8 @@ This SDK is intentionally thin:
|
|
|
50
56
|
`tasks.submit()` expects the target function path to be configured in `background_routes`.
|
|
51
57
|
That keeps frontend calls compatible with strict CORS deployments while preserving the same task receipt API.
|
|
52
58
|
|
|
59
|
+
Use `correlationId`, `businessTaskId`, and `metadata` when the application already has its own task, workflow, or billing records. SupaCloud stores these fields but does not interpret them; lifecycle webhooks echo them back so the application can update its own tables.
|
|
60
|
+
|
|
53
61
|
The current package focuses on:
|
|
54
62
|
|
|
55
63
|
- `tasks.submit`
|
|
@@ -88,6 +96,37 @@ The current package focuses on:
|
|
|
88
96
|
|
|
89
97
|
This lets apps degrade gracefully when websocket or channel health is transient.
|
|
90
98
|
|
|
99
|
+
## Task Lifecycle Webhook
|
|
100
|
+
|
|
101
|
+
Applications that already own a business task table should keep it. SupaCloud emits lifecycle events so the app can sync `public.tasks`, billing, Realtime, and workflow rows without adopting platform-internal mirror tables.
|
|
102
|
+
|
|
103
|
+
Register a webhook from a trusted backend:
|
|
104
|
+
|
|
105
|
+
```http
|
|
106
|
+
POST /v1/projects/:ref/task-events/webhook
|
|
107
|
+
Authorization: Bearer <management-token>
|
|
108
|
+
Content-Type: application/json
|
|
109
|
+
|
|
110
|
+
{
|
|
111
|
+
"url": "https://app.example.com/supacloud/task-events",
|
|
112
|
+
"secret": "shared-hmac-secret"
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Events are delivered as `{ events: [...] }`. Each event includes `event_type`, `task_id`, `status`, `attempt`, `correlation_id`, `business_task_id`, and `metadata`.
|
|
117
|
+
|
|
118
|
+
Supported lifecycle events:
|
|
119
|
+
|
|
120
|
+
- `task.created`
|
|
121
|
+
- `task.running`
|
|
122
|
+
- `task.succeeded`
|
|
123
|
+
- `task.failed`
|
|
124
|
+
- `task.retry_scheduled`
|
|
125
|
+
- `task.dead_lettered`
|
|
126
|
+
- `task.cancelled`
|
|
127
|
+
|
|
128
|
+
If `secret` is set, verify `X-SupaCloud-Signature: sha256=<hmac>` against the raw JSON body.
|
|
129
|
+
|
|
91
130
|
## Queue Helpers
|
|
92
131
|
|
|
93
132
|
```ts
|
|
@@ -97,9 +136,15 @@ const message = await queue.send(
|
|
|
97
136
|
{ to: "user@example.com", template: "welcome" },
|
|
98
137
|
{
|
|
99
138
|
idempotencyKey: "welcome-user-123",
|
|
139
|
+
delayMs: 10_000,
|
|
140
|
+
maxAttempts: 5,
|
|
141
|
+
traceId: "trace-123",
|
|
100
142
|
correlationId: "signup-123",
|
|
101
143
|
businessTaskId: "email-job-123",
|
|
102
|
-
metadata: {
|
|
144
|
+
metadata: {
|
|
145
|
+
source: "signup",
|
|
146
|
+
billing_subject: "user-123",
|
|
147
|
+
},
|
|
103
148
|
},
|
|
104
149
|
);
|
|
105
150
|
|
|
@@ -117,6 +162,29 @@ const stats = await queue.stats();
|
|
|
117
162
|
console.log(stats.inFlight, stats.deadLettered);
|
|
118
163
|
```
|
|
119
164
|
|
|
165
|
+
Queue API surface:
|
|
166
|
+
|
|
167
|
+
- `queue.send(payload, options)`: enqueue a message, optionally delayed and idempotent
|
|
168
|
+
- `queue.receive({ visibilityTimeoutSec })`: lease the next message, or return `null`
|
|
169
|
+
- `queue.ack(messageId, result)`: mark the leased message succeeded
|
|
170
|
+
- `queue.release(messageId, { delayMs, error })`: return the message to the queue later
|
|
171
|
+
- `queue.fail(messageId, { error, deadLetter })`: mark failed or dead-lettered
|
|
172
|
+
- `queue.retry(messageId)`: replay a dead-lettered message
|
|
173
|
+
- `queue.delete(messageId)`: cancel/delete a message
|
|
174
|
+
- `queue.list(filters)`: list messages by status, DLQ flag, and limit
|
|
175
|
+
- `queue.listFailed(limit)`: shortcut for DLQ messages
|
|
176
|
+
- `queue.get(messageId)`: read message detail, attempts, and latest logs
|
|
177
|
+
- `queue.stats()`: inspect queue depth and recent success/failure counts
|
|
178
|
+
- `queue.getSettings()`: read concurrency, lease, retry, and rate-limit settings
|
|
179
|
+
- `queue.updateSettings(settings)`: patch queue settings
|
|
180
|
+
|
|
181
|
+
Queue settings:
|
|
182
|
+
|
|
183
|
+
- `max_in_flight`: max concurrently leased/running messages for this queue
|
|
184
|
+
- `default_visibility_timeout_sec`: lease timeout used by `receive()`
|
|
185
|
+
- `max_attempts`: default retry budget for new messages
|
|
186
|
+
- `rate_limit_per_minute`: producer enqueue limit
|
|
187
|
+
|
|
120
188
|
Queue conflicts such as replaying a non-DLQ message are surfaced as `SupaCloudApiError` with `status`, `code`, and `responseBody`, so callers do not need to parse raw `fetch` responses.
|
|
121
189
|
|
|
122
190
|
## OAuth/OIDC Helpers
|