@terreno/api 0.0.18 → 0.2.0

package/src/tests.ts

@@ -54,10 +54,10 @@ export interface Food {
 }
 
 const userSchema = new Schema<User>({
-  admin: {default: false, type: Boolean},
-  age: Number,
-  name: String,
-  username: String,
+  admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
+  age: {description: "The user's age", type: Number},
+  name: {description: "The user's display name", type: String},
+  username: {description: "The user's username", type: String},
 });
 
 userSchema.plugin(passportLocalMongoose as any, {
@@ -80,55 +80,65 @@ userSchema.methods.postCreate = async function (body: any) {
 export const UserModel = model<User>("User", userSchema);
 
 const superUserSchema = new Schema<SuperUser>({
-  superTitle: {required: true, type: String},
+  superTitle: {description: "The super user's title", required: true, type: String},
 });
 export const SuperUserModel = UserModel.discriminator("SuperUser", superUserSchema);
 
 const staffUserSchema = new Schema<StaffUser>({
-  department: {required: true, type: String},
+  department: {
+    description: "The department the staff member belongs to",
+    required: true,
+    type: String,
+  },
 });
 export const StaffUserModel = UserModel.discriminator("Staff", staffUserSchema);
 
 const foodCategorySchema = new Schema<FoodCategory>(
   {
-    name: String,
-    show: Boolean,
+    name: {description: "The name of the food category", type: String},
+    show: {description: "Whether this category is visible", type: Boolean},
   },
   {timestamps: {createdAt: "created", updatedAt: "updated"}}
 );
 
 const likesSchema = new Schema<any>({
-  likes: Boolean,
-  userId: {ref: "User", type: "ObjectId"},
+  likes: {description: "Whether the user liked the item", type: Boolean},
+  userId: {description: "The user who liked the item", ref: "User", type: "ObjectId"},
 });
 
 const foodSchema = new Schema<Food>(
   {
-    calories: Number,
-    categories: [foodCategorySchema],
-    created: Date,
+    calories: {description: "Number of calories in the food", type: Number},
+    categories: {description: "Categories this food belongs to", type: [foodCategorySchema]},
+    created: {description: "When this food was created", type: Date},
     eatenBy: [
       {
+        description: "Users who have eaten this food",
         ref: "User",
         required: true,
         type: Schema.Types.ObjectId,
       },
     ],
-    expiration: DateOnly,
-    hidden: {default: false, type: Boolean},
+    expiration: {description: "Expiration date of the food", type: DateOnly as any},
+    hidden: {
+      default: false,
+      description: "Whether this food is hidden from listings",
+      type: Boolean,
+    },
     lastEatenWith: {
+      description: "Map of user names to dates they last ate this food with",
       of: Date,
       type: Map,
     },
-    likesIds: {required: true, type: [likesSchema]},
-    name: String,
-    ownerId: {ref: "User", type: "ObjectId"},
+    likesIds: {description: "User likes for this food", required: true, type: [likesSchema]},
+    name: {description: "The name of the food", type: String},
+    ownerId: {description: "The user who owns this food entry", ref: "User", type: "ObjectId"},
     source: {
-      dateAdded: String,
-      href: String,
-      name: String,
+      dateAdded: {description: "When the source was added", type: String},
+      href: {description: "URL of the source", type: String},
+      name: {description: "Name of the source", type: String},
     },
-    tags: [String],
+    tags: {description: "Tags associated with this food", type: [String]},
   },
   {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
 );
@@ -145,8 +155,8 @@ interface RequiredField {
 }
 
 const requiredSchema = new Schema<RequiredField>({
-  about: String,
-  name: {required: true, type: String},
+  about: {description: "Information about the item", type: String},
+  name: {description: "The name of the item", required: true, type: String},
 });
 export const RequiredModel = model<RequiredField>("Required", requiredSchema);
 

package/.cursorrules

@@ -1,107 +0,0 @@
-# @terreno/api
-
-REST API framework built on Express/Mongoose, styled after Django REST Framework.
-
-## Commands
-
-```bash
-bun run compile          # Compile TypeScript
-bun run dev              # Watch mode
-bun run test             # Run tests
-bun run lint             # Lint code
-bun run lint:fix         # Fix lint issues
-```
-
-## Architecture
-
-### modelRouter
-
-Automatically creates RESTful CRUD APIs for Mongoose models with built-in permissions, population, filtering, and lifecycle hooks.
-
-```typescript
-import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
-
-const router = modelRouter(YourModel, {
-  permissions: {
-    list: [Permissions.IsAuthenticated],
-    create: [Permissions.IsAuthenticated],
-    read: [Permissions.IsOwner],
-    update: [Permissions.IsOwner],
-    delete: [],  // Disabled
-  },
-  sort: "-created",
-  queryFields: ["_id", "type", "name"],
-});
-```
-
-### Custom Routes
-
-For non-CRUD endpoints, use the OpenAPI builder:
-
-```typescript
-import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
-
-router.get("/yourRoute/:id", [
-  authenticateMiddleware(),
-  createOpenApiBuilder(options)
-    .withTags(["yourTag"])
-    .withSummary("Brief summary")
-    .withPathParameter("id", {type: "string"})
-    .withResponse(200, {data: {type: "object"}})
-    .build(),
-], asyncHandler(async (req, res) => {
-  return res.json({data: result});
-}));
-```
-
-## Conventions
-
-### Error Handling
-- Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
-- Services should throw user-friendly errors
-
-### Mongoose
-- Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
-- Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
-- All model types live in `src/modelInterfaces.ts`
-
-### User Type Casting
-- In API routes: `req.user` is `UserDocument | undefined`
-- In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
-- Never use `as any as UserDocument`
-
-### Logging
-- Use `logger.info/warn/error/debug` for permanent logs (not `console.log`)
-
-### Testing
-- Use bun test with expect for testing
-- Use existing manual mocks from `src/__mocks__/`
-- Never mock @terreno/api or models
-
-## Model Type Generation
-
-When creating/modifying Mongoose models, update `src/modelInterfaces.ts`:
-
-```typescript
-export type YourModelMethods = {
-  customMethod: (this: YourModelDocument, param: string) => Promise<void>;
-};
-
-export type YourModelStatics = DefaultStatics<YourModelDocument> & {
-  customStatic: (this: YourModelModel, param: string) => Promise<YourModelDocument>;
-};
-
-export type YourModelModel = DefaultModel<YourModelDocument> & YourModelStatics;
-export type YourModelSchema = mongoose.Schema<YourModelDocument, YourModelModel, YourModelMethods>;
-export type YourModelDocument = DefaultDoc & YourModelMethods & {
-  fieldName: string;
-};
-```
-
-## SDK Generation
-
-After modifying routes, regenerate the SDK:
-
-```bash
-bun run sdk
-```

package/.windsurfrules

@@ -1,107 +0,0 @@
-# @terreno/api
-
-REST API framework built on Express/Mongoose, styled after Django REST Framework.
-
-## Commands
-
-```bash
-bun run compile          # Compile TypeScript
-bun run dev              # Watch mode
-bun run test             # Run tests
-bun run lint             # Lint code
-bun run lint:fix         # Fix lint issues
-```
-
-## Architecture
-
-### modelRouter
-
-Automatically creates RESTful CRUD APIs for Mongoose models with built-in permissions, population, filtering, and lifecycle hooks.
-
-```typescript
-import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
-
-const router = modelRouter(YourModel, {
-  permissions: {
-    list: [Permissions.IsAuthenticated],
-    create: [Permissions.IsAuthenticated],
-    read: [Permissions.IsOwner],
-    update: [Permissions.IsOwner],
-    delete: [],  // Disabled
-  },
-  sort: "-created",
-  queryFields: ["_id", "type", "name"],
-});
-```
-
-### Custom Routes
-
-For non-CRUD endpoints, use the OpenAPI builder:
-
-```typescript
-import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
-
-router.get("/yourRoute/:id", [
-  authenticateMiddleware(),
-  createOpenApiBuilder(options)
-    .withTags(["yourTag"])
-    .withSummary("Brief summary")
-    .withPathParameter("id", {type: "string"})
-    .withResponse(200, {data: {type: "object"}})
-    .build(),
-], asyncHandler(async (req, res) => {
-  return res.json({data: result});
-}));
-```
-
-## Conventions
-
-### Error Handling
-- Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
-- Services should throw user-friendly errors
-
-### Mongoose
-- Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
-- Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
-- All model types live in `src/modelInterfaces.ts`
-
-### User Type Casting
-- In API routes: `req.user` is `UserDocument | undefined`
-- In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
-- Never use `as any as UserDocument`
-
-### Logging
-- Use `logger.info/warn/error/debug` for permanent logs (not `console.log`)
-
-### Testing
-- Use bun test with expect for testing
-- Use existing manual mocks from `src/__mocks__/`
-- Never mock @terreno/api or models
-
-## Model Type Generation
-
-When creating/modifying Mongoose models, update `src/modelInterfaces.ts`:
-
-```typescript
-export type YourModelMethods = {
-  customMethod: (this: YourModelDocument, param: string) => Promise<void>;
-};
-
-export type YourModelStatics = DefaultStatics<YourModelDocument> & {
-  customStatic: (this: YourModelModel, param: string) => Promise<YourModelDocument>;
-};
-
-export type YourModelModel = DefaultModel<YourModelDocument> & YourModelStatics;
-export type YourModelSchema = mongoose.Schema<YourModelDocument, YourModelModel, YourModelMethods>;
-export type YourModelDocument = DefaultDoc & YourModelMethods & {
-  fieldName: string;
-};
-```
-
-## SDK Generation
-
-After modifying routes, regenerate the SDK:
-
-```bash
-bun run sdk
-```

package/AGENTS.md

@@ -1,313 +0,0 @@
-# Terreno
-
-A monorepo containing shared packages for building full-stack applications with React Native and Express/Mongoose.
-
-## Packages
-
-- **api/** - REST API framework built on Express/Mongoose (`@terreno/api`)
-- **ui/** - React Native UI component library (`@terreno/ui`)
-- **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
-- **demo/** - Demo app for showcasing and testing UI components
-- **example-frontend/** - Example Expo app demonstrating full stack usage
-- **example-backend/** - Example Express backend using @terreno/api
-
-## Development
-
-Uses [Bun](https://bun.sh/) as the package manager. Use `yarn` commands, not `npm`.
-
-```bash
-bun install              # Install dependencies
-bun run compile          # Compile all packages
-bun run lint             # Lint all packages
-bun run lint:fix         # Fix lint issues
-bun run test             # Run tests in api and ui
-```
-
-### Package-specific commands
-
-```bash
-bun run api:test         # Test API package
-bun run ui:test          # Test UI package
-bun run demo:start       # Start demo app
-bun run frontend:web     # Start frontend example
-bun run backend:dev      # Start backend example
-```
-
-## How the Packages Work Together
-
-The three core packages form a complete full-stack framework:
-
-```
-                           BACKEND
-  @terreno/api
-  - Mongoose models with modelRouter -> CRUD endpoints
-  - Built-in auth (JWT + Passport)
-  - Automatic OpenAPI spec generation
-                              |
-                     /openapi.json
-                              |
-                    RTK Query SDK Codegen
-                              |
-                           FRONTEND
-  @terreno/rtk
-  - Generated hooks from OpenAPI spec
-  - Auth slice with JWT token management
-  - Automatic token refresh
-                              +
-  @terreno/ui
-  - React Native components (Box, Button, TextField, etc.)
-  - TerrenoProvider for theming
-```
-
-### Integration Flow
-
-1. **Backend (api)**: Define Mongoose models, use `modelRouter` to create CRUD endpoints with permissions
-2. **OpenAPI Generation**: `setupServer` automatically generates `/openapi.json`
-3. **SDK Codegen**: Frontend runs `bun run sdk` to generate RTK Query hooks from OpenAPI spec
-4. **Frontend (rtk + ui)**: Use generated hooks with UI components for type-safe API calls
-
-## Example Apps (Keep These Updated!)
-
-The `frontend-example/` and `backend-example/` directories serve as both documentation and integration tests. When adding features to api, ui, or rtk:
-
-1. **Add examples** demonstrating new features
-2. **Update SDK** after backend changes: `cd frontend-example && bun run sdk`
-3. **Verify integration** by running both examples together
-
-### Running the Full Stack
-
-```bash
-# Terminal 1: Start backend
-bun run backend:dev
-
-# Terminal 2: Start frontend
-bun run frontend:web
-```
-
-## Code Style
-
-### TypeScript/JavaScript
-- Use ES module syntax and TypeScript for all code
-- Prefer interfaces over types; avoid enums, use maps
-- Prefer const arrow functions over `function` keyword
-- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`)
-- Use camelCase directories (e.g., `components/authWizard`)
-- Favor named exports
-- Use the RORO pattern (Receive an Object, Return an Object)
-
-### Dates and Time
-- Always use Luxon instead of Date or dayjs
-
-### Error Handling
-- Check error conditions at start of functions and return early
-- Limit nested if statements
-- Use multiline syntax with curly braces for all conditionals
-
-### Testing
-- Use bun test with expect for testing
-
-### Logging
-- Frontend: Use `console.info`, `console.debug`, `console.warn`, or `console.error` for permanent logs
-- Backend: Use `logger.info/warn/error/debug` for permanent logs
-- Use `console.log` only for debugging (to be removed)
-
-### Development Practices
-- Don't apologize for errors: fix them
-- Prioritize modularity, DRY, performance, and security
-- Focus on readability over performance
-- Write complete, functional code without TODOs when possible
-- Comments should describe purpose, not effect
-
-## Package Reference
-
-### @terreno/api
-
-REST API framework providing:
-
-- **modelRouter**: Auto-generates CRUD endpoints for Mongoose models
-- **Permissions**: `IsAuthenticated`, `IsOwner`, `IsAdmin`, `IsAuthenticatedOrReadOnly`
-- **Query Filters**: `OwnerQueryFilter` for filtering list queries by owner
-- **setupServer**: Express server setup with auth, OpenAPI, and middleware
-- **APIError**: Standardized error handling
-- **logger**: Winston-based logging
-
-Key imports:
-```typescript
-import {
-  modelRouter,
-  setupServer,
-  Permissions,
-  OwnerQueryFilter,
-  APIError,
-  logger,
-  asyncHandler,
-  authenticateMiddleware,
-} from "@terreno/api";
-```
-
-#### modelRouter Usage
-
-```typescript
-import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
-
-const router = modelRouter(YourModel, {
-  permissions: {
-    list: [Permissions.IsAuthenticated],
-    create: [Permissions.IsAuthenticated],
-    read: [Permissions.IsOwner],
-    update: [Permissions.IsOwner],
-    delete: [],  // Disabled
-  },
-  sort: "-created",
-  queryFields: ["_id", "type", "name"],
-});
-```
-
-#### Custom Routes
-
-For non-CRUD endpoints, use the OpenAPI builder:
-
-```typescript
-import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
-
-router.get("/yourRoute/:id", [
-  authenticateMiddleware(),
-  createOpenApiBuilder(options)
-    .withTags(["yourTag"])
-    .withSummary("Brief summary")
-    .withPathParameter("id", {type: "string"})
-    .withResponse(200, {data: {type: "object"}})
-    .build(),
-], asyncHandler(async (req, res) => {
-  return res.json({data: result});
-}));
-```
-
-#### API Conventions
-
-- Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
-- Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
-- Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
-- All model types live in `src/modelInterfaces.ts`
-- In routes: `req.user` is `UserDocument | undefined`
-- In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
-
-### @terreno/ui
-
-React Native component library with 88+ components:
-
-- **Layout**: Box, Page, SplitPage, Card
-- **Forms**: TextField, SelectField, DateTimeField, CheckBox
-- **Display**: Text, Heading, Badge, DataTable
-- **Actions**: Button, IconButton, Link
-- **Feedback**: Spinner, Modal, Toast
-- **Theming**: TerrenoProvider, useTheme
-
-Key imports:
-```typescript
-import {
-  Box,
-  Button,
-  Card,
-  Page,
-  Text,
-  TextField,
-  TerrenoProvider,
-} from "@terreno/ui";
-```
-
-#### UI Component Examples
-
-Layout with Box:
-```typescript
-<Box direction="row" padding={4} gap={2} alignItems="center">
-  <Text>Content</Text>
-  <Button text="Action" />
-</Box>
-```
-
-Buttons:
-```typescript
-<Button
-  text="Submit"
-  variant="primary"  // 'primary' | 'secondary' | 'outline' | 'ghost'
-  onClick={handleSubmit}
-  loading={isLoading}
-  iconName="check"
-/>
-```
-
-Forms:
-```typescript
-<TextField
-  label="Email"
-  value={email}
-  onChangeText={setEmail}
-  error={emailError}
-  helperText="Enter a valid email"
-/>
-```
-
-Modals:
-```typescript
-<Modal
-  title="Confirm Action"
-  visible={isVisible}
-  primaryButtonText="Confirm"
-  secondaryButtonText="Cancel"
-  onDismiss={() => setIsVisible(false)}
-  onPrimaryAction={handleConfirm}
->
-  <Text>Are you sure?</Text>
-</Modal>
-```
-
-#### UI Common Pitfalls
-
-- Don't use inline styles when theme values are available
-- Don't use raw `View`/`Text` when `Box`/@terreno/ui `Text` are available
-- Don't forget loading and error states
-- Don't use `style` prop when equivalent props exist (`padding`, `margin`)
-- Never modify `openApiSdk.ts` manually
-
-### @terreno/rtk
-
-Redux Toolkit Query integration:
-
-- **generateAuthSlice**: Creates auth reducer and middleware with JWT handling
-- **emptyApi**: Base RTK Query API for code generation
-- **Platform utilities**: Secure token storage (expo-secure-store for native, AsyncStorage for web)
-
-Key imports:
-```typescript
-import {generateAuthSlice} from "@terreno/rtk";
-```
-
-Always use generated SDK hooks - never use `axios` or `request` directly:
-
-```typescript
-// Correct
-import {useGetYourRouteQuery} from "@/store/openApiSdk";
-const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
-
-// Wrong - don't use axios directly
-// const result = await axios.get("/api/yourRoute/value");
-```
-
-## React Best Practices (Frontend Packages)
-
-- Use functional components with `React.FC` type
-- Import hooks directly: `import {useEffect, useMemo} from 'react'`
-- Always provide return types for functions
-- Add explanatory comment above each `useEffect`
-- Wrap callbacks in `useCallback`
-- Prefer const arrow functions
-- Use inline styles over `StyleSheet.create`
-- Use Luxon for date operations
-- Place static content and interfaces at beginning of file
-- Minimize `use client`, `useEffect`, and `setState`
-- Always support React-Native Web
-
-## Dependency Management
-
-Uses [Bun Catalogs](https://bun.sh/docs/install/catalogs) - shared versions defined in root `package.json` under `catalog`. Reference with `catalog:` in workspace packages.

package/dist/response.js

@@ -1 +0,0 @@
-"use strict";

package/index.ts

@@ -1 +0,0 @@
-console.log("Hello via Bun!");