@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/transcription-recordings.ts

@@ -15,6 +15,7 @@ import {
   normalizeMimeType,
   requireAccessGrant,
   TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS,
+  TranscriptionBillingRefusedError,
   TranscriptionServiceError,
   type ApiRouteDeps,
 } from "@opengeni/core";
@@ -45,10 +46,13 @@ import {
   TranscriptionRecordingStateError,
   isSessionEventPersistenceError,
 } from "@opengeni/db";
-import { getWorkspace } from "@opengeni/db";
+import { getWorkspace, type CreditDebitAttribution } from "@opengeni/db";
 import type { Context, Hono } from "hono";
+import { creditDebitAttributionForGrant } from "../access-grant-rls";
 import { ApiHttpError } from "../http/api-error";
+import { wavDurationSeconds } from "../transcription/wav-duration";
 import { TranscriptionSegmenterError } from "../transcription/segmenter";
+import { transcriptionBillingRefusal } from "../transcription/billing-refusal";
 
 const CHUNK_SHA256_HEADER = "x-opengeni-chunk-sha256";
 const CHUNK_START_HEADER = "x-opengeni-chunk-start-milliseconds";
@@ -60,6 +64,8 @@ type RecordingAuthority = {
   workspaceId: string;
   subjectId: string;
   voiceInput?: WorkspaceVoiceInputSettings | undefined;
+  /** Trusted payer for deployment-funded segments. */
+  attribution: CreditDebitAttribution;
 };
 
 class RecordingProcessingError extends Error {
@@ -370,6 +376,8 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
           !(await service.available({
             workspaceId: authority.workspaceId,
             subjectId: authority.subjectId,
+            preferredProvider: authority.voiceInput?.preferredProvider,
+            fallbackEnabled: authority.voiceInput?.fallbackEnabled,
           }))
         ) {
           return c.json({ code: "unavailable" }, 503);
@@ -420,6 +428,37 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
             false,
           );
         }
+        const segmentProviderId =
+          claim.segment.providerId && claim.segment.providerId !== "host"
+            ? claim.segment.providerId
+            : null;
+        // Credit admission for the exact pinned provider, before the durable
+        // provider-start fence. A refusal releases the claim untouched (no
+        // audio sent) and surfaces 402 so the client stops retrying.
+        if (segmentProviderId && service.admit) {
+          try {
+            await service.admit({
+              providerId: segmentProviderId,
+              accountId: authority.accountId,
+              workspaceId: authority.workspaceId,
+              attribution: authority.attribution,
+            });
+          } catch (error) {
+            if (!(error instanceof TranscriptionBillingRefusedError)) throw error;
+            await failTranscriptionRecordingSegment(deps.db, {
+              workspaceId: authority.workspaceId,
+              subjectId: authority.subjectId,
+              recordingId: uuidParam(c, "recordingId"),
+              segmentNumber,
+              attemptId,
+              fallbackProviderId: null,
+              // The real refusal, so a reloaded recording still explains it.
+              errorCode: error.code,
+              retryable: true,
+            }).catch(() => null);
+            return transcriptionBillingRefusal(c, error);
+          }
+        }
         const providerStartedAt = new Date();
         const providerDeadlineAt = new Date(
           providerStartedAt.getTime() + TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS,
@@ -442,10 +481,22 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
           durationSeconds: claim.segment.durationMilliseconds / 1_000,
           requestId: attemptId,
           providerDeadlineAt,
-          ...(claim.segment.providerId && claim.segment.providerId !== "host"
-            ? { providerId: claim.segment.providerId }
-            : {}),
+          deferBillingSettlement: true,
+          ...(segmentProviderId ? { providerId: segmentProviderId } : {}),
+          billing: {
+            // One settlement per prepared segment of this exact recording,
+            // however many provider attempts it takes. The recording id is
+            // client-chosen, so the unit id also binds its server creation
+            // time and the server-produced segment bytes.
+            sourceId: `${claim.recording.recording.id}:${Date.parse(claim.recording.recording.createdAt)}:${segmentNumber}:${claim.segment.sha256}`,
+            attribution: authority.attribution,
+            trustedDurationSeconds: wavDurationSeconds(stored.bytes) ?? undefined,
+          },
         });
