@supacloud/js 0.25.0 → 0.30.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
@@ -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
- - Realtime subscription with polling fallback
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 provisioning and runtime verification helpers
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
93
+ ## SupAuth Management Compatibility
88
94
 
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.
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.
90
103
 
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
- });
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`.
98
111
 
99
- await supacloud.supauth.provision({
100
- authDomain: "auth.example.com",
101
- apiDomain: "api.example.com",
102
- adminMode: "sso",
103
- storageBuckets: [{ id: "avatars", public: true }],
104
- });
105
-
106
- await supacloud.supauth.reconcile({ dryRun: false });
107
-
108
- const health = await supacloud.supauth.verify();
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,25 +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
 
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).
280
+
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.
292
+
293
+ ```ts
294
+ type Invoice = { id: string; total: number };
295
+
296
+ function decodeInvoice(value: unknown): Invoice {
297
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
298
+ throw new Error("Invalid invoice");
299
+ }
300
+ const record = value as Record<string, unknown>;
301
+ if (typeof record.id !== "string" || typeof record.total !== "number") {
302
+ throw new Error("Invalid invoice");
303
+ }
304
+ return { id: record.id, total: record.total };
305
+ }
306
+
307
+ const receipt = await client.tasks.submitTyped(
308
+ "generate-invoice",
309
+ decodeInvoice,
310
+ { body: { orderId } },
311
+ );
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;
315
+ ```
316
+
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.
362
+
189
363
  ## Status Subscription
190
364
 
191
- `tasks.subscribe()` uses this strategy:
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.
192
368
 
193
- 1. try `postgres_changes` on `public.tasks`
194
- 2. if Realtime is unavailable, fall back to polling the management API
369
+ Applications with their own published task-state table can explicitly opt in:
370
+
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
+ ```
195
379
 
196
- This lets apps degrade gracefully when websocket or channel health is transient.
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.
197
407
 
198
408
  ## Task Lifecycle Webhook
199
409
 
@@ -228,6 +438,37 @@ If `secret` is set, verify `X-SupaCloud-Signature: sha256=<hmac>` against the ra
228
438
 
229
439
  ## Queue Helpers
230
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
+
231
472
  The core message operations use the official Supabase Queues API exposed through `pgmq_public`:
232
473
 
233
474
  - `pgmq_public.send(queue_name, message, sleep_seconds)`
@@ -296,6 +537,57 @@ Management extension conflicts are surfaced as `SupaCloudApiError` with `status`
296
537
 
297
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.
298
539
 
540
+ Install the response guard when creating the Supabase client:
541
+
542
+ ```ts
543
+ import { createClient } from "@supabase/supabase-js";
544
+ import { createSupaCloudClient, createSupaCloudWorkflowFetch } from "@supacloud/js";
545
+
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
+ ```
556
+
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.
564
+
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.
590
+
299
591
  ```ts
300
592
  const runId = crypto.randomUUID();
301
593
 
@@ -324,7 +616,7 @@ if (claim?.status === "claimed") {
324
616
  }
325
617
  ```
326
618
 
327
- Available operations are `start`, `claim`, `advance`, `complete`, `retry`, `fail`, `cancel`, `get`, and `events`. Mutating calls are safe to replay with the same request after a lost response; a different replay payload fails with an idempotency conflict. See the repository's `docs/durable-workflows.md` for execution, security, and DBOS design boundaries.
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.
328
620
 
329
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.
330
622
 
@@ -332,4 +624,43 @@ Message IDs, queue message IDs, event cursors, and run row versions are decimal
332
624
 
333
625
  `client.auth.oauthServer` is the SupaCloud SDK surface for project-scoped OAuth 2.1 / OIDC migration and discovery.
334
626
 
335
- It does **not** take a global account scope. The SDK always sends the normal Management API Bearer token and lets the server enforce project ownership.
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
+ export declare class SupaCloudApiError extends Error {
2
+ readonly status: number;
3
+ readonly code: string | null;
4
+ readonly responseBody: unknown;
5
+ constructor(message: string, status: number, responseBody: unknown);
6
+ }
@@ -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>;
@@ -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;
@@ -1,3 +1,4 @@
1
+ type FetchTransport = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
1
2
  export type SupaCloudOAuthFetchOptions = {
2
3
  /**
3
4
  * Public OAuth client identifier registered with SupAuth. Leave empty for a
@@ -11,7 +12,7 @@ export type SupaCloudOAuthFetchOptions = {
11
12
  */
12
13
  tokenEndpoint?: string;
13
14
  /** Injectable transport for tests or runtimes with a custom fetch. */
14
- fetch?: typeof fetch;
15
+ fetch?: FetchTransport;
15
16
  };
16
17
  /**
17
18
  * Adapts Supabase Auth's built-in refresh request to SupAuth's OAuth token
@@ -22,4 +23,5 @@ export type SupaCloudOAuthFetchOptions = {
22
23
  * global: { fetch: createSupaCloudOAuthFetch({ clientId }) },
23
24
  * });
24
25
  */
25
- export declare function createSupaCloudOAuthFetch(options?: SupaCloudOAuthFetchOptions): typeof fetch;
26
+ export declare function createSupaCloudOAuthFetch(options?: SupaCloudOAuthFetchOptions): FetchTransport;
27
+ export {};
@@ -0,0 +1,2 @@
1
+ export type FetchTransport = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
2
+ export declare function createBoundedRpcFetch(path: RegExp, failure: () => Error, fetchImpl?: FetchTransport): FetchTransport;
@@ -0,0 +1,6 @@
1
+ import { type FetchTransport } from "./bounded-rpc-fetch.js";
2
+ export interface SupaCloudCommandFetchOptions {
3
+ fetch?: FetchTransport;
4
+ }
5
+ /** Install in Supabase's global.fetch to bound command responses before JSON parsing. */
6
+ export declare function createSupaCloudCommandFetch(options?: SupaCloudCommandFetchOptions): FetchTransport;