# Day AI SDK - Claude Context

## What This Is

**Day AI SDK** is a TypeScript/Node.js SDK for building AI-native applications that integrate with Day AI's CRM platform. This repo provides:

1. **Core SDK** (`src/`) - OAuth 2.0 + MCP client for Day AI platform
2. **Example Apps** (`examples/`) - Reusable templates for building AI-powered tools

## The Vision

Day AI is an **AI-native CRM** with rich contextual business data (contacts, opportunities, meetings). This SDK enables developers to build specialized **object-of-work interfaces** that are deeply integrated with the CRM from day one.

Instead of standalone apps, developers clone example templates and build tools that can instantly query Day AI for context across contacts, opportunities, meetings, and more - all in natural language optimized for LLM agents.

## Architecture

```
User's App (Electron/CLI/Web)
    ↓
Day AI SDK (OAuth + MCP Client)
    ↓
Day AI Platform (AI-native CRM)
    ↓ (MCP Tools)
Contacts, Opportunities, Meetings, Pages, etc.
```

## Key Components

### Core SDK (`src/`)
- **DayAIClient**: OAuth 2.0 with auto token refresh
- **Convenience methods**: `search()`, `createPerson()`, `createOrganization()`, `createOpportunity()`, `sendNotification()`, `keywordSearch()` — typed wrappers that return parsed results
- **Raw MCP access**: `searchObjects()`, `findMeetingsByAttendee()` return raw `ApiResponse<McpToolResult>` for full control; `mcpCallTool()` is the escape hatch for any tool
- **Types**: `src/types.ts` exports `ObjectType`, `WhereCondition`, `SearchOptions`, `SearchResponse`, and input types for all convenience methods
- Full TypeScript types and error handling

### Example 1: Desktop App (`examples/desktop/`)
- **Electron** app with React + TypeScript + Tailwind
- **Left sidebar**: Notes list (CRUD operations)
- **Center**: Rich text editor for notes
- **Right sidebar**: Claude AI chat with streaming
- **MCP Integration**: AI agent can query Day AI CRM via MCP tools
- **Native Tools**: AI can read/update notes directly

This is a **template** - clone it to build bug trackers, opportunity managers, meeting prep tools, etc.

### Example 2: Vercel Weather Cron (`examples/vercel-weather-cron/`)
- **Next.js** app with Vercel Cron Jobs
- **Automated workflow**: Fetches weather daily at 9 AM
- **Email notification**: Uses Day AI's `send_notification` MCP tool
- **Simple dashboard**: Manual trigger and status display
- **Zero server management**: Runs on Vercel's edge

This is a **template** - clone it to build daily digests, scheduled reports, monitoring alerts, data enrichment crons, etc.

## File Structure

```
day-ai-sdk/
├── src/                 # Core SDK
│   ├── client.ts        # DayAIClient (OAuth + MCP + convenience methods)
│   ├── types.ts         # TypeScript types (ObjectType, WhereCondition, inputs, responses)
│   └── index.ts         # Re-exports
├── examples/
│   ├── desktop/         # Electron notes app (template)
│   │   ├── electron/    # Main process (IPC, services)
│   │   │   ├── main.ts
│   │   │   └── services/
│   │   │       ├── AgentService.ts      # Claude SDK integration
│   │   │       ├── OAuthService.ts      # Day AI OAuth
│   │   │       ├── MCPClientService.ts  # MCP client
│   │   │       └── ToolExecutor.ts      # Native + MCP tool execution
│   │   └── src/         # Renderer (React UI)
│   │       ├── App.tsx
│   │       └── components/
│   └── vercel-weather-cron/  # Vercel cron automation (template)
│       ├── app/
│       │   ├── page.tsx             # Dashboard UI
│       │   └── api/
│       │       ├── cron/weather/    # Cron job endpoint
│       │       └── manual-sync/     # Manual trigger
│       ├── lib/
│       │   ├── dayai.ts             # Day AI client
│       │   └── weather.ts           # Weather API
│       └── vercel.json              # Cron config
├── scripts/
│   └── oauth-setup.ts   # CLI OAuth wizard
└── SCHEMA.md            # Day AI object schemas
```

## Common Tasks

### Run the Desktop Example
```bash
cd examples/desktop
npm install
npm run dev
```

### Run the Vercel Example Locally
```bash
cd examples/vercel-weather-cron
npm install
npm run dev
# Visit http://localhost:3000
```

### Deploy Vercel Example
```bash
cd examples/vercel-weather-cron
vercel
# Set environment variables in Vercel dashboard
```

### Add/Modify Features
- **Add native tools**: Edit `electron/services/tools.ts`
- **Modify UI**: Edit `src/components/`
- **Change agent behavior**: Edit `electron/services/AgentService.ts`

### Build New Apps from Template
1. Copy `examples/desktop/` to a new directory
2. Rename "notes" to your object type (bugs, tasks, etc.)
3. Update tools and UI for your use case
4. Day AI MCP integration works out of the box

## Using the SDK

### Convenience Methods (recommended for most use cases)
```typescript
// Search
const contacts = await client.search('native_contact', { propertyId: 'email', operator: 'contains', value: '@acme.com' });

// Create
await client.createPerson({ email: 'jane@acme.com', firstName: 'Jane' });
await client.createOrganization({ domain: 'acme.com', name: 'Acme Inc' });
await client.createOpportunity({ title: 'Deal', stageId: 'stage-id', domain: 'acme.com' });

// Notify
await client.sendNotification({ channel: 'email', emailSubject: 'Hi', emailBody: '<p>Hello</p>', reasoning: 'test' });

// Keyword search
await client.keywordSearch([{ objectType: 'native_contact', keywords: ['acme'] }]);
```