+        // The transcript commits first and on its own: a billing failure can
+        // never roll back text the user already waited for. Only the attempt
+        // that durably completed the segment settles it (a stale attempt is
+        // refused here and never charges); settlement itself never throws.
         const completed = await completeTranscriptionRecordingSegment(deps.db, {
           workspaceId: authority.workspaceId,
           subjectId: authority.subjectId,
@@ -456,6 +507,9 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
           languages: result.languages,
           providerId: claim.segment.providerId ?? result.providerId,
         });
+        // Never rejects for the built-in service (it logs and retries); a
+        // custom service's failure must not turn a durable transcript into an error.
+        await result.settleBilling?.().catch(() => undefined);
         return c.json(await cleanupTerminalObjects(deps, authority, completed));
       } catch (error) {
         if (authority && attemptId && segmentNumber !== null) {
@@ -489,6 +543,11 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
             errorCode: failure.code,
             retryable: failure.retryable,
           }).catch(() => null);
+          // A credit refusal sent no audio; the released segment stays
+          // retryable, but the client must see the definitive refusal.
+          if (error instanceof TranscriptionBillingRefusedError) {
+            return transcriptionBillingRefusal(c, error);
+          }
           if (persisted) return c.json(persisted);
         }
         return routeError(c, error);
@@ -545,6 +604,7 @@ async function requireRecordingAuthority(
     accountId: grant.accountId,
     workspaceId,
     subjectId: grant.subjectId,
+    attribution: creditDebitAttributionForGrant(grant),
   };
 }
 
