xapi-to 0.1.19 → 0.1.21

package/skills/xapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xapi
-description: Access real-time external data via the xapi CLI — Twitter/X (including resolving and downloading tweet videos), Douyin/TikTok, Reddit, LinkedIn, Weibo, on-chain crypto data (price, holders, wallets, DEX, CEX), web/news/image/video/scholar search, AI text/image/video/speech generation and transcription, and SMS verification. Configure the Anthropic/OpenAI-compatible xAPI AI Gateway or the xAPI WebSocket Gateway for realtime voice, streaming ASR/TTS, and provider-native bidirectional sessions. Use when the user mentions xapi, wants to call a third-party API, asks what external services are available, or needs to connect an AI or realtime client to xAPI.
+description: Access real-time external data and managed cloud sandboxes via the xapi CLI — Twitter/X, social platforms, crypto, web/news search, AI generation, SMS verification, and auditable ephemeral compute. Configure the xAPI AI or WebSocket Gateways, or use sandbox run for automatic quote/create/execute/cleanup. Use when the user mentions xapi, external services, or sandbox compute.
 metadata: {"openclaw":{"emoji":"x","requires":{"anyBins":["npx"]},"primaryEnv":"XAPI_KEY"}}
 ---
 
@@ -62,6 +62,17 @@ xapi offers two types of APIs under a unified interface:
 
 Both types use the same discovery and call workflow. Use `--source capability` or `--source api` on commands that expose source filtering.
 
+## Managed Sandbox Compute
+Read `guides/sandbox.md` before creating a billable instance. For a one-shot
+command, prefer `sandbox run`; it quotes, applies a price ceiling, waits,
+executes, and terminates in `finally`:
+```bash
+npx xapi-to sandbox run --command 'python3 -c "print(6 * 7)"'
+```
+Use granular commands only for multi-step work. Keep the instance ID, terminate
+in cleanup, and verify terminal state/cost afterward. Do not use `--keep` unless
+the user explicitly wants a reusable, continuing-to-bill instance.
+
 ## Usage Workflow
 
 **Critical rule:** Before calling any API, always use `get` to understand the required parameters.
