release: 0.13.2

Add balances.check to the Autumn emulator, matching the autumn-js SDK's
POST /v1/balances.check wire shape. Access is computed from the same plan
item and tracked usage state that drives customer balances, the response
carries the full balance object the SDK validates, and the route
participates in fault injection and the request ledger.

Author: RhysSullivan

CHANGELOG.md

@@ -1,15 +1,21 @@
 # Changelog
 
-## 0.13.1
+## 0.13.2
 
 <!-- release:start -->
 
-### Fixes
+### New Features
 
-- **Seeded drive items land on the seed's own user** — `drive_items` (and other resources) that omit `user_email` now attach to the first user declared in the seed config instead of the plugin's built-in default user, so a token minted for the seeded user sees the seeded files (and their `content`) under `/me/drive`.
+- **Autumn `balances.check`** — the Autumn emulator now supports the SDK's `check()` call (`POST /v1/balances.check`). Access is computed from the same plan items and tracked usage that drive customer balances: unlimited and overage-allowed features always pass, metered features pass while remaining balance covers `required_balance` (default 1), and a feature the customer's plan does not carry is allowed with a `null` balance. The response carries the full balance object (`granted`, `remaining`, `usage`, `unlimited`, `overage_allowed`) in the shape autumn-js validates, and the route participates in fault injection and the request ledger like every other operation.
 
 <!-- release:end -->
 
+## 0.13.1
+
+### Fixes
+
+- **Seeded drive items land on the seed's own user** — `drive_items` (and other resources) that omit `user_email` now attach to the first user declared in the seed config instead of the plugin's built-in default user, so a token minted for the seeded user sees the seeded files (and their `content`) under `/me/drive`.
+
 ## 0.13.0
 
 ### New Features

packages/@emulators/adapter-next/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulators/adapter-next",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",

packages/@emulators/apple/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulators/apple",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",

packages/@emulators/autumn/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulators/autumn",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",

packages/@emulators/autumn/src/__tests__/autumn.test.ts

@@ -21,8 +21,14 @@ beforeAll(() => {
     fallbackUser: { login: "am_emulate_admin", id: 1, scopes: [] },
   });
   seedFromConfig(store, BASE, {
-    plans: [{ id: "pro", name: "Pro", items: [{ feature_id: "executions", included: 1000 }] }],
-    customers: [{ id: "org_paid", subscriptions: [{ plan_id: "pro", status: "active" }] }],
+    plans: [
+      { id: "pro", name: "Pro", items: [{ feature_id: "executions", included: 1000 }] },
+      { id: "starter", name: "Starter", items: [{ feature_id: "executions", included: 2 }] },
+    ],
+    customers: [
+      { id: "org_paid", subscriptions: [{ plan_id: "pro", status: "active" }] },
+      { id: "org_capped", subscriptions: [{ plan_id: "starter", status: "active" }] },
+    ],
   });
   httpServer = serve({ fetch: app.fetch, port: PORT });
   autumn = new Autumn({ secretKey: "am_test_emulate", serverURL: BASE });
@@ -48,6 +54,61 @@ describe("autumn emulator with the real autumn-js SDK", () => {
     await autumn.track({ customerId: "org_fresh", featureId: "executions", value: 1 });
   });
 
