@spaceinvoices/react-ui 0.1.1

package/src/providers/sdk-provider.tsx

@@ -0,0 +1,164 @@
+import SDK from "@spaceinvoices/js-sdk";
+import type { ReactNode } from "react";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+
+import { AUTH_COOKIES } from "@/ui/lib/auth";
+import { flushCookies, getCookie } from "@/ui/lib/browser-cookies";
+
+/**
+ * SDK context type definition
+ * Note: SDK is guaranteed to be non-null when accessing this context
+ * The provider blocks rendering until SDK is initialized
+ */
+type SDKContextType = {
+  sdk: SDK; // Non-null - guaranteed by provider
+  isInitialized: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  reinitialize: () => Promise<void>;
+};
+
+/**
+ * SDK context with default values
+ * Note: These defaults are never actually used because the provider
+ * blocks rendering until SDK is initialized
+ */
+const SDKContext = createContext<SDKContextType | undefined>(undefined);
+
+// Add a name to help with debugging
+SDKContext.displayName = "SDKContext";
+
+type SDKProviderProps = {
+  children: ReactNode;
+  onUnauthorized?: (response: Response) => void;
+  fallbackLoading?: ReactNode;
+  fallbackError?: (error: Error) => ReactNode;
+  fallbackUnauthorized?: ReactNode;
+};
+
+/**
+ * SDK Provider component
+ * Responsible for initializing the SDK and providing it to the application
+ */
+export function SDKProvider({
+  children,
+  onUnauthorized,
+  fallbackLoading = <div className="p-4">Initializing SDK...</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>,
+}: SDKProviderProps) {
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [sdk, setSdk] = useState<SDK | null>(null);
+
+  /**
+   * Initialize the SDK with the current auth token
+   */
+  const initializeSDK = async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const token = getCookie(AUTH_COOKIES.TOKEN);
+
+      if (!token) {
+        setIsInitialized(false);
+        setSdk(null);
+        setIsLoading(false);
+        return;
+      }
+
+      const basePath = import.meta.env?.VITE_API_URL || import.meta.env?.BUN_PUBLIC_API_URL || undefined;
+      const newSDK = new SDK({
+        accessToken: token,
+        ...(basePath && { basePath }),
+        onUnauthorized: (response: Response) => {
+          flushCookies();
+          onUnauthorized?.(response);
+        },
+      });
+
+      setSdk(newSDK);
+      setIsInitialized(true);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error("Failed to initialize SDK"));
+      setSdk(null);
+      setIsInitialized(false);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  // Initialize SDK on component mount
+  // biome-ignore lint/correctness/useExhaustiveDependencies: initializeSDK is intentionally omitted - should only run once on mount
+  useEffect(() => {
+    initializeSDK();
+  }, []); // Empty dependency array - only run on mount
+
+  // IMPORTANT: useMemo must be called BEFORE any conditional returns
+  // to satisfy React's Rules of Hooks
+  // biome-ignore lint/correctness/useExhaustiveDependencies: initializeSDK is stable (doesn't change) and including it would cause unnecessary re-renders
+  const value = useMemo(
+    () => ({
+      sdk: sdk as SDK, // Will be non-null when children render (checked below)
+      isInitialized,
+      isLoading,
+      error,
+      reinitialize: initializeSDK,
+    }),
+    [sdk, isInitialized, isLoading, error], // Don't include initializeSDK - it's stable but causes re-renders
+  );
+
+  // Render appropriate UI based on SDK state
+  // Children only render when SDK is guaranteed non-null
+  if (isLoading) {
+    return <>{fallbackLoading}</>;
+  }
+
+  if (error) {
+    return <>{fallbackError(error)}</>;
+  }
+
+  if (!sdk || !isInitialized) {
+    return <>{fallbackUnauthorized}</>;
+  }
+
+  return <SDKContext.Provider value={value}>{children}</SDKContext.Provider>;
+}
+
+/**
+ * Hook to access the SDK context
+ * @throws Error if used outside of SDKProvider
+ */
+export function useSDK() {
+  const context = useContext(SDKContext);
+
+  if (context === undefined) {
+    throw new Error("useSDK must be used within an SDKProvider");
+  }
+
+  return context;
+}
+
+/**
+ * Optional hook that returns null if not in SDKProvider
+ * Useful for components that may be used with or without SDK context
+ */
+export function useSDKOptional() {
+  const context = useContext(SDKContext);
+  return context ?? null;
+}
+
+/**
+ * Get access token from SDK context (helper for WLSubscriptionProvider)
+ */
+export function useAccessToken(): string | null {
+  const context = useContext(SDKContext);
+  if (!context?.sdk) return null;
+
+  // Access token is stored in SDK configuration
+  // We need to get it from the auth cookie since SDK doesn't expose it directly
+  const token = getCookie(AUTH_COOKIES.TOKEN);
+  return token ?? null;
+}

