@farthershore/farthershore-js 0.0.0

package/README.md

@@ -0,0 +1,137 @@
+# @farthershore/farthershore-js
+
+The **Farther Shore Frontend SDK** — the canonical browser integration layer
+between a static frontend artifact (the default dev-portal template, generated
+frontends, managed components, custom frontends) and the Farther Shore platform.
+
+> **Internal & experimental.** Not published to npm yet (`private: true`).
+> Breaking changes are expected while we validate the API against the dev portal,
+> managed components, and a real builder-defined feature. The eventual public
+> name is `@farthershore/farthershore-js` (the `@stripe/stripe-js` analog to the
+> server-side `@farthershore/sdk`).
+
+## Philosophy
+
+Frontend code never sees Core URLs, Gateway URLs, product backend URLs, auth
+endpoints, or routing rules. It **expresses intent**:
+
+```ts
+import { createFartherShoreClient } from "@farthershore/farthershore-js";
+
+const fs = createFartherShoreClient({
+  coreUrl: "https://core.farthershore.com",
+});
+
+const { product } = await fs.bootstrap(); // discover the product for this host
+const keys = await fs.keys.list(); // → Core (platform)
+const forecast = await fs.feature("weather").json("/forecast?city=NYC"); // → Gateway
+```
+
+The SDK decides **where** each request goes (Core for platform concerns, the
+Gateway for builder features), **how** it's authenticated, and the host/env
+scoping headers Core needs.
+
+## Surface
+
+| Namespace                              | Routes to             | Methods                                                                 |
+| -------------------------------------- | --------------------- | ----------------------------------------------------------------------- |
+| `fs.bootstrap()`                       | Core (public resolve) | discover product/env/gateway/capabilities                               |
+| `fs.product`                           | (bootstrap)           | `get()`                                                                 |
+| `fs.auth`                              | Core                  | `getSession()`, `signIn({apiKey})` (persona), `signOut()`, `setToken()` |
+| `fs.keys`                              | Core                  | `list()`, `create()`, `revoke()`, `rotate()`                            |
+| `fs.usage`                             | Core                  | `summary()`, `events()`, ~~`timeseries()`~~                             |
+| `fs.billing`                           | Core                  | `subscription()`, `openBillingPortal()`, ~~`invoices()`~~               |
+| `fs.analytics`                         | Core                  | ~~`requests()`~~                                                        |
+| `fs.feature(name)` / `fs.invoke(path)` | **Gateway**           | `fetch(path)`, `json(path)`                                             |
+
+Struck-through methods have **no platform endpoint yet** and throw
+`FartherShoreNotImplementedError` (the SDK never silently no-ops a missing
+capability) — see Deferred.
+
+## Auth
+
+- **Core** calls use the consumer **session token** as `Authorization: Bearer`.
+  The host app owns the session:
+  - _Clerk envs:_ pass `getToken` (from the Clerk browser SDK) in the config, or
+    call `fs.auth.setToken(token)`.
+  - _Persona/preview envs:_ `fs.auth.signIn({ apiKey: "fsk_test_…" })` — the SDK
+    exchanges the key for a session and manages the token itself.
+- **Gateway** (feature) calls use the consumer **API key** (`fsk_…`):
+  `fs.setApiKey(key)` (or `fs.feature(name).fetch(path, { apiKey })`). The gateway
+  host is discovered at bootstrap (the product's `runtimeHostname`).
+
+## Configuration
+
+```ts
+createFartherShoreClient({
+  coreUrl, // required — platform Core base URL
+  portalHost, // defaults to window.location.host
+  productId, // optional — bootstrap() discovers it
+  environmentId, // ephemeral/preview env scoping
+  organizationId, // org-owned subscriptions
+  gatewayUrl, // override (else derived from the product runtimeHostname)
+  apiKey, // consumer key for Gateway calls
+  getToken, // () => session bearer (Clerk) | null
+  fetch, // injectable (tests / SSR)
+});
+```
+
+## React (`@farthershore/farthershore-js/react`)
+
+The hooks live in a **subpath** of the same package — `react` is an _optional_
+peer dependency, so the core stays framework-agnostic and only React apps pull it
+in. (No second package to version.)
+
+```tsx
+import { createFartherShoreClient } from "@farthershore/farthershore-js";
+import {
+  FartherShoreProvider,
+  useProduct,
+  useApiKeys,
+  useUsage,
+  useBilling,
+  useSession,
+  useFeature,
+} from "@farthershore/farthershore-js/react";
+
+const fs = createFartherShoreClient({ coreUrl: import.meta.env.VITE_CORE_URL });
+
+function App() {
+  return (
+    <FartherShoreProvider client={fs}>
+      <Portal />
+    </FartherShoreProvider>
+  );
+}
+
+function ApiKeys() {
+  const { data, loading, create, revoke } = useApiKeys();
+  // …each hook is { data, loading, error, refresh } plus its mutations.
+}
+```
+
+Hooks: `useBootstrap`, `useProduct`, `useSession` (+ `signIn`/`signOut`),
+`useApiKeys` (+ `create`/`revoke`/`rotate`), `useUsage`, `useBilling` (+
+`openBillingPortal`), `useFeature(name)`, plus `useFartherShore()` for the raw
+client. They're thin wrappers over the client — no duplicated logic.
+
+## Deferred (no platform endpoint yet)
+
+- `usage.timeseries()` — Core exposes `summary` + recent `events` only; derive a
+  series client-side or add a Core timeseries route.
+- `billing.invoices()` — invoices are viewed through `billing.openBillingPortal()`
+  (Stripe-hosted); there's no JSON invoice list.
+- `analytics.requests()` — no consumer analytics endpoint; closest is
+  `usage.events()` + audit logs.
+- **Clerk browser sign-in** is host-app-driven (pass `getToken`); the SDK doesn't
+  bundle `@clerk/clerk-js`.
+- A browser-safe **short-lived gateway token** (vs. a long-lived `fsk_` key in the
+  page) — the platform's `fsc_` context token is server-minted today.
+
+## Scripts
+
+```bash
+pnpm --filter @farthershore/farthershore-js build      # tsc → dist/
+pnpm --filter @farthershore/farthershore-js test       # vitest
+pnpm --filter @farthershore/farthershore-js typecheck
+```

package/dist/bootstrap.d.ts

@@ -0,0 +1,6 @@
+import { type ClientContext } from "./config.js";
+import type { Bootstrap } from "./types.js";
+/** Resolve + cache the product/env/gateway onto `ctx`. Idempotent — safe to call
+ *  repeatedly; the client memoizes the result. */
+export declare function resolveBootstrap(ctx: ClientContext): Promise<Bootstrap>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAEV,SAAS,EASV,MAAM,YAAY,CAAC;AA8LpB;kDACkD;AAClD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CA+B7E"}

package/dist/bootstrap.js

@@ -0,0 +1,147 @@
+// Capability discovery. `bootstrap()` resolves the product the frontend is
+// running for from the portal host — the SAME public endpoint the portal renders
+// from — and caches productId / environmentId / gateway origin on the client so
+// every later call knows where to go.
+//
+// The resolve DTO carries the product's full catalog: the plan list (the rich
+// 5-knob unified billing shape — recurring fee, metered $/unit, trial,
+// min/max spend, included quotas, credit grants), product-level meters, and the
+// docs/legal MDX origins. `bootstrap()` surfaces ALL of it so a generated or
+// managed frontend can render plans/pricing/quotas/credit/docs/legal and a
+// subscribe flow — not just an account dashboard.
+import { coreFetch } from "./http.js";
+import { FartherShoreNotReadyError } from "./errors.js";
+// ── Mappers ───────────────────────────────────────────────────────────────
+function mapMeter(m) {
+    const key = m.key ?? m.dimension;
+    if (!key)
+        return null;
+    return {
+        key,
+        display: m.display ?? m.label ?? key,
+        ...(m.unit ? { unit: m.unit } : {}),
+    };
+}
+function mapBranding(p) {
+    return {
+        displayName: p.displayName ?? p.name,
+        logoUrl: p.logoUrl ?? null,
+        primaryColor: p.primaryColor ?? null,
+        description: p.description ?? null,
+    };
+}
+function mapProduct(p) {
+    const meters = (p.meters ?? [])
+        .map(mapMeter)
+        .filter((m) => m !== null);
+    return {
+        id: p.id,
+        slug: p.runtimeHostname.split(".")[0] ?? p.id,
+        name: p.name,
+        description: p.description ?? null,
+        branding: mapBranding(p),
+        gatewayHost: p.runtimeHostname,
+        portalHost: p.portalHostname,
+        docsBaseUrl: p.docsBaseUrl ?? null,
+        legalBaseUrl: p.legalBaseUrl ?? null,
+        featuredCompiledPlanId: p.featuredCompiledPlanId ?? null,
+        meters,
+    };
+}
+function mapEnv(e) {
+    return {
+        id: e.id,
+        name: e.name,
+        slug: e.slug,
+        authStrategy: e.customerAuthStrategy ?? "clerk",
+        branch: e.branch ?? null,
+        stripeMode: e.stripeMode ?? null,
+    };
+}
+function mapPlanMeter(m) {
+    return {
+        dimension: m.dimension,
+        price_per_unit_micros: m.price_per_unit_micros,
+    };
+}
+function mapPlanLimit(l) {
+    return {
+        dimension: l.dimension,
+        window: l.window.type === "named"
+            ? { type: "named", name: l.window.name }
+            : { type: "custom", seconds: l.window.seconds },
+        capacity: l.capacity,
+        ...(l.enforcement ? { enforcement: l.enforcement } : {}),
+    };
+}
+function mapPlan(p) {
+    return {
+        id: p.id,
+        key: p.key,
+        name: p.name,
+        description: p.description ?? null,
+        recurringFeeCents: p.recurring_fee_cents,
+        grants: p.grants ?? [],
+        trialDays: p.trial_days,
+        maxMonthlySpendCents: p.max_monthly_spend_cents ?? null,
+        minMonthlySpendCents: p.min_monthly_spend_cents ?? null,
+        meters: (p.meters ?? []).map(mapPlanMeter),
+        limits: (p.limits ?? []).map(mapPlanLimit),
+        planDetails: p.planDetails ?? [],
+    };
+}
+/** Derive coarse capability keys from the resolved product + plans so a
+ *  managed frontend can branch on what the product actually offers (instead of
+ *  the previously hard-coded empty array). */
+function deriveCapabilities(product, plans) {
+    const caps = new Set();
+    if (plans.length > 0)
+        caps.add("plans");
+    if (plans.some((p) => p.recurringFeeCents > 0 || p.meters.length > 0)) {
+        caps.add("billing");
+    }
+    if (plans.some((p) => p.meters.length > 0))
+        caps.add("usage-metered");
+    if (plans.some((p) => p.limits.some((l) => l.window.type === "named" && l.window.name === "month"))) {
+        caps.add("usage-quota");
+    }
+    if (plans.some((p) => p.grants.length > 0 || p.trialDays > 0)) {
+        caps.add("credit-grants");
+    }
+    if (product.docsBaseUrl)
+        caps.add("docs");
+    if (product.legalBaseUrl)
+        caps.add("legal");
+    return [...caps];
+}
+/** Resolve + cache the product/env/gateway onto `ctx`. Idempotent — safe to call
+ *  repeatedly; the client memoizes the result. */
+export async function resolveBootstrap(ctx) {
+    if (!ctx.portalHost) {
+        throw new FartherShoreNotReadyError("no portalHost to bootstrap from — set config.portalHost (or run in a browser).");
+    }
+    const raw = await coreFetch(ctx, {
+        method: "GET",
+        path: "/portal/public/resolve",
+        query: { host: ctx.portalHost },
+        auth: "none",
+    });
+    const product = mapProduct(raw.product);
+    const environment = raw.environment ? mapEnv(raw.environment) : null;
+    const plans = (raw.plans ?? []).map(mapPlan);
+    // Cache routing facts for subsequent calls (config values still win).
+    ctx.productId = ctx.productId ?? product.id;
+    if (environment)
+        ctx.environmentId = ctx.environmentId ?? environment.id;
+    ctx.gatewayUrl = ctx.gatewayUrl ?? `https://${product.gatewayHost}`;
+    return {
+        product,
+        environment,
+        branding: product.branding,
+        plans,
+        frontendReleaseHash: raw.frontendReleaseHash ?? null,
+        capabilities: deriveCapabilities(product, plans),
+        features: [],
+    };
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/catalog.d.ts

@@ -0,0 +1,81 @@
+import type { Grant, Meter, Plan, PlanMeter } from "./types.js";
+export type PlanKind = "free" | "pay_as_you_go" | "subscription" | "hybrid" | "prepaid" | "trial" | "custom";
+/**
+ * Classify a plan into a single canonical kind — mirrors the shared
+ * `classifyPlan` decision tree so this surface labels a plan identically to the
+ * SSR portal / web-ui / fs-admin.
+ */
+export declare function classifyPlan(plan: Plan): PlanKind;
+/** True iff the plan charges nothing at all (no fee, no meters, no prepaid, no
+ *  trial). Free plans skip Stripe — `subscribe()` activates them directly. */
+export declare function isFreePlan(plan: Plan): boolean;
+/** True iff the plan is purely usage-based (no recurring fee, ≥1 meter). */
+export declare function isPayAsYouGoPlan(plan: Plan): boolean;
+/** Render-ready headline price for a plan card: `{ price, period }`.
+ *   - free          → `{ "$0", "forever" }`
+ *   - pay-as-you-go → `{ "$0", "+ usage" }`
+ *   - otherwise     → `{ "$N", "/mo" }` */
+export declare function formatPlanPrice(plan: Plan): {
+    price: string;
+    period: string;
+};
+/** Format an integer-cents value as "$X" (or "$X.YY" when fractional). */
+export declare function formatCents(cents: number): string;
+/**
+ * Format a micros-per-unit value as a dollar price string (mirrors the SSR
+ * portal's `formatPriceFromMicros`):
+ *   1_000_000 → "$1"   100_000 → "$0.10"   1_000 → "$0.001"   1 → "$0.000001"
+ */
+export declare function formatPriceFromMicros(micros: number): string;
+/** Per-meter pricing headline, e.g. "$0.001 / request". */
+export declare function summarizeMeterPricing(meter: PlanMeter): string;
+/** One-line minimum-spend floor summary, or null when the plan has no floor. */
+export declare function formatMinimumSpend(plan: Plan): string | null;
+/**
+ * Synthesize a short feature-bullet list for a plan card. Uses the builder's
+ * `planDetails` verbatim when present, else derives from the plan's monthly
+ * quotas + kind — mirrors the SSR portal's `synthesizeFeatures`.
+ */
+export declare function synthesizePlanFeatures(plan: Plan): string[];
+export type GrantRow = {
+    /** Stable React key. */
+    id: string;
+    kind: Grant["kind"];
+    /** Display label, e.g. "Monthly credit". */
+    label: string;
+    /** Primary value, e.g. "$50/month", "14-day trial". */
+    value: string;
+    /** Secondary line, or null. */
+    detail: string | null;
+};
+/** The effective grant list for a plan: the declared `grants[]` plus a
+ *  synthesized `{kind:"trial"}` entry when `trialDays > 0` (de-duped). Mirrors
+ *  the shared `getEffectiveGrants`. */
+export declare function effectiveGrants(plan: Plan): Grant[];
+/** Build render-ready grant rows for a plan, sorted by a stable display order. */
+export declare function buildGrantRows(plan: Plan): GrantRow[];
+/** Monthly included quota for a dimension on a plan, or null when none. */
+export declare function quotaForDimension(plan: Plan | null, dimension: string): number | null;
+/** Progress-bar percentage + a coarse status color name for `used / total`. */
+export declare function computeProgressBar(used: number, total: number): {
+    pct: number;
+    status: "ok" | "warning" | "error";
+};
+export type MeterUsageRow = {
+    key: string;
+    label: string;
+    used: number;
+    quota: number | null;
+    unit?: string;
+};
+/**
+ * Combine a plan's monthly quotas with a usage summary into render-ready rows —
+ * one per meter that has a quota OR non-zero usage. Sorted: quota'd meters
+ * first (by label), then no-quota meters by usage descending. Mirrors the SSR
+ * portal's `buildAllMeterUsage`.
+ *
+ * `meters` is the product-level meter catalog (for labels/units); when empty,
+ * the summary keys are used directly.
+ */
+export declare function buildMeterUsageRows(plan: Plan | null, summary: Record<string, number>, meters: Meter[]): MeterUsageRow[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAa,SAAS,EAAE,MAAM,YAAY,CAAC;AAS3E,MAAM,MAAM,QAAQ,GAChB,MAAM,GACN,eAAe,GACf,cAAc,GACd,QAAQ,GACR,SAAS,GACT,OAAO,GACP,QAAQ,CAAC;AAUb;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAQjD;AAED;8EAC8E;AAC9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAO9C;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEpD;AAID;;;2CAG2C;AAC3C,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAO7E;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,2DAA2D;AAC3D,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAE9D;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAI5D;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAoB3D;AAID,MAAM,MAAM,QAAQ,GAAG;IACrB,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAsBF;;uCAEuC;AACvC,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,EAAE,CAMnD;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,EAAE,CAMrD;AAwED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAKf;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,OAAO,CAAA;CAAE,CAIrD;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,EAAE,KAAK,EAAE,GACd,aAAa,EAAE,CA+BjB"}

package/dist/catalog.js

@@ -0,0 +1,281 @@
+// Pure catalog/pricing display helpers — the SDK-local port of the SSR portal's
+// plan classification + pricing/grant/quota formatting (dev-portal's
+// classification.ts / pricing-display.ts / grant-display.ts / plan-display.ts).
+//
+// These keep a generated/managed frontend from re-deriving "is this Free vs
+// pay-as-you-go vs $N/mo", "$0.001 / request", "$50/month credit", or "used / N
+// included" by hand. All pure functions over the SDK's `Plan` type — safe to
+// call from render paths.
+/** The named-window name for a limit rule, or null for custom windows. */
+function windowName(limit) {
+    return limit.window.type === "named" ? limit.window.name : null;
+}
+/** First one-time grant amount (cents) in the plan's grants, or 0. */
+function oneTimeGrantCents(plan) {
+    for (const g of plan.grants) {
+        if (g.kind === "one_time")
+            return g.amount_cents;
+    }
+    return 0;
+}
+/**
+ * Classify a plan into a single canonical kind — mirrors the shared
+ * `classifyPlan` decision tree so this surface labels a plan identically to the
+ * SSR portal / web-ui / fs-admin.
+ */
+export function classifyPlan(plan) {
+    if (plan.trialDays > 0)
+        return "trial";
+    if (plan.recurringFeeCents > 0) {
+        return plan.meters.length > 0 ? "hybrid" : "subscription";
+    }
+    if (oneTimeGrantCents(plan) > 0)
+        return "prepaid";
+    if (plan.meters.length > 0)
+        return "pay_as_you_go";
+    return "free";
+}
+/** True iff the plan charges nothing at all (no fee, no meters, no prepaid, no
+ *  trial). Free plans skip Stripe — `subscribe()` activates them directly. */
+export function isFreePlan(plan) {
+    return (plan.recurringFeeCents === 0 &&
+        plan.meters.length === 0 &&
+        oneTimeGrantCents(plan) === 0 &&
+        plan.trialDays === 0);
+}
+/** True iff the plan is purely usage-based (no recurring fee, ≥1 meter). */
+export function isPayAsYouGoPlan(plan) {
+    return plan.recurringFeeCents === 0 && plan.meters.length > 0;
+}
+// ── Price formatting ─────────────────────────────────────────────────────────
+/** Render-ready headline price for a plan card: `{ price, period }`.
+ *   - free          → `{ "$0", "forever" }`
+ *   - pay-as-you-go → `{ "$0", "+ usage" }`
+ *   - otherwise     → `{ "$N", "/mo" }` */
+export function formatPlanPrice(plan) {
+    if (isFreePlan(plan))
+        return { price: "$0", period: "forever" };
+    if (isPayAsYouGoPlan(plan))
+        return { price: "$0", period: "+ usage" };
+    return {
+        price: `$${(plan.recurringFeeCents / 100).toFixed(0)}`,
+        period: "/mo",
+    };
+}
+/** Format an integer-cents value as "$X" (or "$X.YY" when fractional). */
+export function formatCents(cents) {
+    if (cents % 100 === 0)
+        return `$${(cents / 100).toFixed(0)}`;
+    return `$${(cents / 100).toFixed(2)}`;
+}
+/**
+ * Format a micros-per-unit value as a dollar price string (mirrors the SSR
+ * portal's `formatPriceFromMicros`):
+ *   1_000_000 → "$1"   100_000 → "$0.10"   1_000 → "$0.001"   1 → "$0.000001"
+ */
+export function formatPriceFromMicros(micros) {
+    if (micros === 0)
+        return "Free";
+    const dollars = micros / 1_000_000;
+    if (dollars >= 1)
+        return `$${dollars.toFixed(2).replace(/\.00$/, "")}`;
+    const raw = dollars.toFixed(8);
+    const trimmed = raw.replace(/(\.\d*?[1-9])0+$/, "$1");
+    const padded = /\.\d$/.test(trimmed) ? `${trimmed}0` : trimmed;
+    return `$${padded}`;
+}
+/** Per-meter pricing headline, e.g. "$0.001 / request". */
+export function summarizeMeterPricing(meter) {
+    return `${formatPriceFromMicros(meter.price_per_unit_micros)} / ${meter.dimension}`;
+}
+/** One-line minimum-spend floor summary, or null when the plan has no floor. */
+export function formatMinimumSpend(plan) {
+    const floor = plan.minMonthlySpendCents;
+    if (!floor || floor <= 0)
+        return null;
+    return `${formatCents(floor)}/month minimum`;
+}
+// ── Feature synthesis ────────────────────────────────────────────────────────
+/**
+ * Synthesize a short feature-bullet list for a plan card. Uses the builder's
+ * `planDetails` verbatim when present, else derives from the plan's monthly
+ * quotas + kind — mirrors the SSR portal's `synthesizeFeatures`.
+ */
+export function synthesizePlanFeatures(plan) {
+    if (plan.planDetails.length > 0)
+        return plan.planDetails;
+    const features = [];
+    for (const rule of plan.limits) {
+        if (windowName(rule) === "month") {
+            features.push(`${rule.capacity.toLocaleString()} ${rule.dimension} / month`);
+        }
+    }
+    features.push("Full API access");
+    if (isFreePlan(plan)) {
+        features.push("Community support");
+    }
+    else if (isPayAsYouGoPlan(plan)) {
+        features.push("Usage-based billing for overages");
+        features.push("Dedicated support");
+    }
+    else {
+        features.push("Priority support");
+    }
+    return features;
+}
+const GRANT_KIND_LABEL = {
+    recurring: "Monthly credit",
+    one_time: "Prepaid credit",
+    promotional: "Promotional credit",
+    trial: "Free trial",
+    rollover: "Unused balance rollover",
+    top_up: "Top-up pack",
+    auto_recharge: "Auto-recharge",
+};
+const GRANT_KIND_ORDER = {
+    recurring: 0,
+    one_time: 1,
+    promotional: 2,
+    trial: 3,
+    rollover: 4,
+    top_up: 5,
+    auto_recharge: 6,
+};
+/** The effective grant list for a plan: the declared `grants[]` plus a
+ *  synthesized `{kind:"trial"}` entry when `trialDays > 0` (de-duped). Mirrors
+ *  the shared `getEffectiveGrants`. */
+export function effectiveGrants(plan) {
+    const out = [...plan.grants];
+    if (plan.trialDays > 0 && !out.some((g) => g.kind === "trial")) {
+        out.push({ kind: "trial" });
+    }
+    return out;
+}
+/** Build render-ready grant rows for a plan, sorted by a stable display order. */
+export function buildGrantRows(plan) {
+    const rows = effectiveGrants(plan).map((grant, idx) => formatGrantRow(grant, plan, idx));
+    rows.sort((a, b) => GRANT_KIND_ORDER[a.kind] - GRANT_KIND_ORDER[b.kind]);
+    return rows;
+}
+function formatGrantRow(grant, plan, idx) {
+    switch (grant.kind) {
+        case "recurring":
+            return {
+                id: `recurring-${idx}`,
+                kind: "recurring",
+                label: GRANT_KIND_LABEL.recurring,
+                value: `${formatCents(grant.amount_cents)}/month`,
+                detail: "Resets every billing period",
+            };
+        case "one_time":
+            return {
+                id: `one_time-${idx}`,
+                kind: "one_time",
+                label: GRANT_KIND_LABEL.one_time,
+                value: formatCents(grant.amount_cents),
+                detail: "One-time grant at signup",
+            };
+        case "promotional":
+            return {
+                id: `promotional-${grant.label}`,
+                kind: "promotional",
+                label: grant.label,
+                value: formatCents(grant.amount_cents),
+                detail: grant.expires_after_days
+                    ? `Expires ${grant.expires_after_days} days after issue`
+                    : null,
+            };
+        case "trial":
+            return {
+                id: `trial-${idx}`,
+                kind: "trial",
+                label: GRANT_KIND_LABEL.trial,
+                value: plan.trialDays > 0 ? `${plan.trialDays}-day trial` : "Included",
+                detail: null,
+            };
+        case "rollover":
+            return {
+                id: `rollover-${idx}`,
+                kind: "rollover",
+                label: GRANT_KIND_LABEL.rollover,
+                value: `${grant.percent}% carries over`,
+                detail: grant.percent === 0
+                    ? "Unused credit expires at period end"
+                    : grant.percent === 100
+                        ? "Unused credit fully carries to next period"
+                        : null,
+            };
+        case "top_up":
+            return {
+                id: `top_up-${grant.sku}`,
+                kind: "top_up",
+                label: grant.label,
+                value: `${formatCents(grant.price_cents)} → ${formatCents(grant.credit_cents)} credit`,
+                detail: `SKU: ${grant.sku}`,
+            };
+        case "auto_recharge":
+            return {
+                id: `auto_recharge-${idx}`,
+                kind: "auto_recharge",
+                label: GRANT_KIND_LABEL.auto_recharge,
+                value: `+${formatCents(grant.refill_cents)} per refill`,
+                detail: `Triggers when balance drops below ${formatCents(grant.threshold_cents)}`,
+            };
+    }
+}
+// ── Usage / quota rows (progress) ────────────────────────────────────────────
+/** Monthly included quota for a dimension on a plan, or null when none. */
+export function quotaForDimension(plan, dimension) {
+    const rule = plan?.limits.find((r) => r.dimension === dimension && windowName(r) === "month");
+    return rule?.capacity ?? null;
+}
+/** Progress-bar percentage + a coarse status color name for `used / total`. */
+export function computeProgressBar(used, total) {
+    const pct = total > 0 ? Math.min(100, Math.round((used / total) * 100)) : 0;
+    const status = pct >= 90 ? "error" : pct >= 70 ? "warning" : "ok";
+    return { pct, status };
+}
+/**
+ * Combine a plan's monthly quotas with a usage summary into render-ready rows —
+ * one per meter that has a quota OR non-zero usage. Sorted: quota'd meters
+ * first (by label), then no-quota meters by usage descending. Mirrors the SSR
+ * portal's `buildAllMeterUsage`.
+ *
+ * `meters` is the product-level meter catalog (for labels/units); when empty,
+ * the summary keys are used directly.
+ */
+export function buildMeterUsageRows(plan, summary, meters) {
+    // Union of catalog dimensions and any dimension present in the summary.
+    const byKey = new Map();
+    for (const m of meters)
+        byKey.set(m.key, m);
+    for (const key of Object.keys(summary)) {
+        if (!byKey.has(key))
+            byKey.set(key, { key, display: key });
+    }
+    const rows = [];
+    for (const meter of byKey.values()) {
+        const used = summary[meter.key] ?? 0;
+        const quota = quotaForDimension(plan, meter.key);
+        if (quota != null || used > 0) {
+            rows.push({
+                key: meter.key,
+                label: meter.display,
+                used,
+                quota,
+                ...(meter.unit ? { unit: meter.unit } : {}),
+            });
+        }
+    }
+    rows.sort((a, b) => {
+        const aHasQuota = a.quota != null && a.quota > 0 ? 0 : 1;
+        const bHasQuota = b.quota != null && b.quota > 0 ? 0 : 1;
+        if (aHasQuota !== bHasQuota)
+            return aHasQuota - bHasQuota;
+        if (aHasQuota === 0)
+            return a.label.localeCompare(b.label);
+        return b.used - a.used;
+    });
+    return rows;
+}
+//# sourceMappingURL=catalog.js.map