@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 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
- Facade `.mutate` calls with required idempotency must supply an execution key.
39
- Direct generated procedures may still satisfy the legacy runtime check with an
40
- explicit `idempotency-key` request header. Legacy callable routes retain their old
41
- header and argument conventions. Extra generated-client settings can still be applied with
42
- `generated: config => createApiClient({ ...config, normalize: false })`.
43
- Do not override `config.fetch` or introduce retrying interceptors in that factory.
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`: generated API or SupaCloud transport classification
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 { SupaCloudProcedureError } from "@supacloud/js";
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 instanceof SupaCloudProcedureError)) throw 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`; other client failures
80
- use `SUPACLOUD_CLIENT_ERROR`. Invalid idempotency uses `SUPACLOUD_EXECUTION_ERROR`.
81
- Native `AbortError` cancellation remains unchanged.
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
- Successful response bodies may already be consumed when schema validation fails;
88
- their status and headers remain available. If Supabase fails before returning a
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 validates execution keys; direct generated procedures retain their
150
- legacy header checks. With the facade, invalid mutation
151
- execution settings reject with `SupaCloudProcedureError` and
152
- `SUPACLOUD_EXECUTION_ERROR` before dispatch; direct generated clients retain their
153
- original validation errors.
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
@@ -71,6 +71,7 @@ const api = createSupaCloudProcedureClient({
71
71
  supabase,
72
72
  functionName: "app-api",
73
73
  generated: createApiClient,
74
+ generatedConfig: { normalize: false },
74
75
  });
75
76
 
76
77
  const detail = await api.cases.detail.query({ params: { id: "case-1" } });
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 import_supabase_js = require("@supabase/supabase-js");
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-client.ts
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 (!isRecord5(value))
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 isRecord5(body) ? body : undefined;
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 isRecord5(error) && typeof error.name === "string" ? error.name : undefined;
2886
+ return isRecord6(error) && typeof error.name === "string" ? error.name : undefined;
2688
2887
  }
2689
2888
  async function normalizeProcedureError(error, transport = false) {
2690
- if (error instanceof SupaCloudProcedureError)
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" && isRecord5(error) && errorName(error.context) === "AbortError")
2897
+ if (errorName(error) === "FunctionsFetchError" && isRecord6(error) && errorName(error.context) === "AbortError")
2695
2898
  return error.context;
2696
- const generated = asGeneratedError(error);
2697
- const response = generated?.response instanceof Response ? generated.response : isRecord5(error) && error.context instanceof Response ? error.context : undefined;
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" : error instanceof SyntaxError ? "API_RESPONSE_INVALID" : transport ? "SUPACLOUD_TRANSPORT_ERROR" : "SUPACLOUD_CLIENT_ERROR";
2704
- const code = name === "FunctionsRelayError" ? fallback : generated?.code ?? fallback;
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
- return wrapGeneratedClient(options.generated({ fetch: fetch2 }));
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 import_supabase_js.FunctionsHttpError && response instanceof Response && error.context === response && !response.redirected && response.status >= 400 && response.status < 500) {
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 import_supabase_js.FunctionsHttpError(response);
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
- return {
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
  }