commit 7cac4eb12701da5e167ff70fc8f2fa3260287410 Author: Timmy Date: Fri Mar 20 00:43:56 2026 +0800 Initial commit: Last-Z Gift Center CLI Co-Authored-By: Claude Sonnet 4.6 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..69cac2e --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.env +.venv/ +__pycache__/ +*.pyc diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4ed97b2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,31 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Commands + +```bash +# Install dependencies +pip install -r requirements.txt + +# Run the CLI +python giftcenter.py login +python giftcenter.py redeem + +# Override UID without editing .env +python giftcenter.py --uid login +python giftcenter.py --uid redeem +``` + +## Configuration + +UID is read from the `UID` environment variable, typically set in `.env`. The `--uid` flag on any subcommand overrides it. + +## Architecture + +Single-file Python CLI (`giftcenter.py`) using `argparse` subcommands: + +- `login` → `cmd_login()` — GET `/getcodeuser.php?uid=...`, displays account info +- `redeem ` → `cmd_redeem()` — GET `/code.php` with `Usertoken` header and `uid`/`code` params + +API responses use numeric error codes (`code` field) for login and string error codes (`errorCode` field, value `"ok"` on success) for redemption. Error mappings are in `LOGIN_ERRORS` and `REDEEM_ERRORS` constants. UI text is in Traditional Chinese. diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..b6978c1 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,33 @@ +# 快速開始 + +## 1. 安裝依賴 + +```bash +pip install -r requirements.txt +``` + +## 2. 設定 UID + +建立 `.env` 檔案： + +```bash +echo "UID=your_uid_here" > .env +``` + +將 `your_uid_here` 替換為你的實際 UID。 + +## 3. 確認帳號 + +```bash +python giftcenter.py login +``` + +看到「登入成功」即代表設定正確。 + +## 4. 兌換禮品碼 + +```bash +python giftcenter.py redeem ABCD1234 +``` + +成功時顯示「兌換成功！」，失敗時會說明原因（碼不存在、已過期、已使用等）。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..f6b5a86 --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# lastz-giftcenter-cli + +Last-Z Gift Center 的命令列工具，支援查詢帳號資訊與兌換禮品碼。 + +## 安裝 + +```bash +pip install -r requirements.txt +``` + +## 設定 + +在專案根目錄建立 `.env` 檔案，填入你的 UID： + +``` +UID=your_uid_here +``` + +或在執行指令時以 `--uid` 旗標直接指定。 + +## 使用方式 + +### 查詢帳號資訊 + +```bash +python giftcenter.py login +``` + +輸出範例： + +``` +登入成功 + 名稱 : 玩家名稱 + UID : 1234567890 + SID : S001 + 國家 : TW + 等級 : 50 +``` + +### 兌換禮品碼 + +```bash +python giftcenter.py redeem <禮品碼> +``` + +### 指定 UID（覆蓋 .env） + +```bash +python giftcenter.py --uid login +python giftcenter.py --uid redeem <禮品碼> +``` + +## 依賴套件 + +- [requests](https://docs.python-requests.org/) +- [python-dotenv](https://github.com/theskumar/python-dotenv) diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..db274fe --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,28 @@ +# 專案總覽 + +## 簡介 + +`lastz-giftcenter-cli` 是一個輕量的 Python 命令列工具，用於與 Last-Z Gift Center（`https://giftcenter.last-z.com`）互動，提供帳號查詢與禮品碼兌換功能。 + +## 檔案結構 + +| 檔案 | 說明 | +|------|------| +| `giftcenter.py` | 主程式，包含所有邏輯 | +| `requirements.txt` | Python 依賴套件 | +| `.env` | 本地環境設定（UID） | + +## 功能 + +| 指令 | API 端點 | 說明 | +|------|----------|------| +| `login` | `GET /getcodeuser.php` | 查詢帳號名稱、SID、國家、等級 | +| `redeem ` | `GET /code.php` | 兌換禮品碼 | + +## 技術細節 + +- **語言**：Python 3 +- **依賴**：`requests`、`python-dotenv` +- **認證**：UID 透過 query string 及 `Usertoken` header 傳遞 +- **錯誤處理**：login 使用數字錯誤碼，redeem 使用字串錯誤碼（`"ok"` 代表成功） +- **介面語言**：繁體中文 diff --git a/giftcenter.py b/giftcenter.py new file mode 100644 index 0000000..d555a8b --- /dev/null +++ b/giftcenter.py @@ -0,0 +1,121 @@ +#!/usr/bin/env python3 +"""Last-Z Gift Center CLI""" + +import argparse +import os +import sys + +import requests +from dotenv import load_dotenv + +load_dotenv() + +BASE_URL = "https://giftcenter.last-z.com" + +LOGIN_ERRORS = { + 10006: "Token 已過期", + 10007: "請稍後再試", + 10017: "需要充值記錄", + 10018: "UID 不存在", + 10019: "不支援的幣別", + 10020: "操作過於頻繁", + 10022: "帳號警告", + 10023: "不支援的地區", + 10024: "帳號已刪除", + 10002001: "系統錯誤", + 10002002: "請求逾時", + 10002003: "未預期的錯誤", +} + +REDEEM_ERRORS = { + "E001": "系統錯誤", + "E002": "系統錯誤", + "E003": "系統錯誤", + "E004": "禮品碼不存在", + "E005": "禮品碼已過期", + "E006": "禮品碼已被使用", + "E007": "兌換次數已達上限", + "E008": "系統錯誤", + "E009": "請稍後再試", +} + + +def get_uid(): + uid = os.getenv("UID") + if not uid: + print("錯誤：請在 .env 設定 UID=your_uid_here", file=sys.stderr) + sys.exit(1) + return uid + + +def cmd_login(args): + uid = args.uid or get_uid() + try: + resp = requests.get(f"{BASE_URL}/getcodeuser.php", params={"uid": uid}, timeout=10) + resp.raise_for_status() + data = resp.json() + except requests.RequestException as e: + print(f"請求失敗：{e}", file=sys.stderr) + sys.exit(1) + + if data.get("code") == 0: + r = data["result"] + print(f"登入成功") + print(f" 名稱 : {r.get('name')}") + print(f" UID : {uid}") + print(f" SID : {r.get('sid')}") + print(f" 國家 : {r.get('country')}") + print(f" 等級 : {r.get('level')}") + else: + code = data.get("code", 10002001) + print(f"登入失敗：{LOGIN_ERRORS.get(code, f'錯誤碼 {code}')}", file=sys.stderr) + sys.exit(1) + + +def cmd_redeem(args): + uid = args.uid or get_uid() + code = args.code + try: + resp = requests.get( + f"{BASE_URL}/code.php", + headers={"Usertoken": uid}, + params={"uid": uid, "code": code}, + timeout=10, + ) + resp.raise_for_status() + data = resp.json() + except requests.RequestException as e: + print(f"請求失敗：{e}", file=sys.stderr) + sys.exit(1) + + error_code = data.get("errorCode") + if error_code == "ok": + print(f"兌換成功！禮品碼 {code} 已套用") + else: + msg = REDEEM_ERRORS.get(error_code, f"未知錯誤碼 {error_code}") + print(f"兌換失敗：{msg}", file=sys.stderr) + sys.exit(1) + + +def main(): + parser = argparse.ArgumentParser(description="Last-Z Gift Center CLI") + parser.add_argument("--uid", help="指定 UID（覆蓋 .env）") + sub = parser.add_subparsers(dest="command", required=True) + + # login + p_login = sub.add_parser("login", help="登入並查看帳號資訊") + p_login.add_argument("--uid", help="指定 UID（覆蓋 .env）") + p_login.set_defaults(func=cmd_login) + + # redeem + p_redeem = sub.add_parser("redeem", help="兌換禮品碼") + p_redeem.add_argument("code", help="禮品碼") + p_redeem.add_argument("--uid", help="指定 UID（覆蓋 .env）") + p_redeem.set_defaults(func=cmd_redeem) + + args = parser.parse_args() + args.func(args) + + +if __name__ == "__main__": + main() diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..df7458c --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +requests +python-dotenv