package/src/providers/white-label-provider.tsx

@@ -0,0 +1,91 @@
+import type { ReactNode } from "react";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+
+export type WhiteLabelConfig = {
+  slug: string;
+  name: string;
+  hiddenFeatures: string[]; // Features hidden from UI (still available via API)
+};
+
+// Default config until API responds (Space Invoices = all features visible)
+const DEFAULT_CONFIG: WhiteLabelConfig = {
+  slug: "space-invoices",
+  name: "Space Invoices",
+  hiddenFeatures: [],
+};
+
+type WhiteLabelContextType = WhiteLabelConfig & {
+  /** Check if a feature is visible (not hidden) for this white-label */
+  isFeatureVisible: (feature: string) => boolean;
+  isLoading: boolean;
+};
+
+const WhiteLabelContext = createContext<WhiteLabelContextType | undefined>(undefined);
+
+// Add a name to help with debugging
+WhiteLabelContext.displayName = "WhiteLabelContext";
+
+type WhiteLabelProviderProps = {
+  children: ReactNode;
+  /** Optional API base URL (defaults to empty string for same-origin) */
+  apiBaseUrl?: string;
+};
+
+/**
+ * WhiteLabelProvider component
+ * Fetches white-label configuration from the API and provides it to the application
+ */
+export function WhiteLabelProvider({ children, apiBaseUrl = "" }: WhiteLabelProviderProps) {
+  const [config, setConfig] = useState<WhiteLabelConfig>(DEFAULT_CONFIG);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    const fetchConfig = async () => {
+      try {
+        const response = await fetch(`${apiBaseUrl}/white-labels/current`);
+        if (response.ok) {
+          const data = await response.json();
+          // Map snake_case API response to camelCase internal state
+          setConfig({
+            slug: data.slug,
+            name: data.name,
+            hiddenFeatures: data.hidden_features,
+          });
+        }
+      } catch {
+        // Use default config if fetch fails
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchConfig();
+  }, [apiBaseUrl]);
+
+  const isFeatureVisible = (feature: string) => !config.hiddenFeatures.includes(feature);
+
+  const value = useMemo(
+    () => ({
+      ...config,
+      isFeatureVisible,
+      isLoading,
+    }),
+    [config, isLoading, isFeatureVisible],
+  );
+
+  return <WhiteLabelContext.Provider value={value}>{children}</WhiteLabelContext.Provider>;
+}
+
+/**
+ * Hook to access the white-label context
+ * @throws Error if used outside of WhiteLabelProvider
+ */
+export function useWhiteLabel() {
+  const context = useContext(WhiteLabelContext);
+
+  if (context === undefined) {
+    throw new Error("useWhiteLabel must be used within a WhiteLabelProvider");
+  }
+
+  return context;
+}

package/src/providers/wl-subscription-provider.tsx

