@read-frog/api-contract 0.3.0 → 0.4.1

package/src/contracts/custom-table.ts

@@ -0,0 +1,82 @@
+import { pickPublicErrorMap } from "@/public-errors"
+import {
+  CustomTableCreateInputSchema,
+  CustomTableCreateOutputSchema,
+  CustomTableDeleteInputSchema,
+  CustomTableDeleteOutputSchema,
+  CustomTableGetInputSchema,
+  CustomTableGetOutputSchema,
+  CustomTableGetSchemaInputSchema,
+  CustomTableGetSchemaOutputSchema,
+  CustomTableListInputSchema,
+  CustomTableListOutputSchema,
+  CustomTableUpdateInputSchema,
+  CustomTableUpdateOutputSchema,
+} from "@/schemas/custom-table"
+import { notebaseProcedure } from "./shared"
+
+export const customTableContract = {
+  list: notebaseProcedure
+    .route({
+      method: "GET",
+      path: "/custom-tables",
+      summary: "List custom tables",
+      tags: ["Custom Tables"],
+    })
+    .input(CustomTableListInputSchema)
+    .output(CustomTableListOutputSchema),
+
+  get: notebaseProcedure
+    .errors(pickPublicErrorMap("TABLE_NOT_FOUND"))
+    .route({
+      method: "GET",
+      path: "/custom-tables/{id}",
+      summary: "Get custom table with columns, rows, and views",
+      tags: ["Custom Tables"],
+    })
+    .input(CustomTableGetInputSchema)
+    .output(CustomTableGetOutputSchema),
+
+  getSchema: notebaseProcedure
+    .errors(pickPublicErrorMap("TABLE_NOT_FOUND"))
+    .route({
+      method: "GET",
+      path: "/custom-tables/{id}/schema",
+      summary: "Get custom table schema",
+      tags: ["Custom Tables"],
+    })
+    .input(CustomTableGetSchemaInputSchema)
+    .output(CustomTableGetSchemaOutputSchema),
+
+  create: notebaseProcedure
+    .route({
+      method: "POST",
+      path: "/custom-tables",
+      summary: "Create custom table",
+      tags: ["Custom Tables"],
+    })
+    .input(CustomTableCreateInputSchema)
+    .output(CustomTableCreateOutputSchema),
+
+  update: notebaseProcedure
+    .errors(pickPublicErrorMap("TABLE_NOT_FOUND"))
+    .route({
+      method: "PUT",
+      path: "/custom-tables/{id}",
+      summary: "Update custom table",
+      tags: ["Custom Tables"],
+    })
+    .input(CustomTableUpdateInputSchema)
+    .output(CustomTableUpdateOutputSchema),
+
+  delete: notebaseProcedure
+    .errors(pickPublicErrorMap("TABLE_NOT_FOUND"))
+    .route({
+      method: "DELETE",
+      path: "/custom-tables/{id}",
+      summary: "Delete custom table",
+      tags: ["Custom Tables"],
+    })
+    .input(CustomTableDeleteInputSchema)
+    .output(CustomTableDeleteOutputSchema),
+}

package/src/contracts/row.ts

@@ -0,0 +1,62 @@
+import { pickPublicErrorMap } from "@/public-errors"
+import {
+  RowCreateInputSchema,
+  RowCreateOutputSchema,
+  RowDeleteInputSchema,
+  RowDeleteOutputSchema,
+  RowReorderInputSchema,
+  RowReorderOutputSchema,
+  RowUpdateInputSchema,
+  RowUpdateOutputSchema,
+} from "@/schemas/row"
+import { notebaseProcedure } from "./shared"
+
+export const rowContract = {
+  create: notebaseProcedure
+    .errors(pickPublicErrorMap(
+      "TABLE_NOT_FOUND",
+      "CELL_VALIDATION_FAILED",
+      "CONCURRENT_POSITION_CONFLICT",
+    ))
+    .route({
+      method: "POST",
+      path: "/rows",
+      summary: "Create row",
+      tags: ["Rows"],
+    })
+    .input(RowCreateInputSchema)
+    .output(RowCreateOutputSchema),
+
+  update: notebaseProcedure
+    .errors(pickPublicErrorMap("ROW_NOT_FOUND", "CELL_VALIDATION_FAILED"))
+    .route({
+      method: "PATCH",
+      path: "/rows/{rowId}",
+      summary: "Update row cells",
+      tags: ["Rows"],
+    })
+    .input(RowUpdateInputSchema)
+    .output(RowUpdateOutputSchema),
+
+  delete: notebaseProcedure
+    .errors(pickPublicErrorMap("ROW_NOT_FOUND", "CONCURRENT_POSITION_CONFLICT"))
+    .route({
+      method: "DELETE",
+      path: "/rows/{rowId}",
+      summary: "Delete row",
+      tags: ["Rows"],
+    })
+    .input(RowDeleteInputSchema)
+    .output(RowDeleteOutputSchema),
+
+  reorder: notebaseProcedure
+    .errors(pickPublicErrorMap("TABLE_NOT_FOUND", "CONCURRENT_POSITION_CONFLICT"))
+    .route({
+      method: "POST",
+      path: "/rows/reorder",
+      summary: "Reorder rows in a table",
+      tags: ["Rows"],
+    })
+    .input(RowReorderInputSchema)
+    .output(RowReorderOutputSchema),
+}

