@read-frog/api-contract 0.4.1 → 0.6.0

package/src/contracts/user.ts

@@ -0,0 +1,17 @@
+import { oc } from "@orpc/contract"
+import {
+  userEnsureTimezoneInputSchema,
+  userEnsureTimezoneOutputSchema,
+} from "#/schemas/user"
+
+export const userContract = {
+  ensureTimezone: oc
+    .route({
+      method: "POST",
+      path: "/users/me/timezone/ensure",
+      summary: "Ensure the authenticated user has a timezone",
+      tags: ["Users"],
+    })
+    .input(userEnsureTimezoneInputSchema)
+    .output(userEnsureTimezoneOutputSchema),
+}

package/src/index.ts

@@ -1,21 +1,33 @@
 import type { ContractRouterClient } from "@orpc/contract"
 import { betaAccessContract } from "./contracts/beta-access"
-import { columnContract } from "./contracts/column"
-import { customTableContract } from "./contracts/custom-table"
-import { rowContract } from "./contracts/row"
+import { cardContract } from "./contracts/card"
+import { cardTemplateContract } from "./contracts/card-template"
+import { notebaseContract } from "./contracts/notebase"
+import { notebaseColumnContract } from "./contracts/notebase-column"
+import { notebaseRowContract } from "./contracts/notebase-row"
+import { srsContract } from "./contracts/srs"
+import { userContract } from "./contracts/user"
 
 export const contract = {
   betaAccess: betaAccessContract,
-  customTable: customTableContract,
-  column: columnContract,
-  row: rowContract,
+  card: cardContract,
+  cardTemplate: cardTemplateContract,
+  notebase: notebaseContract,
+  notebaseColumn: notebaseColumnContract,
+  notebaseRow: notebaseRowContract,
+  srs: srsContract,
+  user: userContract,
 }
 
 export type ORPCRouterClient = ContractRouterClient<typeof contract>
 
 export * from "./public-errors"
 export * from "./schemas/beta-access"
-export * from "./schemas/column"
-export * from "./schemas/custom-table"
-export * from "./schemas/row"
-export * from "./schemas/view"
+export * from "./schemas/card"
+export * from "./schemas/notebase"
+export * from "./schemas/notebase-column"
+export * from "./schemas/notebase-row"
+export * from "./schemas/notebase-view"
+export * from "./schemas/srs"
+export * from "./schemas/timezone"
+export * from "./schemas/user"

package/src/public-errors.ts

