@schematichq/schematic-components 2.31.1 → 2.33.0

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.
@@ -4,6 +4,11 @@ import { BillingDataProvider } from '@schematichq/schematic-react';
4
4
  import { BillingDataProviderProps } from '@schematichq/schematic-react';
5
5
  import { BillingDataStatus } from '@schematichq/schematic-react';
6
6
  import { BillingResourceName } from '@schematichq/schematic-react';
7
+ import { CreditBalanceEntry } from '@schematichq/schematic-react';
8
+ import { CreditComposition } from '@schematichq/schematic-react';
9
+ import { CreditGrant } from '@schematichq/schematic-react';
10
+ import { CreditUserUsage } from '@schematichq/schematic-react';
11
+ import { CreditUserUsageRow } from '@schematichq/schematic-react';
7
12
  import { Discount } from '@schematichq/schematic-react';
8
13
  import { FEATURE_USER_USAGE_LIMIT } from '@schematichq/schematic-react';
9
14
  import { FeatureUsage } from '@schematichq/schematic-react';
@@ -27,6 +32,8 @@ import { SetupIntent } from '@schematichq/schematic-react';
27
32
  import { SetupIntentHandle } from '@schematichq/schematic-react';
28
33
  import type { Translate } from '@schematichq/schematic-react';
29
34
  import { UpcomingInvoice } from '@schematichq/schematic-react';
35
+ import { useCreditBalances } from '@schematichq/schematic-react';
36
+ import { useCreditUserUsage } from '@schematichq/schematic-react';
30
37
  import { useFeatureUsage } from '@schematichq/schematic-react';
31
38
  import { useFeatureUserUsage } from '@schematichq/schematic-react';
32
39
  import { useInvalidateBillingData } from '@schematichq/schematic-react';
@@ -66,6 +73,129 @@ export declare interface BillLine {
66
73
  amountText: string;
67
74
  }
68
75
 
