@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 +16 -23
- package/dist/index.d.ts +222 -51
- package/dist/index.esm.js +4 -4
- package/dist/index.esm.js.map +1 -1
- package/dist/index.js +4 -4
- package/dist/index.js.map +1 -1
- package/dist/saas-os.css +1 -1
- package/dist/types/api/currency-utils.d.ts +44 -0
- package/dist/types/api/index.d.ts +5 -0
- package/dist/types/api/pricing-variant-utils.d.ts +53 -0
- package/dist/types/api/quota-utils.d.ts +7 -7
- package/dist/types/api/types.d.ts +93 -41
- package/dist/types/components/pricing/PricingPage.d.ts +2 -0
- package/dist/types/index.d.ts +5 -2
- package/dist/types/providers/workspace/hooks.d.ts +1 -1
- package/dist/types/providers/workspace/subscription-hooks.d.ts +1 -0
- package/dist/types/providers/workspace/types.d.ts +18 -1
- package/dist/types/providers/workspace/ui/SubscriptionDialog.d.ts +7 -1
- package/package.json +1 -1
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
17
|
+
/** Profile image URL. Often omitted or empty from API. */
|
|
18
|
+
image?: string;
|
|
17
19
|
role: string;
|
|
18
|
-
country
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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
|
-
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
/**
|
|
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
|
-
/**
|
|
81
|
-
quotas?: Record<string,
|
|
82
|
-
basePricing
|
|
83
|
-
|
|
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,
|
|
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
|
|
299
|
+
description?: string;
|
|
248
300
|
type: 'feature' | 'limit' | 'quota';
|
|
249
301
|
category: IPublicPlanItemCategory;
|
|
250
302
|
}
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
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
|
|
267
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
} |
|
|
2084
|
+
} | null;
|
|
1914
2085
|
/**
|
|
1915
|
-
* Normalize a quota value
|
|
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:
|
|
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.
|
|
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,
|
|
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 };
|