@buildbase/sdk 0.0.11 → 0.0.13

package/dist/types/providers/workspace/subscription-hooks.d.ts

@@ -1,8 +1,40 @@
 import { BillingInterval, ICheckoutSessionRequest, ICheckoutSessionResponse, IInvoice, IPlanGroupResponse, IPlanGroupVersionsResponse, ISubscriptionResponse, ISubscriptionUpdateResponse } from '../../api/types';
 /**
- * Hook to get and manage the current subscription for a workspace
- * @param workspaceId - The workspace ID to get subscription for
- * @returns Subscription data and loading/error states
+ * Hook to get and manage the current subscription for a workspace.
+ * Automatically fetches subscription when workspaceId changes.
+ *
+ * @param workspaceId - The workspace ID to get subscription for. Can be null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `subscription`: Current subscription data (null if no subscription or not loaded)
+ * - `loading`: Boolean indicating if subscription is being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the subscription
+ *
+ * @example
+ * ```tsx
+ * function SubscriptionStatus() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { subscription, loading, error } = useSubscription(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *   if (error) return <Error message={error} />;
+ *   if (!subscription) return <p>No active subscription</p>;
+ *
+ *   return <p>Plan: {subscription.plan.name}</p>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge case: Workspace ID changes
+ * function SubscriptionComponent({ workspaceId }) {
+ *   const { subscription, refetch } = useSubscription(workspaceId);
+ *
+ *   // Subscription automatically refetches when workspaceId changes
+ *   // Use refetch() to manually refresh after mutations
+ *   return <SubscriptionDetails subscription={subscription} />;
+ * }
+ * ```
  */
 export declare const useSubscription: (workspaceId: string | null | undefined) => {
     subscription: ISubscriptionResponse | null;
@@ -11,12 +43,50 @@ export declare const useSubscription: (workspaceId: string | null | undefined) =
     refetch: () => Promise<void>;
 };
 /**
- * Hook to get the plan group for a workspace
+ * Hook to get the plan group for a workspace.
  * Returns the plan group containing the current plan if subscription exists,
- * otherwise returns the latest published group
- * @param workspaceId - The workspace ID to get plan group for
- * @param groupVersionId - Optional: specific group version ID to fetch
- * @returns Plan group data and loading/error states
+ * otherwise returns the latest published group.
+ * Automatically fetches when workspaceId or groupVersionId changes.
+ *
+ * @param workspaceId - The workspace ID to get plan group for. Can be null/undefined to disable fetching.
+ * @param groupVersionId - Optional: specific group version ID to fetch (for viewing historical versions)
+ * @returns An object containing:
+ * - `planGroup`: Plan group data (null if not loaded)
+ * - `loading`: Boolean indicating if plan group is being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the plan group
+ *
+ * @example
+ * ```tsx
+ * function PlanGroupDisplay() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { planGroup, loading } = usePlanGroup(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *   if (!planGroup) return <p>No plan group available</p>;
+ *
+ *   return (
+ *     <div>
+ *       <h3>{planGroup.name}</h3>
+ *       {planGroup.plans.map(plan => (
+ *         <PlanCard key={plan._id} plan={plan} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Fetch specific version for comparison
+ * function PlanVersionComparison() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const current = usePlanGroup(currentWorkspace?._id);
+ *   const previous = usePlanGroup(currentWorkspace?._id, 'previous-version-id');
+ *
+ *   return <ComparePlans current={current.planGroup} previous={previous.planGroup} />;
+ * }
+ * ```
  */
 export declare const usePlanGroup: (workspaceId: string | null | undefined, groupVersionId?: string | null) => {
     planGroup: IPlanGroupResponse | null;
@@ -25,9 +95,36 @@ export declare const usePlanGroup: (workspaceId: string | null | undefined, grou
     refetch: () => Promise<void>;
 };
 /**
- * Hook to get all available versions of a plan group for a workspace
- * @param workspaceId - The workspace ID to get plan group versions for
- * @returns Plan group versions data and loading/error states
+ * Hook to get all available versions of a plan group for a workspace.
+ * Shows current version and available newer versions for upgrade paths.
+ * Automatically fetches when workspaceId changes.
+ *
+ * @param workspaceId - The workspace ID to get plan group versions for. Can be null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `versions`: Plan group versions response with currentVersion and availableVersions
+ * - `loading`: Boolean indicating if versions are being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the versions
+ *
+ * @example
+ * ```tsx
+ * function UpgradeOptions() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { versions, loading } = usePlanGroupVersions(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <p>Current: {versions?.currentVersion.name}</p>
+ *       <h4>Available Upgrades:</h4>
+ *       {versions?.availableVersions.map(version => (
+ *         <UpgradeCard key={version._id} version={version} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare const usePlanGroupVersions: (workspaceId: string | null | undefined) => {
     versions: IPlanGroupVersionsResponse | null;
@@ -36,9 +133,62 @@ export declare const usePlanGroupVersions: (workspaceId: string | null | undefin
     refetch: () => Promise<void>;
 };
 /**
- * Hook to create checkout session for new subscription
- * @param workspaceId - The workspace ID to create checkout session for
- * @returns Create checkout function and loading/error states
+ * Hook to create a checkout session for a new subscription.
+ * Returns a function to initiate the checkout process.
+ *
+ * @param workspaceId - The workspace ID to create checkout session for. Can be null/undefined.
+ * @returns An object containing:
+ * - `createCheckoutSession(request)`: Function to create checkout session (throws if workspaceId is null)
+ * - `loading`: Boolean indicating if checkout session is being created
+ * - `error`: Error message string (null if no error)
+ *
+ * @example
+ * ```tsx
+ * function SubscribeButton({ planVersionId }) {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { createCheckoutSession, loading } = useCreateCheckoutSession(currentWorkspace?._id);
+ *
+ *   const handleSubscribe = async () => {
+ *     try {
+ *       const result = await createCheckoutSession({
+ *         planVersionId,
+ *         successUrl: window.location.href,
+ *         cancelUrl: window.location.href,
+ *       });
+ *       // Redirect to checkout
+ *       window.location.href = result.checkoutUrl;
+ *     } catch (error) {
+ *       console.error('Failed to create checkout:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleSubscribe} disabled={loading}>
+ *       {loading ? 'Loading...' : 'Subscribe'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge case: Workspace ID not available
+ * function SubscribeButton() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { createCheckoutSession } = useCreateCheckoutSession(currentWorkspace?._id);
+ *
+ *   const handleSubscribe = async () => {
+ *     try {
+ *       await createCheckoutSession({ planVersionId: 'plan-123' });
+ *     } catch (error) {
+ *       // Error: "Workspace ID is required"
+ *       alert('Please select a workspace first');
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleSubscribe}>Subscribe</button>;
+ * }
+ * ```
  */
 export declare const useCreateCheckoutSession: (workspaceId: string | null | undefined) => {
     createCheckoutSession: (request: ICheckoutSessionRequest) => Promise<ICheckoutSessionResponse>;
@@ -46,10 +196,71 @@ export declare const useCreateCheckoutSession: (workspaceId: string | null | und
     error: string | null;
 };
 /**
- * Hook to update subscription (upgrade/downgrade)
- * Returns checkout session if payment is required, otherwise returns subscription update response
- * @param workspaceId - The workspace ID to update subscription for
- * @returns Update function and loading/error states
+ * Hook to update subscription (upgrade/downgrade).
+ * Returns checkout session if payment is required, otherwise returns subscription update response.
+ *
+ * @param workspaceId - The workspace ID to update subscription for. Can be null/undefined.
+ * @returns An object containing:
+ * - `updateSubscription(planVersionId, options?)`: Function to update subscription (throws if workspaceId is null)
+ * - `loading`: Boolean indicating if subscription is being updated
+ * - `error`: Error message string (null if no error)
+ *
+ * @example
+ * ```tsx
+ * function UpgradeButton({ planVersionId }) {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { updateSubscription, loading } = useUpdateSubscription(currentWorkspace?._id);
+ *
+ *   const handleUpgrade = async () => {
+ *     try {
+ *       const result = await updateSubscription(planVersionId, {
+ *         billingInterval: 'monthly',
+ *         successUrl: window.location.href,
+ *         cancelUrl: window.location.href,
+ *       });
+ *
+ *       // Check if payment is required
+ *       if ('checkoutUrl' in result) {
+ *         window.location.href = result.checkoutUrl;
+ *       } else {
+ *         // Subscription updated without payment
+ *         alert('Subscription updated successfully!');
+ *       }
+ *     } catch (error) {
+ *       console.error('Failed to update subscription:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleUpgrade} disabled={loading}>
+ *       {loading ? 'Upgrading...' : 'Upgrade'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Handle both checkout and direct update responses
+ * function SubscriptionUpdater({ planVersionId }) {
+ *   const { updateSubscription } = useUpdateSubscription(workspaceId);
+ *
+ *   const handleUpdate = async () => {
+ *     const result = await updateSubscription(planVersionId);
+ *
+ *     // Type guard to check response type
+ *     if ('checkoutUrl' in result) {
+ *       // Redirect to payment
+ *       window.location.href = result.checkoutUrl;
+ *     } else {
+ *       // Direct update successful
+ *       console.log('Updated subscription:', result.subscription);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleUpdate}>Update</button>;
+ * }
+ * ```
  */
 export declare const useUpdateSubscription: (workspaceId: string | null | undefined) => {
     updateSubscription: (planVersionId: string, options?: {
@@ -61,11 +272,43 @@ export declare const useUpdateSubscription: (workspaceId: string | null | undefi
     error: string | null;
 };
 /**
- * Combined hook that provides both subscription and plan group data
- * Useful for subscription management pages
- * @param workspaceId - The workspace ID
+ * Combined hook that provides both subscription and plan group data.
+ * Useful for subscription management pages that need both pieces of data.
+ * Combines useSubscription, usePlanGroup, and useUpdateSubscription.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
  * @param groupVersionId - Optional: specific group version ID to fetch
- * @returns Combined subscription and plan group data with loading/error states
+ * @returns An object containing:
+ * - `subscription`: Current subscription data (from useSubscription)
+ * - `planGroup`: Plan group data (from usePlanGroup)
+ * - `loading`: Boolean indicating if any operation is in progress
+ * - `error`: Error message string (null if no error)
+ * - `updateSubscription(planVersionId, options?)`: Function to update subscription
+ * - `refetch()`: Function to refetch both subscription and plan group
+ *
+ * @example
+ * ```tsx
+ * function SubscriptionManagementPage() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const {
+ *     subscription,
+ *     planGroup,
+ *     loading,
+ *     updateSubscription,
+ *     refetch,
+ *   } = useSubscriptionManagement(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <CurrentPlan subscription={subscription} />
+ *       <AvailablePlans planGroup={planGroup} onSelect={updateSubscription} />
+ *       <button onClick={refetch}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare const useSubscriptionManagement: (workspaceId: string | null | undefined, groupVersionId?: string | null) => {
     subscription: ISubscriptionResponse | null;
@@ -80,11 +323,64 @@ export declare const useSubscriptionManagement: (workspaceId: string | null | un
     refetch: () => Promise<void>;
 };
 /**
- * Hook to list invoices for a workspace subscription
- * @param workspaceId - The workspace ID to get invoices for
+ * Hook to list invoices for a workspace subscription with pagination support.
+ * Automatically fetches when workspaceId, limit, or startingAfter changes.
+ *
+ * @param workspaceId - The workspace ID to get invoices for. Can be null/undefined to disable fetching.
  * @param limit - Number of invoices to return (default: 10)
  * @param startingAfter - Invoice ID to start after (for pagination)
- * @returns Invoice list data and loading/error states
+ * @returns An object containing:
+ * - `invoices`: Array of invoice objects
+ * - `hasMore`: Boolean indicating if there are more invoices to load
+ * - `loading`: Boolean indicating if invoices are being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch invoices
+ *
+ * @example
+ * ```tsx
+ * function InvoiceList() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { invoices, hasMore, loading, refetch } = useInvoices(currentWorkspace?._id, 10);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {invoices.map(invoice => (
+ *         <InvoiceCard key={invoice._id} invoice={invoice} />
+ *       ))}
+ *       {hasMore && <button onClick={() => refetch()}>Load More</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Pagination example
+ * function PaginatedInvoices() {
+ *   const [lastInvoiceId, setLastInvoiceId] = useState<string | undefined>();
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { invoices, hasMore, refetch } = useInvoices(
+ *     currentWorkspace?._id,
+ *     10,
+ *     lastInvoiceId
+ *   );
+ *
+ *   const loadMore = () => {
+ *     if (invoices.length > 0) {
+ *       setLastInvoiceId(invoices[invoices.length - 1]._id);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {invoices.map(invoice => <InvoiceCard key={invoice._id} invoice={invoice} />)}
+ *       {hasMore && <button onClick={loadMore}>Load More</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare const useInvoices: (workspaceId: string | null | undefined, limit?: number, startingAfter?: string) => {
     invoices: IInvoice[];
@@ -94,10 +390,36 @@ export declare const useInvoices: (workspaceId: string | null | undefined, limit
     refetch: () => Promise<void>;
 };
 /**
- * Hook to get a single invoice by ID
- * @param workspaceId - The workspace ID
- * @param invoiceId - The invoice ID to fetch
- * @returns Invoice data and loading/error states
+ * Hook to get a single invoice by ID.
+ * Automatically fetches when workspaceId or invoiceId changes.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @param invoiceId - The invoice ID to fetch. Can be null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `invoice`: Invoice data object (null if not loaded)
+ * - `loading`: Boolean indicating if invoice is being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the invoice
+ *
+ * @example
+ * ```tsx
+ * function InvoiceDetails({ invoiceId }) {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { invoice, loading, error } = useInvoice(currentWorkspace?._id, invoiceId);
+ *
+ *   if (loading) return <Loading />;
+ *   if (error) return <Error message={error} />;
+ *   if (!invoice) return <p>Invoice not found</p>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>Invoice #{invoice.invoiceNumber}</h2>
+ *       <p>Amount: ${invoice.amount}</p>
+ *       <p>Status: {invoice.status}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare const useInvoice: (workspaceId: string | null | undefined, invoiceId: string | null | undefined) => {
     invoice: IInvoice | null;

package/dist/types/providers/workspace/types.d.ts

@@ -29,7 +29,7 @@ export interface WorkspaceContextValue {
     workspaces: IWorkspace[];
     currentWorkspace: IWorkspace | null;
     loading: boolean;
-    switching: boolean;
+    switchingToId: string | null;
     refreshing: boolean;
     error: string | null;
     fetchWorkspaces: () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildbase/sdk",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "description": "A SDK for Buildbase",
   "main": "dist/index.js",
@@ -24,6 +24,7 @@
   ],
   "scripts": {
     "build": "rollup -c",
+    "build:analyze": "rollup --config rollup.config.analyze.js",
     "dev": "rollup -c -w",
     "clean": "rimraf dist",
     "prebuild": "npm run clean",
@@ -44,7 +45,18 @@
     "react-dom": "^19.0.0"
   },
   "dependencies": {
+    "@radix-ui/react-alert-dialog": "^1.1.13",
+    "@radix-ui/react-avatar": "^1.1.9",
+    "@radix-ui/react-dialog": "^1.1.13",
     "@radix-ui/react-icons": "^1.3.2",
+    "@radix-ui/react-label": "^2.1.6",
+    "@radix-ui/react-popover": "^1.1.13",
+    "@radix-ui/react-radio-group": "^1.3.6",
+    "@radix-ui/react-scroll-area": "^1.2.8",
+    "@radix-ui/react-select": "^2.2.4",
+    "@radix-ui/react-separator": "^1.1.6",
+    "@radix-ui/react-slot": "^1.2.2",
+    "@radix-ui/react-switch": "^1.2.4",
     "axios": "^1.6.0",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.0.0",
@@ -57,17 +69,6 @@
   },
   "devDependencies": {
     "@hookform/resolvers": "^5.0.1",
-    "@radix-ui/react-alert-dialog": "^1.1.13",
-    "@radix-ui/react-avatar": "^1.1.9",
-    "@radix-ui/react-dialog": "^1.1.13",
-    "@radix-ui/react-label": "^2.1.6",
-    "@radix-ui/react-popover": "^1.1.13",
-    "@radix-ui/react-radio-group": "^1.3.6",
-    "@radix-ui/react-scroll-area": "^1.2.8",
-    "@radix-ui/react-select": "^2.2.4",
-    "@radix-ui/react-separator": "^1.1.6",
-    "@radix-ui/react-slot": "^1.2.2",
-    "@radix-ui/react-switch": "^1.2.4",
     "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
@@ -88,6 +89,7 @@
     "rollup": "^4.0.0",
     "rollup-plugin-dts": "^6.0.0",
     "rollup-plugin-postcss": "^4.0.0",
+    "rollup-plugin-visualizer": "^6.0.5",
     "tailwindcss": "^3.4.17",
     "tslib": "^2.8.1",
     "typescript": "^5.2.0"