@supacloud/js 0.38.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/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) {
@@ -2411,6 +2411,10 @@ function createSupaCloudArtifactFetch(options = {}) {
2411
2411
  return createBoundedRpcFetch(artifactPath2, () => new Error("Artifact HTTP response could not be validated"), options.fetch);
2412
2412
  }
2413
2413
  // src/api-fetch.ts
2414
+ var invocationErrors = new WeakMap;
2415
+ function getSupaCloudApiFetchError(response) {
2416
+ return invocationErrors.get(response);
2417
+ }
2414
2418
  function isRecord4(value) {
2415
2419
  return value !== null && typeof value === "object" && !Array.isArray(value);
2416
2420
  }
@@ -2491,6 +2495,7 @@ function createSupaCloudApiFetch(options) {
2491
2495
  delete headers[key];
2492
2496
  }
2493
2497
  }
2498
+ request.signal.throwIfAborted();
2494
2499
  const invocation = await invoke(`${functionName}${url.pathname}${url.search}`, {
2495
2500
  ...body === undefined ? {} : { body },
2496
2501
  ...Object.keys(headers).length === 0 ? {} : { headers },
@@ -2498,8 +2503,10 @@ function createSupaCloudApiFetch(options) {
2498
2503
  signal: request.signal
2499
2504
  });
2500
2505
  if (invocation.error !== null && invocation.error !== undefined) {
2501
- if (invocation.response instanceof Response)
2506
+ if (invocation.response instanceof Response) {
2507
+ invocationErrors.set(invocation.response, invocation.error);
2502
2508
  return invocation.response;
2509
+ }
2503
2510
  if (invocation.error instanceof Error)
2504
2511
  throw invocation.error;
2505
2512
  throw new Error(errorMessage(invocation.error));
@@ -2507,6 +2514,213 @@ function createSupaCloudApiFetch(options) {
2507
2514
  return responseFromData(invocation.data, invocation.response instanceof Response ? invocation.response : undefined);
2508
2515
  };
2509
2516
  }
2517
+ // src/procedure-client.ts
2518
+ import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from "@supabase/supabase-js";
2519
+
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
+ }
2533
+ function procedureErrorIdentifier(value) {
2534
+ return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
2535
+ }
2536
+
2537
+ class SupaCloudProcedureError extends Error {
2538
+ code;
2539
+ status;
2540
+ requestId;
2541
+ upstreamCode;
2542
+ details;
2543
+ response;
2544
+ cause;
2545
+ constructor(message, options) {
2546
+ super(message, { cause: options.cause });
2547
+ this.name = "SupaCloudProcedureError";
2548
+ this.code = options.code;
2549
+ this.status = options.status ?? null;
2550
+ this.requestId = procedureErrorIdentifier(options.requestId) ?? null;
2551
+ this.upstreamCode = procedureErrorIdentifier(options.upstreamCode) ?? null;
2552
+ this.details = options.details;
2553
+ this.response = options.response;
2554
+ this.cause = options.cause;
2555
+ Object.defineProperty(this, "response", { enumerable: false });
2556
+ Object.defineProperty(this, "cause", { enumerable: false });
2557
+ Object.defineProperty(this, "upstreamCode", { enumerable: false });
2558
+ Object.defineProperty(this, "details", { enumerable: false });
2559
+ }
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
+ }
2570
+
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
+ }
2576
+ function isRecord5(value) {
2577
+ return value !== null && typeof value === "object" && !Array.isArray(value);
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
+ }
2603
+ function asGeneratedError(value) {
2604
+ if (!isRecord6(value) || !(value instanceof Error))
2605
+ return;
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))
2607
+ return;
2608
+ return { code: value.code, status: value.status, requestId: value.requestId, response: value.response };
2609
+ }
2610
+ async function readErrorBody(response) {
2611
+ if (response === undefined || response.ok || response.bodyUsed || !response.body)
2612
+ return;
2613
+ const type = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
2614
+ if (type !== "application/json" && !type?.endsWith("+json"))
2615
+ return;
2616
+ const maxBytes = 64 * 1024;
2617
+ const length = response.headers.get("content-length");
2618
+ if (length !== null && (!/^\d+$/.test(length) || Number(length) > maxBytes))
2619
+ return;
2620
+ let reader;
2621
+ let timer;
2622
+ let finished = false;
2623
+ try {
2624
+ reader = response.clone().body?.getReader();
2625
+ if (!reader)
2626
+ return;
2627
+ const current = reader;
2628
+ const read = async () => {
2629
+ const decoder = new TextDecoder("utf-8", { fatal: true });
2630
+ let bytes = 0;
2631
+ let text = "";
2632
+ while (!finished) {
2633
+ const chunk = await current.read();
2634
+ if (finished)
2635
+ return;
2636
+ if (chunk.done) {
2637
+ const body = JSON.parse(text + decoder.decode());
2638
+ return isRecord6(body) ? body : undefined;
2639
+ }
2640
+ bytes += chunk.value.byteLength;
2641
+ if (bytes > maxBytes)
2642
+ return;
2643
+ text += decoder.decode(chunk.value, { stream: true });
2644
+ }
2645
+ return;
2646
+ };
2647
+ return await Promise.race([
2648
+ read(),
2649
+ new Promise((resolve) => {
2650
+ timer = setTimeout(() => resolve(undefined), 250);
2651
+ })
2652
+ ]);
2653
+ } catch {
2654
+ return;
2655
+ } finally {
2656
+ finished = true;
2657
+ clearTimeout(timer);
2658
+ reader?.cancel().catch(() => {});
2659
+ }
2660
+ }
2661
+ function errorName(error) {
2662
+ return isRecord6(error) && typeof error.name === "string" ? error.name : undefined;
2663
+ }
2664
+ async function normalizeProcedureError(error, transport = false) {
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)
2670
+ return error;
2671
+ if (errorName(error) === "AbortError")
2672
+ return error;
2673
+ if (errorName(error) === "FunctionsFetchError" && isRecord6(error) && errorName(error.context) === "AbortError")
2674
+ return error.context;
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;
2677
+ const original = response === undefined ? undefined : getSupaCloudApiFetchError(response);
2678
+ const cause = original ?? error;
2679
+ const responseBody = await readErrorBody(response);
2680
+ const name = errorName(cause);
2681
+ const message = error instanceof Error ? error.message : "SupaCloud procedure failed";
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);
2685
+ return new SupaCloudProcedureError(message, {
2686
+ code,
2687
+ status: generated?.status ?? response?.status ?? null,
2688
+ requestId: procedureErrorIdentifier(generated?.requestId) ?? procedureErrorIdentifier(response?.headers.get("x-request-id")) ?? procedureErrorIdentifier(responseBody?.requestId) ?? null,
2689
+ upstreamCode: upstreamCode ?? null,
2690
+ details: responseBody,
2691
+ response,
2692
+ cause
2693
+ });
2694
+ }
2695
+ function createSupaCloudProcedureClient(options) {
2696
+ const transport = createSupaCloudApiFetch({
2697
+ supabase: options.supabase,
2698
+ functionName: options.functionName
2699
+ });
2700
+ const fetch2 = async (input, init) => {
2701
+ try {
2702
+ const response = await transport(input, init);
2703
+ const error = getSupaCloudApiFetchError(response);
2704
+ if (error !== undefined && (response.ok || errorName(error) === "FunctionsRelayError"))
2705
+ throw error;
2706
+ return response;
2707
+ } catch (error) {
2708
+ throw await normalizeProcedureError(error, true);
2709
+ }
2710
+ };
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;
2723
+ }
2510
2724
 
