@read-frog/api-contract 0.12.1 → 0.12.3

package/src/contracts/hosted-ai.ts

@@ -1,12 +1,29 @@
 import { eventIterator, oc } from "@orpc/contract"
+import { pickPublicErrorMap } from "#/public-errors"
 import {
   HostedAiNoteSuggestionStreamInputSchema,
+  HostedAiStatusInputSchema,
+  HostedAiStatusOutputSchema,
   HostedAiStreamPartSchema,
   HostedAiStreamStructuredObjectInputSchema,
   HostedAiStreamTextInputSchema,
 } from "#/schemas/hosted-ai"
 
+const hostedAiStreamErrors = pickPublicErrorMap(
+  "HOSTED_AI_TIER_RESTRICTED",
+  "HOSTED_AI_QUOTA_EXHAUSTED",
+)
+
 export const hostedAiContract = {
+  status: oc
+    .route({
+      method: "GET",
+      path: "/hosted-ai/status",
+      summary: "Get Built-in AI availability and quota status",
+      tags: ["Hosted AI"],
+    })
+    .input(HostedAiStatusInputSchema)
+    .output(HostedAiStatusOutputSchema),
   translate: {
     streamText: oc
       .route({
@@ -16,7 +33,8 @@ export const hostedAiContract = {
         tags: ["Hosted AI"],
       })
       .input(HostedAiStreamTextInputSchema)
-      .output(eventIterator(HostedAiStreamPartSchema)),
+      .output(eventIterator(HostedAiStreamPartSchema))
+      .errors(hostedAiStreamErrors),
   },
   customAction: {
     streamStructuredObject: oc
@@ -27,7 +45,8 @@ export const hostedAiContract = {
         tags: ["Hosted AI"],
       })
       .input(HostedAiStreamStructuredObjectInputSchema)
-      .output(eventIterator(HostedAiStreamPartSchema)),
+      .output(eventIterator(HostedAiStreamPartSchema))
+      .errors(hostedAiStreamErrors),
   },
   noteSuggestion: {
     streamStructuredObject: oc
@@ -38,6 +57,7 @@ export const hostedAiContract = {
         tags: ["Hosted AI"],
       })
       .input(HostedAiNoteSuggestionStreamInputSchema)
-      .output(eventIterator(HostedAiStreamPartSchema)),
+      .output(eventIterator(HostedAiStreamPartSchema))
+      .errors(hostedAiStreamErrors),
   },
 }

package/src/contracts/srs.ts