+  it("check allows a feature with remaining balance", async () => {
+    const check = await autumn.check({ customerId: "org_paid", featureId: "executions" });
+    expect(check.allowed).toBe(true);
+    expect(check.customerId).toBe("org_paid");
+    expect(check.balance?.remaining).toBe(1000);
+    expect(check.balance?.unlimited).toBe(false);
+  });
+
+  it("check denies an exhausted feature with no overage", async () => {
+    // starter includes 2 executions; burn them both through balances.track.
+    await autumn.track({ customerId: "org_capped", featureId: "executions", value: 2 });
+    const check = await autumn.check({ customerId: "org_capped", featureId: "executions" });
+    expect(check.allowed).toBe(false);
+    expect(check.balance?.remaining).toBe(0);
+    expect(check.balance?.usage).toBe(2);
+    expect(check.balance?.overageAllowed).toBe(false);
+  });
+
+  it("check allows a feature the customer's plan does not carry", async () => {
+    const check = await autumn.check({ customerId: "org_paid", featureId: "not-a-feature" });
+    expect(check.allowed).toBe(true);
+    expect(check.balance).toBeNull();
+  });
+
+  it("an armed fault on balances.check returns the injected 500 and marks the ledger entry", async () => {
+    const armRes = await fetch(`${BASE}/_emulate/faults`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        match: { operationId: "balances.check" },
+        response: { status: 500, body: { message: "injected failure" } },
+      }),
+    });
+    expect(armRes.status).toBe(200);
+    const { fault } = (await armRes.json()) as { fault: { id: string } };
+
+    const faulted = await fetch(`${BASE}/v1/balances.check`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: "Bearer am_test_emulate" },
+      body: JSON.stringify({ customer_id: "org_paid", feature_id: "executions" }),
+    });
+    expect(faulted.status).toBe(500);
+    expect(await faulted.json()).toEqual({ message: "injected failure" });
+
+    const ledger = (await (await fetch(`${BASE}/_emulate/ledger`)).json()) as {
+      entries: Array<{ path: string; faulted?: boolean; faultId?: string; response: { status: number } }>;
+    };
+    const entry = ledger.entries.find((e) => e.path === "/v1/balances.check" && e.faulted);
+    expect(entry).toMatchObject({ faulted: true, faultId: fault.id, response: { status: 500 } });
+
+    // The fault was one-shot; the next check goes through normally.
+    const check = await autumn.check({ customerId: "org_paid", featureId: "executions" });
+    expect(check.allowed).toBe(true);
+  });
+
   // Regression for the autumn-js 0.9.0 emulator regression: autumn-js 1.2.8's
   // `useCustomer` hook drives its backend route, which always calls
   // `customers.getOrCreate` with `expand: ["balances.feature"]` (see

packages/@emulators/autumn/src/manifest.ts

@@ -4,7 +4,7 @@ export const manifest: ServiceManifest = {
   id: "autumn",
   name: "Autumn",
   description:
-    "Stateful Autumn billing emulator: customers (with seedable subscriptions and a plan catalog), usage tracking, plan eligibility, and a hosted checkout flow for paid plans and card-required free trials.",
+    "Stateful Autumn billing emulator: customers (with seedable subscriptions and a plan catalog), usage tracking, feature access checks, plan eligibility, and a hosted checkout flow for paid plans and card-required free trials.",
   docsUrl: "https://docs.emulators.dev/autumn",
   surfaces: [
     { id: "rest", kind: "rest", title: "Autumn v1 API", status: "partial", basePath: "/v1" },
@@ -27,6 +27,7 @@ export const manifest: ServiceManifest = {
         { operationId: "customers.list", method: "POST", path: "/v1/customers.list", status: "hand-authored" },
         { operationId: "customers.update", method: "POST", path: "/v1/customers.update", status: "hand-authored" },
         { operationId: "balances.track", method: "POST", path: "/v1/balances.track", status: "hand-authored" },
+        { operationId: "balances.check", method: "POST", path: "/v1/balances.check", status: "hand-authored" },
         { operationId: "plans.list", method: "POST", path: "/v1/plans.list", status: "hand-authored" },
         { operationId: "billing.attach", method: "POST", path: "/v1/billing.attach", status: "hand-authored" },
         {

packages/@emulators/autumn/src/routes/api.ts

@@ -1,7 +1,13 @@
 import type { RouteContext } from "@emulators/core";
 
 import { getAutumnStore } from "../store.js";
-import { ensureCustomer, serializeCustomer, serializePlan, activateSubscription } from "../serialize.js";
+import {
+  ensureCustomer,
+  serializeCustomer,
+  serializePlan,
+  activateSubscription,
+  balanceForFeature,
+} from "../serialize.js";
 
 /** Autumn v1 RPC-style API (paths mirror autumn-js: /v1/<group>.<method>). */
 export function autumnApiRoutes(ctx: RouteContext): void {
@@ -57,6 +63,43 @@ export function autumnApiRoutes(ctx: RouteContext): void {
     });
   });
 
+  // Feature access check, shaped after autumn-js's CheckResponse schema
+  // (allowed, customer_id, entity_id, required_balance, balance, flag).
+  // `allowed` is computed from the same balance state customers.get_or_create
+  // serializes: unlimited features and overage-allowed features always pass,
+  // metered features pass while `remaining` covers the required balance.
+  // A feature the customer's plan does not carry gets a permissive
+  // `allowed: true` with a null balance. The SDK types leave this case
+  // ambiguous (CheckResponse.balance is nullable either way), so the emulator
+  // deliberately fails open: an unseeded feature should not block every
+  // request in the application under test. Seed a plan item with included: 0
+  // to model a feature that denies access.
+  app.post("/v1/balances.check", async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as Record<string, unknown>;
+    const customerId = String(body.customer_id ?? body.customerId ?? "");
+    const featureId = String(body.feature_id ?? body.featureId ?? "");
+    if (!customerId || !featureId) {
+      return c.json({ message: "customer_id and feature_id are required", code: "invalid_request" }, 400);
+    }
+    const requiredBalance = typeof body.required_balance === "number" ? body.required_balance : 1;
+    const entityId = typeof body.entity_id === "string" ? body.entity_id : null;
+    const store = as();
+    // Real Autumn auto-creates unknown customers on check (the SDK's own
+    // backend flow relies on get_or_create semantics), so mirror that here.
+    const customer = ensureCustomer(store, customerId, body);
+    const balance = balanceForFeature(store, customer, featureId);
+    const allowed =
+      balance === undefined || balance.unlimited || balance.overage_allowed || balance.remaining >= requiredBalance;
+    return c.json({
+      allowed,
+      customer_id: customerId,
+      entity_id: entityId,
+      required_balance: requiredBalance,
+      balance: balance ?? null,
+      flag: null,
+    });
+  });
+
   // The plan catalog, scoped to the calling customer. The backend handler
   // injects `customer_id` into every request, so eligibility is per-customer:
   // a card-required trial reads as "Start free trial" until it is attached.

packages/@emulators/autumn/src/routes/openapi.ts

@@ -107,6 +107,23 @@ function buildSpec(baseUrl: string): Record<string, unknown> {
           responses: { "200": ok("Event confirmation."), "400": ok("Validation error.") },
         },
       },