@@ -362,7 +373,7 @@ npx xapi-to call web.search --input '{"q":"hello world"}'
 npx xapi-to call serper.search --input '{"body":{"q":"hello world"}}'
 ```
 
-This ensures correct types (strings, numbers, booleans) are preserved.
+Read `guides/serper.md` before using direct `serper.*` actions; it covers all current v7 actions, mini-batches, Reviews, billing, and the `web.search.*` boundary.
 
 ## Code Generation (`--code`)
 
@@ -436,10 +447,10 @@ Beyond built-in capabilities, xapi proxies **dozens** of third-party API service
 - **Douyin** (`douyin`) — Douyin/TikTok API (videos, users, trending, comments)
 - **Twitter API** (`twitter`) — Alternative Twitter data API
 - **Reddit** (`reddit`) — Reddit API (posts, comments, subreddits, search)
-- **LinkedIn** (`linkedin`) — LinkedIn API (person profiles & career history, company pages, posts & comments, job search)
+- **LinkedIn** (`linkedin`) — LinkedIn API (person profiles & career history, company pages, posts & comments, job search). For career history, see `guides/linkedin.md` first — the profile endpoint silently omits `experience`/`education` for ordinary profiles
 - **Weibo** (`weibo-app`) — Weibo API (user profiles, feeds, search, trending)
 - **5SIM SMS** (`5sim-sms`) — SMS verification (virtual numbers, activation codes)
-- **Serper API** (`serper`) — Google Search API
+- **Serper API** (`serper`) — 12 provider-native Google Search actions including web, images, news, maps, places, video, shopping, scholar, patents, autocomplete, Lens, and reviews. Eleven support mini-batch; Reviews does not. Read `guides/serper.md` before calling them
 - **OpenRouter API** (`openrouter`) — Multi-model AI gateway (chat, embeddings, audio transcription/speech, video)
 
 The full catalog also spans many other categories — crypto/on-chain data, CEX market data, stocks & macro, social platforms, news, weather, and more. Discover them with `search` / `services`.
@@ -455,8 +466,6 @@ The full catalog also spans many other categories — crypto/on-chain data, CEX
 
 The CLI retries idempotent metadata reads and `task poll` for transient timeouts, network failures, `408`, `429`, and `502`–`504`. It does not automatically retry arbitrary `call` actions because the upstream may already have completed a write; confirm the result before manually retrying posts, payments, or other mutations. Ordinary JSON execution has a 60-second request ceiling. HTTP SSE streams and raw downloads instead use a 60-second no-data timeout, reset whenever a chunk arrives; override it with `XAPI_TRANSFER_IDLE_TIMEOUT_MS` when an upstream legitimately pauses longer.
 
-## Tips
-
 - Use `--page` and `--page-size` for pagination on `list`, `search`, and `services`.
 
 ## Specialized Guides
@@ -465,17 +474,20 @@ When the user's task involves these workflows, read the corresponding guide file
 
 - **`guides/twitter.md`** — Twitter/X (推特): read and paginate tweets/replies/media, download the highest-quality MP4 from a video tweet, advanced search, read long-form X Articles directly from `tweet_detail`, post tweets, reply, quote, like, retweet, OAuth binding
 - **`guides/reddit.md`** — Reddit: user profiles, posts, comments, subreddit feeds, popular/news/games feeds, trending, search
-- **`guides/linkedin.md`** — LinkedIn (领英): person profiles with career history, company pages, posts & comments, job search & job detail — every endpoint but job search is addressed by an ordinary LinkedIn page URL, and post comments need a numeric `urn` alongside `url`
+- **`guides/linkedin.md`** — LinkedIn (领英): person profiles with career history, company pages, posts & comments, job search & job detail — every endpoint but job search is addressed by an ordinary LinkedIn page URL, and post comments need a numeric `urn` alongside `url`. **Read this guide before summarizing anyone's background:** `get__user__profile` returns `experience: null` / `education: null` for ordinary (non-creator) profiles because it reads the logged-out page, and the guide gives the fallback that recovers the real career history
 - **`guides/tiktok.md`** — TikTok: user profiles, videos, comments, search, hashtags, music, live rooms, feed
 - **`guides/douyin.md`** — Douyin (抖音): user profiles, videos, comments, hot search, hashtags, music, video mix/series
 - **`guides/xiaohongshu.md`** — 小红书 (Xiaohongshu): user profiles, notes, comments, search, topics, products, creator inspiration
 - **`guides/weibo.md`** — Weibo (微博): hot search, content search, user profiles, post details, comments, reposts, media
 - **`guides/google_search.md`** — Google Search: web, realtime, news, image, video, scholar, maps, places, shopping
+- **`guides/serper.md`** — direct Serper v7 API: 12 provider-native actions, object-or-array mini-batches, Reviews pagination and batch exception, Lens, dynamic per-credit billing, and the current Webpage service boundary
 - **`guides/crypto.md`** — Crypto (加密货币): on-chain token price/overview/holders/security/OHLCV, wallet analytics, DEX pairs, CEX spot prices by symbol, news — covers contract-address vs symbol addressing and multi-chain
 - **`guides/ai.md`** — AI (人工智能): synchronous or SSE-streamed text, embeddings, asynchronous image/video generation with `task wait`, text-to-speech, and speech-to-text
 - **`guides/ai_gateway.md`** — xAPI AI Gateway: Claude Code and Anthropic/OpenAI SDK setup, model discovery, routing strategies, streaming, fallback, routing/billing headers, direct media endpoints, and known limitations
 - **`guides/ws_gateway.md`** — xAPI WebSocket Gateway: OpenAI Realtime, streaming ASR/TTS, simultaneous interpretation, podcast generation, service/path routing, browser authentication, native binary protocols, limits, billing, close codes, and reconnects
+- **`guides/sandbox.md`** — managed Sandbox compute: AI tool selection, one-shot and multi-step lifecycles, provider pinning, files, Cloudflare Web previews, suspension, GPU jobs, parallel agents, cleanup recovery, audit/history, and billing verification
 - **`guides/sms.md`** — SMS verification: buy virtual phone numbers, receive verification codes, finish/cancel orders (5SIM)
+- **`guides/provider.md`** — Provider management: create/update services, About/changelog, version lifecycle, metrics/events and request receipts, Skill upload/linking, rollback/delete, earnings transfer
 
 ## Security
 

package/skills/xapi/guides/linkedin.md

@@ -8,6 +8,7 @@ Complete guide for LinkedIn operations via xAPI — person profiles with career
 
 - [Key concept: everything is addressed by URL](#key-concept-everything-is-addressed-by-url)
 - [Person data](#person-data)
+  - [When `experience` and `education` come back `null`](#when-experience-and-education-come-back-null)
 - [Company data](#company-data)
 - [Posts and comments](#posts-and-comments)
 - [Jobs](#jobs)
@@ -56,6 +57,48 @@ One call returns the whole profile — no follow-up requests for individual sect
 
 There are no separate `get__user__experience` / `educations` / `skills` / `honors` / `publications` endpoints in v2 — that was the older `username` → `urn` two-step API. If you were using those IDs, they now return `Action not found`.
 
+### When `experience` and `education` come back `null`
+
+`get__user__profile` reads the **logged-out** public page. LinkedIn renders the full career and school sections there only for creator/open profiles; on an ordinary member's page it serves a trimmed topcard. The call still succeeds with `code: 200`, so the failure is silent — you get identity, `current_company`, `educations_details`, `followers`, and `people_also_viewed`, but:
+
+```json
+{ "position": null, "experience": null, "education": null, "about": "Don't use LinkedIn that much…" }
+```
+
+`null` here means **not rendered to logged-out visitors**, not "this person has no jobs listed". A truncated `about` ending in `…` is the same signal. Never summarize a person's background from a response in this state, and never report the profile as private or empty — fall back:
+
+```bash
+npx xapi-to call icypeas-email.api_scrape_profile \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/ricky-wang-74b3a0194/"}}'
+```
+
+This returns a differently-shaped payload under `data.result`:
+
+| Field | Contents |
+|---|---|
+| `worksFor[]` | Current positions — `jobTitle`, `startDate`, `description`, nested `company` (industry, size, website, HQ) |
+| `alumniOf[]` | Past positions — same shape plus `endDate` |
+| `educations[]` | `name`, `degree`, `fieldsOfStudy[]`, `description` |
+| `headline`, `description` | Headline and the full untruncated About text |
+| `firstname`, `lastname`, `address`, `numOfConnections`, `skills[]`, `languages[]` | Identity and profile detail |
+
+Check `data.status` before reading `data.result`: `FOUND` means real data, `NOT_FOUND` means `result` is `null` and this source has nothing for that URL either. Two caveats worth carrying into any summary: the snapshot is cached, so `headline` can lag the person's current role, and `startDate`/`endDate` are year-granular (often stamped to January), so treat them as approximate. `jobTitle` also reflects whatever the member typed, which can disagree with a company's own announcement — prefer cross-checking a role against `web.search` before asserting a title.
+
+Do not reach for `contactout-api.v1_linkedin_enrich` as a fallback. Without a separate ContactOut contract it returns a fully-populated **sample profile** (`"Example Person"` at `"Legros, Smitham and Kessler"`) with `status_code: 200`, which is easy to mistake for real data, and it is the most expensive LinkedIn-adjacent action in the catalog.
+
+### Person profile decision path
+
+```
+get__user__profile
+  ├─ experience[] present            → done, use it
+  └─ experience/education == null    → icypeas-email.api_scrape_profile
+        ├─ status == FOUND           → read worksFor / alumniOf / educations
+        └─ status == NOT_FOUND       → say the career history is unavailable;
+                                        fall back to web.search for public
+                                        bios, or twitter.user_by_screen_name
+                                        when the person came from an X handle
+```
+
 ### Get a person's posts
 
 ```bash
@@ -144,6 +187,10 @@ This is the most expensive LinkedIn endpoint — search first, then fetch detail
 npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__user__profile \
   --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/"}}'
 
+# 1b. Only if experience/education came back null — career history from the fallback
+npx xapi-to call icypeas-email.api_scrape_profile \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/"}}'
+
 # 2. Their posts (take `urn` from each item for step 3)
 npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__user__posts \
   --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/","page":1}}'
@@ -186,6 +233,12 @@ npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__company__profile \
 | `search__jobs` | Job search | `keywords` | `location`, `page` |
 | `get__job__detail` | Full job posting | `url` | — |
 
+One non-`linkedin` action belongs in this workflow:
+
+| Action ID | Purpose | Required params | Notes |
+|---|---|---|---|
+| `icypeas-email.api_scrape_profile` | Career history for profiles the logged-out page hides | `url` | Fallback when `get__user__profile` returns `experience: null`. Check `data.status == "FOUND"`. |
+
 Detail-style endpoints (`get__*__profile`, `get__post__detail`) are the cheapest; list-style endpoints (posts, comments, job search) cost more per call, and `get__job__detail` is the most expensive. Run `npx xapi-to get <action-id>` for the current `meta.pricing` rather than assuming these ratios hold.
 
 ## Error Handling
