xtablo-source/packages/shared-types/README.md

# @xtablo/shared-types

Shared TypeScript type definitions for the Xtablo monorepo. This package provides a centralized location for all type definitions used across all applications, including database types, domain types, and utility types.

> **Note**: This package has **zero runtime dependencies** and is purely for TypeScript types. It can be safely imported by any app in the monorepo (API, frontend, mobile) without bringing in unnecessary dependencies.

## Features

- **Zero dependencies**: Pure TypeScript types with no runtime dependencies
- **Supabase integration**: Auto-generated database types from Supabase schema
- **Domain types**: Strongly-typed definitions for Events, Tablos, Stripe, Kanban, etc.
- **Utility types**: Helper types for working with database types
- **Tree-shakeable**: Import only what you need

## Installation

This package is part of the Xtablo monorepo and is available to all apps via workspace protocol:

```json
{
  "dependencies": {
    "@xtablo/shared-types": "workspace:*"
  }
}
```

## Usage

### Import from main export

```typescript
import type { Event, Tablo, UserSubscriptionStatus } from "@xtablo/shared-types";
```

### Import from specific modules

```typescript
import type { Event } from "@xtablo/shared-types/events";
import type { Tablo } from "@xtablo/shared-types/tablos";
import type { StripePrice } from "@xtablo/shared-types/stripe";
import type { KanbanTask } from "@xtablo/shared-types/kanban";
import type { RemoveNull } from "@xtablo/shared-types/utils";
```

## Available Types

### Database Types

Generated from Supabase schema:

```typescript
import type { Database, Json } from "@xtablo/shared-types";
```

### Utility Types

Helper types for working with database types:

```typescript
import type {
  Tables,           // Extract table row types
  TablesInsert,     // Extract table insert types
  TablesUpdate,     // Extract table update types
  RemoveNull,       // Remove null from a type
  RemoveNullFromObject, // Remove null from object properties
} from "@xtablo/shared-types";

// Example usage:
type EventRow = Tables<"events">;
type EventInsert = TablesInsert<"events">;
type EventUpdate = TablesUpdate<"events">;
```

### Event Types

```typescript
import type {
  Event,              // Event with non-null fields
  EventInsert,        // Type for inserting events
  EventUpdate,        // Type for updating events
  EventInsertInTablo, // Event insert without tablo_id
  EventAndTablo,      // Joined event and tablo view
} from "@xtablo/shared-types";
```

### Tablo Types

```typescript
import type {
  Tablo,        // Tablo table type
  TabloInsert,  // Type for inserting tablos
  TabloUpdate,  // Type for updating tablos
  UserTablo,    // User's tablo view
  CreateTablo,  // Type for creating a tablo with events
} from "@xtablo/shared-types";
```

### Stripe Types

```typescript
import type {
  StripeSubscription,
  StripeProduct,
  StripePrice,
  SubscriptionStatus,
  BillingInterval,
  UserSubscriptionStatus,
  PriceWithProduct,
  SubscriptionWithDetails,
} from "@xtablo/shared-types";
```

### Kanban Types

```typescript
import type {
  KanbanTask,
  KanbanBoard,
  KanbanColumn,
  TaskStatus,
  Priority,
  TaskType,
  KanbanTaskInsert,
  KanbanTaskUpdate,
} from "@xtablo/shared-types";
```

## Type Generation

Database types are generated from Supabase and should be updated when the schema changes:

```bash
# From the root of the monorepo
npx supabase gen types typescript --project-id YOUR_PROJECT_ID > packages/shared-types/src/database.types.ts
```

## Structure

```
packages/shared-types/
├── src/
│   ├── database.types.ts  # Supabase-generated types
│   ├── events.types.ts    # Event-related types
│   ├── tablos.types.ts    # Tablo-related types
│   ├── stripe.types.ts    # Stripe integration types
│   ├── kanban.types.ts    # Kanban board types
│   ├── utils.ts           # Utility types
│   └── index.ts           # Main export
├── package.json
├── tsconfig.json
└── README.md
```

## Best Practices

1. **Import specific types**: Use granular imports when possible to improve tree-shaking
2. **Type safety**: Leverage utility types like `RemoveNull` to enforce non-null values
3. **Reusability**: Define types here instead of duplicating them across apps
4. **Documentation**: Add JSDoc comments for complex types

## Scripts

```bash
# Type checking
pnpm typecheck

# Linting
pnpm lint
pnpm lint:fix

# Formatting
pnpm format
```

## Integration with Apps

### API (Node.js/Hono)

```typescript
import type { Event, Tablo, Database } from "@xtablo/shared-types";

export function getEvents(): Promise<Event[]> {
  // Implementation
}
```

### Frontend (React)

```typescript
import type { Event, UserTablo } from "@xtablo/shared-types";

function EventList({ events }: { events: Event[] }) {
  // Component implementation
}
```

### Expo (React Native)

```typescript
import type { Event } from "@xtablo/shared-types";

const EventScreen = ({ event }: { event: Event }) => {
  // Screen implementation
};
```

## Contributing

When adding new types:

1. Place them in the appropriate module file (e.g., `events.types.ts`)
2. Export them from `index.ts`
3. Add documentation in this README
4. Run type checking and linting before committing