veryfront 0.0.48 → 0.0.50

package/dist/integrations/outlook/README.md

@@ -0,0 +1,308 @@
+# Microsoft Outlook Integration for Veryfront
+
+Complete Microsoft Outlook integration following the veryfront integration pattern.
+
+## Features
+
+- OAuth 2.0 authentication with Microsoft Graph API
+- Read, send, and manage Outlook emails
+- Search emails across all folders
+- List and organize mail folders
+- Full TypeScript type safety
+
+## Setup Instructions
+
+### 1. Create Azure App Registration
+
+1. Go to [Azure Portal - App Registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
+2. Click "New registration"
+3. Enter application details:
+   - Name: Your app name (e.g., "Veryfront Outlook Integration")
+   - Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
+   - Redirect URI: `http://localhost:3000/api/auth/outlook/callback` (adjust for your domain)
+4. Click "Register"
+
+### 2. Configure App Credentials
+
+1. Note the "Application (client) ID" - this is your `MICROSOFT_CLIENT_ID`
+2. Go to "Certificates & secrets"
+3. Click "New client secret"
+4. Add a description and expiration period
+5. Copy the secret value - this is your `MICROSOFT_CLIENT_SECRET`
+
+### 3. Set API Permissions
+
+1. Go to "API permissions"
+2. Click "Add a permission" → "Microsoft Graph" → "Delegated permissions"
+3. Add these permissions:
+   - `Mail.Read` - Read user mail
+   - `Mail.Send` - Send mail as a user
+   - `Mail.ReadWrite` - Read and write access to user mail
+   - `offline_access` - Maintain access to data you have given it access to
+4. Click "Grant admin consent" (if available)
+
+### 4. Add Environment Variables
+
+Add to your `.env` file:
+
+```bash
+MICROSOFT_CLIENT_ID=your_client_id_here
+MICROSOFT_CLIENT_SECRET=your_client_secret_here
+```
+
+## File Structure
+
+```
+outlook/
+├── connector.json                    # Integration configuration
+├── files/
+│   ├── _env.example                 # Example environment variables
+│   ├── lib/
+│   │   ├── oauth.ts                 # OAuth flow utilities
+│   │   ├── outlook-client.ts        # Microsoft Graph API client
+│   │   └── token-store.ts           # Token storage (in-memory)
+│   ├── app/api/auth/outlook/
+│   │   ├── route.ts                 # OAuth initiation
+│   │   └── callback/route.ts        # OAuth callback handler
+│   └── ai/tools/
+│       ├── list-emails.ts           # List recent emails
+│       ├── get-email.ts             # Get email details
+│       ├── send-email.ts            # Send email
+│       ├── search-emails.ts         # Search emails
+│       └── list-folders.ts          # List mail folders
+```
+
+## API Client (`outlook-client.ts`)
+
+### Functions
+
+#### `listEmails(options?)`
+List emails from inbox or specific folder.
+- `folderId?: string` - Folder ID (default: inbox)
+- `top?: number` - Max results
+- `skip?: number` - Pagination offset
+- `filter?: string` - OData filter
+- `orderBy?: string` - Sort order
+
+#### `getEmail(messageId: string)`
+Get detailed email information including full body.
+
+#### `sendEmail(options: SendEmailOptions)`
+Send a new email message.
+- `to: string[]` - Recipients
+- `subject: string` - Subject line
+- `body: string` - Email body
+- `cc?: string[]` - CC recipients
+- `bcc?: string[]` - BCC recipients
+- `importance?: 'low' | 'normal' | 'high'`
+- `bodyType?: 'text' | 'html'`
+
+#### `searchEmails(options)`
+Search emails by query string.
+- `query: string` - Search query
+- `top?: number` - Max results
+- `skip?: number` - Pagination offset
+
+#### `listFolders()`
+List all mail folders in the mailbox.
+
+#### Helper Functions
+- `markAsRead(messageId: string)`
+- `markAsUnread(messageId: string)`
+- `deleteEmail(messageId: string)`
+- `moveEmail(messageId: string, destinationFolderId: string)`
+- `formatEmail(message: OutlookMessage)` - Format for display
+
+## AI Tools
+
+### 1. `list-emails`
+List recent emails from inbox or folder.
+
+**Parameters:**
+- `folderId?: string` - Folder ID
+- `limit?: number` (1-50, default: 10) - Max emails
+- `unreadOnly?: boolean` - Only unread emails
+- `orderBy?: string` - Sort order
+
+**Example:**
+```typescript
+{
+  folderId: "inbox",
+  limit: 20,
+  unreadOnly: true,
+  orderBy: "receivedDateTime desc"
+}
+```
+
+### 2. `get-email`
+Get detailed email information.
+
+**Parameters:**
+- `messageId: string` - Email ID
+- `includeBody?: boolean` (default: true) - Include full body
+
+**Example:**
+```typescript
+{
+  messageId: "AAMkAGI2TG93AAA=",
+  includeBody: true
+}
+```
+
+### 3. `send-email`
+Send a new email message.
+
+**Parameters:**
+- `to: string[]` - Recipient emails
+- `subject: string` - Subject line
+- `body: string` - Email body
+- `cc?: string[]` - CC emails
+- `bcc?: string[]` - BCC emails
+- `importance?: 'low' | 'normal' | 'high'`
+- `bodyType?: 'text' | 'html'`
+
+**Example:**
+```typescript
+{
+  to: ["user@example.com"],
+  subject: "Meeting Follow-up",
+  body: "Thank you for attending...",
+  cc: ["manager@example.com"],
+  importance: "high",
+  bodyType: "text"
+}
+```
+
+### 4. `search-emails`
+Search emails across all fields.
+
+**Parameters:**
+- `query: string` - Search query
+- `limit?: number` (1-50, default: 10) - Max results
+
+**Example:**
+```typescript
+{
+  query: "quarterly report",
+  limit: 15
+}
+```
+
+### 5. `list-folders`
+List all mail folders.
+
+**Parameters:** None
+
+**Returns:** Array of folders with counts and metadata.
+
+## OAuth Configuration
+
+### Authorization URL
+```
+https://login.microsoftonline.com/common/oauth2/v2.0/authorize
+```
+
+### Token URL
+```
+https://login.microsoftonline.com/common/oauth2/v2.0/token
+```
+
+### Scopes
+- `Mail.Read` - Read user mail
+- `Mail.Send` - Send mail
+- `Mail.ReadWrite` - Full mail access
+- `offline_access` - Refresh token
+
+### Token Authentication
+Uses `body` method (credentials sent in request body as form parameters).
+
+## Usage Flow
+
+1. User navigates to `/api/auth/outlook`
+2. Redirected to Microsoft login
+3. User authorizes application
+4. Microsoft redirects to `/api/auth/outlook/callback` with code
+5. Code exchanged for access token
+6. Token stored (in-memory by default)
+7. AI tools can now access Outlook data
+
+## Production Considerations
+
+### Token Storage
+The default `token-store.ts` uses in-memory storage. For production:
+
+1. Replace with database-backed storage
+2. Implement token encryption
+3. Support multiple users with session management
+4. Implement token refresh logic
+
+### Token Refresh
+Access tokens expire after ~1 hour. Implement refresh logic:
+
+```typescript
+import { refreshAccessToken } from './oauth'
+import { getRefreshToken, setTokens } from './token-store'
+
+async function ensureValidToken() {
+  const refreshToken = getRefreshToken()
+  if (refreshToken) {
+    const tokens = await refreshAccessToken(refreshToken)
+    setTokens({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresAt: Date.now() + tokens.expires_in * 1000,
+    })
+  }
+}
+```
+
+### Security
+- Store secrets in environment variables
+- Use HTTPS in production
+- Implement CSRF protection (state parameter)
+- Validate redirect URIs
+- Rate limit API calls
+
+## Microsoft Graph API Resources
+
+- [Microsoft Graph Documentation](https://docs.microsoft.com/graph/)
+- [Mail API Reference](https://docs.microsoft.com/graph/api/resources/mail-api-overview)
+- [Authentication Guide](https://docs.microsoft.com/graph/auth/)
+- [OAuth 2.0 Flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow)
+
+## Troubleshooting
+
+### Common Issues
+
+**"Not authenticated" error**
+- Verify OAuth flow completed successfully
+- Check token storage is working
+- Ensure tokens haven't expired
+
+**"Insufficient permissions" error**
+- Verify all required scopes are requested
+- Check admin consent was granted
+- Ensure API permissions are enabled in Azure
+
+**"Invalid client" error**
+- Verify `MICROSOFT_CLIENT_ID` is correct
+- Check `MICROSOFT_CLIENT_SECRET` is valid
+- Ensure redirect URI matches Azure configuration
+
+## Testing
+
+To test the integration:
+
+1. Start your development server
+2. Navigate to `/api/auth/outlook`
+3. Complete Microsoft OAuth flow
+4. Test AI tools via chat interface
+
+Example prompts:
+- "List my recent emails"
+- "Search for emails about project alpha"
+- "Send an email to john@example.com"
+
+## License
+
+Part of the Veryfront framework.

package/dist/integrations/outlook/connector.json

@@ -0,0 +1,98 @@
+{
+  "name": "outlook",
+  "displayName": "Microsoft Outlook",
+  "icon": "outlook.svg",
+  "description": "Read, send, and manage Outlook emails",
+  "auth": {
+    "type": "oauth2",
+    "provider": "microsoft",
+    "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+    "tokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+    "scopes": [
+      "Mail.Read",
+      "Mail.Send",
+      "Mail.ReadWrite",
+      "offline_access"
+    ],
+    "callbackPath": "/api/auth/outlook/callback",
+    "tokenAuthMethod": "body",
+    "requiredApis": [
+      {
+        "name": "Microsoft Graph API",
+        "enableUrl": "https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade"
+      }
+    ]
+  },
+  "envVars": [
+    {
+      "name": "MICROSOFT_CLIENT_ID",
+      "description": "Microsoft Azure App Client ID (Application ID)",
+      "required": true,
+      "sensitive": false,
+      "docsUrl": "https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade"
+    },
+    {
+      "name": "MICROSOFT_CLIENT_SECRET",
+      "description": "Microsoft Azure App Client Secret",
+      "required": true,
+      "sensitive": true,
+      "docsUrl": "https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade"
+    }
+  ],
+  "tools": [
+    {
+      "id": "list-emails",
+      "name": "List Emails",
+      "description": "List recent emails from inbox or a specific folder",
+      "requiresWrite": false
+    },
+    {
+      "id": "get-email",
+      "name": "Get Email",
+      "description": "Get detailed information about a specific email",
+      "requiresWrite": false
+    },
+    {
+      "id": "send-email",
+      "name": "Send Email",
+      "description": "Send a new email message",
+      "requiresWrite": true
+    },
+    {
+      "id": "search-emails",
+      "name": "Search Emails",
+      "description": "Search emails by query, subject, sender, or date",
+      "requiresWrite": false
+    },
+    {
+      "id": "list-folders",
+      "name": "List Folders",
+      "description": "List all mail folders in the mailbox",
+      "requiresWrite": false
+    }
+  ],
+  "prompts": [
+    {
+      "id": "check-emails",
+      "title": "Check my emails",
+      "prompt": "List my recent unread emails and summarize the most important ones.",
+      "category": "productivity",
+      "icon": "mail"
+    },
+    {
+      "id": "search-emails",
+      "title": "Search my emails",
+      "prompt": "Search my emails for specific topics, senders, or date ranges.",
+      "category": "productivity",
+      "icon": "search"
+    },
+    {
+      "id": "draft-email",
+      "title": "Draft an email",
+      "prompt": "Help me draft a professional email with proper formatting and tone.",
+      "category": "productivity",
+      "icon": "compose"
+    }
+  ],
+  "suggestedWith": ["teams", "calendar", "gmail"]
+}

package/dist/integrations/outlook/files/_env.example

@@ -0,0 +1,8 @@
+# Microsoft Outlook Integration
+# Get these from: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
+
+# Your Microsoft Azure App Client ID (Application ID)
+MICROSOFT_CLIENT_ID=your_client_id_here
+
+# Your Microsoft Azure App Client Secret
+MICROSOFT_CLIENT_SECRET=your_client_secret_here

package/dist/integrations/outlook/files/ai/tools/get-email.ts

@@ -0,0 +1,47 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { getEmail } from "../../lib/outlook-client.ts";
+
+export default tool({
+  id: "get-email",
+  description:
+    "Get detailed information about a specific email, including full body content, recipients, and metadata.",
+  inputSchema: z.object({
+    messageId: z.string().describe("The ID of the email message to retrieve"),
+    includeBody: z.boolean().default(true).describe("Include full email body content"),
+  }),
+  async execute({ messageId, includeBody }) {
+    const message = await getEmail(messageId);
+
+    return {
+      id: message.id,
+      subject: message.subject,
+      from: {
+        name: message.from.emailAddress.name,
+        email: message.from.emailAddress.address,
+      },
+      to: message.toRecipients.map((r) => ({
+        name: r.emailAddress.name,
+        email: r.emailAddress.address,
+      })),
+      cc: message.ccRecipients?.map((r) => ({
+        name: r.emailAddress.name,
+        email: r.emailAddress.address,
+      })),
+      body: includeBody
+        ? {
+          contentType: message.body.contentType,
+          content: message.body.content,
+        }
+        : undefined,
+      bodyPreview: message.bodyPreview,
+      receivedAt: message.receivedDateTime,
+      sentAt: message.sentDateTime,
+      isRead: message.isRead,
+      hasAttachments: message.hasAttachments,
+      importance: message.importance,
+      conversationId: message.conversationId,
+      webLink: message.webLink,
+    };
+  },
+});

package/dist/integrations/outlook/files/ai/tools/list-emails.ts

@@ -0,0 +1,46 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { listEmails } from "../../lib/outlook-client.ts";
+
+export default tool({
+  id: "list-emails",
+  description:
+    "List recent emails from inbox or a specific folder. Returns email metadata including subject, sender, date, and preview.",
+  inputSchema: z.object({
+    folderId: z.string().optional().describe("Folder ID to list emails from (default: inbox)"),
+    limit: z.number().min(1).max(50).default(10).describe("Maximum number of emails to return"),
+    unreadOnly: z.boolean().default(false).describe("Only return unread emails"),
+    orderBy: z.enum(["receivedDateTime desc", "receivedDateTime asc", "subject"]).default(
+      "receivedDateTime desc",
+    ).describe("Sort order for emails"),
+  }),
+  async execute({ folderId, limit, unreadOnly, orderBy }) {
+    const filter = unreadOnly ? "isRead eq false" : undefined;
+
+    const messages = await listEmails({
+      folderId,
+      top: limit,
+      filter,
+      orderBy,
+    });
+
+    return messages.map((msg) => ({
+      id: msg.id,
+      subject: msg.subject,
+      from: {
+        name: msg.from.emailAddress.name,
+        email: msg.from.emailAddress.address,
+      },
+      to: msg.toRecipients.map((r) => ({
+        name: r.emailAddress.name,
+        email: r.emailAddress.address,
+      })),
+      preview: msg.bodyPreview,
+      receivedAt: msg.receivedDateTime,
+      isRead: msg.isRead,
+      hasAttachments: msg.hasAttachments,
+      importance: msg.importance,
+      webLink: msg.webLink,
+    }));
+  },
+});

package/dist/integrations/outlook/files/ai/tools/list-folders.ts

@@ -0,0 +1,22 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { listFolders } from "../../lib/outlook-client.ts";
+
+export default tool({
+  id: "list-folders",
+  description:
+    "List all mail folders in the mailbox, including inbox, sent items, drafts, and custom folders.",
+  inputSchema: z.object({}),
+  async execute() {
+    const folders = await listFolders();
+
+    return folders.map((folder) => ({
+      id: folder.id,
+      name: folder.displayName,
+      parentFolderId: folder.parentFolderId,
+      childFolderCount: folder.childFolderCount,
+      unreadItemCount: folder.unreadItemCount,
+      totalItemCount: folder.totalItemCount,
+    }));
+  },
+});

package/dist/integrations/outlook/files/ai/tools/search-emails.ts

@@ -0,0 +1,41 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { searchEmails } from "../../lib/outlook-client.ts";
+
+export default tool({
+  id: "search-emails",
+  description:
+    "Search emails by query string. Searches across subject, body, sender, and recipients. Supports advanced search syntax.",
+  inputSchema: z.object({
+    query: z.string().min(1).describe("Search query (searches subject, body, from, to fields)"),
+    limit: z.number().min(1).max(50).default(10).describe("Maximum number of results to return"),
+  }),
+  async execute({ query, limit }) {
+    const messages = await searchEmails({
+      query,
+      top: limit,
+    });
+
+    return {
+      totalResults: messages.length,
+      emails: messages.map((msg) => ({
+        id: msg.id,
+        subject: msg.subject,
+        from: {
+          name: msg.from.emailAddress.name,
+          email: msg.from.emailAddress.address,
+        },
+        to: msg.toRecipients.map((r) => ({
+          name: r.emailAddress.name,
+          email: r.emailAddress.address,
+        })),
+        preview: msg.bodyPreview,
+        receivedAt: msg.receivedDateTime,
+        isRead: msg.isRead,
+        hasAttachments: msg.hasAttachments,
+        importance: msg.importance,
+        webLink: msg.webLink,
+      })),
+    };
+  },
+});

package/dist/integrations/outlook/files/ai/tools/send-email.ts

@@ -0,0 +1,41 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { sendEmail } from "../../lib/outlook-client.ts";
+
+export default tool({
+  id: "send-email",
+  description:
+    "Send a new email message. Supports multiple recipients, CC, BCC, and importance levels.",
+  inputSchema: z.object({
+    to: z.array(z.string().email()).min(1).describe("Email addresses of recipients"),
+    subject: z.string().min(1).describe("Email subject line"),
+    body: z.string().min(1).describe("Email body content"),
+    cc: z.array(z.string().email()).optional().describe("Email addresses to CC"),
+    bcc: z.array(z.string().email()).optional().describe("Email addresses to BCC"),
+    importance: z.enum(["low", "normal", "high"]).default("normal").describe(
+      "Email importance level",
+    ),
+    bodyType: z.enum(["text", "html"]).default("text").describe("Body content type (text or html)"),
+  }),
+  async execute({ to, subject, body, cc, bcc, importance, bodyType }) {
+    await sendEmail({
+      to,
+      subject,
+      body,
+      cc,
+      bcc,
+      importance,
+      bodyType,
+    });
+
+    return {
+      success: true,
+      message: `Email sent successfully to ${to.join(", ")}`,
+      recipients: {
+        to,
+        cc,
+        bcc,
+      },
+    };
+  },
+});

package/dist/integrations/outlook/files/app/api/auth/outlook/callback/route.ts

@@ -0,0 +1,11 @@
+/**
+ * Outlook OAuth Callback
+ */
+
+import { createOAuthCallbackHandler, memoryTokenStore, outlookConfig } from "veryfront/oauth";
+
+export const GET = createOAuthCallbackHandler(outlookConfig, {
+  tokenStore: memoryTokenStore,
+  onSuccess: () => "/",
+  onError: () => "/",
+});

package/dist/integrations/outlook/files/app/api/auth/outlook/route.ts

@@ -0,0 +1,9 @@
+/**
+ * Outlook OAuth Initiation
+ */
+
+import { createOAuthInitHandler, memoryTokenStore, outlookConfig } from "veryfront/oauth";
+
+export const GET = createOAuthInitHandler(outlookConfig, {
+  tokenStore: memoryTokenStore,
+});