@buildbase/sdk 0.0.19 → 0.0.21

package/dist/index.d.ts

@@ -255,6 +255,7 @@ interface IPlanGroupVersionsResponse {
 interface ICheckoutSessionRequest {
     planVersionId: string;
     billingInterval?: BillingInterval;
+    currency?: string;
     successUrl?: string;
     cancelUrl?: string;
 }
@@ -348,6 +349,68 @@ interface IInvoiceResponse {
     success: boolean;
     invoice: IInvoice;
 }
+/** Request body for POST .../workspaces/:id/subscription/usage */
+interface IRecordUsageRequest {
+    quotaSlug: string;
+    quantity: number;
+    metadata?: Record<string, unknown>;
+    source?: string;
+    idempotencyKey?: string;
+}
+/** Response from POST .../workspaces/:id/subscription/usage */
+interface IRecordUsageResponse {
+    used: number;
+    consumed: number;
+    included: number;
+    available: number;
+    overage: number;
+    billedAsync: boolean;
+}
+/** Single quota usage status (shared between status and all endpoints). */
+interface IQuotaUsageStatus {
+    consumed: number;
+    included: number;
+    available: number;
+    overage: number;
+    hasOverage: boolean;
+}
+/** Response from GET .../workspaces/:id/subscription/usage/status?quotaSlug=X */
+interface IQuotaUsageStatusResponse extends IQuotaUsageStatus {
+    quotaSlug: string;
+}
+/** Response from GET .../workspaces/:id/subscription/usage/all */
+interface IAllQuotaUsageResponse {
+    quotas: Record<string, IQuotaUsageStatus>;
+}
+/** Single usage log entry from GET .../usage/logs */
+interface IUsageLogEntry {
+    _id: string;
+    quotaSlug: string;
+    quantity: number;
+    source?: string;
+    workspace: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Query parameters for GET .../workspaces/:id/subscription/usage/logs */
+interface IUsageLogsQuery {
+    quotaSlug?: string;
+    from?: string;
+    to?: string;
+    source?: string;
+    page?: number;
+    limit?: number;
+}
+/** Paginated response from GET .../workspaces/:id/subscription/usage/logs */
+interface IUsageLogsResponse {
+    docs: IUsageLogEntry[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
 
 interface IWorkspace {
     _id: string;
@@ -634,7 +697,10 @@ interface IProps$2 {
  * }
  * ```
  */
-declare const WhenAuthenticated: (props: IProps$2) => react.ReactNode;
+declare const WhenAuthenticated: {
+    (props: IProps$2): react.ReactNode;
+    displayName: string;
+};
 /**
  * Conditional component that renders children only when user is NOT authenticated.
  * Returns null if user is authenticated.
@@ -676,7 +742,10 @@ declare const WhenAuthenticated: (props: IProps$2) => react.ReactNode;
  * }
  * ```
  */
-declare const WhenUnauthenticated: (props: IProps$2) => react.ReactNode;
+declare const WhenUnauthenticated: {
+    (props: IProps$2): react.ReactNode;
+    displayName: string;
+};
 
 interface IProps$1 {
     roles: string[];
@@ -718,7 +787,10 @@ interface IProps$1 {
  * }
  * ```
  */
-declare const WhenRoles: (props: IProps$1) => react.ReactNode;
+declare const WhenRoles: {
+    (props: IProps$1): react.ReactNode;
+    displayName: string;
+};
 /**
  * Conditional component that renders children only when user has one of the specified roles
  * in the current workspace. Checks workspace-specific role, not global role.
@@ -754,7 +826,10 @@ declare const WhenRoles: (props: IProps$1) => react.ReactNode;
  * }
  * ```
  */
-declare const WhenWorkspaceRoles: (props: IProps$1) => react.ReactNode;
+declare const WhenWorkspaceRoles: {
+    (props: IProps$1): react.ReactNode;
+    displayName: string;
+};
 
 interface IProps {
     slug: string;
@@ -796,7 +871,10 @@ interface IProps {
  * }
  * ```
  */
-declare const WhenWorkspaceFeatureEnabled: (props: IProps) => react.ReactNode;
+declare const WhenWorkspaceFeatureEnabled: {
+    (props: IProps): react.ReactNode;
+    displayName: string;
+};
 /**
  * Conditional component that renders children only when the specified workspace feature is disabled.
  * Checks feature flags at the workspace level.
@@ -816,7 +894,10 @@ declare const WhenWorkspaceFeatureEnabled: (props: IProps) => react.ReactNode;
  * }
  * ```
  */
-declare const WhenWorkspaceFeatureDisabled: (props: IProps) => react.ReactNode;
+declare const WhenWorkspaceFeatureDisabled: {
+    (props: IProps): react.ReactNode;
+    displayName: string;
+};
 /**
  * Conditional component that renders children only when the specified user feature is enabled.
  * Checks feature flags at the user level (from UserProvider).
@@ -852,7 +933,10 @@ declare const WhenWorkspaceFeatureDisabled: (props: IProps) => react.ReactNode;
  * }
  * ```
  */
-declare const WhenUserFeatureEnabled: (props: IProps) => react.ReactNode;
+declare const WhenUserFeatureEnabled: {
+    (props: IProps): react.ReactNode;
+    displayName: string;
+};
 /**
  * Conditional component that renders children only when the specified user feature is disabled.
  * Checks feature flags at the user level (from UserProvider).
@@ -872,7 +956,10 @@ declare const WhenUserFeatureEnabled: (props: IProps) => react.ReactNode;
  * }
  * ```
  */
-declare const WhenUserFeatureDisabled: (props: IProps) => react.ReactNode;
+declare const WhenUserFeatureDisabled: {
+    (props: IProps): react.ReactNode;
+    displayName: string;
+};
 
 interface IWhenSubscriptionProps {
     /** Content to render when the condition is met (workspace has an active subscription). */
@@ -910,7 +997,10 @@ interface IWhenSubscriptionProps {
  * </WhenSubscription>
  * ```
  */
-declare const WhenSubscription: (props: IWhenSubscriptionProps) => react.ReactNode;
+declare const WhenSubscription: {
+    (props: IWhenSubscriptionProps): react.ReactNode;
+    displayName: string;
+};
 /**
  * Renders children only when the current workspace has no subscription (or no current workspace).
  * Optionally pass loadingComponent (while loading) or fallbackComponent (when already subscribed).
@@ -939,7 +1029,10 @@ declare const WhenSubscription: (props: IWhenSubscriptionProps) => react.ReactNo
  * </WhenNoSubscription>
  * ```
  */
-declare const WhenNoSubscription: (props: IWhenSubscriptionProps) => react.ReactNode;
+declare const WhenNoSubscription: {
+    (props: IWhenSubscriptionProps): react.ReactNode;
+    displayName: string;
+};
 interface IWhenSubscriptionToPlansProps {
     /** Plan slugs to match (e.g. ['pro', 'enterprise']). Matching is case-insensitive. */
     plans: string[];
@@ -980,7 +1073,131 @@ interface IWhenSubscriptionToPlansProps {
  * </WhenSubscriptionToPlans>
  * ```
  */
-declare const WhenSubscriptionToPlans: (props: IWhenSubscriptionToPlansProps) => react.ReactNode;
+declare const WhenSubscriptionToPlans: {
+    (props: IWhenSubscriptionToPlansProps): react.ReactNode;
+    displayName: string;
+};
+
+interface IWhenQuotaProps {
+    /** Quota slug to check (e.g. 'api_calls', 'emails', 'storage'). */
+    slug: string;
+    /** Content to render when the condition is met. */
+    children: React.ReactNode;
+    /** Optional component/element to show while quota usage is loading (e.g. <Skeleton />). */
+    loadingComponent?: React.ReactNode;
+    /** Optional component/element to show when condition is not met (e.g. <UpgradePrompt />). */
+    fallbackComponent?: React.ReactNode;
+}
+interface IWhenQuotaThresholdProps extends IWhenQuotaProps {
+    /** Usage percentage threshold (0-100). Children render when usage >= this percentage. */
+    threshold: number;
+}
+/**
+ * Renders children only when the specified quota has remaining units (available > 0).
+ * Must be used within QuotaUsageContextProvider (included in SaaSOSProvider by default).
+ *
+ * @example
+ * ```tsx
+ * <WhenQuotaAvailable slug="api_calls">
+ *   <MakeApiCallButton />
+ * </WhenQuotaAvailable>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <WhenQuotaAvailable
+ *   slug="emails"
+ *   loadingComponent={<Skeleton />}
+ *   fallbackComponent={<p>Email quota exhausted. <UpgradeLink /></p>}
+ * >
+ *   <SendEmailButton />
+ * </WhenQuotaAvailable>
+ * ```
+ */
+declare const WhenQuotaAvailable: {
+    (props: IWhenQuotaProps): react.ReactNode;
+    displayName: string;
+};
+/**
+ * Renders children only when the specified quota is fully consumed (available <= 0).
+ * Must be used within QuotaUsageContextProvider (included in SaaSOSProvider by default).
+ *
+ * @example
+ * ```tsx
+ * <WhenQuotaExhausted slug="api_calls">
+ *   <UpgradePrompt message="You've used all your API calls this month." />
+ * </WhenQuotaExhausted>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <WhenQuotaExhausted
+ *   slug="storage"
+ *   loadingComponent={<Spinner />}
+ *   fallbackComponent={null}
+ * >
+ *   <StorageFullBanner />
+ * </WhenQuotaExhausted>
+ * ```
+ */
+declare const WhenQuotaExhausted: {
+    (props: IWhenQuotaProps): react.ReactNode;
+    displayName: string;
+};
+/**
+ * Renders children only when the specified quota is in overage (consumed > included).
+ * Must be used within QuotaUsageContextProvider (included in SaaSOSProvider by default).
+ *
+ * @example
+ * ```tsx
+ * <WhenQuotaOverage slug="api_calls">
+ *   <OverageBillingWarning />
+ * </WhenQuotaOverage>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <WhenQuotaOverage
+ *   slug="emails"
+ *   loadingComponent={<Skeleton />}
+ *   fallbackComponent={null}
+ * >
+ *   <p>You are being billed for overage usage.</p>
+ * </WhenQuotaOverage>
+ * ```
+ */
+declare const WhenQuotaOverage: {
+    (props: IWhenQuotaProps): react.ReactNode;
+    displayName: string;
+};
+/**
+ * Renders children when the specified quota's usage percentage reaches or exceeds the threshold.
+ * Usage percentage = (consumed / included) * 100. If included is 0 and consumed > 0, treats as 100%.
+ * Must be used within QuotaUsageContextProvider (included in SaaSOSProvider by default).
+ *
+ * @example
+ * ```tsx
+ * <WhenQuotaThreshold slug="api_calls" threshold={80}>
+ *   <p>Warning: You've used over 80% of your API calls.</p>
+ * </WhenQuotaThreshold>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <WhenQuotaThreshold
+ *   slug="storage"
+ *   threshold={90}
+ *   loadingComponent={<Spinner />}
+ *   fallbackComponent={null}
+ * >
+ *   <StorageWarningBanner />
+ * </WhenQuotaThreshold>
+ * ```
+ */
+declare const WhenQuotaThreshold: {
+    (props: IWhenQuotaThresholdProps): react.ReactNode;
+    displayName: string;
+};
 
 /**
  * Value provided by SubscriptionContext and returned by useSubscriptionContext.
@@ -990,6 +1207,8 @@ interface SubscriptionContextValue {
     response: ISubscriptionResponse | null;
     /** True while subscription is being fetched. */
     loading: boolean;
+    /** Error message if the last fetch failed, or null. */
+    error: string | null;
     /** Refetch subscription for the current workspace. Call after plan change (e.g. upgrade) or when subscription was updated elsewhere. */
     refetch: () => Promise<void>;
 }
@@ -1015,7 +1234,54 @@ declare const SubscriptionContextProvider: react__default.FC<{
  */
 declare function useSubscriptionContext(): SubscriptionContextValue;
 
-type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'features' | 'danger';
+/**
+ * Notify all subscribers to refetch subscription (e.g. after update/cancel/resume).
+ * Called internally by useUpdateSubscription, useCancelSubscription, useResumeSubscription on success.
+ */
+declare function invalidateSubscription(): void;
+
+/**
+ * Value provided by QuotaUsageContext and returned by useQuotaUsageContext.
+ */
+interface QuotaUsageContextValue {
+    /** Current quota usage statuses keyed by slug, or null if not loaded. */
+    quotas: Record<string, IQuotaUsageStatus> | null;
+    /** True while quota usage is being fetched. */
+    loading: boolean;
+    /** Error message if the last fetch failed, or null. */
+    error: string | null;
+    /** Refetch all quota usage for the current workspace. Call after recording usage or when usage was updated elsewhere. */
+    refetch: () => Promise<void>;
+}
+
+/**
+ * Provides quota usage data for the current workspace to quota gate components.
+ * Fetches when workspace changes; refetches when quota usage is invalidated (e.g. after recording usage).
+ * Must wrap (or be ancestor of) any component that uses WhenQuotaAvailable, WhenQuotaExhausted,
+ * WhenQuotaOverage, WhenQuotaThreshold, or useQuotaUsageContext. Included in SaaSOSProvider by default.
+ *
+ * @param props - Component props
+ * @param props.children - React tree that may use quota gates or useQuotaUsageContext
+ * @returns Provider element that supplies quota usage context to descendants
+ */
+declare const QuotaUsageContextProvider: react__default.FC<{
+    children: ReactNode;
+}>;
+/**
+ * Returns quota usage data for the current workspace. Must be used within QuotaUsageContextProvider.
+ *
+ * @returns QuotaUsageContextValue - { quotas, loading, refetch }
+ * @throws Error if used outside QuotaUsageContextProvider
+ */
+declare function useQuotaUsageContext(): QuotaUsageContextValue;
+
+/**
+ * Notify all subscribers to refetch quota usage (e.g. after recording usage).
+ * Called internally by useRecordUsage on success.
+ */
+declare function invalidateQuotaUsage(): void;
+
+type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'usage' | 'features' | 'danger';
 
 declare function useSaaSAuth(): {
     signIn: () => Promise<void>;
@@ -1354,6 +1620,33 @@ declare class WorkspaceApi extends BaseApi {
      * @returns Updated subscription with cancelAtPeriodEnd set to false
      */
     resumeSubscription(workspaceId: string): Promise<ISubscriptionResponse>;
+    /**
+     * Record quota usage for a workspace
+     * @param workspaceId - The workspace ID
+     * @param request - Usage request with quotaSlug, quantity, and optional metadata/source
+     * @returns Usage result with consumed/included/available/overage
+     */
+    recordUsage(workspaceId: string, request: IRecordUsageRequest): Promise<IRecordUsageResponse>;
+    /**
+     * Get usage status for a single quota
+     * @param workspaceId - The workspace ID
+     * @param quotaSlug - The quota slug to check
+     * @returns Quota usage status with consumed/included/available/overage/hasOverage
+     */
+    getQuotaUsageStatus(workspaceId: string, quotaSlug: string): Promise<IQuotaUsageStatusResponse>;
+    /**
+     * Get usage status for all quotas in the workspace's current plan
+     * @param workspaceId - The workspace ID
+     * @returns All quota usage statuses keyed by quota slug
+     */
+    getAllQuotaUsage(workspaceId: string): Promise<IAllQuotaUsageResponse>;
+    /**
+     * Get paginated usage logs for a workspace
+     * @param workspaceId - The workspace ID
+     * @param query - Optional filters: quotaSlug, from, to, source, page, limit
+     * @returns Paginated usage log entries
+     */
+    getUsageLogs(workspaceId: string, query?: IUsageLogsQuery): Promise<IUsageLogsResponse>;
 }
 
 declare const useSaaSWorkspaces: () => {
@@ -1888,6 +2181,264 @@ declare const useInvoice: (workspaceId: string | null | undefined, invoiceId: st
     error: string | null;
     refetch: () => Promise<void>;
 };
+/**
+ * Hook to cancel a subscription at the end of the current billing period.
+ * Sets cancelAtPeriodEnd: true - subscription remains active until period ends.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined.
+ * @returns An object containing:
+ * - `cancelSubscription()`: Function to cancel subscription at period end
+ * - `loading`: Boolean indicating if cancellation is in progress
+ * - `error`: Error message string (null if no error)
+ *
+ * @example
+ * ```tsx
+ * function CancelSubscriptionButton() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { cancelSubscription, loading } = useCancelSubscription(currentWorkspace?._id);
+ *   const { refetch } = useSubscription(currentWorkspace?._id);
+ *
+ *   const handleCancel = async () => {
+ *     try {
+ *       await cancelSubscription();
+ *       await refetch(); // Refresh subscription data
+ *       alert('Subscription will be canceled at the end of the billing period');
+ *     } catch (error) {
+ *       console.error('Failed to cancel:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleCancel} disabled={loading}>
+ *       {loading ? 'Canceling...' : 'Cancel Subscription'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const useCancelSubscription: (workspaceId: string | null | undefined) => {
+    cancelSubscription: () => Promise<ISubscriptionResponse>;
+    loading: boolean;
+    error: string | null;
+};
+/**
+ * Hook to resume a subscription that was scheduled for cancellation.
+ * Sets cancelAtPeriodEnd: false - subscription will continue after period ends.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined.
+ * @returns An object containing:
+ * - `resumeSubscription()`: Function to resume subscription
+ * - `loading`: Boolean indicating if resume is in progress
+ * - `error`: Error message string (null if no error)
+ *
+ * @example
+ * ```tsx
+ * function ResumeSubscriptionButton() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { resumeSubscription, loading } = useResumeSubscription(currentWorkspace?._id);
+ *   const { refetch } = useSubscription(currentWorkspace?._id);
+ *
+ *   const handleResume = async () => {
+ *     try {
+ *       await resumeSubscription();
+ *       await refetch(); // Refresh subscription data
+ *       alert('Subscription has been resumed');
+ *     } catch (error) {
+ *       console.error('Failed to resume:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleResume} disabled={loading}>
+ *       {loading ? 'Resuming...' : 'Resume Subscription'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const useResumeSubscription: (workspaceId: string | null | undefined) => {
+    resumeSubscription: () => Promise<ISubscriptionResponse>;
+    loading: boolean;
+    error: string | null;
+};
+/**
+ * Hook to record quota usage for a workspace.
+ * Returns a function to record usage (mutation pattern).
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined.
+ * @returns An object containing:
+ * - `recordUsage(request)`: Function to record usage (throws if workspaceId is null)
+ * - `loading`: Boolean indicating if recording is in progress
+ * - `error`: Error message string (null if no error)
+ *
+ * @example
+ * ```tsx
+ * function RecordUsageButton() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { recordUsage, loading } = useRecordUsage(currentWorkspace?._id);
+ *
+ *   const handleRecord = async () => {
+ *     try {
+ *       const result = await recordUsage({
+ *         quotaSlug: 'api_calls',
+ *         quantity: 1,
+ *         source: 'web-app',
+ *       });
+ *       console.log(`Used: ${result.consumed}/${result.included}`);
+ *     } catch (error) {
+ *       console.error('Failed to record usage:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleRecord} disabled={loading}>
+ *       {loading ? 'Recording...' : 'Record Usage'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const useRecordUsage: (workspaceId: string | null | undefined) => {
+    recordUsage: (request: IRecordUsageRequest) => Promise<IRecordUsageResponse>;
+    loading: boolean;
+    error: string | null;
+};
+/**
+ * Hook to get usage status for a single quota.
+ * Automatically fetches when workspaceId or quotaSlug changes.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @param quotaSlug - The quota slug to check. Can be null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `status`: Quota usage status (null if not loaded)
+ * - `loading`: Boolean indicating if status is being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch the status
+ *
+ * @example
+ * ```tsx
+ * function QuotaStatusDisplay() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { status, loading } = useQuotaUsageStatus(currentWorkspace?._id, 'api_calls');
+ *
+ *   if (loading) return <Loading />;
+ *   if (!status) return null;
+ *
+ *   return (
+ *     <div>
+ *       <p>Used: {status.consumed} / {status.included}</p>
+ *       <p>Available: {status.available}</p>
+ *       {status.hasOverage && <p>Overage: {status.overage}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useQuotaUsageStatus: (workspaceId: string | null | undefined, quotaSlug: string | null | undefined) => {
+    status: IQuotaUsageStatusResponse | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to get usage status for all quotas in the workspace's current plan.
+ * Automatically fetches when workspaceId changes.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @returns An object containing:
+ * - `quotas`: Record of quota usage statuses keyed by slug (null if not loaded)
+ * - `loading`: Boolean indicating if statuses are being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch all statuses
+ *
+ * @example
+ * ```tsx
+ * function AllQuotasDisplay() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { quotas, loading } = useAllQuotaUsage(currentWorkspace?._id);
+ *
+ *   if (loading) return <Loading />;
+ *   if (!quotas) return null;
+ *
+ *   return (
+ *     <div>
+ *       {Object.entries(quotas).map(([slug, usage]) => (
+ *         <div key={slug}>
+ *           <p>{slug}: {usage.consumed}/{usage.included}</p>
+ *           {usage.hasOverage && <p>Overage: {usage.overage}</p>}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useAllQuotaUsage: (workspaceId: string | null | undefined) => {
+    quotas: Record<string, IQuotaUsageStatus> | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to get paginated usage logs for a workspace.
+ * Automatically fetches when workspaceId or filter params change.
+ *
+ * @param workspaceId - The workspace ID. Can be null/undefined to disable fetching.
+ * @param quotaSlug - Optional quota slug to filter logs by.
+ * @param options - Optional filters: from, to, source, page, limit
+ * @returns An object containing:
+ * - `logs`: Array of usage log entries
+ * - `totalDocs`: Total number of log entries matching the query
+ * - `totalPages`: Total number of pages
+ * - `page`: Current page number
+ * - `hasNextPage`: Whether there are more pages after the current one
+ * - `hasPrevPage`: Whether there are pages before the current one
+ * - `loading`: Boolean indicating if logs are being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refetch()`: Function to manually refetch logs
+ *
+ * @example
+ * ```tsx
+ * function UsageLogsTable() {
+ *   const { currentWorkspace } = useSaaSWorkspaces();
+ *   const { logs, totalPages, page, hasNextPage, loading } = useUsageLogs(
+ *     currentWorkspace?._id,
+ *     'api_calls',
+ *     { limit: 20 }
+ *   );
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {logs.map(log => (
+ *         <div key={log._id}>
+ *           {log.quotaSlug}: {log.quantity} ({log.createdAt})
+ *         </div>
+ *       ))}
+ *       <p>Page {page} of {totalPages}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useUsageLogs: (workspaceId: string | null | undefined, quotaSlug?: string, options?: {
+    from?: string;
+    to?: string;
+    source?: string;
+    page?: number;
+    limit?: number;
+}) => {
+    logs: IUsageLogEntry[];
+    totalDocs: number;
+    totalPages: number;
+    page: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
 
 /**
  * EventEmitter class to handle and trigger event callbacks
@@ -2101,5 +2652,5 @@ interface FormatQuotaWithPriceOptions {
  */
 declare function formatQuotaWithPrice(value: QuotaDisplayValue, unitName: string, options?: FormatQuotaWithPriceOptions): string;
 
-export { ApiVersion, AuthStatus, BaseApi, BetaForm, CURRENCY_DISPLAY, CURRENCY_FLAG, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PricingPage, SaaSOSProvider, SettingsApi, SubscriptionContextProvider, UserApi, WhenAuthenticated, WhenNoSubscription, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getStripePriceIdForInterval, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionContext, useSubscriptionManagement, useUpdateSubscription, useUserAttributes, useUserFeatures };
-export type { BillingInterval, EventData, EventType, FormatQuotaWithPriceOptions, IBaseApiConfig, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPricingVariant, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, OnWorkspaceChangeParams, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, SubscriptionContextValue, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export { ApiVersion, AuthStatus, BaseApi, BetaForm, CURRENCY_DISPLAY, CURRENCY_FLAG, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PricingPage, QuotaUsageContextProvider, SaaSOSProvider, SettingsApi, SubscriptionContextProvider, UserApi, WhenAuthenticated, WhenNoSubscription, WhenQuotaAvailable, WhenQuotaExhausted, WhenQuotaOverage, WhenQuotaThreshold, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, eventEmitter, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getStripePriceIdForInterval, invalidateQuotaUsage, invalidateSubscription, useAllQuotaUsage, useCancelSubscription, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useQuotaUsageContext, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionContext, useSubscriptionManagement, useUpdateSubscription, useUsageLogs, useUserAttributes, useUserFeatures };
+export type { BillingInterval, EventData, EventType, FormatQuotaWithPriceOptions, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, IEventCallbacks, IInvoice, IInvoiceListResponse, IInvoiceResponse, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPricingVariant, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, InvoiceStatus, OnWorkspaceChangeParams, PlanVersionWithPricingVariants, PricingPageDetails, PricingPageProps, QuotaDisplayValue, QuotaDisplayWithOverage, QuotaUsageContextValue, SubscriptionContextValue, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };