@supacloud/js 0.39.0 → 0.39.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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
@@ -76,10 +76,14 @@ __export(exports_src, {
76
76
  createSupaCloudOAuthFetch: () => createSupaCloudOAuthFetch,
77
77
  createSupaCloudProcedureClient: () => createSupaCloudProcedureClient,
78
78
  createSupaCloudTaskFetch: () => createSupaCloudTaskFetch,
79
- createSupaCloudWorkflowFetch: () => createSupaCloudWorkflowFetch
79
+ createSupaCloudWorkflowFetch: () => createSupaCloudWorkflowFetch,
80
+ isSupaCloudProcedureError: () => isSupaCloudProcedureError,
81
+ isSupaCloudProcedureErrorCode: () => isSupaCloudProcedureErrorCode,
82
+ isSupaCloudProcedureHttpError: () => isSupaCloudProcedureHttpError,
83
+ isSupaCloudProcedureTransportError: () => isSupaCloudProcedureTransportError
80
84
  });
81
85
  module.exports = __toCommonJS(exports_src);
82
- var import_supabase_js = require("@supabase/supabase-js");
86
+ var import_supabase_js2 = require("@supabase/supabase-js");
83
87
 
84
88
  // src/workflow-rpc.ts
85
89
  function invokeWorkflowMutation(supabase, functionName, request, unconfirmed) {
@@ -2594,7 +2598,22 @@ function createSupaCloudApiFetch(options) {
2594
2598
  return responseFromData(invocation.data, invocation.response instanceof Response ? invocation.response : undefined);
2595
2599
  };
2596
2600
  }
2601
+ // src/procedure-client.ts
2602
+ var import_supabase_js = require("@supabase/supabase-js");
2603
+
2597
2604
  // src/procedure-error.ts
2605
+ var procedureErrorCodes = new Set([
2606
+ "API_HTTP_ERROR",
2607
+ "API_RESPONSE_INVALID",
2608
+ "API_RESPONSE_UNDECLARED",
2609
+ "SUPACLOUD_EXECUTION_ERROR",
2610
+ "SUPACLOUD_FUNCTIONS_ERROR",
2611
+ "SUPACLOUD_TRANSPORT_ERROR",
2612
+ "SUPACLOUD_CLIENT_ERROR"
2613
+ ]);
2614
+ function isSupaCloudProcedureErrorCode(value) {
2615
+ return typeof value === "string" && procedureErrorCodes.has(value);
2616
+ }
2598
2617
  function procedureErrorIdentifier(value) {
2599
2618
  return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
2600
2619
  }
@@ -2603,6 +2622,7 @@ class SupaCloudProcedureError extends Error {
2603
2622
  code;
2604
2623
  status;
2605
2624
  requestId;
2625
+ upstreamCode;
2606
2626
  details;
2607
2627
  response;
2608
2628
  cause;
@@ -2612,23 +2632,62 @@ class SupaCloudProcedureError extends Error {
2612
2632
  this.code = options.code;
2613
2633
  this.status = options.status ?? null;
2614
2634
  this.requestId = procedureErrorIdentifier(options.requestId) ?? null;
2635
+ this.upstreamCode = procedureErrorIdentifier(options.upstreamCode) ?? null;
2615
2636
  this.details = options.details;
2616
2637
  this.response = options.response;
2617
2638
  this.cause = options.cause;
2618
2639
  Object.defineProperty(this, "response", { enumerable: false });
2619
2640
  Object.defineProperty(this, "cause", { enumerable: false });
2641
+ Object.defineProperty(this, "upstreamCode", { enumerable: false });
2620
2642
  Object.defineProperty(this, "details", { enumerable: false });
2621
2643
  }
2622
2644
  }
2645
+ function isSupaCloudProcedureError(value) {
2646
+ 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;
2647
+ }
2648
+ function isSupaCloudProcedureHttpError(value) {
2649
+ return isSupaCloudProcedureError(value) && typeof value.status === "number" && value.response instanceof Response;
2650
+ }
2651
+ function isSupaCloudProcedureTransportError(value) {
2652
+ return isSupaCloudProcedureError(value) && (value.code === "SUPACLOUD_FUNCTIONS_ERROR" || value.code === "SUPACLOUD_TRANSPORT_ERROR");
2653
+ }
2623
2654
 
2624
- // src/procedure-client.ts
2655
+ // src/procedure-runtime.ts
2656
+ var idempotencyKeyPattern = /^[A-Za-z0-9._:-]{1,512}$/;
2657
+ function isValidSupaCloudIdempotencyKey(value) {
2658
+ return typeof value === "string" && idempotencyKeyPattern.test(value);
2659
+ }
2625
2660
  function isRecord5(value) {
2626
2661
  return value !== null && typeof value === "object" && !Array.isArray(value);
2627
2662
  }
2663
+ function validateSupaCloudProcedureExecution(metadata, execution) {
2664
+ if (execution !== undefined && !isRecord5(execution)) {
2665
+ throw new SupaCloudProcedureError("Procedure execution must be an options object", {
2666
+ code: "SUPACLOUD_EXECUTION_ERROR"
2667
+ });
2668
+ }
2669
+ const signal = isRecord5(execution) ? execution.signal : undefined;
2670
+ if (signal !== undefined && (typeof AbortSignal === "undefined" || !(signal instanceof AbortSignal))) {
2671
+ throw new SupaCloudProcedureError("Procedure signal must be an AbortSignal", {
2672
+ code: "SUPACLOUD_EXECUTION_ERROR"
2673
+ });
2674
+ }
2675
+ const key = isRecord5(execution) ? execution.idempotencyKey : undefined;
2676
+ if (metadata.idempotency === "required" && key === undefined || key !== undefined && !isValidSupaCloudIdempotencyKey(key)) {
2677
+ throw new SupaCloudProcedureError("This procedure requires a valid idempotencyKey", {
2678
+ code: "SUPACLOUD_EXECUTION_ERROR"
2679
+ });
2680
+ }
2681
+ }
2682
+
2683
+ // src/procedure-client.ts
2684
+ function isRecord6(value) {
2685
+ return value !== null && typeof value === "object" && !Array.isArray(value);
2686
+ }
2628
2687
  function asGeneratedError(value) {
2629
- if (!isRecord5(value))
2688
+ if (!isRecord6(value) || !(value instanceof Error))
2630
2689
  return;
2631
- if (value.name !== "ApiClientError" || typeof value.code !== "string" || typeof value.status !== "number")
2690
+ 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
2691
  return;
2633
2692
  return { code: value.code, status: value.status, requestId: value.requestId, response: value.response };
2634
2693
  }
@@ -2660,7 +2719,7 @@ async function readErrorBody(response) {
2660
2719
  return;
2661
2720
  if (chunk.done) {
2662
2721
  const body = JSON.parse(text + decoder.decode());
2663
- return isRecord5(body) ? body : undefined;
2722
+ return isRecord6(body) ? body : undefined;
2664
2723
  }
2665
2724
  bytes += chunk.value.byteLength;
2666
2725
  if (bytes > maxBytes)
@@ -2684,79 +2743,39 @@ async function readErrorBody(response) {
2684
2743
  }
2685
2744
  }
