xapi-to 0.1.18 → 0.1.20

package/skills/xapi/guides/sms.md

@@ -0,0 +1,186 @@
+# SMS Verification Guide
+
+Use xAPI's 5SIM SMS service to get virtual phone numbers and receive SMS verification codes for platform registrations (Claude, OpenAI, Telegram, etc.).
+
+> **Dynamic catalog:** These are database-registered third-party APIs, not built-in capabilities. Exact action IDs, HTTP methods, parameters, billing rules, and response fields can change. Run `search` and then `get` before every paid workflow; the current schema, service terms, quoted price, and live response are authoritative. Examples below reflect one known GET-based version.
+
+Use virtual numbers only where the target service permits them. Do not use this workflow to bypass access controls, identity checks, account limits, or platform terms.
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Check availability](#step-1-check-availability)
+- [Buy a number](#step-2-buy-a-number)
+- [Use the number](#step-3-use-the-number)
+- [Check for SMS](#step-4-check-for-sms)
+- [Finish or cancel](#step-5-finish-or-cancel)
+- [Agent workflow](#complete-agent-workflow)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+
+## How It Works
+
+1. **Check availability** — See stock and pricing by country
+2. **Buy a number** — Review the live quote and obtain explicit user confirmation before this paid action
+3. **Use the number** — Enter it on the target platform's registration page
+4. **Check for SMS** — Poll until the verification code arrives
+5. **Finish or cancel** — Confirm completion, or cancel/ban if the number didn't work
+
+**Billing:** Treat purchase, finish, cancel, ban, settlement, and refund behavior as service-version dependent. Some versions may reserve balance first and settle later; others may charge at purchase. Never promise a refund or a final charge point without checking the current schema and service terms.
+
+## Step 1: Check Availability
+
+```bash
+npx xapi-to call 5sim-sms.v1_guest_products_country_operator_product \
+  --method GET \
+  --input '{"pathParams":{"country":"any","operator":"any","product":"claudeai"},"params":{"single":0,"sort":"top"}}'
+```
+
+Returns stock and pricing per country. Pick a country with good stock and low price.
+
+### Common Product Names
+
+| Platform | Product name |
+|----------|-------------|
+| Claude / Anthropic | `claudeai` |
+| OpenAI / ChatGPT | `openai` |
+| Telegram | `telegram` |
+| WhatsApp | `whatsapp` |
+| Google | `google` |
+| Discord | `discord` |
+| Twitter / X | `twitter` |
+
+Treat these names as examples, not a stable catalog. Use `npx xapi-to search "5sim <platform>" --source api`, inspect candidates with `get`, or query the current products endpoint.
+
+As a last resort, you can list all products:
+
+```bash
+npx xapi-to call 5sim-sms.v1_guest_products_country_operator \
+  --method GET \
+  --input '{"pathParams":{"country":"any","operator":"any"}}'
+```
+
+The full product response can be large; filter it locally or query a product-specific endpoint after discovering the current name.
+
+## Step 2: Buy a Number
+
+```bash
+npx xapi-to call 5sim-sms.v1_user_buy_activation_country_operator_product \
+  --method GET \
+  --input '{"pathParams":{"country":"england","operator":"any","product":"claudeai"}}'
+```
+
+Response:
+
+```json
+{
+  "id": 123456789,
+  "phone": "+447123456789",
+  "operator": "three",
+  "product": "claudeai",
+  "price": 0.05,
+  "status": "PENDING",
+  "country": "england"
+}
+```
+
+Before running the buy call, show the user the selected country, operator, product, quoted price, and applicable cancellation/refund terms, then obtain explicit confirmation. **Save the returned `id` and `phone`**; the `id` is needed for subsequent operations.
+
+Inspect the returned balance/order fields to determine whether the current version reserved or charged funds. Do not infer settlement solely from a successful HTTP response.
+
+## Step 3: Use the Number
+
+Tell the user to:
+
+1. Go to the target platform's sign-up page (e.g. claude.ai)
+2. Enter the phone number from step 2 (e.g. `+447123456789`)
+3. Click "Send verification code"
+
+**This step requires human action.** Wait for the user to confirm they've requested the code.
+
+## Step 4: Check for SMS
+
+```bash
+npx xapi-to call 5sim-sms.v1_user_check_id \
+  --method GET \
+  --input '{"pathParams":{"id":"123456789"}}'
+```
+
+Response when SMS received:
+
+```json
+{
+  "id": 123456789,
+  "phone": "+447123456789",
+  "status": "RECEIVED",
+  "sms": [
+    {
+      "created_at": "2026-03-26T10:30:00Z",
+      "text": "Your Claude verification code is: 834291",
+      "code": "834291"
+    }
+  ]
+}
+```
+
+If `status` is still `PENDING`, wait a few seconds and poll again until the order's current expiry or retry limit.
+
+**Polling strategy:** Start around every 5 seconds, respect any upstream retry guidance, and stop at the order's current expiry. Do not create another paid order without a new confirmation.
+
+## Step 5: Finish or Cancel
+
+### Finish (mark order as completed)
+
+After the user has successfully used the verification code:
+
+```bash
+npx xapi-to call 5sim-sms.v1_user_finish_id \
+  --method GET \
+  --input '{"pathParams":{"id":"123456789"}}'
+```
+
+### Cancel
+
+If the SMS never arrives or the number doesn't work:
+
+```bash
+npx xapi-to call 5sim-sms.v1_user_cancel_id \
+  --method GET \
+  --input '{"pathParams":{"id":"123456789"}}'
+```
+
+Read the returned order and balance fields to determine the result. Cancellation does not imply that a refund is either guaranteed or impossible.
+
+
+## Complete Agent Workflow
+
+When a user asks to register for a platform using SMS verification:
+
+1. Ask which platform (to determine the product name)
+2. Check availability and pricing — suggest the cheapest option with good stock
+3. Show the exact quote and terms, obtain explicit confirmation, then buy one number
+4. Tell the user to enter the number on the platform and request the code
+5. Poll for SMS — check every 5 seconds until received
+6. Show the verification code to the user
+7. Wait for user to confirm they've completed registration
+8. Call finish to confirm, or cancel if something went wrong
+
+## API Reference
+
+| API | Description |
+|-----------|-------------|
+| `5sim-sms.v1_guest_products_country_operator_product` | Check stock and pricing by country/product |
+| `5sim-sms.v1_guest_products_country_operator` | List all available products |
+| `5sim-sms.v1_guest_countries` | List all supported countries |
+| `5sim-sms.v1_guest_prices` | Query prices by country/product/carrier |
+| `5sim-sms.v1_user_buy_activation_country_operator_product` | Buy a number; inspect the response for billing state |
+| `5sim-sms.v1_user_check_id` | Check order status and SMS content |
+| `5sim-sms.v1_user_finish_id` | Confirm completion under current service terms |
+| `5sim-sms.v1_user_cancel_id` | Request cancellation under current service terms |
+
+## Error Handling
+
+- **"Bad product"** → Rediscover the current action/product with `search`, `get`, or the products endpoint; do not keep guessing paid inputs.
+- **SMS never arrives** → Inspect the order's allowed cancel/ban actions and terms. Ask before buying another number in a different country.
+- **Insufficient balance** → Top up: `npx xapi-to topup --method stripe --amount 10`
+- **Number rejected by platform** → Some platforms block certain countries. Try USA or UK numbers.

package/skills/xapi/guides/tiktok.md

@@ -0,0 +1,322 @@
+# TikTok Guide
+
+Complete guide for TikTok operations via xAPI — user profiles, videos, comments, search, hashtags, music, live rooms, and recommended feed.
+
+> **Dynamic catalog:** These are database-registered third-party APIs under the `tiktok` service. Exact action IDs, HTTP methods, parameters, and response fields can change. Run `search` and `get` before calling; the current schema wins. Examples below reflect one known GET-based version and keep `"method":"GET"` in the input for compatibility.
+
+## Contents
+
+- [User data](#user-data)
+- [Video data](#video-data)
+- [Search](#search)
+- [Hashtags](#hashtags)
+- [Music](#music)
+- [Live](#live)
+- [Feed](#feed)
+- [Common workflows](#common-workflows)
+- [Pagination](#pagination-patterns)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+
+## User Data
+
+### Get user profile
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_handler__user__profile \
+  --input '{"method":"GET","params":{"unique_id":"tiktok"}}'
+```
+
+Look up a user by `unique_id` (username), `user_id` (numeric), or `sec_user_id`. At least one must be provided.
+
+Returns `data.data.user` with fields: `uid`, `unique_id`, `nickname`, `signature`, `follower_count`, `following_count`, `total_favorited`, `aweme_count`, `avatar_thumb`, `avatar_medium`, `sec_uid`.
+
+**Important:** The user profile returns `sec_uid`, but other TikTok APIs expect the parameter name `sec_user_id`. Pass the value of `sec_uid` as `sec_user_id` when calling other endpoints.
+
+### Get user_id and sec_user_id by username
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_get__user__id__and__sec__user__id__by__username \
+  --input '{"method":"GET","params":{"username":"tiktok"}}'
+```
+
+**Important:** Many TikTok actions require `sec_user_id` instead of the username. Use this endpoint or `handler_user_profile` to get it first.
+
+### Get user's videos
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__user__post__videos \
+  --input '{"method":"GET","params":{"unique_id":"tiktok","count":10}}'
+```
+
+Can also pass `sec_user_id` instead of `unique_id`. Paginate with `max_cursor` from previous response.
+
+Optional parameters:
+- `count` — items per page
+- `sort_type` — sort type
+- `max_cursor` — pagination cursor
+
+For faster response with simplified data, use the V3 endpoint: `tiktok.api_v1_tiktok_app_v3_fetch__user__post__videos__v3`.
+
+### Get user's liked videos
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__user__like__videos \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>","counts":10}}'
+```
+
+Requires `sec_user_id`. Paginate with `max_cursor`. Note: the parameter is `counts` (with 's'), not `count`.
+
+### Get followers / following
+
+```bash
+# Followers
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__user__follower__list \
+  --input '{"method":"GET","params":{"user_id":"107955","count":20}}'
+
+# Following
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__user__following__list \
+  --input '{"method":"GET","params":{"user_id":"107955","count":20}}'
+```
+
+Pass either `user_id` or `sec_user_id`. Paginate with `min_time` and `page_token` from previous response.
+
+### Get similar user recommendations
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__similar__user__recommendations \
+  --input '{"method":"GET","params":{"user_id":"107955"}}'
+```
+
+## Video Data
+
+### Get video by ID
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__one__video__v2 \
+  --input '{"method":"GET","params":{"aweme_id":"<video_id>"}}'
+```
+
+The `aweme_id` is the numeric video ID. Returns full video data including `desc`, `statistics`, `author`, `music`, `video` (with play URLs).
+
+### Get video by share URL
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__one__video__by__share__url__v2 \
+  --input '{"method":"GET","params":{"share_url":"https://www.tiktok.com/@user/video/1234567890"}}'
+```
+
+### Batch get videos
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__multi__video__v2 \
+  --input '{"method":"GET","params":{"aweme_ids":"id1,id2,id3"}}'
+```
+
+### Get video comments
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__video__comments \
+  --input '{"method":"GET","params":{"aweme_id":"<video_id>","count":20,"cursor":0}}'
+```
+
+Paginate with `cursor`.
+
+### Get comment replies
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__video__comment__replies \
+  --input '{"method":"GET","params":{"item_id":"<video_id>","comment_id":"<comment_id>","count":20,"cursor":0}}'
+```
+
+## Search
+
+### General search (comprehensive)
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__general__search__result \
+  --input '{"method":"GET","params":{"keyword":"cat","count":10}}'
+```
+
+Returns mixed results (videos, users, hashtags). Paginate with `offset`.
+
+Optional parameters:
+- `sort_type` — sort type
+- `publish_time` — publish time filter
+
+### Video search
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__video__search__result \
+  --input '{"method":"GET","params":{"keyword":"cooking","count":10}}'
+```
+
+Optional: `region`, `sort_type`, `publish_time`. Paginate with `offset`.
+
+### User search
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__user__search__result \
+  --input '{"method":"GET","params":{"keyword":"chef","count":10}}'
+```
+
+Optional filters: `user_search_follower_count`, `user_search_profile_type`. Paginate with `offset`.
+
+### Music search
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__music__search__result \
+  --input '{"method":"GET","params":{"keyword":"pop","count":10}}'
+```
+
+Optional: `region`, `filter_by`, `sort_type`. Paginate with `offset`.
+
+### Hashtag search
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__hashtag__search__result \
+  --input '{"method":"GET","params":{"keyword":"dance","count":10}}'
+```
+
+Paginate with `offset`.
+
+## Hashtags
+
+### Get hashtag details
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__hashtag__detail \
+  --input '{"method":"GET","params":{"ch_id":"<hashtag_id>"}}'
+```
+
+### Get hashtag video list
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__hashtag__video__list \
+  --input '{"method":"GET","params":{"ch_id":"<hashtag_id>","count":20,"cursor":0}}'
+```
+
+Paginate with `cursor`.
+
+## Music
+
+### Get music details
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__music__detail \
+  --input '{"method":"GET","params":{"music_id":"<music_id>"}}'
+```
+
+### Get videos using a music
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__music__video__list \
+  --input '{"method":"GET","params":{"music_id":"<music_id>","count":20,"cursor":0}}'
+```
+
+Paginate with `cursor`.
+
+## Live
+
+### Get live room info
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__live__room__info \
+  --input '{"method":"GET","params":{"room_id":"<room_id>"}}'
+```
+
+### Check if live room is online
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_check__live__room__online \
+  --input '{"method":"GET","params":{"room_id":"<room_id>"}}'
+```
+
+### Batch check live rooms online
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_check__live__room__online__batch \
+  --input '{"method":"GET","params":{"room_ids":"id1,id2,id3"}}'
+```
+
+### Get live search results
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__live__search__result \
+  --input '{"method":"GET","params":{"keyword":"gaming"}}'
+```
+
+## Feed
+
+### Get home feed (recommended videos)
+
+```bash
+npx xapi-to call tiktok.api_v1_tiktok_app_v3_fetch__home__feed \
+  --input '{"method":"GET","params":{}}'
+```
+
+Returns recommended "For You" page videos. **Note:** This endpoint may return empty results depending on account/region configuration.
+
+## Common Workflows
+
+### Research a TikTok creator
+
+1. Look up user: `tiktok...handler__user__profile` with `unique_id` → get `uid`, `sec_user_id`, follower stats
+2. Get videos: `tiktok...fetch__user__post__videos` → browse recent content
+3. Check engagement: view `statistics` in each video (play count, likes, comments, shares)
+
+### Analyze a TikTok video
+
+1. Get video: `tiktok...fetch__one__video__v2` with `aweme_id` → full video data
+2. Read comments: `tiktok...fetch__video__comments` → top comments
+3. Get replies: `tiktok...fetch__video__comment__replies` → comment threads
+
+### Discover content by hashtag
+
+1. Search hashtags: `tiktok...fetch__hashtag__search__result` with `keyword` → find hashtag IDs
+2. Get details: `tiktok...fetch__hashtag__detail` with `ch_id` → view count, video count
+3. Browse videos: `tiktok...fetch__hashtag__video__list` → videos using this hashtag
+
+## Pagination Patterns
+
+| Pattern | Endpoints | How to use |
+|---------|-----------|------------|
+| `max_cursor` | user videos, liked videos | Pass `max_cursor` from previous response |
+| `cursor` | comments, hashtag videos, music videos | Pass `cursor` from previous response |
+| `offset` | all search endpoints | Increment by `count` each page |
+| `min_time` + `page_token` | follower/following lists | Pass both from previous response |
+
+## API Reference
+
+| API (prefix: `tiktok.api_v1_tiktok_app_v3_`) | Description | Key Params |
+|---|---|---|
+| `handler__user__profile` | Get user profile | `unique_id` or `user_id` or `sec_user_id` |
+| `get__user__id__and__sec__user__id__by__username` | Get IDs by username | `username` |
+| `fetch__user__post__videos` | User's videos | `unique_id` or `sec_user_id`, `count`, `max_cursor` |
+| `fetch__user__post__videos__v3` | User's videos (simplified) | `unique_id` or `sec_user_id`, `count`, `max_cursor` |
+| `fetch__user__like__videos` | User's liked videos | `sec_user_id`, `counts`, `max_cursor` |
+| `fetch__user__follower__list` | User's followers | `user_id` or `sec_user_id`, `count` |
+| `fetch__user__following__list` | User's following | `user_id` or `sec_user_id`, `count` |
+| `fetch__one__video__v2` | Single video | `aweme_id` |
+| `fetch__one__video__by__share__url__v2` | Video by share URL | `share_url` |
+| `fetch__multi__video__v2` | Batch get videos | `aweme_ids` |
+| `fetch__video__comments` | Video comments | `aweme_id`, `count`, `cursor` |
+| `fetch__video__comment__replies` | Comment replies | `item_id`, `comment_id`, `count`, `cursor` |
+| `fetch__general__search__result` | General search | `keyword`, `count`, `offset` |
+| `fetch__video__search__result` | Video search | `keyword`, `count`, `offset` |
+| `fetch__user__search__result` | User search | `keyword`, `count`, `offset` |
+| `fetch__music__search__result` | Music search | `keyword`, `count`, `offset` |
+| `fetch__hashtag__search__result` | Hashtag search | `keyword`, `count`, `offset` |
+| `fetch__hashtag__detail` | Hashtag details | `ch_id` |
+| `fetch__hashtag__video__list` | Hashtag videos | `ch_id`, `count`, `cursor` |
+| `fetch__music__detail` | Music details | `music_id` |
+| `fetch__music__video__list` | Music videos | `music_id`, `count`, `cursor` |
+| `fetch__live__room__info` | Live room info | `room_id` |
+| `check__live__room__online` | Check live online | `room_id` |
+| `fetch__home__feed` | Home feed | — |
+
+## Error Handling
+
+- **Missing sec_user_id** → Use `handler_user_profile` or `get_user_id_and_sec_user_id_by_username` to get it first
+- **Empty results** → Check that `aweme_id`, `ch_id`, or `music_id` is valid
+- **Pagination exhausted** → When `has_more` is `0` or `false`, no more pages available