@@ -1,5 +1,7 @@
 import { pickPublicErrorMap } from "#/public-errors"
 import {
+  srsListCardRevlogsInputSchema,
+  srsListCardRevlogsOutputSchema,
   srsReviewInputSchema,
   srsReviewOutputSchema,
   srsRollbackReviewInputSchema,
@@ -25,6 +27,17 @@ export const srsContract = {
     .input(srsScheduleStatusStatsInputSchema)
     .output(srsScheduleStatusStatsOutputSchema),
 
+  listCardRevlogs: notebaseProcedure
+    .errors(pickPublicErrorMap("CARD_NOT_FOUND"))
+    .route({
+      method: "GET",
+      path: "/srs/cards/{cardId}/revlogs",
+      summary: "List complete review history for a card",
+      tags: ["SRS"],
+    })
+    .input(srsListCardRevlogsInputSchema)
+    .output(srsListCardRevlogsOutputSchema),
+
   review: notebaseProcedure
     .errors(pickPublicErrorMap(
       "CARD_NOT_FOUND",

package/src/contracts/stats.ts

@@ -0,0 +1,42 @@
+import { pickPublicErrorMap } from "#/public-errors"
+import { notebaseRowGrowthStatsOutputSchema } from "#/schemas/notebase-stats"
+import {
+  srsMemoryGrowthStatsOutputSchema,
+} from "#/schemas/srs-stats"
+import { activityStatsOutputSchema, statsInputSchema } from "#/schemas/stats"
+import { notebaseProcedure } from "./shared"
+
+export const statsContract = {
+  activity: notebaseProcedure
+    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
+    .route({
+      method: "GET",
+      path: "/stats/activity",
+      summary: "Get SRS and notebase activity statistics",
+      tags: ["Statistics"],
+    })
+    .input(statsInputSchema)
+    .output(activityStatsOutputSchema),
+
+  srsMemoryGrowth: notebaseProcedure
+    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
+    .route({
+      method: "GET",
+      path: "/srs/stats/memory-growth",
+      summary: "Get SRS long-term memory growth statistics",
+      tags: ["Statistics"],
+    })
+    .input(statsInputSchema)
+    .output(srsMemoryGrowthStatsOutputSchema),
+
+  notebaseRowGrowth: notebaseProcedure
+    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
+    .route({
+      method: "GET",
+      path: "/notebases/stats/row-growth",
+      summary: "Get notebase row growth statistics",
+      tags: ["Statistics"],
+    })
+    .input(statsInputSchema)
+    .output(notebaseRowGrowthStatsOutputSchema),
+}

package/src/index.ts

@@ -9,6 +9,7 @@ import { notebaseContract } from "./contracts/notebase"
 import { notebaseColumnContract } from "./contracts/notebase-column"
 import { notebaseRowContract } from "./contracts/notebase-row"
 import { srsContract } from "./contracts/srs"
+import { statsContract } from "./contracts/stats"
 import { userContract } from "./contracts/user"
 import { videoTranscriptContract } from "./contracts/video-transcript"
 
@@ -23,6 +24,7 @@ export const contract = {
   notebaseColumn: notebaseColumnContract,
   notebaseRow: notebaseRowContract,
   srs: srsContract,
+  stats: statsContract,
   user: userContract,
   videoTranscript: videoTranscriptContract,
 }
@@ -38,8 +40,11 @@ export * from "./schemas/hosted-ai"
 export * from "./schemas/notebase"
 export * from "./schemas/notebase-column"
 export * from "./schemas/notebase-row"
+export * from "./schemas/notebase-stats"
 export * from "./schemas/notebase-view"
 export * from "./schemas/srs"
+export * from "./schemas/srs-stats"
+export * from "./schemas/stats"
 export * from "./schemas/timezone"
 export * from "./schemas/user"
 export * from "./schemas/video-transcript"

package/src/public-errors.ts

@@ -1,5 +1,6 @@
 import type { ErrorMap } from "@orpc/contract"
 import { z } from "zod"
+import { HostedAiCreditPolicyIdSchema, HostedAiModelTierSchema } from "./schemas/hosted-ai"
 
 interface PublicAppErrorDefinition {
   data?: z.ZodTypeAny
@@ -38,7 +39,32 @@ export const CardTemplateInvalidColumnsDataSchema = z.object({
 }).strict()
 export type CardTemplateInvalidColumnsData = z.infer<typeof CardTemplateInvalidColumnsDataSchema>
 
+export const HostedAiTierRestrictedDataSchema = z.strictObject({
+  modelTier: HostedAiModelTierSchema,
+})
+
+export const HostedAiQuotaExhaustedDataSchema = z.strictObject({
+  modelTier: HostedAiModelTierSchema,
+  // Reuses the credit-status enum rather than restating it: these two always
+  // describe the same set of policy ids, and a second copy silently drifts —
+  // the error payload is `strictObject`, so a policy missing only here fails
+  // output validation at exactly the moment a user runs out of credit.
+  policyId: HostedAiCreditPolicyIdSchema,
+  usedPercent: z.number().min(0).max(100),
+  resetAt: z.iso.datetime().nullable(),
+})
+
 export const PUBLIC_APP_ERROR_DEFS = {
+  HOSTED_AI_TIER_RESTRICTED: {
+    data: HostedAiTierRestrictedDataSchema,
+    message: "This Built-in AI tier is not available for this account",
+    status: 403,
+  },
+  HOSTED_AI_QUOTA_EXHAUSTED: {
+    data: HostedAiQuotaExhaustedDataSchema,
+    message: "Built-in AI credit exhausted",
+    status: 429,
+  },
   NOTEBASE_BETA_RESTRICTED: {
     message: "Notebase is currently in beta for selected accounts",
     status: 403,

package/src/schemas/hosted-ai.ts

@@ -1,8 +1,5 @@
-import type { RefinementCtx } from "zod"
 import { z } from "zod"
 
-const HOSTED_AI_SYSTEM_FALLBACK_REMOVAL_DATE = "2026-07-11"
-
 export const HostedAiOutputFieldTypeSchema = z.enum(["string", "number"])
 
 export const HostedAiOutputFieldSchema = z.strictObject({
@@ -12,42 +9,43 @@ export const HostedAiOutputFieldSchema = z.strictObject({
 
 const HostedAiInstructionsSchema = z.string().trim().min(1).max(16000)
 
-interface HostedAiInstructionsCompatibilityInput {
-  instructions?: string
-  system?: string
-}
-
-function validateHostedAiInstructionsCompatibility(
-  input: HostedAiInstructionsCompatibilityInput,
-  ctx: RefinementCtx<HostedAiInstructionsCompatibilityInput>,
-): void {
-  if (input.instructions !== undefined || input.system !== undefined) {
-    return
-  }
-
-  ctx.addIssue({
-    code: "custom",
-    message: `instructions is required. The deprecated system field is accepted as a temporary fallback until ${HOSTED_AI_SYSTEM_FALLBACK_REMOVAL_DATE}.`,
-    path: ["instructions"],
-  })
+export const HostedAiModelTierSchema = z.enum(["normal", "ultra"])
+export const HostedAiFeatureSchema = z.enum([
+  "pageTranslation",
+  "customAction",
+  "noteSuggestion",
+])
+export const HostedAiRequestIdSchema = z.uuid()
+
+const HostedAiRequestMetadataSchema = {
+  /**
+   * Optional on the wire, always present after parsing: these endpoints shipped
+   * before tiers existed, so every installed extension below 1.55.0 sends no
+   * `modelTier` at all, and the input objects are strict. Defaulting here keeps
+   * those clients working while giving handlers a single source of truth
+   * instead of a `?? "normal"` at every call site.
+   *
+   * TODO(2026-11-01): Drop the default and make this required once extensions
+   * below 1.55.0 have drained from the store.
+   */
+  modelTier: HostedAiModelTierSchema.default("normal"),
+  requestId: HostedAiRequestIdSchema.optional(),
 }
 
 export const HostedAiStreamTextInputSchema = z.strictObject({
-  instructions: HostedAiInstructionsSchema.optional(),
-  system: HostedAiInstructionsSchema.optional(),
+  ...HostedAiRequestMetadataSchema,
+  instructions: HostedAiInstructionsSchema,
   prompt: z.string().trim().min(1).max(32000),
   temperature: z.number().min(0).max(2).optional(),
-}).superRefine(validateHostedAiInstructionsCompatibility)
+})
 
 export const HostedAiStreamStructuredObjectInputSchema = z.strictObject({
-  instructions: HostedAiInstructionsSchema.optional(),
-  system: HostedAiInstructionsSchema.optional(),
+  ...HostedAiRequestMetadataSchema,
+  instructions: HostedAiInstructionsSchema,
   prompt: z.string().trim().min(1).max(32000),
   outputSchema: z.array(HostedAiOutputFieldSchema).min(1).max(32),
   temperature: z.number().min(0).max(2).optional(),
 }).superRefine((input, ctx) => {
-  validateHostedAiInstructionsCompatibility(input, ctx)
-
   const fieldNames = new Set<string>()
 
   input.outputSchema.forEach((field, index) => {
@@ -68,6 +66,7 @@ export const HOSTED_AI_NOTE_SUGGESTION_MAX_NOTES = 2
 export const HOSTED_AI_NOTE_SUGGESTION_MAX_NOTE_FIELDS = 16
 
 export const HostedAiNoteSuggestionStreamInputSchema = z.strictObject({
+  ...HostedAiRequestMetadataSchema,
   instructions: HostedAiInstructionsSchema,
   prompt: z.string().trim().min(1).max(32000),
   temperature: z.number().min(0).max(2).optional(),
@@ -109,10 +108,126 @@ export const HostedAiStreamPartSchema = z.looseObject({
   type: z.string().trim().min(1),
 })
 
+/**
+ * The only stream part types this API emits. Every other part the AI SDK
+ * produces (`start-step`, `finish-step`, `text-start`, ...) carries upstream
+ * metadata — provider model id, response headers, request body — and is dropped
+ * server-side so it never reaches a client.
+ *
+ * The consumer switch lives in the extension's background stream reader. Adding
+ * a type here without teaching that switch about it is a no-op; removing one
+ * breaks rendering. `error` is absent on purpose: it is converted into a thrown
+ * error before it can be yielded.
+ */
+export const HOSTED_AI_CLIENT_STREAM_PART_TYPES = [
+  "text-delta",
+  "reasoning-start",
+  "reasoning-delta",
+  "reasoning-end",
+  "reasoning-file",
+  "finish",
+] as const
+
+/**
+ * Status is per-identity, not per-feature: one call reports every feature and
+ * every pool, so a client caches a single response instead of one per feature.
+ * Non-strict so a client still sending the retired `feature` argument gets a
+ * useful response rather than a validation error.
+ */
+export const HostedAiStatusInputSchema = z.object({})
+
+export const HostedAiUnavailableReasonSchema = z.enum([
+  "authentication_required",
+  "ultra_required",
+  "quota_exhausted",
+  "service_unavailable",
+])
+
+export const HostedAiCreditPolicyIdSchema = z.enum([
+  "custom-action-guest-daily-v1",
+  "custom-action-user-daily-v1",
+  "custom-action-pro-daily-v1",
+  "ultra-weekly-v1",
+])
+
+export const HostedAiCreditPeriodKindSchema = z.enum(["daily", "weekly"])
+
+export const HostedAiQuotaScopeSchema = z.enum(["guest", "user"])
+
+/**
+ * Data payload of the TOO_MANY_REQUESTS error every hosted AI guard emits.
+ * The code itself is ORPC's own rather than a PUBLIC_APP_ERROR_DEFS entry, so
+ * this schema is the only contract tying the server's construction to the
+ * extension's parsing of it.
+ */
+export const HostedAiRateLimitErrorDataSchema = z.strictObject({
+  retryAfterMs: z.number().int().min(0),
+  quotaScope: HostedAiQuotaScopeSchema,
+})
+
+/**
+ * Deliberately free of dollar amounts and of the versioned policy id. Clients
+ * render a consumption bar and a reset time, so a percentage and a period kind
+ * are all they need, and neither leaks what a call costs us. `usedPercent`
+ * counts settled spend only: including in-flight reservations would make the
+ * bar jump forward and then back as each stream settles.
+ */
+export const HostedAiCreditStatusSchema = z.strictObject({
+  periodKind: HostedAiCreditPeriodKindSchema,
+  usedPercent: z.number().min(0).max(100),
+  resetAt: z.iso.datetime().nullable(),
+  /**
+   * Every feature drawing on this pool. Ultra shares one weekly pool across all
+   * three, so the grouping lives here rather than inlined per feature — that way
+   * a client can tell one shared pool from several separate ones.
+   */
+  features: z.array(HostedAiFeatureSchema).min(1),
+})
+
+export const HostedAiTierStatusSchema = z.strictObject({
+  accessAllowed: z.boolean(),
+  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.
+   */
+  requiresUltra: z.boolean(),
+  modelRevision: z.string().trim().min(1),
+})
+
+export const HostedAiFeatureStatusSchema = z.strictObject({
+  normal: HostedAiTierStatusSchema,
+  ultra: HostedAiTierStatusSchema,
+})
+
+export const HostedAiStatusOutputSchema = z.strictObject({
+  credits: z.array(HostedAiCreditStatusSchema),
+  features: z.strictObject({
+    pageTranslation: HostedAiFeatureStatusSchema,
+    customAction: HostedAiFeatureStatusSchema,
+    noteSuggestion: HostedAiFeatureStatusSchema,
+  }),
+})
+
 export type HostedAiOutputFieldType = z.infer<typeof HostedAiOutputFieldTypeSchema>
 export type HostedAiOutputField = z.infer<typeof HostedAiOutputFieldSchema>
+export type HostedAiModelTier = z.infer<typeof HostedAiModelTierSchema>
+export type HostedAiFeature = z.infer<typeof HostedAiFeatureSchema>
 export type HostedAiStreamTextInput = z.infer<typeof HostedAiStreamTextInputSchema>
 export type HostedAiStreamStructuredObjectInput = z.infer<typeof HostedAiStreamStructuredObjectInputSchema>
 export type HostedAiNoteSuggestionStreamInput = z.infer<typeof HostedAiNoteSuggestionStreamInputSchema>
 export type HostedAiNoteSuggestionObject = z.infer<typeof HostedAiNoteSuggestionObjectSchema>
 export type HostedAiStreamPart = z.infer<typeof HostedAiStreamPartSchema>
+export type HostedAiStatusInput = z.infer<typeof HostedAiStatusInputSchema>
+export type HostedAiUnavailableReason = z.infer<typeof HostedAiUnavailableReasonSchema>
+export type HostedAiCreditPolicyId = z.infer<typeof HostedAiCreditPolicyIdSchema>
+export type HostedAiCreditPeriodKind = z.infer<typeof HostedAiCreditPeriodKindSchema>
+export type HostedAiQuotaScope = z.infer<typeof HostedAiQuotaScopeSchema>
+export type HostedAiRateLimitErrorData = z.infer<typeof HostedAiRateLimitErrorDataSchema>
+export type HostedAiCreditStatus = z.infer<typeof HostedAiCreditStatusSchema>
+export type HostedAiTierStatus = z.infer<typeof HostedAiTierStatusSchema>
+export type HostedAiFeatureStatus = z.infer<typeof HostedAiFeatureStatusSchema>
+export type HostedAiStatusOutput = z.infer<typeof HostedAiStatusOutputSchema>

package/src/schemas/notebase-column.ts

@@ -11,6 +11,7 @@ export const notebaseColumnSchema = z.object({
   position: z.number(),
   isPrimary: z.boolean(),
   width: z.number().nullable(),
+  wrap: z.boolean(),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
 })
@@ -27,6 +28,7 @@ export const notebaseColumnUpdateDataSchema = z.object({
   name: z.string().min(1).optional(),
   config: notebaseColumnConfigSchema.optional(),
   width: notebaseColumnWidthSchema.nullable().optional(),
+  wrap: z.boolean().optional(),
 }).strict()
 export type NotebaseColumnUpdateData = z.infer<typeof notebaseColumnUpdateDataSchema>
 

package/src/schemas/notebase-stats.ts

@@ -0,0 +1,24 @@
+import { z } from "zod"
+
+export const notebaseActivityStatsItemSchema = z.object({
+  date: z.iso.date(),
+  notes: z.number().int().nonnegative(),
+}).strict()
+export type NotebaseActivityStatsItem = z.infer<typeof notebaseActivityStatsItemSchema>
+
+export const notebaseActivityStatsOutputSchema = z.object({
+  daily: z.array(notebaseActivityStatsItemSchema),
+}).strict()
+export type NotebaseActivityStatsOutput = z.infer<typeof notebaseActivityStatsOutputSchema>
+
+export const notebaseRowGrowthStatsItemSchema = z.object({
+  date: z.iso.date(),
+  delta: z.number().int(),
+}).strict()
+export type NotebaseRowGrowthStatsItem = z.infer<typeof notebaseRowGrowthStatsItemSchema>
+
+export const notebaseRowGrowthStatsOutputSchema = z.object({
+  baseTotal: z.number().int().nonnegative(),
+  daily: z.array(notebaseRowGrowthStatsItemSchema),
+}).strict()
+export type NotebaseRowGrowthStatsOutput = z.infer<typeof notebaseRowGrowthStatsOutputSchema>

package/src/schemas/srs-stats.ts

@@ -0,0 +1,26 @@
+import { z } from "zod"
+
+export const srsActivityStatsItemSchema = z.object({
+  date: z.iso.date(),
+  answers: z.number().int().nonnegative(),
+  durationMs: z.number().int().nonnegative(),
+}).strict()
+export type SrsActivityStatsItem = z.infer<typeof srsActivityStatsItemSchema>
+
+export const srsActivityStatsOutputSchema = z.object({
+  learnedCards: z.number().int().nonnegative(),
+  daily: z.array(srsActivityStatsItemSchema),
+}).strict()
+export type SrsActivityStatsOutput = z.infer<typeof srsActivityStatsOutputSchema>
+
+export const srsMemoryGrowthStatsItemSchema = z.object({
+  date: z.iso.date(),
+  delta: z.number().int(),
+}).strict()
+export type SrsMemoryGrowthStatsItem = z.infer<typeof srsMemoryGrowthStatsItemSchema>
+
+export const srsMemoryGrowthStatsOutputSchema = z.object({
+  baseTotal: z.number().int().nonnegative(),
+  daily: z.array(srsMemoryGrowthStatsItemSchema),
+}).strict()
+export type SrsMemoryGrowthStatsOutput = z.infer<typeof srsMemoryGrowthStatsOutputSchema>

package/src/schemas/srs.ts

@@ -90,7 +90,9 @@ export const srsRevlogSchema = z.object({
   cardId: z.uuid(),
   rating: reviewRatingSchema,
   state: cardStateSchema,
+  stability: z.number(),
   afterScheduleStatus: scheduleStatusSchema,
+  afterStability: z.number(),
   reviewedAt: z.coerce.date(),
   durationMs: z.number().int(),
   fsrsReviewLogSnapshot: fsrsReviewLogSnapshotSchema,
@@ -103,6 +105,16 @@ export const srsRevlogWithoutSnapshotSchema = srsRevlogSchema.omit({
 })
 export type SrsRevlogWithoutSnapshot = z.infer<typeof srsRevlogWithoutSnapshotSchema>
 
+export const srsListCardRevlogsInputSchema = z.object({
+  cardId: z.uuid(),
+}).strict()
+export type SrsListCardRevlogsInput = z.infer<typeof srsListCardRevlogsInputSchema>
+
+export const srsListCardRevlogsOutputSchema = z.object({
+  items: z.array(srsRevlogWithoutSnapshotSchema),
+}).strict()
+export type SrsListCardRevlogsOutput = z.infer<typeof srsListCardRevlogsOutputSchema>
+
 export const srsReviewOutputSchema = z.object({
   card: cardSchema,
   revlog: srsRevlogSchema,

package/src/schemas/stats.ts

@@ -0,0 +1,25 @@
+import { z } from "zod"
+import { notebaseActivityStatsOutputSchema } from "./notebase-stats"
+import { srsActivityStatsOutputSchema } from "./srs-stats"
+import { timezoneSchema } from "./timezone"
+
+const statsNotebaseIdsSchema = z.array(z.uuid())
+  .min(1)
+  .transform(ids => Array.from(new Set(ids)))
+
+export const statsInputSchema = z.object({
+  notebaseIds: statsNotebaseIdsSchema.optional(),
+  from: z.iso.date().optional(),
+  to: z.iso.date(),
+  timezone: timezoneSchema,
+}).strict().refine(input => !input.from || input.from <= input.to, {
+  message: "from must be before or equal to to",
+  path: ["from"],
+})
+export type StatsInput = z.infer<typeof statsInputSchema>
+
+export const activityStatsOutputSchema = z.object({
+  srs: srsActivityStatsOutputSchema,
+  notebase: notebaseActivityStatsOutputSchema,
+}).strict()
+export type ActivityStatsOutput = z.infer<typeof activityStatsOutputSchema>