@read-frog/api-contract 0.14.0 → 0.16.0

package/src/public-errors.ts

@@ -1,11 +1,11 @@
-import type { ErrorMap } from "@orpc/contract"
-import { z } from "zod"
-import { HostedAiCreditPolicyIdSchema, HostedAiModelTierSchema } from "./schemas/hosted-ai"
+import type { ErrorMap } from "@orpc/contract";
+import { z } from "zod";
+import { HostedAiCreditPolicyIdSchema, HostedAiModelTierSchema } from "./schemas/hosted-ai";
 
 interface PublicAppErrorDefinition {
-  data?: z.ZodTypeAny
-  message: string
-  status: number
+  data?: z.ZodTypeAny;
+  message: string;
+  status: number;
 }
 
 export const CellValidationFailureReasonSchema = z.enum([
@@ -13,35 +13,41 @@ export const CellValidationFailureReasonSchema = z.enum([
   "type_mismatch",
   "invalid_select_option",
   "invalid_date_format",
-])
-export type CellValidationFailureReason = z.infer<typeof CellValidationFailureReasonSchema>
+]);
+export type CellValidationFailureReason = z.infer<typeof CellValidationFailureReasonSchema>;
 
-export const CellValidationFailureDetailsSchema = z.object({
-  expectedFormat: z.string().optional(),
-  expectedType: z.string().optional(),
-  receivedType: z.string().optional(),
-  receivedValue: z.unknown().optional(),
-  validOptions: z.array(z.string()).optional(),
-}).strict()
-export type CellValidationFailureDetails = z.infer<typeof CellValidationFailureDetailsSchema>
+export const CellValidationFailureDetailsSchema = z
+  .object({
+    expectedFormat: z.string().optional(),
+    expectedType: z.string().optional(),
+    receivedType: z.string().optional(),
+    receivedValue: z.unknown().optional(),
+    validOptions: z.array(z.string()).optional(),
+  })
+  .strict();
+export type CellValidationFailureDetails = z.infer<typeof CellValidationFailureDetailsSchema>;
 
-export const CellValidationFailedDataSchema = z.object({
-  notebaseColumnId: z.string(),
-  details: CellValidationFailureDetailsSchema,
-  reason: CellValidationFailureReasonSchema,
-  /** Index of the failing row within a batch input (createMany / initialRows). */
-  rowIndex: z.number().int().min(0).optional(),
-}).strict()
-export type CellValidationFailedData = z.infer<typeof CellValidationFailedDataSchema>
+export const CellValidationFailedDataSchema = z
+  .object({
+    notebaseColumnId: z.string(),
+    details: CellValidationFailureDetailsSchema,
+    reason: CellValidationFailureReasonSchema,
+    /** Index of the failing row within a batch input (createMany / initialRows). */
+    rowIndex: z.number().int().min(0).optional(),
+  })
+  .strict();
+export type CellValidationFailedData = z.infer<typeof CellValidationFailedDataSchema>;
 
-export const CardTemplateInvalidColumnsDataSchema = z.object({
-  notebaseColumnIds: z.array(z.string()),
-}).strict()
-export type CardTemplateInvalidColumnsData = z.infer<typeof CardTemplateInvalidColumnsDataSchema>
+export const CardTemplateInvalidColumnsDataSchema = z
+  .object({
+    notebaseColumnIds: z.array(z.string()),
+  })
+  .strict();
+export type CardTemplateInvalidColumnsData = z.infer<typeof CardTemplateInvalidColumnsDataSchema>;
 
 export const HostedAiTierRestrictedDataSchema = z.strictObject({
   modelTier: HostedAiModelTierSchema,
-})
+});
 
 export const HostedAiQuotaExhaustedDataSchema = z.strictObject({
   modelTier: HostedAiModelTierSchema,
@@ -52,9 +58,18 @@ export const HostedAiQuotaExhaustedDataSchema = z.strictObject({
   policyId: HostedAiCreditPolicyIdSchema,
   usedPercent: z.number().min(0).max(100),
   resetAt: z.iso.datetime().nullable(),
-})
+});
 
 export const PUBLIC_APP_ERROR_DEFS = {
+  RESOURCE_UPDATE_CONFLICT: {
+    message: "The resource changed. Read it again before updating.",
+    status: 409,
+  },
+  RESOURCE_ALREADY_EXISTS: { message: "A resource with this ID already exists.", status: 409 },
+  FIELD_TYPE_CHANGE_UNSUPPORTED: {
+    message: "This operation cannot change the field type.",
+    status: 400,
+  },
   HOSTED_AI_TIER_RESTRICTED: {
     data: HostedAiTierRestrictedDataSchema,
     message: "This Built-in AI tier is not available for this account",
@@ -226,40 +241,48 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Ebook upload has not been completed",
     status: 409,
   },
-} as const satisfies Record<string, PublicAppErrorDefinition>
+} as const satisfies Record<string, PublicAppErrorDefinition>;
 
