docs: document useSchematicCreditBalance for React, Vue, and Angular

fern/docs/pages/developer_resources/sdks/angular.mdx

@@ -233,6 +233,46 @@ export class PlanComponent {
 }
 ```
 
+### Credit balances
+
+Use `creditBalance$` to observe a company's credit balance. It is keyed by credit ID and emits as the balance changes over the DataStream, so the number stays accurate while leases open and close:
+
+```typescript
+import { Component, inject } from "@angular/core";
+import { AsyncPipe } from "@angular/common";
+import { SchematicService } from "@schematichq/schematic-angular";
+
+@Component({
+  selector: "app-credit-meter",
+  standalone: true,
+  imports: [AsyncPipe],
+  template: `
+    @if (creditBalance$ | async; as credit) {
+      @if (credit.isLoading) {
+        <div>Loading…</div>
+      } @else {
+        <div>{{ credit.balance }} credits remaining</div>
+      }
+    }
+  `,
+})
+export class CreditMeterComponent {
+  private schematic = inject(SchematicService);
+  creditBalance$ = this.schematic.creditBalance$("credit-id");
+}
+```
+
+`creditBalance$` emits 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 |
+
+By default it surfaces the `settled` balance, which is the spendable number you should show end users. For advanced lease-aware accounting, pass a second argument (`"remaining"` or `"reserved"`) to surface those values instead. The credit ID is available on a feature's entitlement: `entitlement$(key)` emits `creditId` for credit-based features.
+
+*Note: `creditBalance$` requires `@schematichq/schematic-angular` 1.5.0 or later.*
+
 ## API Reference
 
 ### `provideSchematic(config)`
@@ -252,6 +292,7 @@ Injectable service providing all Schematic functionality:
 | `flagValue$(key, fallback?)` | `Observable<boolean>` | Observe a feature flag's boolean value |
 | `entitlement$(key, fallback?)` | `Observable<CheckFlagReturn>` | Observe detailed entitlement data |
 | `plan$()` | `Observable<CheckPlanReturn \| undefined>` | Observe plan information |
+| `creditBalance$(creditId, type?)` | `Observable<SchematicCreditBalance>` | Observe a company's lease-aware credit balance |
 | `isPending$()` | `Observable<boolean>` | Observe loading state |
 
 ### `SCHEMATIC_CLIENT`

fern/docs/pages/developer_resources/sdks/react.mdx

@@ -179,6 +179,41 @@ 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, so the number stays accurate while leases open and close:
+
+```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 |
+
+By default the hook surfaces the `settled` balance, which is the spendable number you should show end users. For advanced lease-aware accounting, pass `opts.type` as `"remaining"` or `"reserved"` to surface those values instead:
+
+```tsx
+const { balance } = useSchematicCreditBalance("credit-id", { type: "reserved" });
+```
+
+The credit ID is available on a feature's entitlement: `useSchematicEntitlement(key)` returns `creditId` for credit-based features.
+
+*Note: `useSchematicCreditBalance` requires `@schematichq/schematic-react` 1.5.0 or later.*
+
 ## 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).

fern/docs/pages/developer_resources/sdks/vue.mdx

@@ -177,6 +177,40 @@ 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, so the number stays accurate while leases open and close:
+
+```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 |
+
+By default the composable surfaces the `settled` balance, which is the spendable number you should show end users. For advanced lease-aware accounting, pass `opts.type` as `"remaining"` or `"reserved"` to surface those values instead:
+
+```ts
+const { balance } = useSchematicCreditBalance("credit-id", { type: "reserved" });
+```
+
+The credit ID is available on a feature's entitlement: `useSchematicEntitlement(key)` returns `creditId` for credit-based features.
+
+*Note: `useSchematicCreditBalance` requires `@schematichq/schematic-vue` 1.5.0 or later.*
+
 ## 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).