@spaceinvoices/react-ui 0.4.11 → 0.4.31

package/src/lib/zod-validation-message.ts

@@ -0,0 +1,291 @@
+import { getLocaleLanguage } from "./locale";
+
+type ValidationDictionary = {
+  required: string;
+  minChars: (count: number) => string;
+  maxChars: (count: number) => string;
+  exactDigits: (count: number) => string;
+  digitsOnly: string;
+  invalidEmail: string;
+  invalidFormat: string;
+  invalidValue: string;
+  alphanumericRange: string;
+};
+
+const dictionaries: Record<string, ValidationDictionary> = {
+  en: {
+    required: "Required",
+    minChars: (count) => `Must be at least ${count} characters`,
+    maxChars: (count) => `Must be at most ${count} characters`,
+    exactDigits: (count) => `Must be exactly ${count} digits`,
+    digitsOnly: "Must contain only digits",
+    invalidEmail: "Invalid email address",
+    invalidFormat: "Invalid format",
+    invalidValue: "Invalid value",
+    alphanumericRange: "Must be alphanumeric, 1-20 characters",
+  },
+  de: {
+    required: "Erforderlich",
+    minChars: (count) => `Muss mindestens ${count} Zeichen enthalten`,
+    maxChars: (count) => `Darf höchstens ${count} Zeichen enthalten`,
+    exactDigits: (count) => `Muss genau ${count} Ziffern enthalten`,
+    digitsOnly: "Darf nur Ziffern enthalten",
+    invalidEmail: "Ungultige E-Mail-Adresse",
+    invalidFormat: "Ungultiges Format",
+    invalidValue: "Ungultiger Wert",
+    alphanumericRange: "Muss alphanumerisch sein, 1-20 Zeichen",
+  },
+  es: {
+    required: "Obligatorio",
+    minChars: (count) => `Debe tener al menos ${count} caracteres`,
+    maxChars: (count) => `Debe tener como maximo ${count} caracteres`,
+    exactDigits: (count) => `Debe tener exactamente ${count} digitos`,
+    digitsOnly: "Debe contener solo digitos",
+    invalidEmail: "Direccion de correo electronico no valida",
+    invalidFormat: "Formato no valido",
+    invalidValue: "Valor no valido",
+    alphanumericRange: "Debe ser alfanumerico y tener entre 1 y 20 caracteres",
+  },
+  fr: {
+    required: "Obligatoire",
+    minChars: (count) => `Doit contenir au moins ${count} caracteres`,
+    maxChars: (count) => `Doit contenir au maximum ${count} caracteres`,
+    exactDigits: (count) => `Doit contenir exactement ${count} chiffres`,
+    digitsOnly: "Doit contenir uniquement des chiffres",
+    invalidEmail: "Adresse e-mail invalide",
+    invalidFormat: "Format invalide",
+    invalidValue: "Valeur invalide",
+    alphanumericRange: "Doit etre alphanumerique, 1 a 20 caracteres",
+  },
+  hr: {
+    required: "Obavezno",
+    minChars: (count) => `Mora sadrzavati najmanje ${count} znakova`,
+    maxChars: (count) => `Smije sadrzavati najvise ${count} znakova`,
+    exactDigits: (count) => `Mora sadrzavati tocno ${count} znamenke`,
+    digitsOnly: "Mora sadrzavati samo znamenke",
+    invalidEmail: "Neispravna e-mail adresa",
+    invalidFormat: "Neispravan format",
+    invalidValue: "Neispravna vrijednost",
+    alphanumericRange: "Mora biti alfanumericko, 1-20 znakova",
+  },
+  bg: {
+    required: "Zadalzhitelno",
+    minChars: (count) => `Tryabva da sadrzha pone ${count} znaka`,
+    maxChars: (count) => `Mozhe da sadrzha nai-mnogo ${count} znaka`,
+    exactDigits: (count) => `Tryabva da sadrzha tochno ${count} cifri`,
+    digitsOnly: "Tryabva da sadrzha samo cifri",
+    invalidEmail: "Nevaliden email adres",
+    invalidFormat: "Nevaliden format",
+    invalidValue: "Nevalidna stoinost",
+    alphanumericRange: "Tryabva da e bukveno-cifrovo, 1-20 znaka",
+  },
+  cs: {
+    required: "Povinne",
+    minChars: (count) => `Musi obsahovat alespon ${count} znaku`,
+    maxChars: (count) => `Muze obsahovat nejvyse ${count} znaku`,
+    exactDigits: (count) => `Musi obsahovat presne ${count} cislice`,
+    digitsOnly: "Musi obsahovat pouze cislice",
+    invalidEmail: "Neplatna e-mailova adresa",
+    invalidFormat: "Neplatny format",
+    invalidValue: "Neplatna hodnota",
+    alphanumericRange: "Musi byt alfanumericke, 1-20 znaku",
+  },
+  et: {
+    required: "Kohustuslik",
+    minChars: (count) => `Peab sisaldama vahemalt ${count} marki`,
+    maxChars: (count) => `Voib sisaldada kuni ${count} marki`,
+    exactDigits: (count) => `Peab sisaldama tapselt ${count} numbrit`,
+    digitsOnly: "Tohib sisaldada ainult numbreid",
+    invalidEmail: "Vigane e-posti aadress",
+    invalidFormat: "Vigane vorming",
+    invalidValue: "Vigane vaartus",
+    alphanumericRange: "Peab olema tahe- ja numbrimarkidega, 1-20 marki",
+  },
+  fi: {
+    required: "Pakollinen",
+    minChars: (count) => `Vahintaan ${count} merkkiä`,
+    maxChars: (count) => `Enintaan ${count} merkkiä`,
+    exactDigits: (count) => `Taytyy olla tasan ${count} numeroa`,
+    digitsOnly: "Saa sisaltaa vain numeroita",
+    invalidEmail: "Virheellinen sahkopostiosoite",
+    invalidFormat: "Virheellinen muoto",
+    invalidValue: "Virheellinen arvo",
+    alphanumericRange: "Taytyy olla aakkosnumeerinen, 1-20 merkkia",
+  },
+  it: {
+    required: "Obbligatorio",
+    minChars: (count) => `Deve contenere almeno ${count} caratteri`,
+    maxChars: (count) => `Deve contenere al massimo ${count} caratteri`,
+    exactDigits: (count) => `Deve contenere esattamente ${count} cifre`,
+    digitsOnly: "Deve contenere solo cifre",
+    invalidEmail: "Indirizzo email non valido",
+    invalidFormat: "Formato non valido",
+    invalidValue: "Valore non valido",
+    alphanumericRange: "Deve essere alfanumerico, 1-20 caratteri",
+  },
+  nl: {
+    required: "Verplicht",
+    minChars: (count) => `Moet minimaal ${count} tekens bevatten`,
+    maxChars: (count) => `Mag maximaal ${count} tekens bevatten`,
+    exactDigits: (count) => `Moet precies ${count} cijfers bevatten`,
+    digitsOnly: "Mag alleen cijfers bevatten",
+    invalidEmail: "Ongeldig e-mailadres",
+    invalidFormat: "Ongeldig formaat",
+    invalidValue: "Ongeldige waarde",
+    alphanumericRange: "Moet alfanumeriek zijn, 1-20 tekens",
+  },
+  nb: {
+    required: "Obligatorisk",
+    minChars: (count) => `Må inneholde minst ${count} tegn`,
+    maxChars: (count) => `Kan inneholde maksimalt ${count} tegn`,
+    exactDigits: (count) => `Må inneholde nøyaktig ${count} sifre`,
+    digitsOnly: "Må bare inneholde sifre",
+    invalidEmail: "Ugyldig e-postadresse",
+    invalidFormat: "Ugyldig format",
+    invalidValue: "Ugyldig verdi",
+    alphanumericRange: "Må være alfanumerisk, 1-20 tegn",
+  },
+  pl: {
+    required: "Wymagane",
+    minChars: (count) => `Musi zawierac co najmniej ${count} znakow`,
+    maxChars: (count) => `Moze zawierac maksymalnie ${count} znakow`,
+    exactDigits: (count) => `Musi zawierac dokladnie ${count} cyfry`,
+    digitsOnly: "Musi zawierac tylko cyfry",
+    invalidEmail: "Nieprawidlowy adres e-mail",
+    invalidFormat: "Nieprawidlowy format",
+    invalidValue: "Nieprawidlowa wartosc",
+    alphanumericRange: "Musi byc alfanumeryczne, 1-20 znakow",
+  },
+  pt: {
+    required: "Obrigatorio",
+    minChars: (count) => `Tem de ter pelo menos ${count} caracteres`,
+    maxChars: (count) => `Tem de ter no maximo ${count} caracteres`,
+    exactDigits: (count) => `Tem de ter exatamente ${count} digitos`,
+    digitsOnly: "Tem de conter apenas digitos",
+    invalidEmail: "Endereco de email invalido",
+    invalidFormat: "Formato invalido",
+    invalidValue: "Valor invalido",
+    alphanumericRange: "Tem de ser alfanumerico, 1-20 caracteres",
+  },
+  sk: {
+    required: "Povinne",
+    minChars: (count) => `Musi obsahovat aspon ${count} znakov`,
+    maxChars: (count) => `Moze obsahovat najviac ${count} znakov`,
+    exactDigits: (count) => `Musi obsahovat presne ${count} cislice`,
+    digitsOnly: "Musi obsahovat iba cislice",
+    invalidEmail: "Neplatna e-mailova adresa",
+    invalidFormat: "Neplatny format",
+    invalidValue: "Neplatna hodnota",
+    alphanumericRange: "Musi byt alfanumericke, 1-20 znakov",
+  },
+  sl: {
+    required: "Obvezno",
+    minChars: (count) => `Mora vsebovati vsaj ${count} znakov`,
+    maxChars: (count) => `Lahko vsebuje najvec ${count} znakov`,
+    exactDigits: (count) => `Mora vsebovati natanko ${count} stevilke`,
+    digitsOnly: "Vsebovati mora samo stevilke",
+    invalidEmail: "Neveljaven e-postni naslov",
+    invalidFormat: "Neveljaven format",
+    invalidValue: "Neveljavna vrednost",
+    alphanumericRange: "Mora biti alfanumericno, 1-20 znakov",
+  },
+  sv: {
+    required: "Obligatoriskt",
+    minChars: (count) => `Maste innehalla minst ${count} tecken`,
+    maxChars: (count) => `Far innehalla hogst ${count} tecken`,
+    exactDigits: (count) => `Maste innehalla exakt ${count} siffror`,
+    digitsOnly: "Får bara innehålla siffror",
+    invalidEmail: "Ogiltig e-postadress",
+    invalidFormat: "Ogiltigt format",
+    invalidValue: "Ogiltigt varde",
+    alphanumericRange: "Maste vara alfanumeriskt, 1-20 tecken",
+  },
+  is: {
+    required: "Skyldureitur",
+    minChars: (count) => `Verdur ad innihalda ad minnsta kosti ${count} stafi`,
+    maxChars: (count) => `Ma innihalda ad haesta lagi ${count} stafi`,
+    exactDigits: (count) => `Verdur ad innihalda natturlega ${count} tolustafi`,
+    digitsOnly: "Ma einungis innihalda tolustafi",
+    invalidEmail: "Ogiltt netfang",
+    invalidFormat: "Ogilt snið",
+    invalidValue: "Ogilt gildi",
+    alphanumericRange: "Verdur ad vera bokstafa- og tolustafablandad, 1-20 stafir",
+  },
+};
+
+const tooSmallStringRegex = /^Too small: expected string to have >=(\d+) characters$/;
+const tooBigStringRegex = /^Too big: expected string to have <=(\d+) characters$/;
+const invalidPatternRegex = /^Invalid string: must match pattern (\/.*\/)$/;
+const invalidInputRegex = /^Invalid input: expected .*$/;
+
+function getDictionary(locale?: string): ValidationDictionary {
+  const language = getLocaleLanguage(locale);
+  return dictionaries[language] ?? dictionaries.en;
+}
+
+function normalizePattern(pattern: string): string {
+  return pattern.replaceAll("\\\\", "\\");
+}
+
+export function getValidationLocale(explicitLocale?: string): string {
+  if (explicitLocale?.trim()) return explicitLocale;
+
+  if (typeof document !== "undefined") {
+    const htmlLang = document.documentElement.lang?.trim();
+    if (htmlLang) return htmlLang;
+  }
+
+  if (typeof navigator !== "undefined" && navigator.language) {
+    return navigator.language;
+  }
+
+  return "en";
+}
+
+export function translateZodValidationMessage(message?: string, locale?: string): string | undefined {
+  if (!message) return message;
+
+  const dict = getDictionary(locale);
+
+  if (message === "Invalid email address") {
+    return dict.invalidEmail;
+  }
+
+  if (message === "Must be alphanumeric, 1-20 characters") {
+    return dict.alphanumericRange;
+  }
+
+  const tooSmallMatch = message.match(tooSmallStringRegex);
+  if (tooSmallMatch) {
+    const count = Number.parseInt(tooSmallMatch[1] || "0", 10);
+    return count <= 1 ? dict.required : dict.minChars(count);
+  }
+
+  const tooBigMatch = message.match(tooBigStringRegex);
+  if (tooBigMatch) {
+    const count = Number.parseInt(tooBigMatch[1] || "0", 10);
+    return dict.maxChars(count);
+  }
+
+  const invalidPatternMatch = message.match(invalidPatternRegex);
+  if (invalidPatternMatch) {
+    const pattern = normalizePattern(invalidPatternMatch[1] || "");
+
+    if (pattern === "/^\\d+$/") {
+      return dict.digitsOnly;
+    }
+
+    const exactDigitsMatch = pattern.match(/^\/\^\\d\{(\d+)\}\$\/$/);
+    if (exactDigitsMatch) {
+      return dict.exactDigits(Number.parseInt(exactDigitsMatch[1] || "0", 10));
+    }
+
+    return dict.invalidFormat;
+  }
+
+  if (invalidInputRegex.test(message)) {
+    return dict.invalidValue;
+  }
+
+  return message;
+}

