@schematichq/schematic-components 2.27.1 → 2.29.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.
package/README.md CHANGED
@@ -93,6 +93,97 @@ notice that appears in the same spot.
93
93
  The Plans and add-ons available to the checkout flows must be live in your
94
94
  Schematic account [Catalog configuration](https://docs.schematichq.com/catalog/overview).
95
95
 
96
+ To offer an add-on that isn't live, see
97
+ [Rehydrating With Params](#rehydrating-with-params).
98
+
99
+ ## Rehydrating With Params
100
+
101
+ We provide a function `rehydrateWithParams` for re-fetching the embed's data
102
+ with params the standard load doesn't send. Like `initializeWithPlan`, it's
103
+ suitable for click handlers and must be extracted from the library's embedded
104
+ context.
105
+
106
+ ```ts
107
+ const { rehydrateWithParams } = useEmbed();
108
+
109
+ const data = await rehydrateWithParams({ includeAddOnIds: ['plan_BQx8kWjSx4'] });
110
+ ```
111
+
112
+ It re-fetches the component your `SchematicEmbed` loaded and applies the
113
+ result in place:
114
+
115
+ - The embed's data updates without the embed showing its loading state.
116
+ - It isn't debounced: every call makes a request, and the promise resolves
117
+ with the new data once it's applied.
118
+ - The promise rejects if the request fails, leaving the embed's data and
119
+ error state as they were, so your UI decides how to handle it. It also
120
+ rejects if no `SchematicEmbed` has loaded yet.
121
+ - The params apply to this fetch only. The embed's next refresh, such as the
122
+ one after a purchase, goes back to the standard load.
123
+
124
+ Await it before anything that depends on the new data, such as opening a
125
+ checkout with `initializeWithPlan`.
126
+
127
+ ### Params
128
+
129
+ | Param | Type | Effect |
130
+ | ----------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
131
+ | `includeAddOnIds` | `string[]` | Add-ons to offer in the checkout even though they aren't live. Each must be an add-on with a billing product; any other ID is left out, with a console warning. |
132
+
133
+ ### Example: selling an add-on that isn't live
134
+
135
+ Say your backend creates an add-on for a single purchase, such as a one-off
136
+ service, and deletes it afterward, so it's never live in your catalog. A "Buy
137
+ now" button can create it, include it, and open the checkout with it
138
+ selected:
139
+
140
+ ```tsx
141
+ import { useState } from 'react';
142
+ import { useEmbed } from '@schematichq/schematic-components';
143
+
144
+ function BuyServiceButton({ serviceId }: { serviceId: string }) {
145
+ const { rehydrateWithParams, initializeWithPlan } = useEmbed();
146
+ const [isLoading, setIsLoading] = useState(false);
147
+ const [error, setError] = useState<string>();
148
+
149
+ const handleClick = async () => {
150
+ setIsLoading(true);
151
+ setError(undefined);
152
+
153
+ try {
154
+ // Your backend creates the add-on and returns its Schematic ID
155
+ const { addOnId } = await createServiceAddOn(serviceId);
156
+
157
+ // Fetch the embed's data again, this time with the add-on in it
158
+ await rehydrateWithParams({ includeAddOnIds: [addOnId] });
159
+
160
+ // Open the checkout. Including an add-on only makes it available;
161
+ // list it in `addOnIds` to pre-select it.
162
+ initializeWithPlan({
163
+ addOnIds: [addOnId],
164
+ skipped: { addOnStage: true }, // it's already chosen
165
+ });
166
+ } catch {
167
+ setError("We couldn't start the checkout. Please try again.");
168
+ } finally {
169
+ setIsLoading(false);
170
+ }
171
+ };
172
+
173
+ return (
174
+ <>
175
+ <button onClick={handleClick} disabled={isLoading}>
176
+ {isLoading ? 'Preparing checkout…' : 'Buy now'}
177
+ </button>
178
+ {error && <p role="alert">{error}</p>}
179
+ </>
180
+ );
181
+ }
182
+ ```
183
+
184
+ The add-on still has to be compatible with the selected plan and priced in
185
+ the checkout's currency and billing period to appear.
186
+
96
187
  ## Programmatic Unsubscribe
97
188
 
98
189
  We provide a function `requestUnsubscribe` for starting the unsubscribe flow
@@ -175,7 +266,9 @@ reach it, so `{{amount}}` reads `20,000` or `20.000` on its own. A plural's
175
266
  the bundle formats it with `{{count, number}}`.
176
267
 
177
268
  Feature names and their plural forms come from your Schematic account, not the
178
- bundle, so set them there in the language you need.
269
+ bundle, so set them there in the language you need. In a language other than
270
+ English, a name with no plural form set is shown as entered for every count,
271
+ rather than with an English plural ending added.
179
272
 
180
273
  ## License
181
274