@schematichq/schematic-react 1.4.1 → 1.6.0

package/README.md

@@ -136,6 +136,35 @@ const MyComponent = () => {
 
 *Note: `useSchematicIsPending` is checking if entitlement data has been loaded, typically via `identify`. It should, therefore, be used to wrap flag and entitlement checks, but never the initial call to `identify`.*
 
+For features metered by credit burndown, the same entitlement object carries the company's credit position:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `creditId` | `string \| undefined` | The ID of the credit funding this feature |
+| `creditSettled` | `number \| undefined` | The spendable balance, including any amount held by an open lease. This is the number to show end users |
+| `creditRemaining` | `number \| undefined` | The balance available to fund new consumption, excluding any open lease hold |
+| `creditReserved` | `number \| undefined` | The unspent amount held by an open credit lease, `0` when none is open |
+
+All four are `undefined` when the feature is not credit-based.
+
+```tsx
+import { useSchematicEntitlement } from "@schematichq/schematic-react";
+import { Feature, OutOfCredits } from "./components";
+
+const MyComponent = () => {
+    const { creditSettled, value: isFeatureEnabled } =
+        useSchematicEntitlement("my-flag-key");
+
+    if (!isFeatureEnabled) {
+        return <OutOfCredits />;
+    }
+
+    return <Feature creditsRemaining={creditSettled} />;
+};
+```
+
+These values refresh with each flag check. For a balance that also updates on the credit partials arriving between checks, pass `creditId` to [`useSchematicCreditBalance`](#credit-balances) instead.
+
 ### Company plan information
 
 To access the current company's plan and trial status, you can use the `useSchematicPlan` hook:
@@ -175,6 +204,48 @@ The hook returns an object with the following properties:
 | `trialEndDate` | `Date \| undefined` | The trial end date, if the company has or had a trial |
 | `trialStatus` | `"active" \| "expired" \| "converted" \| undefined` | The company's trial status: `active` if the trial is ongoing, `expired` if the trial ended without conversion, `converted` if the company converted to a paid plan, or `undefined` if the company has never trialed |
 
+### Credit balances
+
+To display a company's credit balance, use the `useSchematicCreditBalance` hook. It is keyed by credit ID and updates reactively as the balance changes over the DataStream:
+
+```tsx
+import { useSchematicCreditBalance } from "@schematichq/schematic-react";
+
+const CreditMeter = () => {
+    const { balance, isLoading } = useSchematicCreditBalance("credit-id");
+
+    if (isLoading) {
+        return <div>Loading…</div>;
+    }
+
+    return <div>{balance} credits remaining</div>;
+};
+```
+
+The hook returns an object with the following properties:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `balance` | `number` | The spendable balance, or `0` while loading or when the company holds no balance in this credit |
+| `isLoading` | `boolean` | `true` while the balance is still loading and no value has arrived yet |
+
+The credit ID is available on a feature's entitlement, and the hook accepts `string | undefined`, so you can feed it straight through without waiting for the check to arrive:
+
+```tsx
+const CreditMeter = () => {
+    const { creditId } = useSchematicEntitlement("my-flag-key");
+    const { balance, isLoading } = useSchematicCreditBalance(creditId);
+
+    if (isLoading) {
+        return <div>Loading…</div>;
+    }
+
+    return <div>{balance} credits remaining</div>;
+};
+```
+
+While `creditId` is `undefined`, the hook reports the client's loading state and a balance of `0`.
+
 ## Fallback Behavior
 
 The SDK includes built-in fallback behavior you can use to ensure your application continues to function even when unable to reach Schematic (e.g., during service disruptions or network issues).
@@ -233,7 +304,7 @@ When events (track, identify) cannot be sent due to network issues, they are aut
 
 ### WebSocket Fallback
 
-In WebSocket mode, if the WebSocket connection fails, the SDK will provide the last known value or the configured fallback values as [outlined above](/#flag-check-fallbacks). The WebSocket will also automatically attempt to re-establish it's connection with Schematic using an exponential backoff. 
+In WebSocket mode, if the WebSocket connection fails, the SDK will provide the last known value or the configured fallback values as [outlined above](#flag-check-fallbacks). The WebSocket will also automatically attempt to re-establish its connection with Schematic using an exponential backoff. 
 
 ## React Native