-export type PublicAppErrorCode = keyof typeof PUBLIC_APP_ERROR_DEFS
+export type PublicAppErrorCode = keyof typeof PUBLIC_APP_ERROR_DEFS;
 
-export type PublicAppErrorData<TCode extends PublicAppErrorCode>
-  = (typeof PUBLIC_APP_ERROR_DEFS)[TCode] extends { data: infer TSchema extends z.ZodTypeAny }
+export type PublicAppErrorData<TCode extends PublicAppErrorCode> =
+  (typeof PUBLIC_APP_ERROR_DEFS)[TCode] extends { data: infer TSchema extends z.ZodTypeAny }
     ? z.output<TSchema>
-    : undefined
+    : undefined;
 
 export function isPublicAppErrorCode(code: string | undefined): code is PublicAppErrorCode {
-  return code !== undefined && code in PUBLIC_APP_ERROR_DEFS
+  return code !== undefined && code in PUBLIC_APP_ERROR_DEFS;
 }
 
 export function getPublicErrorDefinition<TCode extends PublicAppErrorCode>(code: TCode) {
-  return PUBLIC_APP_ERROR_DEFS[code]
+  return PUBLIC_APP_ERROR_DEFS[code];
 }
 
 export function pickPublicErrorMap<const TCodes extends readonly PublicAppErrorCode[]>(
   ...codes: TCodes
 ) {
-  return Object.fromEntries(codes.map((code) => {
-    const definition = PUBLIC_APP_ERROR_DEFS[code]
+  return Object.fromEntries(
+    codes.map((code) => {
+      const definition = PUBLIC_APP_ERROR_DEFS[code];
 
-    if ("data" in definition) {
-      return [code, {
-        data: definition.data,
-        message: definition.message,
-        status: definition.status,
-      }]
-    }
+      if ("data" in definition) {
+        return [
+          code,
+          {
+            data: definition.data,
+            message: definition.message,
+            status: definition.status,
+          },
+        ];
+      }
 
-    return [code, {
-      message: definition.message,
-      status: definition.status,
-    }]
-  })) as Pick<ErrorMap, TCodes[number]>
+      return [
+        code,
+        {
+          message: definition.message,
+          status: definition.status,
+        },
+      ];
+    }),
+  ) as Pick<ErrorMap, TCodes[number]>;
 }

package/src/schemas/beta-access.ts

@@ -1,16 +1,18 @@
-import { BETA_FEATURE_KEYS } from "@read-frog/definitions"
-import { z } from "zod"
+import { BETA_FEATURE_KEYS } from "@read-frog/definitions";
+import { z } from "zod";
 
-export const BetaFeatureKeySchema = z.enum(BETA_FEATURE_KEYS)
-export type BetaFeatureKey = z.infer<typeof BetaFeatureKeySchema>
+export const BetaFeatureKeySchema = z.enum(BETA_FEATURE_KEYS);
+export type BetaFeatureKey = z.infer<typeof BetaFeatureKeySchema>;
 
