@buildbase/sdk 0.0.18 → 0.0.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -318,6 +318,18 @@ function FeatureExample() {
318
318
 
319
319
  Use the `useUserFeatures` hook to check feature flags programmatically:
320
320
 
321
+ ```tsx
322
+ import { useUserFeatures } from '@buildbase/sdk';
323
+
324
+ function FeatureCheck() {
325
+ const { features, isFeatureEnabled, refreshFeatures } = useUserFeatures();
326
+
327
+ return (
328
+ <div>{isFeatureEnabled('premium-features') ? <PremiumContent /> : <StandardContent />}</div>
329
+ );
330
+ }
331
+ ```
332
+
321
333
  ## 📋 Subscription Gates
322
334
 
323
335
  Control UI visibility based on the current workspace’s subscription. Subscription data is loaded once per workspace and refetched when the workspace changes or when the subscription is updated (e.g. upgrade, cancel, resume).
@@ -411,22 +423,6 @@ function SubscriptionStatus() {
411
423
  - When subscription is updated via SDK (e.g. `useUpdateSubscription`, cancel, resume) — refetch is triggered automatically.
412
424
  - When you call `refetch()` (e.g. after redirect from checkout).
413
425
 
414
- ### Feature Flags Hook
415
-
416
- Use the `useUserFeatures` hook to check feature flags programmatically:
417
-
418
- ```tsx
419
- import { useUserFeatures } from '@buildbase/sdk';
420
-
421
- function FeatureCheck() {
422
- const { features, isFeatureEnabled, refreshFeatures } = useUserFeatures();
423
-
424
- return (
425
- <div>{isFeatureEnabled('premium-features') ? <PremiumContent /> : <StandardContent />}</div>
426
- );
427
- }
428
- ```
429
-
430
426
  ## 👤 User Management
431
427
 
432
428
  ### User Attributes
@@ -640,7 +636,7 @@ import { SaaSOSProvider, eventEmitter } from '@buildbase/sdk';
640
636
 
641
637
  ## 🛡️ Error Handling
642
638
 
643
- The SDK handles errors internally: API failures, auth errors, and component errors are logged and surfaced through hook states (e.g. `error` from `useSaaSWorkspaces`) and callbacks. Wrap your app in an error boundary of your choice to catch React errors. For failed operations, check the `error` property on hooks and handle it in your UI (e.g. toast or inline message).
639
+ The SDK handles errors internally: API failures, auth errors, and component errors are logged and surfaced through hook states (e.g. `error` from `useSaaSWorkspaces`) and callbacks. **SaaSOSProvider** wraps its children in an internal **SDKErrorBoundary** to catch React render errors inside the SDK tree. For app-level errors, wrap your app (or routes) in your own error boundary (e.g. React’s `ErrorBoundary` or your framework’s error UI). For failed async operations, check the `error` property on hooks and show user feedback (e.g. toast or inline message). See [Error codes](docs/ERROR_CODES.md) for SDK error codes and HTTP mappings.
644
640
 
645
641
  ## ⚙️ Settings
646
642
 
@@ -674,21 +670,18 @@ All SDK API clients extend a shared base class and are exported from the package
674
670
  | `WorkspaceApi` | Workspaces, subscription, invoices, users |
675
671
  | `SettingsApi` | Organization settings |
676
672
 
677
- Use the hooks (`useUserApi`, `useWorkspaceApi`, etc.) for a ready-made instance with OS config, or instantiate with your own config:
673
+ Get OS config from `useSaaSOs()` and instantiate API classes when you need low-level access; otherwise prefer the high-level hooks (`useSaaSWorkspaces`, `useUserAttributes`, `useSaaSSettings`, etc.):
678
674
 
679
675
  ```tsx
680
676
  import { UserApi, WorkspaceApi, SettingsApi, useSaaSOs } from '@buildbase/sdk';
681
677
 
682
- // Via hook (uses OS config from context)
683
- const api = useWorkspaceApi(); // or useUserApi(), etc.
684
-
685
- // Or instantiate with config
686
678
  const os = useSaaSOs();
687
679
  const workspaceApi = new WorkspaceApi({
688
680
  serverUrl: os.serverUrl,
689
681
  version: os.version,
690
682
  orgId: os.orgId,
691
683
  });
684
+ // Similarly: new UserApi({ ... }), new SettingsApi({ ... })
692
685
  ```
693
686
 
694
687
  ### Hooks
@@ -719,7 +712,7 @@ All TypeScript types are exported for type safety. See the [TypeScript definitio
719
712
 
720
713
  ### Further documentation
721
714
 
722
- - [Architecture](docs/ARCHITECTURE.md) – Layers, APIs (BaseApi, UserApi, WorkspaceApi, SettingsApi), state, auth flow
715
+ - [Architecture](docs/ARCHITECTURE.md) – Layers, providers, APIs (BaseApi, UserApi, WorkspaceApi, SettingsApi), state, auth flow
723
716
  - [Error codes](docs/ERROR_CODES.md) – SDK error codes and HTTP status mappings
724
717
 
725
718
  ## ⚙️ Configuration Reference
package/dist/index.d.ts CHANGED
@@ -4,7 +4,8 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
4
4
 
5
5
  interface IDocument {
6
6
  _id: string;
7
- id: string;
7
+ /** Optional; some APIs only return _id. Prefer _id for identity. */
8
+ id?: string;
8
9
  createdAt: string;
9
10
  updatedAt: string;
10
11
  deleted: boolean;
@@ -13,12 +14,17 @@ interface IUser extends IDocument {
13
14
  _id: string;
14
15
  name: string;
15
16
  email: string;
16
- image: string;
17
+ /** Profile image URL. Often omitted or empty from API. */
18
+ image?: string;
17
19
  role: string;
18
- country: string;
19
- timezone: string;
20
- language: string;
21
- currency: string;
20
+ /** ISO country code. May be omitted. */
21
+ country?: string;
22
+ /** IANA timezone. May be omitted. */
23
+ timezone?: string;
24
+ /** Language code. May be omitted. */
25
+ language?: string;
26
+ /** Currency code. May be omitted. */
27
+ currency?: string;
22
28
  attributes?: Record<string, string | number | boolean>;
23
29
  }
24
30
  type BillingInterval = 'monthly' | 'yearly' | 'quarterly';
@@ -36,6 +42,8 @@ interface ISubscription {
36
42
  name: string;
37
43
  slug: string;
38
44
  description?: string;
45
+ /** Stripe currency code (e.g. 'usd', 'inr', 'eur'). */
46
+ currency?: string;
39
47
  };
40
48
  }
41
49
  interface ISubscriptionItem {
@@ -46,17 +54,14 @@ interface ISubscriptionItem {
46
54
  description?: string;
47
55
  category: string;
48
56
  }
49
- interface IQuotaValue {
50
- included: number;
51
- overage?: number;
52
- stripePriceId?: string;
53
- }
54
- /** Per-interval quota value (new plan-group/versions schema) */
57
+ /** Per-interval quota value (plan-group/versions and public plans schema). */
55
58
  interface IQuotaIntervalValue {
56
59
  included: number;
57
- overage: number;
58
- priceId: string;
59
- /** Optional unit size for overage pricing (e.g. 1000 = price per 1000 units). */
60
+ /** Overage price in cents. Omitted in public plans; use pricingVariant.quotaOverages for display. */
61
+ overage?: number;
62
+ /** Stripe price ID for overage. Omitted in public plans; use pricingVariant.quotaOveragePriceIds. */
63
+ priceId?: string;
64
+ /** Unit size for overage pricing (e.g. 1000 = price per 1000 units). */
60
65
  unitSize?: number;
61
66
  }
62
67
  /** Quota defined per billing interval (new plan-group/versions schema) */
@@ -65,11 +70,46 @@ interface IQuotaByInterval {
65
70
  yearly?: IQuotaIntervalValue;
66
71
  quarterly?: IQuotaIntervalValue;
67
72
  }
73
+ /** Base pricing per interval. Values are often in cents (Stripe); convert for display. */
68
74
  interface IBasePricing {
69
75
  monthly: number;
70
76
  yearly: number;
71
77
  quarterly: number;
72
78
  }
79
+ /** Stripe price IDs per billing interval (for a single currency variant). */
80
+ interface IStripePricesByInterval {
81
+ monthlyPriceId?: string;
82
+ yearlyPriceId?: string;
83
+ quarterlyPriceId?: string;
84
+ monthly?: string;
85
+ yearly?: string;
86
+ }
87
+ /** Overage amounts in cents per interval, keyed by quota slug. Used in pricing variants. */
88
+ type IQuotaOveragesByInterval = Record<string, {
89
+ monthly?: number;
90
+ yearly?: number;
91
+ quarterly?: number;
92
+ }>;
93
+ /** Overage Stripe price IDs per interval, keyed by quota slug. Used in pricing variants. */
94
+ type IQuotaOveragePriceIdsByInterval = Record<string, {
95
+ monthly?: string;
96
+ yearly?: string;
97
+ quarterly?: string;
98
+ }>;
99
+ /**
100
+ * Multi-currency pricing variant at plan version level.
101
+ * Each plan version can have multiple variants (e.g. usd, eur, inr, sgd).
102
+ */
103
+ interface IPricingVariant {
104
+ _id: string;
105
+ currency: string;
106
+ basePricing: IBasePricing;
107
+ stripePrices: IStripePricesByInterval;
108
+ /** Overage cents per quota slug per interval. */
109
+ quotaOverages?: IQuotaOveragesByInterval;
110
+ /** Stripe price IDs for overage per quota slug per interval. */
111
+ quotaOveragePriceIds?: IQuotaOveragePriceIdsByInterval;
112
+ }
73
113
  interface IPlanVersion {
74
114
  _id: string;
75
115
  version: number;
@@ -77,16 +117,10 @@ interface IPlanVersion {
77
117
  status: 'draft' | 'published';
78
118
  features?: Record<string, boolean>;
79
119
  limits?: Record<string, number>;
80
- /** Legacy: number | IQuotaValue. New schema: IQuotaByInterval (per-interval included/overage/priceId) */
81
- quotas?: Record<string, number | IQuotaValue | IQuotaByInterval>;
82
- basePricing?: IBasePricing;
83
- stripePrices?: {
84
- monthlyPriceId?: string;
85
- yearlyPriceId?: string;
86
- quarterlyPriceId?: string;
87
- monthly?: string;
88
- yearly?: string;
89
- };
120
+ /** Per-interval quotas (included, unitSize; overage from pricingVariant.quotaOverages). */
121
+ quotas?: Record<string, IQuotaByInterval>;
122
+ /** Multi-currency pricing. Each variant has currency, basePricing, stripePrices, quotaOverages. */
123
+ pricingVariants?: IPricingVariant[];
90
124
  subscriptionItems?: ISubscriptionItem[];
91
125
  isCurrent?: boolean;
92
126
  isLegacy?: boolean;
@@ -106,6 +140,8 @@ interface IPlan {
106
140
  name: string;
107
141
  slug: string;
108
142
  description?: string;
143
+ /** Stripe currency code (e.g. 'usd', 'inr', 'eur'). Used for pricing display. */
144
+ currency?: string;
109
145
  latestVersion?: IPlanVersionSummary;
110
146
  archived?: boolean;
111
147
  deleted?: boolean;
@@ -166,13 +202,19 @@ interface ISubscriptionResponse {
166
202
  group: IPlanGroup | null;
167
203
  groupVersion: IPlanGroupVersion | null;
168
204
  }
205
+ /** Plan version with nested plan info (name, slug, currency for display). */
169
206
  interface IPlanVersionWithPlan extends IPlanVersion {
170
207
  plan: IPlan;
171
208
  }
209
+ /**
210
+ * Plan group version with full plan versions (for GET .../plan-group/versions).
211
+ * Each plan has plan, subscriptionItems, quotas (per-interval), pricingVariants.
212
+ */
172
213
  interface IPlanGroupVersionWithPlans {
173
214
  _id: string;
174
215
  version: number;
175
216
  description?: string;
217
+ /** Full plan versions with nested plan (name, slug, currency). */
176
218
  plans: IPlanVersionWithPlan[];
177
219
  isCurrent?: boolean;
178
220
  whatsNew?: {
@@ -189,18 +231,27 @@ interface IPlanGroupInfo {
189
231
  }
190
232
  /** Response from GET workspaces/:id/subscription/plan-group (and by version). */
191
233
  interface IPlanGroupResponse {
192
- /** Plan group with latestVersion, archived, deleted, timestamps. */
193
- group: IPlanGroup;
234
+ /** Plan group with latestVersion, archived, deleted, timestamps. May be null in some API responses. */
235
+ group: IPlanGroup | null;
194
236
  /** Current group version with populated planVersionIds (or IDs). */
195
237
  groupVersion: IPlanGroupVersion;
196
- /** Full plan versions for display (subscriptionItems, basePricing, quotas, etc.). */
238
+ /** Full plan versions for display (subscriptionItems, pricingVariants, quotas). */
197
239
  plans: IPlanVersionWithPlan[];
198
240
  }
241
+ /**
242
+ * Response from GET workspaces/:workspaceId/subscription/plan-group/versions.
243
+ * Group summary plus current and available group versions; each version has plans with
244
+ * per-interval quotas and pricingVariants.
245
+ */
199
246
  interface IPlanGroupVersionsResponse {
247
+ /** Plan group summary (_id, name, slug). */
200
248
  group: IPlanGroupInfo;
249
+ /** Current group version (user's version when subscribed, or latest published when not). */
201
250
  currentVersion: IPlanGroupVersionWithPlans;
251
+ /** Newer versions when user has subscription; empty when no subscription. */
202
252
  availableVersions: IPlanGroupVersionWithPlans[];
203
253
  }
254
+ /** Request body for POST .../workspaces/:id/subscription/checkout. Only these fields are allowed. */
204
255
  interface ICheckoutSessionRequest {
205
256
  planVersionId: string;
206
257
  billingInterval?: BillingInterval;
@@ -218,6 +269,7 @@ interface ICheckoutSessionResponse {
218
269
  name: string;
219
270
  };
220
271
  }
272
+ /** Request body for PATCH .../workspaces/:id/subscription. Only these fields are allowed. */
221
273
  interface ISubscriptionUpdateRequest {
222
274
  planVersionId: string;
223
275
  billingInterval?: BillingInterval;
@@ -244,33 +296,33 @@ interface IPublicPlanItem {
244
296
  _id: string;
245
297
  name: string;
246
298
  slug: string;
247
- description: string;
299
+ description?: string;
248
300
  type: 'feature' | 'limit' | 'quota';
249
301
  category: IPublicPlanItemCategory;
250
302
  }
251
- interface IPublicPlanPricing {
252
- monthly: number;
253
- yearly: number;
254
- quarterly: number;
255
- }
256
- interface IPublicPlanQuotaValue {
257
- included: number;
258
- overage: number;
259
- stripePriceId?: string;
260
- }
303
+ /**
304
+ * Public plan version (e.g. from GET /api/v1/public/:orgId/plans/:slug).
305
+ * Each plan has _id, name (plan display name), version, status, pricingVariants, quotas, features, limits.
306
+ * Pricing is in cents (see response.notes).
307
+ */
261
308
  interface IPublicPlanVersion {
262
309
  _id: string;
310
+ /** Plan display name (e.g. "Pro", "Base Plan"). */
263
311
  name: string;
264
312
  version: number;
265
313
  status: 'draft' | 'published';
266
- pricing: IPublicPlanPricing;
267
- quotas: Record<string, IPublicPlanQuotaValue>;
314
+ /** Multi-currency pricing. Use getBasePriceCents(plan, currency, interval) and getQuotaDisplayWithVariant for display. */
315
+ pricingVariants?: IPricingVariant[];
316
+ /** Keyed by item slug. Per-interval: included, unitSize; overage from pricingVariant.quotaOverages. */
317
+ quotas: Record<string, IQuotaByInterval>;
268
318
  features: Record<string, boolean>;
269
319
  limits: Record<string, number>;
270
320
  }
271
321
  interface IPublicPlansResponse {
272
322
  items: IPublicPlanItem[];
273
323
  plans: IPublicPlanVersion[];
324
+ /** Optional note from API (e.g. "Pricing is in cents. Please convert to dollars for display."). */
325
+ notes?: string;
274
326
  }
275
327
  type InvoiceStatus = 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
276
328
  interface IInvoice {
@@ -306,7 +358,24 @@ interface IWorkspace {
306
358
  roles: string[];
307
359
  createdBy: string | IUser;
308
360
  features: Record<string, boolean>;
309
- subscription?: ISubscription | null;
361
+ /**
362
+ * Quota usage tracking: { [quotaSlug]: number } – how much of each quota has been used.
363
+ */
364
+ quotas?: Record<string, number>;
365
+ /**
366
+ * Subscription limits snapshot: { [limitSlug]: number | null } – synced from subscription plan.
367
+ * Limits are maximum values (e.g. max-users, max-workspaces). Updated when subscription is assigned/updated.
368
+ */
369
+ limits?: Record<string, number | null>;
370
+ subscription?: ISubscription | string | null;
371
+ /** Stripe Customer ID for this workspace. */
372
+ stripeCustomerId?: string;
373
+ /**
374
+ * Billing currency locked for this workspace (set on first subscription).
375
+ * Stripe allows one currency per customer; all future subscriptions must use this currency.
376
+ * When set, subscription UI only shows/uses this currency.
377
+ */
378
+ billingCurrency?: string | null;
310
379
  }
311
380
  interface IWorkspaceFeature {
312
381
  _id: string;
@@ -500,6 +569,8 @@ interface PricingPageDetails {
500
569
  items: IPublicPlanItem[];
501
570
  /** Plan versions with pricing, features, limits, quotas */
502
571
  plans: IPublicPlanVersion[];
572
+ /** Optional note from API (e.g. "Pricing is in cents. Please convert to dollars for display.") */
573
+ notes?: string;
503
574
  /** Refetch plan data */
504
575
  refetch: () => Promise<void>;
505
576
  }
@@ -1300,7 +1371,7 @@ declare const useSaaSWorkspaces: () => {
1300
1371
  forceEmit?: boolean;
1301
1372
  }) => Promise<void>;
1302
1373
  resetCurrentWorkspace: () => void;
1303
- createWorkspace: (name: string, image: string) => Promise<void>;
1374
+ createWorkspace: (name: string, image?: string) => Promise<void>;
1304
1375
  allFeatures: IWorkspaceFeature[];
1305
1376
  getFeatures: () => Promise<IWorkspaceFeature[] | null>;
1306
1377
  updateFeature: (workspaceId: string, key: string, value: boolean) => Promise<IWorkspace>;
@@ -1346,6 +1417,7 @@ declare function WorkspaceSwitcher(props: {
1346
1417
  declare const usePublicPlans: (slug: string) => {
1347
1418
  items: IPublicPlanItem[];
1348
1419
  plans: IPublicPlanVersion[];
1420
+ notes: string | undefined;
1349
1421
  loading: boolean;
1350
1422
  error: string | null;
1351
1423
  refetch: () => Promise<void>;
@@ -1906,23 +1978,122 @@ declare class SettingsApi extends BaseApi {
1906
1978
  getSettings(signal?: AbortSignal): Promise<ISettings>;
1907
1979
  }
1908
1980
 
1981
+ /**
1982
+ * Centralized formatting for subscription/quota display: cents, overage rates, included + overage text.
1983
+ * Currency must be provided by the caller (e.g. workspace.billingCurrency, plan.currency, or selected currency).
1984
+ */
1985
+ /** Common currency display (code or symbol). Use lowercase Stripe codes (usd, eur, etc.). */
1986
+ declare const CURRENCY_DISPLAY: Record<string, string>;
1987
+ /** Currency code to flag emoji (country/region associated with the currency). Use for dropdowns. */
1988
+ declare const CURRENCY_FLAG: Record<string, string>;
1989
+ /** Get flag emoji for a currency code. Returns empty string when unknown or empty. */
1990
+ declare function getCurrencyFlag(currency: string): string;
1991
+ /** Get currency symbol for display. Use lowercase Stripe codes (usd, eur). Returns code when unknown; empty string when currency is empty. */
1992
+ declare function getCurrencySymbol(currency: string): string;
1993
+ /** Allowed plan/pricing currency codes (must match server ALLOWED_BILLING_CURRENCIES). Use for dropdowns and validation. */
1994
+ declare const PLAN_CURRENCY_CODES: readonly ["usd", "eur", "gbp", "jpy", "cad", "aud", "chf", "cny", "hkd", "sgd", "inr", "mxn", "brl", "nzd", "sek", "nok", "dkk", "pln", "thb"];
1995
+ /** Options for plan currency select: { value, label } with symbol. Use in CreateOrEditPlan and anywhere a currency dropdown is needed. */
1996
+ declare const PLAN_CURRENCY_OPTIONS: {
1997
+ value: "usd" | "eur" | "gbp" | "jpy" | "cad" | "aud" | "chf" | "cny" | "hkd" | "sgd" | "inr" | "mxn" | "brl" | "nzd" | "sek" | "nok" | "dkk" | "pln" | "thb";
1998
+ label: string;
1999
+ }[];
2000
+ /** Format cents as money string (e.g. 1999, "usd" -> "$19.99"). Caller must pass currency (e.g. from plan or workspace). */
2001
+ declare function formatCents(cents: number, currency: string): string;
2002
+ /**
2003
+ * Format overage rate for display. When unitSize > 1: "$1.00/1,000 units"; else "$1.00/unit".
2004
+ * Returns null if overageCents is missing or negative.
2005
+ */
2006
+ declare function formatOverageRate(overageCents: number | undefined, unitSize: number | undefined, currency: string): string | null;
2007
+ /**
2008
+ * Format overage rate with optional unit label for comparison/preview UIs.
2009
+ * e.g. formatOverageRateWithLabel(50, 1000, "video") -> "$0.50/1,000 videos"
2010
+ * formatOverageRateWithLabel(46, 1, "video") -> "$0.46/video"
2011
+ * When unitLabel is omitted, falls back to formatOverageRate behavior.
2012
+ */
2013
+ declare function formatOverageRateWithLabel(overageCents: number | undefined, unitSize: number | undefined, unitLabel: string | undefined, currency: string): string | null;
2014
+ /**
2015
+ * Get singular unit label from item name or slug (e.g. "Videos" -> "video", "reels" -> "reel").
2016
+ * Used for quota display in comparison and preview.
2017
+ */
2018
+ declare function getQuotaUnitLabelFromName(nameOrSlug: string): string;
2019
+ /**
2020
+ * Format quota "included + overage" for display.
2021
+ * When unitSize >= 2: "Included: 1,000, after that $1.00/1,000 emails".
2022
+ * Otherwise: "Included: 5, after that $0.30/image".
2023
+ */
2024
+ declare function formatQuotaIncludedOverage(included: number | undefined, overageCents: number | undefined, unitLabel: string, currency: string, unitSize?: number): string;
2025
+
2026
+ /**
2027
+ * Helpers for multi-currency plan version pricing (pricingVariants).
2028
+ */
2029
+
2030
+ /** Get the pricing variant for a currency, or null if not available. */
2031
+ declare function getPricingVariant(planVersion: IPlanVersion, currency: string): IPricingVariant | null;
2032
+ /**
2033
+ * Get base price in cents for a plan version and currency/interval.
2034
+ */
2035
+ declare function getBasePriceCents(planVersion: IPlanVersion, currency: string, interval: BillingInterval): number | null;
2036
+ /**
2037
+ * Get Stripe price ID for the given plan version, currency, and interval.
2038
+ */
2039
+ declare function getStripePriceIdForInterval(planVersion: IPlanVersion, currency: string, interval: BillingInterval): string | null;
2040
+ /**
2041
+ * Get overage amount in cents for a quota in a given currency and interval.
2042
+ * Returns undefined if not defined in the pricing variant.
2043
+ */
2044
+ declare function getQuotaOverageCents(planVersion: IPlanVersion, currency: string, quotaSlug: string, interval: BillingInterval): number | undefined;
2045
+ /**
2046
+ * Get display currency for a plan version when using a given currency.
2047
+ * Returns the requested currency if the variant exists; otherwise plan.currency or null.
2048
+ */
2049
+ declare function getDisplayCurrency(planVersion: IPlanVersionWithPlan, currency: string): string;
2050
+ /** Minimal shape for extracting currencies (IPlanVersionWithPlan or IPublicPlanVersion). */
2051
+ type PlanVersionWithPricingVariants = {
2052
+ pricingVariants?: IPricingVariant[];
2053
+ };
2054
+ /**
2055
+ * Collect all unique currency codes from plan versions (from their pricingVariants).
2056
+ * Use for currency selector. Accepts IPlanVersionWithPlan[] or IPublicPlanVersion[].
2057
+ */
2058
+ declare function getAvailableCurrenciesFromPlans(planVersions: PlanVersionWithPricingVariants[]): string[];
2059
+ /**
2060
+ * Quota display shape: included count and optional overage (cents) and unitSize from plan + variant.
2061
+ */
2062
+ type QuotaDisplayWithOverage = {
2063
+ included: number;
2064
+ overage?: number;
2065
+ unitSize?: number;
2066
+ } | null;
2067
+ /**
2068
+ * Get quota display value for a slug/interval, merging plan version quotas (included, unitSize)
2069
+ * with pricing variant overage (cents) when available.
2070
+ */
2071
+ declare function getQuotaDisplayWithVariant(planVersion: IPlanVersion, currency: string, quotaSlug: string, interval: BillingInterval): QuotaDisplayWithOverage;
2072
+ /**
2073
+ * Resolve billing interval and currency from a Stripe price ID by checking all plan versions' pricingVariants.
2074
+ */
2075
+ declare function getBillingIntervalAndCurrencyFromPriceId(priceId: string | null | undefined, planVersions: IPlanVersionWithPlan[]): {
2076
+ interval: BillingInterval;
2077
+ currency: string;
2078
+ } | null;
2079
+
1909
2080
  type QuotaDisplayValue = {
1910
2081
  included: number;
1911
2082
  overage?: number;
1912
2083
  unitSize?: number;
1913
- } | number | null;
2084
+ } | null;
1914
2085
  /**
1915
- * Normalize a quota value (legacy or per-interval) to a display shape for a given billing interval.
1916
- * - Legacy: number or IQuotaValue → use as-is (interval ignored).
1917
- * - New schema: IQuotaByInterval → pick the interval slice (e.g. monthly, yearly, quarterly).
2086
+ * Normalize a per-interval quota value to a display shape for the given billing interval.
1918
2087
  */
1919
- declare function getQuotaDisplayValue(value: number | IQuotaValue | IQuotaByInterval | null | undefined, interval?: BillingInterval): QuotaDisplayValue;
2088
+ declare function getQuotaDisplayValue(value: IQuotaByInterval | null | undefined, interval?: BillingInterval): QuotaDisplayValue;
1920
2089
  /** Options for formatting quota with price. */
1921
2090
  interface FormatQuotaWithPriceOptions {
1922
2091
  /** If true, overage is in cents (Stripe); format as dollars. Default true. */
1923
2092
  overageInCents?: boolean;
1924
- /** Currency symbol. Default '$'. */
2093
+ /** Currency symbol override. When omitted, derived from `currency` (empty if no currency). */
1925
2094
  currencySymbol?: string;
2095
+ /** Stripe currency code (e.g. 'usd', 'inr'). Used to resolve symbol when currencySymbol is not set. */
2096
+ currency?: string;
1926
2097
  }
1927
2098
  /**
1928
2099
  * Format a quota display value as "X included, then $Y.YY / unit" (e.g. "10 included, then $10.00 / video").
@@ -1930,5 +2101,5 @@ interface FormatQuotaWithPriceOptions {
1930
2101
  */
1931
2102
  declare function formatQuotaWithPrice(value: QuotaDisplayValue, unitName: string, options?: FormatQuotaWithPriceOptions): string;
1932
2103
 
1933
- export { ApiVersion, AuthStatus, BaseApi, BetaForm, PricingPage, SaaSOSProvider, SettingsApi, SubscriptionContextProvider, UserApi, WhenAuthenticated, WhenNoSubscription, WhenRoles, WhenSubscription, WhenSubscriptionToPlans, WhenUnauthenticated, WhenUserFeatureDisabled, WhenUserFeatureEnabled, WhenWorkspaceFeatureDisabled, WhenWorkspaceFeatureEnabled, WhenWorkspaceRoles, WorkspaceApi, WorkspaceSwitcher, eventEmitter, formatQuotaWithPrice, getQuotaDisplayValue, useCreateCheckoutSession, useInvoice, useInvoices, usePlanGroup, usePlanGroupVersions, usePublicPlanGroupVersion, usePublicPlans, useSaaSAuth, useSaaSOs, useSaaSSettings, useSaaSWorkspaces, useSubscription, useSubscriptionContext, useSubscriptionManagement, useUpdateSubscription, useUserAttributes, useUserFeatures };
1934
- 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, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanPricing, IPublicPlanQuotaValue, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaValue, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, InvoiceStatus, OnWorkspaceChangeParams, PricingPageDetails, PricingPageProps, QuotaDisplayValue, SubscriptionContextValue, UserCreatedEventData, UserUpdatedEventData, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
2104
+ 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 };
2105
+ 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 };