@@ -195,4 +248,6 @@ Detail-style endpoints (`get__*__profile`, `get__post__detail`) are the cheapest
 - **`must have required property 'urn'`** — `get__post__comments` needs the numeric `urn` alongside `url`. See [Get comments on a post](#get-comments-on-a-post).
 - **`must match pattern "^[0-9]+$"` on `/params/urn`** — you passed the prefixed `urn:li:activity:<id>` form. Send the digits only.
 - **`API Token lacks required permissions`** (upstream `403`) — the account's upstream provider token has no LinkedIn scope. This is an account entitlement, not a parameter problem; enable it in the provider dashboard.
+- **`experience: null` / `education: null` / `about` ending in `…` on `get__user__profile`** — not an error and not a private profile: the logged-out page LinkedIn serves for ordinary members omits those sections. Fall back to `icypeas-email.api_scrape_profile`. See [When `experience` and `education` come back `null`](#when-experience-and-education-come-back-null).
+- **A ContactOut response naming `Example Person` at `Legros, Smitham and Kessler`** — `contactout-api.*` returned its sample payload because the account has no ContactOut entitlement. It carries `status_code: 200` and a `message` pointing at a sales call. Discard it; never summarize from it.
 - **Empty `data[]` on a valid URL** — either the page is private/deleted, or you paginated past the end. LinkedIn also rate-limits aggressively; retry with backoff rather than in a tight loop.

package/skills/xapi/guides/provider.md

@@ -0,0 +1,198 @@
+# Provider service management
+
+Read this guide for provider-side service authoring and operations. These
+commands use `XAPI-KEY` directly and never exchange it for a broad JWT session.
+The key must belong to the service owner and carry the scope named by the
+operation.
+
+## Inspect capabilities and scopes
+
+```bash
+npx xapi-to provider --help
+npx xapi-to skill --help
+npx xapi-to skill spec
+```
+
+Use narrowly scoped keys. Common scopes are:
+
+- `service:create`, `service:read`, `service:update`
+- `version:create`, `service:publish`, `service:rollback`
+- `observability:read`
+- `skill:read`, `skill:submit`
+- `earnings:read`; `earnings:transfer` only when reinvestment is intended
+- `service:delete` only for deliberate removal workflows
+
+Scope permission and ownership are independent. A key with a scope still cannot
+manage another provider's service or Skill.
+
+## Create and describe a service
+
+Create uses the backend service DTO as JSON so credentials and endpoint
+contracts do not have to appear in shell history:
+
+```bash
+npx xapi-to provider create --file ./service.json
+npx xapi-to provider list
+npx xapi-to provider get <service-id>
+```
+
+Keep the three service content layers distinct:
+
+- `description` is the short marketplace-card summary.
+- `aboutMarkdown` is the long About tab.
+- `website` is a public HTTP(S) link.
+
+Prefer files for long text:
+
+```bash
+npx xapi-to provider update <service-id> \
+  --description "Short marketplace summary" \
+  --about-file ./ABOUT.md \
+  --website https://example.com
+```
+
+Use `--clear-about` or `--clear-website` to clear a value. Provider metadata
+updates cannot modify the version contract or upstream credentials; use the
+version command for those fields.
+
+## Edit and publish a revision
+
+```bash
+# Inspect current majors and revisions
+npx xapi-to provider versions <service-id>
+
+# Either create a new major or pull a working revision from an existing major
+npx xapi-to provider major create <service-id>
+npx xapi-to provider revision start <service-id> <major>
+
+# Merge a partial version-contract update; add --replace for full replacement
+npx xapi-to provider version update \
+  <service-id> <version-id> --file ./contract.json
+
+# Inspect before publishing
+npx xapi-to provider diff <service-id> <major>
+
+# Submit through the normal review gate with public release notes
+npx xapi-to provider publish \
+  <service-id> <revision-id> --changelog-file ./CHANGELOG.md
+
+# Inspect the review result
+npx xapi-to provider review <service-id> <revision-id>
+```
+
+The changelog is provider-authored, public release information associated with
+that revision. It is not a system deployment log. Build, review, and runtime
+events are generated by the platform and should only be read, never uploaded as
+if they were evidence.
+
+`publish` can change live service behavior after review. The CLI does not
+automatically retry this write after an ambiguous transport failure. Read the
+version overview and review state before deciding whether to submit again.
+
+## Create, upload, and link the usage Skill
+
+Generate a service-specific starting point from the currently serving endpoints:
+
+```bash
+npx xapi-to provider skill scaffold \
+  <service-id> --output ./my-service/SKILL.md
+```
+
+The scaffold command refuses to overwrite an existing file unless `--force` is
+explicitly supplied. Complete the instructions and metadata, then submit either
+a local directory or a public GitHub tree:
+
+```bash
+npx xapi-to skill submit --dir ./my-service
+
+npx xapi-to skill submit \
+  --github https://github.com/org/repo/tree/main/skills/my-service \
+  --version 1.0.0
+```
+
+Local submission skips symlinks, `.git`, and `node_modules`; requires a root
+`SKILL.md`; permits at most 100 files; limits each file to 512 KiB and the encoded
+package to 2 MiB. The server still performs manifest validation and secret
+scanning. A successful upload creates or updates the owned Skill version and
+submits it for review; it is not immediately public.
+
+Use the returned submission ID:
+
+```bash
+npx xapi-to skill status <submission-id>
+npx xapi-to skill wait <submission-id> --timeout 10m
+```
+
+After the Skill is published, bind it as the service's primary tutorial and
+record the serving-contract fingerprint:
+
+```bash
+npx xapi-to provider skill link <service-id> <skill-id>
+npx xapi-to provider skill fingerprint \
+  <service-id> --skill-version-id <skill-version-id>
+npx xapi-to provider skill context <service-id>
+```
+
+Only a Skill owned by the same provider can be linked, and one Skill can be the
+primary Skill of only one service. The backend permits linking a pending Skill,
+but the public marketplace exposes only a published version; wait for publication
+unless intentionally preparing the association early. Use `provider skill unlink`
+to remove the primary association. The context response reports drift when host,
+major version, or serving endpoints no longer match the stored fingerprint; update
+and resubmit the Skill rather than merely overwriting the fingerprint.
+
+## Observe and recover
+
+```bash
+npx xapi-to provider metrics --days 30
+npx xapi-to provider metrics <service-id> --days 7
+npx xapi-to provider events --limit 50
+npx xapi-to provider events --after '<opaque-next-cursor>' --limit 50
+```
+
+Pass event cursors back unchanged. Metrics and events are owner-scoped; usage
+events are also restricted to the current key where applicable.
+
+Verify the finalized cost of a canary or provider call with its receipt ID. Use
+the `X-XAPI-Request-Id` response header or the final `xapi.usage` SSE event, and
+wait when asynchronous billing has not finalized yet:
+
+```bash
+npx xapi-to usage <request-id>
+npx xapi-to usage wait <request-id> --timeout 1m
+```
+
+Receipt reads are idempotent. The wait command applies one total deadline,
+retries not-found and transient transport failures within that deadline, and
+fails immediately for permanent authorization or validation errors.
+
+Rollback and default-major changes affect live routing:
+
+```bash
+npx xapi-to provider rollback \
+  <service-id> <major> --revision <published-revision-id> \
+  --reason "Restore the last known-good contract"
+npx xapi-to provider default-major <service-id> <major>
+npx xapi-to provider deprecate <service-id> <major>
+npx xapi-to provider restore <service-id> <major>
+```
+
+Inspect the target revision before rollback. Do not automatically retry an
+ambiguous rollback response. Deletion requires both `service:delete` and an
+explicit service name or ID confirmation:
+
+```bash
+npx xapi-to provider delete <service-id> --confirm <service-name-or-id>
+```
+
+## Earnings reinvestment
+
+```bash
+npx xapi-to earnings
+npx xapi-to earnings list --status SETTLED
+npx xapi-to earnings transfer 1 --idempotency-key <stable-operation-key>
+```
+
+Transfer is one-way: it converts settled provider earnings into spendable xAPI
+balance. Confirm the amount and available settled balance first. A transfer may
+be retried only with the same idempotency key and the same amount.