76
+ export { CreditBalanceEntry }
77
+
78
+ export { CreditComposition }
79
+
80
+ export declare interface CreditCompositionLine {
81
+ /** Credits per period in all. */
82
+ total: string;
83
+ creditName: string;
84
+ /** A period key: "day", "week", "month" or "year". */
85
+ period: string;
86
+ /** "12 Seats × 10". */
87
+ perLicense: {
88
+ quantity: string;
89
+ licenseName: string;
90
+ perUnit: string;
91
+ };
92
+ /** The flat company grant on top; `null` when there is none. */
93
+ companyGrant: string | null;
94
+ /** "1st", "22nd": the day of the month the next bill is due. */
95
+ renewsOn: string | null;
96
+ }
97
+
98
+ export { CreditGrant }
99
+
100
+ /**
101
+ * `deriveCreditUsage`: the company's credit balances as the cards show them,
102
+ * with numbers, names and dates formatted here. The wording is the
103
+ * element's, keyed by `kind`.
104
+ */
105
+ /** Why credits were granted, as the ledger words it. */
106
+ export declare type CreditGrantKind = "plan" | "bundle" | "autoTopup" | "promotional";
107
+
108
+ export declare interface CreditLedgerRow {
109
+ id: string;
110
+ kind: CreditGrantKind;
111
+ /** Credits granted. */
112
+ amount: string;
113
+ /** The credit's name for `amount`; a bundle is named in the singular. */
114
+ item: string;
115
+ /** "Sep 1, 2026". */
116
+ createdAt: string;
117
+ /** When the grant refreshes, or when it runs out; `null` for neither. */
118
+ date: {
119
+ kind: "resets" | "expires";
120
+ text: string;
121
+ } | null;
122
+ source: CreditGrant;
123
+ }
124
+
125
+ /**
126
+ * The company's credit balances, a card each: what is left, the grants
127
+ * behind it, how the plan's grants add up, and who on the team spent it.
128
+ *
129
+ * A company with no credits, and a plan that draws on none, renders
130
+ * nothing. A 404 means the account is not enabled for company reads, and
131
+ * the element says so.
132
+ */
133
+ export declare function CreditUsage({ buyMoreTarget, buyMoreUrl, className, headingLevel, locale: localeProp, onBuyMore, showDescription, showExpiration, showHeader, showIcon, showUsage, showUsageByUser, strings, visibleCredits, }: CreditUsageProps): JSX.Element | null;
134
+
135
+ export declare namespace CreditUsage {
136
+ var resources: readonly ["creditBalances"];
137
+ }
138
+
139
+ export declare interface CreditUsageProps extends ElementProps {
140
+ /** The "Credits" heading above the cards. Default false, as in the embed. */
141
+ showHeader?: boolean;
142
+ /**
143
+ * Heading level; each credit's name sits one below while the heading
144
+ * shows, and takes it when the heading is hidden. Names stay h6 under an
145
+ * h6 heading, as HTML has no h7. Default 2.
146
+ */
147
+ headingLevel?: HeadingLevel;
148
+ /** Each credit's icon; the circle is held even without one. Default true. */
149
+ showIcon?: boolean;
150
+ /** Each credit's description. Default true. */
151
+ showDescription?: boolean;
152
+ /** When each grant expires or resets, in its balance details. Default true. */
153
+ showExpiration?: boolean;
154
+ /** What is left of each credit. Default true. */
155
+ showUsage?: boolean;
156
+ /** The breakdown of consumption by user. Default true. */
157
+ showUsageByUser?: boolean;
158
+ /** Credit ids to show, in this order; every credit when absent. */
159
+ visibleCredits?: string[];
160
+ /**
161
+ * "Buy More" on a credit a bundle sells calls this. Without it or
162
+ * `buyMoreUrl` there is no button.
163
+ */
164
+ onBuyMore?: (credit: CreditBalanceEntry) => void;
165
+ /** "Buy More" links here when there is no `onBuyMore`. */
166
+ buyMoreUrl?: string;
167
+ /** `target` for `buyMoreUrl`. */
168
+ buyMoreTarget?: string;
169
+ }
170
+
171
+ export declare interface CreditUsageRow {
172
+ creditId: string;
173
+ name: string;
174
+ description: string | null;
175
+ /** A schematic-icons glyph name; `null` when the credit has none. */
176
+ icon: string | null;
177
+ /** What is left, to ten fraction digits, and the credit's name for it. */
178
+ remaining: {
179
+ amount: string;
180
+ units: string;
181
+ };
182
+ purchasable: boolean;
183
+ /** Newest first. Empty for a plan credit the company holds none of. */
184
+ ledger: CreditLedgerRow[];
185
+ composition: CreditCompositionLine | null;
186
+ /** The credit's names, for a host labelling amounts itself. */
187
+ unit: {
188
+ name: string;
189
+ singularName?: string;
190
+ pluralName?: string;
191
+ };
192
+ source: CreditBalanceEntry;
193
+ }
194
+
195
+ export { CreditUserUsage }
196
+
197
+ export { CreditUserUsageRow }
198
+
69
199
  /**
70
200
  * The tier a row's usage sits in. For overage, the tier past the soft limit
71
201
  * of a two-tier price, which is how an overage price is built; for tiered
@@ -89,6 +219,14 @@ export declare function currentTier(row: FeatureUsage): TierRange | null;
89
219
  */
90
220
  export declare const DEFAULT_STRINGS: ElementStrings & StringCatalog;
91
221
 
