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

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

Usage

In Chrome Extension

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

// 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

cd packages/shared-types
pnpm generate  # Updates types from schemas
pnpm build     # Builds package

Sync to Chrome Extension

# 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:

# 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.