package/src/providers/entities-provider.tsx

@@ -3,8 +3,8 @@ import type { ReactNode } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useCookies } from "react-cookie";
 import { ACTIVE_ENTITY_COOKIE, ACTIVE_ENVIRONMENT_COOKIE } from "@/ui/components/entities/keys";
-
-import { useSDK } from "@/ui/providers/sdk-provider";
+import { useSpaceInvoicesRuntime } from "@/ui/providers/space-invoices-provider";
+import { entities as entitiesApi } from "../../../js-sdk/src/sdk/entities";
 
 import { EntitiesContext, type Entity, type EntityEnvironment } from "./entities-context";
 
@@ -29,7 +29,7 @@ type EntitiesProviderProps = {
   /** When provided, determines environment from URL instead of cookie. true = sandbox, false = live. */
   isSandbox?: boolean;
   /** Called when urlEntityId is not found in any environment, allowing parent to try other accounts */
-  onEntityNotFound?: (entityId: string) => boolean | void | Promise<boolean | void>;
+  onEntityNotFound?: (entityId: string) => boolean | undefined | Promise<boolean | undefined>;
 };
 
 export function EntitiesProvider({
@@ -41,7 +41,7 @@ export function EntitiesProvider({
   isSandbox,
   onEntityNotFound,
 }: EntitiesProviderProps) {
-  const { sdk, isInitialized } = useSDK();
+  const { hasAccessToken, isResolvingAccessToken } = useSpaceInvoicesRuntime();
   const [cookies, setCookie, removeCookie] = useCookies([ACTIVE_ENTITY_COOKIE, ACTIVE_ENVIRONMENT_COOKIE]);
   const isInitialMount = useRef(true);
   const initialEnvironmentFromCookie = cookies[ACTIVE_ENVIRONMENT_COOKIE] as EntityEnvironment | undefined;
@@ -91,13 +91,10 @@ export function EntitiesProvider({
   } = useQuery({
     queryKey: [...ENTITIES_QUERY_KEY, environment],
     queryFn: async () => {
-      if (!sdk) return [];
-
-      // Pass environment to filter entities for user tokens
-      const response = await sdk.entities.list({ limit: 100, environment });
+      const response = await entitiesApi.list({ limit: 100, environment });
       return response.data;
     },
-    enabled: !!sdk && isInitialized,
+    enabled: hasAccessToken && !isResolvingAccessToken,
     staleTime: 1000 * 60 * 5,
     gcTime: 1000 * 60 * 60,
     retry: 2,
@@ -119,7 +116,28 @@ export function EntitiesProvider({
       const refetchKey = `${urlEntityId}:${environment}`;
       if (emptyUrlEntityRefetchKeyRef.current !== refetchKey) {
         emptyUrlEntityRefetchKeyRef.current = refetchKey;
-        void refetch();
+        void refetch().then((result) => {
+          if ((result.data?.length ?? 0) > 0 || hasCalledNoEntities.current) return;
+          if (resolvingUrlEntityRef.current === urlEntityId) return;
+          resolvingUrlEntityRef.current = urlEntityId;
+
+          if (!onEntityNotFound) {
+            hasCalledNoEntities.current = true;
+            onNoEntities?.();
+            return;
+          }
+
+          void Promise.resolve(onEntityNotFound(urlEntityId))
+            .then((resolved) => {
+              if (resolved) return;
+              hasCalledNoEntities.current = true;
+              onNoEntities?.();
+            })
+            .catch(() => {
+              hasCalledNoEntities.current = true;
+              onNoEntities?.();
+            });
+        });
         return;
       }
 
@@ -153,10 +171,10 @@ export function EntitiesProvider({
     }
 
     // Try the other environment before calling onNoEntities
-    if (!hasTriedFallback.current && sdk) {
+    if (!hasTriedFallback.current && hasAccessToken) {
       hasTriedFallback.current = true;
       const altEnv = environment === "live" ? "sandbox" : "live";
-      sdk.entities
+      entitiesApi
         .list({ limit: 1, environment: altEnv })
         .then((res) => {
           if (res.data.length > 0) {
@@ -184,7 +202,7 @@ export function EntitiesProvider({
     onEntityNotFound,
     onNoEntities,
     refetch,
-    sdk,
+    hasAccessToken,
     environment,
     isSandbox,
     urlEntityId,
@@ -358,7 +376,7 @@ export function EntitiesProvider({
   );
 
   // Show loading state only if entities are still loading
-  if (isLoading) {
+  if (isResolvingAccessToken || isLoading) {
     return <LoadingFallback />;
   }
 

package/src/providers/sdk-provider.tsx

@@ -1,9 +1,13 @@
-import SDK from "@spaceinvoices/js-sdk";
+import type SDK from "@spaceinvoices/js-sdk";
 import type { ReactNode } from "react";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
-
 import { AUTH_COOKIES } from "@/ui/lib/auth";
 import { flushCookies, getCookie } from "@/ui/lib/browser-cookies";
+import {
+  SpaceInvoicesProvider,
+  useAccessToken as useRuntimeAccessToken,
+  useSpaceInvoicesRuntime,
+} from "@/ui/providers/space-invoices-provider";
 
 /**
  * SDK context type definition
@@ -38,6 +42,8 @@ type SDKProviderProps = {
   fallbackUnauthorized?: ReactNode;
 };
 
+type LegacySDKContextBridgeProps = SDKProviderProps;
+
 /**
  * SDK Provider component
  * Responsible for initializing the SDK and providing it to the application
@@ -76,7 +82,8 @@ export function SDKProvider({
       }
 
       const basePath = import.meta.env?.VITE_API_URL || import.meta.env?.BUN_PUBLIC_API_URL || undefined;
-      const newSDK = new SDK({
+      const { default: SDKConstructor } = await import("@spaceinvoices/js-sdk");
+      const newSDK = new SDKConstructor({
         accessToken: token,
         ...(basePath && { basePath }),
         onUnauthorized: (response: Response) => {
@@ -110,6 +117,7 @@ export function SDKProvider({
       isLoading,
       error,
       reinitialize: initializeSDK,
+      accessToken: getCookie(AUTH_COOKIES.TOKEN) ?? null,
     }),
     [sdk, isInitialized, isLoading, error, initializeSDK],
   );
@@ -128,6 +136,104 @@ export function SDKProvider({
     return <>{fallbackUnauthorized}</>;
   }
 
+  return (
+    <SpaceInvoicesProvider
+      accessToken={value.accessToken ?? ""}
+      basePath={import.meta.env?.VITE_API_URL || import.meta.env?.BUN_PUBLIC_API_URL || undefined}
+      onUnauthorized={(response) => {
+        flushCookies();
+        onUnauthorized?.(response);
+      }}
+    >
+      <SDKContext.Provider value={value}>{children}</SDKContext.Provider>
+    </SpaceInvoicesProvider>
+  );
+}
+
+export function LegacySDKContextBridge({
+  children,
+  onUnauthorized,
+  fallbackLoading = (
+    <div className="fixed inset-0 flex items-center justify-center bg-background/50">
+      <div className="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent" />
+    </div>
+  ),
+  fallbackError = (error) => <div className="p-4 text-red-500">Error initializing SDK: {error.message}</div>,
+  fallbackUnauthorized = <div className="p-4 text-amber-500">No SDK available. Please log in first.</div>,
+}: LegacySDKContextBridgeProps) {
+  const runtime = useSpaceInvoicesRuntime();
+  const [sdk, setSdk] = useState<SDK | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const initializeSDK = useCallback(async () => {
+    if (runtime.isResolvingAccessToken) {
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      if (!runtime.accessToken) {
+        setSdk(null);
+        return;
+      }
+
+      const { default: SDKConstructor } = await import("@spaceinvoices/js-sdk");
+      const newSDK = new SDKConstructor({
+        accessToken: runtime.accessToken,
+        ...(runtime.basePath && { basePath: runtime.basePath }),
+        ...(runtime.clientName && { clientName: runtime.clientName }),
+        ...(onUnauthorized && { onUnauthorized }),
+      });
+
+      setSdk(newSDK);
+    } catch (cause) {
+      setSdk(null);
+      setError(cause instanceof Error ? cause : new Error("Failed to initialize SDK"));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [onUnauthorized, runtime.accessToken, runtime.basePath, runtime.clientName, runtime.isResolvingAccessToken]);
+
+  useEffect(() => {
+    void initializeSDK();
+  }, [initializeSDK]);
+
+  const combinedError = runtime.error ?? error;
+  const value = useMemo(
+    () => ({
+      sdk: sdk as SDK,
+      isInitialized: Boolean(sdk) && runtime.hasAccessToken,
+      isLoading: runtime.isResolvingAccessToken || isLoading,
+      error: combinedError,
+      reinitialize: initializeSDK,
+      accessToken: runtime.accessToken,
+    }),
+    [
+      sdk,
+      runtime.hasAccessToken,
+      runtime.isResolvingAccessToken,
+      isLoading,
+      combinedError,
+      initializeSDK,
+      runtime.accessToken,
+    ],
+  );
+
+  if (runtime.isResolvingAccessToken || isLoading) {
+    return <>{fallbackLoading}</>;
+  }
+
+  if (combinedError) {
+    return <>{fallbackError(combinedError)}</>;
+  }
+
+  if (!sdk || !runtime.hasAccessToken) {
+    return <>{fallbackUnauthorized}</>;
+  }
+
   return <SDKContext.Provider value={value}>{children}</SDKContext.Provider>;
 }
 
@@ -159,13 +265,7 @@ export function useSDKOptional() {
  * Checks context.accessToken first (set by embed mode), then falls back to cookies
  */
 export function useAccessToken(): string | null {
-  const context = useContext(SDKContext);
-  if (!context?.sdk) return null;
-
-  // Embed mode passes token explicitly via context
-  if (context.accessToken) return context.accessToken;
-
-  // Normal mode: read from auth cookie
-  const token = getCookie(AUTH_COOKIES.TOKEN);
-  return token ?? null;
+  const runtimeToken = useRuntimeAccessToken();
+  if (runtimeToken) return runtimeToken;
+  return getCookie(AUTH_COOKIES.TOKEN) ?? null;
 }

package/src/providers/space-invoices-provider.tsx

@@ -0,0 +1,129 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { setAccountId } from "../../../js-sdk/src/mutator/custom-fetch";
+import { initSDK } from "../../../js-sdk/src/sdk/init";
+import type { SDKConfig } from "../../../js-sdk/src/sdk/types";
+
+export type SpaceInvoicesRuntimeContextType = {
+  accessToken: string | null;
+  accountId: string | null;
+  basePath?: string;
+  clientName?: string;
+  hasAccessToken: boolean;
+  isResolvingAccessToken: boolean;
+  error: Error | null;
+  getAccessToken: () => Promise<string>;
+};
+
+const SpaceInvoicesRuntimeContext = createContext<SpaceInvoicesRuntimeContextType | undefined>(undefined);
+
+SpaceInvoicesRuntimeContext.displayName = "SpaceInvoicesRuntimeContext";
+
+export type SpaceInvoicesProviderProps = {
+  children: ReactNode;
+  accessToken: SDKConfig["accessToken"];
+  accountId?: string | null;
+  basePath?: string;
+  clientName?: string;
+  onUnauthorized?: SDKConfig["onUnauthorized"];
+};
+
+async function resolveAccessToken(accessToken: SDKConfig["accessToken"]): Promise<string> {
+  const resolved = typeof accessToken === "function" ? await accessToken() : accessToken;
+  return resolved ?? "";
+}
+
+export function SpaceInvoicesProvider({
+  children,
+  accessToken,
+  accountId = null,
+  basePath,
+  clientName,
+  onUnauthorized,
+}: SpaceInvoicesProviderProps) {
+  const [resolvedAccessToken, setResolvedAccessToken] = useState<string | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [isResolvingAccessToken, setIsResolvingAccessToken] = useState(true);
+  const onUnauthorizedRef = useRef(onUnauthorized);
+
+  useEffect(() => {
+    onUnauthorizedRef.current = onUnauthorized;
+  }, [onUnauthorized]);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    setIsResolvingAccessToken(true);
+    setError(null);
+
+    initSDK({
+      accessToken,
+      ...(basePath && { basePath }),
+      ...(clientName && { clientName }),
+      ...(onUnauthorizedRef.current && {
+        onUnauthorized: (response) => onUnauthorizedRef.current?.(response),
+      }),
+    });
+
+    void resolveAccessToken(accessToken)
+      .then((token) => {
+        if (cancelled) return;
+        setResolvedAccessToken(token || null);
+      })
+      .catch((cause) => {
+        if (cancelled) return;
+        setResolvedAccessToken(null);
+        setError(cause instanceof Error ? cause : new Error("Failed to resolve Space Invoices access token"));
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setIsResolvingAccessToken(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [accessToken, basePath, clientName]);
+
+  useEffect(() => {
+    setAccountId(accountId);
+  }, [accountId]);
+
+  const value = useMemo<SpaceInvoicesRuntimeContextType>(
+    () => ({
+      accessToken: resolvedAccessToken,
+      accountId,
+      basePath,
+      clientName,
+      hasAccessToken: Boolean(resolvedAccessToken),
+      isResolvingAccessToken,
+      error,
+      getAccessToken: () => resolveAccessToken(accessToken),
+    }),
+    [resolvedAccessToken, accountId, basePath, clientName, isResolvingAccessToken, error, accessToken],
+  );
+
+  return <SpaceInvoicesRuntimeContext.Provider value={value}>{children}</SpaceInvoicesRuntimeContext.Provider>;
+}
+
+export function useSpaceInvoicesRuntime() {
+  const context = useContext(SpaceInvoicesRuntimeContext);
+
+  if (!context) {
+    throw new Error("useSpaceInvoicesRuntime must be used within a SpaceInvoicesProvider");
+  }
+
+  return context;
+}
+
+export function useSpaceInvoicesRuntimeOptional() {
+  return useContext(SpaceInvoicesRuntimeContext) ?? null;
+}
+
+export function useAccessToken() {
+  const context = useSpaceInvoicesRuntimeOptional();
+  return context?.accessToken ?? null;
+}