@vibesdotdev/account 0.0.0-stage → 1.0.0-rc.3

package/dist/billing/internal/quota-client.js

@@ -0,0 +1,239 @@
+/**
+ * Internal (service-to-service) quota decision client — SERVER SCOPE ONLY.
+ *
+ * Canonical request/decision contract for the INTERNAL
+ * `POST /api/billing/quota/check` seam (service bearer + `X-Vibes-User-Id`).
+ * Owning platform surfaces (e.g. platform-web storage) build their raw
+ * app-local facts, then call `checkQuotaInternal` — they never hand-roll the
+ * HTTP shape. Account alone applies plan semantics.
+ *
+ * TRANSPORT: rides the canonical account `api/client` instance
+ * (`vibesAccountClient`, SPEC hard rule: all HTTP to account goes through it —
+ * this module adds no second transport authority). The service bearer and the
+ * asserted user ride as per-request headers.
+ *
+ * Deliberately SEPARATE from `../client/quota-guard.ts`, which is the PUBLIC
+ * browser preflight export: a service token must never ride in a module that
+ * browser bundles import. Never re-export this from a browser-reachable
+ * barrel.
+ */
+import * as z from 'zod/v4';
+import { settle, valueFreeFailure } from '@vibesdotdev/kernel';
+import { JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import { vibesAccountClient } from "../../client/factory.js";
+import { failureStatus } from "../failure-status.js";
+import { FEATURE_SLUGS } from "../schemas/core/feature-slugs.js";
+/** Entitlement configuration state — `limit: null` is never ambiguous. */
+export const quotaLimitStateSchema = z.enum(['limited', 'unlimited', 'unconfigured']);
+/**
+ * Features whose CURRENT USAGE is a physical fact owned by the calling
+ * platform surface (not account's rated-usage records). For these,
+ * `currentUsage` is REQUIRED — an admission gate must never silently fall
+ * back to the rating meter (that would re-smuggle the meter into admission).
+ *
+ *   - `storage-capacity-gb` — current stored GB from platform-web's own DB.
+ *   - `private-repos` (ruling 1742) — the owner's LIVE count of private repo
+ *     rows in platform-web's DB. Account has no recorder for it, and the
+ *     rated meter is billing-period scoped, so it could never back a live
+ *     resource count.
+ */
+export const CALLER_SUPPLIED_USAGE_FEATURES = new Set([
+    FEATURE_SLUGS['storage-capacity-gb'],
+    FEATURE_SLUGS['private-repos']
+]);
+/** Open feature ids; only caller-supplied usage features need another request shape. */
+export const meteredFeatureSlugSchema = z.string().min(1)
+    .refine((slug) => !CALLER_SUPPLIED_USAGE_FEATURES.has(slug), {
+    message: 'Caller-supplied-usage features must use their typed request shape.'
+})
+    .brand();
+const capacityQuotaRequestSchema = z.object({
+    featureSlug: z.literal(FEATURE_SLUGS['storage-capacity-gb']),
+    /**
+     * The DELTA the caller wants to admit (e.g. this upload's GB). Chair
+     * ruling 1742: the quota contract is DELTA-ONLY — account evaluates
+     * currentUsage + requestedDelta <= limit; callers never pass absolute
+     * post-op targets.
+     */
+    requestedDelta: z.number().positive(),
+    /** Org billing subject; the asserted user must be a member (else 404). */
+    organizationId: z.string().min(1).nullable().optional(),
+    /**
+     * REQUIRED raw current usage from the OWNING platform surface (absolute,
+     * finite, nonnegative — e.g. current stored GB from the platform's own
+     * DB). Account applies plan semantics to the supplied fact; it never
+     * re-derives another app's physical facts.
+     */
+    currentUsage: z.number().min(0).finite()
+});
+const privateReposQuotaRequestSchema = z.object({
+    featureSlug: z.literal(FEATURE_SLUGS['private-repos']),
+    /**
+     * DELTA-ONLY (ruling 1742): the number of private repos being admitted by
+     * THIS operation — a whole-repo INTEGER (the forge callsite always sends
+     * 1), never an absolute post-op target like `existingCount + 1`.
+     */
+    requestedDelta: z.number().int().positive(),
+    /** Org billing subject; the asserted user must be a member (else 404). */
+    organizationId: z.string().min(1).nullable().optional(),
+    /**
+     * REQUIRED raw fact from the OWNING platform surface: the owner's LIVE
+     * count of existing private repos (a finite nonnegative INTEGER from
+     * platform-web's `countPrivateRepositories`). Account applies plan
+     * semantics to the supplied fact; it never re-derives it.
+     */
+    currentUsage: z.number().int().min(0).finite()
+});
+export const meteredQuotaRequestSchema = z.object({
+    featureSlug: meteredFeatureSlugSchema,
+    /**
+     * DELTA-ONLY (chair ruling 1742): the increment being requested, evaluated
+     * against account's own rated records — never an absolute post-op target.
+     */
+    requestedDelta: z.number().positive(),
+    organizationId: z.string().min(1).nullable().optional(),
+    /**
+     * Runtime mirror of the compile-time `currentUsage?: never`: a metered
+     * request that SMUGGLES a fact is a defective request (400), not a value
+     * to silently strip — account's own records are the only truthful basis
+     * for metered features.
+     */
+    currentUsage: z.never().optional()
+});
+/**
+ * Request contract for the internal quota check — a DISCRIMINATED union:
+ * a caller-supplied-usage request (storage capacity, private repos) without
+ * its raw fact does not typecheck and does not parse; a metered request can
+ * neither smuggle a caller-supplied slug nor carry a `currentUsage` fact.
+ */
+export const internalQuotaRequestSchema = z.union([
+    capacityQuotaRequestSchema,
+    privateReposQuotaRequestSchema,
+    meteredQuotaRequestSchema
+]);
+/** 200 body of the internal quota check (unavailable is a 503, never a 200). */
+export const internalQuotaResponseSchema = z.object({
+    feature: z.string(),
+    currentUsage: z.number(),
+    limit: z.number().nullable(),
+    limitState: quotaLimitStateSchema,
+    remaining: z.number().nullable(),
+    allowed: z.boolean(),
+    reason: z.string().optional()
+});
+/**
+ * Keep rejected-path diagnostics actionable without shipping secrets.
+ * ClientError.message already carries the account-web JSON `message`/`error`
+ * body; collapse whitespace, strip credential-shaped tokens, bound length.
+ */
+/** The text a rejected transport failure carries: an Error's message or a thrown string, else none. */
+const failureTextSchema = z.union([z.instanceof(Error).transform((error) => error.message), z.string()]).catch('');
+export function formatRejectedQuotaReason(status, err) {
+    const raw = failureTextSchema.parse(err);
+    const cleaned = raw
+        .replace(/\s+/g, ' ')
+        .replace(/(?:bearer\s+)[a-z0-9._\-+=/]{12,}/gi, 'bearer [redacted]')
+        .replace(/\b(?:sk|pk|api|token|secret|key)[_-]?[a-z0-9]{16,}\b/gi, '[redacted]')
+        .trim();
+    const detail = cleaned
+        .replace(new RegExp(`^${status}\\s+`), '')
+        .replace(/^HTTP\s+\d+\s*/i, '')
+        .slice(0, 240);
+    return detail
+        ? `quota check rejected (${status}): ${detail}`
+        : `quota check rejected (${status})`;
+}
+/**
+ * Bound every cross-app billing call: account-web transitively validates the
+ * service token against auth-web, which has intermittently hung to the CF 30s
+ * wall clock — an unbounded call here stalls the caller's whole request.
+ */
+const INTERNAL_QUOTA_TIMEOUT_MS = 20_000;
+/** The JSON value the quota check sends: the parsed request, serialized as the client serializes it. */
+const quotaWireBodySchema = JsonValueSchema;
+/**
+ * Canonical internal quota check client. Transport = the account `api/client`
+ * instance (`vibesAccountClient`); platform surfaces must not hand-roll this
+ * call.
+ */
+export async function checkQuotaInternal(params) {
+    // Absent optional fields drop out here exactly as they do on the wire.
+    const body = quotaWireBodySchema.parse(JSON.parse(JSON.stringify(internalQuotaRequestSchema.parse(params.request))));
+    // Composition failures are owner errors, not a remote quota decision.
+    const transport = params.transport ?? (await vibesAccountClient(params.runtime));
+    const posted = await settle(() => transport.post('/api/billing/quota/check', body, {
+        headers: {
+            Authorization: `Bearer ${params.serviceToken}`,
+            'X-Vibes-User-Id': params.userId
+        },
+        timeout: INTERNAL_QUOTA_TIMEOUT_MS
+    }));
+    if (!posted.ok) {
+        // The canonical client throws typed errors carrying `.status` on non-2xx.
+        const status = failureStatus(posted.cause);
+        // 4xx are REAL rejections (404 = subject not a member of the asserted
+        // org; 400 = bad request) — writes deny, but no entitlement state is
+        // invented for them. 5xx / 429 / network is not a decision at all.
+        // Retain a values-safe slice of the transport message so platform logs
+        // (BILLING_QUOTA_CONTRACT_REJECTED) can diagnose capacity_fact_required
+        // / Invalid request body without a second hop into account-web.
+        if (status !== undefined && status >= 400 && status < 500 && status !== 429) {
+            return {
+                decision: 'rejected',
+                status,
+                reason: formatRejectedQuotaReason(status, posted.cause)
+            };
+        }
+        const failure = valueFreeFailure(posted.cause);
+        return {
+            decision: 'unavailable',
+            reason: ['quota request failed:', failure.name, failure.code, failure.reason].filter(Boolean).join(' ')
+        };
+    }
+    const parsed = internalQuotaResponseSchema.safeParse(posted.value);
+    if (!parsed.success) {
+        return { decision: 'unavailable', reason: 'quota check returned an invalid body' };
+    }
+    return {
+        decision: 'decided',
+        allowed: parsed.data.allowed,
+        currentUsage: parsed.data.currentUsage,
+        limit: parsed.data.limit,
+        limitState: parsed.data.limitState,
+        remaining: parsed.data.remaining,
+        reason: parsed.data.reason
+    };
+}
+/**
+ * Generic ACCOUNT-OWNED feature quota primitive for service callers that need
+ * a plain decided outcome (forge gates, code-session gates). Throws on
+ * `unavailable`/`rejected` so the caller's own fail-direction handling (e.g.
+ * `meterGate({ failClosed })`, `CodeSessionBillingUnavailable`) applies.
+ *
+ * This lives HERE — with the account billing contract — precisely so no other
+ * surface (storage included) becomes a second authority for generic account
+ * quota decisions.
+ */
+export async function checkFeatureQuotaDecided(params) {
+    const decision = await checkQuotaInternal({
+        runtime: params.runtime,
+        serviceToken: params.serviceToken,
+        userId: params.userId,
+        request: {
+            featureSlug: params.featureSlug,
+            requestedDelta: params.requestedDelta,
+            organizationId: params.organizationId ?? null
+        },
+        transport: params.transport
+    });
+    if (decision.decision !== 'decided') {
+        throw new Error(`Billing quota check ${decision.decision}: ${decision.reason}`);
+    }
+    return {
+        allowed: decision.allowed,
+        currentUsage: decision.currentUsage,
+        limit: decision.limit,
+        remaining: decision.remaining
+    };
+}
+//# sourceMappingURL=quota-client.js.map

package/dist/billing/internal/quota-client.js.map

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

package/dist/billing/org-member-billing.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Org-first billing decision (PURE).
+ *
+ * When an organization opts in to paying for its members, a member's usage
+ * draws from the ORG credit pool up to a per-member, per-period allocation —
+ * and then FALLS BACK to the member's own user pool (a hard block only happens
+ * downstream when both pools are empty). This module holds the pure decision so
+ * it is unit-testable in isolation; the data-fetching wrapper (org config +
+ * subscription period, the member's period consumption from `credits_ledger`,
+ * and the org pool balance) lives in `apps/account-web`'s billing server and
+ * feeds these inputs in.
+ *
+ * Design (locked): per-org opt-in flag; fall back to the user pool past the
+ * allocation. The non-opted default is "user pool" — i.e. NO behavior change
+ * for any org that hasn't opted in.
+ */
+import * as z from 'zod/v4';
+/**
+ * Per-org billing config. Stored alongside the org (org settings or the org
+ * subscription metadata) and read at billing time.
+ */
+export declare const orgMemberBillingConfigSchema: z.ZodObject<{
+    orgPaysForMembers: z.ZodDefault<z.ZodBoolean>;
+    perMemberCreditAllocation: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type OrgMemberBillingConfig = z.infer<typeof orgMemberBillingConfigSchema>;
+export interface OrgBillingDecisionInput {
+    /** Whether the org has opted in to paying for member usage. */
+    orgPaysForMembers: boolean;
+    /** Per-member per-period allocation in credits. `0` = effectively off. */
+    perMemberCreditAllocation: number;
+    /** Credits this member has already drawn from the org pool this period. */
+    memberPeriodConsumption: number;
+    /** Current org credit-pool balance in credits. */
+    orgPoolBalance: number;
+}
+/**
+ * Decide whether this member's next charge routes to the ORG pool. `false`
+ * means route to the member's own user pool (the fall-back). Every failed
+ * condition resolves to the user pool — this function NEVER blocks; blocking is
+ * the downstream 402 that fires only when both pools are exhausted.
+ */
+export declare function shouldChargeOrgPool(input: OrgBillingDecisionInput): boolean;
+/** Credits this member can still draw from the org pool this period (>= 0). */
+export declare function remainingOrgAllocation(input: Pick<OrgBillingDecisionInput, 'perMemberCreditAllocation' | 'memberPeriodConsumption'>): number;
+//# sourceMappingURL=org-member-billing.d.ts.map

package/dist/billing/org-member-billing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-member-billing.d.ts","sourceRoot":"","sources":["../../src/billing/org-member-billing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;iBAKvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,yBAAyB,EAAE,MAAM,CAAC;IAClC,2EAA2E;IAC3E,uBAAuB,EAAE,MAAM,CAAC;IAChC,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAU3E;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,IAAI,CAAC,uBAAuB,EAAE,2BAA2B,GAAG,yBAAyB,CAAC,GAC3F,MAAM,CAER"}

package/dist/billing/org-member-billing.js

@@ -0,0 +1,53 @@
+/**
+ * Org-first billing decision (PURE).
+ *
+ * When an organization opts in to paying for its members, a member's usage
+ * draws from the ORG credit pool up to a per-member, per-period allocation —
+ * and then FALLS BACK to the member's own user pool (a hard block only happens
+ * downstream when both pools are empty). This module holds the pure decision so
+ * it is unit-testable in isolation; the data-fetching wrapper (org config +
+ * subscription period, the member's period consumption from `credits_ledger`,
+ * and the org pool balance) lives in `apps/account-web`'s billing server and
+ * feeds these inputs in.
+ *
+ * Design (locked): per-org opt-in flag; fall back to the user pool past the
+ * allocation. The non-opted default is "user pool" — i.e. NO behavior change
+ * for any org that hasn't opted in.
+ */
+import * as z from 'zod/v4';
+/**
+ * Per-org billing config. Stored alongside the org (org settings or the org
+ * subscription metadata) and read at billing time.
+ */
+export const orgMemberBillingConfigSchema = z.object({
+    /** The org pays for member usage from its org credit pool when true. */
+    orgPaysForMembers: z.boolean().default(false),
+    /** Credits each member may draw from the org pool per billing period. */
+    perMemberCreditAllocation: z.number().nonnegative().default(0)
+});
+/**
+ * Decide whether this member's next charge routes to the ORG pool. `false`
+ * means route to the member's own user pool (the fall-back). Every failed
+ * condition resolves to the user pool — this function NEVER blocks; blocking is
+ * the downstream 402 that fires only when both pools are exhausted.
+ */
+export function shouldChargeOrgPool(input) {
+    // Not opted in → user pool (the unchanged default for every other org).
+    if (!input.orgPaysForMembers)
+        return false;
+    // No (positive) allocation configured → nothing to draw from the org → user.
+    if (!(input.perMemberCreditAllocation > 0))
+        return false;
+    // Member has used their full allocation this period → fall back to user.
+    if (!(input.memberPeriodConsumption < input.perMemberCreditAllocation))
+        return false;
+    // Org pool is empty → fall back to the user pool.
+    if (!(input.orgPoolBalance > 0))
+        return false;
+    return true;
+}
+/** Credits this member can still draw from the org pool this period (>= 0). */
+export function remainingOrgAllocation(input) {
+    return Math.max(0, input.perMemberCreditAllocation - input.memberPeriodConsumption);
+}
+//# sourceMappingURL=org-member-billing.js.map

package/dist/billing/org-member-billing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-member-billing.js","sourceRoot":"","sources":["../../src/billing/org-member-billing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,wEAAwE;IACxE,iBAAiB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC7C,yEAAyE;IACzE,yBAAyB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;CAC9D,CAAC,CAAC;AAcH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAA8B;IACjE,wEAAwE;IACxE,IAAI,CAAC,KAAK,CAAC,iBAAiB;QAAE,OAAO,KAAK,CAAC;IAC3C,6EAA6E;IAC7E,IAAI,CAAC,CAAC,KAAK,CAAC,yBAAyB,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACzD,yEAAyE;IACzE,IAAI,CAAC,CAAC,KAAK,CAAC,uBAAuB,GAAG,KAAK,CAAC,yBAAyB,CAAC;QAAE,OAAO,KAAK,CAAC;IACrF,kDAAkD;IAClD,IAAI,CAAC,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,IAAI,CAAC;AACb,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB,CACrC,KAA6F;IAE7F,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,yBAAyB,GAAG,KAAK,CAAC,uBAAuB,CAAC,CAAC;AACrF,CAAC"}