@schematichq/schematic-vue 1.5.0 → 1.7.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:
@@ -197,7 +259,61 @@ The composable returns an object with the following reactive properties:
 | `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: `useSchematicEntitlement(key)` returns `creditId` for credit-based features.
+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`.
+
+### Credit spend policies
+
+To show the spend limits that bind the current company and user, use the `useSchematicCreditSpendPolicies` composable. It updates over the DataStream, so a policy edited or deleted in the dashboard reaches the component without a refetch:
+
+```vue
+<script setup lang="ts">
+import { useSchematicCreditSpendPolicies } from "@schematichq/schematic-vue";
+
+const { policies, isLoading } = useSchematicCreditSpendPolicies();
+</script>
+
+<template>
+  <div v-if="isLoading">Loading…</div>
+  <ul v-else>
+    <li v-for="policy in policies" :key="policy.id">
+      <template v-if="policy.kind === 'window' && policy.window">
+        {{ policy.scope }} limit: {{ policy.consumed }} of {{ policy.limit }} credits used this {{ policy.window.unit }}
+      </template>
+      <template v-else>
+        {{ policy.scope }} limit: {{ policy.limit }} credits per request
+      </template>
+    </li>
+  </ul>
+</template>
+```
+
+The composable returns an object with the following reactive properties:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `policies` | `ComputedRef<CreditSpendPolicies>` | Company-scope policies first, then the user's own; empty when none bind |
+| `isLoading` | `ComputedRef<boolean>` | `true` while the policies are still loading and nothing has arrived yet |
+
+A `per_draw` policy caps a single draw. A `window` policy caps what can be spent in one period: `consumed` is what the current period has spent, `resetsAt` is when the period ends, and `window` names the period. Each new spend sends an updated `consumed`. Once `resetsAt` has passed, read `consumed` as `0` until the next update arrives.
 
 ## Fallback Behavior
 
@@ -259,7 +375,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