pywayne-lark-custom-bot

What this skill does

# Pywayne Lark Custom Bot - Webhook Message Sender

## Overview

`LarkCustomBot` is a webhook-based Feishu (Lark) bot wrapper designed for **one-way message pushing**. It's ideal for scenarios where you only need to send messages to Feishu groups without listening for incoming messages or managing complex interactions.

**Key Characteristics**:
- Lightweight, simple webhook-based architecture
- No event subscription or listening capabilities
- Perfect for alerts, notifications, scheduled tasks
- Supports signature verification for security

**When to Use LarkCustomBot**:
- Push-only scenarios (notifications, alerts, reports)
- Simple scheduled tasks sending updates
- Quick setup without event subscription configuration
- Don't need message replies, reactions, or chat management

**When to Use LarkBot Instead**:
- Need to listen and reply to messages
- Require message lifecycle management (recall, edit, reactions)
- Need chat management (members, admins, announcements)
- Interactive features like button callbacks

## Installation

```bash
pip install pywayne
```

## Quick Start

```python
from pywayne.lark_custom_bot import LarkCustomBot

# Initialize bot with webhook
bot = LarkCustomBot(
    webhook="https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxx"
)

# Send simple text message
bot.send_text("Hello, Feishu!")

# Send text with @all mention
bot.send_text("Important announcement!", mention_all=True)
```

## LarkCustomBot Class

### Constructor

```python
bot = LarkCustomBot(
    webhook: str,              # Required: Webhook URL from Feishu group bot settings
    secret: str = '',          # Optional: Signing secret for request verification
    bot_app_id: str = '',      # Optional: App ID for image upload authentication
    bot_secret: str = ''       # Optional: App secret for image upload authentication
)
```

**Parameters**:
- `webhook`: Webhook URL obtained from Feishu group custom bot settings
- `secret`: Signing secret for signature verification (enhances security)
- `bot_app_id`: Required for `upload_image()` and `upload_image_from_cv2()`
- `bot_secret`: Required for `upload_image()` and `upload_image_from_cv2()`

**Note**: Image upload requires app credentials (`bot_app_id` and `bot_secret`) because it uses Feishu's OpenAPI authentication, not webhook.

## Core Methods

### send_text - Send Text Message

Send plain text message with optional @all mention.

```python
bot.send_text(text: str, mention_all: bool = False) -> None
```

**Parameters**:
- `text`: Message text content
- `mention_all`: Whether to @all users in the group (default `False`)

**Examples**:

```python
# Simple text
bot.send_text("Daily backup completed successfully")

# With @all mention
bot.send_text("System maintenance at 23:00 tonight", mention_all=True)

# Multi-line text
bot.send_text("""
Deployment completed:
- API: v1.2.3
- Frontend: v2.4.5
- Database migration: done
""")

# With HTML-like formatting (supported in text messages)
bot.send_text("<b>Bold text</b> and <i>italic text</i>")
```

### send_post - Send Rich Text Post

Send rich text message with structured content including text, links, @mentions, and images.

```python
bot.send_post(
    content: List[List[Dict]],      # 2D list of content elements
    title: Optional[str] = None     # Optional post title
) -> None
```

**Parameters**:
- `content`: 2D list structure where:
  - Outer list = multiple lines
  - Inner list = multiple elements in the same line
- `title`: Post title displayed at the top

**Content Structure**:

```python
content = [
    [element1, element2],  # Line 1 with 2 elements
    [element3],            # Line 2 with 1 element
    [element4, element5],  # Line 3 with 2 elements
]
```

**Basic Example**:

