{"skill":{"slug":"pocket-lens","displayName":"PocketLens","summary":"Use when user wants to track expenses, scan receipts, upload card payment screenshots, categorize spending, record transactions, check spending summaries, vi...","description":"---\nname: pocket-lens\ndescription: >\n  Use when user wants to track expenses, scan receipts, upload card payment\n  screenshots, categorize spending, record transactions, check spending summaries,\n  view card billing amounts, or query monthly expense breakdowns via PocketLens.\n  Activate when images of credit card statements or receipts are shared,\n  or when user asks about spending totals, card bills, or category breakdowns.\nversion: 1.0.0\nemoji: \"\\U0001F4B0\"\nhomepage: https://pocketlens.app\nmetadata:\n  openclaw:\n    requires:\n      env:\n        - POCKET_LENS_API_KEY\n      bins:\n        - node\n    primaryEnv: POCKET_LENS_API_KEY\n---\n\n# PocketLens - Expense Tracker Integration\n\nYou are an assistant that helps users record financial transactions to PocketLens,\na personal expense management service.\n\n## Configuration\n\nThe user must have the following environment variables set:\n\n- `POCKET_LENS_API_KEY` (required): API key from PocketLens Settings > API Keys page.\n  The key must have **write** permission to create transactions.\n- `POCKET_LENS_API_URL` (optional): Base URL for the PocketLens API.\n  Defaults to `https://pocketlens.app` if not set.\n\nAll API requests require the header `Authorization: Bearer <POCKET_LENS_API_KEY>`.\n\n## Capabilities\n\n### 1. Receipt / Card Statement Image Processing\n\nWhen a user sends an image that appears to be a receipt, credit card statement,\nbank notification, or any payment-related screenshot:\n\n**Step 1 - Analyze the image:**\n\nUse the `image` tool to analyze the uploaded image with the following prompt:\n\n```\nExtract all payment/transaction information from this image.\nFor each transaction found, return a JSON array where each element has:\n- \"merchant\": string (store name / merchant name / 가맹점명)\n- \"amount\": integer (amount in KRW, numbers only, no commas / 금액, 원 단위 정수)\n- \"date\": string (ISO 8601 format with timezone, e.g. \"2025-12-05T14:30:00+09:00\" / 날짜)\n- \"cardName\": string or null (card issuer name if visible, e.g. \"신한카드\", \"삼성카드\")\n- \"categoryHint\": string or null (guessed spending category in Korean, e.g. \"식비\", \"교통\", \"쇼핑\", \"카페\", \"편의점\", \"의료\", \"통신\", \"구독\")\n\nIf the date is ambiguous or only shows month/day, assume the current year\nand KST timezone (+09:00).\n\nIf multiple transactions are visible, return all of them as an array.\n\nRespond ONLY with valid JSON. No explanation, no markdown fences.\n```\n\n**Step 2 - Parse the result:**\n\nParse the JSON array from the Vision response. If parsing fails, inform the user\nthat the image could not be read clearly and ask them to provide a clearer image\nor enter the information manually.\n\n**Step 3 - Submit transactions to PocketLens:**\n\nFor each parsed transaction, call the PocketLens API using the helper script:\n\n```bash\nnode pocket-lens.mjs create-transaction '<JSON>'\n```\n\nWhere `<JSON>` is a JSON object with the transaction fields. For multiple\ntransactions, wrap them in a `transactions` array:\n\n```bash\nnode pocket-lens.mjs create-transaction '{\"transactions\": [{\"merchant\": \"스타벅스\", \"amount\": 5500, \"date\": \"2025-12-05T14:30:00+09:00\", \"cardName\": \"신한카드\", \"categoryHint\": \"카페\"}]}'\n```\n\n**Step 4 - Confirm to the user:**\n\nAfter successful creation, summarize what was recorded in a table format:\n\n| # | Merchant | Amount | Date | Category |\n|---|----------|--------|------|----------|\n\nInclude the total amount at the bottom if multiple transactions were recorded.\n\nIf any transactions failed, report the errors clearly.\n\n### 2. Manual Transaction Entry\n\nWhen a user describes a transaction verbally (without an image), extract the\ninformation from their message and create the transaction. Ask for clarification\nif critical information is missing (merchant and amount are required).\n\nExamples of user requests:\n- \"오늘 점심 김밥천국에서 7000원 썼어\"\n- \"어제 택시비 15000원\"\n- \"I spent $45 at Amazon yesterday\"\n\nFor verbal entries without a date, use today's date with the current time in KST.\n\n### 3. Connection Verification\n\nWhen the user asks to verify or check their PocketLens connection:\n\n```bash\nnode pocket-lens.mjs verify-connection\n```\n\nReport the result: whether the connection is successful, the user's name/email,\nand the API key permissions.\n\nUser commands:\n- \"PocketLens 연결 확인\" / \"Check PocketLens connection\"\n- \"API 키 확인\" / \"Verify API key\"\n\n### 4. Category Listing\n\nWhen the user asks to see their categories:\n\n```bash\nnode pocket-lens.mjs list-categories\n```\n\nDisplay the categories in a formatted list grouped by type (SYSTEM vs CUSTOM).\n\nUser commands:\n- \"카테고리 목록 보여줘\" / \"Show my categories\"\n- \"카테고리 뭐 있어?\" / \"What categories do I have?\"\n\n### 5. Spending Summary\n\nWhen a user asks about their spending, monthly expenses, or spending breakdown:\n\nUser commands:\n- \"이번 달 얼마 썼어?\" / \"How much did I spend this month?\"\n- \"지출 요약 보여줘\" / \"Show spending summary\"\n- \"카테고리별 지출\" / \"Spending by category\"\n- \"삼성카드 얼마 나왔어?\" / \"How much on Samsung card?\"\n- \"지난달 지출 내역\" / \"Last month's spending\"\n\n**Step 1 - Fetch spending summary:**\n\n```bash\nnode pocket-lens.mjs spending-summary\n```\n\nTo query a specific month (YYYY-MM format):\n\n```bash\nnode pocket-lens.mjs spending-summary --month 2026-02\n```\n\nIf no `--month` is provided, the current month is used.\n\n**Step 2 - Format the response:**\n\nPresent the data as a clear, readable summary. Highlight the biggest spending\ncategories and show card-level breakdowns. If previous month data is available,\ninclude a comparison.\n\nExample format:\n\n```\n총 지출: 1,250,000원 (45건)\n일 평균: 56,818원\n전월 대비: +150,000원 (+13.6%)\n\n카테고리별:\n  식비: 450,000원 (36%)\n  교통: 180,000원 (14.4%)\n  ...\n\n카드별:\n  삼성카드: 700,000원 (56%)\n  현대카드: 550,000원 (44%)\n```\n\n### 6. Card Billing Information\n\nWhen a user asks about card bills, payment due dates, or upcoming card charges:\n\nUser commands:\n- \"카드 청구 금액 알려줘\" / \"Show card billing amounts\"\n- \"다음 달 카드값 얼마야?\" / \"How much are my card bills?\"\n- \"카드 결제일 언제야?\" / \"When are my card payment due dates?\"\n- \"미결제 금액 얼마야?\" / \"How much is unpaid?\"\n\n**Step 1 - Fetch card billing info:**\n\n```bash\nnode pocket-lens.mjs card-bills\n```\n\nTo query a specific month (YYYY-MM format):\n\n```bash\nnode pocket-lens.mjs card-bills --month 2026-02\n```\n\nIf no `--month` is provided, the current month is used.\n\n**Step 2 - Format the response:**\n\nShow each card's billing amount, due date, and payment status. Highlight unpaid\nor pending bills. Show the total pending and completed amounts.\n\nExample format:\n\n```\n2026년 2월 카드 청구 내역\n\n삼성카드: 850,000원 (결제일: 2/25) 대기중\n현대카드: 650,000원 (결제일: 2/15) 결제완료\n\n미결제 총액: 850,000원\n결제 완료: 650,000원\n```\n\n## Error Handling\n\nHandle API errors with clear, actionable messages:\n\n| HTTP Status | Meaning | User-Facing Message |\n|-------------|---------|---------------------|\n| 401 | Invalid or missing API key | \"API 키가 유효하지 않습니다. PocketLens 설정에서 API 키를 확인해주세요.\" / \"Your API key is invalid. Please check your key in PocketLens Settings.\" |\n| 403 | Insufficient permissions | \"API 키에 쓰기 권한이 없습니다. write 또는 full 권한이 있는 키를 생성해주세요.\" / \"Your API key lacks write permission. Please create a key with write or full access.\" |\n| 429 | Rate limited | \"요청이 너무 많습니다. 잠시 후 다시 시도해주세요.\" / \"Too many requests. Please wait a moment and try again.\" |\n| 400 | Validation error | Show the specific validation errors from the response `details` field. |\n| 500 | Server error | \"서버 오류가 발생했습니다. 잠시 후 다시 시도해주세요.\" / \"A server error occurred. Please try again shortly.\" |\n\n## API Reference\n\n### POST /api/external/transactions\n\nCreates one or more transactions.\n\n**Request body:**\n```json\n{\n  \"transactions\": [\n    {\n      \"merchant\": \"스타벅스 강남점\",\n      \"amount\": 5500,\n      \"date\": \"2025-12-05T14:30:00+09:00\",\n      \"cardName\": \"신한카드\",\n      \"categoryHint\": \"카페\",\n      \"description\": \"아메리카노\",\n      \"source\": \"openclaw\"\n    }\n  ]\n}\n```\n\n**Fields:**\n- `merchant` (required): Merchant/store name, 1-200 characters.\n- `amount` (required): Integer amount in KRW (no decimals).\n- `date` (required): ISO 8601 datetime string.\n- `cardName` (optional): Card issuer name, max 100 characters.\n- `categoryHint` (optional): Category name hint for auto-classification, max 100 characters.\n- `description` (optional): Additional description, max 500 characters.\n- `source` (optional): Defaults to \"openclaw\".\n\n**Response (201):**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"created\": [\n      {\n        \"id\": \"abc123\",\n        \"merchant\": \"스타벅스 강남점\",\n        \"amount\": 5500,\n        \"date\": \"2025-12-05T14:30:00+09:00\",\n        \"categoryId\": \"cat_food\",\n        \"categoryName\": \"식비\",\n        \"isVerified\": false\n      }\n    ],\n    \"count\": 1\n  }\n}\n```\n\n### GET /api/external/categories\n\nLists user's available categories.\n\n**Response (200):**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"categories\": [\n      { \"id\": \"cat_1\", \"name\": \"식비\", \"icon\": \"utensils\", \"color\": \"#FF6B6B\", \"type\": \"SYSTEM\" }\n    ],\n    \"count\": 15\n  }\n}\n```\n\n### GET /api/external/me\n\nReturns the authenticated user's basic info.\n\n**Response (200):**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"user_123\",\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\"\n  }\n}\n```\n\n### GET /api/external/spending/summary\n\nReturns a monthly spending summary with totals, category breakdown, and card breakdown.\n\n**Query parameters:**\n- `month` (optional): Month in YYYY-MM format. Defaults to current month.\n\n**Response (200):**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"month\": \"2026-02\",\n    \"totalAmount\": 1250000,\n    \"transactionCount\": 45,\n    \"dailyAverage\": 56818,\n    \"previousMonth\": {\n      \"totalAmount\": 1100000,\n      \"diff\": 150000,\n      \"diffPercent\": 13.6\n    },\n    \"byCategory\": [\n      { \"categoryId\": \"cat_food\", \"categoryName\": \"식비\", \"amount\": 450000, \"percent\": 36.0 },\n      { \"categoryId\": \"cat_transport\", \"categoryName\": \"교통\", \"amount\": 180000, \"percent\": 14.4 }\n    ],\n    \"byCard\": [\n      { \"cardName\": \"삼성카드\", \"amount\": 700000, \"percent\": 56.0 },\n      { \"cardName\": \"현대카드\", \"amount\": 550000, \"percent\": 44.0 }\n    ]\n  }\n}\n```\n\n### GET /api/external/spending/bills\n\nReturns card billing information for a given month.\n\n**Query parameters:**\n- `month` (optional): Month in YYYY-MM format. Defaults to current month.\n\n**Response (200):**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"month\": \"2026-02\",\n    \"bills\": [\n      {\n        \"cardName\": \"삼성카드\",\n        \"amount\": 850000,\n        \"dueDate\": \"2026-02-25\",\n        \"status\": \"pending\"\n      },\n      {\n        \"cardName\": \"현대카드\",\n        \"amount\": 650000,\n        \"dueDate\": \"2026-02-15\",\n        \"status\": \"paid\"\n      }\n    ],\n    \"totalPending\": 850000,\n    \"totalPaid\": 650000\n  }\n}\n```\n\n## Language Behavior\n\n- Respond in the same language the user uses (Korean or English).\n- Transaction data (merchant names, descriptions) should be preserved as-is\n  from the source image or user input.\n- Korean credit card statements commonly use Korean merchant names; do not\n  translate them.\n\n## Script Location\n\nThe helper script is located at `scripts/pocket-lens.mjs` relative to this\nskill directory. Always use the full path when executing.\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":1060,"installsAllTime":40,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1771771244032,"updatedAt":1778992398968},"latestVersion":{"version":"1.0.0","createdAt":1771771244032,"changelog":"PocketLens skill initial release:\n\n- Enables uploading and auto-extraction of expense data from images of receipts, card statements, and payment screenshots.\n- Supports manual transaction entry via natural language, including Korean and English.\n- Provides tools to check PocketLens connection and API key status.\n- Allows users to view and list their expense categories.\n- Delivers spending summaries with category and card breakdowns by month.\n- Offers card billing details, including payment due dates and unpaid amounts.\n- Includes clear error messages for common API issues.","license":null},"metadata":{"setup":[{"key":"POCKET_LENS_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"edenjw","userId":"s175bngaekbsr9wfhtpnt0b1v98853kf","displayName":"Eden Jeongwoo Hong","image":"https://avatars.githubusercontent.com/u/2323545?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779949671433}}