@@ -8,7 +8,7 @@ interface PublicAppErrorDefinition {
 }
 
 export const CellValidationFailureReasonSchema = z.enum([
-  "unknown_column",
+  "unknown_notebase_column",
   "type_mismatch",
   "invalid_select_option",
   "invalid_date_format",
@@ -25,31 +25,65 @@ export const CellValidationFailureDetailsSchema = z.object({
 export type CellValidationFailureDetails = z.infer<typeof CellValidationFailureDetailsSchema>
 
 export const CellValidationFailedDataSchema = z.object({
-  columnId: z.string(),
+  notebaseColumnId: z.string(),
   details: CellValidationFailureDetailsSchema,
   reason: CellValidationFailureReasonSchema,
 }).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 PUBLIC_APP_ERROR_DEFS = {
   NOTEBASE_BETA_RESTRICTED: {
     message: "Notebase is currently in beta for selected accounts",
     status: 403,
   },
-  TABLE_NOT_FOUND: {
-    message: "Table not found",
+  NOTEBASE_NOT_FOUND: {
+    message: "Notebase not found",
+    status: 404,
+  },
+  NOTEBASE_COLUMN_NOT_FOUND: {
+    message: "Notebase column not found",
     status: 404,
   },
-  COLUMN_NOT_FOUND: {
-    message: "Column not found",
+  NOTEBASE_ROW_NOT_FOUND: {
+    message: "Notebase row not found",
     status: 404,
   },
-  ROW_NOT_FOUND: {
-    message: "Row not found",
+  CARD_NOT_FOUND: {
+    message: "Card not found",
     status: 404,
   },
-  VIEW_NOT_FOUND: {
-    message: "View not found",
+  CARD_TEMPLATE_NOT_FOUND: {
+    message: "Card template not found",
+    status: 404,
+  },
+  CARD_TEMPLATE_INVALID_NOTEBASE_COLUMNS: {
+    data: CardTemplateInvalidColumnsDataSchema,
+    message: "Card template references unknown notebase columns",
+    status: 422,
+  },
+  CARD_TEMPLATE_NOTEBASE_COLUMN_IN_USE: {
+    message: "Notebase column is used by a card template",
+    status: 409,
+  },
+  CARD_NOT_REVIEWABLE: {
+    message: "Card cannot be reviewed in its current state",
+    status: 409,
+  },
+  CARD_REVIEW_STATE_STALE: {
+    message: "Card review state is stale",
+    status: 409,
+  },
+  CARD_REVIEW_ROLLBACK_UNAVAILABLE: {
+    message: "Card review cannot be rolled back",
+    status: 409,
+  },
+  NOTEBASE_VIEW_NOT_FOUND: {
+    message: "Notebase view not found",
     status: 404,
   },
   CELL_VALIDATION_FAILED: {
@@ -57,8 +91,8 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Cell validation failed",
     status: 422,
   },
-  PRIMARY_COLUMN_DELETE_NOT_ALLOWED: {
-    message: "Cannot delete primary column",
+  PRIMARY_NOTEBASE_COLUMN_DELETE_NOT_ALLOWED: {
+    message: "Cannot delete primary notebase column",
     status: 400,
   },
   CONCURRENT_POSITION_CONFLICT: {

package/src/schemas/card.ts

@@ -0,0 +1,120 @@
+import {
+  cardIdentityShape,
+  cardMemoryStateShape,
+  cardStateSchema,
+  cardTemplateConfigSchema,
+  scheduleStatusSchema,
+} from "@read-frog/definitions"
+import { z } from "zod"
+
+export {
+  cardStateSchema,
+  scheduleStatusSchema,
+}
+export type { CardState, ScheduleStatus } from "@read-frog/definitions"
+
+export const cardTemplateSchema = z.object({
+  id: z.uuid(),
+  notebaseId: z.uuid(),
+  name: z.string(),
+  config: cardTemplateConfigSchema,
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+})
+export type CardTemplate = z.infer<typeof cardTemplateSchema>
+
+export const CardTemplateListInputSchema = z.object({
+  notebaseId: z.uuid(),
+})
+export type CardTemplateListInput = z.infer<typeof CardTemplateListInputSchema>
+
+export const CardTemplateListOutputSchema = z.array(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 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 const CardTemplateUpdateOutputSchema = cardTemplateSchema.extend({
+  txid: z.number(),
+})
+export type CardTemplateUpdateOutput = z.infer<typeof CardTemplateUpdateOutputSchema>
+
+export const CardTemplateDeleteInputSchema = z.object({
+  id: z.uuid(),
+})
+export type CardTemplateDeleteInput = z.infer<typeof CardTemplateDeleteInputSchema>
+
+export const CardTemplateDeleteOutputSchema = z.object({
+  txid: z.number(),
+})
+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 const renderedCardSchema = cardSchema.extend({
+  front: z.string(),
+  back: z.string(),
+})
+export type RenderedCard = z.infer<typeof renderedCardSchema>
+
+export const CardListInputSchema = z.object({
+  notebaseId: z.uuid(),
+  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>
+
+export const CardListOutputSchema = z.array(renderedCardSchema)
+export type CardListOutput = z.infer<typeof CardListOutputSchema>
+
+export const CardGetInputSchema = z.object({
+  id: z.uuid(),
+})
+export type CardGetInput = z.infer<typeof CardGetInputSchema>
+
+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 const CardGenerateOutputSchema = z.object({
+  created: z.number().int().min(0),
+  txid: z.number(),
+})
+export type CardGenerateOutput = z.infer<typeof CardGenerateOutputSchema>

package/src/schemas/notebase-column.ts

@@ -0,0 +1,74 @@
+import { NOTEBASE_COLUMN_MAX_WIDTH, NOTEBASE_COLUMN_MIN_WIDTH, notebaseColumnConfigSchema } from "@read-frog/definitions"
+import { z } from "zod"
+
+export const notebaseColumnWidthSchema = z.number().int().min(NOTEBASE_COLUMN_MIN_WIDTH).max(NOTEBASE_COLUMN_MAX_WIDTH)
+
+export const notebaseColumnSchema = z.object({
+  id: z.string(),
+  notebaseId: z.string(),
+  name: z.string(),
+  config: notebaseColumnConfigSchema,
+  position: z.number(),
+  isPrimary: z.boolean(),
+  width: z.number().nullable(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+})
+export type NotebaseColumn = z.infer<typeof notebaseColumnSchema>
+
+export const notebaseColumnCreateDataSchema = z.object({
+  id: z.uuid().optional(),
+  name: z.string().min(1),
+  config: notebaseColumnConfigSchema,
+}).strict()
+export type NotebaseColumnCreateData = z.infer<typeof notebaseColumnCreateDataSchema>
+
+export const notebaseColumnUpdateDataSchema = z.object({
+  name: z.string().min(1).optional(),
+  config: notebaseColumnConfigSchema.optional(),
+  width: notebaseColumnWidthSchema.nullable().optional(),
+}).strict()
+export type NotebaseColumnUpdateData = z.infer<typeof notebaseColumnUpdateDataSchema>
+
+export const NotebaseColumnCreateInputSchema = z.object({
+  notebaseId: z.uuid(),
+  data: notebaseColumnCreateDataSchema,
+})
+export type NotebaseColumnCreateInput = z.infer<typeof NotebaseColumnCreateInputSchema>
+
+export const NotebaseColumnCreateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseColumnCreateOutput = z.infer<typeof NotebaseColumnCreateOutputSchema>
+
+export const NotebaseColumnUpdateInputSchema = z.object({
+  notebaseColumnId: z.uuid(),
+  data: notebaseColumnUpdateDataSchema,
+})
+export type NotebaseColumnUpdateInput = z.infer<typeof NotebaseColumnUpdateInputSchema>
+
+export const NotebaseColumnUpdateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseColumnUpdateOutput = z.infer<typeof NotebaseColumnUpdateOutputSchema>
+
+export const NotebaseColumnDeleteInputSchema = z.object({
+  notebaseColumnId: z.uuid(),
+})
+export type NotebaseColumnDeleteInput = z.infer<typeof NotebaseColumnDeleteInputSchema>
+
+export const NotebaseColumnDeleteOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseColumnDeleteOutput = z.infer<typeof NotebaseColumnDeleteOutputSchema>
+
+export const NotebaseColumnReorderInputSchema = z.object({
+  notebaseId: z.uuid(),
+  ids: z.array(z.uuid()),
+})
+export type NotebaseColumnReorderInput = z.infer<typeof NotebaseColumnReorderInputSchema>
+
+export const NotebaseColumnReorderOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseColumnReorderOutput = z.infer<typeof NotebaseColumnReorderOutputSchema>

package/src/schemas/notebase-row.ts

@@ -0,0 +1,73 @@
+import { z } from "zod"
+
+export const notebaseRowCellsSchema = z.record(z.string(), z.unknown())
+
+export const notebaseRowSchema = z.object({
+  id: z.string(),
+  notebaseId: z.string(),
+  cells: notebaseRowCellsSchema,
+  position: z.number(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+})
+export type NotebaseRow = z.infer<typeof notebaseRowSchema>
+
+export const notebaseRowCreateDataSchema = z.object({
+  id: z.uuid().optional(),
+  cells: notebaseRowCellsSchema.optional(),
+}).strict()
+export type NotebaseRowCreateData = z.infer<typeof notebaseRowCreateDataSchema>
+
+export const notebaseRowUpdateDataSchema = z.object({
+  cells: notebaseRowCellsSchema.optional(),
+}).strict()
+export type NotebaseRowUpdateData = z.infer<typeof notebaseRowUpdateDataSchema>
+
+export const NotebaseRowCreateInputSchema = z.object({
+  notebaseId: z.uuid(),
+  data: notebaseRowCreateDataSchema,
+})
+export type NotebaseRowCreateInput = z.infer<typeof NotebaseRowCreateInputSchema>
+
+export const NotebaseRowCreateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseRowCreateOutput = z.infer<typeof NotebaseRowCreateOutputSchema>
+
+export const NotebaseRowUpdateInputSchema = z.object({
+  notebaseRowId: z.uuid(),
+  data: notebaseRowUpdateDataSchema,
+})
+export type NotebaseRowUpdateInput = z.infer<typeof NotebaseRowUpdateInputSchema>
+
+export const NotebaseRowUpdateOutputSchema = z.object({
+  id: z.uuid(),
+  notebaseId: z.uuid(),
+  cells: notebaseRowCellsSchema,
+  position: z.number().int(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+  txid: z.number(),
+})
+export type NotebaseRowUpdateOutput = z.infer<typeof NotebaseRowUpdateOutputSchema>
+
+export const NotebaseRowDeleteInputSchema = z.object({
+  notebaseRowId: z.uuid(),
+})
+export type NotebaseRowDeleteInput = z.infer<typeof NotebaseRowDeleteInputSchema>
+
+export const NotebaseRowDeleteOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseRowDeleteOutput = z.infer<typeof NotebaseRowDeleteOutputSchema>
+
+export const NotebaseRowReorderInputSchema = z.object({
+  notebaseId: z.uuid(),
+  ids: z.array(z.uuid()),
+})
+export type NotebaseRowReorderInput = z.infer<typeof NotebaseRowReorderInputSchema>
+
+export const NotebaseRowReorderOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseRowReorderOutput = z.infer<typeof NotebaseRowReorderOutputSchema>

package/src/schemas/notebase-view.ts

@@ -0,0 +1,61 @@
+import { z } from "zod"
+
+export const notebaseViewTypeSchema = z.enum(["table", "kanban", "gallery"])
+export type NotebaseViewType = z.infer<typeof notebaseViewTypeSchema>
+
+export const notebaseViewConfigSchema = z.object({
+  notebaseColumnWidths: z.record(z.string(), z.number()).optional(),
+  hiddenNotebaseColumns: z.array(z.string()).optional(),
+  groupByNotebaseColumnId: z.string().optional(),
+}).catchall(z.unknown())
+export type NotebaseViewConfig = z.infer<typeof notebaseViewConfigSchema>
+
+export const notebaseViewFilterSchema = z.object({
+  notebaseColumnId: z.string(),
+  operator: z.string(),
+  value: z.unknown(),
+}).strict()
+export type NotebaseViewFilter = z.infer<typeof notebaseViewFilterSchema>
+
+export const notebaseViewFiltersSchema = z.array(notebaseViewFilterSchema)
+
+export const notebaseViewSortSchema = z.object({
+  notebaseColumnId: z.string(),
+  direction: z.enum(["asc", "desc"]),
+}).strict()
+export type NotebaseViewSort = z.infer<typeof notebaseViewSortSchema>
+
+export const notebaseViewSortsSchema = z.array(notebaseViewSortSchema)
+
+export const notebaseViewCreateDataSchema = z.object({
+  id: z.uuid().optional(),
+  name: z.string().min(1),
+  type: notebaseViewTypeSchema,
+  config: notebaseViewConfigSchema.optional(),
+  filters: notebaseViewFiltersSchema.optional(),
+  sorts: notebaseViewSortsSchema.optional(),
+}).strict()
+export type NotebaseViewCreateData = z.infer<typeof notebaseViewCreateDataSchema>
+
+export const notebaseViewUpdateDataSchema = z.object({
+  name: z.string().min(1).optional(),
+  type: notebaseViewTypeSchema.optional(),
+  config: notebaseViewConfigSchema.optional(),
+  filters: notebaseViewFiltersSchema.optional(),
+  sorts: notebaseViewSortsSchema.optional(),
+}).strict()
+export type NotebaseViewUpdateData = z.infer<typeof notebaseViewUpdateDataSchema>
+
+export const notebaseViewSchema = z.object({
+  id: z.string(),
+  notebaseId: z.string(),
+  name: z.string(),
+  type: notebaseViewTypeSchema,
+  config: notebaseViewConfigSchema.nullable(),
+  filters: z.array(z.unknown()).nullable(),
+  sorts: z.array(z.unknown()).nullable(),
+  position: z.number(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+})
+export type NotebaseView = z.infer<typeof notebaseViewSchema>

package/src/schemas/notebase.ts

@@ -0,0 +1,103 @@
+import { schedulingParamsShape, srsWeightsSchema } from "@read-frog/definitions"
+import { z } from "zod"
+import { notebaseColumnSchema } from "./notebase-column"
+import { notebaseRowSchema } from "./notebase-row"
+import { notebaseViewSchema } from "./notebase-view"
+
+export const NotebaseListInputSchema = z.object({})
+export type NotebaseListInput = z.infer<typeof NotebaseListInputSchema>
+
+export const NotebaseListItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+export type NotebaseListItem = z.infer<typeof NotebaseListItemSchema>
+
+export const NotebaseListOutputSchema = z.array(NotebaseListItemSchema)
+export type NotebaseListOutput = z.infer<typeof NotebaseListOutputSchema>
+
+export const notebaseSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  name: z.string(),
+  srsNewPerDay: schedulingParamsShape.newPerDay,
+  srsReviewsPerDay: schedulingParamsShape.reviewsPerDay,
+  srsDesiredRetention: schedulingParamsShape.desiredRetention,
+  srsEnableShortTerm: schedulingParamsShape.enableShortTerm,
+  srsMaximumInterval: schedulingParamsShape.maximumInterval,
+  srsLearningSteps: schedulingParamsShape.learningSteps,
+  srsRelearningSteps: schedulingParamsShape.relearningSteps,
+  srsLeechThreshold: schedulingParamsShape.leechThreshold,
+  srsEnableFuzz: schedulingParamsShape.enableFuzz,
+  srsWeights: srsWeightsSchema.nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+export type Notebase = z.infer<typeof notebaseSchema>
+
+export const notebaseCreateDataSchema = z.object({
+  id: z.uuid().optional(),
+  name: z.string().min(1),
+}).strict()
+export type NotebaseCreateData = z.infer<typeof notebaseCreateDataSchema>
+
+export const NotebaseCreateInputSchema = notebaseCreateDataSchema
+export type NotebaseCreateInput = z.infer<typeof NotebaseCreateInputSchema>
+
+export const NotebaseCreateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseCreateOutput = z.infer<typeof NotebaseCreateOutputSchema>
+
+export const notebaseUpdateDataSchema = z.object({
+  name: z.string().min(1).optional(),
+}).strict()
+export type NotebaseUpdateData = z.infer<typeof notebaseUpdateDataSchema>
+
+export const NotebaseUpdateInputSchema = notebaseUpdateDataSchema.extend({
+  id: z.uuid(),
+})
+export type NotebaseUpdateInput = z.infer<typeof NotebaseUpdateInputSchema>
+
+export const NotebaseUpdateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseUpdateOutput = z.infer<typeof NotebaseUpdateOutputSchema>
+
+export const NotebaseDeleteInputSchema = z.object({
+  id: z.uuid(),
+})
+export type NotebaseDeleteInput = z.infer<typeof NotebaseDeleteInputSchema>
+
+export const NotebaseDeleteOutputSchema = z.object({
+  txid: z.number(),
+})
+export type NotebaseDeleteOutput = z.infer<typeof NotebaseDeleteOutputSchema>
+
+// Get endpoint schemas
+export const NotebaseGetInputSchema = z.object({
+  id: z.uuid(),
+})
+export type NotebaseGetInput = z.infer<typeof NotebaseGetInputSchema>
+
+export const NotebaseGetSchemaInputSchema = z.object({
+  id: z.uuid(),
+})
+export type NotebaseGetSchemaInput = z.infer<typeof NotebaseGetSchemaInputSchema>
+
+export const NotebaseGetOutputSchema = notebaseSchema.extend({
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+  notebaseColumns: z.array(notebaseColumnSchema),
+  notebaseRows: z.array(notebaseRowSchema),
+  notebaseViews: z.array(notebaseViewSchema),
+})
+export type NotebaseGetOutput = z.infer<typeof NotebaseGetOutputSchema>
+
+export const NotebaseGetSchemaOutputSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  updatedAt: z.coerce.date(),
+  notebaseColumns: z.array(notebaseColumnSchema),
+})
+export type NotebaseGetSchemaOutput = z.infer<typeof NotebaseGetSchemaOutputSchema>