2686
2745
  function errorName(error) {
2687
- return isRecord5(error) && typeof error.name === "string" ? error.name : undefined;
2746
+ return isRecord6(error) && typeof error.name === "string" ? error.name : undefined;
2688
2747
  }
2689
2748
  async function normalizeProcedureError(error, transport = false) {
2690
- if (error instanceof SupaCloudProcedureError)
2749
+ if (isSupaCloudProcedureError(error))
2750
+ return error;
2751
+ const generated = asGeneratedError(error);
2752
+ const knownTransportFailure = error instanceof import_supabase_js.FunctionsFetchError || error instanceof import_supabase_js.FunctionsRelayError || error instanceof import_supabase_js.FunctionsHttpError;
2753
+ if (generated === undefined && !knownTransportFailure && !transport)
2691
2754
  return error;
2692
2755
  if (errorName(error) === "AbortError")
2693
2756
  return error;
2694
- if (errorName(error) === "FunctionsFetchError" && isRecord5(error) && errorName(error.context) === "AbortError")
2757
+ if (errorName(error) === "FunctionsFetchError" && isRecord6(error) && errorName(error.context) === "AbortError")
2695
2758
  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;
2759
+ const responseDecodeFailure = transport && error instanceof SyntaxError;
2760
+ const response = generated?.response instanceof Response ? generated.response : isRecord6(error) && error.context instanceof Response ? error.context : undefined;
2698
2761
  const original = response === undefined ? undefined : getSupaCloudApiFetchError(response);
2699
2762
  const cause = original ?? error;
2700
2763
  const responseBody = await readErrorBody(response);
2701
2764
  const name = errorName(cause);
2702
2765
  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;
2766
+ 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";
2767
+ const code = name !== "FunctionsRelayError" && generated?.code && isSupaCloudProcedureErrorCode(generated.code) ? generated.code : fallback;
2768
+ const upstreamCode = procedureErrorIdentifier(responseBody?.code) ?? (generated && !isSupaCloudProcedureErrorCode(generated.code) ? procedureErrorIdentifier(generated.code) : undefined);
2705
2769
  return new SupaCloudProcedureError(message, {
2706
2770
  code,
2707
2771
  status: generated?.status ?? response?.status ?? null,
2708
2772
  requestId: procedureErrorIdentifier(generated?.requestId) ?? procedureErrorIdentifier(response?.headers.get("x-request-id")) ?? procedureErrorIdentifier(responseBody?.requestId) ?? null,
2773
+ upstreamCode: upstreamCode ?? null,
2709
2774
  details: responseBody,
2710
2775
  response,
2711
2776
  cause
2712
2777
  });
2713
2778
  }
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
2779
  function createSupaCloudProcedureClient(options) {
2761
2780
  const transport = createSupaCloudApiFetch({
2762
2781
  supabase: options.supabase,
@@ -2773,7 +2792,18 @@ function createSupaCloudProcedureClient(options) {
2773
2792
  throw await normalizeProcedureError(error, true);
2774
2793
  }
2775
2794
  };
2776
- return wrapGeneratedClient(options.generated({ fetch: fetch2 }));
2795
+ const generatedConfig = {
2796
+ ...options.generatedConfig ?? {},
2797
+ fetch: fetch2,
2798
+ errorMapper: normalizeProcedureError,
2799
+ procedureExecutionValidator: validateSupaCloudProcedureExecution
2800
+ };
2801
+ const client = options.generated(generatedConfig);
2802
+ const capabilities = Reflect.get(client, "__supacloudClient");
2803
+ if (!isRecord6(capabilities) || capabilities.hooksVersion !== 1) {
2804
+ throw new TypeError("Regenerate the application client to enable procedure error and execution hooks");
2805
+ }
2806
+ return client;
2777
2807
  }
2778
2808
 
2779
2809
  // src/index.ts
@@ -3491,11 +3521,11 @@ class SupaCloudTasksClient extends SupaCloudManagementClient {
3491
3521
  const { data, error, response } = invocation;
3492
3522
  const boundedHttpFailure = response instanceof Response && boundedTaskHttpFailures.delete(response);
3493
3523
  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) {
3524
+ if (error instanceof import_supabase_js2.FunctionsHttpError && response instanceof Response && error.context === response && !response.redirected && response.status >= 400 && response.status < 500) {
3495
3525
  throw error;
3496
3526
  }
3497
3527
  if (boundedHttpFailure && response instanceof Response && !response.redirected && response.status >= 400 && response.status < 500 && matchesForeignTaskHttpError(error, response)) {
3498
- throw new import_supabase_js.FunctionsHttpError(response);
3528
+ throw new import_supabase_js2.FunctionsHttpError(response);
3499
3529
  }
3500
3530
  if (response instanceof Response)
3501
3531
  response.body?.cancel().catch(() => {});
package/dist/index.d.cts CHANGED
@@ -17,7 +17,7 @@ export { createSupaCloudWorkflowFetch, type SupaCloudWorkflowFetchOptions } from
17
17
  export { createSupaCloudCommandFetch, type SupaCloudCommandFetchOptions } from "./command-fetch.cjs";
18
18
  export { createSupaCloudArtifactFetch, type SupaCloudArtifactFetchOptions } from "./artifact-fetch.cjs";
19
19
  export { createSupaCloudApiFetch, type SupaCloudApiFetchOptions, } from "./api-fetch.cjs";
20
- export { createSupaCloudProcedureClient, SupaCloudProcedureError, type SupaCloudGeneratedClientConfig, type SupaCloudGeneratedClientFactory, type SupaCloudProcedureClient, type SupaCloudProcedureClientOptions, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-client.cjs";
20
+ export { createSupaCloudProcedureClient, SupaCloudProcedureError, isSupaCloudProcedureError, isSupaCloudProcedureErrorCode, isSupaCloudProcedureHttpError, isSupaCloudProcedureTransportError, type SupaCloudGeneratedClientConfig, type SupaCloudGeneratedClientFactory, type SupaCloudGeneratedClientOptions, type SupaCloudProcedureClient, type SupaCloudProcedureClientOptions, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-client.cjs";
21
21
  export * from "./commands.cjs";
22
22
  export * from "./artifacts.cjs";
23
23
  export type SupaCloudTaskStatus = "pending" | "leased" | "running" | "retry_scheduled" | "succeeded" | "failed" | "dead_lettered" | "cancelled" | "queued" | "processing" | "completed";
package/dist/index.d.mts CHANGED
@@ -17,7 +17,7 @@ export { createSupaCloudWorkflowFetch, type SupaCloudWorkflowFetchOptions } from
17
17
  export { createSupaCloudCommandFetch, type SupaCloudCommandFetchOptions } from "./command-fetch.mjs";
18
18
  export { createSupaCloudArtifactFetch, type SupaCloudArtifactFetchOptions } from "./artifact-fetch.mjs";
19
19
  export { createSupaCloudApiFetch, type SupaCloudApiFetchOptions, } from "./api-fetch.mjs";
20
- export { createSupaCloudProcedureClient, SupaCloudProcedureError, type SupaCloudGeneratedClientConfig, type SupaCloudGeneratedClientFactory, type SupaCloudProcedureClient, type SupaCloudProcedureClientOptions, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-client.mjs";
20
+ export { createSupaCloudProcedureClient, SupaCloudProcedureError, isSupaCloudProcedureError, isSupaCloudProcedureErrorCode, isSupaCloudProcedureHttpError, isSupaCloudProcedureTransportError, type SupaCloudGeneratedClientConfig, type SupaCloudGeneratedClientFactory, type SupaCloudGeneratedClientOptions, type SupaCloudProcedureClient, type SupaCloudProcedureClientOptions, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-client.mjs";
21
21
  export * from "./commands.mjs";
22
22
  export * from "./artifacts.mjs";
23
23
  export type SupaCloudTaskStatus = "pending" | "leased" | "running" | "retry_scheduled" | "succeeded" | "failed" | "dead_lettered" | "cancelled" | "queued" | "processing" | "completed";
package/dist/index.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  // src/index.ts
2
- import { FunctionsHttpError } from "@supabase/supabase-js";
2
+ import { FunctionsHttpError as FunctionsHttpError2 } from "@supabase/supabase-js";
3
3
 
4
4
  // src/workflow-rpc.ts
5
5
  function invokeWorkflowMutation(supabase, functionName, request, unconfirmed) {
@@ -2514,7 +2514,22 @@ function createSupaCloudApiFetch(options) {
2514
2514
  return responseFromData(invocation.data, invocation.response instanceof Response ? invocation.response : undefined);
2515
2515
  };
2516
2516
  }
2517
+ // src/procedure-client.ts
2518
+ import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from "@supabase/supabase-js";
2519
+
2517
2520
  // src/procedure-error.ts
2521
+ var procedureErrorCodes = new Set([
2522
+ "API_HTTP_ERROR",
2523
+ "API_RESPONSE_INVALID",
2524
+ "API_RESPONSE_UNDECLARED",
2525
+ "SUPACLOUD_EXECUTION_ERROR",
2526
+ "SUPACLOUD_FUNCTIONS_ERROR",
2527
+ "SUPACLOUD_TRANSPORT_ERROR",
2528
+ "SUPACLOUD_CLIENT_ERROR"
2529
+ ]);
2530
+ function isSupaCloudProcedureErrorCode(value) {
2531
+ return typeof value === "string" && procedureErrorCodes.has(value);
2532
+ }
2518
2533
  function procedureErrorIdentifier(value) {
2519
2534
  return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
2520
2535
  }
@@ -2523,6 +2538,7 @@ class SupaCloudProcedureError extends Error {
2523
2538
  code;
2524
2539
  status;
2525
2540
  requestId;
2541
+ upstreamCode;
2526
2542
  details;
2527
2543
  response;
2528
2544
  cause;
@@ -2532,23 +2548,62 @@ class SupaCloudProcedureError extends Error {
2532
2548
  this.code = options.code;
2533
2549
  this.status = options.status ?? null;
2534
2550
  this.requestId = procedureErrorIdentifier(options.requestId) ?? null;
2551
+ this.upstreamCode = procedureErrorIdentifier(options.upstreamCode) ?? null;
2535
2552
  this.details = options.details;
2536
2553
  this.response = options.response;
2537
2554
  this.cause = options.cause;
2538
2555
  Object.defineProperty(this, "response", { enumerable: false });
2539
2556
  Object.defineProperty(this, "cause", { enumerable: false });
2557
+ Object.defineProperty(this, "upstreamCode", { enumerable: false });
2540
2558
  Object.defineProperty(this, "details", { enumerable: false });
2541
2559
  }
2542
2560
  }
2561
+ function isSupaCloudProcedureError(value) {
2562
+ 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;
2563
+ }
2564
+ function isSupaCloudProcedureHttpError(value) {
2565
+ return isSupaCloudProcedureError(value) && typeof value.status === "number" && value.response instanceof Response;
2566
+ }
2567
+ function isSupaCloudProcedureTransportError(value) {
2568
+ return isSupaCloudProcedureError(value) && (value.code === "SUPACLOUD_FUNCTIONS_ERROR" || value.code === "SUPACLOUD_TRANSPORT_ERROR");
2569
+ }
2543
2570
 
2544
- // src/procedure-client.ts
2571
+ // src/procedure-runtime.ts
2572
+ var idempotencyKeyPattern = /^[A-Za-z0-9._:-]{1,512}$/;
2573
+ function isValidSupaCloudIdempotencyKey(value) {
2574
+ return typeof value === "string" && idempotencyKeyPattern.test(value);
2575
+ }
2545
2576
  function isRecord5(value) {
2546
2577
  return value !== null && typeof value === "object" && !Array.isArray(value);
2547
2578
  }
2579
+ function validateSupaCloudProcedureExecution(metadata, execution) {
2580
+ if (execution !== undefined && !isRecord5(execution)) {
2581
+ throw new SupaCloudProcedureError("Procedure execution must be an options object", {
2582
+ code: "SUPACLOUD_EXECUTION_ERROR"
2583
+ });
2584
+ }
2585
+ const signal = isRecord5(execution) ? execution.signal : undefined;
2586
+ if (signal !== undefined && (typeof AbortSignal === "undefined" || !(signal instanceof AbortSignal))) {
2587
+ throw new SupaCloudProcedureError("Procedure signal must be an AbortSignal", {
2588
+ code: "SUPACLOUD_EXECUTION_ERROR"
2589
+ });
2590
+ }
2591
+ const key = isRecord5(execution) ? execution.idempotencyKey : undefined;
2592
+ if (metadata.idempotency === "required" && key === undefined || key !== undefined && !isValidSupaCloudIdempotencyKey(key)) {
2593
+ throw new SupaCloudProcedureError("This procedure requires a valid idempotencyKey", {
2594
+ code: "SUPACLOUD_EXECUTION_ERROR"
2595
+ });
2596
+ }
2597
+ }
2598
+
2599
+ // src/procedure-client.ts
2600
+ function isRecord6(value) {
2601
+ return value !== null && typeof value === "object" && !Array.isArray(value);
2602
+ }
2548
2603
  function asGeneratedError(value) {
2549
- if (!isRecord5(value))
2604
+ if (!isRecord6(value) || !(value instanceof Error))
2550
2605
  return;
2551
- if (value.name !== "ApiClientError" || typeof value.code !== "string" || typeof value.status !== "number")
2606
+ 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))
2552
2607
  return;
2553
2608
  return { code: value.code, status: value.status, requestId: value.requestId, response: value.response };
2554
2609
  }
@@ -2580,7 +2635,7 @@ async function readErrorBody(response) {
2580
2635
  return;
2581
2636
  if (chunk.done) {
2582
2637
  const body = JSON.parse(text + decoder.decode());
2583
- return isRecord5(body) ? body : undefined;
2638
+ return isRecord6(body) ? body : undefined;
2584
2639
  }
2585
2640
  bytes += chunk.value.byteLength;
2586
2641
  if (bytes > maxBytes)
@@ -2604,79 +2659,39 @@ async function readErrorBody(response) {
2604
2659
  }
2605
2660
  }
2606
2661
  function errorName(error) {
2607
- return isRecord5(error) && typeof error.name === "string" ? error.name : undefined;
2662
+ return isRecord6(error) && typeof error.name === "string" ? error.name : undefined;
2608
2663
  }
2609
2664
  async function normalizeProcedureError(error, transport = false) {
2610
- if (error instanceof SupaCloudProcedureError)
2665
+ if (isSupaCloudProcedureError(error))
2666
+ return error;
2667
+ const generated = asGeneratedError(error);
2668
+ const knownTransportFailure = error instanceof FunctionsFetchError || error instanceof FunctionsRelayError || error instanceof FunctionsHttpError;
2669
+ if (generated === undefined && !knownTransportFailure && !transport)
2611
2670
  return error;
2612
2671
  if (errorName(error) === "AbortError")
2613
2672
  return error;
2614
- if (errorName(error) === "FunctionsFetchError" && isRecord5(error) && errorName(error.context) === "AbortError")
2673
+ if (errorName(error) === "FunctionsFetchError" && isRecord6(error) && errorName(error.context) === "AbortError")
2615
2674
  return error.context;
2616
- const generated = asGeneratedError(error);
2617
- const response = generated?.response instanceof Response ? generated.response : isRecord5(error) && error.context instanceof Response ? error.context : undefined;
2675
+ const responseDecodeFailure = transport && error instanceof SyntaxError;
2676
+ const response = generated?.response instanceof Response ? generated.response : isRecord6(error) && error.context instanceof Response ? error.context : undefined;
2618
2677
  const original = response === undefined ? undefined : getSupaCloudApiFetchError(response);
2619
2678
  const cause = original ?? error;
2620
2679
  const responseBody = await readErrorBody(response);
2621
2680
  const name = errorName(cause);
2622
2681
  const message = error instanceof Error ? error.message : "SupaCloud procedure failed";
2623
- 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";
2624
- const code = name === "FunctionsRelayError" ? fallback : generated?.code ?? fallback;
2682
+ 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";
2683
+ const code = name !== "FunctionsRelayError" && generated?.code && isSupaCloudProcedureErrorCode(generated.code) ? generated.code : fallback;
2684
+ const upstreamCode = procedureErrorIdentifier(responseBody?.code) ?? (generated && !isSupaCloudProcedureErrorCode(generated.code) ? procedureErrorIdentifier(generated.code) : undefined);
2625
2685
  return new SupaCloudProcedureError(message, {
2626
2686
  code,
2627
2687
  status: generated?.status ?? response?.status ?? null,
2628
2688
  requestId: procedureErrorIdentifier(generated?.requestId) ?? procedureErrorIdentifier(response?.headers.get("x-request-id")) ?? procedureErrorIdentifier(responseBody?.requestId) ?? null,
2689
+ upstreamCode: upstreamCode ?? null,
2629
2690
  details: responseBody,
2630
2691
  response,
2631
2692
  cause
2632
2693
  });
2633
2694
  }
2634
- function validateProcedureExecution(procedure, args) {
2635
- const metadata = Reflect.get(procedure, "__supacloudProcedure");
2636
- if (!isRecord5(metadata))
2637
- return;
2638
- const [first, second] = args;
2639
- const execution = second ?? (isRecord5(first) && (Object.hasOwn(first, "idempotencyKey") || Object.hasOwn(first, "signal")) ? first : undefined);
2640
- const key = isRecord5(execution) ? execution.idempotencyKey : undefined;
2641
- if (metadata.idempotency === "required" && key === undefined || key !== undefined && (typeof key !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(key))) {
2642
- throw new SupaCloudProcedureError("This procedure requires a valid idempotencyKey", {
2643
- code: "SUPACLOUD_EXECUTION_ERROR"
2644
- });
2645
- }
2646
- }
2647
- function wrapGeneratedClient(client) {
2648
- const cache = new WeakMap;
2649
- const wrap = (value, level) => {
2650
- const cached = cache.get(value);
2651
- if (cached !== undefined)
2652
- return cached;
2653
- const proxy = new Proxy(value, {
2654
- async apply(current, thisArg, args) {
2655
- try {
2656
- validateProcedureExecution(current, args);
2657
- return await Reflect.apply(current, thisArg, args);
2658
- } catch (failure) {
2659
- throw await normalizeProcedureError(failure);
2660
- }
2661
- },
2662
- get(current, key, receiver) {
2663
- const member = Reflect.get(current, key, receiver);
2664
- if (!Object.hasOwn(current, key))
2665
- return member;
2666
- if (typeof member === "function" && (level === "controller" || level === "client" && key === "request" || level === "call" && (key === "query" || key === "mutate"))) {
2667
- return wrap(member, "call");
2668
- }
2669
- if (level === "client" && isRecord5(member) && Object.getPrototypeOf(member) === Object.prototype) {
2670
- return wrap(member, "controller");
2671
- }
2672
- return member;
2673
- }
2674
- });
2675
- cache.set(value, proxy);
2676
- return proxy;
2677
- };
2678
- return wrap(client, "client");
2679
- }
2680
2695
  function createSupaCloudProcedureClient(options) {
2681
2696
  const transport = createSupaCloudApiFetch({
2682
2697
  supabase: options.supabase,
@@ -2693,7 +2708,18 @@ function createSupaCloudProcedureClient(options) {
2693
2708
  throw await normalizeProcedureError(error, true);
2694
2709
  }
2695
2710
  };
2696
- return wrapGeneratedClient(options.generated({ fetch: fetch2 }));
2711
+ const generatedConfig = {
2712
+ ...options.generatedConfig ?? {},
2713
+ fetch: fetch2,
2714
+ errorMapper: normalizeProcedureError,
2715
+ procedureExecutionValidator: validateSupaCloudProcedureExecution
2716
+ };
2717
+ const client = options.generated(generatedConfig);
2718
+ const capabilities = Reflect.get(client, "__supacloudClient");
2719
+ if (!isRecord6(capabilities) || capabilities.hooksVersion !== 1) {
2720
+ throw new TypeError("Regenerate the application client to enable procedure error and execution hooks");
2721
+ }
2722
+ return client;
2697
2723
  }
2698
2724
 
2699
2725
  // src/index.ts
@@ -3411,11 +3437,11 @@ class SupaCloudTasksClient extends SupaCloudManagementClient {
3411
3437
  const { data, error, response } = invocation;
3412
3438
  const boundedHttpFailure = response instanceof Response && boundedTaskHttpFailures.delete(response);
3413
3439
  if (error !== null && error !== undefined) {
3414
- if (error instanceof FunctionsHttpError && response instanceof Response && error.context === response && !response.redirected && response.status >= 400 && response.status < 500) {
3440
+ if (error instanceof FunctionsHttpError2 && response instanceof Response && error.context === response && !response.redirected && response.status >= 400 && response.status < 500) {
3415
3441
  throw error;
3416
3442
  }
3417
3443
  if (boundedHttpFailure && response instanceof Response && !response.redirected && response.status >= 400 && response.status < 500 && matchesForeignTaskHttpError(error, response)) {
3418
- throw new FunctionsHttpError(response);
3444
+ throw new FunctionsHttpError2(response);
3419
3445
  }
3420
3446
  if (response instanceof Response)
3421
3447
  response.body?.cancel().catch(() => {});
@@ -3976,5 +4002,9 @@ export {
3976
4002
  createSupaCloudOAuthFetch,
3977
4003
  createSupaCloudProcedureClient,
3978
4004
  createSupaCloudTaskFetch,
3979
- createSupaCloudWorkflowFetch
4005
+ createSupaCloudWorkflowFetch,
4006
+ isSupaCloudProcedureError,
4007
+ isSupaCloudProcedureErrorCode,
4008
+ isSupaCloudProcedureHttpError,
4009
+ isSupaCloudProcedureTransportError
3980
4010
  };
@@ -1,10 +1,18 @@
1
1
  import type { SupabaseClient } from "./supabase-types.cjs";
2
2
  import type { FetchTransport } from "./bounded-rpc-fetch.cjs";
3
- export { SupaCloudProcedureError, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-error.cjs";
3
+ import { type SupaCloudProcedureExecution, type SupaCloudProcedureMetadata } from "./procedure-runtime.cjs";
4
+ export { SupaCloudProcedureError, isSupaCloudProcedureError, isSupaCloudProcedureErrorCode, isSupaCloudProcedureHttpError, isSupaCloudProcedureTransportError, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-error.cjs";
4
5
  export interface SupaCloudGeneratedClientConfig {
5
6
  fetch: FetchTransport;
7
+ errorMapper?: (error: unknown) => unknown | Promise<unknown>;
8
+ procedureExecutionValidator?: (metadata: SupaCloudProcedureMetadata, execution?: SupaCloudProcedureExecution) => void;
6
9
  }
7
10
  export type SupaCloudGeneratedClientFactory<TClient extends object = object> = (config: SupaCloudGeneratedClientConfig) => TClient;
11
+ export type SupaCloudGeneratedClientOptions<TFactory extends SupaCloudGeneratedClientFactory> = Omit<NonNullable<Parameters<TFactory>[0]>, keyof SupaCloudGeneratedClientConfig> & {
12
+ fetch?: never;
13
+ errorMapper?: never;
14
+ procedureExecutionValidator?: never;
15
+ };
8
16
  export interface SupaCloudProcedureClientOptions<TClient extends SupabaseClient, TFactory extends SupaCloudGeneratedClientFactory> {
9
17
  /** The existing user-scoped Supabase client; it owns auth and session refresh. */
10
18
  supabase: TClient;
@@ -12,6 +20,8 @@ export interface SupaCloudProcedureClientOptions<TClient extends SupabaseClient,
12
20
  functionName: string;
13
21
  /** The generated createApiClient factory for the application contract. */
14
22
  generated: TFactory;
23
+ /** Additional generated-client settings; transport and facade policies are owned by this wrapper. */
24
+ generatedConfig?: SupaCloudGeneratedClientOptions<NoInfer<TFactory>>;
15
25
  }
16
26
  export type SupaCloudProcedureClient<TFactory extends SupaCloudGeneratedClientFactory> = ReturnType<TFactory>;
17
27
  /**
@@ -1,10 +1,18 @@
1
1
  import type { SupabaseClient } from "./supabase-types.mjs";
2
2
  import type { FetchTransport } from "./bounded-rpc-fetch.mjs";
3
- export { SupaCloudProcedureError, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-error.mjs";
3
+ import { type SupaCloudProcedureExecution, type SupaCloudProcedureMetadata } from "./procedure-runtime.mjs";
4
+ export { SupaCloudProcedureError, isSupaCloudProcedureError, isSupaCloudProcedureErrorCode, isSupaCloudProcedureHttpError, isSupaCloudProcedureTransportError, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-error.mjs";
4
5
  export interface SupaCloudGeneratedClientConfig {
5
6
  fetch: FetchTransport;
7
+ errorMapper?: (error: unknown) => unknown | Promise<unknown>;
8
+ procedureExecutionValidator?: (metadata: SupaCloudProcedureMetadata, execution?: SupaCloudProcedureExecution) => void;
6
9
  }
7
10
  export type SupaCloudGeneratedClientFactory<TClient extends object = object> = (config: SupaCloudGeneratedClientConfig) => TClient;
11
+ export type SupaCloudGeneratedClientOptions<TFactory extends SupaCloudGeneratedClientFactory> = Omit<NonNullable<Parameters<TFactory>[0]>, keyof SupaCloudGeneratedClientConfig> & {
12
+ fetch?: never;
13
+ errorMapper?: never;
14
+ procedureExecutionValidator?: never;
15
+ };
8
16
  export interface SupaCloudProcedureClientOptions<TClient extends SupabaseClient, TFactory extends SupaCloudGeneratedClientFactory> {
9
17
  /** The existing user-scoped Supabase client; it owns auth and session refresh. */
10
18
  supabase: TClient;
@@ -12,6 +20,8 @@ export interface SupaCloudProcedureClientOptions<TClient extends SupabaseClient,
12
20
  functionName: string;
13
21
  /** The generated createApiClient factory for the application contract. */
14
22
  generated: TFactory;
23
+ /** Additional generated-client settings; transport and facade policies are owned by this wrapper. */
24
+ generatedConfig?: SupaCloudGeneratedClientOptions<NoInfer<TFactory>>;
15
25
  }
16
26
  export type SupaCloudProcedureClient<TFactory extends SupaCloudGeneratedClientFactory> = ReturnType<TFactory>;
17
27
  /**
@@ -1,8 +1,10 @@
1
1
  export type SupaCloudProcedureErrorCode = "API_HTTP_ERROR" | "API_RESPONSE_INVALID" | "API_RESPONSE_UNDECLARED" | "SUPACLOUD_EXECUTION_ERROR" | "SUPACLOUD_FUNCTIONS_ERROR" | "SUPACLOUD_TRANSPORT_ERROR" | "SUPACLOUD_CLIENT_ERROR";
2
+ export declare function isSupaCloudProcedureErrorCode(value: unknown): value is SupaCloudProcedureErrorCode;
2
3
  export interface SupaCloudProcedureErrorOptions {
3
- code: string;
4
+ code: SupaCloudProcedureErrorCode;
4
5
  status?: number | null;
5
6
  requestId?: string | null;
7
+ upstreamCode?: string | null;
6
8
  details?: unknown;
7
9
  response?: Response | undefined;
8
10
  cause?: unknown;
@@ -11,11 +13,21 @@ export interface SupaCloudProcedureErrorOptions {
11
13
  export declare function procedureErrorIdentifier(value: unknown): string | undefined;
12
14
  /** Failure metadata is not proof that a server-side mutation rolled back. */
13
15
  export declare class SupaCloudProcedureError extends Error {
14
- readonly code: string;
16
+ readonly code: SupaCloudProcedureErrorCode;
15
17
  readonly status: number | null;
16
18
  readonly requestId: string | null;
19
+ readonly upstreamCode: string | null;
17
20
  readonly details: unknown;
18
21
  readonly response: Response | undefined;
19
22
  readonly cause: unknown;
20
23
  constructor(message: string, options: SupaCloudProcedureErrorOptions);
21
24
  }
25
+ /** Recognizes errors from separately bundled SDK entrypoints. */
26
+ export declare function isSupaCloudProcedureError(value: unknown): value is SupaCloudProcedureError;
27
+ export declare function isSupaCloudProcedureHttpError(value: unknown): value is SupaCloudProcedureError & {
28
+ status: number;
29
+ response: Response;
30
+ };
31
+ export declare function isSupaCloudProcedureTransportError(value: unknown): value is SupaCloudProcedureError & {
32
+ code: "SUPACLOUD_FUNCTIONS_ERROR" | "SUPACLOUD_TRANSPORT_ERROR";
33
+ };
@@ -1,8 +1,10 @@
1
1
  export type SupaCloudProcedureErrorCode = "API_HTTP_ERROR" | "API_RESPONSE_INVALID" | "API_RESPONSE_UNDECLARED" | "SUPACLOUD_EXECUTION_ERROR" | "SUPACLOUD_FUNCTIONS_ERROR" | "SUPACLOUD_TRANSPORT_ERROR" | "SUPACLOUD_CLIENT_ERROR";
2
+ export declare function isSupaCloudProcedureErrorCode(value: unknown): value is SupaCloudProcedureErrorCode;
2
3
  export interface SupaCloudProcedureErrorOptions {
3
- code: string;
4
+ code: SupaCloudProcedureErrorCode;
4
5
  status?: number | null;
5
6
  requestId?: string | null;
7
+ upstreamCode?: string | null;
6
8
  details?: unknown;
7
9
  response?: Response | undefined;
8
10
  cause?: unknown;
@@ -11,11 +13,21 @@ export interface SupaCloudProcedureErrorOptions {
11
13
  export declare function procedureErrorIdentifier(value: unknown): string | undefined;
12
14
  /** Failure metadata is not proof that a server-side mutation rolled back. */
13
15
  export declare class SupaCloudProcedureError extends Error {
14
- readonly code: string;
16
+ readonly code: SupaCloudProcedureErrorCode;
15
17
  readonly status: number | null;
16
18
  readonly requestId: string | null;
19
+ readonly upstreamCode: string | null;
17
20
  readonly details: unknown;
18
21
  readonly response: Response | undefined;
19
22
  readonly cause: unknown;
20
23
  constructor(message: string, options: SupaCloudProcedureErrorOptions);
21
24
  }
25
+ /** Recognizes errors from separately bundled SDK entrypoints. */
26
+ export declare function isSupaCloudProcedureError(value: unknown): value is SupaCloudProcedureError;
27
+ export declare function isSupaCloudProcedureHttpError(value: unknown): value is SupaCloudProcedureError & {
28
+ status: number;
29
+ response: Response;
30
+ };
31
+ export declare function isSupaCloudProcedureTransportError(value: unknown): value is SupaCloudProcedureError & {
32
+ code: "SUPACLOUD_FUNCTIONS_ERROR" | "SUPACLOUD_TRANSPORT_ERROR";
33
+ };
@@ -0,0 +1,9 @@
1
+ export interface SupaCloudProcedureMetadata {
2
+ readonly idempotency: "none" | "required";
3
+ }
4
+ export interface SupaCloudProcedureExecution {
5
+ readonly idempotencyKey?: string;
6
+ readonly signal?: AbortSignal;
7
+ }
8
+ export declare function isValidSupaCloudIdempotencyKey(value: unknown): value is string;
9
+ export declare function validateSupaCloudProcedureExecution(metadata: SupaCloudProcedureMetadata, execution?: unknown): void;
@@ -0,0 +1,9 @@
1
+ export interface SupaCloudProcedureMetadata {
2
+ readonly idempotency: "none" | "required";
3
+ }
4
+ export interface SupaCloudProcedureExecution {
5
+ readonly idempotencyKey?: string;
6
+ readonly signal?: AbortSignal;
7
+ }
8
+ export declare function isValidSupaCloudIdempotencyKey(value: unknown): value is string;
9
+ export declare function validateSupaCloudProcedureExecution(metadata: SupaCloudProcedureMetadata, execution?: unknown): void;
package/dist/query.cjs CHANGED
@@ -42,9 +42,81 @@ __export(exports_query, {
42
42
  createSupaCloudQueryAdapter: () => createSupaCloudQueryAdapter
43
43
  });
44
44
  module.exports = __toCommonJS(exports_query);
45
+
46
+ // src/procedure-error.ts
47
+ var procedureErrorCodes = new Set([
48
+ "API_HTTP_ERROR",
49
+ "API_RESPONSE_INVALID",
50
+ "API_RESPONSE_UNDECLARED",
51
+ "SUPACLOUD_EXECUTION_ERROR",
52
+ "SUPACLOUD_FUNCTIONS_ERROR",
53
+ "SUPACLOUD_TRANSPORT_ERROR",
54
+ "SUPACLOUD_CLIENT_ERROR"
55
+ ]);
56
+ function procedureErrorIdentifier(value) {
57
+ return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
58
+ }
59
+
60
+ class SupaCloudProcedureError extends Error {
61
+ code;
62
+ status;
63
+ requestId;
64
+ upstreamCode;
65
+ details;
66
+ response;
67
+ cause;
68
+ constructor(message, options) {
69
+ super(message, { cause: options.cause });
70
+ this.name = "SupaCloudProcedureError";
71
+ this.code = options.code;
72
+ this.status = options.status ?? null;
73
+ this.requestId = procedureErrorIdentifier(options.requestId) ?? null;
74
+ this.upstreamCode = procedureErrorIdentifier(options.upstreamCode) ?? null;
75
+ this.details = options.details;
76
+ this.response = options.response;
77
+ this.cause = options.cause;
78
+ Object.defineProperty(this, "response", { enumerable: false });
79
+ Object.defineProperty(this, "cause", { enumerable: false });
80
+ Object.defineProperty(this, "upstreamCode", { enumerable: false });
81
+ Object.defineProperty(this, "details", { enumerable: false });
82
+ }
83
+ }
84
+
85
+ // src/procedure-runtime.ts
86
+ var idempotencyKeyPattern = /^[A-Za-z0-9._:-]{1,512}$/;
87
+ function isValidSupaCloudIdempotencyKey(value) {
88
+ return typeof value === "string" && idempotencyKeyPattern.test(value);
89
+ }
90
+ function isRecord(value) {
91
+ return value !== null && typeof value === "object" && !Array.isArray(value);
92
+ }
93
+ function validateSupaCloudProcedureExecution(metadata, execution) {
94
+ if (execution !== undefined && !isRecord(execution)) {
95
+ throw new SupaCloudProcedureError("Procedure execution must be an options object", {
96
+ code: "SUPACLOUD_EXECUTION_ERROR"
97
+ });
98
+ }
99
+ const signal = isRecord(execution) ? execution.signal : undefined;
100
+ if (signal !== undefined && (typeof AbortSignal === "undefined" || !(signal instanceof AbortSignal))) {
101
+ throw new SupaCloudProcedureError("Procedure signal must be an AbortSignal", {
102
+ code: "SUPACLOUD_EXECUTION_ERROR"
103
+ });
104
+ }
105
+ const key = isRecord(execution) ? execution.idempotencyKey : undefined;
106
+ if (metadata.idempotency === "required" && key === undefined || key !== undefined && !isValidSupaCloudIdempotencyKey(key)) {
107
+ throw new SupaCloudProcedureError("This procedure requires a valid idempotencyKey", {
108
+ code: "SUPACLOUD_EXECUTION_ERROR"
109
+ });
110
+ }
111
+ }
112
+
113
+ // src/query.ts
45
114
  function metadataOf(procedure, kind) {
115
+ if (typeof procedure !== "function") {
116
+ throw new TypeError(`Expected a generated ${kind} procedure; regenerate the application client`);
117
+ }
46
118
  const metadata = procedure.__supacloudProcedure;
47
- if (!metadata || metadata.kind !== kind || typeof metadata.method !== "string" || typeof metadata.path !== "string" || !["none", "required"].includes(metadata.idempotency)) {
119
+ if (!metadata || metadata.kind !== kind || typeof metadata.key !== "string" || typeof metadata.method !== "string" || typeof metadata.path !== "string" || !["none", "required"].includes(metadata.idempotency)) {
48
120
  throw new TypeError(`Expected a generated ${kind} procedure; regenerate the application client`);
49
121
  }
50
122
  return metadata;
@@ -72,8 +144,10 @@ function snapshot(value, ancestors = new Set) {
72
144
  }
73
145
  }
74
146
  function callProcedure(procedure, input, execution) {
147
+ validateSupaCloudProcedureExecution(procedure.__supacloudProcedure, execution);
148
+ const capturedExecution = Object.freeze({ ...execution });
75
149
  const call = procedure;
76
- const signal = execution.signal;
150
+ const signal = capturedExecution.signal;
77
151
  return new Promise((resolve, reject) => {
78
152
  const onAbort = () => reject(signal?.reason ?? new DOMException("Procedure cancelled", "AbortError"));
79
153
  if (signal?.aborted) {
@@ -83,7 +157,7 @@ function callProcedure(procedure, input, execution) {
83
157
  signal?.addEventListener("abort", onAbort, { once: true });
84
158
  Promise.resolve().then(() => {
85
159
  signal?.throwIfAborted();
86
- return call(input, execution);
160
+ return call(input, capturedExecution);
87
161
  }).then(resolve, reject).finally(() => signal?.removeEventListener("abort", onAbort));
88
162
  });
89
163
  }
@@ -126,7 +200,7 @@ function createSupaCloudQueryAdapter({
126
200
  mutationKey: procedureKey(procedure, "mutation"),
127
201
  retry: false,
128
202
  mutationFn: async (variables) => {
129
- const execution = variables.execution ?? {};
203
+ const execution = variables.execution === undefined ? {} : variables.execution;
130
204
  return callProcedure(procedure, variables.input, execution);
131
205
  }
132
206
  };
package/dist/query.d.cts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { DataTag, DefaultError, MutationKey, MutationObserverOptions, QueryFunctionContext, QueryKey, QueryObserverOptions } from "@tanstack/query-core";
2
- type Procedure<Kind extends "query" | "mutation"> = {
2
+ import type { SupaCloudProcedureExecution } from "./procedure-runtime.cjs";
3
+ type Procedure<Kind extends "query" | "mutation"> = ((...args: never) => Promise<unknown>) & {
3
4
  readonly __supacloudProcedure: {
4
5
  readonly key: string;
5
6
  readonly method: string;
@@ -16,8 +17,7 @@ export type SupaCloudProcedureResult<TProcedure> = TProcedure extends (...args:
16
17
  type ProcedureInput<TProcedure> = {} extends SupaCloudProcedureInput<TProcedure> ? SupaCloudProcedureInput<TProcedure> | undefined : SupaCloudProcedureInput<TProcedure>;
17
18
  type QueryResult<TProcedure> = Exclude<SupaCloudProcedureResult<TProcedure>, undefined | void> | (undefined extends SupaCloudProcedureResult<TProcedure> ? null : never);
18
19
  type TaggedQueryKey<TProcedure, TError = DefaultError> = DataTag<QueryKey, QueryResult<TProcedure>, TError>;
19
- export interface SupaCloudProcedureExecutionOptions {
20
- idempotencyKey?: string;
20
+ export interface SupaCloudProcedureExecutionOptions extends SupaCloudProcedureExecution {
21
21
  /** Pass an existing CommandAttempt signal to bind a mutation to component lifetime. */
22
22
  signal?: AbortSignal;
23
23
  }
@@ -56,7 +56,7 @@ export declare function createSupaCloudQueryAdapter({ keyPrefix, }: SupaCloudQue
56
56
  <TProcedure extends Procedure<"query">>(procedure: TProcedure, input: NoInfer<ProcedureInput<TProcedure>>): TaggedQueryKey<TProcedure>;
57
57
  };
58
58
  queryOptions: <TProcedure extends Procedure<"query">, TError = Error, TData = QueryResult<TProcedure>>(procedure: TProcedure, input: NoInfer<ProcedureInput<TProcedure>>, options?: SupaCloudQueryOptions<NoInfer<TProcedure>, TError, TData>) => SupaCloudQueryOptionsResult<TProcedure, TError, TData>;
59
- mutationKey: (procedure: Procedure<"mutation">) => readonly unknown[];
59
+ mutationKey: <TProcedure extends Procedure<"mutation">>(procedure: TProcedure) => readonly unknown[];
60
60
  mutationOptions: <TProcedure extends Procedure<"mutation">, TError = Error, TContext = unknown>(procedure: TProcedure, options?: SupaCloudMutationOptions<NoInfer<TProcedure>, TError, TContext>) => SupaCloudMutationOptionsResult<TProcedure, TError, TContext>;
61
61
  };
62
62
  export {};
package/dist/query.d.mts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { DataTag, DefaultError, MutationKey, MutationObserverOptions, QueryFunctionContext, QueryKey, QueryObserverOptions } from "@tanstack/query-core";
2
- type Procedure<Kind extends "query" | "mutation"> = {
2
+ import type { SupaCloudProcedureExecution } from "./procedure-runtime.mjs";
3
+ type Procedure<Kind extends "query" | "mutation"> = ((...args: never) => Promise<unknown>) & {
3
4
  readonly __supacloudProcedure: {
4
5
  readonly key: string;
5
6
  readonly method: string;
@@ -16,8 +17,7 @@ export type SupaCloudProcedureResult<TProcedure> = TProcedure extends (...args:
16
17
  type ProcedureInput<TProcedure> = {} extends SupaCloudProcedureInput<TProcedure> ? SupaCloudProcedureInput<TProcedure> | undefined : SupaCloudProcedureInput<TProcedure>;
17
18
  type QueryResult<TProcedure> = Exclude<SupaCloudProcedureResult<TProcedure>, undefined | void> | (undefined extends SupaCloudProcedureResult<TProcedure> ? null : never);
18
19
  type TaggedQueryKey<TProcedure, TError = DefaultError> = DataTag<QueryKey, QueryResult<TProcedure>, TError>;
19
- export interface SupaCloudProcedureExecutionOptions {
20
- idempotencyKey?: string;
20
+ export interface SupaCloudProcedureExecutionOptions extends SupaCloudProcedureExecution {
21
21
  /** Pass an existing CommandAttempt signal to bind a mutation to component lifetime. */
22
22
  signal?: AbortSignal;
23
23
  }
@@ -56,7 +56,7 @@ export declare function createSupaCloudQueryAdapter({ keyPrefix, }: SupaCloudQue
56
56
  <TProcedure extends Procedure<"query">>(procedure: TProcedure, input: NoInfer<ProcedureInput<TProcedure>>): TaggedQueryKey<TProcedure>;
57
57
  };
58
58
  queryOptions: <TProcedure extends Procedure<"query">, TError = Error, TData = QueryResult<TProcedure>>(procedure: TProcedure, input: NoInfer<ProcedureInput<TProcedure>>, options?: SupaCloudQueryOptions<NoInfer<TProcedure>, TError, TData>) => SupaCloudQueryOptionsResult<TProcedure, TError, TData>;
59
- mutationKey: (procedure: Procedure<"mutation">) => readonly unknown[];
59
+ mutationKey: <TProcedure extends Procedure<"mutation">>(procedure: TProcedure) => readonly unknown[];
60
60
  mutationOptions: <TProcedure extends Procedure<"mutation">, TError = Error, TContext = unknown>(procedure: TProcedure, options?: SupaCloudMutationOptions<NoInfer<TProcedure>, TError, TContext>) => SupaCloudMutationOptionsResult<TProcedure, TError, TContext>;
61
61
  };
62
62
  export {};
package/dist/query.mjs CHANGED
@@ -1,7 +1,77 @@
1
+ // src/procedure-error.ts
2
+ var procedureErrorCodes = new Set([
3
+ "API_HTTP_ERROR",
4
+ "API_RESPONSE_INVALID",
5
+ "API_RESPONSE_UNDECLARED",
6
+ "SUPACLOUD_EXECUTION_ERROR",
7
+ "SUPACLOUD_FUNCTIONS_ERROR",
8
+ "SUPACLOUD_TRANSPORT_ERROR",
9
+ "SUPACLOUD_CLIENT_ERROR"
10
+ ]);
11
+ function procedureErrorIdentifier(value) {
12
+ return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
13
+ }
14
+
15
+ class SupaCloudProcedureError extends Error {
16
+ code;
17
+ status;
18
+ requestId;
19
+ upstreamCode;
20
+ details;
21
+ response;
22
+ cause;
23
+ constructor(message, options) {
24
+ super(message, { cause: options.cause });
25
+ this.name = "SupaCloudProcedureError";
26
+ this.code = options.code;
27
+ this.status = options.status ?? null;
28
+ this.requestId = procedureErrorIdentifier(options.requestId) ?? null;
29
+ this.upstreamCode = procedureErrorIdentifier(options.upstreamCode) ?? null;
30
+ this.details = options.details;
31
+ this.response = options.response;
32
+ this.cause = options.cause;
33
+ Object.defineProperty(this, "response", { enumerable: false });
34
+ Object.defineProperty(this, "cause", { enumerable: false });
35
+ Object.defineProperty(this, "upstreamCode", { enumerable: false });
36
+ Object.defineProperty(this, "details", { enumerable: false });
37
+ }
38
+ }
39
+
40
+ // src/procedure-runtime.ts
41
+ var idempotencyKeyPattern = /^[A-Za-z0-9._:-]{1,512}$/;
42
+ function isValidSupaCloudIdempotencyKey(value) {
43
+ return typeof value === "string" && idempotencyKeyPattern.test(value);
44
+ }
45
+ function isRecord(value) {
46
+ return value !== null && typeof value === "object" && !Array.isArray(value);
47
+ }
48
+ function validateSupaCloudProcedureExecution(metadata, execution) {
49
+ if (execution !== undefined && !isRecord(execution)) {
50
+ throw new SupaCloudProcedureError("Procedure execution must be an options object", {
51
+ code: "SUPACLOUD_EXECUTION_ERROR"
52
+ });
53
+ }
54
+ const signal = isRecord(execution) ? execution.signal : undefined;
55
+ if (signal !== undefined && (typeof AbortSignal === "undefined" || !(signal instanceof AbortSignal))) {
56
+ throw new SupaCloudProcedureError("Procedure signal must be an AbortSignal", {
57
+ code: "SUPACLOUD_EXECUTION_ERROR"
58
+ });
59
+ }
60
+ const key = isRecord(execution) ? execution.idempotencyKey : undefined;
61
+ if (metadata.idempotency === "required" && key === undefined || key !== undefined && !isValidSupaCloudIdempotencyKey(key)) {
62
+ throw new SupaCloudProcedureError("This procedure requires a valid idempotencyKey", {
63
+ code: "SUPACLOUD_EXECUTION_ERROR"
64
+ });
65
+ }
66
+ }
67
+
1
68
  // src/query.ts
2
69
  function metadataOf(procedure, kind) {
70
+ if (typeof procedure !== "function") {
71
+ throw new TypeError(`Expected a generated ${kind} procedure; regenerate the application client`);
72
+ }
3
73
  const metadata = procedure.__supacloudProcedure;
4
- if (!metadata || metadata.kind !== kind || typeof metadata.method !== "string" || typeof metadata.path !== "string" || !["none", "required"].includes(metadata.idempotency)) {
74
+ if (!metadata || metadata.kind !== kind || typeof metadata.key !== "string" || typeof metadata.method !== "string" || typeof metadata.path !== "string" || !["none", "required"].includes(metadata.idempotency)) {
5
75
  throw new TypeError(`Expected a generated ${kind} procedure; regenerate the application client`);
6
76
  }
7
77
  return metadata;
@@ -29,8 +99,10 @@ function snapshot(value, ancestors = new Set) {
29
99
  }
30
100
  }
31
101
  function callProcedure(procedure, input, execution) {
102
+ validateSupaCloudProcedureExecution(procedure.__supacloudProcedure, execution);
103
+ const capturedExecution = Object.freeze({ ...execution });
32
104
  const call = procedure;
33
- const signal = execution.signal;
105
+ const signal = capturedExecution.signal;
34
106
  return new Promise((resolve, reject) => {
35
107
  const onAbort = () => reject(signal?.reason ?? new DOMException("Procedure cancelled", "AbortError"));
36
108
  if (signal?.aborted) {
@@ -40,7 +112,7 @@ function callProcedure(procedure, input, execution) {
40
112
  signal?.addEventListener("abort", onAbort, { once: true });
41
113
  Promise.resolve().then(() => {
42
114
  signal?.throwIfAborted();
43
- return call(input, execution);
115
+ return call(input, capturedExecution);
44
116
  }).then(resolve, reject).finally(() => signal?.removeEventListener("abort", onAbort));
45
117
  });
46
118
  }
@@ -83,7 +155,7 @@ function createSupaCloudQueryAdapter({
83
155
  mutationKey: procedureKey(procedure, "mutation"),
84
156
  retry: false,
85
157
  mutationFn: async (variables) => {
86
- const execution = variables.execution ?? {};
158
+ const execution = variables.execution === undefined ? {} : variables.execution;
87
159
  return callProcedure(procedure, variables.input, execution);
88
160
  }
89
161
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@supacloud/js",
3
- "version": "0.39.0",
3
+ "version": "0.39.1",
4
4
  "description": "Platform SDK for SupaCloud, built on top of supabase-js",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",