@schematichq/schematic-vue 1.4.1 → 1.6.0

package/README.md

@@ -137,6 +137,68 @@ const {
 
 _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 composable exposes the company's credit position:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `creditId` | `ComputedRef<string \| undefined>` | The ID of the credit funding this feature |
+| `creditSettled` | `ComputedRef<number \| undefined>` | The spendable balance, including any amount held by an open lease. This is the number to show end users |
+| `creditRemaining` | `ComputedRef<number \| undefined>` | The balance available to fund new consumption, excluding any open lease hold |
+| `creditReserved` | `ComputedRef<number \| undefined>` | The unspent amount held by an open credit lease, `0` when none is open |
+
+All four unwrap to `undefined` when the feature is not credit-based.
+
+```vue
+<script setup lang="ts">
+import { useSchematicEntitlement } from "@schematichq/schematic-vue";
+
+const { creditSettled, value: isFeatureEnabled } =
+  useSchematicEntitlement("my-flag-key");
+</script>
+
+<template>
+  <OutOfCredits v-if="!isFeatureEnabled" />
+  <Feature v-else :credits-remaining="creditSettled" />
+</template>
+```
+
+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 composable exposes it as `warningTiers`, so you can warn a customer before they hit the limit rather than after:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `warningTiers` | `ComputedRef<WarningTier[] \| undefined>` | The usage warning thresholds configured on the entitlement, each a `{ key, value }` pair in the entitlement's usage units. Unwraps to `undefined` when none are configured |
+| `softLimit` | `ComputedRef<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`.
+
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+import { useSchematicEntitlement } from "@schematichq/schematic-vue";
+
+const { featureUsage, warningTiers } = useSchematicEntitlement("my-flag-key");
+
+const warning = computed(() =>
+  warningTiers.value?.find((tier) => tier.key === "default"),
+);
+const approachingLimit = computed(
+  () =>
+    typeof featureUsage.value === "number" &&
+    typeof warning.value?.value === "number" &&
+    featureUsage.value >= warning.value.value,
+);
+</script>
+
+<template>
+  <ApproachingLimit v-if="approachingLimit" :limit="warning!.value" />
+  <Feature />
+</template>
+```
+
 ### Company plan information
 
 To access the current company's plan and trial status, you can use the `useSchematicPlan` composable:
@@ -173,6 +235,51 @@ The composable 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` composable. It is keyed by credit ID and updates reactively as the balance changes over the DataStream:
+
+```vue
+<script setup lang="ts">
+import { useSchematicCreditBalance } from "@schematichq/schematic-vue";
+
+const { balance, isLoading } = useSchematicCreditBalance("credit-id");
+</script>
+
+<template>
+  <div v-if="isLoading">Loading…</div>
+  <div v-else>{{ balance }} credits remaining</div>
+</template>
+```
+
+The composable returns an object with the following reactive properties:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `balance` | `ComputedRef<number>` | The spendable balance, or `0` while loading or when the company holds no balance in this credit |
+| `isLoading` | `ComputedRef<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 composable accepts a ref or a getter as well as a plain string, so you can feed one straight through:
+
+```vue
+<script setup lang="ts">
+import {
+  useSchematicCreditBalance,
+  useSchematicEntitlement,
+} from "@schematichq/schematic-vue";
+
+const { creditId } = useSchematicEntitlement("my-flag-key");
+const { balance, isLoading } = useSchematicCreditBalance(creditId);
+</script>
+
+<template>
+  <div v-if="isLoading">Loading…</div>
+  <div v-else>{{ balance }} credits remaining</div>
+</template>
+```
+
+The composable re-keys to the new credit whenever the source resolves to a different ID. While it resolves to `undefined`, it 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 +340,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. 
 
 ## Options API Support