@supacloud/js 0.29.0 → 0.31.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 +373 -104
- package/dist/api-error.d.ts +6 -0
- package/dist/artifact-fetch.d.ts +6 -0
- package/dist/artifact-link.d.ts +8 -0
- package/dist/artifact-read.d.ts +13 -0
- package/dist/artifact-register.d.ts +14 -0
- package/dist/artifact-rpc.d.ts +2 -0
- package/dist/artifacts.d.ts +3 -0
- package/dist/auth-fetch.d.ts +4 -2
- package/dist/bounded-rpc-fetch.d.ts +2 -0
- package/dist/command-fetch.d.ts +6 -0
- package/dist/commands.d.ts +10 -0
- package/dist/index.d.ts +80 -278
- package/dist/index.js +3031 -668
- package/dist/oauth-clients.d.ts +95 -0
- package/dist/oauth-server.d.ts +104 -0
- package/dist/queue-rpc.d.ts +54 -0
- package/dist/workflow-advance.d.ts +8 -0
- package/dist/workflow-attempt.d.ts +4 -0
- package/dist/workflow-cancel.d.ts +14 -0
- package/dist/workflow-claim.d.ts +12 -0
- package/dist/workflow-complete.d.ts +8 -0
- package/dist/workflow-events.d.ts +14 -0
- package/dist/workflow-fail.d.ts +8 -0
- package/dist/workflow-fetch.d.ts +9 -0
- package/dist/workflow-json.d.ts +2 -0
- package/dist/workflow-retry.d.ts +8 -0
- package/dist/workflow-rpc.d.ts +6 -0
- package/dist/workflow-run.d.ts +8 -0
- package/dist/workflow-start.d.ts +8 -0
- package/dist/workflow-timestamp.d.ts +1 -0
- package/dist/workflows.d.ts +9 -0
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -7,13 +7,13 @@ It does **not** replace [`@supabase/supabase-js`](https://www.npmjs.com/package/
|
|
|
7
7
|
- background task submission
|
|
8
8
|
- task detail and list APIs
|
|
9
9
|
- cancel / retry helpers
|
|
10
|
-
-
|
|
10
|
+
- Task subscription through polling, with optional application-owned Realtime
|
|
11
11
|
- Supabase Queues helpers backed by the official `pgmq_public` RPC API, plus SupaCloud management extensions for queue administration and diagnostics
|
|
12
12
|
- Service-role-only durable workflow helpers backed by PostgreSQL and PGMQ
|
|
13
13
|
- Service-role-only transactional command receipts backed by Durable Workflows
|
|
14
14
|
- Immutable Storage artifact registration and lineage helpers
|
|
15
15
|
- project OAuth/OIDC migration and OAuth client management
|
|
16
|
-
- SupAuth
|
|
16
|
+
- SupAuth-compatible OAuth refresh adaptation
|
|
17
17
|
|
|
18
18
|
## Install
|
|
19
19
|
|
|
@@ -25,9 +25,15 @@ npm install @supacloud/js @supabase/supabase-js
|
|
|
25
25
|
|
|
26
26
|
```ts
|
|
27
27
|
import { createClient } from "@supabase/supabase-js";
|
|
28
|
-
import { createSupaCloudClient } from "@supacloud/js";
|
|
28
|
+
import { createSupaCloudClient, createSupaCloudTaskFetch } from "@supacloud/js";
|
|
29
29
|
|
|
30
|
-
const supabase = createClient("https://api.example.com", "anon-key"
|
|
30
|
+
const supabase = createClient("https://api.example.com", "anon-key", {
|
|
31
|
+
global: {
|
|
32
|
+
fetch: createSupaCloudTaskFetch({
|
|
33
|
+
functionUrls: ["https://api.example.com/functions/v1/aorist-ai/generate/crop"],
|
|
34
|
+
}),
|
|
35
|
+
},
|
|
36
|
+
});
|
|
31
37
|
|
|
32
38
|
const supacloud = createSupaCloudClient({
|
|
33
39
|
supabase,
|
|
@@ -84,50 +90,26 @@ redirects instead of forwarding the refresh token to a second endpoint. All
|
|
|
84
90
|
other Supabase Auth, Database, Storage, Realtime, and Functions requests pass
|
|
85
91
|
through unchanged. Never pass a client secret to browser code.
|
|
86
92
|
|
|
87
|
-
## SupAuth Management
|
|
88
|
-
|
|
89
|
-
`supacloud.supauth` is a management-plane helper for provisioning and verifying a SupAuth/SupaOAuth runtime on SupaCloud. It is intended for trusted server-side tools, CI jobs, or admin backends that can call the SupaCloud Management API.
|
|
90
|
-
|
|
91
|
-
```ts
|
|
92
|
-
const supacloud = createSupaCloudClient({
|
|
93
|
-
supabase,
|
|
94
|
-
managementApiUrl: "https://admin.example.com",
|
|
95
|
-
projectRef: "abcd1234",
|
|
96
|
-
getAccessToken: () => process.env.SUPACLOUD_MANAGEMENT_TOKEN ?? null,
|
|
97
|
-
});
|
|
93
|
+
## SupAuth Management Compatibility
|
|
98
94
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
95
|
+
**Breaking change:** the unsupported `supacloud.supauth` namespace and all
|
|
96
|
+
`SupaCloudSupAuth*` types have been removed. Its five methods (`provision`,
|
|
97
|
+
`reconcile`, `rollback`, `getClientConfig`, `verify`) targeted routes that are
|
|
98
|
+
not implemented by this repository's Management API. Earlier examples and
|
|
99
|
+
mocked success responses did not establish that these operations existed.
|
|
100
|
+
Consumers using that namespace must remove those calls before upgrading.
|
|
101
|
+
There is no equivalent SupAuth provisioning, rollback or health workflow in
|
|
102
|
+
this SDK; an actual backend contract is required before one can be added.
|
|
105
103
|
|
|
106
|
-
|
|
104
|
+
The existing `auth.oauthServer` and `auth.oauthClients` APIs remain available
|
|
105
|
+
for their documented OAuth/OIDC operations. OAuth Server status describes
|
|
106
|
+
configuration, not verified runtime health, and is not a replacement for the
|
|
107
|
+
removed SupAuth verification helper. `createSupaCloudOAuthFetch` continues to
|
|
108
|
+
adapt SupAuth refresh requests without adding a Management orchestration API.
|
|
109
|
+
Normal application sessions, database, storage, realtime and edge-function
|
|
110
|
+
calls remain on `@supabase/supabase-js`.
|
|
107
111
|
|
|
108
|
-
|
|
109
|
-
if (!health.healthy) {
|
|
110
|
-
throw new Error("SupAuth runtime is not healthy");
|
|
111
|
-
}
|
|
112
|
-
|
|
113
|
-
const config = await supacloud.supauth.getClientConfig();
|
|
114
|
-
console.log(config.authUrl);
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
The helper maps to these SupaCloud Management API routes:
|
|
118
|
-
|
|
119
|
-
- `POST /v1/projects/:projectRef/supauth/provision`
|
|
120
|
-
- `POST /v1/projects/:projectRef/supauth/reconcile`
|
|
121
|
-
- `POST /v1/projects/:projectRef/supauth/rollback`
|
|
122
|
-
- `GET /v1/projects/:projectRef/supauth/client-config`
|
|
123
|
-
- `GET /v1/projects/:projectRef/supauth/verify`
|
|
124
|
-
|
|
125
|
-
Boundary:
|
|
126
|
-
|
|
127
|
-
- Use `@supacloud/js` for SupaCloud-owned infrastructure orchestration: GoTrue env injection, restart/reconcile, Caddy route setup, runtime health checks, and public client config discovery.
|
|
128
|
-
- Use `@supabase/supabase-js` for normal application runtime calls: auth session, database, storage, realtime, and edge functions.
|
|
129
|
-
- Use the SupaOAuth product SDK or Management API for SupaOAuth-owned resources: applications, connectors, organizations, roles, permissions, audit logs, and webhooks.
|
|
130
|
-
- Do not expose SupaCloud Management API credentials in browser code.
|
|
112
|
+
Do not expose SupaCloud Management API credentials in browser code.
|
|
131
113
|
|
|
132
114
|
## Design
|
|
133
115
|
|
|
@@ -138,6 +120,101 @@ This SDK is intentionally thin:
|
|
|
138
120
|
|
|
139
121
|
`tasks.submit()` expects the target function path to be configured in `background_routes`.
|
|
140
122
|
That keeps frontend calls compatible with strict CORS deployments while preserving the same task receipt API.
|
|
123
|
+
Successful submission requires the official invocation's HTTP `Response` with
|
|
124
|
+
status 202 and no redirect marker. Other success statuses or missing response
|
|
125
|
+
metadata are unconfirmed even when the body resembles a task receipt. This
|
|
126
|
+
post-response check does not prevent a transport from following redirects.
|
|
127
|
+
Receipts require `project_ref` exactly matching the configured project, a valid
|
|
128
|
+
task ID and a nonempty string status. Missing project identity is unconfirmed,
|
|
129
|
+
not accepted as a legacy receipt. Missing status
|
|
130
|
+
no longer defaults to `enqueued`. Legacy `taskId` is accepted, but both ID
|
|
131
|
+
aliases must agree after UUID normalization. Progressed and future statuses
|
|
132
|
+
are preserved for idempotent replay. Invalid receipts throw
|
|
133
|
+
`SupaCloudTaskSubmitError` with `TASK_SUBMIT_UNCONFIRMED` and
|
|
134
|
+
`mutationMayHaveApplied: true`. This does not prove enqueue failure; the SDK
|
|
135
|
+
does not automatically retry. Receipt validation is not a function transport
|
|
136
|
+
timeout or streamed response-size limit.
|
|
137
|
+
Submission waiting has a separate 15-second deadline around the official
|
|
138
|
+
Functions invocation, including waiting for its parsed response. On timeout,
|
|
139
|
+
the SDK aborts the invocation signal and throws `TASK_SUBMIT_UNCONFIRMED` with
|
|
140
|
+
`mutationMayHaveApplied: true`; it never automatically replays the call.
|
|
141
|
+
The legacy `retries` and `timeoutSec` submit fields are accepted for source
|
|
142
|
+
compatibility but ignored; configure retry budgets and worker timeouts in the
|
|
143
|
+
platform project/function settings. This SDK deadline is independent of worker
|
|
144
|
+
execution time. A custom transport that ignores cancellation may continue in
|
|
145
|
+
the background. The deadline does not impose a streamed response-size limit.
|
|
146
|
+
Network, relay, server and response-parsing failures also produce
|
|
147
|
+
`TASK_SUBMIT_UNCONFIRMED`, without exposing the underlying exception.
|
|
148
|
+
Verified official `FunctionsHttpError` responses with a non-redirected HTTP
|
|
149
|
+
4xx status retain their original error and response context. Neither category
|
|
150
|
+
is automatically retried.
|
|
151
|
+
|
|
152
|
+
Background task idempotency keys bind the invocation content, business headers,
|
|
153
|
+
caller identity, exact decrypted credentials and execution configuration.
|
|
154
|
+
Reusing a key with different values returns HTTP 409 `TASK_IDEMPOTENCY_CONFLICT`.
|
|
155
|
+
Tracing headers may change, and re-encrypting unchanged credentials is allowed.
|
|
156
|
+
A refreshed JWT or rotated API key is a credential change, even for the same user.
|
|
157
|
+
After an unconfirmed submission, do not automatically switch to a new key:
|
|
158
|
+
the original task may already exist. Read its receipt/task when available and
|
|
159
|
+
resolve the original outcome before submitting a distinct operation.
|
|
160
|
+
The SDK never automatically retries submission. The Management service may
|
|
161
|
+
retry database failures only when a nonempty idempotency key is present;
|
|
162
|
+
without one, a failed submission can still have committed a task.
|
|
163
|
+
|
|
164
|
+
To bound the response before the official Functions client parses it, install
|
|
165
|
+
the task transport when creating the Supabase client:
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
import { createClient } from "@supabase/supabase-js";
|
|
169
|
+
import { createSupaCloudTaskFetch } from "@supacloud/js";
|
|
170
|
+
|
|
171
|
+
const supabase = createClient(supabaseUrl, publishableKey, {
|
|
172
|
+
global: {
|
|
173
|
+
fetch: createSupaCloudTaskFetch({
|
|
174
|
+
functionUrls: [`${supabaseUrl}/functions/v1/aorist-ai/generate/crop`],
|
|
175
|
+
}),
|
|
176
|
+
},
|
|
177
|
+
});
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Only the captured origin/path pairs are guarded; query arguments do not change
|
|
181
|
+
the match. Configured URLs must not include credentials, query or fragment.
|
|
182
|
+
Matched requests use a 1 MiB streamed-byte cap, strict UTF-8/JSON, a 15-second
|
|
183
|
+
fetch/body deadline, `redirect: "error"` and `cache: "no-store"`. Other addresses
|
|
184
|
+
pass through unchanged. An optional `fetch` supplies the underlying transport.
|
|
185
|
+
Existing Supabase clients are not automatically retrofitted, and custom
|
|
186
|
+
transports must honor redirect policy to prevent redirect dispatch.
|
|
187
|
+
|
|
188
|
+
Task Management reads, lists, cancellation and retry automatically limit
|
|
189
|
+
fetch/body waiting to 15 seconds and response bodies to 1 MiB before JSON
|
|
190
|
+
parsing. They require JSON/UTF-8, reject redirects and disable caching.
|
|
191
|
+
Access-token resolution has a separate 15-second deadline, followed by the
|
|
192
|
+
15-second fetch/body deadline. Invalid tokens or resolver failures throw
|
|
193
|
+
`SupaCloudTaskAuthenticationError` with `TASK_AUTH_INVALID`; timeouts use
|
|
194
|
+
`TASK_AUTH_TIMEOUT`. Both have `mutationMayHaveApplied: false`, and a late token
|
|
195
|
+
cannot dispatch the task request. A custom resolver's background work cannot
|
|
196
|
+
be forcibly stopped. Function invocation via `tasks.submit()` is separate.
|
|
197
|
+
Invalid reads throw `SupaCloudTaskResponseError` with `TASK_READ_INVALID`.
|
|
198
|
+
An unconfirmed cancel/retry response uses `TASK_CANCEL_UNCONFIRMED` or
|
|
199
|
+
`TASK_RETRY_UNCONFIRMED` and `mutationMayHaveApplied: true`: read the task state
|
|
200
|
+
before deciding whether to retry. The SDK does not automatically replay those
|
|
201
|
+
mutations. Explicit JSON 4xx errors retain their `SupaCloudApiError` status/body.
|
|
202
|
+
All Task Management records, submission receipts and Realtime snapshots require
|
|
203
|
+
`project_ref` exactly matching the configured project. A missing, conflicting
|
|
204
|
+
or malformed marker rejects the response, including an entire mixed-project
|
|
205
|
+
list. Legacy records without the marker are no longer accepted. This check
|
|
206
|
+
does not replace server authorization. Invalid submission receipts are
|
|
207
|
+
unconfirmed; invalid Realtime events call `onError` without updating or ending
|
|
208
|
+
the subscription.
|
|
209
|
+
`SupaCloudTaskDetail.project_ref` is a required string in the public type,
|
|
210
|
+
matching the decoder's project validation. Consumers constructing task
|
|
211
|
+
details themselves must now supply this field.
|
|
212
|
+
Task list filters are validated before authentication. Limits must be positive
|
|
213
|
+
safe integers; status/task-type filters use a nonempty string or nonempty array
|
|
214
|
+
of strings, not comma-separated strings. Empty, padded, control-bearing values,
|
|
215
|
+
accessors and unknown filter keys are rejected. `listDlq(limit)` uses the regular
|
|
216
|
+
task list with `dlq=true` so the requested limit is forwarded to the route that
|
|
217
|
+
supports it; its default remains 100.
|
|
141
218
|
|
|
142
219
|
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.
|
|
143
220
|
|
|
@@ -175,63 +252,158 @@ The current package focuses on:
|
|
|
175
252
|
- `auth.oauthServer.getJwks`
|
|
176
253
|
- `auth.oauthServer.buildAuthorizeUrl`
|
|
177
254
|
- `auth.oauthClients.list/create/get/update/delete/regenerateSecret`
|
|
178
|
-
- `supauth.provision`
|
|
179
|
-
- `supauth.reconcile`
|
|
180
|
-
- `supauth.rollback`
|
|
181
|
-
- `supauth.getClientConfig`
|
|
182
|
-
- `supauth.verify`
|
|
183
255
|
- `commands.submit`
|
|
184
256
|
- `commands.get`
|
|
185
257
|
- `artifacts.register`
|
|
186
258
|
- `artifacts.get`
|
|
187
259
|
- `artifacts.link`
|
|
188
260
|
|
|
189
|
-
|
|
261
|
+
## Command Status
|
|
262
|
+
|
|
263
|
+
`commands.submit` and `commands.get` share a runtime-validated status contract:
|
|
264
|
+
`kind: "submission"` means accepted work, with `execution: null`; `kind: "execution"`
|
|
265
|
+
includes the durable execution receipt. Workflow status remains a separate field.
|
|
266
|
+
A completed workflow by itself never proves that an external business effect
|
|
267
|
+
occurred. Use `workflows.get(commandId)` for the full workflow details.
|
|
268
|
+
|
|
269
|
+
`commands.get(commandId)` also accepts a `CommandLookup` object for direct
|
|
270
|
+
execution lookup. The lookup may identify a command by `commandId`, or provide
|
|
271
|
+
the `{ tenantId, actorId, command, operationId }` reference used by the command
|
|
272
|
+
store. The returned `commandId` is the global dispatch/workflow ID.
|
|
273
|
+
These RPCs remain service-role-only and are not browser authorization boundaries.
|
|
274
|
+
|
|
275
|
+
For submitted work, supply verified `tenantId` and `actorId` on submission, then
|
|
276
|
+
bind the claimed execute step with `createPostgresCommandStore(database, { submission })`.
|
|
277
|
+
The executor preserves the submitted ID and atomically completes or advances the
|
|
278
|
+
same Workflow; it does not create a second command. See
|
|
279
|
+
[migration and worker wiring](../../docs/command-workflow-convergence.md).
|
|
190
280
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
281
|
+
This is a breaking SDK return-shape change: old top-level `idempotent`, target and
|
|
282
|
+
full-workflow fields are no longer the public command status contract. Identical
|
|
283
|
+
submission replay still deduplicates in SQL. Legacy low-level SQL snapshot/submit
|
|
284
|
+
functions retain their stored submission data; older records are not reclassified
|
|
285
|
+
as confirmed executions.
|
|
286
|
+
|
|
287
|
+
## Typed Task Results
|
|
288
|
+
|
|
289
|
+
Task details and submission receipts default to `unknown` for the result payload.
|
|
290
|
+
Use an explicit runtime decoder when the application wants a trusted result type;
|
|
291
|
+
the decoder runs against a bounded JSON snapshot returned by the platform.
|
|
195
292
|
|
|
196
293
|
```ts
|
|
197
|
-
type
|
|
294
|
+
type Invoice = { id: string; total: number };
|
|
198
295
|
|
|
199
|
-
|
|
200
|
-
if (
|
|
201
|
-
throw new Error("Invalid invoice
|
|
296
|
+
function decodeInvoice(value: unknown): Invoice {
|
|
297
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
298
|
+
throw new Error("Invalid invoice");
|
|
202
299
|
}
|
|
203
|
-
const
|
|
204
|
-
if (typeof
|
|
205
|
-
throw new Error("Invalid invoice
|
|
300
|
+
const record = value as Record<string, unknown>;
|
|
301
|
+
if (typeof record.id !== "string" || typeof record.total !== "number") {
|
|
302
|
+
throw new Error("Invalid invoice");
|
|
206
303
|
}
|
|
207
|
-
return {
|
|
208
|
-
}
|
|
304
|
+
return { id: record.id, total: record.total };
|
|
305
|
+
}
|
|
209
306
|
|
|
210
|
-
const receipt = await
|
|
211
|
-
"
|
|
212
|
-
|
|
213
|
-
{ body: {
|
|
307
|
+
const receipt = await client.tasks.submitTyped(
|
|
308
|
+
"generate-invoice",
|
|
309
|
+
decodeInvoice,
|
|
310
|
+
{ body: { orderId } },
|
|
214
311
|
);
|
|
215
|
-
const
|
|
216
|
-
|
|
312
|
+
const completed = await receipt.wait();
|
|
313
|
+
if (!completed.result) throw new Error("Invoice result is not available");
|
|
314
|
+
const invoiceId: string = completed.result.id;
|
|
217
315
|
```
|
|
218
316
|
|
|
219
|
-
|
|
220
|
-
`
|
|
221
|
-
|
|
222
|
-
`
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
317
|
+
`getTyped`, `listTyped`, `listDlqTyped`, `waitTyped`, `cancelTyped`,
|
|
318
|
+
`retryTyped` and `subscribeTyped` use the same decoder contract. A decoder is
|
|
319
|
+
required before a typed read starts; decoder failure throws a redacted
|
|
320
|
+
`SupaCloudTaskDecoderError` (`TASK_RESULT_INVALID`). For `cancel` and `retry`,
|
|
321
|
+
that error remains outcome-uncertain because the server mutation may already
|
|
322
|
+
have committed. The SDK never retries or replays an unconfirmed mutation.
|
|
323
|
+
|
|
324
|
+
## OAuth Client Management
|
|
325
|
+
|
|
326
|
+
`auth.oauthClients` calls SupaCloud Management API, not GoTrue directly. It
|
|
327
|
+
validates client fields, response status and requested client identity before
|
|
328
|
+
returning data. Public clients cannot carry secrets; confidential creation and
|
|
329
|
+
secret rotation return a required `client_secret`. Save that one-time result
|
|
330
|
+
securely rather than expecting subsequent reads to return it.
|
|
331
|
+
|
|
332
|
+
Each operation accepts a final `{ signal, timeoutMs }` argument. The default
|
|
333
|
+
deadline is 15 seconds and covers credential resolution, the request and its
|
|
334
|
+
response body. Requests reject redirects and are not retried automatically.
|
|
335
|
+
`SupaCloudOAuthClientError` extends `SupaCloudApiError` and exposes
|
|
336
|
+
`mutationMayHaveApplied` for uncertain writes. Cancellation does not undo a
|
|
337
|
+
request that the server has already received.
|
|
338
|
+
|
|
339
|
+
Console integrations can use the standalone client with an existing
|
|
340
|
+
authenticated, same-origin request function:
|
|
341
|
+
|
|
342
|
+
```ts
|
|
343
|
+
import { SupaCloudOAuthClientsClient } from "@supacloud/js";
|
|
344
|
+
|
|
345
|
+
const clients = new SupaCloudOAuthClientsClient({
|
|
346
|
+
projectRef,
|
|
347
|
+
managementApiUrl: "",
|
|
348
|
+
sessionRequest: authenticatedRequest,
|
|
349
|
+
});
|
|
350
|
+
const result = await clients.list({ signal });
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
This explicit session mode accepts only a relative Management URL and never
|
|
354
|
+
adds a bearer token. The supplied transport remains responsible for session
|
|
355
|
+
handling. Recreate the client when the project changes and cancel old requests.
|
|
356
|
+
|
|
357
|
+
Deploy the updated Management OAuth adapter before this client: list responses
|
|
358
|
+
must contain a `clients` array, creation returns HTTP 201, and deletion returns
|
|
359
|
+
an empty HTTP 204. GoTrue's raw `{}` empty list is normalized by Management.
|
|
360
|
+
Canonical UUID client IDs and supported authentication/grant enums are now
|
|
361
|
+
enforced; malformed legacy responses no longer pass through.
|
|
226
362
|
|
|
227
363
|
## Status Subscription
|
|
228
364
|
|
|
229
|
-
`tasks.subscribe()`
|
|
365
|
+
`tasks.subscribe()` polls the Management API by default. The platform does not
|
|
366
|
+
provision a `public.tasks` Realtime table. Internal background task mirrors
|
|
367
|
+
are execution evidence, not a complete lifecycle feed.
|
|
368
|
+
|
|
369
|
+
Applications with their own published task-state table can explicitly opt in:
|
|
230
370
|
|
|
231
|
-
|
|
232
|
-
|
|
371
|
+
```ts
|
|
372
|
+
const subscription = task.subscribe({
|
|
373
|
+
realtime: { schema: "public", table: "task_updates" },
|
|
374
|
+
onUpdate(snapshot) {
|
|
375
|
+
console.log(snapshot.status);
|
|
376
|
+
},
|
|
377
|
+
});
|
|
378
|
+
```
|
|
233
379
|
|
|
234
|
-
|
|
380
|
+
That table must expose the platform task `id`, `project_ref` and `status`,
|
|
381
|
+
and have appropriate publication, SELECT privileges and row-level policies.
|
|
382
|
+
The SDK does not create the table or grant access. Schema/table names must be
|
|
383
|
+
simple identifiers of at most 63 characters. Explicit Realtime subscriptions
|
|
384
|
+
retain Management polling on connection failure and periodic reconciliation.
|
|
385
|
+
An omitted source no longer guesses `public.tasks`; malformed source options
|
|
386
|
+
are rejected before opening a channel.
|
|
387
|
+
Polling intervals must be integer milliseconds from 1 through 2,147,483,647.
|
|
388
|
+
Realtime connection timeout and reconciliation intervals accept the same
|
|
389
|
+
range plus 0 to disable that timer. Invalid explicit values, including null,
|
|
390
|
+
are rejected before authentication or subscription work. The computed default
|
|
391
|
+
reconciliation interval is capped at the same maximum.
|
|
392
|
+
Subscription options are captured at creation. Callbacks must be functions,
|
|
393
|
+
`stopOnTerminal` must be boolean, and unknown keys or accessor properties are
|
|
394
|
+
rejected. Changing the original options or callbacks afterward does not
|
|
395
|
+
reconfigure an active subscription.
|
|
396
|
+
Thrown or rejected callback failures close the subscription. Failures from
|
|
397
|
+
update/state callbacks are reported through `onError` when available;
|
|
398
|
+
failure of `onError` itself is not reported recursively. Channel-removal
|
|
399
|
+
errors are handled without an unhandled rejection. Already-running application
|
|
400
|
+
callback work cannot be forcibly stopped.
|
|
401
|
+
`tasks.get(taskId, signal)` accepts an optional abort signal, and `wait()` now
|
|
402
|
+
forwards its signal through credential resolution and each HTTP read.
|
|
403
|
+
Cancellation preserves the caller's abort reason. Closing a subscription
|
|
404
|
+
aborts its reads and suppresses their late errors; a late credential cannot
|
|
405
|
+
dispatch a cancelled read. Noncooperative provider/transport work may continue
|
|
406
|
+
internally despite cancellation.
|
|
235
407
|
|
|
236
408
|
## Task Lifecycle Webhook
|
|
237
409
|
|
|
@@ -266,6 +438,37 @@ If `secret` is set, verify `X-SupaCloud-Signature: sha256=<hmac>` against the ra
|
|
|
266
438
|
|
|
267
439
|
## Queue Helpers
|
|
268
440
|
|
|
441
|
+
**Breaking change:** queue message `id` and `msg_id` are canonical positive
|
|
442
|
+
int64 decimal strings. Mutation inputs accept those strings or positive safe
|
|
443
|
+
JavaScript integers. Invalid, rounded or noncanonical IDs are rejected, never
|
|
444
|
+
coerced to `0`. A large ID that has already been parsed as an unsafe JavaScript
|
|
445
|
+
number cannot be recovered: the SDK rejects it. End-to-end large-ID delivery
|
|
446
|
+
therefore requires a transport that preserves such IDs as decimal strings.
|
|
447
|
+
Deploy the matching Management backend for full-int64 visibility, archive and
|
|
448
|
+
delete paths. Its PGMQ message queries return IDs as SQL text and its mutation
|
|
449
|
+
parameters bind decimal strings as `bigint`. Older backends still reject large
|
|
450
|
+
IDs. Management send/batch/message responses now also expose string IDs.
|
|
451
|
+
|
|
452
|
+
Queue messages use `SupaCloudQueueJson`, including arrays, scalars and null.
|
|
453
|
+
Sending captures an independent JSON snapshot before asynchronous transport;
|
|
454
|
+
cycles, undefined, accessors, nonfinite numbers and non-JSON objects are rejected.
|
|
455
|
+
Snapshots are bounded to 64 nesting levels, 10,000 values and 1,048,576 total
|
|
456
|
+
key/string characters. These are decoded-value budgets, not raw HTTP body limits.
|
|
457
|
+
Callers must narrow a received payload before using it as an object.
|
|
458
|
+
|
|
459
|
+
Single-send and batch receipts must have exactly the expected distinct IDs.
|
|
460
|
+
Only actual empty row arrays mean no messages; malformed reads are errors.
|
|
461
|
+
Archive/delete require literal boolean receipts, preserving `false`.
|
|
462
|
+
Seconds/counts must be bounded integers and conflicting option aliases fail.
|
|
463
|
+
`receive()` accepts only a count of one.
|
|
464
|
+
|
|
465
|
+
Queue RPCs explicitly disable underlying retries. Their transport and receipt
|
|
466
|
+
failures use `SupaCloudQueueError.mutationMayHaveApplied`; reads alter visibility
|
|
467
|
+
and `pop()` deletes, so those operations can also have uncertain outcomes.
|
|
468
|
+
Do not automatically repeat an uncertain operation. This does not add deadlines
|
|
469
|
+
or cancellation to the supplied Supabase transport, or certify a live PGMQ
|
|
470
|
+
transaction. Management extensions retain their separate transport limitations.
|
|
471
|
+
|
|
269
472
|
The core message operations use the official Supabase Queues API exposed through `pgmq_public`:
|
|
270
473
|
|
|
271
474
|
- `pgmq_public.send(queue_name, message, sleep_seconds)`
|
|
@@ -330,33 +533,60 @@ Queue settings:
|
|
|
330
533
|
|
|
331
534
|
Management extension conflicts are surfaced as `SupaCloudApiError` with `status`, `code`, and `responseBody`, so callers do not need to parse raw `fetch` responses.
|
|
332
535
|
|
|
333
|
-
##
|
|
536
|
+
## Durable Workflows
|
|
334
537
|
|
|
335
|
-
`
|
|
336
|
-
`kind: "submission"` means accepted work, with `execution: null`; `kind: "execution"`
|
|
337
|
-
includes the durable execution receipt. Workflow status remains a separate field.
|
|
338
|
-
A completed workflow by itself never proves that an external business effect
|
|
339
|
-
occurred. Use `workflows.get(commandId)` for the full workflow details.
|
|
538
|
+
`supacloud.workflows` coordinates code-defined, linear steps on the project's PostgreSQL and PGMQ runtime. Every workflow RPC is restricted to `service_role`; create this client only in a trusted worker or server process.
|
|
340
539
|
|
|
341
|
-
|
|
342
|
-
for direct executions. The returned commandId is the global dispatch/workflow ID.
|
|
343
|
-
These RPCs remain service-role-only and are not browser authorization boundaries.
|
|
540
|
+
Install the response guard when creating the Supabase client:
|
|
344
541
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
same Workflow; it does not create a second command. See
|
|
349
|
-
[migration and worker wiring](../../docs/command-workflow-convergence.md).
|
|
542
|
+
```ts
|
|
543
|
+
import { createClient } from "@supabase/supabase-js";
|
|
544
|
+
import { createSupaCloudClient, createSupaCloudWorkflowFetch } from "@supacloud/js";
|
|
350
545
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
546
|
+
const supabase = createClient("https://api.example.com", "service-role-key", {
|
|
547
|
+
global: { fetch: createSupaCloudWorkflowFetch() },
|
|
548
|
+
auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
|
|
549
|
+
});
|
|
550
|
+
const supacloud = createSupaCloudClient({
|
|
551
|
+
supabase,
|
|
552
|
+
managementApiUrl: "https://management.example.com",
|
|
553
|
+
projectRef: "project-ref",
|
|
554
|
+
});
|
|
555
|
+
```
|
|
356
556
|
|
|
357
|
-
|
|
557
|
+
The guard bounds workflow responses to 1 MiB before JSON parsing, validates
|
|
558
|
+
UTF-8, rejects redirects, and limits fetch/body waiting to 15 seconds. Other
|
|
559
|
+
Supabase requests pass through unchanged. Supply `{ fetch: yourFetch }` to
|
|
560
|
+
compose with an existing transport. An already-created Supabase client is not
|
|
561
|
+
retrofitted automatically: without this guard, workflow decoders and wait
|
|
562
|
+
limits still apply, but preparse byte limits do not. Large existing workflow
|
|
563
|
+
snapshots may exceed this new byte budget.
|
|
358
564
|
|
|
359
|
-
|
|
565
|
+
Command RPCs need their own guard. Compose both guards when using commands and
|
|
566
|
+
workflows with the same Supabase client:
|
|
567
|
+
|
|
568
|
+
```ts
|
|
569
|
+
import { createSupaCloudCommandFetch, createSupaCloudWorkflowFetch } from "@supacloud/js";
|
|
570
|
+
|
|
571
|
+
const guardedFetch = createSupaCloudCommandFetch({
|
|
572
|
+
fetch: createSupaCloudWorkflowFetch(),
|
|
573
|
+
});
|
|
574
|
+
// Pass guardedFetch as global.fetch when constructing the Supabase client.
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
The command guard covers `supacloud_command_submit` and `supacloud_command_get`
|
|
578
|
+
with the same 1 MiB and 15-second limits. A rejected submission response may
|
|
579
|
+
already have committed. Explicit replay must retain the original command
|
|
580
|
+
identity and payload; a receipt that remains over the byte cap will still be
|
|
581
|
+
rejected even when its replay is idempotent.
|
|
582
|
+
|
|
583
|
+
For artifact receipts, wrap the combined transport with
|
|
584
|
+
`createSupaCloudArtifactFetch({ fetch: guardedFetch })` and install that result
|
|
585
|
+
as `global.fetch` when creating the Supabase client. Import this helper from
|
|
586
|
+
`@supacloud/js`. It applies the same byte, UTF-8, redirect and wait limits to
|
|
587
|
+
artifact register/get/link RPCs only; Storage file transfers remain unchanged.
|
|
588
|
+
Registration and link errors caused by rejected responses may follow a
|
|
589
|
+
successful database commit. Existing Supabase clients are not modified.
|
|
360
590
|
|
|
361
591
|
```ts
|
|
362
592
|
const runId = crypto.randomUUID();
|
|
@@ -386,7 +616,7 @@ if (claim?.status === "claimed") {
|
|
|
386
616
|
}
|
|
387
617
|
```
|
|
388
618
|
|
|
389
|
-
Available operations are `start`, `claim`, `advance`, `complete`, `retry`, `fail`, `cancel`, `get`, and `events`.
|
|
619
|
+
Available operations are `start`, `claim`, `advance`, `complete`, `retry`, `fail`, `cancel`, `get`, and `events`. No workflow RPC is automatically retried. Identity-bound mutations support explicit replay of the same request after a lost response; changed replay payloads can fail with a conflict. `claim` is not idempotent: repeating it after a lost response can acquire another message or attempt. An unconfirmed mutation, including a response rejected by the guard, may already have committed. Install the current workflow SQL before using the retry SDK, which requires the persisted `retryReceipt` response field. See the repository's `docs/durable-workflows.md` for execution, security, and DBOS design boundaries.
|
|
390
620
|
|
|
391
621
|
Message IDs, queue message IDs, event cursors, and run row versions are decimal strings, preserving the full PostgreSQL `bigint` range. Retry a `claim` that returns SQLSTATE `40001`; the contended queue lease is rolled back before that error is returned.
|
|
392
622
|
|
|
@@ -394,4 +624,43 @@ Message IDs, queue message IDs, event cursors, and run row versions are decimal
|
|
|
394
624
|
|
|
395
625
|
`client.auth.oauthServer` is the SupaCloud SDK surface for project-scoped OAuth 2.1 / OIDC migration and discovery.
|
|
396
626
|
|
|
397
|
-
It does **not** take a global account scope.
|
|
627
|
+
It does **not** take a global account scope. Management requests carry the
|
|
628
|
+
Management API Bearer token; public Discovery/JWKS requests carry no management
|
|
629
|
+
headers or cookies. All requests reject redirects.
|
|
630
|
+
|
|
631
|
+
Status is a validated configuration contract, with `state_source:
|
|
632
|
+
"configuration"` and `runtime_verified: false`. Organization is required but
|
|
633
|
+
nullable. Signing algorithm, key ID, readiness and migration status must agree.
|
|
634
|
+
Deploy the matching Management backend before this SDK; legacy incomplete
|
|
635
|
+
status responses are rejected.
|
|
636
|
+
|
|
637
|
+
Each operation has a 15-second total deadline and each JSON body is limited to
|
|
638
|
+
64 KiB with strict UTF-8 decoding. Public endpoints must match the configured
|
|
639
|
+
issuer. Discovery returns declared issuer/endpoints and supported response,
|
|
640
|
+
subject and signing lists. JWKS returns validated ES256/RS256 public keys only,
|
|
641
|
+
requiring the configured key ID and algorithm. Unknown fields are stripped.
|
|
642
|
+
The SDK rereads configuration after public reads and rejects observed changes.
|
|
643
|
+
This is not full OIDC conformance, transactional configuration locking, key
|
|
644
|
+
material attestation or a network destination allowlist. The Management
|
|
645
|
+
configuration remains the trust anchor; HTTP is accepted for local runtimes.
|
|
646
|
+
|
|
647
|
+
Migration validates submitted values against the receipt, preserves the
|
|
648
|
+
configured signing identity, and never retries a write automatically.
|
|
649
|
+
`SupaCloudOAuthServerError.mutationMayHaveApplied` signals uncertain writes;
|
|
650
|
+
the recognized dependent-refresh failure code remains an error, not success.
|
|
651
|
+
Authorization URL inputs are validated and captured before asynchronous work.
|
|
652
|
+
The URL builder does not generate state, nonce or PKCE values, or validate the
|
|
653
|
+
subsequent authorization callback.
|
|
654
|
+
|
|
655
|
+
## Consumer Type Verification
|
|
656
|
+
|
|
657
|
+
`bun run typecheck:consumer` generates JavaScript and declarations from the
|
|
658
|
+
current SDK source into a temporary package and compiles the NodeNext consumer
|
|
659
|
+
against that package's real export map. It uses the installed Supabase peer
|
|
660
|
+
dependency and Node declarations, with `skipLibCheck: false`,
|
|
661
|
+
`exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`. Existing `dist`
|
|
662
|
+
files in the SDK checkout are neither read nor overwritten.
|
|
663
|
+
|
|
664
|
+
Dependency declaration failures remain failures. This check does not replace
|
|
665
|
+
Supabase declarations with stubs, patch ambient browser types or certify live
|
|
666
|
+
authentication behavior.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import { type FetchTransport } from "./bounded-rpc-fetch.js";
|
|
2
|
+
export interface SupaCloudArtifactFetchOptions {
|
|
3
|
+
fetch?: FetchTransport;
|
|
4
|
+
}
|
|
5
|
+
/** Bound artifact RPC receipts without imposing limits on Storage file transfers. */
|
|
6
|
+
export declare function createSupaCloudArtifactFetch(options?: SupaCloudArtifactFetchOptions): FetchTransport;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { SupaCloudApiError } from "./api-error.js";
|
|
2
|
+
import type { SupaCloudArtifact, SupaCloudArtifactLinkRequest } from "./artifacts.js";
|
|
3
|
+
export declare class SupaCloudArtifactLinkError extends SupaCloudApiError {
|
|
4
|
+
readonly mutationMayHaveApplied: boolean;
|
|
5
|
+
constructor(mutationMayHaveApplied?: boolean);
|
|
6
|
+
}
|
|
7
|
+
export declare function captureArtifactLink(value: unknown): Required<SupaCloudArtifactLinkRequest>;
|
|
8
|
+
export declare function decodeArtifactLink(value: unknown, request: Required<SupaCloudArtifactLinkRequest>): SupaCloudArtifact;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { SupaCloudApiError } from "./api-error.js";
|
|
2
|
+
import type { SupaCloudArtifact } from "./artifacts.js";
|
|
3
|
+
export declare class SupaCloudArtifactReadError extends SupaCloudApiError {
|
|
4
|
+
readonly mutationMayHaveApplied = false;
|
|
5
|
+
constructor(input?: boolean);
|
|
6
|
+
}
|
|
7
|
+
export declare function captureArtifactId(value: unknown): string;
|
|
8
|
+
export declare function artifactText(value: unknown, min?: number, max?: number): string;
|
|
9
|
+
export declare function artifactKey(value: unknown): string;
|
|
10
|
+
export declare function artifactTimestampMicros(value: string): bigint;
|
|
11
|
+
export declare function artifactSize(value: unknown): string;
|
|
12
|
+
export declare function artifactPath(value: unknown): string;
|
|
13
|
+
export declare function decodeArtifactRead(value: unknown, artifactId: string, allowIdempotent?: boolean): SupaCloudArtifact | null;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { SupaCloudApiError } from "./api-error.js";
|
|
2
|
+
import type { SupaCloudArtifact, SupaCloudArtifactRegisterRequest } from "./artifacts.js";
|
|
3
|
+
export declare class SupaCloudArtifactRegisterError extends SupaCloudApiError {
|
|
4
|
+
readonly mutationMayHaveApplied: boolean;
|
|
5
|
+
constructor(mutationMayHaveApplied?: boolean);
|
|
6
|
+
}
|
|
7
|
+
type CapturedRegister = Omit<Required<SupaCloudArtifactRegisterRequest>, "sizeBytes" | "retentionUntil" | "createdBy"> & {
|
|
8
|
+
sizeBytes: string;
|
|
9
|
+
retentionUntil: string | null;
|
|
10
|
+
createdBy: string | null;
|
|
11
|
+
};
|
|
12
|
+
export declare function captureArtifactRegister(value: unknown): CapturedRegister;
|
|
13
|
+
export declare function decodeArtifactRegister(value: unknown, request: CapturedRegister): SupaCloudArtifact;
|
|
14
|
+
export {};
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
import type { SupabaseClient } from "@supabase/supabase-js";
|
|
2
|
+
export declare function invokeArtifactRpc(supabase: SupabaseClient, name: "supacloud_artifact_get" | "supacloud_artifact_register" | "supacloud_artifact_link", request: object, failure: () => Error): Promise<unknown>;
|
package/dist/artifacts.d.ts
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
1
|
import type { SupabaseClient } from "@supabase/supabase-js";
|
|
2
|
+
export { SupaCloudArtifactReadError } from "./artifact-read.js";
|
|
3
|
+
export { SupaCloudArtifactRegisterError } from "./artifact-register.js";
|
|
4
|
+
export { SupaCloudArtifactLinkError } from "./artifact-link.js";
|
|
2
5
|
export type SupaCloudArtifactJson = Record<string, unknown>;
|
|
3
6
|
export interface SupaCloudArtifactParent {
|
|
4
7
|
artifactId: string;
|