package/src/contracts/shared.ts

@@ -0,0 +1,6 @@
+import { oc } from "@orpc/contract"
+import { pickPublicErrorMap } from "@/public-errors"
+
+export const notebaseProcedure = oc.errors(
+  pickPublicErrorMap("NOTEBASE_BETA_RESTRICTED"),
+)

package/src/index.ts

@@ -0,0 +1,21 @@
+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"
+
+export const contract = {
+  betaAccess: betaAccessContract,
+  customTable: customTableContract,
+  column: columnContract,
+  row: rowContract,
+}
+
+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"

package/src/public-errors.ts

@@ -0,0 +1,104 @@
+import type { ErrorMap } from "@orpc/contract"
+import { z } from "zod"
+
+interface PublicAppErrorDefinition {
+  data?: z.ZodTypeAny
+  message: string
+  status: number
+}
+
+export const CellValidationFailureReasonSchema = z.enum([
+  "unknown_column",
+  "type_mismatch",
+  "invalid_select_option",
+  "invalid_date_format",
+])
+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 CellValidationFailedDataSchema = z.object({
+  columnId: z.string(),
+  details: CellValidationFailureDetailsSchema,
+  reason: CellValidationFailureReasonSchema,
+}).strict()
+export type CellValidationFailedData = z.infer<typeof CellValidationFailedDataSchema>
+
+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",
+    status: 404,
+  },
+  COLUMN_NOT_FOUND: {
+    message: "Column not found",
+    status: 404,
+  },
+  ROW_NOT_FOUND: {
+    message: "Row not found",
+    status: 404,
+  },
+  VIEW_NOT_FOUND: {
+    message: "View not found",
+    status: 404,
+  },
+  CELL_VALIDATION_FAILED: {
+    data: CellValidationFailedDataSchema,
+    message: "Cell validation failed",
+    status: 422,
+  },
+  PRIMARY_COLUMN_DELETE_NOT_ALLOWED: {
+    message: "Cannot delete primary column",
+    status: 400,
+  },
+  CONCURRENT_POSITION_CONFLICT: {
+    message: "Concurrent position conflict, please retry",
+    status: 409,
+  },
+} as const satisfies Record<string, PublicAppErrorDefinition>
+
+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 }
+    ? z.output<TSchema>
+    : undefined
+
+export function isPublicAppErrorCode(code: string | undefined): code is PublicAppErrorCode {
+  return code !== undefined && code in PUBLIC_APP_ERROR_DEFS
+}
+
+export function getPublicErrorDefinition<TCode extends PublicAppErrorCode>(code: TCode) {
+  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]
+
+    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]>
+}

package/src/schemas/beta-access.ts

@@ -0,0 +1,16 @@
+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 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>

package/src/schemas/column.ts