-export const BetaAccessStatusInputSchema = z.object({
-  featureKey: BetaFeatureKeySchema,
-}).strict()
-export type BetaAccessStatusInput = z.infer<typeof BetaAccessStatusInputSchema>
+export const BetaAccessStatusInputSchema = z
+  .object({
+    featureKey: BetaFeatureKeySchema,
+  })
+  .strict();
+export type BetaAccessStatusInput = z.infer<typeof BetaAccessStatusInputSchema>;
 
 export const BetaAccessStatusOutputSchema = z.object({
   featureKey: BetaFeatureKeySchema,
   allowed: z.boolean(),
-})
-export type BetaAccessStatusOutput = z.infer<typeof BetaAccessStatusOutputSchema>
+});
+export type BetaAccessStatusOutput = z.infer<typeof BetaAccessStatusOutputSchema>;

package/src/schemas/billing.ts

@@ -1,7 +1,7 @@
-import { z } from "zod"
+import { z } from "zod";
 
-export const billingIntervalSchema = z.enum(["month", "year"])
-export type BillingInterval = z.infer<typeof billingIntervalSchema>
+export const billingIntervalSchema = z.enum(["month", "year"]);
+export type BillingInterval = z.infer<typeof billingIntervalSchema>;
 
 export const billingSubscriptionStatusSchema = z.enum([
   "incomplete",
@@ -12,18 +12,44 @@ export const billingSubscriptionStatusSchema = z.enum([
   "canceled",
   "unpaid",
   "paused",
-])
-export type BillingSubscriptionStatus = z.infer<typeof billingSubscriptionStatusSchema>
+]);
+export type BillingSubscriptionStatus = z.infer<typeof billingSubscriptionStatusSchema>;
 
-export const billingPlanSchema = z.enum(["free", "pro", "ultra"])
-export type BillingPlan = z.infer<typeof billingPlanSchema>
+export const billingPlanSchema = z.enum(["free", "pro", "ultra"]);
+export type BillingPlan = z.infer<typeof billingPlanSchema>;
+
+/**
+ * Whether a plan may use a feature, given the plans that feature allows.
+ *
+ * An explicit set rather than a minimum tier: there is no rank table to keep in
+ * step with the plan enum, and any combination is expressible by writing it
+ * down. The cost is that nothing derives from it automatically -- a feature's
+ * pricing-card placement is a companion edit, noted at each `*_ALLOWED_PLANS`.
+ */
+export function isPlanAllowed(plan: BillingPlan, allowed: readonly BillingPlan[]): boolean {
+  return allowed.includes(plan);
+}
+
+/**
+ * Plans that may use the remote MCP server.
+ *
+ * Read by the server-side gate AND by the website's copy, so the page cannot
+ * promise access the API refuses. `satisfies` keeps the literal tuple type so
+ * the UI can render the plan names from this constant instead of hardcoding
+ * them.
+ *
+ * Companion edit when this changes: the feature bullet in
+ * `apps/www/src/routes/pricing.tsx` lives on the lowest allowed plan's card
+ * (higher cards inherit it through their "everything in <lower plan>" line).
+ */
+export const MCP_ALLOWED_PLANS = ["ultra"] as const satisfies readonly BillingPlan[];
 
 // Plans a user can actively check out into (the free tier has no price).
-export const billingCheckoutPlanSchema = z.enum(["pro", "ultra"])
-export type BillingCheckoutPlan = z.infer<typeof billingCheckoutPlanSchema>
+export const billingCheckoutPlanSchema = z.enum(["pro", "ultra"]);
+export type BillingCheckoutPlan = z.infer<typeof billingCheckoutPlanSchema>;
 
-export const billingCurrencySchema = z.enum(["usd", "cad", "cny"])
-export type BillingCurrency = z.infer<typeof billingCurrencySchema>
+export const billingCurrencySchema = z.enum(["usd", "cad", "cny"]);
+export type BillingCurrency = z.infer<typeof billingCurrencySchema>;
 
 export const billingLocaleSchema = z.enum([
   "en",
@@ -35,58 +61,76 @@ export const billingLocaleSchema = z.enum([
   "vi",
   "zh",
   "zh-TW",
-])
-export type BillingLocale = z.infer<typeof billingLocaleSchema>
+]);
+export type BillingLocale = z.infer<typeof billingLocaleSchema>;
 
