@read-frog/api-contract 0.12.5 → 0.14.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@read-frog/api-contract",
   "type": "module",
-  "version": "0.12.5",
+  "version": "0.14.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/contracts/hosted-ai.ts

@@ -48,6 +48,64 @@ export const hostedAiContract = {
       .output(eventIterator(HostedAiStreamPartSchema))
       .errors(hostedAiStreamErrors),
   },
+  videoSubtitles: {
+    // Subtitle lines and the video summary share this route: both are short
+    // text and both bill against `videoSubtitles`.
+    streamText: oc
+      .route({
+        method: "POST",
+        path: "/hosted-ai/video-subtitles/stream-text",
+        summary: "Stream hosted subtitle translation or video summary text output",
+        tags: ["Hosted AI"],
+      })
+      .input(HostedAiStreamTextInputSchema)
+      .output(eventIterator(HostedAiStreamPartSchema))
+      .errors(hostedAiStreamErrors),
+    /**
+     * Segmentation shares the `videoSubtitles` feature but not its route,
+     * because `endpointMaxOutputTokens` sizes the credit reservation: emitting
+     * a WebVTT block needs several times a subtitle line's budget, and folding
+     * both into one route would make every line reserve — and, near the end of
+     * a credit window, fail to afford — what only segmentation needs.
+     */
+    streamSegmentation: oc
+      .route({
+        method: "POST",
+        path: "/hosted-ai/video-subtitles/stream-segmentation",
+        summary: "Stream hosted subtitle segmentation output",
+        tags: ["Hosted AI"],
+      })
+      .input(HostedAiStreamTextInputSchema)
+      .output(eventIterator(HostedAiStreamPartSchema))
+      .errors(hostedAiStreamErrors),
+  },
+  inputTranslation: {
+    streamText: oc
+      .route({
+        method: "POST",
+        path: "/hosted-ai/input-translation/stream-text",
+        summary: "Stream hosted input box translation text output",
+        tags: ["Hosted AI"],
+      })
+      .input(HostedAiStreamTextInputSchema)
+      .output(eventIterator(HostedAiStreamPartSchema))
+      .errors(hostedAiStreamErrors),
+  },
+  languageDetection: {
+    // Detection wants one short string back, not a stream, but the quota
+    // reserve/settle path is stream-shaped end to end. Reusing it keeps one
+    // metering implementation; the client collects the deltas.
+    streamText: oc
+      .route({
+        method: "POST",
+        path: "/hosted-ai/language-detection/stream-text",
+        summary: "Stream hosted language detection output",
+        tags: ["Hosted AI"],
+      })
+      .input(HostedAiStreamTextInputSchema)
+      .output(eventIterator(HostedAiStreamPartSchema))
+      .errors(hostedAiStreamErrors),
+  },
   customAction: {
     streamStructuredObject: oc
       .route({

package/src/contracts/video-transcript.ts

@@ -10,7 +10,12 @@ import {
 
 export const videoTranscriptContract = {
   create: oc
-    .errors(pickPublicErrorMap("VIDEO_TRANSCRIPTION_QUOTA_EXCEEDED"))
+    .errors(pickPublicErrorMap(
+      "VIDEO_TRANSCRIPTION_QUOTA_EXCEEDED",
+      "VIDEO_TRANSCRIPTION_SUBSCRIPTION_REQUIRED",
+      "VIDEO_TRANSCRIPTION_PAYMENT_REQUIRED",
+      "VIDEO_TRANSCRIPTION_UNSUPPORTED_LENGTH",
+    ))
     .route({
       method: "POST",
       path: "/video-transcripts",
@@ -28,7 +33,7 @@ export const videoTranscriptContract = {
     })
     .output(videoTranscriptUsageSchema),
   get: oc
-    .errors(pickPublicErrorMap("VIDEO_TRANSCRIPT_NOT_FOUND"))
+    .errors(pickPublicErrorMap("VIDEO_TRANSCRIPT_NOT_FOUND", "VIDEO_TRANSCRIPTION_SUBSCRIPTION_REQUIRED"))
     .route({
       method: "GET",
       path: "/video-transcripts/{id}",
@@ -38,7 +43,7 @@ export const videoTranscriptContract = {
     .input(videoTranscriptGetInputSchema)
     .output(videoTranscriptResourceSchema),
   getSubtitles: oc
-    .errors(pickPublicErrorMap("VIDEO_TRANSCRIPT_NOT_FOUND", "VIDEO_TRANSCRIPT_NOT_READY"))
+    .errors(pickPublicErrorMap("VIDEO_TRANSCRIPT_NOT_FOUND", "VIDEO_TRANSCRIPT_NOT_READY", "VIDEO_TRANSCRIPTION_SUBSCRIPTION_REQUIRED"))
     .route({
       method: "GET",
       path: "/video-transcripts/{id}/subtitles",

package/src/public-errors.ts

@@ -73,10 +73,26 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Notebase not found",
     status: 404,
   },
+  // Retired at launch (2026-08-14) but kept defined for one release so old
+  // clients' error maps keep parsing; the server no longer emits it. Remove
+  // together with the beta feature key in the follow-up cleanup.
   VIDEO_TRANSCRIPTION_BETA_RESTRICTED: {
     message: "Video transcription is currently in beta for selected accounts",
     status: 403,
   },
+  VIDEO_TRANSCRIPTION_SUBSCRIPTION_REQUIRED: {
+    message: "AI subtitles require a Pro or Ultra subscription",
+    status: 403,
+  },
+  // Dunning (`past_due` / `paused`), not cancellation: the account keeps
+  // reading subtitles it already paid to generate, but cannot start new work
+  // that spends upstream money until the payment method is fixed. Distinct
+  // from SUBSCRIPTION_REQUIRED so the client can say "update your card"
+  // instead of "subscribe".
+  VIDEO_TRANSCRIPTION_PAYMENT_REQUIRED: {
+    message: "Update your payment method to generate new AI subtitles",
+    status: 402,
+  },
   VIDEO_TRANSCRIPT_NOT_FOUND: {
     message: "Video transcript not found",
     status: 404,
@@ -89,6 +105,13 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Monthly transcription quota exceeded",
     status: 429,
   },
+  // A property of the video, not of the account: upgrading or waiting for the
+  // quota to reset changes nothing. Kept apart from QUOTA_EXCEEDED so the
+  // client does not answer it with an upgrade wall.
+  VIDEO_TRANSCRIPTION_UNSUPPORTED_LENGTH: {
+    message: "This video is longer than AI subtitles support",
+    status: 422,
+  },
   NOTEBASE_COLUMN_NOT_FOUND: {
     message: "Notebase column not found",
     status: 404,

package/src/schemas/billing.ts

@@ -53,7 +53,13 @@ export const billingStatusSchema = z.object({
   status: billingSubscriptionStatusSchema.nullable(),
   interval: billingIntervalSchema.nullable(),
   currentPeriodEnd: z.coerce.date().nullable(),
-  cancelAtPeriodEnd: z.boolean(),
+  /**
+   * When the subscription terminates, or null if it renews. Replaces the
+   * `cancelAtPeriodEnd` boolean: Stripe deprecated its counterpart and the
+   * Customer Portal no longer sets it, and the termination date is not always
+   * `currentPeriodEnd` — a stacked pass pushes that past the cancellation.
+   */
+  cancelAt: z.coerce.date().nullable(),
   accessSource: billingAccessSourceSchema.nullable(),
   scheduledChange: billingScheduledChangeSchema.nullable(),
   unlimitedNotebaseNotes: z.boolean(),

package/src/schemas/hosted-ai.ts

@@ -9,14 +9,28 @@ export const HostedAiOutputFieldSchema = z.strictObject({
 
 const HostedAiInstructionsSchema = z.string().trim().min(1).max(16000)
 
-export const HostedAiModelTierSchema = z.enum(["normal", "ultra"])
+/**
+ * Which hosted model a request runs on. Deliberately NOT named after a billing
+ * plan: which plans may reach which tier is policy (see `access-policy.ts`),
+ * not identity, so a future plan can be sold with any tier without a rename.
+ */
+export const HostedAiModelTierSchema = z.enum(["normal", "advance"])
+/**
+ * The billing/access subject of a hosted request, not a route id. Sub-calls
+ * bill against the feature they serve: the page summary is `pageTranslation`,
+ * and the video summary and subtitle segmentation are `videoSubtitles`.
+ *
+ * Appended last on purpose: the db pgEnum mirrors this order, and appending
+ * keeps drizzle from emitting the ADD VALUE ... BEFORE variant.
+ */
 export const HostedAiFeatureSchema = z.enum([
   "pageTranslation",
   "customAction",
   "noteSuggestion",
-  // Appended last on purpose: the db pgEnum mirrors this order, and appending
-  // keeps drizzle from emitting the ADD VALUE ... BEFORE variant.
   "selectionTranslation",
+  "videoSubtitles",
+  "inputTranslation",
+  "languageDetection",
 ])
 export const HostedAiRequestIdSchema = z.uuid()
 
@@ -210,7 +224,7 @@ export const HostedAiTierStatusSchema = z.strictObject({
 
 export const HostedAiFeatureStatusSchema = z.strictObject({
   normal: HostedAiTierStatusSchema,
-  ultra: HostedAiTierStatusSchema,
+  advance: HostedAiTierStatusSchema,
 })
 
 export const HostedAiStatusOutputSchema = z.strictObject({
@@ -220,6 +234,9 @@ export const HostedAiStatusOutputSchema = z.strictObject({
     customAction: HostedAiFeatureStatusSchema,
     noteSuggestion: HostedAiFeatureStatusSchema,
     selectionTranslation: HostedAiFeatureStatusSchema,
+    videoSubtitles: HostedAiFeatureStatusSchema,
+    inputTranslation: HostedAiFeatureStatusSchema,
+    languageDetection: HostedAiFeatureStatusSchema,
   }),
 })
 

package/src/schemas/video-transcript.ts

@@ -1,5 +1,6 @@
 import { getVideoIdFromUrl, transcriptSegmentSchema } from "@read-frog/definitions"
 import { z } from "zod"
+import { billingPlanSchema } from "./billing"
 
 export const videoTranscriptStatusSchema = z.enum([
   "pending",
@@ -35,6 +36,12 @@ export type VideoTranscriptSubtitles = z.infer<typeof videoTranscriptSubtitlesSc
 
 export const videoTranscriptCreateInputSchema = z.object({
   url: z.url().refine(url => getVideoIdFromUrl(url) !== null, { message: "url must be a supported video URL" }),
+  // The player's own duration, read from the media element. REQUIRED, and an
+  // untrusted UX hint only: admission uses it to reject an over-quota request
+  // instantly, but every reservation and charge is made against the
+  // server-measured duration in the worker — lying here changes nothing about
+  // what gets billed.
+  durationSec: z.number().int().positive(),
 }).strict()
 export type VideoTranscriptCreateInput = z.infer<typeof videoTranscriptCreateInputSchema>
 
@@ -43,10 +50,31 @@ export const videoTranscriptGetInputSchema = z.object({
 }).strict()
 export type VideoTranscriptGetInput = z.infer<typeof videoTranscriptGetInputSchema>
 
-// The caller's monthly transcription usage against the beta quota.
+// One quota pool as shown to the user. `resetAt` is null for a one-time grant
+// (it never resets); `expiresAt` is null for a monthly pool (its end is the
+// reset). Minutes are display units: `usedMinutes` rounds up and
+// `limitMinutes` rounds down, so the UI can never show headroom that
+// admission (which compares raw seconds) would deny.
+export const videoTranscriptUsagePoolSchema = z.object({
+  id: z.string(),
+  usedMinutes: z.number().int(),
+  limitMinutes: z.number().int(),
+  remainingMinutes: z.number().int(),
+  resetAt: z.iso.datetime().nullable(),
+  expiresAt: z.iso.datetime().nullable(),
+})
+export type VideoTranscriptUsagePool = z.infer<typeof videoTranscriptUsagePoolSchema>
+
+// The caller's transcription quota usage. Totals aggregate across pools;
+// `remainingMinutes` nets out in-flight reservations (committed), while each
+// pool's `usedMinutes` shows settled spend only, so a progress bar cannot run
+// forward and then backwards when a job is released. Deliberately a non-strict
+// object: old clients strip the keys they don't know.
 export const videoTranscriptUsageSchema = z.object({
   usedMinutes: z.number().int(),
   limitMinutes: z.number().int(),
   remainingMinutes: z.number().int(),
+  plan: billingPlanSchema,
+  pools: z.array(videoTranscriptUsagePoolSchema),
 })
 export type VideoTranscriptUsage = z.infer<typeof videoTranscriptUsageSchema>