@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.
Files changed (2) hide show
  1. package/README.md +69 -1
  2. 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: { source: "signup" },
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@supacloud/js",
3
- "version": "0.16.0",
3
+ "version": "0.16.1",
4
4
  "description": "Platform SDK for SupaCloud, built on top of supabase-js",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",