flomo-send

# Flomo via App

Send notes to flomo using URL Scheme, with automatic webhook fallback for reliability.

> ⚠️ **首次使用提示**: 安装后请先运行 `./scripts/configure.sh` 进行配置

## Quick Start

### 1. 配置（首次使用必需）

```bash
./scripts/configure.sh
```

运行后会交互式询问：
1. 是否有 flomo PRO 账户
2. Webhook token/URL
3. 保存位置（默认保存到 skill 目录的 `.env` 文件）

配置默认保存到 `.env` 文件，这样更便于管理和隔离。

### 2. 发送笔记

```bash
scripts/flomo_send.sh "Your note content" "#tag1 #tag2"
```

Or manually via URL scheme:

```bash
open "flomo://create?content=Hello%20World&tag=daily"
```

## How It Works

The script uses a **dual-channel strategy** for maximum reliability:

1. **Primary:** URL Scheme → Opens flomo app directly (instant, local)
2. **Fallback:** Webhook API → HTTP POST to flomo servers (works without app)

If the flomo app is not installed or `open` command fails, it automatically falls back to webhook.

## Script Usage

### Basic Usage

```bash
# Simple note
./scripts/flomo_send.sh "My quick thought"

# With tags
./scripts/flomo_send.sh "Meeting notes from today" "#work #meeting"

# From clipboard
./scripts/flomo_send.sh "$(pbpaste)" "#clippings"

# From stdin
echo "Note from pipe" | ./scripts/flomo_send.sh
```

### Webhook Configuration (Optional)

If you ran `./scripts/configure.sh` during setup, webhook is already configured.

To manually configure, set environment variable:

```bash
# Option 1: Full webhook URL
export FLOMO_WEBHOOK_URL="https://flomoapp.com/iwh/xxxxxxxxxxxxxxxx"

# Option 2: Just the token
export FLOMO_WEBHOOK_TOKEN="xxxxxxxxxxxxxxxx"

# Then run script
./scripts/flomo_send.sh "Note with fallback" "#test"
```

## Supported Actions

### Send Text Note
```bash
./scripts/flomo_send.sh "Your note here"
```

### Send with Tags
Tags in format `#tagname` will be automatically parsed by flomo.

```bash
./scripts/flomo_send.sh "Reading notes" "#books #learning"
```

### Multi-line Notes
```bash
./scripts/flomo_send.sh "Line 1
Line 2
Line 3" "#journal"
```

### Send with Images (URL Scheme only)
**Note:** The `flomo_send.sh` script currently supports text only. To send images, use URL Scheme directly:

```bash
# Via URL Scheme directly (supports up to 9 images)
open "flomo://create?image_urls=%5B%22https://example.com/img1.jpg%22%5D&content=Photo%20notes"
```

Image URLs must be:
- Publicly accessible URLs
- URL-encoded JSON array format
- Maximum 9 images per note

See [references/api.md](references/api.md) for more details on image parameters.

## URL Scheme Format

Direct URL scheme usage (macOS only):

- **Base URL:** `flomo://create`
- **Parameters:**
  - `content` (optional): The note content, URL-encoded, max 5000 chars
  - `image_urls` (optional): JSON array of image URLs, URL-encoded, max 9 images

### Examples

**Text only:**
```bash
open "flomo://create?content=Your%20URL-encoded%20content"
```

**With images:**
```bash
open "flomo://create?image_urls=%5B%22https://example.com/img.jpg%22%5D&content=Photo%20notes"
```

The `image_urls` parameter format:
- JSON array of publicly accessible image URLs
- Must be URL-encoded with `encodeURIComponent`

## Examples

**Save a link:**
```bash
./scripts/flomo_send.sh "https://example.com/article" "#readlater #tech"
```

**Daily journal:**
```bash
./scripts/flomo_send.sh "Morning reflection: feeling productive today" "#journal"
```

**Quick idea capture:**
```bash
./scripts/flomo_send.sh "App idea: AI-powered plant water reminder" "#ideas"
```

**Remote/SSH session (uses webhook):**
```bash
export FLOMO_WEBHOOK_TOKEN="your-token"
./scripts/flomo_send.sh "Note from server" "#server-log"
```

## Requirements

⚠️ **API 和 URL Scheme 功能需要 [flomo PRO 会员](https://flomoapp.com/mine?source=incoming_webhook) 才能使用。**

### URL Scheme (Primary)
- macOS with flomo app installed
- flomo app v1.5+ (supports URL Scheme)
- flomo PRO 会员

### Webhook Fallback
- `curl` command available
- `FLOMO_WEBHOOK_URL` or `FLOMO_WEBHOOK_TOKEN` environment variable set
- flomo PRO 会员

### Limitations
- **Content**: Maximum 5000 characters (before URL encoding)
- **Images**: Maximum 9 images per note (URL Scheme only; webhook does not support images)

## Configuration

### Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `FLOMO_WEBHOOK_URL` | Full webhook URL | `https://flomoapp.com/iwh/abc123` |
| `FLOMO_WEBHOOK_TOKEN` | Webhook token only | `abc123` |

### Persistent Configuration

Add to your `~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`:

```bash
export FLOMO_WEBHOOK_TOKEN="your-webhook-token-here"
```

## Troubleshooting

**"Error: Webhook not configured"**
→ Set `FLOMO_WEBHOOK_URL` or `FLOMO_WEBHOOK_TOKEN` environment variable

**"Error: flomo URL scheme failed"**
→ Normal if app not installed; check if webhook fallback succeeded

**Unicode/Chinese characters not working**
→ The script auto-encodes UTF-8; if issues persist, check Python3 availability

## API Reference

For detailed webhook API documentation, see [references/api.md](references/api.md).