zurl

Zurl 短縮リンク管理

Zurl サービス API を使って短縮 URL を管理します。

実行ルール

ユーザーが要求したコマンドを、依存関係、環境変数、設定を事前に確認せずに直接実行してください。問題があれば、スクリプトが明確なエラーを出して失敗します。その場合にのみ確認して修正してください。

重要なルール

1. API URL は環境変数からのみ取得 — ZURL_APIURL を設定する必要があります。API アドレスをハードコードしないでください。
2. 短縮コードを自動生成 — ユーザーがコードを指定せずに URL の短縮を求めた場合、スクリプトは英字と数字を組み合わせた 4 文字のランダムなコードを自動生成します。
3. 作成時にタイトルを指定しない — 新しい短縮リンクのタイトルには空文字列 "" を渡し、Zurl がページタイトルを自動取得するようにしてください。タイトルを自分で入力しないでください。
4. すべてのドメインを表示 — 短縮リンクの作成または更新後は、設定済みの表示ドメイン（ZURL_DISPLAY_URLS から取得。スクリプトの short_links フィールドには完全な URL が含まれます）を必ずすべて表示してください。
5. QR コードのドメイン — QR コードを生成する場合は、ユーザーが指定しない限り、ZURL_DISPLAY_URLS の最初のドメインを QR コードの内容として使用してください。

環境変数

変数	必須	説明
ZURL_APIURL	✅	API のベース URL。例：http://192.168.1.100:3088
ZURL_TOKEN	❌	API 認証トークン（サーバーで認証が有効な場合は必須）
ZURL_DISPLAY_URLS	❌	カンマ区切りの表示ドメイン一覧。デフォルトは ZURL_APIURL

スクリプトはこれらの変数を ~/.wmyskills/.env（複数のスキルで共有）から自動的に読み込みます。スクリプトディレクトリに scripts/.env がある場合は、そちらが優先されます。テンプレートとして scripts/.env.example を使用してください。変数は ~/.wmyskills/.env に追加し、既存のファイルを上書きしないでください。

要件

pip install python-dotenv

使い方

スクリプト：scripts/zurl_api.py

短縮 URL を作成する

python scripts/zurl_api.py shorten <long_url> [short_code] [title] [description] [ttl_days]

引数	必須	説明
long_url	✅	元の長い URL
short_code	❌	カスタム短縮コード。省略した場合は 4 文字のコードを自動生成
title	❌	タイトル（自動取得する場合は空のままにします）
description	❌	説明
ttl_days	❌	有効期間（日数）

短縮 URL を更新する

python scripts/zurl_api.py update <id> [long_url] [short_code] [title] [description] [ttl_days]

引数	必須	説明
id	✅	URL のデータベース ID（一覧または検索結果から取得）
long_url	❌	新しい長い URL
short_code	❌	新しい短縮コード
title	❌	新しいタイトル
description	❌	新しい説明
ttl_days	❌	新しい有効期間（日数）

スクリプトは None（未設定）の引数をスキップし、API に送信しません。API が long_url または short_code を必須とする場合、これらを省略すると 422 エラーになります。フィールドをクリアするには ""（空文字列）を渡してください。API の 500 エラーを避けるため、short_code は空でない値にする必要があります。空の値はスキップされます。

短縮 URL を編集する（key=value 形式）

# Update specific fields using -o key=value (repeatable)
python scripts/zurl_api.py edit <id> -o long_url=https://new.url -o title="New Title"

引数	必須	説明
id	✅	URL のデータベース ID（一覧または検索結果から取得）
-o / --option	✅	key=value のペア（繰り返し指定可能）。キー：long_url、short_code、title、description、ttl_days

これは位置引数の代わりに -o key=value のペアを使う、update の代替方法です。-o で指定したフィールドのみ変更され、指定していないフィールドはそのままです（update では省略した位置引数は送信されませんが、空の "" を指定するとフィールドがクリアされます）。

短縮 URL を削除する

# Delete by short code
python scripts/zurl_api.py delete <short_code>

# Batch delete by short codes (comma-separated)
python scripts/zurl_api.py delete-batch code1,code2,code3

delete-batch は短縮コード（スラッグ）を受け取ります。スクリプトはすべてのページを対象に対応するデータベース ID を検索してから削除します。どの URL にも一致しないコードは、通知せずにスキップされます。

一覧表示と検索

# List short URLs (paginated)
python scripts/zurl_api.py list [page] [limit]

# Search
python scripts/zurl_api.py search <keyword> [filter_type]

filter_type：all（デフォルト）／long_url／short_url／title

URL のメタデータを取得する

python scripts/zurl_api.py metadata <url>

リンク先ページのタイトルと説明を返します。

ユーザーへの表示

短縮リンクを作成または更新した後、JSON レスポンスを解析し、short_links フィールド（ZURL_DISPLAY_URLS で設定）を使用して結果をユーザーに表示します。例：

✅ Short URL created

Short Links:
  https://short.example.com/abc123
  https://s.example.com/abc123

Original URL: https://very-long-url.com/page
Title: Page Title

実際のドメインは ZURL_DISPLAY_URLS で指定します。上記の例は説明用です。

検証済み API エンドポイント

エンドポイント	メソッド	ステータス
/api/shorten_url	POST JSON	✅
/api/update_url/{id}	POST JSON	✅
/api/delete/url	POST form	✅
/api/delete/urls	POST JSON	✅
/api/urls	GET	✅
/api/search	POST JSON	✅
/api/get_url_metadata	POST form	✅

レスポンス形式

スクリプトは JSON を標準出力に出力します。

成功（short_links を含むコマンド）：

{"code": 200, "msg": "...", "data": {"short_url": "abc123", "long_url": "...", ...}, "short_links": ["https://s.example/abc123", ...]}

short_links フィールドは shorten、update、list、search によって追加されます。その他のコマンド（delete、delete-batch、metadata）は、加工せずに API レスポンスを返します。

成功（short_links を含まないコマンド）：

{"code": 200, "msg": "...", "data": {...}}

失敗：

{"error": true, "status": 4XX, "detail": {...}}