xapi-to 0.1.18 → 0.1.19

package/skills/xapi/guides/reddit.md

@@ -0,0 +1,312 @@
+# Reddit Guide
+
+Complete guide for Reddit operations via xAPI — user profiles, posts, comments, subreddit feeds, popular/news/games feeds, trending, and search suggestions.
+
+> **Dynamic catalog:** These are database-registered third-party APIs under the `reddit` 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.
+
+**Tip:** Most endpoints accept `need_format` (boolean). Set it to `true` for cleaner, pre-processed responses; omit or set `false` for raw Reddit data.
+
+## Contents
+
+- [User data](#user-data)
+- [Post data](#post-data)
+- [Subreddit data](#subreddit-data)
+- [Feeds](#feeds)
+- [Search and trending](#search--trending)
+- [Common workflows](#common-workflows)
+- [Pagination](#pagination)
+- [Reddit ID prefixes](#reddit-id-prefixes)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+
+## User Data
+
+### Get user profile
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__user__profile \
+  --input '{"method":"GET","params":{"username":"spez","need_format":true}}'
+```
+
+Returns `data.data.redditorInfoByName` with fields: `id` (e.g. `t2_1w72`), `name`, `prefixedName`, `isEmployee`, `isVerified`, `accountType`, `karma` (total, fromPosts, fromComments), `profile` (createdAt, subscribersCount, publicDescriptionText, styles).
+
+### Get user's posts
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__user__posts \
+  --input '{"method":"GET","params":{"username":"spez","sort":"TOP","need_format":true}}'
+```
+
+Optional parameters:
+- `sort` — `NEW`, `TOP`, `HOT`, `CONTROVERSIAL`
+- `after` — pagination cursor from previous response
+
+### Get user's comments
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__user__comments \
+  --input '{"method":"GET","params":{"username":"spez","sort":"TOP","need_format":true}}'
+```
+
+Optional parameters:
+- `sort` — `NEW`, `TOP`, `HOT`, `CONTROVERSIAL`
+- `after` — pagination cursor
+- `page_size` — items per page (default: 25)
+
+### Get user's active subreddits
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__user__active__subreddits \
+  --input '{"method":"GET","params":{"username":"spez","need_format":true}}'
+```
+
+### Get user's trophies
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__user__trophies \
+  --input '{"method":"GET","params":{"username":"spez","need_format":true}}'
+```
+
+## Post Data
+
+### Get single post details
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__post__details \
+  --input '{"method":"GET","params":{"post_id":"t3_1ojnh50","need_format":true}}'
+```
+
+The `post_id` must include the `t3_` prefix. To jump to a specific comment within the post, set `include_comment_id` to `true` and pass the `comment_id`.
+
+### Batch get post details
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__post__details__batch \
+  --input '{"method":"GET","params":{"post_ids":"t3_1ojnh50,t3_1abc123","need_format":true}}'
+```
+
+Comma-separated, up to 5 post IDs per request.
+
+### Get post comments
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__post__comments \
+  --input '{"method":"GET","params":{"post_id":"t3_1ojnh50","sort_type":"TOP","need_format":true}}'
+```
+
+Optional parameters:
+- `sort_type` — `CONFIDENCE`, `NEW`, `TOP`, `HOT`, `CONTROVERSIAL`, `OLD`, `RANDOM`
+- `after` — pagination cursor
+
+### Get comment replies
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__comment__replies \
+  --input '{"method":"GET","params":{"post_id":"t3_1qmup73","cursor":"commenttree:ex:(RjiJd)","need_format":true}}'
+```
+
+Both `post_id` and `cursor` are required. The `cursor` value comes from the `more.cursor` field in comment responses.
+
+Optional: `sort_type` — same options as post comments.
+
+## Subreddit Data
+
+### Get subreddit info
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__subreddit__info \
+  --input '{"method":"GET","params":{"subreddit_name":"bitcoin","need_format":true}}'
+```
+
+Returns `data.data.subredditInfoByName` with: `id`, `name`, `prefixedName`, `title`, `description`, `publicDescriptionText`, `subscribersCount`, `styles`.
+
+### Get subreddit feed
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__subreddit__feed \
+  --input '{"method":"GET","params":{"subreddit_name":"programming","sort":"HOT","need_format":true}}'
+```
+
+Optional parameters:
+- `sort` — `BEST`, `HOT`, `NEW`, `TOP`, `CONTROVERSIAL`, `RISING`
+- `after` — pagination cursor
+- `filter_posts` — array of post IDs to exclude
+
+### Get subreddit style
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__subreddit__style \
+  --input '{"method":"GET","params":{"subreddit_name":"bitcoin","need_format":true}}'
+```
+
+Returns the subreddit's visual theme info (banner, icon, colors).
+
+### Get subreddit post channels
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__subreddit__post__channels \
+  --input '{"method":"GET","params":{"subreddit_name":"bitcoin","sort":"HOT","need_format":true}}'
+```
+
+Optional parameters:
+- `sort` — `HOT`, `NEW`, `TOP`, `CONTROVERSIAL`, `RISING`
+- `range` — `HOUR`, `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL`
+
+### Check if subreddit is muted
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_check__subreddit__muted \
+  --input '{"method":"GET","params":{"subreddit_id":"t5_2s3qj","need_format":true}}'
+```
+
+Requires the subreddit ID with `t5_` prefix (get it from subreddit info).
+
+### Get community highlights
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__community__highlights \
+  --input '{"method":"GET","params":{"subreddit_id":"t5_2s3qj","need_format":true}}'
+```
+
+Requires `subreddit_id` with `t5_` prefix.
+
+## Feeds
+
+### Get popular feed
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__popular__feed \
+  --input '{"method":"GET","params":{"sort":"HOT","need_format":true}}'
+```
+
+Returns `data.data.posts[]` with post objects and `after` for pagination.
+
+Each post includes: `id`, `postTitle`, `url`, `score`, `commentCount`, `subreddit`, `authorInfo`, `permalink`, `postHint`, `upvoteRatio`, `createdAt`, `isNsfw`, `isSpoiler`, `media`, `thumbnail`.
+
+Optional parameters:
+- `sort` — `BEST`, `HOT`, `NEW`, `TOP`, `CONTROVERSIAL`, `RISING`
+- `time` — `ALL`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `YEAR`
+- `after` — pagination cursor
+- `filter_posts` — array of post IDs to exclude
+
+### Get news feed
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__news__feed \
+  --input '{"method":"GET","params":{"need_format":true}}'
+```
+
+Optional parameters:
+- `after` — pagination cursor
+- `subtopic_ids` — array of subtopic IDs to filter
+
+### Get games feed
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__games__feed \
+  --input '{"method":"GET","params":{"sort":"HOT","need_format":true}}'
+```
+
+Optional: `sort`, `time`, `after`.
+
+## Search & Trending
+
+### Get trending searches
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__trending__searches \
+  --input '{"method":"GET","params":{"need_format":true}}'
+```
+
+Returns current trending search queries on Reddit.
+
+### Search typeahead (suggestions)
+
+```bash
+npx xapi-to call reddit.api_v1_reddit_app_fetch__search__typeahead \
+  --input '{"method":"GET","params":{"query":"bitcoin","need_format":true}}'
+```
+
+Returns search suggestions including query completions and matching subreddits.
+
+Optional parameters:
+- `allow_nsfw` — `"0"` or `"1"`
+- `safe_search` — `"unset"` or `"strict"`
+
+## Common Workflows
+
+### Research a Reddit user
+
+1. Get profile: `reddit...fetch__user__profile` → karma, account age, description
+2. Get posts: `reddit...fetch__user__posts` with `sort=TOP` → most popular posts
+3. Get comments: `reddit...fetch__user__comments` → user's comment activity
+4. Active subreddits: `reddit...fetch__user__active__subreddits` → community participation
+
+### Monitor a subreddit
+
+1. Get info: `reddit...fetch__subreddit__info` → subscriber count, description
+2. Get feed: `reddit...fetch__subreddit__feed` with `sort=HOT` → trending posts
+3. Read post: `reddit...fetch__post__details` → full post content
+4. Read comments: `reddit...fetch__post__comments` with `sort_type=TOP` → top comments
+
+### Track what's trending
+
+1. Trending: `reddit...fetch__trending__searches` → current trending topics
+2. Popular feed: `reddit...fetch__popular__feed` with `sort=HOT` → top posts across Reddit
+3. News feed: `reddit...fetch__news__feed` → latest news posts
+
+### Deep-dive a post thread
+
+1. Get post: `reddit...fetch__post__details` with `post_id` → post content
+2. Get comments: `reddit...fetch__post__comments` with `sort_type=TOP` → top-level comments
+3. Get replies: `reddit...fetch__comment__replies` with `cursor` → expand comment threads
+
+## Pagination
+
+All paginated endpoints use the `after` cursor pattern (except comment replies which use `cursor`):
+
+1. Make the initial request without `after`
+2. Extract `after` from the response (e.g. `data.data.after` or from `pageInfo.endCursor`)
+3. Pass `after` in the next request to get the next page
+4. When `after` is `null` or response has no more data, pagination is exhausted
+
+## Reddit ID Prefixes
+
+| Prefix | Type | Example |
+|--------|------|---------|
+| `t1_` | Comment | `t1_abc123` |
+| `t2_` | User | `t2_1w72` |
+| `t3_` | Post/Link | `t3_1ojnh50` |
+| `t5_` | Subreddit | `t5_2s3qj` |
+
+## API Reference
+
+| API (prefix: `reddit.api_v1_reddit_app_`) | Description | Key Params |
+|---|---|---|
+| `fetch__user__profile` | User profile | `username`* |
+| `fetch__user__posts` | User's posts | `username`*, `sort`, `after` |
+| `fetch__user__comments` | User's comments | `username`*, `sort`, `after`, `page_size` |
+| `fetch__user__active__subreddits` | User's active subreddits | `username`* |
+| `fetch__user__trophies` | User's trophies | `username`* |
+| `fetch__post__details` | Single post details | `post_id`* |
+| `fetch__post__details__batch` | Batch post details (up to 5) | `post_ids`* |
+| `fetch__post__comments` | Post comments | `post_id`*, `sort_type`, `after` |
+| `fetch__comment__replies` | Comment replies | `post_id`*, `cursor`*, `sort_type` |
+| `fetch__subreddit__info` | Subreddit info | `subreddit_name` |
+| `fetch__subreddit__feed` | Subreddit feed | `subreddit_name`*, `sort`, `after` |
+| `fetch__subreddit__style` | Subreddit style/theme | `subreddit_name` |
+| `fetch__subreddit__post__channels` | Subreddit post channels | `subreddit_name`, `sort`, `range` |
+| `check__subreddit__muted` | Check subreddit muted | `subreddit_id`* |
+| `fetch__community__highlights` | Community highlights | `subreddit_id`* |
+| `fetch__popular__feed` | Popular feed | `sort`, `time`, `after` |
+| `fetch__news__feed` | News feed | `after`, `subtopic_ids` |
+| `fetch__games__feed` | Games feed | `sort`, `time`, `after` |
+| `fetch__trending__searches` | Trending searches | — |
+| `fetch__search__typeahead` | Search suggestions | `query`* |
+
+## Error Handling
+
+- **Missing t3_ prefix** → Post IDs must include the `t3_` prefix (e.g. `t3_1ojnh50`, not just `1ojnh50`)
+- **Empty results** → Verify the username or subreddit_name exists
+- **Pagination exhausted** → `after` is `null` or missing in the response
+- **Comment replies require cursor** → Get the `cursor` value from the `more` field in comment responses

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.