@schematichq/schematic-react 1.5.0 → 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:
@@ -200,7 +229,22 @@ The hook returns an object with the following properties:
 | `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: `useSchematicEntitlement(key)` returns `creditId` for credit-based features.
+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
 
@@ -260,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