@buildbase/sdk 0.0.9 → 0.0.11

package/README.md

@@ -212,7 +212,7 @@ const {
   isAuthenticated, // Boolean: true if user is authenticated
   isLoading, // Boolean: true when checking authentication status
   isRedirecting, // Boolean: true when redirecting for OAuth
-  status, // String: 'idle' | 'loading' | 'authenticated' | 'error'
+  status, // AuthStatus: 'loading' | 'redirecting' | 'authenticating' | 'authenticated' | 'unauthenticated' (use AuthStatus enum for type-safe checks)
   signIn, // Function: initiates sign-in flow
   signOut, // Function: signs out the user
   openWorkspaceSettings, // Function: opens workspace settings dialog
@@ -529,6 +529,7 @@ function SettingsExample() {
 ### Enums
 
 - `ApiVersion` - API version enum (currently only `V1`)
+- `AuthStatus` - Auth status enum: `loading` \| `redirecting` \| `authenticating` \| `authenticated` \| `unauthenticated`. Use with `useSaaSAuth().status`; `isLoading`, `isAuthenticated`, and `isRedirecting` are derived from it.
 
 ### Types
 

package/dist/index.d.ts

@@ -21,6 +21,213 @@ interface IUser extends IDocument {
     currency: string;
     attributes?: Record<string, string | number | boolean>;
 }
+interface ISubscription {
+    _id: string;
+    subscriptionStatus: 'active' | 'trialing' | 'canceled' | 'past_due';
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ISubscriptionItem {
+    _id: string;
+    type: 'feature' | 'limit' | 'quota';
+    name: string;
+    slug: string;
+    description?: string;
+    category: string;
+}
+interface IQuotaValue {
+    included: number;
+    overage?: number;
+    stripePriceId?: string;
+}
+interface IBasePricing {
+    monthly: number;
+    yearly: number;
+    quarterly: number;
+}
+interface IPlanVersion {
+    _id: string;
+    version: number;
+    name: string;
+    status: 'draft' | 'published';
+    features?: Record<string, boolean>;
+    limits?: Record<string, number>;
+    quotas?: Record<string, number | IQuotaValue>;
+    basePricing?: IBasePricing;
+    stripePrices?: {
+        monthlyPriceId?: string;
+        yearlyPriceId?: string;
+        quarterlyPriceId?: string;
+        monthly?: string;
+        yearly?: string;
+    };
+    subscriptionItems?: ISubscriptionItem[];
+    isCurrent?: boolean;
+    isLegacy?: boolean;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    id?: string;
+}
+interface IPlan {
+    _id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    latestVersion?: IPlanVersion;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    id?: string;
+}
+interface IPlanGroupLatestVersion {
+    _id: string;
+    version: number;
+    planVersionIds: string[];
+    requiredItems: string[];
+    status: 'draft' | 'published';
+    isCurrent?: boolean;
+    isLegacy?: boolean;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    description?: string;
+}
+interface IPlanGroup {
+    _id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    latestVersion?: IPlanGroupLatestVersion;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    id?: string;
+}
+interface IPlanGroupVersion {
+    _id: string;
+    version: number;
+    description?: string;
+    group?: {
+        _id: string;
+        name: string;
+        description?: string;
+    };
+    planVersionIds: IPlanVersionWithPlan[] | string[];
+    requiredItems?: string[];
+    status?: 'draft' | 'published';
+    isCurrent?: boolean;
+    isLegacy?: boolean;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    id?: string;
+}
+interface ISubscriptionResponse {
+    subscription: ISubscription | null;
+    planVersion: IPlanVersion | null;
+    plan: IPlan | null;
+    group: IPlanGroup | null;
+    groupVersion: IPlanGroupVersion | null;
+}
+interface IPlanVersionWithPlan extends IPlanVersion {
+    plan: IPlan;
+}
+interface IPlanGroupVersionWithPlans {
+    _id: string;
+    version: number;
+    description?: string;
+    plans: IPlanVersionWithPlan[];
+    isCurrent?: boolean;
+    whatsNew?: {
+        newPlans: IPlanVersionWithPlan[];
+        updatedPlans: IPlanVersionWithPlan[];
+        removedPlans: IPlanVersionWithPlan[];
+    };
+}
+interface IPlanGroupResponse {
+    group: {
+        _id: string;
+        name: string;
+        slug: string;
+    };
+    currentVersion: IPlanGroupVersionWithPlans;
+    availableVersions: IPlanGroupVersionWithPlans[];
+}
+interface IPlanGroupVersionsResponse {
+    group: {
+        _id: string;
+        name: string;
+        slug: string;
+    };
+    currentVersion: IPlanGroupVersionWithPlans;
+    availableVersions: IPlanGroupVersionWithPlans[];
+}
+type BillingInterval = 'monthly' | 'yearly' | 'quarterly';
+interface ICheckoutSessionRequest {
+    planVersionId: string;
+    billingInterval?: BillingInterval;
+    successUrl?: string;
+    cancelUrl?: string;
+}
+interface ICheckoutSessionResponse {
+    success: boolean;
+    checkoutUrl: string;
+    sessionId: string;
+    message: string;
+    planVersion?: {
+        _id: string;
+        version: number;
+        name: string;
+    };
+}
+interface ISubscriptionUpdateRequest {
+    planVersionId: string;
+    billingInterval?: BillingInterval;
+    successUrl?: string;
+    cancelUrl?: string;
+}
+interface ISubscriptionUpdateResponse {
+    _id: string;
+    subscriptionStatus: string;
+    workspace: string;
+    planVersion: string;
+    plan: string;
+    planGroup?: string;
+    planGroupVersion?: string;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+type InvoiceStatus = 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
+interface IInvoice {
+    id: string;
+    amount_due: number;
+    amount_paid: number;
+    currency: string;
+    status: InvoiceStatus;
+    created: number;
+    due_date: number | null;
+    hosted_invoice_url: string;
+    invoice_pdf: string | null;
+    description: string | null;
+    subscription: string;
+}
+interface IInvoiceListResponse {
+    success: boolean;
+    invoices: IInvoice[];
+    has_more: boolean;
+}
+interface IInvoiceResponse {
+    success: boolean;
+    invoice: IInvoice;
+}
 
 interface IWorkspace {
     _id: string;
@@ -112,6 +319,7 @@ interface IEventCallbacks {
 
 declare enum AuthStatus {
     loading = "loading",
+    redirecting = "redirecting",
     authenticated = "authenticated",
     unauthenticated = "unauthenticated",
     authenticating = "authenticating"
@@ -227,15 +435,15 @@ declare const WhenUserFeatureEnabled: (props: IProps) => react.ReactNode;
 declare const WhenUserFeatureDisabled: (props: IProps) => react.ReactNode;
 
 declare function useSaaSAuth(): {
-    user: AuthUser | undefined;
-    session: AuthSession | null;
-    isLoading: boolean;
-    isAuthenticated: boolean;
-    isRedirecting: boolean;
-    status: AuthStatus;
     signIn: () => Promise<void>;
     signOut: () => Promise<void>;
     openWorkspaceSettings: (section?: "profile" | "general" | "users" | "features" | "danger") => void;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    isRedirecting: boolean;
+    user: AuthUser | undefined;
+    session: AuthSession | null;
+    status: AuthStatus;
 };
 
 declare function useSaaSSettings(): {
@@ -309,6 +517,113 @@ declare const useSaaSWorkspaces: () => {
     }>;
 };
 
+/**
+ * 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
+ */
+declare const useSubscription: (workspaceId: string | null | undefined) => {
+    subscription: ISubscriptionResponse | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * 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
+ */
+declare const usePlanGroup: (workspaceId: string | null | undefined, groupVersionId?: string | null) => {
+    planGroup: IPlanGroupResponse | null;
+    loading: boolean;
+    error: string | null;
+    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
+ */
+declare const usePlanGroupVersions: (workspaceId: string | null | undefined) => {
+    versions: IPlanGroupVersionsResponse | null;
+    loading: boolean;
+    error: string | null;
+    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
+ */
+declare const useCreateCheckoutSession: (workspaceId: string | null | undefined) => {
+    createCheckoutSession: (request: ICheckoutSessionRequest) => Promise<ICheckoutSessionResponse>;
+    loading: boolean;
+    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
+ */
+declare const useUpdateSubscription: (workspaceId: string | null | undefined) => {
+    updateSubscription: (planVersionId: string, options?: {
+        billingInterval?: BillingInterval;
+        successUrl?: string;
+        cancelUrl?: string;
+    }) => Promise<ISubscriptionUpdateResponse | ICheckoutSessionResponse>;
+    loading: boolean;
+    error: string | null;
+};
+/**
+ * Combined hook that provides both subscription and plan group data
+ * Useful for subscription management pages
+ * @param workspaceId - The workspace ID
+ * @param groupVersionId - Optional: specific group version ID to fetch
+ * @returns Combined subscription and plan group data with loading/error states
+ */
+declare const useSubscriptionManagement: (workspaceId: string | null | undefined, groupVersionId?: string | null) => {
+    subscription: ISubscriptionResponse | null;
+    planGroup: IPlanGroupResponse | null;
+    loading: boolean;
+    error: string | null;
+    updateSubscription: (planVersionId: string, options?: {
+        billingInterval?: BillingInterval;
+        successUrl?: string;
+        cancelUrl?: string;
+    }) => Promise<ISubscriptionUpdateResponse | ICheckoutSessionResponse>;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to list invoices for a workspace subscription
+ * @param workspaceId - The workspace ID to get invoices for
+ * @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
+ */
+declare const useInvoices: (workspaceId: string | null | undefined, limit?: number, startingAfter?: string) => {
+    invoices: IInvoice[];
+    hasMore: boolean;
+    loading: boolean;
+    error: string | null;
+    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
+ */
+declare const useInvoice: (workspaceId: string | null | undefined, invoiceId: string | null | undefined) => {
+    invoice: IInvoice | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
 /**
  * EventEmitter class to handle and trigger event callbacks
  * This class manages all event listeners and provides methods to trigger events
@@ -481,5 +796,5 @@ declare const errorHandler: ErrorHandler;
 declare function handleError(error: Error | unknown, context?: SDKErrorContext): void;
 declare function createSDKError(message: string, code?: string, context?: SDKErrorContext, originalError?: Error): SDKError;
 
-export { ApiVersion, BetaForm, SDKErrorBoundary as ErrorBoundary, SDKError, SDKErrorBoundary, SaaSOSProvider, WhenAuthenticated, WhenRoles, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceSwitcher, createSDKError, errorHandler, eventEmitter, handleError, useSaaSAuth, useSaaSSettings, useSaaSWorkspaces, useUserAttributes, useUserFeatures };
-export type { ErrorHandlerConfig, EventData, EventType, IEventCallbacks, SDKErrorContext, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export { ApiVersion, AuthStatus, BetaForm, SDKErrorBoundary as ErrorBoundary, SDKError, SDKErrorBoundary, SaaSOSProvider, WhenAuthenticated, WhenRoles, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceSwitcher, createSDKError, errorHandler, eventEmitter, handleError, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, useSaaSAuth, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionManagement, useUpdateSubscription, useUserAttributes, useUserFeatures };
+export type { BillingInterval, ErrorHandlerConfig, EventData, EventType, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IPlan, IPlanGroup, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionWithPlan, IQuotaValue, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, SDKErrorContext, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };