# Shared Types Package - @xtablo/shared-types

## Quick Reference

**Package Name**: `@xtablo/shared-types`  
**Location**: `packages/shared-types/`  
**Purpose**: Centralized TypeScript type definitions for the entire monorepo  
**Dependencies**: Zero (pure TypeScript types only)

## Installation

Add to any app in the monorepo:

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

Or use pnpm:

```bash
cd apps/your-app
pnpm add @xtablo/shared-types@workspace:*
```

## Usage

### Basic Imports

```typescript
// Import from main export
import type { Event, Tablo, StripePrice } from "@xtablo/shared-types";

// Import from specific modules (tree-shakeable)
import type { Event } from "@xtablo/shared-types/events";
import type { Tablo } from "@xtablo/shared-types/tablos";
import type { StripePrice } from "@xtablo/shared-types/stripe";
```

### Complete API

```typescript
// Database & Utility Types
import type {
  Database,
  Json,
  Tables,
  TablesInsert,
  TablesUpdate,
  RemoveNull,
  RemoveNullFromObject,
} from "@xtablo/shared-types";

// Event Types
import type {
  Event,
  EventInsert,
  EventUpdate,
  EventInsertInTablo,
  EventAndTablo,
} from "@xtablo/shared-types";

// Tablo Types
import type {
  Tablo,
  TabloInsert,
  TabloUpdate,
  UserTablo,
  CreateTablo,
} from "@xtablo/shared-types";

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

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

## Package Structure

```
packages/shared-types/
├── src/
│   ├── database.types.ts    # Supabase-generated (855 lines)
│   ├── events.types.ts      # Event domain types
│   ├── tablos.types.ts      # Tablo domain types
│   ├── stripe.types.ts      # Stripe integration
│   ├── kanban.types.ts      # Kanban boards (149 lines)
│   ├── utils.ts             # Utility types
│   └── index.ts             # Main export
├── package.json             # Zero dependencies
├── tsconfig.json
├── biome.json
├── turbo.json
├── README.md                # Package documentation
└── EXAMPLES.md              # Usage examples
```

## Key Benefits

1. **Zero Dependencies**: No runtime code, just TypeScript types
2. **Universal**: Works in API (Node), Frontend (React), Mobile (React Native)
3. **Type Safe**: Single source of truth for all types
4. **Tree Shakeable**: Import only what you need
5. **Auto-Generated**: Database types sync with Supabase schema
6. **Well Documented**: Comprehensive README and examples

## Common Patterns

### API Routes (Hono/Express)

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

app.get("/events", async (c) => {
  const events: Event[] = await fetchEvents();
  return c.json(events);
});

app.post("/events", async (c) => {
  const body = await c.req.json<EventInsert>();
  const event = await createEvent(body);
  return c.json(event);
});
```

### React Components

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

interface EventCardProps {
  event: Event;
  tablo: Tablo;
}

export function EventCard({ event, tablo }: EventCardProps) {
  return <div>{event.title}</div>;
}
```

### Utility Type Helpers

```typescript
import type { Tables, TablesInsert, RemoveNull } from "@xtablo/shared-types";

// Extract table types
type Note = Tables<"notes">;
type NoteInsert = TablesInsert<"notes">;

// Make fields non-nullable
type RequiredEvent = RemoveNullFromObject<Tables<"events">, "title" | "start_date">;
```

## Updating Database Types

When the Supabase schema changes:

```bash
# Generate new types
npx supabase gen types typescript --project-id YOUR_ID > packages/shared-types/src/database.types.ts

# Or from local instance
supabase gen types typescript --local > packages/shared-types/src/database.types.ts

# Format the file
turbo run format --filter=@xtablo/shared-types
```

All apps automatically get the updated types on next build.

## Development Commands

```bash
# Type check
turbo run typecheck --filter=@xtablo/shared-types

# Lint
turbo run lint --filter=@xtablo/shared-types
turbo run lint:fix --filter=@xtablo/shared-types

# Format
turbo run format --filter=@xtablo/shared-types
```

## Documentation

- **`packages/shared-types/README.md`** - Complete package documentation
- **`packages/shared-types/EXAMPLES.md`** - 10+ practical usage examples
- **`docs/TYPES_PACKAGE.md`** - Detailed integration guide (old naming)
- **`docs/SHARED_TYPES_PACKAGE.md`** - This quick reference

## Migration Guide

To migrate an existing app:

1. Add dependency: `pnpm add @xtablo/shared-types@workspace:*`
2. Update imports:
   ```typescript
   // Before
   import type { Event } from "../types/events";
   
   // After
   import type { Event } from "@xtablo/shared-types";
   ```
3. Remove duplicate local type files
4. Test: `turbo run typecheck --filter=your-app`

## Integration Status

- ✅ Package created and configured
- ✅ All types organized and exported
- ✅ Zero dependencies verified
- ✅ Type checking passes
- ✅ Linting passes
- ✅ Documentation complete
- ⏳ Ready for integration in apps

## Next Steps

1. Add `@xtablo/shared-types` to app dependencies
2. Replace local type imports with shared types
3. Remove duplicate type definitions
4. Enjoy consistent, type-safe development!

