@read-frog/api-contract 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/public-errors.ts

@@ -1,6 +1,10 @@
 import type { ErrorMap } from "@orpc/contract";
 import { z } from "zod";
-import { HostedAiCreditPolicyIdSchema, HostedAiModelTierSchema } from "./schemas/hosted-ai";
+import {
+  HostedAiCreditPolicyIdSchema,
+  HostedAiModelTierSchema,
+  HostedAiUpgradePlanSchema,
+} from "./schemas/hosted-ai";
 
 interface PublicAppErrorDefinition {
   data?: z.ZodTypeAny;
@@ -74,6 +78,8 @@ export type CardTemplateNotebaseColumnInUseData = z.infer<
 
 export const HostedAiTierRestrictedDataSchema = z.strictObject({
   modelTier: HostedAiModelTierSchema,
+  /** The cheapest plan that unlocks it; a client offers "Pro or Ultra" for `pro`. */
+  upgradeTo: HostedAiUpgradePlanSchema,
 });
 
 export const HostedAiQuotaExhaustedDataSchema = z.strictObject({

package/src/schemas/hosted-ai.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { billingPlanSchema } from "./billing";
 
 export const HostedAiOutputFieldTypeSchema = z.enum(["string", "number"]);
 
@@ -159,13 +160,25 @@ export const HOSTED_AI_CLIENT_STREAM_PART_TYPES = [
  */
 export const HostedAiStatusInputSchema = z.object({});
 
+/**
+ * `pro_required` means the Pro plan or any plan above it; `ultra_required`
+ * means Ultra. Appended last, so a client that predates a value falls back on
+ * its own default instead of misreading it.
+ */
 export const HostedAiUnavailableReasonSchema = z.enum([
   "authentication_required",
   "ultra_required",
   "quota_exhausted",
   "service_unavailable",
+  "pro_required",
 ]);
 
+/**
+ * The cheapest plan an account would need to buy for something it cannot use
+ * now. Any plan above it works too, so `pro` reads as "Pro or Ultra".
+ */
+export const HostedAiUpgradePlanSchema = billingPlanSchema.exclude(["free"]);
+
 export const HostedAiCreditPolicyIdSchema = z.enum([
   "custom-action-guest-daily-v1",
   "custom-action-user-daily-v1",
@@ -246,10 +259,18 @@ export const HostedAiTierStatusSchema = z.strictObject({
   available: z.boolean(),
   unavailableReason: HostedAiUnavailableReasonSchema.nullable(),
   /**
-   * Viewer-independent product fact: no non-Ultra account can ever use this
-   * feature/tier, so signing in alone will not unlock it. Unlike the fields
-   * above, this does not vary with the caller's identity or plan — clients use
-   * it to label Ultra-only options rather than to gate the current user.
+   * The cheapest plan this account would need to use the tier, or null when it
+   * needs none: its plan or a one-time pool already covers it, or the tier is
+   * open to every signed-in account. For a guest it is the plan needed after
+   * signing in. Clients badge an option with it and offer that plan.
+   */
+  upgradeTo: HostedAiUpgradePlanSchema.nullable(),
+  /**
+   * @deprecated Read `upgradeTo`. Viewer-independent product fact: no
+   * non-Ultra account can ever use this feature/tier. Extensions released
+   * before `upgradeTo` badge options with it, including for Ultra accounts.
+   *
+   * TODO(2026-11-21): remove once those extensions have drained (#710).
    */
   requiresUltra: z.boolean(),
   modelRevision: z.string().trim().min(1),
@@ -302,6 +323,7 @@ export type HostedAiNoteSuggestionObject = z.infer<typeof HostedAiNoteSuggestion
 export type HostedAiStreamPart = z.infer<typeof HostedAiStreamPartSchema>;
 export type HostedAiStatusInput = z.infer<typeof HostedAiStatusInputSchema>;
 export type HostedAiUnavailableReason = z.infer<typeof HostedAiUnavailableReasonSchema>;
+export type HostedAiUpgradePlan = z.infer<typeof HostedAiUpgradePlanSchema>;
 export type HostedAiCreditPolicyId = z.infer<typeof HostedAiCreditPolicyIdSchema>;
 export type HostedAiCreditPeriodKind = z.infer<typeof HostedAiCreditPeriodKindSchema>;
 export type HostedAiQuotaScope = z.infer<typeof HostedAiQuotaScopeSchema>;