@spaceinvoices/react-ui 0.4.8 → 0.4.11

package/src/providers/entities-provider.tsx

@@ -26,6 +26,10 @@ type EntitiesProviderProps = {
   cookieDomain?: string;
   /** When provided (from URL param), this entity ID is used as the source of truth instead of the cookie */
   urlEntityId?: string;
+  /** 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>;
 };
 
 export function EntitiesProvider({
@@ -34,6 +38,8 @@ export function EntitiesProvider({
   onNoEntities,
   cookieDomain,
   urlEntityId,
+  isSandbox,
+  onEntityNotFound,
 }: EntitiesProviderProps) {
   const { sdk, isInitialized } = useSDK();
   const [cookies, setCookie, removeCookie] = useCookies([ACTIVE_ENTITY_COOKIE, ACTIVE_ENVIRONMENT_COOKIE]);
@@ -44,12 +50,24 @@ export function EntitiesProvider({
   // URL entity ID takes precedence over cookie
   const resolvedEntityId = urlEntityId ?? initialEntityIdFromCookie;
 
+  // When isSandbox is provided (URL-driven), use it as source of truth; otherwise fall back to cookie
   const resolvedInitialEnvironment: EntityEnvironment =
-    initialEnvironmentFromCookie ?? (initialActiveEntity?.environment as EntityEnvironment | undefined) ?? "live";
+    isSandbox !== undefined
+      ? isSandbox
+        ? "sandbox"
+        : "live"
+      : (initialEnvironmentFromCookie ?? (initialActiveEntity?.environment as EntityEnvironment | undefined) ?? "live");
 
   const [environment, setEnvironmentState] = useState<EntityEnvironment>(resolvedInitialEnvironment);
   const previousEnvironment = useRef(environment);
 
+  // Sync environment with isSandbox prop when it changes (URL-driven navigation)
+  useEffect(() => {
+    if (isSandbox === undefined) return;
+    const target: EntityEnvironment = isSandbox ? "sandbox" : "live";
+    setEnvironmentState((current) => (current === target ? current : target));
+  }, [isSandbox]);
+
   // Store the initial entity ID (from URL or cookie) so we can match it when entities load
   const initialEntityIdRef = useRef(resolvedEntityId);
 
@@ -65,6 +83,7 @@ export function EntitiesProvider({
   const {
     data: entities = [],
     isLoading,
+    isFetching,
     refetch,
     isError,
     error,
@@ -88,10 +107,50 @@ export function EntitiesProvider({
   });
 
   // When no entities in current environment, check the other before giving up
+  // Skip auto-switch when isSandbox is explicitly set (URL-driven) — respect the user's intent
   const hasCalledNoEntities = useRef(false);
   const hasTriedFallback = useRef(false);
+  const resolvingUrlEntityRef = useRef<string | null>(null);
+  const emptyUrlEntityRefetchKeyRef = useRef<string | null>(null);
   useEffect(() => {
-    if (isLoading || entities.length > 0 || hasCalledNoEntities.current) return;
+    if (isLoading || isFetching || entities.length > 0 || hasCalledNoEntities.current) return;
+
+    if (urlEntityId) {
+      const refetchKey = `${urlEntityId}:${environment}`;
+      if (emptyUrlEntityRefetchKeyRef.current !== refetchKey) {
+        emptyUrlEntityRefetchKeyRef.current = refetchKey;
+        void refetch();
+        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;
+    }
+
+    // When environment is explicitly set via URL, don't auto-switch to the other environment
+    if (isSandbox !== undefined) {
+      hasCalledNoEntities.current = true;
+      onNoEntities?.();
+      return;
+    }
 
     // Try the other environment before calling onNoEntities
     if (!hasTriedFallback.current && sdk) {
@@ -118,7 +177,18 @@ export function EntitiesProvider({
     if (!hasTriedFallback.current) return;
     hasCalledNoEntities.current = true;
     onNoEntities?.();
-  }, [isLoading, entities.length, onNoEntities, sdk, environment]);
+  }, [
+    isLoading,
+    isFetching,
+    entities.length,
+    onEntityNotFound,
+    onNoEntities,
+    refetch,
+    sdk,
+    environment,
+    isSandbox,
+    urlEntityId,
+  ]);
 
   // Memoize entities to prevent unnecessary re-renders
   const memoizedEntities = useMemo(() => entities, [entities]);
@@ -130,6 +200,13 @@ export function EntitiesProvider({
     }
   }, [environment]);
 
+  useEffect(() => {
+    if (entities.length > 0) {
+      emptyUrlEntityRefetchKeyRef.current = null;
+      resolvingUrlEntityRef.current = null;
+    }
+  }, [entities.length]);
+
   // Sync active entity when entities list changes
   // Use ref to read current activeEntityState without causing re-runs
   const activeEntityRef = useRef(activeEntityState);
@@ -139,6 +216,8 @@ export function EntitiesProvider({
   useEffect(() => {
     if (urlEntityId) {
       initialEntityIdRef.current = urlEntityId;
+      resolvingUrlEntityRef.current = null;
+      emptyUrlEntityRefetchKeyRef.current = null;
     }
   }, [urlEntityId]);
 
@@ -201,6 +280,26 @@ export function EntitiesProvider({
     setEnvironmentState(altEnv);
   }, [urlEntityId, memoizedEntities, isLoading, environment]);
 
+  // After environment fallback has been attempted and entity is still not found, notify parent
+  const entityNotFoundCallbackFired = useRef<string | null>(null);
+  useEffect(() => {
+    if (!urlEntityId || !onEntityNotFound || isLoading) return;
+    if (memoizedEntities.length === 0) return;
+
+    const found = memoizedEntities.some((e) => e.id === urlEntityId);
+    if (found) {
+      entityNotFoundCallbackFired.current = null;
+      return;
+    }
+
+    // Only fire after the environment fallback has already been attempted for this entity
+    if (urlEntityFallbackAttempted.current !== urlEntityId) return;
+    if (entityNotFoundCallbackFired.current === urlEntityId) return;
+
+    entityNotFoundCallbackFired.current = urlEntityId;
+    onEntityNotFound(urlEntityId);
+  }, [urlEntityId, memoizedEntities, isLoading, onEntityNotFound]);
+
   const cookieOpts = useMemo(
     () => ({
       path: "/",

package/src/providers/form-footer-context.tsx

@@ -1,4 +1,4 @@
-import { createContext, type ReactNode, useContext, useEffect, useState } from "react";
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 
 type SecondaryAction = {
   label: string;
@@ -54,6 +54,37 @@ export function useFormFooterRegistration({
   secondaryAction,
 }: UseFormFooterRegistrationProps) {
   const { setFormFooter } = useFormFooterContext();
+  const onSubmitRef = useRef(onSubmit);
+  const secondaryActionRef = useRef(secondaryAction);
+
+  useEffect(() => {
+    onSubmitRef.current = onSubmit;
+  }, [onSubmit]);
+
+  useEffect(() => {
+    secondaryActionRef.current = secondaryAction;
+  }, [secondaryAction]);
+
+  const stableOnSubmit = useCallback(() => {
+    onSubmitRef.current?.();
+  }, []);
+
+  const hasSecondaryAction = !!secondaryAction;
+  const secondaryActionLabel = secondaryAction?.label;
+  const secondaryActionPending = secondaryAction?.isPending;
+  const stableSecondaryActionOnClick = useCallback(() => {
+    secondaryActionRef.current?.onClick();
+  }, []);
+
+  const stableSecondaryAction = useMemo(() => {
+    if (!hasSecondaryAction || !secondaryActionLabel) return undefined;
+
+    return {
+      label: secondaryActionLabel,
+      isPending: secondaryActionPending,
+      onClick: stableSecondaryActionOnClick,
+    };
+  }, [hasSecondaryAction, secondaryActionLabel, secondaryActionPending, stableSecondaryActionOnClick]);
 
   useEffect(() => {
     setFormFooter({
@@ -61,12 +92,14 @@ export function useFormFooterRegistration({
       isPending,
       isDirty,
       label,
-      onSubmit,
-      secondaryAction,
+      onSubmit: onSubmit ? stableOnSubmit : undefined,
+      secondaryAction: stableSecondaryAction,
     });
+  }, [formId, isPending, isDirty, label, onSubmit, setFormFooter, stableOnSubmit, stableSecondaryAction]);
 
+  useEffect(() => {
     return () => {
       setFormFooter(null);
     };
-  }, [formId, isPending, isDirty, label, onSubmit, secondaryAction, setFormFooter]);
+  }, [setFormFooter]);
 }

package/src/providers/sdk-provider.tsx

@@ -16,6 +16,8 @@ export type SDKContextType = {
   isLoading: boolean;
   error: Error | null;
   reinitialize: () => Promise<void>;
+  /** Optional explicit access token (used by embed mode where cookies aren't available) */
+  accessToken?: string | null;
 };
 
 /**
@@ -154,13 +156,16 @@ export function useSDKOptional() {
 
 /**
  * Get access token from SDK context (helper for WLSubscriptionProvider)
+ * 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;
 
-  // Access token is stored in SDK configuration
-  // We need to get it from the auth cookie since SDK doesn't expose it directly
+  // 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;
 }

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

@@ -1,3 +1,4 @@
+import { getClientHeaders } from "@spaceinvoices/js-sdk";
 import type { ReactNode } from "react";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 
@@ -44,7 +45,9 @@ export function WhiteLabelProvider({ children, apiBaseUrl = "" }: WhiteLabelProv
   useEffect(() => {
     const fetchConfig = async () => {
       try {
-        const response = await fetch(`${apiBaseUrl}/white-labels/current`);
+        const response = await fetch(`${apiBaseUrl}/white-labels/current`, {
+          headers: apiBaseUrl ? getClientHeaders("ui") : undefined,
+        });
         if (response.ok) {
           const data = await response.json();
           // Map snake_case API response to camelCase internal state

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

@@ -1,3 +1,4 @@
+import { getClientHeaders } from "@spaceinvoices/js-sdk";
 import type { ReactNode } from "react";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { useEntitiesOptional } from "./entities-context";
@@ -9,6 +10,8 @@ import { useAccessToken } from "./sdk-provider";
 
 export type PlanLimits = {
   documents_per_month: number | null;
+  invoices_per_month: number | null;
+  overage_price_cents: number | null;
 } | null;
 
 export type WhiteLabelPlan = {
@@ -26,6 +29,8 @@ export type WhiteLabelPlan = {
 export type UsageStats = {
   documents_count: number;
   documents_limit: number | null;
+  invoices_count: number;
+  invoices_limit: number | null;
   period_start: string;
   period_end: string;
 };
@@ -36,6 +41,14 @@ export type CurrentSubscription = {
   billing_interval: string | null;
   current_period_start: string;
   current_period_end: string;
+  trial_ends_at: string | null;
+  trial_days_remaining: number | null;
+  cancel_at: string | null;
+  payment_method: {
+    last4: string | null;
+    brand: string | null;
+    has_card: boolean;
+  } | null;
   usage: UsageStats;
 };
 
@@ -49,7 +62,8 @@ export type GatedFeature =
   | "custom_templates"
   | "api_access"
   | "webhooks"
-  | "priority_support";
+  | "priority_support"
+  | "e_invoicing";
 
 // ============================================
 // CONTEXT
@@ -63,12 +77,19 @@ type WLSubscriptionContextType = {
   isLoading: boolean;
   error: string | null;
 
+  // Trial state
+  isTrialActive: boolean;
+  isTrialExpired: boolean;
+  trialDaysRemaining: number | null;
+  needsPayment: boolean;
+
   // Feature/limit checks
   hasFeature: (feature: GatedFeature | string) => boolean;
   isOverLimit: (resource: "documents") => boolean;
   getUsagePercentage: (resource: "documents") => number;
 
-  // Refresh data
+  // Actions
+  createCheckout: (planSlug: string, billingInterval?: "monthly" | "yearly") => Promise<string>;
   refresh: () => Promise<void>;
 };
 
@@ -97,9 +118,19 @@ const DEFAULT_SUBSCRIPTION: CurrentSubscription = {
   billing_interval: null,
   current_period_start: new Date().toISOString(),
   current_period_end: new Date().toISOString(),
+  trial_ends_at: null,
+  trial_days_remaining: null,
+  cancel_at: null,
+  payment_method: {
+    last4: null,
+    brand: null,
+    has_card: false,
+  },
   usage: {
     documents_count: 0,
     documents_limit: null,
+    invoices_count: 0,
+    invoices_limit: null,
     period_start: new Date().toISOString(),
     period_end: new Date().toISOString(),
   },
@@ -146,6 +177,7 @@ export function WLSubscriptionProvider({ children, apiBaseUrl }: WLSubscriptionP
       const headers = {
         Authorization: `Bearer ${accessToken}`,
         "x-entity-id": entityId,
+        ...getClientHeaders("ui"),
         "Content-Type": "application/json",
       };
 
@@ -232,6 +264,42 @@ export function WLSubscriptionProvider({ children, apiBaseUrl }: WLSubscriptionP
     [subscription],
   );
 
+  // Return the in-app billing page URL for plan activation.
+  const createCheckout = useCallback(
+    async (planSlug: string, billingInterval: "monthly" | "yearly" = "monthly"): Promise<string> => {
+      if (!entityId || !accessToken) {
+        throw new Error("Not authenticated");
+      }
+
+      const url = new URL(`/app/${entityId}/settings/billing`, window.location.origin);
+      url.searchParams.set("plan", planSlug);
+      url.searchParams.set("interval", billingInterval);
+      return url.toString();
+    },
+    [entityId, accessToken],
+  );
+
+  // Compute trial state
+  const isTrialActive =
+    subscription.status === "trialing" &&
+    subscription.trial_ends_at != null &&
+    new Date(subscription.trial_ends_at) > new Date();
+
+  const isTrialExpiredState =
+    subscription.status === "trialing" &&
+    subscription.trial_ends_at != null &&
+    new Date(subscription.trial_ends_at) <= new Date();
+
+  const trialDaysRemaining = subscription.trial_days_remaining;
+
+  // needsPayment: trial expired, or no free plan and no active Stripe subscription
+  const needsPayment =
+    isTrialExpiredState ||
+    (subscription.status === "active" &&
+      !subscription.plan.is_free &&
+      subscription.billing_interval === null &&
+      subscription.plan.slug !== "unlimited");
+
   const value = useMemo(
     () => ({
       subscription,
@@ -240,12 +308,31 @@ export function WLSubscriptionProvider({ children, apiBaseUrl }: WLSubscriptionP
       availablePlans,
       isLoading,
       error,
+      isTrialActive,
+      isTrialExpired: isTrialExpiredState,
+      trialDaysRemaining,
+      needsPayment,
       hasFeature,
       isOverLimit,
       getUsagePercentage,
+      createCheckout,
       refresh: fetchSubscription,
     }),
-    [subscription, availablePlans, isLoading, error, hasFeature, isOverLimit, getUsagePercentage, fetchSubscription],
+    [
+      subscription,
+      availablePlans,
+      isLoading,
+      error,
+      isTrialActive,
+      isTrialExpiredState,
+      trialDaysRemaining,
+      needsPayment,
+      hasFeature,
+      isOverLimit,
+      getUsagePercentage,
+      createCheckout,
+      fetchSubscription,
+    ],
   );
 
   return <WLSubscriptionContext.Provider value={value}>{children}</WLSubscriptionContext.Provider>;