```python
from pywayne.lark_custom_bot import (
    LarkCustomBot,
    create_text_content,
    create_link_content,
    create_at_content,
    create_image_content
)

bot = LarkCustomBot(
    webhook="https://open.feishu.cn/open-apis/bot/v2/hook/xxx",
    bot_app_id="cli_xxx",
    bot_secret="sec_xxx"
)

# Upload image first
image_key = bot.upload_image("/tmp/report.png")

# Construct post content
content = [
    # Line 1: Title text
    [create_text_content("Daily Report", unescape=False)],
    
    # Line 2: Link
    [create_link_content(href="https://dashboard.example.com", text="View Dashboard")],
    
    # Line 3: @mention
    [create_at_content(user_id="all", user_name="Everyone")],
    
    # Line 4: Image
    [create_image_content(image_key=image_key, width=400, height=300)],
    
    # Line 5: Multiple elements in one line
    [
        create_text_content("Status: "),
        create_text_content("✅ Completed", unescape=True)
    ]
]

bot.send_post(content, title="Daily Operations Report")
```

### send_image - Send Image Message

Send image message using image key.

```python
bot.send_image(image_key: str) -> None
```

**Note**: Must upload image first using `upload_image()` or `upload_image_from_cv2()`.

**Example**:

```python
# Upload and send local image
image_key = bot.upload_image("/path/to/chart.png")
bot.send_image(image_key)

# Upload from OpenCV image
import cv2
import numpy as np

img = cv2.imread("/path/to/image.jpg")
# Process image...
image_key = bot.upload_image_from_cv2(img)
bot.send_image(image_key)
```

### send_interactive - Send Interactive Card

Send interactive card message with buttons, forms, or other interactive elements.

```python
bot.send_interactive(card: Dict) -> None
```

**Parameters**:
- `card`: Interactive card JSON structure following Feishu card schema

**Example: Simple Notification Card**:

```python
card = {
    "config": {"wide_screen_mode": True},
    "header": {
        "title": {"tag": "plain_text", "content": "Approval Required"},
        "template": "red"
    },
    "elements": [
        {
            "tag": "markdown",
            "content": "**Ticket #1234** is waiting for approval"
        },
        {
            "tag": "action",
            "actions": [
                {
                    "tag": "button",
                    "text": {"tag": "plain_text", "content": "View Details"},
                    "type": "primary",
                    "url": "https://example.com/ticket/1234"
                }
            ]
        }
    ]
}
bot.send_interactive(card)
```

**Example: Status Card with Multiple Elements**:

```python
card = {
    "header": {
        "title": {"tag": "plain_text", "content": "Build Status"},
        "template": "blue"
    },
    "elements": [
        {
            "tag": "div",
            "text": {"tag": "lark_md", "content": "**Build #456** completed"}
        },
        {
            "tag": "hr"
        },
        {
            "tag": "div",
            "fields": [
                {"is_short": True, "text": {"tag": "lark_md", "content": "**Duration**\n3m 42s"}},
                {"is_short": True, "text": {"tag": "lark_md", "content": "**Status**\n✅ Success"}}
            ]
        }
    ]
}
bot.send_interactive(card)
```

### send_share_chat - Share Chat

Share a chat group as a card.

```python
bot.send_share_chat(share_chat_id: str) -> None
```

**Example**:

```python
# Share a group chat
bot.send_share_chat("oc_a1b2c3d4e5f6g7h8")
```

## Image Upload Methods

### upload_image - Upload from File Path

Upload local image file to Feishu and get image key.

```python
image_key = bot.upload_image(file_path: str) -> str
```

**Parameters**:
- `file_path`: Local path to image file

**Returns**:
- `str`: Image key if successful, empty string if failed

**Example**:

```python
# Upload and send
image_key = bot.upload_image("/tmp/screenshot.png")
if image_key:
    bot.send_image(image_key)
else:
    print("Image upload failed")
```

**Requirements**:
- Must set `bot_app_id` and `bot_secret` in constructor
- File must exist and not be empty
- Supported formats: JPEG, PNG, GIF, etc.

### upload_image_from_cv2 - Upload from OpenCV Image

Upload image directly from OpenCV/numpy array.

```python
image_key = b