@buildbase/sdk 0.0.19 → 0.0.21

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/dist/types/providers/workspace/ui/SettingsDialog.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { IWorkspace } from '../types';
-export type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'features' | 'danger';
+export type WorkspaceSettingsSection = 'profile' | 'general' | 'users' | 'subscription' | 'usage' | 'features' | 'danger';
 export interface WorkspaceSettingsDialogProps {
     workspace: IWorkspace;
     onClose?: () => void;

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

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const WorkspaceSettingsUsage: React.FC;
+export default WorkspaceSettingsUsage;

package/package.json

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