@@ -0,0 +1,74 @@
+import { COLUMN_MAX_WIDTH, COLUMN_MIN_WIDTH, columnConfigSchema } from "@read-frog/definitions"
+import { z } from "zod"
+
+export const columnWidthSchema = z.number().int().min(COLUMN_MIN_WIDTH).max(COLUMN_MAX_WIDTH)
+
+export const tableColumnSchema = z.object({
+  id: z.string(),
+  tableId: z.string(),
+  name: z.string(),
+  config: columnConfigSchema,
+  position: z.number(),
+  isPrimary: z.boolean(),
+  width: z.number().nullable(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+})
+export type TableColumn = z.infer<typeof tableColumnSchema>
+
+export const columnCreateDataSchema = z.object({
+  id: z.uuid().optional(),
+  name: z.string().min(1),
+  config: columnConfigSchema,
+}).strict()
+export type ColumnCreateData = z.infer<typeof columnCreateDataSchema>
+
+export const columnUpdateDataSchema = z.object({
+  name: z.string().min(1).optional(),
+  config: columnConfigSchema.optional(),
+  width: columnWidthSchema.nullable().optional(),
+}).strict()
+export type ColumnUpdateData = z.infer<typeof columnUpdateDataSchema>
+
+export const ColumnCreateInputSchema = z.object({
+  tableId: z.uuid(),
+  data: columnCreateDataSchema,
+})
+export type ColumnCreateInput = z.infer<typeof ColumnCreateInputSchema>
+
+export const ColumnCreateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type ColumnCreateOutput = z.infer<typeof ColumnCreateOutputSchema>
+
+export const ColumnUpdateInputSchema = z.object({
+  columnId: z.uuid(),
+  data: columnUpdateDataSchema,
+})
+export type ColumnUpdateInput = z.infer<typeof ColumnUpdateInputSchema>
+
+export const ColumnUpdateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type ColumnUpdateOutput = z.infer<typeof ColumnUpdateOutputSchema>
+
+export const ColumnDeleteInputSchema = z.object({
+  columnId: z.uuid(),
+})
+export type ColumnDeleteInput = z.infer<typeof ColumnDeleteInputSchema>
+
+export const ColumnDeleteOutputSchema = z.object({
+  txid: z.number(),
+})
+export type ColumnDeleteOutput = z.infer<typeof ColumnDeleteOutputSchema>
+
+export const ColumnReorderInputSchema = z.object({
+  tableId: z.uuid(),
+  ids: z.array(z.uuid()),
+})
+export type ColumnReorderInput = z.infer<typeof ColumnReorderInputSchema>
+
+export const ColumnReorderOutputSchema = z.object({
+  txid: z.number(),
+})
+export type ColumnReorderOutput = z.infer<typeof ColumnReorderOutputSchema>

package/src/schemas/custom-table.ts

@@ -0,0 +1,86 @@
+import { z } from "zod"
+import { tableColumnSchema } from "./column"
+import { tableRowSchema } from "./row"
+import { tableViewSchema } from "./view"
+
+export const CustomTableListInputSchema = z.object({})
+export type CustomTableListInput = z.infer<typeof CustomTableListInputSchema>
+
+export const CustomTableListItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+export type CustomTableListItem = z.infer<typeof CustomTableListItemSchema>
+
+export const CustomTableListOutputSchema = z.array(CustomTableListItemSchema)
+export type CustomTableListOutput = z.infer<typeof CustomTableListOutputSchema>
+
+export const customTableCreateDataSchema = z.object({
+  id: z.uuid().optional(),
+  name: z.string().min(1),
+}).strict()
+export type CustomTableCreateData = z.infer<typeof customTableCreateDataSchema>
+
+export const CustomTableCreateInputSchema = customTableCreateDataSchema
+export type CustomTableCreateInput = z.infer<typeof CustomTableCreateInputSchema>
+
+export const CustomTableCreateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type CustomTableCreateOutput = z.infer<typeof CustomTableCreateOutputSchema>
+
+export const customTableUpdateDataSchema = z.object({
+  name: z.string().min(1).optional(),
+}).strict()
+export type CustomTableUpdateData = z.infer<typeof customTableUpdateDataSchema>
+
+export const CustomTableUpdateInputSchema = customTableUpdateDataSchema.extend({
+  id: z.uuid(),
+})
+export type CustomTableUpdateInput = z.infer<typeof CustomTableUpdateInputSchema>
+
+export const CustomTableUpdateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type CustomTableUpdateOutput = z.infer<typeof CustomTableUpdateOutputSchema>
+
+export const CustomTableDeleteInputSchema = z.object({
+  id: z.uuid(),
+})
+export type CustomTableDeleteInput = z.infer<typeof CustomTableDeleteInputSchema>
+
+export const CustomTableDeleteOutputSchema = z.object({
+  txid: z.number(),
+})
+export type CustomTableDeleteOutput = z.infer<typeof CustomTableDeleteOutputSchema>
+
+// Get endpoint schemas
+export const CustomTableGetInputSchema = z.object({
+  id: z.uuid(),
+})
+export type CustomTableGetInput = z.infer<typeof CustomTableGetInputSchema>
+
+export const CustomTableGetSchemaInputSchema = z.object({
+  id: z.uuid(),
+})
+export type CustomTableGetSchemaInput = z.infer<typeof CustomTableGetSchemaInputSchema>
+
+export const CustomTableGetOutputSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  name: z.string(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+  columns: z.array(tableColumnSchema),
+  rows: z.array(tableRowSchema),
+  views: z.array(tableViewSchema),
+})
+export type CustomTableGetOutput = z.infer<typeof CustomTableGetOutputSchema>
+
+export const CustomTableGetSchemaOutputSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  updatedAt: z.coerce.date(),
+  columns: z.array(tableColumnSchema),
+})
+export type CustomTableGetSchemaOutput = z.infer<typeof CustomTableGetSchemaOutputSchema>

package/src/schemas/row.ts