+      "/v1/balances.check": {
+        post: {
+          operationId: "balances.check",
+          tags: ["balances"],
+          summary: "Check feature access for a customer",
+          requestBody: jsonBody(
+            {
+              customer_id: { type: "string" },
+              feature_id: { type: "string" },
+              required_balance: { type: "number" },
+            },
+            ["customer_id", "feature_id"],
+            "The customer and feature to check. `required_balance` defaults to 1.",
+          ),
+          responses: { "200": ok("Access decision with the feature balance."), "400": ok("Validation error.") },
+        },
+      },
       "/v1/plans.list": {
         post: {
           operationId: "plans.list",

packages/@emulators/autumn/src/serialize.ts

@@ -106,10 +106,25 @@ function serializeSubscription(sub: AutumnSubscription): Record<string, unknown>
   };
 }
 
-function balancesFor(as: AutumnStore, customer: AutumnCustomer): Record<string, unknown> {
+/** One feature balance in the snake_case wire shape autumn-js's
+ *  `Balance$inboundSchema` requires: every field below is non-optional in the
+ *  SDK schema, so a balance is either absent (null) or complete. */
+export interface SerializedBalance {
+  feature_id: string;
+  feature: Record<string, unknown>;
+  granted: number;
+  remaining: number;
+  usage: number;
+  unlimited: boolean;
+  overage_allowed: boolean;
+  max_purchase: number | null;
+  next_reset_at: number | null;
+}
+
+function balancesFor(as: AutumnStore, customer: AutumnCustomer): Record<string, SerializedBalance> {
   const planId = activeSubscription(customer)?.plan_id ?? "free";
   const plan = as.plans.findOneBy("plan_id", planId);
-  const balances: Record<string, unknown> = {};
+  const balances: Record<string, SerializedBalance> = {};
   for (const item of plan?.items ?? []) {
     const unlimited = item.unlimited === true;
     const granted = unlimited ? 0 : (item.included ?? 0);
@@ -129,6 +144,17 @@ function balancesFor(as: AutumnStore, customer: AutumnCustomer): Record<string,
   return balances;
 }
 
+/** The customer's balance for one feature, or undefined when the customer's
+ *  current plan has no item for it. Shares `balancesFor` so `balances.check`
+ *  and `customers.get_or_create` can never disagree about a balance. */
+export function balanceForFeature(
+  as: AutumnStore,
+  customer: AutumnCustomer,
+  featureId: string,
+): SerializedBalance | undefined {
+  return balancesFor(as, customer)[featureId];
+}
+
 export function serializeCustomer(as: AutumnStore, customer: AutumnCustomer): Record<string, unknown> {
   return {
     id: customer.customer_id,

packages/@emulators/aws/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulators/aws",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",