@supacloud/js 0.39.0 → 0.41.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/PROCEDURES.md +60 -15
- package/QUERY.md +13 -5
- package/README.md +1 -0
- package/dist/index.cjs +279 -63
- package/dist/index.d.cts +36 -4
- package/dist/index.d.mts +36 -4
- package/dist/index.mjs +279 -63
- package/dist/procedure-client.d.cts +11 -1
- package/dist/procedure-client.d.mts +11 -1
- package/dist/procedure-error.d.cts +14 -2
- package/dist/procedure-error.d.mts +14 -2
- package/dist/procedure-runtime.d.cts +9 -0
- package/dist/procedure-runtime.d.mts +9 -0
- package/dist/query.cjs +78 -4
- package/dist/query.d.cts +4 -4
- package/dist/query.d.mts +4 -4
- package/dist/query.mjs +76 -4
- package/dist/queue-rpc.d.cts +5 -0
- package/dist/queue-rpc.d.mts +5 -0
- package/package.json +2 -1
package/PROCEDURES.md
CHANGED
|
@@ -28,6 +28,9 @@ callable route methods remain compatible, so migration can be incremental.
|
|
|
28
28
|
## Migration
|
|
29
29
|
|
|
30
30
|
Upgrade the compiler and SDK together and regenerate the application `client.ts`.
|
|
31
|
+
The facade checks the generated `__supacloudClient.hooksVersion` capability and
|
|
32
|
+
rejects older generated files with a regeneration message. It returns the
|
|
33
|
+
generated client itself, without a Proxy.
|
|
31
34
|
Existing `createApiClient({ fetch: createSupaCloudApiFetch(...) })` initialization
|
|
32
35
|
remains supported and retains the original error classes. Switch initialization
|
|
33
36
|
to the facade when ready; successful values, route decoder overloads and
|
|
@@ -35,12 +38,30 @@ to the facade when ready; successful values, route decoder overloads and
|
|
|
35
38
|
calls also work through the facade. The facade normalizes failures from routes,
|
|
36
39
|
procedures and `api.request`; `buildRouteUrl` stays synchronous.
|
|
37
40
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
header and argument conventions. Extra
|
|
42
|
-
|
|
43
|
-
|
|
41
|
+
All `.mutate` calls with required idempotency must supply an execution key,
|
|
42
|
+
including direct generated procedures. An `idempotency-key` request header
|
|
43
|
+
cannot satisfy this requirement. Legacy callable routes retain their old
|
|
44
|
+
header and argument conventions. Extra settings are inferred from the generated
|
|
45
|
+
factory's own configuration:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
const api = createSupaCloudProcedureClient({
|
|
49
|
+
supabase,
|
|
50
|
+
functionName: "app-api",
|
|
51
|
+
generated: createApiClient,
|
|
52
|
+
generatedConfig: {
|
|
53
|
+
normalize: false,
|
|
54
|
+
headers: () => ({ "x-tenant": tenantId }),
|
|
55
|
+
interceptors: [businessInterceptor],
|
|
56
|
+
},
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`fetch`, `errorMapper` and `procedureExecutionValidator` remain facade-owned,
|
|
61
|
+
including when configuration is supplied as an existing variable. Other
|
|
62
|
+
generated settings keep their original types and behavior. Custom factory
|
|
63
|
+
wrappers must forward these hooks; do not replace them or introduce retrying
|
|
64
|
+
interceptors. Supabase still owns authentication headers.
|
|
44
65
|
|
|
45
66
|
The same procedures work with the optional
|
|
46
67
|
[`@supacloud/js/query`](./QUERY.md) adapter and ordinary Svelte/React Query bindings.
|
|
@@ -50,21 +71,22 @@ The facade does not create a cache or import a framework runtime.
|
|
|
50
71
|
|
|
51
72
|
`SupaCloudProcedureError` exposes:
|
|
52
73
|
|
|
53
|
-
- `code`:
|
|
74
|
+
- `code`: the closed `SupaCloudProcedureErrorCode` classification
|
|
54
75
|
- `status`: HTTP status, or `null` when no response was received
|
|
55
76
|
- `requestId`: bounded `x-request-id` (or the JSON body's `requestId`), or `null`
|
|
77
|
+
- `upstreamCode`: bounded domain/server code (or an unknown future generated code), or `null`
|
|
56
78
|
- `details`: the full JSON error body when available, including any domain `code`
|
|
57
79
|
- `response`: the original HTTP `Response` when available
|
|
58
80
|
- `cause`: the original Supabase `FunctionsHttpError`, fetch error or client error
|
|
59
81
|
|
|
60
82
|
```ts
|
|
61
83
|
import { FunctionsHttpError } from "@supabase/supabase-js";
|
|
62
|
-
import {
|
|
84
|
+
import { isSupaCloudProcedureError } from "@supacloud/js";
|
|
63
85
|
|
|
64
86
|
try {
|
|
65
87
|
await api.cases.detail.query({ params: { id: "case-1" } });
|
|
66
88
|
} catch (error) {
|
|
67
|
-
if (!(error
|
|
89
|
+
if (!isSupaCloudProcedureError(error)) throw error;
|
|
68
90
|
console.error(error.code, error.status, error.requestId);
|
|
69
91
|
if (error.cause instanceof FunctionsHttpError) {
|
|
70
92
|
// Identical to error.response; its body has not been consumed by the facade.
|
|
@@ -76,16 +98,31 @@ try {
|
|
|
76
98
|
HTTP failures use `API_HTTP_ERROR`; JSON/schema failures use
|
|
77
99
|
`API_RESPONSE_INVALID` and undeclared success statuses use
|
|
78
100
|
`API_RESPONSE_UNDECLARED`. Network and relay failures use
|
|
79
|
-
`SUPACLOUD_TRANSPORT_ERROR` and `SUPACLOUD_FUNCTIONS_ERROR
|
|
80
|
-
use `SUPACLOUD_CLIENT_ERROR
|
|
81
|
-
|
|
101
|
+
`SUPACLOUD_TRANSPORT_ERROR` and `SUPACLOUD_FUNCTIONS_ERROR`. Unknown future generated
|
|
102
|
+
error codes use `SUPACLOUD_CLIENT_ERROR` with the original code in `upstreamCode`.
|
|
103
|
+
Invalid idempotency uses `SUPACLOUD_EXECUTION_ERROR`.
|
|
104
|
+
Unknown application, header-provider, interceptor and custom-decoder exceptions
|
|
105
|
+
remain unchanged, including `SyntaxError` and `TypeError`. Native `AbortError`
|
|
106
|
+
cancellation remains unchanged.
|
|
107
|
+
|
|
108
|
+
Use `isSupaCloudProcedureError` when catching errors across separately bundled
|
|
109
|
+
SDK entrypoints: their constructors need not have the same identity. This guard
|
|
110
|
+
checks the error's shape and known code, not its provenance; it is not an
|
|
111
|
+
authorization check or an error deserializer. Cross-realm errors are not
|
|
112
|
+
supported. `isSupaCloudProcedureHttpError` additionally narrows to a numeric
|
|
113
|
+
status and a `Response` (including contract failures on 2xx responses);
|
|
114
|
+
`isSupaCloudProcedureTransportError` narrows to network/relay codes.
|
|
82
115
|
|
|
83
116
|
Error-body inspection reads only a clone of JSON failures, at most 64 KiB and
|
|
84
117
|
250 ms. Non-JSON, oversized, malformed or stalled bodies leave `details`
|
|
85
118
|
undefined without hiding the HTTP failure. Treat details as untrusted data.
|
|
86
|
-
`details`, `response` and `cause` are excluded from JSON serialization.
|
|
87
|
-
|
|
88
|
-
|
|
119
|
+
`details`, `upstreamCode`, `response` and `cause` are excluded from JSON serialization.
|
|
120
|
+
Generated clients decode buffered responses from a clone when possible, including
|
|
121
|
+
successful responses that fail schema validation. If cloning is unavailable,
|
|
122
|
+
decoding falls back to the original body. Successful live streams are not cloned.
|
|
123
|
+
This preserves the response received by the generated client; Supabase may have
|
|
124
|
+
already decoded its own successful response before adapting it to Fetch.
|
|
125
|
+
If Supabase fails before returning a
|
|
89
126
|
response (including malformed success JSON), the original error is kept as
|
|
90
127
|
`cause`, but no HTTP status is fabricated.
|
|
91
128
|
|
|
@@ -98,3 +135,11 @@ client's typed-value behavior instead of being reclassified as exceptions.
|
|
|
98
135
|
Reuse the key only for the same logical operation. A failed or cancelled request
|
|
99
136
|
does not prove that a write rolled back; resolve uncertain outcomes before retrying.
|
|
100
137
|
The facade does not implement server-side idempotency or durable command receipts.
|
|
138
|
+
|
|
139
|
+
The facade's generated execution hook and the Query adapter share the same
|
|
140
|
+
validator. Standalone generated procedures enforce the same execution rules with
|
|
141
|
+
native `TypeError` failures, without adding an SDK runtime dependency. An
|
|
142
|
+
`idempotency-key` in request input, global headers or interceptors never replaces
|
|
143
|
+
the execution key. The captured execution key wins over header overrides.
|
|
144
|
+
Existing header-only procedure calls must move the key to the execution argument
|
|
145
|
+
when regenerating; callable route methods retain their original conventions.
|
package/QUERY.md
CHANGED
|
@@ -18,6 +18,9 @@ The adapter targets Query Core `^5.104.1`; the integration tests use Svelte Quer
|
|
|
18
18
|
and the adapter has no runtime dependency on Supabase, Svelte or Query Core.
|
|
19
19
|
|
|
20
20
|
Regenerate `client.ts` with a compiler that emits `__supacloudProcedure` metadata.
|
|
21
|
+
Procedures must be callable asynchronous functions; metadata-only objects and
|
|
22
|
+
synchronous functions are rejected by the type contract. Invalid runtime shapes
|
|
23
|
+
are rejected before creating query or mutation options.
|
|
21
24
|
Earlier generated clients remain usable directly, but cannot use these options
|
|
22
25
|
until regenerated. Existing route calls, response validation, interceptors,
|
|
23
26
|
`.query()` and `.mutate()` argument conventions are unchanged.
|
|
@@ -146,11 +149,16 @@ Each invocation supplies `{ input, execution }`. A required command idempotency
|
|
|
146
149
|
key is required both by TypeScript and at runtime. It belongs to the logical
|
|
147
150
|
operation, not to the component or mutation-options factory. Reuse it only when
|
|
148
151
|
reconciling/retrying the same operation, never for a different write.
|
|
149
|
-
The facade
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
152
|
+
The adapter and facade share execution validation. Missing, empty, oversized and
|
|
153
|
+
invalid-character keys reject with `SupaCloudProcedureError` and
|
|
154
|
+
`SUPACLOUD_EXECUTION_ERROR` before dispatch, including when adapting direct
|
|
155
|
+
generated clients or custom procedures. An input `idempotency-key` header cannot
|
|
156
|
+
replace the per-invocation execution key. Standalone generated procedures enforce
|
|
157
|
+
the same execution rules with native `TypeError` failures; legacy callable routes
|
|
158
|
+
retain their original header conventions.
|
|
159
|
+
|
|
160
|
+
Use `isSupaCloudProcedureError` from `@supacloud/js` rather than relying on
|
|
161
|
+
constructor identity when catching errors from separately bundled entrypoints.
|
|
154
162
|
|
|
155
163
|
Mutations set `retry: false`, including when QueryClient defaults enable retry.
|
|
156
164
|
An unknown outcome is not permission to retry; first resolve the server outcome.
|
package/README.md
CHANGED
package/dist/index.cjs
CHANGED
|
@@ -69,6 +69,9 @@ __export(exports_src, {
|
|
|
69
69
|
SupaCloudWorkflowRetryError: () => SupaCloudWorkflowRetryError,
|
|
70
70
|
SupaCloudWorkflowStartError: () => SupaCloudWorkflowStartError,
|
|
71
71
|
SupaCloudWorkflowsClient: () => SupaCloudWorkflowsClient,
|
|
72
|
+
createProcedureClient: () => createProcedureClient,
|
|
73
|
+
createQueryAdapter: () => createQueryAdapter,
|
|
74
|
+
createQueryKey: () => createQueryKey,
|
|
72
75
|
createSupaCloudApiFetch: () => createSupaCloudApiFetch,
|
|
73
76
|
createSupaCloudArtifactFetch: () => createSupaCloudArtifactFetch,
|
|
74
77
|
createSupaCloudClient: () => createSupaCloudClient,
|
|
@@ -76,10 +79,15 @@ __export(exports_src, {
|
|
|
76
79
|
createSupaCloudOAuthFetch: () => createSupaCloudOAuthFetch,
|
|
77
80
|
createSupaCloudProcedureClient: () => createSupaCloudProcedureClient,
|
|
78
81
|
createSupaCloudTaskFetch: () => createSupaCloudTaskFetch,
|
|
79
|
-
createSupaCloudWorkflowFetch: () => createSupaCloudWorkflowFetch
|
|
82
|
+
createSupaCloudWorkflowFetch: () => createSupaCloudWorkflowFetch,
|
|
83
|
+
invalidateByTags: () => invalidateByTags,
|
|
84
|
+
isSupaCloudProcedureError: () => isSupaCloudProcedureError,
|
|
85
|
+
isSupaCloudProcedureErrorCode: () => isSupaCloudProcedureErrorCode,
|
|
86
|
+
isSupaCloudProcedureHttpError: () => isSupaCloudProcedureHttpError,
|
|
87
|
+
isSupaCloudProcedureTransportError: () => isSupaCloudProcedureTransportError
|
|
80
88
|
});
|
|
81
89
|
module.exports = __toCommonJS(exports_src);
|
|
82
|
-
var
|
|
90
|
+
var import_supabase_js2 = require("@supabase/supabase-js");
|
|
83
91
|
|
|
84
92
|
// src/workflow-rpc.ts
|
|
85
93
|
function invokeWorkflowMutation(supabase, functionName, request, unconfirmed) {
|
|
@@ -2388,6 +2396,142 @@ class SupaCloudOAuthServerClient {
|
|
|
2388
2396
|
});
|
|
2389
2397
|
}
|
|
2390
2398
|
}
|
|
2399
|
+
|
|
2400
|
+
// node_modules/@supacloud/query/dist/index.js
|
|
2401
|
+
async function invalidateByTags(queryClient, tags, keyPrefix) {
|
|
2402
|
+
const targetTags = Array.isArray(tags) ? tags : [tags];
|
|
2403
|
+
if (targetTags.length === 0)
|
|
2404
|
+
return;
|
|
2405
|
+
await queryClient.invalidateQueries({
|
|
2406
|
+
...keyPrefix ? { queryKey: keyPrefix } : {},
|
|
2407
|
+
predicate: (query) => {
|
|
2408
|
+
const queryTags = query.meta?.tags;
|
|
2409
|
+
if (!Array.isArray(queryTags))
|
|
2410
|
+
return false;
|
|
2411
|
+
return targetTags.some((tag) => queryTags.includes(tag));
|
|
2412
|
+
}
|
|
2413
|
+
});
|
|
2414
|
+
}
|
|
2415
|
+
function snapshot(value, ancestors = new Set) {
|
|
2416
|
+
if (value === null || value === undefined || typeof value === "string" || typeof value === "boolean")
|
|
2417
|
+
return value;
|
|
2418
|
+
if (typeof value === "number" && Number.isFinite(value))
|
|
2419
|
+
return value;
|
|
2420
|
+
if (typeof value !== "object" || ancestors.has(value))
|
|
2421
|
+
throw new TypeError("Input must be acyclic JSON data");
|
|
2422
|
+
const prototype = Object.getPrototypeOf(value);
|
|
2423
|
+
if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
|
|
2424
|
+
throw new TypeError("Input must be JSON data");
|
|
2425
|
+
ancestors.add(value);
|
|
2426
|
+
try {
|
|
2427
|
+
if (Array.isArray(value))
|
|
2428
|
+
return Object.freeze(value.map((item) => snapshot(item, ancestors) ?? null));
|
|
2429
|
+
return Object.freeze(Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, snapshot(item, ancestors)])));
|
|
2430
|
+
} finally {
|
|
2431
|
+
ancestors.delete(value);
|
|
2432
|
+
}
|
|
2433
|
+
}
|
|
2434
|
+
function identityPrefix(prefix) {
|
|
2435
|
+
if (!Array.isArray(prefix) || prefix.length === 0 || prefix.some((part) => typeof part !== "string" || !part.trim())) {
|
|
2436
|
+
throw new TypeError("keyPrefix must contain nonempty identity values");
|
|
2437
|
+
}
|
|
2438
|
+
return Object.freeze(["supacloud", ...prefix]);
|
|
2439
|
+
}
|
|
2440
|
+
function createQueryKey(operationId, input, keyPrefix) {
|
|
2441
|
+
return Object.freeze([...identityPrefix(keyPrefix), operationId, snapshot(input)]);
|
|
2442
|
+
}
|
|
2443
|
+
function createProcedureClient(client) {
|
|
2444
|
+
const candidate = Object.hasOwn(client, "procedureClient") ? client.procedureClient : undefined;
|
|
2445
|
+
return candidate !== undefined ? candidate : client;
|
|
2446
|
+
}
|
|
2447
|
+
function call(procedure, input, execution) {
|
|
2448
|
+
if (!execution || typeof execution !== "object" || Array.isArray(execution))
|
|
2449
|
+
throw new TypeError("Invalid execution options");
|
|
2450
|
+
const { signal, idempotencyKey } = execution;
|
|
2451
|
+
if (signal !== undefined && !(signal instanceof AbortSignal))
|
|
2452
|
+
throw new TypeError("Invalid AbortSignal");
|
|
2453
|
+
if (procedure.__supacloudProcedure.idempotency === "required" && idempotencyKey === undefined || idempotencyKey !== undefined && (typeof idempotencyKey !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(idempotencyKey))) {
|
|
2454
|
+
throw new TypeError("A valid idempotencyKey is required");
|
|
2455
|
+
}
|
|
2456
|
+
const captured = Object.freeze({ ...execution });
|
|
2457
|
+
const invoke = procedure;
|
|
2458
|
+
return new Promise((resolve, reject) => {
|
|
2459
|
+
const abort = () => reject(signal?.reason ?? new DOMException("Procedure cancelled", "AbortError"));
|
|
2460
|
+
if (signal?.aborted) {
|
|
2461
|
+
abort();
|
|
2462
|
+
return;
|
|
2463
|
+
}
|
|
2464
|
+
signal?.addEventListener("abort", abort, { once: true });
|
|
2465
|
+
Promise.resolve().then(() => {
|
|
2466
|
+
signal?.throwIfAborted();
|
|
2467
|
+
return invoke(input, captured);
|
|
2468
|
+
}).then(resolve, reject).finally(() => signal?.removeEventListener("abort", abort));
|
|
2469
|
+
});
|
|
2470
|
+
}
|
|
2471
|
+
function createQueryAdapter(client, options) {
|
|
2472
|
+
const prefix = identityPrefix(options.keyPrefix);
|
|
2473
|
+
const source = createProcedureClient(client);
|
|
2474
|
+
const result = Object.create(null);
|
|
2475
|
+
for (const [controller, handlers] of Object.entries(source)) {
|
|
2476
|
+
if (controller === "invalidateByTags")
|
|
2477
|
+
throw new TypeError("Reserved controller name: invalidateByTags");
|
|
2478
|
+
const mapped = Object.create(null);
|
|
2479
|
+
result[controller] = mapped;
|
|
2480
|
+
for (const [name, member] of Object.entries(handlers)) {
|
|
2481
|
+
const procedure = "query" in member ? member.query : member.mutate;
|
|
2482
|
+
if (procedure === undefined)
|
|
2483
|
+
throw new TypeError("Expected a generated procedure");
|
|
2484
|
+
const metadata = procedure.__supacloudProcedure;
|
|
2485
|
+
if (typeof procedure !== "function" || !metadata || metadata.kind !== ("query" in member ? "query" : "mutation") || typeof metadata.key !== "string" || typeof metadata.method !== "string" || typeof metadata.path !== "string" || !["none", "required"].includes(metadata.idempotency)) {
|
|
2486
|
+
throw new TypeError("Expected a generated procedure");
|
|
2487
|
+
}
|
|
2488
|
+
const key = Object.freeze([...prefix, metadata.kind, metadata.method, metadata.path]);
|
|
2489
|
+
if ("query" in member) {
|
|
2490
|
+
const proc = member.query;
|
|
2491
|
+
mapped[name] = {
|
|
2492
|
+
queryKey: (...args) => args.length ? Object.freeze([...key, snapshot(args[0] ?? {})]) : key,
|
|
2493
|
+
queryOptions: (input, opts) => {
|
|
2494
|
+
const captured = snapshot(input ?? {});
|
|
2495
|
+
return {
|
|
2496
|
+
queryKey: Object.freeze([...key, captured]),
|
|
2497
|
+
queryFn: async ({ signal }) => await call(proc, captured, { signal }) ?? null,
|
|
2498
|
+
meta: { ...opts?.meta, tags: Object.freeze([...opts?.tags ?? []]) }
|
|
2499
|
+
};
|
|
2500
|
+
}
|
|
2501
|
+
};
|
|
2502
|
+
} else {
|
|
2503
|
+
const proc = member.mutate;
|
|
2504
|
+
if (proc === undefined)
|
|
2505
|
+
throw new TypeError("Expected a generated mutation");
|
|
2506
|
+
mapped[name] = {
|
|
2507
|
+
mutationKey: () => key,
|
|
2508
|
+
mutationOptions: (opts) => ({
|
|
2509
|
+
mutationKey: key,
|
|
2510
|
+
retry: false,
|
|
2511
|
+
mutationFn: async (variables) => call(proc, variables.input, variables.execution === undefined ? {} : variables.execution),
|
|
2512
|
+
meta: { ...opts?.meta },
|
|
2513
|
+
onSuccess: async (data, variables, context) => {
|
|
2514
|
+
const target = opts?.queryClient ?? options.queryClient;
|
|
2515
|
+
if (opts?.invalidateTags?.length && target === undefined)
|
|
2516
|
+
throw new Error("No QueryClient provided for invalidation");
|
|
2517
|
+
if (target !== undefined && opts?.invalidateTags?.length)
|
|
2518
|
+
await invalidateByTags(target, opts.invalidateTags, prefix);
|
|
2519
|
+
return opts?.onSuccess?.(data, variables, context);
|
|
2520
|
+
}
|
|
2521
|
+
})
|
|
2522
|
+
};
|
|
2523
|
+
}
|
|
2524
|
+
}
|
|
2525
|
+
}
|
|
2526
|
+
return Object.assign(result, {
|
|
2527
|
+
invalidateByTags: (tags, clientForInvalidation) => {
|
|
2528
|
+
const target = clientForInvalidation ?? options.queryClient;
|
|
2529
|
+
if (target === undefined)
|
|
2530
|
+
throw new Error("No QueryClient provided for invalidateByTags");
|
|
2531
|
+
return invalidateByTags(target, tags, prefix);
|
|
2532
|
+
}
|
|
2533
|
+
});
|
|
2534
|
+
}
|
|
2391
2535
|
// src/auth-fetch.ts
|
|
2392
2536
|
function requestMethod(input, init) {
|
|
2393
2537
|
return (init?.method || (input instanceof Request ? input.method : "GET")).toUpperCase();
|
|
@@ -2594,7 +2738,22 @@ function createSupaCloudApiFetch(options) {
|
|
|
2594
2738
|
return responseFromData(invocation.data, invocation.response instanceof Response ? invocation.response : undefined);
|
|
2595
2739
|
};
|
|
2596
2740
|
}
|
|
2741
|
+
// src/procedure-client.ts
|
|
2742
|
+
var import_supabase_js = require("@supabase/supabase-js");
|
|
2743
|
+
|
|
2597
2744
|
// src/procedure-error.ts
|
|
2745
|
+
var procedureErrorCodes = new Set([
|
|
2746
|
+
"API_HTTP_ERROR",
|
|
2747
|
+
"API_RESPONSE_INVALID",
|
|
2748
|
+
"API_RESPONSE_UNDECLARED",
|
|
2749
|
+
"SUPACLOUD_EXECUTION_ERROR",
|
|
2750
|
+
"SUPACLOUD_FUNCTIONS_ERROR",
|
|
2751
|
+
"SUPACLOUD_TRANSPORT_ERROR",
|
|
2752
|
+
"SUPACLOUD_CLIENT_ERROR"
|
|
2753
|
+
]);
|
|
2754
|
+
function isSupaCloudProcedureErrorCode(value) {
|
|
2755
|
+
return typeof value === "string" && procedureErrorCodes.has(value);
|
|
2756
|
+
}
|
|
2598
2757
|
function procedureErrorIdentifier(value) {
|
|
2599
2758
|
return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
|
|
2600
2759
|
}
|
|
@@ -2603,6 +2762,7 @@ class SupaCloudProcedureError extends Error {
|
|
|
2603
2762
|
code;
|
|
2604
2763
|
status;
|
|
2605
2764
|
requestId;
|
|
2765
|
+
upstreamCode;
|
|
2606
2766
|
details;
|
|
2607
2767
|
response;
|
|
2608
2768
|
cause;
|
|
@@ -2612,23 +2772,62 @@ class SupaCloudProcedureError extends Error {
|
|
|
2612
2772
|
this.code = options.code;
|
|
2613
2773
|
this.status = options.status ?? null;
|
|
2614
2774
|
this.requestId = procedureErrorIdentifier(options.requestId) ?? null;
|
|
2775
|
+
this.upstreamCode = procedureErrorIdentifier(options.upstreamCode) ?? null;
|
|
2615
2776
|
this.details = options.details;
|
|
2616
2777
|
this.response = options.response;
|
|
2617
2778
|
this.cause = options.cause;
|
|
2618
2779
|
Object.defineProperty(this, "response", { enumerable: false });
|
|
2619
2780
|
Object.defineProperty(this, "cause", { enumerable: false });
|
|
2781
|
+
Object.defineProperty(this, "upstreamCode", { enumerable: false });
|
|
2620
2782
|
Object.defineProperty(this, "details", { enumerable: false });
|
|
2621
2783
|
}
|
|
2622
2784
|
}
|
|
2785
|
+
function isSupaCloudProcedureError(value) {
|
|
2786
|
+
return value instanceof Error && value.name === "SupaCloudProcedureError" && "code" in value && isSupaCloudProcedureErrorCode(value.code) && "status" in value && (value.status === null || typeof value.status === "number" && Number.isInteger(value.status) && value.status >= 0 && value.status <= 599) && "requestId" in value && (value.requestId === null || procedureErrorIdentifier(value.requestId) !== undefined) && "upstreamCode" in value && (value.upstreamCode === null || procedureErrorIdentifier(value.upstreamCode) !== undefined) && "response" in value && (value.response === undefined || value.response instanceof Response) && "details" in value && "cause" in value;
|
|
2787
|
+
}
|
|
2788
|
+
function isSupaCloudProcedureHttpError(value) {
|
|
2789
|
+
return isSupaCloudProcedureError(value) && typeof value.status === "number" && value.response instanceof Response;
|
|
2790
|
+
}
|
|
2791
|
+
function isSupaCloudProcedureTransportError(value) {
|
|
2792
|
+
return isSupaCloudProcedureError(value) && (value.code === "SUPACLOUD_FUNCTIONS_ERROR" || value.code === "SUPACLOUD_TRANSPORT_ERROR");
|
|
2793
|
+
}
|
|
2623
2794
|
|
|
2624
|
-
// src/procedure-
|
|
2795
|
+
// src/procedure-runtime.ts
|
|
2796
|
+
var idempotencyKeyPattern = /^[A-Za-z0-9._:-]{1,512}$/;
|
|
2797
|
+
function isValidSupaCloudIdempotencyKey(value) {
|
|
2798
|
+
return typeof value === "string" && idempotencyKeyPattern.test(value);
|
|
2799
|
+
}
|
|
2625
2800
|
function isRecord5(value) {
|
|
2626
2801
|
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
2627
2802
|
}
|
|
2803
|
+
function validateSupaCloudProcedureExecution(metadata, execution) {
|
|
2804
|
+
if (execution !== undefined && !isRecord5(execution)) {
|
|
2805
|
+
throw new SupaCloudProcedureError("Procedure execution must be an options object", {
|
|
2806
|
+
code: "SUPACLOUD_EXECUTION_ERROR"
|
|
2807
|
+
});
|
|
2808
|
+
}
|
|
2809
|
+
const signal = isRecord5(execution) ? execution.signal : undefined;
|
|
2810
|
+
if (signal !== undefined && (typeof AbortSignal === "undefined" || !(signal instanceof AbortSignal))) {
|
|
2811
|
+
throw new SupaCloudProcedureError("Procedure signal must be an AbortSignal", {
|
|
2812
|
+
code: "SUPACLOUD_EXECUTION_ERROR"
|
|
2813
|
+
});
|
|
2814
|
+
}
|
|
2815
|
+
const key = isRecord5(execution) ? execution.idempotencyKey : undefined;
|
|
2816
|
+
if (metadata.idempotency === "required" && key === undefined || key !== undefined && !isValidSupaCloudIdempotencyKey(key)) {
|
|
2817
|
+
throw new SupaCloudProcedureError("This procedure requires a valid idempotencyKey", {
|
|
2818
|
+
code: "SUPACLOUD_EXECUTION_ERROR"
|
|
2819
|
+
});
|
|
2820
|
+
}
|
|
2821
|
+
}
|
|
2822
|
+
|
|
2823
|
+
// src/procedure-client.ts
|
|
2824
|
+
function isRecord6(value) {
|
|
2825
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
2826
|
+
}
|
|
2628
2827
|
function asGeneratedError(value) {
|
|
2629
|
-
if (!
|
|
2828
|
+
if (!isRecord6(value) || !(value instanceof Error))
|
|
2630
2829
|
return;
|
|
2631
|
-
if (value.name !== "ApiClientError" || typeof value.code !== "string" || typeof value.status !== "number")
|
|
2830
|
+
if (value.name !== "ApiClientError" || typeof value.code !== "string" || typeof value.status !== "number" || !Number.isInteger(value.status) || value.status < 0 || value.status > 599 || typeof value.method !== "string" || typeof value.path !== "string" || !("response" in value) || value.response !== undefined && !(value.response instanceof Response))
|
|
2632
2831
|
return;
|
|
2633
2832
|
return { code: value.code, status: value.status, requestId: value.requestId, response: value.response };
|
|
2634
2833
|
}
|
|
@@ -2660,7 +2859,7 @@ async function readErrorBody(response) {
|
|
|
2660
2859
|
return;
|
|
2661
2860
|
if (chunk.done) {
|
|
2662
2861
|
const body = JSON.parse(text + decoder.decode());
|
|
2663
|
-
return
|
|
2862
|
+
return isRecord6(body) ? body : undefined;
|
|
2664
2863
|
}
|
|
2665
2864
|
bytes += chunk.value.byteLength;
|
|
2666
2865
|
if (bytes > maxBytes)
|
|
@@ -2684,79 +2883,39 @@ async function readErrorBody(response) {
|
|
|
2684
2883
|
}
|
|
2685
2884
|
}
|
|
2686
2885
|
function errorName(error) {
|
|
2687
|
-
return
|
|
2886
|
+
return isRecord6(error) && typeof error.name === "string" ? error.name : undefined;
|
|
2688
2887
|
}
|
|
2689
2888
|
async function normalizeProcedureError(error, transport = false) {
|
|
2690
|
-
if (error
|
|
2889
|
+
if (isSupaCloudProcedureError(error))
|
|
2890
|
+
return error;
|
|
2891
|
+
const generated = asGeneratedError(error);
|
|
2892
|
+
const knownTransportFailure = error instanceof import_supabase_js.FunctionsFetchError || error instanceof import_supabase_js.FunctionsRelayError || error instanceof import_supabase_js.FunctionsHttpError;
|
|
2893
|
+
if (generated === undefined && !knownTransportFailure && !transport)
|
|
2691
2894
|
return error;
|
|
2692
2895
|
if (errorName(error) === "AbortError")
|
|
2693
2896
|
return error;
|
|
2694
|
-
if (errorName(error) === "FunctionsFetchError" &&
|
|
2897
|
+
if (errorName(error) === "FunctionsFetchError" && isRecord6(error) && errorName(error.context) === "AbortError")
|
|
2695
2898
|
return error.context;
|
|
2696
|
-
const
|
|
2697
|
-
const response = generated?.response instanceof Response ? generated.response :
|
|
2899
|
+
const responseDecodeFailure = transport && error instanceof SyntaxError;
|
|
2900
|
+
const response = generated?.response instanceof Response ? generated.response : isRecord6(error) && error.context instanceof Response ? error.context : undefined;
|
|
2698
2901
|
const original = response === undefined ? undefined : getSupaCloudApiFetchError(response);
|
|
2699
2902
|
const cause = original ?? error;
|
|
2700
2903
|
const responseBody = await readErrorBody(response);
|
|
2701
2904
|
const name = errorName(cause);
|
|
2702
2905
|
const message = error instanceof Error ? error.message : "SupaCloud procedure failed";
|
|
2703
|
-
const fallback = name === "FunctionsFetchError" ? "SUPACLOUD_TRANSPORT_ERROR" : name === "FunctionsRelayError" ? "SUPACLOUD_FUNCTIONS_ERROR" : name === "FunctionsHttpError" ? "API_HTTP_ERROR" :
|
|
2704
|
-
const code = name
|
|
2906
|
+
const fallback = name === "FunctionsFetchError" ? "SUPACLOUD_TRANSPORT_ERROR" : name === "FunctionsRelayError" ? "SUPACLOUD_FUNCTIONS_ERROR" : name === "FunctionsHttpError" ? "API_HTTP_ERROR" : responseDecodeFailure ? "API_RESPONSE_INVALID" : transport ? "SUPACLOUD_TRANSPORT_ERROR" : "SUPACLOUD_CLIENT_ERROR";
|
|
2907
|
+
const code = name !== "FunctionsRelayError" && generated?.code && isSupaCloudProcedureErrorCode(generated.code) ? generated.code : fallback;
|
|
2908
|
+
const upstreamCode = procedureErrorIdentifier(responseBody?.code) ?? (generated && !isSupaCloudProcedureErrorCode(generated.code) ? procedureErrorIdentifier(generated.code) : undefined);
|
|
2705
2909
|
return new SupaCloudProcedureError(message, {
|
|
2706
2910
|
code,
|
|
2707
2911
|
status: generated?.status ?? response?.status ?? null,
|
|
2708
2912
|
requestId: procedureErrorIdentifier(generated?.requestId) ?? procedureErrorIdentifier(response?.headers.get("x-request-id")) ?? procedureErrorIdentifier(responseBody?.requestId) ?? null,
|
|
2913
|
+
upstreamCode: upstreamCode ?? null,
|
|
2709
2914
|
details: responseBody,
|
|
2710
2915
|
response,
|
|
2711
2916
|
cause
|
|
2712
2917
|
});
|
|
2713
2918
|
}
|
|
2714
|
-
function validateProcedureExecution(procedure, args) {
|
|
2715
|
-
const metadata = Reflect.get(procedure, "__supacloudProcedure");
|
|
2716
|
-
if (!isRecord5(metadata))
|
|
2717
|
-
return;
|
|
2718
|
-
const [first, second] = args;
|
|
2719
|
-
const execution = second ?? (isRecord5(first) && (Object.hasOwn(first, "idempotencyKey") || Object.hasOwn(first, "signal")) ? first : undefined);
|
|
2720
|
-
const key = isRecord5(execution) ? execution.idempotencyKey : undefined;
|
|
2721
|
-
if (metadata.idempotency === "required" && key === undefined || key !== undefined && (typeof key !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(key))) {
|
|
2722
|
-
throw new SupaCloudProcedureError("This procedure requires a valid idempotencyKey", {
|
|
2723
|
-
code: "SUPACLOUD_EXECUTION_ERROR"
|
|
2724
|
-
});
|
|
2725
|
-
}
|
|
2726
|
-
}
|
|
2727
|
-
function wrapGeneratedClient(client) {
|
|
2728
|
-
const cache = new WeakMap;
|
|
2729
|
-
const wrap = (value, level) => {
|
|
2730
|
-
const cached = cache.get(value);
|
|
2731
|
-
if (cached !== undefined)
|
|
2732
|
-
return cached;
|
|
2733
|
-
const proxy = new Proxy(value, {
|
|
2734
|
-
async apply(current, thisArg, args) {
|
|
2735
|
-
try {
|
|
2736
|
-
validateProcedureExecution(current, args);
|
|
2737
|
-
return await Reflect.apply(current, thisArg, args);
|
|
2738
|
-
} catch (failure) {
|
|
2739
|
-
throw await normalizeProcedureError(failure);
|
|
2740
|
-
}
|
|
2741
|
-
},
|
|
2742
|
-
get(current, key, receiver) {
|
|
2743
|
-
const member = Reflect.get(current, key, receiver);
|
|
2744
|
-
if (!Object.hasOwn(current, key))
|
|
2745
|
-
return member;
|
|
2746
|
-
if (typeof member === "function" && (level === "controller" || level === "client" && key === "request" || level === "call" && (key === "query" || key === "mutate"))) {
|
|
2747
|
-
return wrap(member, "call");
|
|
2748
|
-
}
|
|
2749
|
-
if (level === "client" && isRecord5(member) && Object.getPrototypeOf(member) === Object.prototype) {
|
|
2750
|
-
return wrap(member, "controller");
|
|
2751
|
-
}
|
|
2752
|
-
return member;
|
|
2753
|
-
}
|
|
2754
|
-
});
|
|
2755
|
-
cache.set(value, proxy);
|
|
2756
|
-
return proxy;
|
|
2757
|
-
};
|
|
2758
|
-
return wrap(client, "client");
|
|
2759
|
-
}
|
|
2760
2919
|
function createSupaCloudProcedureClient(options) {
|
|
2761
2920
|
const transport = createSupaCloudApiFetch({
|
|
2762
2921
|
supabase: options.supabase,
|
|
@@ -2773,7 +2932,18 @@ function createSupaCloudProcedureClient(options) {
|
|
|
2773
2932
|
throw await normalizeProcedureError(error, true);
|
|
2774
2933
|
}
|
|
2775
2934
|
};
|
|
2776
|
-
|
|
2935
|
+
const generatedConfig = {
|
|
2936
|
+
...options.generatedConfig ?? {},
|
|
2937
|
+
fetch: fetch2,
|
|
2938
|
+
errorMapper: normalizeProcedureError,
|
|
2939
|
+
procedureExecutionValidator: validateSupaCloudProcedureExecution
|
|
2940
|
+
};
|
|
2941
|
+
const client = options.generated(generatedConfig);
|
|
2942
|
+
const capabilities = Reflect.get(client, "__supacloudClient");
|
|
2943
|
+
if (!isRecord6(capabilities) || capabilities.hooksVersion !== 1) {
|
|
2944
|
+
throw new TypeError("Regenerate the application client to enable procedure error and execution hooks");
|
|
2945
|
+
}
|
|
2946
|
+
return client;
|
|
2777
2947
|
}
|
|
2778
2948
|
|
|
2779
2949
|
// src/index.ts
|
|
@@ -3491,11 +3661,11 @@ class SupaCloudTasksClient extends SupaCloudManagementClient {
|
|
|
3491
3661
|
const { data, error, response } = invocation;
|
|
3492
3662
|
const boundedHttpFailure = response instanceof Response && boundedTaskHttpFailures.delete(response);
|
|
3493
3663
|
if (error !== null && error !== undefined) {
|
|
3494
|
-
if (error instanceof
|
|
3664
|
+
if (error instanceof import_supabase_js2.FunctionsHttpError && response instanceof Response && error.context === response && !response.redirected && response.status >= 400 && response.status < 500) {
|
|
3495
3665
|
throw error;
|
|
3496
3666
|
}
|
|
3497
3667
|
if (boundedHttpFailure && response instanceof Response && !response.redirected && response.status >= 400 && response.status < 500 && matchesForeignTaskHttpError(error, response)) {
|
|
3498
|
-
throw new
|
|
3668
|
+
throw new import_supabase_js2.FunctionsHttpError(response);
|
|
3499
3669
|
}
|
|
3500
3670
|
if (response instanceof Response)
|
|
3501
3671
|
response.body?.cancel().catch(() => {});
|
|
@@ -3869,6 +4039,34 @@ class SupaCloudQueueClient extends SupaCloudManagementClient {
|
|
|
3869
4039
|
payload: captured
|
|
3870
4040
|
};
|
|
3871
4041
|
}
|
|
4042
|
+
async sendIdempotent(payload = {}, jobKey, options = {}) {
|
|
4043
|
+
const captured = queueJsonSnapshot(payload);
|
|
4044
|
+
if (typeof jobKey !== "string" || jobKey.trim() !== jobKey || !/^[A-Za-z0-9_.:@/-]{1,200}$/.test(jobKey)) {
|
|
4045
|
+
throw new SupaCloudQueueError(false, "QUEUE_JOB_KEY_INVALID");
|
|
4046
|
+
}
|
|
4047
|
+
const result = await this.rpc("send_idempotent", {
|
|
4048
|
+
queue_name: this.name,
|
|
4049
|
+
message: captured,
|
|
4050
|
+
p_job_key: jobKey,
|
|
4051
|
+
sleep_seconds: normalizeSecondsFromOptions(options)
|
|
4052
|
+
}, (value) => {
|
|
4053
|
+
if (!Array.isArray(value) || value.length !== 1 || !value[0] || Array.isArray(value[0]) || typeof value[0] !== "object") {
|
|
4054
|
+
throw new SupaCloudQueueError;
|
|
4055
|
+
}
|
|
4056
|
+
const row = value[0];
|
|
4057
|
+
if (typeof row.created !== "boolean")
|
|
4058
|
+
throw new SupaCloudQueueError;
|
|
4059
|
+
return { msgId: queueMessageId(row.msg_id), created: row.created === true };
|
|
4060
|
+
});
|
|
4061
|
+
return {
|
|
4062
|
+
id: result.msgId,
|
|
4063
|
+
msg_id: result.msgId,
|
|
4064
|
+
queue_name: this.name,
|
|
4065
|
+
status: result.created ? "pending" : "deduplicated",
|
|
4066
|
+
payload: captured,
|
|
4067
|
+
deduplicated: !result.created
|
|
4068
|
+
};
|
|
4069
|
+
}
|
|
3872
4070
|
async sendBatch(messages, options = {}) {
|
|
3873
4071
|
if (!Array.isArray(messages) || messages.length === 0 || messages.length > 1e4)
|
|
3874
4072
|
throw new SupaCloudQueueError;
|
|
@@ -3999,7 +4197,7 @@ function createSupaCloudClient(options) {
|
|
|
3999
4197
|
const workflows2 = new SupaCloudWorkflowsClient(options.supabase);
|
|
4000
4198
|
const commands2 = new SupaCloudCommandsClient(options.supabase);
|
|
4001
4199
|
const artifacts2 = new SupaCloudArtifactsClient(options.supabase);
|
|
4002
|
-
|
|
4200
|
+
const instance = {
|
|
4003
4201
|
supabase: options.supabase,
|
|
4004
4202
|
projectRef: normalized.projectRef,
|
|
4005
4203
|
managementApiUrl: normalized.managementApiUrl,
|
|
@@ -4017,4 +4215,22 @@ function createSupaCloudClient(options) {
|
|
|
4017
4215
|
invokeBackground: (functionName, submitOptions) => tasks.submit(functionName, submitOptions)
|
|
4018
4216
|
}
|
|
4019
4217
|
};
|
|
4218
|
+
function withClient(apiClient) {
|
|
4219
|
+
return {
|
|
4220
|
+
...instance,
|
|
4221
|
+
procedures: createProcedureClient(apiClient),
|
|
4222
|
+
queryAdapter: (adapterOptions) => createQueryAdapter(apiClient, adapterOptions),
|
|
4223
|
+
withClient
|
|
4224
|
+
};
|
|
4225
|
+
}
|
|
4226
|
+
return {
|
|
4227
|
+
...instance,
|
|
4228
|
+
procedures: options.apiClient === undefined ? undefined : createProcedureClient(options.apiClient),
|
|
4229
|
+
queryAdapter: (adapterOptions) => {
|
|
4230
|
+
if (options.apiClient === undefined)
|
|
4231
|
+
throw new Error("No procedure client attached");
|
|
4232
|
+
return createQueryAdapter(options.apiClient, adapterOptions);
|
|
4233
|
+
},
|
|
4234
|
+
withClient
|
|
4235
|
+
};
|
|
4020
4236
|
}
|