-export const billingAccessSourceSchema = z.enum(["subscription", "pass"])
-export type BillingAccessSource = z.infer<typeof billingAccessSourceSchema>
+export const billingAccessSourceSchema = z.enum(["subscription", "pass"]);
+export type BillingAccessSource = z.infer<typeof billingAccessSourceSchema>;
 
-export const billingScheduledChangeSchema = z.object({
-  plan: billingCheckoutPlanSchema,
-  interval: billingIntervalSchema,
-  effectiveAt: z.coerce.date(),
-}).strict()
-export type BillingScheduledChange = z.infer<typeof billingScheduledChangeSchema>
+export const billingScheduledChangeSchema = z
+  .object({
+    plan: billingCheckoutPlanSchema,
+    interval: billingIntervalSchema,
+    effectiveAt: z.coerce.date(),
+  })
+  .strict();
+export type BillingScheduledChange = z.infer<typeof billingScheduledChangeSchema>;
 
-export const billingStatusSchema = z.object({
-  plan: billingPlanSchema,
-  status: billingSubscriptionStatusSchema.nullable(),
-  interval: billingIntervalSchema.nullable(),
-  currentPeriodEnd: z.coerce.date().nullable(),
-  /**
-   * 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(),
-  notebaseNoteLimit: z.number().int().positive(),
-  notebaseNoteCount: z.number().int().min(0),
-}).strict()
-export type BillingStatus = z.infer<typeof billingStatusSchema>
+export const billingStatusSchema = z
+  .object({
+    plan: billingPlanSchema,
+    status: billingSubscriptionStatusSchema.nullable(),
+    interval: billingIntervalSchema.nullable(),
+    currentPeriodEnd: z.coerce.date().nullable(),
+    /**
+     * 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(),
+    notebaseNoteLimit: z.number().int().positive(),
+    notebaseNoteCount: z.number().int().min(0),
+  })
+  .strict();
+export type BillingStatus = z.infer<typeof billingStatusSchema>;
 
-export const billingCreateCheckoutSessionInputSchema = z.object({
-  currency: billingCurrencySchema,
-  interval: billingIntervalSchema,
-  locale: billingLocaleSchema,
-  plan: billingCheckoutPlanSchema.default("pro"),
-}).strict()
-export type BillingCreateCheckoutSessionInput = z.infer<typeof billingCreateCheckoutSessionInputSchema>
+export const billingCreateCheckoutSessionInputSchema = z
+  .object({
+    currency: billingCurrencySchema,
+    interval: billingIntervalSchema,
+    locale: billingLocaleSchema,
+    plan: billingCheckoutPlanSchema.default("pro"),
+  })
+  .strict();
+export type BillingCreateCheckoutSessionInput = z.infer<
+  typeof billingCreateCheckoutSessionInputSchema
+>;
 
-export const billingCreateCustomerPortalSessionInputSchema = z.object({
-  locale: billingLocaleSchema,
-}).strict()
-export type BillingCreateCustomerPortalSessionInput = z.infer<typeof billingCreateCustomerPortalSessionInputSchema>
+export const billingCreateCustomerPortalSessionInputSchema = z
+  .object({
+    locale: billingLocaleSchema,
+  })
+  .strict();
+export type BillingCreateCustomerPortalSessionInput = z.infer<
+  typeof billingCreateCustomerPortalSessionInputSchema
+>;
 
-export const billingSessionUrlOutputSchema = z.object({
-  url: z.url(),
-}).strict()
-export type BillingSessionUrlOutput = z.infer<typeof billingSessionUrlOutputSchema>
+export const billingSessionUrlOutputSchema = z
+  .object({
+    url: z.url(),
+  })
+  .strict();
+export type BillingSessionUrlOutput = z.infer<typeof billingSessionUrlOutputSchema>;
 
-export const billingCancelScheduledChangeOutputSchema = z.object({
-  success: z.literal(true),
-}).strict()
-export type BillingCancelScheduledChangeOutput = z.infer<typeof billingCancelScheduledChangeOutputSchema>
+export const billingCancelScheduledChangeOutputSchema = z
+  .object({
+    success: z.literal(true),
+  })
+  .strict();
+export type BillingCancelScheduledChangeOutput = z.infer<
+  typeof billingCancelScheduledChangeOutputSchema
+>;

package/src/schemas/card.ts

@@ -1,17 +1,16 @@
+import { paginationShape, pageSchema } from "./pagination";
+import { deletionResultSchema, expectedUpdatedAtSchema } from "./resource-mutation";
 import {
   cardIdentityShape,
   cardMemoryStateShape,
   cardStateSchema,
   cardTemplateConfigSchema,
   scheduleStatusSchema,
-} from "@read-frog/definitions"
-import { z } from "zod"
+} from "@read-frog/definitions";
+import { z } from "zod";
 
-export {
-  cardStateSchema,
-  scheduleStatusSchema,
-}
-export type { CardState, ScheduleStatus } from "@read-frog/definitions"
+export { cardStateSchema, scheduleStatusSchema };
+export type { CardState, ScheduleStatus } from "@read-frog/definitions";
 
 export const cardTemplateSchema = z.object({
   id: z.uuid(),
@@ -20,101 +19,105 @@ export const cardTemplateSchema = z.object({
   config: cardTemplateConfigSchema,
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
-})
-export type CardTemplate = z.infer<typeof cardTemplateSchema>
+});
+export type CardTemplate = z.infer<typeof cardTemplateSchema>;
 
 export const CardTemplateListInputSchema = z.object({
-  notebaseId: z.uuid(),
-})
-export type CardTemplateListInput = z.infer<typeof CardTemplateListInputSchema>
+  ...paginationShape,
+  notebaseId: z.uuid().optional(),
+});
+export type CardTemplateListInput = z.infer<typeof CardTemplateListInputSchema>;
 
-export const CardTemplateListOutputSchema = z.array(cardTemplateSchema)
-export type CardTemplateListOutput = z.infer<typeof CardTemplateListOutputSchema>
+export const CardTemplateListOutputSchema = pageSchema(cardTemplateSchema);
+export type CardTemplateListOutput = z.infer<typeof CardTemplateListOutputSchema>;
 
 export const CardTemplateGetInputSchema = z.object({
   id: z.uuid(),
-})
-export type CardTemplateGetInput = z.infer<typeof CardTemplateGetInputSchema>
-
-export const CardTemplateGetOutputSchema = cardTemplateSchema
-export type CardTemplateGetOutput = z.infer<typeof CardTemplateGetOutputSchema>
-
-export const CardTemplateCreateInputSchema = z.object({
-  id: z.uuid().optional(),
-  notebaseId: z.uuid(),
-  name: z.string().min(1),
-  config: cardTemplateConfigSchema,
-}).strict()
-export type CardTemplateCreateInput = z.infer<typeof CardTemplateCreateInputSchema>
+});
+export type CardTemplateGetInput = z.infer<typeof CardTemplateGetInputSchema>;
+
+export const CardTemplateGetOutputSchema = cardTemplateSchema;
+export type CardTemplateGetOutput = z.infer<typeof CardTemplateGetOutputSchema>;
+
+export const CardTemplateCreateInputSchema = z
+  .object({
+    id: z.uuid().optional(),
+    notebaseId: z.uuid(),
+    name: z.string().min(1),
+    config: cardTemplateConfigSchema,
+  })
+  .strict();
+export type CardTemplateCreateInput = z.infer<typeof CardTemplateCreateInputSchema>;
 
 export const CardTemplateCreateOutputSchema = cardTemplateSchema.extend({
   txid: z.number(),
-})
-export type CardTemplateCreateOutput = z.infer<typeof CardTemplateCreateOutputSchema>
-
-export const CardTemplateUpdateInputSchema = z.object({
-  id: z.uuid(),
-  name: z.string().min(1).optional(),
-  config: cardTemplateConfigSchema.optional(),
-}).strict()
-export type CardTemplateUpdateInput = z.infer<typeof CardTemplateUpdateInputSchema>
+});
+export type CardTemplateCreateOutput = z.infer<typeof CardTemplateCreateOutputSchema>;
+
+export const CardTemplateUpdateInputSchema = z
+  .object({
+    expectedUpdatedAt: expectedUpdatedAtSchema.optional(),
+    id: z.uuid(),
+    name: z.string().min(1).optional(),
+    config: cardTemplateConfigSchema.optional(),
+  })
+  .strict();
+export type CardTemplateUpdateInput = z.infer<typeof CardTemplateUpdateInputSchema>;
 
 export const CardTemplateUpdateOutputSchema = cardTemplateSchema.extend({
   txid: z.number(),
-})
-export type CardTemplateUpdateOutput = z.infer<typeof CardTemplateUpdateOutputSchema>
+});
+export type CardTemplateUpdateOutput = z.infer<typeof CardTemplateUpdateOutputSchema>;
 
 export const CardTemplateDeleteInputSchema = z.object({
   id: z.uuid(),
-})
-export type CardTemplateDeleteInput = z.infer<typeof CardTemplateDeleteInputSchema>
+});
+export type CardTemplateDeleteInput = z.infer<typeof CardTemplateDeleteInputSchema>;
 
-export const CardTemplateDeleteOutputSchema = z.object({
-  txid: z.number(),
-})
-export type CardTemplateDeleteOutput = z.infer<typeof CardTemplateDeleteOutputSchema>
+export const CardTemplateDeleteOutputSchema = deletionResultSchema;
+export type CardTemplateDeleteOutput = z.infer<typeof CardTemplateDeleteOutputSchema>;
 
 export const cardSchema = z.object({
   ...cardIdentityShape,
   ...cardMemoryStateShape,
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
-})
-export type Card = z.infer<typeof cardSchema>
+});
+export type Card = z.infer<typeof cardSchema>;
 
 export const renderedCardSchema = cardSchema.extend({
   front: z.string(),
   back: z.string(),
-})
-export type RenderedCard = z.infer<typeof renderedCardSchema>
+});
+export type RenderedCard = z.infer<typeof renderedCardSchema>;
 
 export const CardListInputSchema = z.object({
-  notebaseId: z.uuid(),
+  notebaseId: z.uuid().optional(),
   templateId: z.uuid().optional(),
-  limit: z.number().int().min(1).max(500).optional(),
-  offset: z.number().int().min(0).optional(),
-})
-export type CardListInput = z.infer<typeof CardListInputSchema>
+  scheduleStatus: scheduleStatusSchema.optional(),
+  ...paginationShape,
+});
+export type CardListInput = z.infer<typeof CardListInputSchema>;
 
-export const CardListOutputSchema = z.array(renderedCardSchema)
-export type CardListOutput = z.infer<typeof CardListOutputSchema>
+export const CardListOutputSchema = pageSchema(renderedCardSchema);
+export type CardListOutput = z.infer<typeof CardListOutputSchema>;
 
 export const CardGetInputSchema = z.object({
   id: z.uuid(),
-})
-export type CardGetInput = z.infer<typeof CardGetInputSchema>
+});
+export type CardGetInput = z.infer<typeof CardGetInputSchema>;
 
-export const CardGetOutputSchema = renderedCardSchema
-export type CardGetOutput = z.infer<typeof CardGetOutputSchema>
+export const CardGetOutputSchema = renderedCardSchema;
+export type CardGetOutput = z.infer<typeof CardGetOutputSchema>;
 
 export const CardGenerateInputSchema = z.object({
   notebaseId: z.uuid(),
   templateId: z.uuid().optional(),
-})
-export type CardGenerateInput = z.infer<typeof CardGenerateInputSchema>
+});
+export type CardGenerateInput = z.infer<typeof CardGenerateInputSchema>;
 
 export const CardGenerateOutputSchema = z.object({
   created: z.number().int().min(0),
   txid: z.number(),
-})
-export type CardGenerateOutput = z.infer<typeof CardGenerateOutputSchema>
+});
+export type CardGenerateOutput = z.infer<typeof CardGenerateOutputSchema>;