# Feishu Calendar Meeting Service

## Features
- Create Feishu video meetings
- Automatically add calendar ACL for attendees
- Invite group members to meeting

## Usage

```bash
# Install dependencies
cd /home/openclaw/.openclaw/workspace/skills/feishu-calendar
npm install @larksuiteoapi/node-sdk

# Create meeting
node calendar-service.js \
  --summary "Team Meeting" \
  --start "2026-03-26 14:00" \
  --end "2026-03-26 15:00" \
  --attendees "ou_025d45982cf54c1d82c2c6d0738e283f"
```

## Parameters
- `--summary`: Meeting title
- `--start`: Start time (format: YYYY-MM-DD HH:MM)
- `--end`: End time (format: YYYY-MM-DD HH:MM)
- `--attendees`: Attendee open_ids, comma separated
- `--description`: Meeting description (optional)

## Programmatic Usage
```javascript
import { createMeeting } from './calendar-service.js';

const result = await createMeeting({
  summary: 'Team Meeting',
  start: '2026-03-26 14:00',
  end: '2026-03-26 15:00',
  attendees: ['ou_025d45982cf54c1d82c2c6d0738e283f']
});

console.log(result.meetingUrl); // Feishu meeting join URL
```

## Core Flow
1. **Permission Check** - Check if Feishu app has sufficient permissions, prompt user to enable missing permissions
2. **ACL Authorization** - Add user to bot calendar members
3. **Create Meeting** - Create event on bot calendar, auto-generate Feishu video meeting
4. **Invite Attendees** - Add users as meeting attendees

## Permission Check Logic

Before any calendar operation, call `feishu_app_scopes` to check permissions:

```javascript
const REQUIRED_PERMISSIONS = [
  'calendar:calendar.event:read',
  'calendar:calendar.event:create',
  'calendar:calendar.event:update',
  'calendar:calendar.event:delete',
  'calendar:calendar.event:reply',
  'calendar:calendar:read',
  'calendar:calendar:create',
  'calendar:calendar:update',
  'calendar:calendar:delete',
  'calendar:calendar.acl:read',
  'calendar:calendar.acl:create',
  'calendar:calendar.free_busy:read',
  'calendar:room',
  'calendar:room:readonly',
  'calendar:settings.workhour:read',
  'contact:user.base:readonly',
  'contact:user.id:readonly',
  'contact:user.basic_profile:readonly',
  'im:message:send_as_bot'
];

async function checkPermissions() {
  const { granted } = await feishu_app_scopes();
  const grantedSet = new Set(granted.map(p => p.name));
  
  const missing = REQUIRED_PERMISSIONS.filter(p => !grantedSet.has(p));
  
  if (missing.length > 0) {
    return {
      ready: false,
      missing,
      message: `Missing permissions, please enable them in Feishu Open Platform:\n${missing.join('\n')}`
    };
  }
  
  return { ready: true, missing: [] };
}
```

### Handling Missing Permissions

Return the specific missing permissions list and prompt user:

> ❌ Current Feishu app is missing the following permissions, please enable them in Feishu Open Platform:
> - calendar:calendar.event:create
> - calendar:calendar.acl:create
> - ...

Re-check after enabling permissions until requirements are met.

## Permission Requirements

The following Feishu app permissions need to be enabled for calendar subscription feature:

```json
{
  "permissions": [
    "calendar:calendar.event:read",
    "calendar:calendar.event:create",
    "calendar:calendar.event:update",
    "calendar:calendar.event:delete",
    "calendar:calendar.event:reply",
    "calendar:calendar:read",
    "calendar:calendar:create",
    "calendar:calendar:update",
    "calendar:calendar:delete",
    "calendar:calendar.acl:read",
    "calendar:calendar.acl:create",
    "calendar:calendar.free_busy:read",
    "calendar:room",
    "calendar:room:readonly",
    "calendar:settings.workhour:read",
    "contact:user.base:readonly",
    "contact:user.id:readonly",
    "contact:user.basic_profile:readonly",
    "im:message:send_as_bot"
  ]
}
```

### Permission Usage

| Permission | Usage |
|------------|-------|
| `calendar:calendar.event:*` | Read/Create/Update/Delete/Reply calendar events |
| `calendar:calendar:*` | Manage calendars |
| `calendar:calendar.acl:*` | Manage calendar access permissions (add users to calendar) |
| `calendar:calendar.free_busy:read` | Query free/busy status |
| `calendar:room*` | Query meeting rooms |
| `calendar:settings.workhour:read` | Read working hours settings |
| `contact:user.*` | Get user basic info (ID, name, avatar) |
| `im:message:send_as_bot` | Push meeting notifications |

## Configuration

Required environment variables:

```bash
# Feishu App credentials (required)
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
export FEISHU_BOT_CALENDAR_ID="feishu.cn_xxx@group.calendar.feishu.cn"
```

### How to Get BOT_CALENDAR_ID

Each Feishu app automatically has a bot calendar created by Feishu. To get its ID:

1. **Enable Permission**: Go to Feishu Open Platform → Your App → Permissions, enable `calendar:calendar:readonly`

2. **Call API**: Use the app's access token to fetch calendars:

```bash
curl -X GET "https://open.feishu.cn/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer $APP_ACCESS_TOKEN"
```

3. **Find in Response**: The response contains `cal_id` for the bot calendar:

```json
{
  "data": {
    "calendars": [
      {
        "cal_id": "feishu.cn_EPu3AO4pwLcphoqYnU0xBf@group.calendar.feishu.cn",
        "name": "Bot Calendar",
        "role": "owner"
      }
    ]
  }
}
```

**Note**: Each Feishu app has exactly one bot calendar, created automatically by Feishu. You cannot create it manually - it's system-generated.

## Notes
- All three environment variables (FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_BOT_CALENDAR_ID) are required - no defaults
- Bot calendar ID format: `feishu.cn_EPu3AO4pwLcphoqYnU0xBf@group.calendar.feishu.cn`