@@ -0,0 +1,277 @@
+import type { ReactNode } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { useEntitiesOptional } from "./entities-context";
+import { useAccessToken } from "./sdk-provider";
+
+// ============================================
+// TYPES
+// ============================================
+
+export type PlanLimits = {
+  documents_per_month: number | null;
+} | null;
+
+export type WhiteLabelPlan = {
+  id: string;
+  slug: string;
+  name: string;
+  billing_interval: string | null;
+  base_price_cents: number | null;
+  limits: PlanLimits;
+  features: string[];
+  is_free: boolean;
+  display_order: number;
+};
+
+export type UsageStats = {
+  documents_count: number;
+  documents_limit: number | null;
+  period_start: string;
+  period_end: string;
+};
+
+export type CurrentSubscription = {
+  plan: WhiteLabelPlan;
+  status: string;
+  billing_interval: string | null;
+  current_period_start: string;
+  current_period_end: string;
+  usage: UsageStats;
+};
+
+// Known gated features for Apollo
+export type GatedFeature =
+  | "furs"
+  | "eslog"
+  | "recurring"
+  | "email_sending"
+  | "custom_templates"
+  | "api_access"
+  | "webhooks"
+  | "priority_support";
+
+// ============================================
+// CONTEXT
+// ============================================
+
+type WLSubscriptionContextType = {
+  subscription: CurrentSubscription | null;
+  plan: WhiteLabelPlan | null;
+  usage: UsageStats | null;
+  availablePlans: WhiteLabelPlan[];
+  isLoading: boolean;
+  error: string | null;
+
+  // Feature/limit checks
+  hasFeature: (feature: GatedFeature | string) => boolean;
+  isOverLimit: (resource: "documents") => boolean;
+  getUsagePercentage: (resource: "documents") => number;
+
+  // Refresh data
+  refresh: () => Promise<void>;
+};
+
+const WLSubscriptionContext = createContext<WLSubscriptionContextType | undefined>(undefined);
+
+WLSubscriptionContext.displayName = "WLSubscriptionContext";
+
+// ============================================
+// DEFAULT STATE
+// ============================================
+
+// Default subscription (unlimited, all features) for non-WL users
+const DEFAULT_SUBSCRIPTION: CurrentSubscription = {
+  plan: {
+    id: "unlimited",
+    slug: "unlimited",
+    name: "Unlimited",
+    billing_interval: null,
+    base_price_cents: null,
+    limits: null,
+    features: [], // Empty = all features
+    is_free: true,
+    display_order: 0,
+  },
+  status: "active",
+  billing_interval: null,
+  current_period_start: new Date().toISOString(),
+  current_period_end: new Date().toISOString(),
+  usage: {
+    documents_count: 0,
+    documents_limit: null,
+    period_start: new Date().toISOString(),
+    period_end: new Date().toISOString(),
+  },
+};
+
+// ============================================
+// PROVIDER
+// ============================================
+
+type WLSubscriptionProviderProps = {
+  children: ReactNode;
+  /** API base URL (required for authenticated requests) */
+  apiBaseUrl: string;
+};
+
+/**
+ * WLSubscriptionProvider component
+ * Fetches white-label subscription data and provides limit/feature checks.
+ * Must be nested inside EntitiesProvider and SDKProvider.
+ */
+export function WLSubscriptionProvider({ children, apiBaseUrl }: WLSubscriptionProviderProps) {
+  // Get entity and access token from existing context
+  const entitiesContext = useEntitiesOptional();
+  const accessToken = useAccessToken();
+
+  const entityId = entitiesContext?.activeEntity?.id ?? null;
+  const [subscription, setSubscription] = useState<CurrentSubscription>(DEFAULT_SUBSCRIPTION);
+  const [availablePlans, setAvailablePlans] = useState<WhiteLabelPlan[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchSubscription = useCallback(async () => {
+    if (!entityId || !accessToken) {
+      setSubscription(DEFAULT_SUBSCRIPTION);
+      setAvailablePlans([]);
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const headers = {
+        Authorization: `Bearer ${accessToken}`,
+        "x-entity-id": entityId,
+        "Content-Type": "application/json",
+      };
+
+      // Fetch current subscription
+      const subResponse = await fetch(`${apiBaseUrl}/white-label-subscriptions`, { headers });
+
+      if (subResponse.ok) {
+        const subData = await subResponse.json();
+        setSubscription(subData);
+      } else if (subResponse.status === 404) {
+        // No WL subscription = use default (unlimited)
+        setSubscription(DEFAULT_SUBSCRIPTION);
+      } else {
+        throw new Error(`Failed to fetch subscription: ${subResponse.status}`);
+      }
+
+      // Fetch available plans
+      const plansResponse = await fetch(`${apiBaseUrl}/white-label-subscriptions/plans`, {
+        headers,
+      });
+
+      if (plansResponse.ok) {
+        const plansData = await plansResponse.json();
+        setAvailablePlans(plansData.plans || []);
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to fetch subscription");
+      setSubscription(DEFAULT_SUBSCRIPTION);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [apiBaseUrl, entityId, accessToken]);
+
+  useEffect(() => {
+    fetchSubscription();
+  }, [fetchSubscription]);
+
+  // Check if feature is available on current plan
+  const hasFeature = useCallback(
+    (feature: GatedFeature | string): boolean => {
+      const plan = subscription.plan;
+
+      // Empty features array = all features included
+      if (plan.features.length === 0) {
+        return true;
+      }
+
+      return plan.features.includes(feature);
+    },
+    [subscription],
+  );
+
+  // Check if over document limit
+  const isOverLimit = useCallback(
+    (resource: "documents"): boolean => {
+      if (resource !== "documents") return false;
+
+      const { usage, plan } = subscription;
+      const limit = plan.limits?.documents_per_month;
+
+      if (limit === null || limit === undefined) {
+        return false; // No limit = never over
+      }
+
+      return usage.documents_count >= limit;
+    },
+    [subscription],
+  );
+
+  // Get usage percentage for resource
+  const getUsagePercentage = useCallback(
+    (resource: "documents"): number => {
+      if (resource !== "documents") return 0;
+
+      const { usage, plan } = subscription;
+      const limit = plan.limits?.documents_per_month;
+
+      if (limit === null || limit === undefined || limit === 0) {
+        return 0; // No limit = 0%
+      }
+
+      return Math.min(100, Math.round((usage.documents_count / limit) * 100));
+    },
+    [subscription],
+  );
+
+  const value = useMemo(
+    () => ({
+      subscription,
+      plan: subscription.plan,
+      usage: subscription.usage,
+      availablePlans,
+      isLoading,
+      error,
+      hasFeature,
+      isOverLimit,
+      getUsagePercentage,
+      refresh: fetchSubscription,
+    }),
+    [subscription, availablePlans, isLoading, error, hasFeature, isOverLimit, getUsagePercentage, fetchSubscription],
+  );
+
+  return <WLSubscriptionContext.Provider value={value}>{children}</WLSubscriptionContext.Provider>;
+}
+
+// ============================================
+// HOOK
+// ============================================
+
+/**
+ * Hook to access the white-label subscription context
+ * @throws Error if used outside of WLSubscriptionProvider
+ */
+export function useWLSubscription() {
+  const context = useContext(WLSubscriptionContext);
+
+  if (context === undefined) {
+    throw new Error("useWLSubscription must be used within a WLSubscriptionProvider");
+  }
+
+  return context;
+}
+
+/**
+ * Optional hook that returns null if not in WLSubscriptionProvider
+ * Useful for components that may be used with or without subscription context
+ */
+export function useWLSubscriptionOptional() {
+  return useContext(WLSubscriptionContext) ?? null;
+}

package/src/utils/string-helpers.ts

@@ -0,0 +1,111 @@
+/**
+ * String utility functions
+ */
+
+/**
+ * Capitalize first letter of string
+ * @param str - The string to capitalize
+ * @returns The capitalized string
+ *
+ * @example
+ * capitalize("hello") // "Hello"
+ * capitalize("HELLO") // "HELLO"
+ */
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Convert string to kebab-case
+ * @param str - The string to convert
+ * @returns The kebab-cased string
+ *
+ * @example
+ * toKebabCase("helloWorld") // "hello-world"
+ * toKebabCase("HelloWorld") // "hello-world"
+ */
+export function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/[\s_]+/g, "-")
+    .toLowerCase();
+}
+
+/**
+ * Convert string to PascalCase
+ * @param str - The string to convert
+ * @returns The PascalCased string
+ *
+ * @example
+ * toPascalCase("hello world") // "HelloWorld"
+ * toPascalCase("hello-world") // "HelloWorld"
+ */
+export function toPascalCase(str: string): string {
+  return str
+    .split(/[-_\s]+/)
+    .map((word) => capitalize(word))
+    .join("");
+}
+
+/**
+ * Convert string to camelCase
+ * @param str - The string to convert
+ * @returns The camelCased string
+ *
+ * @example
+ * toCamelCase("hello world") // "helloWorld"
+ * toCamelCase("hello-world") // "helloWorld"
+ */
+export function toCamelCase(str: string): string {
+  const pascal = toPascalCase(str);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+/**
+ * Convert string to Title Case
+ * @param str - The string to convert
+ * @returns The Title Cased string
+ *
+ * @example
+ * toTitleCase("hello world") // "Hello World"
+ * toTitleCase("hello-world") // "Hello World"
+ */
+export function toTitleCase(str: string): string {
+  return str
+    .split(/[-_\s]+/)
+    .map((word) => capitalize(word))
+    .join(" ");
+}
+
+/**
+ * Create a URL-friendly slug from a string
+ * @param str - The string to slugify
+ * @returns The slugified string
+ *
+ * @example
+ * slugify("Hello World!") // "hello-world"
+ * slugify("Hello   World") // "hello-world"
+ */
+export function slugify(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, "")
+    .replace(/[\s_]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Truncate a string to a maximum length
+ * @param str - The string to truncate
+ * @param maxLength - The maximum length
+ * @param suffix - The suffix to append (default: "...")
+ * @returns The truncated string
+ *
+ * @example
+ * truncate("Hello World", 5) // "Hello..."
+ * truncate("Hello", 10) // "Hello"
+ */
+export function truncate(str: string, maxLength: number, suffix = "..."): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - suffix.length) + suffix;
+}