lark

What this skill does

## Troubleshooting

If Lark requests fail after the Lark connector is connected, check the runtime token and API access:

```bash
zero doctor check-connector --env-name LARK_TOKEN
zero doctor check-connector --url https://open.larksuite.com/open-apis/bot/v3/info --method GET
```

`LARK_TOKEN` is the Lark API bearer token available after the Lark connector is connected; do not use it as an app secret.

## Authentication Helper

Use this helper in shell examples to read the bearer token and fail clearly when it is missing from the runtime:

```bash
get_lark_token() {
  if [ -z "${LARK_TOKEN:-}" ]; then
    echo "Error: LARK_TOKEN is not set. Connect the Lark connector, then run zero doctor check-connector --env-name LARK_TOKEN." >&2
    return 1
  fi
  printf '%s\n' "$LARK_TOKEN"
}

# Usage in commands
TOKEN=$(get_lark_token)
```

## Examples

### 1. Authentication - Verify Token

```bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/bot/v3/info" \
  -H "Authorization: Bearer ${TOKEN}"
```

### 2. Messaging - Send Messages

#### Send Text Message to User

Write to `/tmp/lark_request.json`:
```json
{
  "receive_id": "ou_xxx",
  "msg_type": "text",
  "content": "{\"text\": \"Hello World\"}"
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### Send Text Message to Group Chat

Write to `/tmp/lark_request.json`:
```json
{
  "receive_id": "oc_xxx",
  "msg_type": "text",
  "content": "{\"text\": \"Group message\"}"
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### Send Rich Text (Post) Message

Write to `/tmp/lark_request.json`:
```json
{
  "receive_id": "ou_xxx",
  "msg_type": "post",
  "content": "{\"zh_cn\": {\"title\": \"Title\", \"content\": [[{\"tag\": \"text\", \"text\": \"Content\"}]]}}"
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### Send Interactive Card Message

Write to `/tmp/lark_request.json`:
```json
{
  "receive_id": "oc_xxx",
  "msg_type": "interactive",
  "content": "{\"header\": {\"title\": {\"tag\": \"plain_text\", \"content\": \"Alert\"}}, \"elements\": [{\"tag\": \"div\", \"text\": {\"tag\": \"plain_text\", \"content\": \"Message\"}}]}"
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### Reply to Message

Write to `/tmp/lark_request.json`:
```json
{
  "msg_type": "text",
  "content": "{\"text\": \"Reply content\"}"
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages/om_xxx/reply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### Get Chat History

```bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/im/v1/messages?container_id_type=chat&container_id=oc_xxx&page_size=20" \
  -H "Authorization: Bearer ${TOKEN}"
```

### 3. Chat Management - Group Operations

#### Create Group Chat

Write to `/tmp/lark_request.json`:
```json
{
  "name": "Project Team",
  "description": "Project discussion group",
  "user_id_list": ["ou_xxx", "ou_yyy"]
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/chats?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### List All Chats

```bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/im/v1/chats" \
  -H "Authorization: Bearer ${TOKEN}"
```

#### Get Chat Info

```bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/im/v1/chats/oc_xxx" \
  -H "Authorization: Bearer ${TOKEN}"
```

#### Add Members to Chat

Write to `/tmp/lark_request.json`:
```json
{
  "id_list": ["ou_xxx", "ou_yyy"]
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/chats/oc_xxx/members?member_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### Remove Members from Chat

Write to `/tmp/lark_request.json`:
```json
{
  "id_list": ["ou_xxx"]
}
```

```bash
TOKEN=$(get_lark_token)
curl -X DELETE "https://open.larksuite.com/open-apis/im/v1/chats/oc_xxx/members?member_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

### 4. Contacts - Directory Queries

#### Get User Info

```bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/contact/v3/users/ou_xxx?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}"
```

#### Look Up User IDs by Email or Mobile

Write to `/tmp/lark_request.json`:
```json
{
  "emails": ["[email protected]"],
  "mobiles": ["+15551234567"],
  "include_resigned": false
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/contact/v3/users/batch_get_id?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### List Departments

```bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/contact/v3/departments?parent_department_id=0" \
  -H "Authorization: Bearer ${TOKEN}"
```

#### Get Department Members

```bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/contact/v3/users/find_by_department?department_id=od_xxx&user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}"
```

### 5. Calendar - Schedule Management

#### List Calendars

```bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer ${TOKEN}"
```

#### Create Calendar

Write to `/tmp/lark_request.json`:
```json
{
  "summary": "Project Calendar",
  "description": "Calendar for project events"
}
```

```bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### Create Calendar Event

Note: Replace `<calendar_id>` with an actual calendar ID from List Calendars API.

```bash
TOKEN=$(get_lark_token)

# Convert ISO 8601 to Unix timestamp
START_TS=$(date -d "2025-01-15T10:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T10:00:00+08:00" +%s)
END_TS=$(date -d "2025-01-15T11:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T11:00:00+08:00" +%s)

# Write request with timestamps
cat > /tmp/lark_request.json <<EOF
{
  "summary": "Team Meeting",
  "description": "Weekly sync",
  "start_time": {"timestamp": "${START_TS}"},
  "end_time": {"timestamp": "${END_TS}"}
}
EOF

curl -X POST "https://open.larksuite.com/open-apis/calendar/v4/calendars/<calendar_id>/events" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
```

#### List Calendar Events

```bash
TOKEN=$(get_lark_token)

# Convert date range
START_TS=$(date -d "2025-01-01T00:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-01T00:00:00+08:00" +%s)
END_TS=$(date -d "2025-01-31T23:59:59+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-31T23:59:59+08:00" +%s)

curl -X GET "https://open