@@ -0,0 +1,73 @@
+import { z } from "zod"
+
+export const rowCellsSchema = z.record(z.string(), z.unknown())
+
+export const tableRowSchema = z.object({
+  id: z.string(),
+  tableId: z.string(),
+  cells: rowCellsSchema,
+  position: z.number(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+})
+export type TableRow = z.infer<typeof tableRowSchema>
+
+export const rowCreateDataSchema = z.object({
+  id: z.uuid().optional(),
+  cells: rowCellsSchema.optional(),
+}).strict()
+export type RowCreateData = z.infer<typeof rowCreateDataSchema>
+
+export const rowUpdateDataSchema = z.object({
+  cells: rowCellsSchema.optional(),
+}).strict()
+export type RowUpdateData = z.infer<typeof rowUpdateDataSchema>
+
+export const RowCreateInputSchema = z.object({
+  tableId: z.uuid(),
+  data: rowCreateDataSchema,
+})
+export type RowCreateInput = z.infer<typeof RowCreateInputSchema>
+
+export const RowCreateOutputSchema = z.object({
+  txid: z.number(),
+})
+export type RowCreateOutput = z.infer<typeof RowCreateOutputSchema>
+
+export const RowUpdateInputSchema = z.object({
+  rowId: z.uuid(),
+  data: rowUpdateDataSchema,
+})
+export type RowUpdateInput = z.infer<typeof RowUpdateInputSchema>
+
+export const RowUpdateOutputSchema = z.object({
+  id: z.uuid(),
+  tableId: z.uuid(),
+  cells: rowCellsSchema,
+  position: z.number().int(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+  txid: z.number(),
+})
+export type RowUpdateOutput = z.infer<typeof RowUpdateOutputSchema>
+
+export const RowDeleteInputSchema = z.object({
+  rowId: z.uuid(),
+})
+export type RowDeleteInput = z.infer<typeof RowDeleteInputSchema>
+
+export const RowDeleteOutputSchema = z.object({
+  txid: z.number(),
+})
+export type RowDeleteOutput = z.infer<typeof RowDeleteOutputSchema>
+
+export const RowReorderInputSchema = z.object({
+  tableId: z.uuid(),
+  ids: z.array(z.uuid()),
+})
+export type RowReorderInput = z.infer<typeof RowReorderInputSchema>
+
+export const RowReorderOutputSchema = z.object({
+  txid: z.number(),
+})
+export type RowReorderOutput = z.infer<typeof RowReorderOutputSchema>

package/src/schemas/view.ts

@@ -0,0 +1,61 @@
+import { z } from "zod"
+
+export const tableViewTypeSchema = z.enum(["table", "kanban", "gallery"])
+export type TableViewType = z.infer<typeof tableViewTypeSchema>
+
+export const viewConfigSchema = z.object({
+  columnWidths: z.record(z.string(), z.number()).optional(),
+  hiddenColumns: z.array(z.string()).optional(),
+  groupByColumnId: z.string().optional(),
+}).catchall(z.unknown())
+export type ViewConfig = z.infer<typeof viewConfigSchema>
+
+export const viewFilterSchema = z.object({
+  columnId: z.string(),
+  operator: z.string(),
+  value: z.unknown(),
+}).strict()
+export type ViewFilter = z.infer<typeof viewFilterSchema>
+
+export const viewFiltersSchema = z.array(viewFilterSchema)
+
+export const viewSortSchema = z.object({
+  columnId: z.string(),
+  direction: z.enum(["asc", "desc"]),
+}).strict()
+export type ViewSort = z.infer<typeof viewSortSchema>
+
+export const viewSortsSchema = z.array(viewSortSchema)
+
+export const viewCreateDataSchema = z.object({
+  id: z.uuid().optional(),
+  name: z.string().min(1),
+  type: tableViewTypeSchema,
+  config: viewConfigSchema.optional(),
+  filters: viewFiltersSchema.optional(),
+  sorts: viewSortsSchema.optional(),
+}).strict()
+export type ViewCreateData = z.infer<typeof viewCreateDataSchema>
+
+export const viewUpdateDataSchema = z.object({
+  name: z.string().min(1).optional(),
+  type: tableViewTypeSchema.optional(),
+  config: viewConfigSchema.optional(),
+  filters: viewFiltersSchema.optional(),
+  sorts: viewSortsSchema.optional(),
+}).strict()
+export type ViewUpdateData = z.infer<typeof viewUpdateDataSchema>
+
+export const tableViewSchema = z.object({
+  id: z.string(),
+  tableId: z.string(),
+  name: z.string(),
+  type: tableViewTypeSchema,
+  config: viewConfigSchema.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 TableView = z.infer<typeof tableViewSchema>