@paykit-sdk/react 1.1.96 → 1.2.0

package/README.md

@@ -41,10 +41,18 @@ function App() {
 
 ```tsx
 import * as React from 'react';
-import { useCustomer, useSubscription, useCheckout } from '@paykit-sdk/react';
+import {
+  useCustomer,
+  useSubscription,
+  useCheckout,
+} from '@paykit-sdk/react';
 import { CustomerView } from './customer-view';
 
-const CustomerDashboard = ({ customerId }: { customerId: string }) => {
+const CustomerDashboard = ({
+  customerId,
+}: {
+  customerId: string;
+}) => {
   const { retrieve, create, update } = useCustomer();
 
   React.useEffect(() => {
@@ -71,9 +79,7 @@ Works with any PayKit provider including Stripe, Polar, Gumroad, and more.
 
 ## Documentation
 
-- [React Documentation](https://www.usepaykit.dev/docs/concepts/client-side-usage)
 - [PayKit Documentation](https://usepaykit.dev/docs)
-- [Framework Examples](https://usepaykit.dev/docs/framework-examples)
 
 ## TypeScript Support
 

package/dist/hooks/use-async-fn.d.mts

@@ -1,7 +1,9 @@
 import { EndpointPath } from '@paykit-sdk/core';
+import { PayKitClientError } from '../util.mjs';
 
-type AsyncResult<T> = [data: T, error: undefined] | [data: undefined, error: Error];
-declare const useAsyncFn: <Args extends unknown[], Response>(path: EndpointPath, apiUrl: string, headersEsque?: Record<string, string> | (() => Record<string, string>)) => {
+type AsyncResult<T> = [data: T, error: undefined] | [data: undefined, error: PayKitClientError];
+type HeadersEsque = Record<string, string> | (() => Record<string, string>);
+declare const useAsyncFn: <Args extends unknown[], Response>(path: EndpointPath, apiUrl: string, headersEsque?: HeadersEsque) => {
     run: (...args: Args) => Promise<AsyncResult<Response>>;
     loading: boolean;
 };

package/dist/hooks/use-async-fn.d.ts

@@ -1,7 +1,9 @@
 import { EndpointPath } from '@paykit-sdk/core';
+import { PayKitClientError } from '../util.js';
 
-type AsyncResult<T> = [data: T, error: undefined] | [data: undefined, error: Error];
-declare const useAsyncFn: <Args extends unknown[], Response>(path: EndpointPath, apiUrl: string, headersEsque?: Record<string, string> | (() => Record<string, string>)) => {
+type AsyncResult<T> = [data: T, error: undefined] | [data: undefined, error: PayKitClientError];
+type HeadersEsque = Record<string, string> | (() => Record<string, string>);
+declare const useAsyncFn: <Args extends unknown[], Response>(path: EndpointPath, apiUrl: string, headersEsque?: HeadersEsque) => {
     run: (...args: Args) => Promise<AsyncResult<Response>>;
     loading: boolean;
 };

package/dist/hooks/use-async-fn.js

@@ -22,6 +22,41 @@ function _interopNamespace(e) {
 
 var React__namespace = /*#__PURE__*/_interopNamespace(React);
 
+// src/hooks/use-async-fn.ts
+
+// src/util.ts
+var PayKitClientError = class extends Error {
+  constructor(errorData) {
+    super(errorData.message);
+    this.name = "PayKitClientError";
+    this.code = errorData.code;
+    this.statusCode = errorData.statusCode;
+    this.provider = errorData.provider;
+    this.method = errorData.method;
+    this.context = errorData.context;
+  }
+};
+var parsePayKitClientError = (response, errorData) => {
+  if (errorData && typeof errorData === "object" && "message" in errorData) {
+    const data = errorData;
+    return new PayKitClientError({
+      message: data.message,
+      code: data.code,
+      statusCode: data.statusCode || response.status,
+      provider: data.provider,
+      method: data.method,
+      context: data.context
+    });
+  }
+  return new PayKitClientError({
+    message: typeof errorData === "string" ? errorData : (errorData == null ? void 0 : errorData.message) || `HTTP ${response.status}: ${response.statusText}`,
+    statusCode: response.status,
+    provider: errorData == null ? void 0 : errorData.provider,
+    method: errorData == null ? void 0 : errorData.method,
+    context: errorData == null ? void 0 : errorData.context
+  });
+};
+
 // src/hooks/use-async-fn.ts
 var useAsyncFn = (path, apiUrl, headersEsque) => {
   const [loading, setLoading] = React__namespace.useState(false);
@@ -30,22 +65,37 @@ var useAsyncFn = (path, apiUrl, headersEsque) => {
       setLoading(true);
       try {
         const headers = typeof headersEsque === "function" ? headersEsque() : headersEsque != null ? headersEsque : {};
-        const response = await fetch(`${apiUrl}${path}`, {
+        const res = await fetch(`${apiUrl}${path}`, {
           method: "POST",
           headers: { "Content-Type": "application/json", ...headers },
           credentials: "include",
           body: JSON.stringify({ args })
         });
-        if (!response.ok) {
-          const errorData = await response.json().catch(() => ({ message: "Request failed" }));
-          throw new Error(errorData.message || `HTTP ${response.status}`);
+        if (!res.ok) {
+          const errorData = await res.json().catch(() => ({
+            message: res.statusText || "Request failed"
+          }));
+          throw parsePayKitClientError(res, errorData);
         }
-        const data = await response.json();
-        setLoading(false);
-        return [data.result, void 0];
-      } catch (error) {
+        const response = await res.json();
+        if (typeof response === "object" && "result" in response) {
+          return [response.result, void 0];
+        }
+        throw new PayKitClientError({
+          message: "Unknown response format (API must return JSON with a top-level 'result' property)",
+          statusCode: 500,
+          context: {
+            response: JSON.stringify(response, null, 2)
+          }
+        });
+      } catch (err) {
+        const error = err instanceof PayKitClientError ? err : new PayKitClientError({
+          message: err instanceof Error ? err.message : "An unexpected error occurred",
+          statusCode: err instanceof Error ? 0 : 500
+        });
+        return [void 0, error];
+      } finally {
         setLoading(false);
-        return [void 0, error instanceof Error ? error : new Error(String(error))];
       }
     },
     [path, apiUrl, headersEsque]

package/dist/hooks/use-async-fn.mjs

@@ -1,5 +1,40 @@
 import * as React from 'react';
 
+// src/hooks/use-async-fn.ts
+
+// src/util.ts
+var PayKitClientError = class extends Error {
+  constructor(errorData) {
+    super(errorData.message);
+    this.name = "PayKitClientError";
+    this.code = errorData.code;
+    this.statusCode = errorData.statusCode;
+    this.provider = errorData.provider;
+    this.method = errorData.method;
+    this.context = errorData.context;
+  }
+};
+var parsePayKitClientError = (response, errorData) => {
+  if (errorData && typeof errorData === "object" && "message" in errorData) {
+    const data = errorData;
+    return new PayKitClientError({
+      message: data.message,
+      code: data.code,
+      statusCode: data.statusCode || response.status,
+      provider: data.provider,
+      method: data.method,
+      context: data.context
+    });
+  }
+  return new PayKitClientError({
+    message: typeof errorData === "string" ? errorData : (errorData == null ? void 0 : errorData.message) || `HTTP ${response.status}: ${response.statusText}`,
+    statusCode: response.status,
+    provider: errorData == null ? void 0 : errorData.provider,
+    method: errorData == null ? void 0 : errorData.method,
+    context: errorData == null ? void 0 : errorData.context
+  });
+};
+
 // src/hooks/use-async-fn.ts
 var useAsyncFn = (path, apiUrl, headersEsque) => {
   const [loading, setLoading] = React.useState(false);
@@ -8,22 +43,37 @@ var useAsyncFn = (path, apiUrl, headersEsque) => {
       setLoading(true);
       try {
         const headers = typeof headersEsque === "function" ? headersEsque() : headersEsque != null ? headersEsque : {};
-        const response = await fetch(`${apiUrl}${path}`, {
+        const res = await fetch(`${apiUrl}${path}`, {
           method: "POST",
           headers: { "Content-Type": "application/json", ...headers },
           credentials: "include",
           body: JSON.stringify({ args })
         });
-        if (!response.ok) {
-          const errorData = await response.json().catch(() => ({ message: "Request failed" }));
-          throw new Error(errorData.message || `HTTP ${response.status}`);
+        if (!res.ok) {
+          const errorData = await res.json().catch(() => ({
+            message: res.statusText || "Request failed"
+          }));
+          throw parsePayKitClientError(res, errorData);
         }
-        const data = await response.json();
-        setLoading(false);
-        return [data.result, void 0];
-      } catch (error) {
+        const response = await res.json();
+        if (typeof response === "object" && "result" in response) {
+          return [response.result, void 0];
+        }
+        throw new PayKitClientError({
+          message: "Unknown response format (API must return JSON with a top-level 'result' property)",
+          statusCode: 500,
+          context: {
+            response: JSON.stringify(response, null, 2)
+          }
+        });
+      } catch (err) {
+        const error = err instanceof PayKitClientError ? err : new PayKitClientError({
+          message: err instanceof Error ? err.message : "An unexpected error occurred",
+          statusCode: err instanceof Error ? 0 : 500
+        });
+        return [void 0, error];
+      } finally {
         setLoading(false);
-        return [void 0, error instanceof Error ? error : new Error(String(error))];
       }
     },
     [path, apiUrl, headersEsque]

package/dist/index.d.mts

@@ -6,12 +6,13 @@ export { useCheckout } from './resources/checkout.mjs';
 export { useRefund } from './resources/refund.mjs';
 export { usePayment } from './resources/payment.mjs';
 import '@paykit-sdk/core';
+import './util.mjs';
 
 interface PaykitProviderProps extends React.PropsWithChildren {
     apiUrl: string;
     headers?: Record<string, string> | (() => Record<string, string>);
 }
-declare const PaykitProvider: ({ apiUrl, headers, children }: PaykitProviderProps) => react_jsx_runtime.JSX.Element;
+declare const PaykitProvider: ({ apiUrl, headers, children, }: PaykitProviderProps) => react_jsx_runtime.JSX.Element;
 declare const usePaykitContext: () => PaykitProviderProps;
 
 export { PaykitProvider, usePaykitContext };

package/dist/index.d.ts

@@ -6,12 +6,13 @@ export { useCheckout } from './resources/checkout.js';
 export { useRefund } from './resources/refund.js';
 export { usePayment } from './resources/payment.js';
 import '@paykit-sdk/core';
+import './util.js';
 
 interface PaykitProviderProps extends React.PropsWithChildren {
     apiUrl: string;
     headers?: Record<string, string> | (() => Record<string, string>);
 }
-declare const PaykitProvider: ({ apiUrl, headers, children }: PaykitProviderProps) => react_jsx_runtime.JSX.Element;
+declare const PaykitProvider: ({ apiUrl, headers, children, }: PaykitProviderProps) => react_jsx_runtime.JSX.Element;
 declare const usePaykitContext: () => PaykitProviderProps;
 
 export { PaykitProvider, usePaykitContext };

package/dist/index.js

@@ -25,16 +25,60 @@ var React__namespace = /*#__PURE__*/_interopNamespace(React);
 
 // src/context.tsx
 var PaykitContext = React__namespace.createContext(void 0);
-var PaykitProvider = ({ apiUrl, headers, children }) => {
-  const value = React__namespace.useMemo(() => ({ apiUrl, headers }), [apiUrl, headers]);
+var PaykitProvider = ({
+  apiUrl,
+  headers,
+  children
+}) => {
+  const value = React__namespace.useMemo(
+    () => ({ apiUrl, headers }),
+    [apiUrl, headers]
+  );
   return /* @__PURE__ */ jsxRuntime.jsx(PaykitContext.Provider, { value, children });
 };
 var usePaykitContext = () => {
   const ctx = React__namespace.useContext(PaykitContext);
   if (!ctx)
-    throw new Error("Your app must be wrapped in PayKitProvider to use PayKit hooks.");
+    throw new Error(
+      "Your app must be wrapped in PayKitProvider to use PayKit hooks."
+    );
   return ctx;
 };
+
+// src/util.ts
+var PayKitClientError = class extends Error {
+  constructor(errorData) {
+    super(errorData.message);
+    this.name = "PayKitClientError";
+    this.code = errorData.code;
+    this.statusCode = errorData.statusCode;
+    this.provider = errorData.provider;
+    this.method = errorData.method;
+    this.context = errorData.context;
+  }
+};
+var parsePayKitClientError = (response, errorData) => {
+  if (errorData && typeof errorData === "object" && "message" in errorData) {
+    const data = errorData;
+    return new PayKitClientError({
+      message: data.message,
+      code: data.code,
+      statusCode: data.statusCode || response.status,
+      provider: data.provider,
+      method: data.method,
+      context: data.context
+    });
+  }
+  return new PayKitClientError({
+    message: typeof errorData === "string" ? errorData : (errorData == null ? void 0 : errorData.message) || `HTTP ${response.status}: ${response.statusText}`,
+    statusCode: response.status,
+    provider: errorData == null ? void 0 : errorData.provider,
+    method: errorData == null ? void 0 : errorData.method,
+    context: errorData == null ? void 0 : errorData.context
+  });
+};
+
+// src/hooks/use-async-fn.ts
 var useAsyncFn = (path, apiUrl, headersEsque) => {
   const [loading, setLoading] = React__namespace.useState(false);
   const run = React__namespace.useCallback(
@@ -42,22 +86,37 @@ var useAsyncFn = (path, apiUrl, headersEsque) => {
       setLoading(true);
       try {
         const headers = typeof headersEsque === "function" ? headersEsque() : headersEsque != null ? headersEsque : {};
-        const response = await fetch(`${apiUrl}${path}`, {
+        const res = await fetch(`${apiUrl}${path}`, {
           method: "POST",
           headers: { "Content-Type": "application/json", ...headers },
           credentials: "include",
           body: JSON.stringify({ args })
         });
-        if (!response.ok) {
-          const errorData = await response.json().catch(() => ({ message: "Request failed" }));
-          throw new Error(errorData.message || `HTTP ${response.status}`);
+        if (!res.ok) {
+          const errorData = await res.json().catch(() => ({
+            message: res.statusText || "Request failed"
+          }));
+          throw parsePayKitClientError(res, errorData);
         }
-        const data = await response.json();
-        setLoading(false);
-        return [data.result, void 0];
-      } catch (error) {
+        const response = await res.json();
+        if (typeof response === "object" && "result" in response) {
+          return [response.result, void 0];
+        }
+        throw new PayKitClientError({
+          message: "Unknown response format (API must return JSON with a top-level 'result' property)",
+          statusCode: 500,
+          context: {
+            response: JSON.stringify(response, null, 2)
+          }
+        });
+      } catch (err) {
+        const error = err instanceof PayKitClientError ? err : new PayKitClientError({
+          message: err instanceof Error ? err.message : "An unexpected error occurred",
+          statusCode: err instanceof Error ? 0 : 500
+        });
+        return [void 0, error];
+      } finally {
         setLoading(false);
-        return [void 0, error instanceof Error ? error : new Error(String(error))];
       }
     },
     [path, apiUrl, headersEsque]

package/dist/index.mjs

@@ -3,16 +3,60 @@ import { jsx } from 'react/jsx-runtime';
 
 // src/context.tsx
 var PaykitContext = React.createContext(void 0);
-var PaykitProvider = ({ apiUrl, headers, children }) => {
-  const value = React.useMemo(() => ({ apiUrl, headers }), [apiUrl, headers]);
+var PaykitProvider = ({
+  apiUrl,
+  headers,
+  children
+}) => {
+  const value = React.useMemo(
+    () => ({ apiUrl, headers }),
+    [apiUrl, headers]
+  );
   return /* @__PURE__ */ jsx(PaykitContext.Provider, { value, children });
 };
 var usePaykitContext = () => {
   const ctx = React.useContext(PaykitContext);
   if (!ctx)
-    throw new Error("Your app must be wrapped in PayKitProvider to use PayKit hooks.");
+    throw new Error(
+      "Your app must be wrapped in PayKitProvider to use PayKit hooks."
+    );
   return ctx;
 };
+
+// src/util.ts
+var PayKitClientError = class extends Error {
+  constructor(errorData) {
+    super(errorData.message);
+    this.name = "PayKitClientError";
+    this.code = errorData.code;
+    this.statusCode = errorData.statusCode;
+    this.provider = errorData.provider;
+    this.method = errorData.method;
+    this.context = errorData.context;
+  }
+};
+var parsePayKitClientError = (response, errorData) => {
+  if (errorData && typeof errorData === "object" && "message" in errorData) {
+    const data = errorData;
+    return new PayKitClientError({
+      message: data.message,
+      code: data.code,
+      statusCode: data.statusCode || response.status,
+      provider: data.provider,
+      method: data.method,
+      context: data.context
+    });
+  }
+  return new PayKitClientError({
+    message: typeof errorData === "string" ? errorData : (errorData == null ? void 0 : errorData.message) || `HTTP ${response.status}: ${response.statusText}`,
+    statusCode: response.status,
+    provider: errorData == null ? void 0 : errorData.provider,
+    method: errorData == null ? void 0 : errorData.method,
+    context: errorData == null ? void 0 : errorData.context
+  });
+};
+
+// src/hooks/use-async-fn.ts
 var useAsyncFn = (path, apiUrl, headersEsque) => {
   const [loading, setLoading] = React.useState(false);
   const run = React.useCallback(
@@ -20,22 +64,37 @@ var useAsyncFn = (path, apiUrl, headersEsque) => {
       setLoading(true);
       try {
         const headers = typeof headersEsque === "function" ? headersEsque() : headersEsque != null ? headersEsque : {};
-        const response = await fetch(`${apiUrl}${path}`, {
+        const res = await fetch(`${apiUrl}${path}`, {
           method: "POST",
           headers: { "Content-Type": "application/json", ...headers },
           credentials: "include",
           body: JSON.stringify({ args })
         });
-        if (!response.ok) {
-          const errorData = await response.json().catch(() => ({ message: "Request failed" }));
-          throw new Error(errorData.message || `HTTP ${response.status}`);
+        if (!res.ok) {
+          const errorData = await res.json().catch(() => ({
+            message: res.statusText || "Request failed"
+          }));
+          throw parsePayKitClientError(res, errorData);
         }
-        const data = await response.json();
-        setLoading(false);
-        return [data.result, void 0];
-      } catch (error) {
+        const response = await res.json();
+        if (typeof response === "object" && "result" in response) {
+          return [response.result, void 0];
+        }
+        throw new PayKitClientError({
+          message: "Unknown response format (API must return JSON with a top-level 'result' property)",
+          statusCode: 500,
+          context: {
+            response: JSON.stringify(response, null, 2)
+          }
+        });
+      } catch (err) {
+        const error = err instanceof PayKitClientError ? err : new PayKitClientError({
+          message: err instanceof Error ? err.message : "An unexpected error occurred",
+          statusCode: err instanceof Error ? 0 : 500
+        });
+        return [void 0, error];
+      } finally {
         setLoading(false);
-        return [void 0, error instanceof Error ? error : new Error(String(error))];
       }
     },
     [path, apiUrl, headersEsque]

package/dist/resources/checkout.d.mts

@@ -1,20 +1,21 @@
+import { PayKitClientError } from '../util.mjs';
 import * as _paykit_sdk_core from '@paykit-sdk/core';
 
 declare const useCheckout: () => {
     create: {
-        run: (params: _paykit_sdk_core.CreateCheckoutSchema) => Promise<[data: undefined, error: Error] | [data: _paykit_sdk_core.Checkout, error: undefined]>;
+        run: (params: _paykit_sdk_core.CreateCheckoutSchema) => Promise<[data: undefined, error: PayKitClientError] | [data: _paykit_sdk_core.Checkout, error: undefined]>;
         loading: boolean;
     };
     retrieve: {
-        run: (id: string) => Promise<[data: undefined, error: Error] | [data: _paykit_sdk_core.Checkout | null, error: undefined]>;
+        run: (id: string) => Promise<[data: undefined, error: PayKitClientError] | [data: _paykit_sdk_core.Checkout | null, error: undefined]>;
         loading: boolean;
     };
     update: {
-        run: (id: string, params: _paykit_sdk_core.UpdateCheckoutSchema) => Promise<[data: undefined, error: Error] | [data: _paykit_sdk_core.Checkout, error: undefined]>;
+        run: (id: string, params: _paykit_sdk_core.UpdateCheckoutSchema) => Promise<[data: undefined, error: PayKitClientError] | [data: _paykit_sdk_core.Checkout, error: undefined]>;
         loading: boolean;
     };
     remove: {
-        run: (id: string) => Promise<[data: undefined, error: Error] | [data: null, error: undefined]>;
+        run: (id: string) => Promise<[data: undefined, error: PayKitClientError] | [data: null, error: undefined]>;
         loading: boolean;
     };
 };

package/dist/resources/checkout.d.ts

@@ -1,20 +1,21 @@
+import { PayKitClientError } from '../util.js';
 import * as _paykit_sdk_core from '@paykit-sdk/core';
 
 declare const useCheckout: () => {
     create: {
-        run: (params: _paykit_sdk_core.CreateCheckoutSchema) => Promise<[data: undefined, error: Error] | [data: _paykit_sdk_core.Checkout, error: undefined]>;
+        run: (params: _paykit_sdk_core.CreateCheckoutSchema) => Promise<[data: undefined, error: PayKitClientError] | [data: _paykit_sdk_core.Checkout, error: undefined]>;
         loading: boolean;
     };
     retrieve: {
-        run: (id: string) => Promise<[data: undefined, error: Error] | [data: _paykit_sdk_core.Checkout | null, error: undefined]>;
+        run: (id: string) => Promise<[data: undefined, error: PayKitClientError] | [data: _paykit_sdk_core.Checkout | null, error: undefined]>;
         loading: boolean;
     };
     update: {
-        run: (id: string, params: _paykit_sdk_core.UpdateCheckoutSchema) => Promise<[data: undefined, error: Error] | [data: _paykit_sdk_core.Checkout, error: undefined]>;
+        run: (id: string, params: _paykit_sdk_core.UpdateCheckoutSchema) => Promise<[data: undefined, error: PayKitClientError] | [data: _paykit_sdk_core.Checkout, error: undefined]>;
         loading: boolean;
     };
     remove: {
-        run: (id: string) => Promise<[data: undefined, error: Error] | [data: null, error: undefined]>;
+        run: (id: string) => Promise<[data: undefined, error: PayKitClientError] | [data: null, error: undefined]>;
         loading: boolean;
     };
 };

package/dist/resources/checkout.js

@@ -28,9 +28,46 @@ var PaykitContext = React__namespace.createContext(void 0);
 var usePaykitContext = () => {
   const ctx = React__namespace.useContext(PaykitContext);
   if (!ctx)
-    throw new Error("Your app must be wrapped in PayKitProvider to use PayKit hooks.");
+    throw new Error(
+      "Your app must be wrapped in PayKitProvider to use PayKit hooks."
+    );
   return ctx;
 };
+
+// src/util.ts
+var PayKitClientError = class extends Error {
+  constructor(errorData) {
+    super(errorData.message);
+    this.name = "PayKitClientError";
+    this.code = errorData.code;
+    this.statusCode = errorData.statusCode;
+    this.provider = errorData.provider;
+    this.method = errorData.method;
+    this.context = errorData.context;
+  }
+};
+var parsePayKitClientError = (response, errorData) => {
+  if (errorData && typeof errorData === "object" && "message" in errorData) {
+    const data = errorData;
+    return new PayKitClientError({
+      message: data.message,
+      code: data.code,
+      statusCode: data.statusCode || response.status,
+      provider: data.provider,
+      method: data.method,
+      context: data.context
+    });
+  }
+  return new PayKitClientError({
+    message: typeof errorData === "string" ? errorData : (errorData == null ? void 0 : errorData.message) || `HTTP ${response.status}: ${response.statusText}`,
+    statusCode: response.status,
+    provider: errorData == null ? void 0 : errorData.provider,
+    method: errorData == null ? void 0 : errorData.method,
+    context: errorData == null ? void 0 : errorData.context
+  });
+};
+
+// src/hooks/use-async-fn.ts
 var useAsyncFn = (path, apiUrl, headersEsque) => {
   const [loading, setLoading] = React__namespace.useState(false);
   const run = React__namespace.useCallback(
@@ -38,22 +75,37 @@ var useAsyncFn = (path, apiUrl, headersEsque) => {
       setLoading(true);
       try {
         const headers = typeof headersEsque === "function" ? headersEsque() : headersEsque != null ? headersEsque : {};
-        const response = await fetch(`${apiUrl}${path}`, {
+        const res = await fetch(`${apiUrl}${path}`, {
           method: "POST",
           headers: { "Content-Type": "application/json", ...headers },
           credentials: "include",
           body: JSON.stringify({ args })
         });
-        if (!response.ok) {
-          const errorData = await response.json().catch(() => ({ message: "Request failed" }));
-          throw new Error(errorData.message || `HTTP ${response.status}`);
+        if (!res.ok) {
+          const errorData = await res.json().catch(() => ({
+            message: res.statusText || "Request failed"
+          }));
+          throw parsePayKitClientError(res, errorData);
         }
-        const data = await response.json();
-        setLoading(false);
-        return [data.result, void 0];
-      } catch (error) {
+        const response = await res.json();
+        if (typeof response === "object" && "result" in response) {
+          return [response.result, void 0];
+        }
+        throw new PayKitClientError({
+          message: "Unknown response format (API must return JSON with a top-level 'result' property)",
+          statusCode: 500,
+          context: {
+            response: JSON.stringify(response, null, 2)
+          }
+        });
+      } catch (err) {
+        const error = err instanceof PayKitClientError ? err : new PayKitClientError({
+          message: err instanceof Error ? err.message : "An unexpected error occurred",
+          statusCode: err instanceof Error ? 0 : 500
+        });
+        return [void 0, error];
+      } finally {
         setLoading(false);
-        return [void 0, error instanceof Error ? error : new Error(String(error))];
       }
     },
     [path, apiUrl, headersEsque]