@schematichq/schematic-react 1.5.0 → 1.7.0

package/README.md

@@ -136,6 +136,69 @@ 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.
+
+### Usage warnings
+
+If a usage warning is configured on the entitlement, the hook returns it as `warningTiers`, so you can warn a customer before they hit the limit rather than after:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `warningTiers` | `WarningTier[] \| undefined` | The usage warning thresholds configured on the entitlement, each a `{ key, value }` pair in the entitlement's usage units. `undefined` when none are configured |
+| `softLimit` | `number \| undefined` | For usage-based pricing, the soft limit for overage charges or the next tier boundary |
+
+The dashboard writes a single tier under the key `default`.
+
+```tsx
+import { useSchematicEntitlement } from "@schematichq/schematic-react";
+import { Feature, ApproachingLimit } from "./components";
+
+const MyComponent = () => {
+    const { featureUsage, warningTiers } =
+        useSchematicEntitlement("my-flag-key");
+
+    const warning = warningTiers?.find((tier) => tier.key === "default");
+    const approachingLimit =
+        typeof featureUsage === "number" &&
+        typeof warning?.value === "number" &&
+        featureUsage >= warning.value;
+
+    return (
+        <>
+            {approachingLimit && <ApproachingLimit limit={warning.value} />}
+            <Feature />
+        </>
+    );
+};
+```
+
 ### Company plan information
 
 To access the current company's plan and trial status, you can use the `useSchematicPlan` hook:
@@ -200,7 +263,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 +338,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