@@ -641,6 +701,10 @@ function processingFailure(error: unknown): {
   if (error instanceof TranscriptionSegmenterError) {
     return { code: error.code, retryable: error.retryable };
   }
+  if (error instanceof TranscriptionBillingRefusedError) {
+    // Refused before any audio was sent; retryable once the payer is funded.
+    return { code: error.code, retryable: true };
+  }
   if (error instanceof TranscriptionServiceError) {
     return {
       code: error.code,
@@ -663,6 +727,9 @@ function routeError(c: Context, error: unknown): Response | Promise<Response> {
   if (error instanceof TranscriptionRecordingNotFoundError) {
     return c.json({ code: "not_found" }, 404);
   }
+  if (error instanceof TranscriptionBillingRefusedError) {
+    return transcriptionBillingRefusal(c, error);
+  }
   if (error instanceof TranscriptionRecordingConflictError) {
     return c.json({ code: "conflict" }, 409);
   }

package/src/routes/transcriptions.ts

@@ -3,9 +3,16 @@ import {
   WorkspaceVoiceInputSettings,
   type TranscribeAudioResponse,
 } from "@opengeni/contracts";
-import { type ApiRouteDeps, requireAccessGrant, TranscriptionServiceError } from "@opengeni/core";
+import {
+  type ApiRouteDeps,
+  requireAccessGrant,
+  TranscriptionBillingRefusedError,
+  TranscriptionServiceError,
+} from "@opengeni/core";
 import { getWorkspace } from "@opengeni/db";
 import type { Hono } from "hono";
+import { creditDebitAttributionForGrant } from "../access-grant-rls";
+import { transcriptionBillingRefusal } from "../transcription/billing-refusal";
 import { registerResumableTranscriptionRoutes } from "./transcription-recordings";
 
 export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void {
@@ -20,12 +27,26 @@ export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void
     }
     const preferences = WorkspaceVoiceInputSettings.safeParse(workspace.settings.voiceInput).data;
     const service = deps.transcription;
-    if (!service || !(await service.available({ workspaceId, subjectId: grant.subjectId }))) {
+    if (
+      !service ||
+      !(await service.available({
+        workspaceId,
+        subjectId: grant.subjectId,
+        preferredProvider: preferences?.preferredProvider,
+        fallbackEnabled: preferences?.fallbackEnabled,
+      }))
+    ) {
       return c.json({ code: "unavailable" }, 503);
     }
     try {
       const body = await audioRequest(c.req.raw, service.limits().maxSizeBytes);
+      // Server-generated: the correlation id is client-chosen and a reused
+      // settlement key would make every later call with it free.
       const result = await service.transcribe({
+        billing: {
+          sourceId: crypto.randomUUID(),
+          attribution: creditDebitAttributionForGrant(grant),
+        },
         preferredProvider: preferences?.preferredProvider,
         fallbackEnabled: preferences?.fallbackEnabled,
         workspaceId,
@@ -46,6 +67,9 @@ export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void
       if (error instanceof TranscriptionServiceError) {
         return c.json({ code: error.code }, error.status as never);
       }
+      if (error instanceof TranscriptionBillingRefusedError) {
+        return transcriptionBillingRefusal(c, error);
+      }
       if (isAbort(error)) return c.json({ code: "cancelled" }, 499 as never);
       return c.json({ code: "unknown" }, 500);
     }

package/src/routes/usage-allowances.ts

@@ -0,0 +1,381 @@
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import {
+  ClearWorkspaceAllowanceRequest,
+  GetMyUsageRequest,
+  GetUsageRequest,
+  GrantWorkspaceCreditsRequest,
+  SetMemberAllowanceRequest,
+  SetWorkspaceAllowanceRequest,
+  WorkspaceAllowance,
+  WorkspaceAllowanceState,
+  WorkspaceCreditGrant,
+  WorkspaceUsageResponse,
+  MemberAllowance,
+  ClearWorkspaceAllowanceResponse,
+  type AccessContext,
+} from "@opengeni/contracts";
+import { ExternalIdentityReference } from "@opengeni/contracts/external-identities";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  accessGrantAuthorizationFromContext,
+  requireAccountAdminAuthorizationStamp,
+  requireAccessContext,
+  requireAccessGrantAuthorization,
+  requireResolvedAccessGrantAuthorization,
+  type AccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  clearWorkspaceAllowance,
+  findWorkspaceByExternalIdentity,
+  getWorkspaceAllowance,
+  getWorkspaceAllowanceState,
+  getWorkspace,
+  getWorkspaceUsage,
+  grantWorkspaceCredits,
+  nestedPostgresSqlState,
+  setMemberAllowance,
+  setWorkspaceAllowance,
+  withAccountRls,
+  UsageAllowanceVersionConflictError,
+} from "@opengeni/db";
+import { parseRequestBody, parseRequestJson } from "../http/request-body";
+
+type Authority = { authorization: AccessGrantAuthorization; context: AccessContext };
+type Operation = "read" | "budget-read" | "workspace-write" | "member-write" | "own";
+
+/** No workspace wildcard, service initiator, or actor label can confer budget authority. */
+export function requireAllowanceAuthority(
+  { authorization, context }: Authority,
+  operation: Operation,
+): void {
+  const grant = requireResolvedAccessGrantAuthorization(
+    authorization,
+    authorization.grant.workspaceId,
+  );
+  if (grant.principalKind === "agent_attempt" || grant.metadata?.sessionId !== undefined) {
+    throw new HTTPException(403, { message: "Agents cannot access usage allowances" });
+  }
+  const organizationKey = accountScopedApiKeyWorkspaceAuthority(context);
+  const sameOrganizationKey =
+    organizationKey?.accountId === grant.accountId ? organizationKey : null;
+  const accountAdmin =
+    authorization.accountGrant?.permissions.includes("account:admin") === true &&
+    requireAccountAdminAuthorizationStamp(authorization).accountId === grant.accountId;
+  const workspaceAdmin = grant.permissions.includes("workspace:admin");
+  if (
+    sameOrganizationKey?.permissionMode === "explicit" &&
+    (operation === "workspace-write" || operation === "member-write")
+  ) {
+    if (authorization.accountGrant?.permissions.includes("usage_allowances:manage")) return;
+    throw new HTTPException(403, { message: "missing permission: usage_allowances:manage" });
+  }
+  if (operation === "own") {
+    if (grant.principalKind !== "human_session" || grant.serviceInitiator) {
+      throw new HTTPException(403, { message: "Own usage requires an authenticated member" });
+    }
+    return;
+  }
+  if (operation === "read" || operation === "budget-read") {
+    if (
+      workspaceAdmin ||
+      accountAdmin ||
+      sameOrganizationKey?.permissions.includes("workspace:read")
+    )
+      return;
+  } else if (operation === "workspace-write") {
+    // Existing full keys retain key-control budget authority. Setup keys use
+    // literal account allowance authority plus the canonical organization-key
+    // workspace stamp; asUser carries neither account scope nor key stamp.
+    if (sameOrganizationKey) {
+      if (
+        sameOrganizationKey.permissions.includes("workspace:admin") &&
+        (sameOrganizationKey.permissions.includes("api_keys:manage") ||
+          authorization.accountGrant?.permissions.includes("usage_allowances:manage"))
+      )
+        return;
+    } else if (
+      accountAdmin &&
+      grant.principalKind === "human_session" &&
+      !grant.serviceInitiator &&
+      !context.subjectId.startsWith("api_key:")
+    )
+      return;
+  } else if (operation === "member-write") {
+    if (
+      sameOrganizationKey?.permissions.includes("workspace:admin") ||
+      (workspaceAdmin &&
+        grant.principalKind === "human_session" &&
+        !grant.serviceInitiator &&
+        !context.subjectId.startsWith("api_key:"))
+    )
+      return;
+  }
+  throw new HTTPException(403, { message: `Missing usage allowance authority: ${operation}` });
+}
+
+async function resolveWorkspace(c: Context, deps: ApiRouteDeps): Promise<string> {
+  const workspaceId = c.req.param("workspaceId");
+  if (workspaceId) return workspaceId;
+  const context = await requireAccessContext(c, deps);
+  const organizationKey = accountScopedApiKeyWorkspaceAuthority(context);
+  // External tenant paths are host-service lookups, never caller-selected
+  // default-account guesses or provisioning.
+  const externalAccountId =
+    c.req.header("x-opengeni-external-actor") !== undefined ? context.defaultAccountId : null;
+  const accountId = organizationKey?.accountId ?? externalAccountId;
+  if (!accountId)
+    throw new HTTPException(403, { message: "Organization API key or external user required" });
+  const reference = parseRequestBody(ExternalIdentityReference, {
+    source: c.req.param("workspaceSource"),
+    externalId: c.req.param("workspaceExternalId"),
+  });
+  const workspace = await withAccountRls(deps.db, accountId, (tx) =>
+    findWorkspaceByExternalIdentity(tx, {
+      accountId,
+      externalSource: reference.source,
+      externalId: reference.externalId,
+    }),
+  );
+  if (!workspace) throw new HTTPException(404, { message: "Workspace not found" });
+  return workspace.id;
+}
+
+async function authorize(c: Context, deps: ApiRouteDeps, operation: Operation) {
+  const workspaceId = await resolveWorkspace(c, deps);
+  const context = await requireAccessContext(c, deps);
+  if (
+    (operation === "workspace-write" || operation === "budget-read") &&
+    !c.req.header("x-opengeni-external-actor") &&
+    !context.subjectId.startsWith("api_key:")
+  ) {
+    // Organization budget management does not require membership in the
+    // target shared workspace. Validate the existing authenticated account
+    // authority on its own anchor, never manufacture a target workspace grant.
+    for (const account of context.accountGrants) {
+      if (account.subjectId !== context.subjectId || !account.permissions.includes("account:admin"))
+        continue;
+      const anchor = context.workspaceGrants.find(
+        (grant) =>
+          grant.accountId === account.accountId &&
+          grant.subjectId === context.subjectId &&
+          grant.principalKind === "human_session" &&
+          !grant.serviceInitiator &&
+          grant.metadata?.sessionId === undefined,
+      );
+      if (!anchor) continue;
+      const stamp = requireAccountAdminAuthorizationStamp(
+        accessGrantAuthorizationFromContext(context, anchor),
+      );
+      const target = await withAccountRls(deps.db, stamp.accountId, (tx) =>
+        getWorkspace(tx, workspaceId),
+      );
+      if (!target || target.accountId !== stamp.accountId) continue;
+      if (target.kind !== "shared") {
+        throw new HTTPException(403, {
+          message: "Organization budgets require a shared workspace",
+        });
+      }
+      return {
+        accountId: stamp.accountId,
+        workspaceId,
+        actorSubjectId: stamp.actorSubjectId,
+        actorType: "human_session" as const,
+      };
+    }
+    // An administrator of another organization may still hold an ordinary
+    // target grant. A budget lookup miss grants nothing and must not mask it.
+  }
+  const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+  requireAllowanceAuthority({ authorization, context }, operation);
+  return {
+    accountId: authorization.grant.accountId,
+    workspaceId,
+    actorSubjectId: authorization.grant.subjectId,
+    actorType: authorization.grant.principalKind ?? "subject",
+  };
+}
+
+function usageQuery(c: Context, own: boolean) {
+  const input = c.req.query();
+  const parsed = parseRequestBody(own ? GetMyUsageRequest : GetUsageRequest, {
+    ...input,
+    ...(input.limit !== undefined ? { limit: Number(input.limit) } : {}),
+  });
+  return {
+    ...(parsed.period === undefined ? {} : { period: parsed.period }),
+    ...("limit" in parsed && parsed.limit !== undefined ? { limit: parsed.limit as number } : {}),
+    ...("cursor" in parsed && parsed.cursor !== undefined
+      ? { cursor: parsed.cursor as string }
+      : {}),
+  };
+}
+
+function requireAllowanceProducersEnabled(deps: ApiRouteDeps): void {
+  if (!deps.settings.usageAllowancesEnabled) {
+    throw new HTTPException(409, {
+      message:
+        "Usage allowance changes are not enabled. Upgrade every API and worker before enabling usage allowances.",
+    });
+  }
+}
+
+/** Map lifecycle refusals without treating a failed CAS as an applied mutation. */
+async function lifecycle<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof UsageAllowanceVersionConflictError)
+      throw new HTTPException(409, { message: error.message });
+    const state = nestedPostgresSqlState(error);
+    if (state === "40001" || state === "23505")
+      throw new HTTPException(409, { message: "Allowance version or operation conflicts" });
+    if (state === "42501")
+      throw new HTTPException(403, { message: "Allowance operation is not authorized" });
+    if (state === "P0002" || state === "23503")
+      throw new HTTPException(404, { message: "Allowance or member not found" });
+    if (state === "22023" || state === "23514")
+      throw new HTTPException(400, { message: "Invalid allowance request" });
+    throw error;
+  }
+}
+
+export function registerUsageAllowanceRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const bases = [
+    "/v1/workspaces/:workspaceId",
+    "/v1/workspaces/external/:workspaceSource/:workspaceExternalId",
+  ];
+  for (const base of bases) {
+    app.get(`${base}/allowance`, async (c) => {
+      const scope = await authorize(c, deps, "budget-read");
+      const result = await getWorkspaceAllowance(deps.db, scope);
+      return c.json(result === null ? null : WorkspaceAllowance.parse(result));
+    });
+    app.get(`${base}/allowance/state`, async (c) => {
+      const scope = await authorize(c, deps, "budget-read");
+      return c.json(
+        WorkspaceAllowanceState.parse(await getWorkspaceAllowanceState(deps.db, scope)),
+      );
+    });
+    app.put(`${base}/allowance`, async (c) => {
+      const scope = await authorize(c, deps, "workspace-write");
+      const request = await parseRequestJson(c, SetWorkspaceAllowanceRequest);
+      requireAllowanceProducersEnabled(deps);
+      return c.json(
+        WorkspaceAllowance.parse(
+          await lifecycle(() =>
+            setWorkspaceAllowance(deps.db, {
+              ...scope,
+              expectedVersion: request.expectedVersion,
+              includedCredits: request.includedCredits,
+              period: request.period,
+              ...(request.anchorDay === undefined ? {} : { anchorDay: request.anchorDay }),
+              ...(request.memberDefault === undefined
+                ? {}
+                : { memberDefault: request.memberDefault }),
+              ...(request.thresholds === undefined
+                ? {}
+                : {
+                    thresholds: {
+                      ...(request.thresholds.workspace === undefined
+                        ? {}
+                        : { workspace: request.thresholds.workspace }),
+                      ...(request.thresholds.member === undefined
+                        ? {}
+                        : { member: request.thresholds.member }),
+                    },
+                  }),
+              ...(request.unbilledUsage === undefined
+                ? {}
+                : { unbilledUsage: request.unbilledUsage }),
+            }),
+          ),
+        ),
+      );
+    });
+    app.delete(`${base}/allowance`, async (c) => {
+      const scope = await authorize(c, deps, "workspace-write");
+      const request = await parseRequestJson(c, ClearWorkspaceAllowanceRequest);
+      return c.json(
+        ClearWorkspaceAllowanceResponse.parse(
+          await lifecycle(() =>
+            clearWorkspaceAllowance(deps.db, {
+              ...scope,
+              expectedVersion: request.expectedVersion,
+              ...(request.operationId === undefined ? {} : { operationId: request.operationId }),
+            }),
+          ),
+        ),
+      );
+    });
+    app.post(`${base}/allowance/grants`, async (c) => {
+      const scope = await authorize(c, deps, "workspace-write");
+      const request = await parseRequestJson(c, GrantWorkspaceCreditsRequest);
+      requireAllowanceProducersEnabled(deps);
+      return c.json(
+        WorkspaceCreditGrant.parse(
+          await lifecycle(() =>
+            grantWorkspaceCredits(deps.db, {
+              ...scope,
+              operationId: request.operationId,
+              credits: request.credits,
+              ...(request.expiresAt === undefined ? {} : { expiresAt: request.expiresAt }),
+            }),
+          ),
+        ),
+      );
+    });
+    for (const memberPath of [
+      "members/:subjectId",
+      "members/external/:memberSource/:memberExternalId",
+    ]) {
+      app.put(`${base}/${memberPath}/allowance`, async (c) => {
+        const scope = await authorize(c, deps, "member-write");
+        const request = await parseRequestJson(c, SetMemberAllowanceRequest);
+        if (request.rule !== null) requireAllowanceProducersEnabled(deps);
+        const subjectId = c.req.param("subjectId");
+        const target = subjectId
+          ? { subjectId }
+          : {
+              externalIdentity: parseRequestBody(ExternalIdentityReference, {
+                source: c.req.param("memberSource"),
+                externalId: c.req.param("memberExternalId"),
+              }),
+            };
+        // Resolve the exact external identity and live member inside the same
+        // protected mutation; never enumerate a roster or provision an identity.
+        return c.json(
+          MemberAllowance.parse(
+            await lifecycle(() => setMemberAllowance(deps.db, { ...scope, ...target, ...request })),
+          ),
+        );
+      });
+    }
+    app.get(`${base}/usage`, async (c) => {
+      const scope = await authorize(c, deps, "read");
+      return c.json(
+        WorkspaceUsageResponse.parse(
+          await getWorkspaceUsage(deps.db, { ...scope, ...usageQuery(c, false) }),
+        ),
+      );
+    });
+    app.get(`${base}/usage/me`, async (c) => {
+      const scope = await authorize(c, deps, "own");
+      const result = WorkspaceUsageResponse.parse(
+        await getWorkspaceUsage(deps.db, {
+          ...scope,
+          ...usageQuery(c, true),
+          subjectId: scope.actorSubjectId,
+        }),
+      );
+      // Defense in depth: the own endpoint never serializes another member or a
+      // roster cursor even if the storage adapter returns an overbroad page.
+      return c.json({
+        ...result,
+        members: result.members.filter((member) => member.subjectId === scope.actorSubjectId),
+        nextCursor: null,
+      });
+    });
+  }
+}

package/src/routes/variable-sets-removed.ts

@@ -0,0 +1,19 @@
+import type { Hono } from "hono";
+import { variableSetsRemovedResponse } from "../http/variable-sets-removed";
+
+/**
+ * Variable Sets were replaced by vaults (RM-1). Every legacy route, including
+ * the deprecated `/environments` alias, answers 410 `variable_sets_removed`
+ * with a pointer to `/vaults`. No grant is checked: the answer reveals nothing.
+ */
+const LEGACY_PREFIXES = [
+  "/v1/workspaces/:workspaceId/variable-sets",
+  "/v1/workspaces/:workspaceId/environments",
+] as const;
+
+export function registerVariableSetsRemovedRoutes(app: Hono): void {
+  for (const prefix of LEGACY_PREFIXES) {
+    app.all(prefix, (c) => variableSetsRemovedResponse(c, 410));
+    app.all(`${prefix}/*`, (c) => variableSetsRemovedResponse(c, 410));
+  }
+}