### Raw MCP Access (for AI agent tool execution and full control)
```typescript
// searchObjects / findMeetingsByAttendee return raw ApiResponse<McpToolResult>
const result = await client.searchObjects([{ objectType: 'native_contact' }], { propertiesToReturn: '*' });
const parsed = JSON.parse(result.data?.content[0]?.text);

// mcpCallTool works with any of the 20+ MCP tools
await client.mcpCallTool('get_meeting_recording_context', { objectId: 'meeting-id' });
```

### MCP Tools Available

Tools available via MCP depend on the user's assistant tier (Free → Turbo → Professional → Executive, cumulative).

**Free (no assistant):** `search_objects`, `create_or_update_person_organization`, `create_or_update_workspace_context`, `get_meeting_recording_context`, `create_meeting_recording_clip`, `get_share_url`, `read_crm_schema`, `activate_skill`, `deactivate_skill`

**Turbo adds:** `create_or_update_action`, `create_or_update_relationship`, `create_or_update_list`, `create_page`, `update_page`, `create_email_draft`, `send_notification_mcp`, `assistant_settings`, `manage_skills`, `whoami`

**Professional adds:** `create_or_update_opportunity`, `create_or_update_custom_property`, `backfill_custom_property`, `analyze_pipeline_metrics`, `create_import_from_file`, `save_import_mapping`, `start_import`, `get_import_progress`, `get_import_errors`, `get_imports_by_object_type`, `analyze_csv`, `read_csv_file`, `read_file`, `transform_csv`, `create_view`, `update_view`, `connect_slack`, `open_email_sharing_rules`, `manage_workspace_members`

**Executive adds:** `batch_create_or_update_opportunities`, `batch_create_or_update_people_organizations`, `search_prospects`

Note: Some tools are internal-only (hidden from MCP): `web_search`, `day_ai_help`, `send_notification` (use `send_notification_mcp` instead), `check_workspace_and_user_settings`, `create_or_update_pipeline_stage`, `delete_contact`, `delete_opportunity`, `delete_organization`, `delete_stage_pipeline`, `open_in_app`, `get_context_for_meeting_recording_citations`

### Key Search Patterns

**Find meetings by attendee (relationship search):**
```typescript
await client.search('native_meetingrecording', {
  relationship: 'attendee',
  targetObjectType: 'native_contact',
  targetObjectId: 'john@acme.com',  // email for contacts
  operator: 'eq'
}, { includeRelationships: true });
```

**Find meetings with a company:**
```typescript
await client.search('native_meetingrecording', {
  relationship: 'attendee',
  targetObjectType: 'native_organization',
  targetObjectId: 'acme.com',  // domain for orgs
  operator: 'eq'
}, { includeRelationships: true });
```

**Find notes on an organization:**
```typescript
await client.search('native_context', {
  relationship: 'parent',
  targetObjectType: 'native_organization',
  targetObjectId: 'acme.com',
  operator: 'eq'
}, { includeRelationships: true });
```

See SCHEMA.md for full tool list and relationship definitions.

## Important Patterns

### OAuth Flow
1. User clicks "Connect to Day AI"
2. SDK registers OAuth client dynamically
3. Opens browser for authorization
4. Exchanges code for tokens
5. Auto-refreshes tokens on each request

### Tool Execution Pattern
1. User sends message to AI
2. Claude responds with tool call(s)
3. ToolExecutor checks: native tool or MCP tool?
4. Executes tool and returns result
5. Claude processes result and responds

### Object-of-Work Pattern
- Notes app stores freeform text ("Urgent Bugs", "Q1 Opportunities")
- AI agent can read notes AND query Day AI CRM
- User gets answers combining their notes + full CRM context
- Natural language everywhere (no rigid forms)

## Key Files to Know

- `src/client.ts` - Core SDK client (DayAIClient with convenience methods + raw MCP access)
- `src/types.ts` - All TypeScript types for the convenience layer
- `examples/desktop/electron/services/AgentService.ts` - Claude integration
- `examples/desktop/electron/services/ToolExecutor.ts` - Tool execution logic
- `examples/desktop/src/components/ChatPane.tsx` - Chat UI with streaming
- `SCHEMA.md` - Full Day AI API documentation

## Development Tips

- **OAuth**: Run `yarn oauth:setup` in root to get credentials
- **Hot reload**: Vite + Electron run together, UI hot reloads automatically
- **Debugging**: Check Electron DevTools (Cmd+Option+I) for renderer logs
- **Tool errors**: Check main process console for IPC/tool execution errors
- **MCP issues**: Verify OAuth tokens are valid, check network tab

## Common Issues

1. **MCP connection fails**: Re-run OAuth setup, check network
2. **Tools not working**: Verify Anthropic API key in Settings
3. **Port in use**: Kill process on 5173/5174/5175, or change port in vite.config.ts
4. **Type errors**: Run `npm run build` to regenerate types

## Next Steps for New Claude Sessions

1. Read this file for context
2. Check user's specific request
3. If modifying desktop app: understand `electron/services/` and `src/components/`
4. If adding features: check SCHEMA.md for available MCP tools
5. If building new app: use `examples/desktop/` as template

## Philosophy

This SDK enables developers to build AI-powered tools in minutes, not weeks. The example apps are templates, not demos. Clone, customize, ship.