npm package: @lamaranelson/xy-mind-shared-types
Description: Shared TypeScript types for XY-Mind tRPC API
Latest version: 1.0.46

# XY-Mind Shared Types

**Type-safe interfaces for XY-Mind tRPC API communication**

This package provides Zod-based TypeScript types for seamless communication between the XY-Mind Next.js backend and Chrome extension, ensuring runtime validation and compile-time type safety.

## Features

- **🎯 Zod-Based Types**: Schema-driven with runtime validation
- **🔄 Zero Drift**: Types auto-sync with backend changes
- **🛡️ Type Safety**: Full IDE autocomplete and error checking
- **📦 Small Footprint**: Only essential types included

## Installation

```bash
pnpm add @lamaranelson/xy-mind-shared-types
```

## Usage

### In Chrome Extension

```typescript
import type {
  HealthCheckOutput,
  SyncTasksInput,
  SyncTasksOutput,
  GetBackendDataInput,
  ReportActivityInput
} from '@lamaranelson/xy-mind-shared-types';

// Fully typed tRPC client calls
const health: HealthCheckOutput = await backendTrpc.extensionSync.healthCheck.query();
const syncResult: SyncTasksOutput = await backendTrpc.extensionSync.syncTasks.mutate({
  tasks: [{ taskId: '123', domain: 'example.com', title: 'Test', createdAt: '...' }]
});
```

### Available Types

#### Extension Sync
- `HealthCheckOutput` - Connection status
- `GetUserInfoOutput` - User authentication state  
- `SyncTasksInput/Output` - Task synchronization
- `GetBackendDataInput/Output` - Backend data retrieval
- `ReportActivityInput/Output` - Activity reporting

#### Agent Management
- `AgentGetInputSchema` - Agent retrieval parameters
- `AgentStopInputSchema` - Agent stop parameters
- `AgentTestInputSchema` - Agent testing parameters

## Development

### Update Backend tRPC Router
```typescript
// In XY-Mind-Frontend/src/server/api/routers/
export const extensionSyncRouter = createTRPCRouter({
  newEndpoint: publicProcedure
    .input(z.object({ data: z.string() }))
    .output(z.object({ result: z.string() }))
    .query(async ({ input }) => ({ result: input.data }))
});
```

### Regenerate Types
```bash
cd packages/shared-types
pnpm generate  # Updates types from schemas
pnpm build     # Builds package
```

### Sync to Chrome Extension
```bash
# From XY-Mind-Frontend root
./scripts/sync-types-to-plugin.sh
```

## Scripts

- `pnpm generate` - Generate types from Zod schemas
- `pnpm build` - Build the package for distribution
- `pnpm dev` - Generate types with watch mode

## Package Structure

```
packages/shared-types/
├── src/
│   ├── schemas/
│   │   ├── agent.ts           # Agent management schemas
│   │   └── extension-sync.ts  # Extension communication schemas
│   ├── index.ts               # Main exports (auto-generated)
│   └── generate-from-schemas.ts # Type generator
├── dist/                      # Built package
└── README.md                  # This file
```

## Publishing

To publish updates to npm:

```bash
# From XY-Mind-Frontend root
./scripts/publish-shared-types.sh
```

This script will:
1. Generate types from schemas (`pnpm generate`)
2. Build the package (`pnpm build`) 
3. Bump version and publish to npm

## Type Safety Approach

This package uses **Zod schemas as the single source of truth**:

1. **Schema Definition**: Define Zod schemas in `src/schemas/`
2. **Type Generation**: Generate TypeScript types from schemas
3. **Runtime Validation**: Use schemas for input/output validation
4. **Compile-time Safety**: Import generated types in client code

---

**Note**: This package is auto-generated from Zod schemas. Do not edit generated types manually. All changes must be made in the schema definitions.