222
+ export declare function deriveCreditUsage(balances: CreditBalanceEntry[], options: DeriveCreditUsageOptions): CreditUsageRow[];
223
+
224
+ export declare interface DeriveCreditUsageOptions {
225
+ locale: string;
226
+ /** Credit ids to show, in this order; every credit when absent. */
227
+ visibleCredits?: string[];
228
+ }
229
+
92
230
  export declare interface DerivedPaymentMethods {
93
231
  /** Every method, in the order the server gave. */
94
232
  rows: PaymentMethodRow[];
@@ -118,6 +256,16 @@ export declare interface DeriveInvoiceListOptions {
118
256
  format?: InvoiceFormatters;
119
257
  }
120
258
 
259
+ export declare function deriveMeteredFeatures(features: FeatureUsage[], options: DeriveMeteredFeaturesOptions): MeteredFeatureRow[];
260
+
261
+ export declare interface DeriveMeteredFeaturesOptions extends UsageLimitOptions {
262
+ locale: string;
263
+ /** Feature ids to show, in this order; every metered feature when absent. */
264
+ visibleFeatures?: string[];
265
+ /** The "credits per use" line on credit-burning features. Default true. */
266
+ showCredits?: boolean;
267
+ }
268
+
121
269
  /**
122
270
  * The default is whichever row the server marked, which already prefers the
123
271
  * subscription's method over the customer's. Nothing is promoted: a list
@@ -257,6 +405,48 @@ export declare type ElementStrings = {
257
405
  includedFeaturesHideAll: string;
258
406
  includedFeaturesExpires: string;
259
407
  includedFeaturesPerLicense: string;
408
+ meteredFeaturesLoading: string;
409
+ meteredFeaturesHeader: string;
410
+ meteredFeaturesError: string;
411
+ meteredFeaturesUnavailable: string;
412
+ meteredFeaturesUsed: string;
413
+ meteredFeaturesIncluded: string;
414
+ meteredFeaturesInUse: string;
415
+ meteredFeaturesLimitOf: string;
416
+ meteredFeaturesNoLimit: string;
417
+ meteredFeaturesAddMore: string;
418
+ meteredFeaturesAdditional: string;
419
+ meteredFeaturesTier: string;
420
+ creditUsageLoading: string;
421
+ creditUsageHeader: string;
422
+ creditUsageError: string;
423
+ creditUsageUnavailable: string;
424
+ creditUsageRemaining: string;
425
+ creditUsageBuyMore: string;
426
+ creditUsageSeeDetails: string;
427
+ creditUsageHideDetails: string;
428
+ creditUsageSeeAll: string;
429
+ creditUsageHideAll: string;
430
+ creditUsageGrantPlan: string;
431
+ creditUsageGrantBundle: string;
432
+ creditUsageGrantAutoTopup: string;
433
+ creditUsageGrantPromotional: string;
434
+ creditUsageResets: string;
435
+ creditUsageExpires: string;
436
+ creditUsageComposition: string;
437
+ creditUsageCompositionWithGrant: string;
438
+ creditUsagePerLicense: string;
439
+ creditUsageCompanyGrant: string;
440
+ creditUsageRenewsOn: string;
441
+ usageByUserHeader: string;
442
+ usageByUserTotal: string;
443
+ usageByUserError: string;
444
+ usageByUserUnattributed: string;
445
+ usageByUserMore: string;
446
+ usageByUserShowTop: string;
447
+ usageByUserShowAllCount: string;
448
+ usageByUserShowAll: string;
449
+ usageByUserShowFewer: string;
260
450
  usageUnits: string;
261
451
  usagePerUnit: string;
262
452
  usagePerPackage: string;
@@ -302,7 +492,7 @@ export declare type EntitlementText =
302
492
  | {
303
493
  kind: "perPackage";
304
494
  cost: string;
305
- size: number;
495
+ size: string;
306
496
  units: string;
307
497
  }
308
498
  /** "Up to 1,000 API calls in this tier". */
@@ -439,7 +629,7 @@ export declare interface IncludedFeatureRow {
439
629
  * the element shows it only when the host asks.
440
630
  */
441
631
  hardLimit: {
442
- amount: number;
632
+ amount: string;
443
633
  units: string;
444
634
  } | null;
445
635
  /** The price's tiers, for a tier-priced row or tiered pay-in-advance. */
@@ -583,8 +773,190 @@ export declare function isTieredPrice(price: MeteredPrice | undefined): boolean;
583
773
  */
584
774
  export declare function lookup(catalog: StringCatalog | undefined, key: string, vars?: StringVars, locale?: string): string | undefined;
585
775
 
776
+ export declare interface MeteredFeatureRow {
777
+ featureId: string;
778
+ name: string;
779
+ description: string | null;
780
+ /** A schematic-icons glyph name; `null` when the feature has none. */
781
+ icon: string | null;
782
+ headline: MeteredHeadline | null;
783
+ limit: MeteredLimit | null;
784
+ /** "Resets Oct 1". */
785
+ resetsAt: string | null;
786
+ hardLimit: {
787
+ amount: string;
788
+ units: string;
789
+ } | null;
790
+ meter: MeteredMeter | null;
791
+ priceDetails: MeteredPriceDetails | null;
792
+ /** Paid in advance, so more can be bought. */
793
+ canAddMore: boolean;
794
+ /** Event-based, so its usage breaks down by user. */
795
+ hasUsageByUser: boolean;
796
+ /** The feature's names, for a host labelling amounts itself. */
797
+ unit: {
798
+ name: string;
799
+ singularName?: string;
800
+ pluralName?: string;
801
+ };
802
+ source: FeatureUsage;
803
+ }
804
+
805
+ /**
806
+ * A card per event- or trait-based feature: usage against its limit, what it
807
+ * costs, and who on the team used it.
808
+ *
809
+ * A company with no metered features renders nothing. A 404 means the
810
+ * account is not enabled for company reads, and the element says so.
811
+ */
812
+ export declare function MeteredFeatures({ addMoreTarget, addMoreUrl, className, headingLevel, locale: localeProp, onAddMore, showAllocation, showCredits, showDescription, showHardLimit, showHeader, showIcon, showMeter, showUsage, showUsageByUser, showWarningThresholdAsLimit, strings, visibleFeatures, }: MeteredFeaturesProps): JSX.Element | null;
813
+
814
+ export declare namespace MeteredFeatures {
815
+ var resources: readonly ["featureUsage"];
816
+ }
817
+
818
+ export declare interface MeteredFeaturesProps extends ElementProps {
819
+ /** The "Usage" heading above the cards. Default false, as in the embed. */
820
+ showHeader?: boolean;
821
+ /**
822
+ * Heading level. Feature names sit one level below it, or take it when the
823
+ * heading is hidden. Default 2.
824
+ */
825
+ headingLevel?: HeadingLevel;
826
+ /** Each feature's icon. Default true. */
827
+ showIcon?: boolean;
828
+ /** Each feature's description. Default true. */
829
+ showDescription?: boolean;
830
+ /** The headline: what is used, or the quantity paid for. Default true. */
831
+ showUsage?: boolean;
832
+ /** The limit line beneath it, and when usage resets. Default true. */
833
+ showAllocation?: boolean;
834
+ /** The usage meter. Default true. */
835
+ showMeter?: boolean;
836
+ /** The breakdown of usage by user, for event-based features. Default true. */
837
+ showUsageByUser?: boolean;
838
+ /** Feature ids to show, in this order; every metered feature when absent. */
839
+ visibleFeatures?: string[];
840
+ /** The "credits per use" line on credit-burning features. Default true. */
841
+ showCredits?: boolean;
842
+ /** An info tip with the hard limit on features billed past it. Default false. */
843
+ showHardLimit?: boolean;
844
+ /**
845
+ * Show an entitlement's warning threshold in place of its limit, where one
846
+ * is configured. Default false.
847
+ */
848
+ showWarningThresholdAsLimit?: boolean;
849
+ /**
850
+ * Called by "Add More" on a feature paid for in advance. With neither this
851
+ * nor `addMoreUrl`, there is no button.
852
+ */
853
+ onAddMore?: (feature: FeatureUsage) => void;
854
+ /** "Add More" links here when there is no `onAddMore`. */
855
+ addMoreUrl?: string;
856
+ /** `target` for `addMoreUrl`. */
857
+ addMoreTarget?: string;
858
+ }
859
+
860
+ /**
861
+ * `deriveMeteredFeatures`: each event- or trait-based feature as its card
862
+ * shows it. The wording is the element's, keyed by `kind`; numbers, names and
863
+ * dates are formatted here.
864
+ */
865
+ /** What is used, or, for a feature paid in advance, what was bought. */
866
+ export declare type MeteredHeadline =
867
+ /** "12 Seats" — a quantity paid for in advance. */
868
+ {
869
+ kind: "quantity";
870
+ amount: string | null;
871
+ units: string;
872
+ }
873
+ /** "1,300 API calls" + "used". */
874
+ | {
875
+ kind: "used";
876
+ amount: string;
877
+ units: string;
878
+ };
879
+
880
+ /** The line under the headline, before "Resets …". */
881
+ export declare type MeteredLimit = {
882
+ kind: "tierUpTo";
883
+ amount: string;
884
+ feature: string;
885
+ } | {
886
+ kind: "tierUnlimited";
887
+ feature: string;
888
+ }
889
+ /** "1,000 included" — an overage's soft limit. */
890
+ | {
891
+ kind: "included";
892
+ amount: string;
893
+ }
894
+ /** "9 used" — how much of a quantity paid for in advance is in use. */
895
+ | {
896
+ kind: "used";
897
+ amount: string;
898
+ }
899
+ /** What pay-as-you-go usage has cost. */
900
+ | {
901
+ kind: "cost";
902
+ cost: string;
903
+ } | {
904
+ kind: "perUse";
905
+ amount: string;
906
+ units: string;
907
+ } | {
908
+ kind: "limitOf";
909
+ amount: string;
910
+ } | {
911
+ kind: "noLimit";
912
+ };
913
+
914
+ export declare interface MeteredMeter {
915
+ value: number;
916
+ total: number;
917
+ /** 0–100. Past an overage's soft limit, the included share of all usage. */
918
+ percent: number;
919
+ tone: MeterTone;
920
+ /** Up to ten fraction digits, as is `totalText`. */
921
+ valueText: string;
922
+ totalText: string;
923
+ }
924
+
586
925
  export { MeteredPrice }
587
926
 
927
+ export declare type MeteredPriceDetails = {
928
+ kind: "overage";
929
+ /** The per-unit price past the soft limit. */
930
+ unitPrice: string;
931
+ /** "100" for a package price; `null` for a price per unit. */
932
+ packageSize: string | null;
933
+ units: string;
934
+ /** A period key, for a trait billed per period. */
935
+ period: string | null;
936
+ /** Usage past the soft limit, and what it costs. */
937
+ overage: {
938
+ amount: string;
939
+ units: string;
940
+ cost: string;
941
+ };
942
+ } | {
943
+ kind: "tier";
944
+ from: string;
945
+ /** `null` for the last, unbounded tier. */
946
+ to: string | null;
947
+ /** What the usage costs across the tiers; `null` when nothing does. */
948
+ cost: string | null;
949
+ period: string | null;
950
+ tiers: {
951
+ ranges: TierRange[];
952
+ currency: string;
953
+ mode: "graduated" | "volume" | null;
954
+ };
955
+ };
956
+
957
+ /** The fill's colour: by price for tiers and overages, else by share used. */
958
+ export declare type MeterTone = "tier" | "overage" | "ok" | "warning" | "critical";
959
+
588
960
  export { PaymentMethod }
589
961
 
590
962
  /**
@@ -721,8 +1093,7 @@ export declare interface PaymentMethodsProps extends ElementProps {
721
1093
  export { PerLicenseCreditGrant }
722
1094
 
723
1095
  export declare interface PerLicenseCredits {
724
- /** Credits per license unit, as the API sends it. */
725
- amount: number;
1096
+ amount: string;
726
1097
  creditName: string;
727
1098
  licenseName: string;
728
1099
  }
@@ -953,12 +1324,13 @@ export declare type UsageSegment =
953
1324
  {
954
1325
  kind: "unitPricePerPeriod";
955
1326
  cost: string;
956
- size: number;
1327
+ /** "100" for a package price; `null` for a price per unit. */
1328
+ size: string | null;
957
1329
  units: string;
958
1330
  /** A period key: "month", "quarter" or "year". */
959
1331
  period: string;
960
1332
  }
961
- /** "1300 API calls used"; the amount is left as the API sends it. */
1333
+ /** "1,300 API calls used". */
962
1334
  | {
963
1335
  kind: "used";
964
1336
  amount: string;
@@ -986,6 +1358,10 @@ export declare type UsageSummary = {
986
1358
  amount: string;
987
1359
  };
988
1360
 
1361
+ export { useCreditBalances }
1362
+
1363
+ export { useCreditUserUsage }
1364
+
989
1365
  export { useFeatureUsage }
990
1366
 
991
1367
  export { useFeatureUserUsage }