2511
2725
  // src/index.ts
2512
2726
  class SupaCloudTaskSubmitError extends Error {
@@ -3223,11 +3437,11 @@ class SupaCloudTasksClient extends SupaCloudManagementClient {
3223
3437
  const { data, error, response } = invocation;
3224
3438
  const boundedHttpFailure = response instanceof Response && boundedTaskHttpFailures.delete(response);
3225
3439
  if (error !== null && error !== undefined) {
3226
- 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) {
3227
3441
  throw error;
3228
3442
  }
3229
3443
  if (boundedHttpFailure && response instanceof Response && !response.redirected && response.status >= 400 && response.status < 500 && matchesForeignTaskHttpError(error, response)) {
3230
- throw new FunctionsHttpError(response);
3444
+ throw new FunctionsHttpError2(response);
3231
3445
  }
3232
3446
  if (response instanceof Response)
3233
3447
  response.body?.cancel().catch(() => {});
@@ -3763,6 +3977,7 @@ export {
3763
3977
  SupaCloudOAuthClientsClient,
3764
3978
  SupaCloudOAuthServerClient,
3765
3979
  SupaCloudOAuthServerError,
3980
+ SupaCloudProcedureError,
3766
3981
  SupaCloudQueueError,
3767
3982
  SupaCloudTaskAuthenticationError,
3768
3983
  SupaCloudTaskDecoderError as SupaCloudTaskDecodeError,
@@ -3785,6 +4000,11 @@ export {
3785
4000
  createSupaCloudClient,
3786
4001
  createSupaCloudCommandFetch,
3787
4002
  createSupaCloudOAuthFetch,
4003
+ createSupaCloudProcedureClient,
3788
4004
  createSupaCloudTaskFetch,
3789
- createSupaCloudWorkflowFetch
4005
+ createSupaCloudWorkflowFetch,
4006
+ isSupaCloudProcedureError,
4007
+ isSupaCloudProcedureErrorCode,
4008
+ isSupaCloudProcedureHttpError,
4009
+ isSupaCloudProcedureTransportError
3790
4010
  };
@@ -0,0 +1,31 @@
1
+ import type { SupabaseClient } from "./supabase-types.cjs";
2
+ import type { FetchTransport } from "./bounded-rpc-fetch.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";
5
+ export interface SupaCloudGeneratedClientConfig {
6
+ fetch: FetchTransport;
7
+ errorMapper?: (error: unknown) => unknown | Promise<unknown>;
8
+ procedureExecutionValidator?: (metadata: SupaCloudProcedureMetadata, execution?: SupaCloudProcedureExecution) => void;
9
+ }
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
+ };
16
+ export interface SupaCloudProcedureClientOptions<TClient extends SupabaseClient, TFactory extends SupaCloudGeneratedClientFactory> {
17
+ /** The existing user-scoped Supabase client; it owns auth and session refresh. */
18
+ supabase: TClient;
19
+ /** The deployed Edge Function name hosting the generated application routes. */
20
+ functionName: string;
21
+ /** The generated createApiClient factory for the application contract. */
22
+ generated: TFactory;
23
+ /** Additional generated-client settings; transport and facade policies are owned by this wrapper. */
24
+ generatedConfig?: SupaCloudGeneratedClientOptions<NoInfer<TFactory>>;
25
+ }
26
+ export type SupaCloudProcedureClient<TFactory extends SupaCloudGeneratedClientFactory> = ReturnType<TFactory>;
27
+ /**
28
+ * Creates a typed procedure facade over a compiler-generated client while
29
+ * reusing Supabase JS for auth, refresh and Functions transport.
30
+ */
31
+ export declare function createSupaCloudProcedureClient<TFactory extends SupaCloudGeneratedClientFactory, TClient extends SupabaseClient = SupabaseClient>(options: SupaCloudProcedureClientOptions<TClient, TFactory>): SupaCloudProcedureClient<TFactory>;
@@ -0,0 +1,31 @@
1
+ import type { SupabaseClient } from "./supabase-types.mjs";
2
+ import type { FetchTransport } from "./bounded-rpc-fetch.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";
5
+ export interface SupaCloudGeneratedClientConfig {
6
+ fetch: FetchTransport;
7
+ errorMapper?: (error: unknown) => unknown | Promise<unknown>;
8
+ procedureExecutionValidator?: (metadata: SupaCloudProcedureMetadata, execution?: SupaCloudProcedureExecution) => void;
9
+ }
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
+ };
16
+ export interface SupaCloudProcedureClientOptions<TClient extends SupabaseClient, TFactory extends SupaCloudGeneratedClientFactory> {
17
+ /** The existing user-scoped Supabase client; it owns auth and session refresh. */
18
+ supabase: TClient;
19
+ /** The deployed Edge Function name hosting the generated application routes. */
20
+ functionName: string;
21
+ /** The generated createApiClient factory for the application contract. */
22
+ generated: TFactory;
23
+ /** Additional generated-client settings; transport and facade policies are owned by this wrapper. */
24
+ generatedConfig?: SupaCloudGeneratedClientOptions<NoInfer<TFactory>>;
25
+ }
26
+ export type SupaCloudProcedureClient<TFactory extends SupaCloudGeneratedClientFactory> = ReturnType<TFactory>;
27
+ /**
28
+ * Creates a typed procedure facade over a compiler-generated client while
29
+ * reusing Supabase JS for auth, refresh and Functions transport.
30
+ */
31
+ export declare function createSupaCloudProcedureClient<TFactory extends SupaCloudGeneratedClientFactory, TClient extends SupabaseClient = SupabaseClient>(options: SupaCloudProcedureClientOptions<TClient, TFactory>): SupaCloudProcedureClient<TFactory>;
@@ -0,0 +1,33 @@
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;
3
+ export interface SupaCloudProcedureErrorOptions {
4
+ code: SupaCloudProcedureErrorCode;
5
+ status?: number | null;
6
+ requestId?: string | null;
7
+ upstreamCode?: string | null;
8
+ details?: unknown;
9
+ response?: Response | undefined;
10
+ cause?: unknown;
11
+ }
12
+ /** Internal validation shared by error construction and response inspection. */
13
+ export declare function procedureErrorIdentifier(value: unknown): string | undefined;
14
+ /** Failure metadata is not proof that a server-side mutation rolled back. */
15
+ export declare class SupaCloudProcedureError extends Error {
16
+ readonly code: SupaCloudProcedureErrorCode;
17
+ readonly status: number | null;
18
+ readonly requestId: string | null;
19
+ readonly upstreamCode: string | null;
20
+ readonly details: unknown;
21
+ readonly response: Response | undefined;
22
+ readonly cause: unknown;
23
+ constructor(message: string, options: SupaCloudProcedureErrorOptions);
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,33 @@
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;
3
+ export interface SupaCloudProcedureErrorOptions {
4
+ code: SupaCloudProcedureErrorCode;
5
+ status?: number | null;
6
+ requestId?: string | null;
7
+ upstreamCode?: string | null;
8
+ details?: unknown;
9
+ response?: Response | undefined;
10
+ cause?: unknown;
11
+ }
12
+ /** Internal validation shared by error construction and response inspection. */
13
+ export declare function procedureErrorIdentifier(value: unknown): string | undefined;
14
+ /** Failure metadata is not proof that a server-side mutation rolled back. */
15
+ export declare class SupaCloudProcedureError extends Error {
16
+ readonly code: SupaCloudProcedureErrorCode;
17
+ readonly status: number | null;
18
+ readonly requestId: string | null;
19
+ readonly upstreamCode: string | null;
20
+ readonly details: unknown;
21
+ readonly response: Response | undefined;
22
+ readonly cause: unknown;
23
+ constructor(message: string, options: SupaCloudProcedureErrorOptions);
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
  }
@@ -121,17 +195,12 @@ function createSupaCloudQueryAdapter({
121
195
  };
122
196
  }
123
197
  function mutationOptions(procedure, options) {
124
- const metadata = metadataOf(procedure, "mutation");
125
198
  return {
126
199
  ...options,
127
200
  mutationKey: procedureKey(procedure, "mutation"),
128
201
  retry: false,
129
202
  mutationFn: async (variables) => {
130
- const execution = variables.execution ?? {};
131
- const key = execution.idempotencyKey;
132
- if (metadata.idempotency === "required" && key === undefined || key !== undefined && (typeof key !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(key))) {
133
- throw new TypeError("This mutation requires a valid idempotencyKey");
134
- }
203
+ const execution = variables.execution === undefined ? {} : variables.execution;
135
204
  return callProcedure(procedure, variables.input, execution);
136
205
  }
137
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 {};