@buildbase/sdk 0.0.19 → 0.0.20

package/dist/types/api/types.d.ts

@@ -282,6 +282,7 @@ export interface IPlanGroupVersionsResponse {
 export interface ICheckoutSessionRequest {
     planVersionId: string;
     billingInterval?: BillingInterval;
+    currency?: string;
     successUrl?: string;
     cancelUrl?: string;
 }
@@ -375,3 +376,65 @@ export interface IInvoiceResponse {
     success: boolean;
     invoice: IInvoice;
 }
+/** Request body for POST .../workspaces/:id/subscription/usage */
+export interface IRecordUsageRequest {
+    quotaSlug: string;
+    quantity: number;
+    metadata?: Record<string, unknown>;
+    source?: string;
+    idempotencyKey?: string;
+}
+/** Response from POST .../workspaces/:id/subscription/usage */
+export interface IRecordUsageResponse {
+    used: number;
+    consumed: number;
+    included: number;
+    available: number;
+    overage: number;
+    billedAsync: boolean;
+}
+/** Single quota usage status (shared between status and all endpoints). */
+export interface IQuotaUsageStatus {
+    consumed: number;
+    included: number;
+    available: number;
+    overage: number;
+    hasOverage: boolean;
+}
+/** Response from GET .../workspaces/:id/subscription/usage/status?quotaSlug=X */
+export interface IQuotaUsageStatusResponse extends IQuotaUsageStatus {
+    quotaSlug: string;
+}
+/** Response from GET .../workspaces/:id/subscription/usage/all */
+export interface IAllQuotaUsageResponse {
+    quotas: Record<string, IQuotaUsageStatus>;
+}
+/** Single usage log entry from GET .../usage/logs */
+export 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 */
+export interface IUsageLogsQuery {
+    quotaSlug?: string;
+    from?: string;
+    to?: string;
+    source?: string;
+    page?: number;
+    limit?: number;
+}
+/** Paginated response from GET .../workspaces/:id/subscription/usage/logs */
+export interface IUsageLogsResponse {
+    docs: IUsageLogEntry[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}

package/dist/types/components/features/index.d.ts

@@ -38,7 +38,10 @@ interface IProps {
  * }
  * ```
  */
-export declare const WhenWorkspaceFeatureEnabled: (props: IProps) => import("react").ReactNode;
+export declare const WhenWorkspaceFeatureEnabled: {
+    (props: IProps): import("react").ReactNode;
+    displayName: string;
+};
 /**
  * Conditional component that renders children only when the specified workspace feature is disabled.
  * Checks feature flags at the workspace level.
@@ -58,7 +61,10 @@ export declare const WhenWorkspaceFeatureEnabled: (props: IProps) => import("rea
  * }
  * ```
  */
-export declare const WhenWorkspaceFeatureDisabled: (props: IProps) => import("react").ReactNode;
+export declare const WhenWorkspaceFeatureDisabled: {
+    (props: IProps): import("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).
@@ -94,7 +100,10 @@ export declare const WhenWorkspaceFeatureDisabled: (props: IProps) => import("re
  * }
  * ```
  */
-export declare const WhenUserFeatureEnabled: (props: IProps) => import("react").ReactNode;
+export declare const WhenUserFeatureEnabled: {
+    (props: IProps): import("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).
@@ -114,5 +123,8 @@ export declare const WhenUserFeatureEnabled: (props: IProps) => import("react").
  * }
  * ```
  */
-export declare const WhenUserFeatureDisabled: (props: IProps) => import("react").ReactNode;
+export declare const WhenUserFeatureDisabled: {
+    (props: IProps): import("react").ReactNode;
+    displayName: string;
+};
 export {};

package/dist/types/components/quota/index.d.ts

@@ -0,0 +1,121 @@
+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>
+ * ```
+ */
+export declare const WhenQuotaAvailable: {
+    (props: IWhenQuotaProps): import("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>
+ * ```
+ */
+export declare const WhenQuotaExhausted: {
+    (props: IWhenQuotaProps): import("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>
+ * ```
+ */
+export declare const WhenQuotaOverage: {
+    (props: IWhenQuotaProps): import("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>
+ * ```
+ */
+export declare const WhenQuotaThreshold: {
+    (props: IWhenQuotaThresholdProps): import("react").ReactNode;
+    displayName: string;
+};
+export {};

package/dist/types/components/subscription/index.d.ts

@@ -34,7 +34,10 @@ interface IWhenSubscriptionProps {
  * </WhenSubscription>
  * ```
  */
-export declare const WhenSubscription: (props: IWhenSubscriptionProps) => import("react").ReactNode;
+export declare const WhenSubscription: {
+    (props: IWhenSubscriptionProps): import("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).
@@ -63,7 +66,10 @@ export declare const WhenSubscription: (props: IWhenSubscriptionProps) => import
  * </WhenNoSubscription>
  * ```
  */
-export declare const WhenNoSubscription: (props: IWhenSubscriptionProps) => import("react").ReactNode;
+export declare const WhenNoSubscription: {
+    (props: IWhenSubscriptionProps): import("react").ReactNode;
+    displayName: string;
+};
 interface IWhenSubscriptionToPlansProps {
     /** Plan slugs to match (e.g. ['pro', 'enterprise']). Matching is case-insensitive. */
     plans: string[];
@@ -104,5 +110,8 @@ interface IWhenSubscriptionToPlansProps {
  * </WhenSubscriptionToPlans>
  * ```
  */
-export declare const WhenSubscriptionToPlans: (props: IWhenSubscriptionToPlansProps) => import("react").ReactNode;
+export declare const WhenSubscriptionToPlans: {
+    (props: IWhenSubscriptionToPlansProps): import("react").ReactNode;
+    displayName: string;
+};
 export {};

package/dist/types/components/user/auth.d.ts

@@ -24,7 +24,10 @@ interface IProps {
  * }
  * ```
  */
-export declare const WhenAuthenticated: (props: IProps) => import("react").ReactNode;
+export declare const WhenAuthenticated: {
+    (props: IProps): import("react").ReactNode;
+    displayName: string;
+};
 /**
  * Conditional component that renders children only when user is NOT authenticated.
  * Returns null if user is authenticated.
@@ -66,5 +69,8 @@ export declare const WhenAuthenticated: (props: IProps) => import("react").React
  * }
  * ```
  */
-export declare const WhenUnauthenticated: (props: IProps) => import("react").ReactNode;
+export declare const WhenUnauthenticated: {
+    (props: IProps): import("react").ReactNode;
+    displayName: string;
+};
 export {};

package/dist/types/components/user/role.d.ts

@@ -38,7 +38,10 @@ interface IProps {
  * }
  * ```
  */
-export declare const WhenRoles: (props: IProps) => import("react").ReactNode;
+export declare const WhenRoles: {
+    (props: IProps): import("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.
@@ -74,5 +77,8 @@ export declare const WhenRoles: (props: IProps) => import("react").ReactNode;
  * }
  * ```
  */
-export declare const WhenWorkspaceRoles: (props: IProps) => import("react").ReactNode;
+export declare const WhenWorkspaceRoles: {
+    (props: IProps): import("react").ReactNode;
+    displayName: string;
+};
 export {};

package/dist/types/contexts/QuotaUsageContext/QuotaUsageContext.d.ts

@@ -0,0 +1,22 @@
+import React, { type ReactNode } from 'react';
+import type { QuotaUsageContextValue } from './types';
+/**
+ * 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
+ */
+export declare const QuotaUsageContextProvider: React.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
+ */
+export declare function useQuotaUsageContext(): QuotaUsageContextValue;

package/dist/types/contexts/QuotaUsageContext/index.d.ts

@@ -0,0 +1,2 @@
+export { QuotaUsageContextProvider, useQuotaUsageContext } from './QuotaUsageContext';
+export type { QuotaUsageContextValue } from './types';

package/dist/types/contexts/QuotaUsageContext/quotaUsageInvalidation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Internal notifier for quota usage data invalidation.
+ * When usage is recorded (via useRecordUsage), call invalidateQuotaUsage()
+ * so QuotaUsageContextProvider refetches and gates stay in sync.
+ */
+type Listener = () => void;
+/**
+ * Subscribe a refetch callback to be called when quota usage is invalidated.
+ *
+ * @param fn - Callback (e.g. refetch) to run when invalidateQuotaUsage() is called
+ * @returns Unsubscribe function to remove the callback
+ */
+export declare function subscribeQuotaUsageInvalidate(fn: Listener): () => void;
+/**
+ * Notify all subscribers to refetch quota usage (e.g. after recording usage).
+ * Called internally by useRecordUsage on success.
+ */
+export declare function invalidateQuotaUsage(): void;
+export {};

package/dist/types/contexts/QuotaUsageContext/types.d.ts

@@ -0,0 +1,14 @@
+import type { IQuotaUsageStatus } from '../../api/types';
+/**
+ * Value provided by QuotaUsageContext and returned by useQuotaUsageContext.
+ */
+export 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>;
+}

package/dist/types/contexts/SubscriptionContext/types.d.ts

@@ -7,6 +7,8 @@ export 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>;
 }

package/dist/types/index.d.ts

@@ -8,8 +8,13 @@ export { WhenAuthenticated, WhenUnauthenticated } from './components/user/auth';
 export { WhenRoles, WhenWorkspaceRoles } from './components/user/role';
 export { WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, } from './components/features';
 export { WhenNoSubscription, WhenSubscription, WhenSubscriptionToPlans, } from './components/subscription';
+export { WhenQuotaAvailable, WhenQuotaExhausted, WhenQuotaOverage, WhenQuotaThreshold, } from './components/quota';
 export { SubscriptionContextProvider, useSubscriptionContext, } from './contexts/SubscriptionContext';
 export type { SubscriptionContextValue } from './contexts/SubscriptionContext';
+export { invalidateSubscription } from './contexts/SubscriptionContext/subscriptionInvalidation';
+export { QuotaUsageContextProvider, useQuotaUsageContext, } from './contexts/QuotaUsageContext';
+export type { QuotaUsageContextValue } from './contexts/QuotaUsageContext';
+export { invalidateQuotaUsage } from './contexts/QuotaUsageContext/quotaUsageInvalidation';
 export { AuthStatus } from './providers/auth/types';
 export type { OnWorkspaceChangeParams } from './providers/auth/types';
 export { useSaaSAuth } from './providers/auth/hooks';
@@ -17,7 +22,7 @@ export { useSaaSOs, useSaaSSettings } from './providers/os/hooks';
 export { useUserAttributes, useUserFeatures } from './providers/user/hooks';
 export { useSaaSWorkspaces } from './providers/workspace/hooks';
 export { WorkspaceSwitcher } from './providers/workspace/provider';
-export { useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useSubscription, useSubscriptionManagement, useUpdateSubscription, } from './providers/workspace/subscription-hooks';
+export { useAllQuotaUsage, useCancelSubscription, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useQuotaUsageStatus, useRecordUsage, useResumeSubscription, useSubscription, useSubscriptionManagement, useUpdateSubscription, useUsageLogs, } from './providers/workspace/subscription-hooks';
 export { eventEmitter } from './providers/events';
 export type { EventData, EventType, IEventCallbacks, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData, } from './providers/events/types';
 export { BaseApi, SettingsApi, UserApi, WorkspaceApi } from './api';
@@ -27,4 +32,4 @@ export { formatQuotaWithPrice, getQuotaDisplayValue } from './api/quota-utils';
 export type { FormatQuotaWithPriceOptions, QuotaDisplayValue } from './api/quota-utils';
 export { getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getDisplayCurrency, getPricingVariant, getQuotaDisplayWithVariant, getQuotaOverageCents, getStripePriceIdForInterval, } from './api/pricing-variant-utils';
 export type { PlanVersionWithPricingVariants, QuotaDisplayWithOverage, } from './api/pricing-variant-utils';
-export type { BillingInterval, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, 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, } from './api/types';
+export type { BillingInterval, IAllQuotaUsageResponse, IBasePricing, ICheckoutSessionRequest, ICheckoutSessionResponse, 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, } from './api/types';

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

@@ -1,4 +1,4 @@
-import { ICheckoutSessionRequest, ICheckoutSessionResponse, IInvoiceListResponse, IInvoiceResponse, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionsResponse, IPublicPlansResponse, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUser } from '../../api/types';
+import { IAllQuotaUsageResponse, ICheckoutSessionRequest, ICheckoutSessionResponse, IInvoiceListResponse, IInvoiceResponse, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionsResponse, IPublicPlansResponse, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogsQuery, IUsageLogsResponse, IUser } from '../../api/types';
 import { BaseApi } from '../../lib/api-base';
 import { IOsConfig } from '../os/types';
 import type { IWorkspace, IWorkspaceFeature, IWorkspaceUser } from './types';
@@ -125,4 +125,31 @@ export 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>;
 }

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

@@ -1,4 +1,4 @@
-import { BillingInterval, ICheckoutSessionRequest, ICheckoutSessionResponse, IInvoice, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionsResponse, ISubscriptionResponse, ISubscriptionUpdateResponse } from '../../api/types';
+import { BillingInterval, ICheckoutSessionRequest, ICheckoutSessionResponse, IInvoice, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionsResponse, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, ISubscriptionResponse, ISubscriptionUpdateResponse, IUsageLogEntry } from '../../api/types';
 /**
  * Hook to get public plans by slug (no auth required).
  * Returns items (features, limits, quotas) and plans (with pricing).
@@ -561,3 +561,181 @@ export declare const useResumeSubscription: (workspaceId: string | null | undefi
     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>
+ *   );
+ * }
+ * ```
+ */
+export 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>
+ *   );
+ * }
+ * ```
+ */
+export 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>
+ *   );
+ * }
+ * ```
+ */
+export 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>
+ *   );
+ * }
+ * ```
+ */
+export 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>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildbase/sdk",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "type": "module",
   "description": "A SDK for Buildbase",
   "main": "dist/index.js",