xapi-to 0.1.20 → 0.1.22

package/README.md

@@ -26,7 +26,8 @@ npx skills add xapi-labs/xapi-cli
 ```
 
 This installs the bundled [`xapi` skill](skills/xapi), which teaches the agent
-how to call social, search, crypto, and AI data through this CLI. Then just ask
+how to call social, search, domains/DNS, crypto, BlockPI RPC, Binance Web3, and
+AI services through this CLI. Then just ask
 — "what's the price of BTC" — and it takes it from there. Set up a key first;
 see [Quick Start](#quick-start).
 
@@ -111,6 +112,13 @@ WebSocket client. Active SSE and raw downloads may run longer than 60 seconds,
 but abort after 60 seconds without data by default. Set
 `XAPI_TRANSFER_IDLE_TIMEOUT_MS` to change that idle timeout.
 
+GPT Live is a WebSocket protocol and cannot be invoked with `xapi-to call`.
+Read [the WebSocket Gateway guide](skills/xapi/guides/ws_gateway.md) and use a
+real WebSocket client. The packaged
+[`examples/openai-gpt-live-text.mjs`](examples/openai-gpt-live-text.mjs)
+demonstrates `session.start`, managed Responses delegation, text events, and a
+graceful `session.close` without placing an xAPI key in source or CLI arguments.
+
 ### Async Task Commands
 
 Task helpers built on top of the `task.poll` capability.
@@ -121,6 +129,114 @@ xapi-to task wait 550e8400-e29b-41d4-a716-446655440000                 # wait un
 xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 1s --timeout 10m
 ```
 
+### Provider: Import → Configure → Submit → Wait
+
+`provider` manages APIs owned by your account. It uses `XAPI_API_HOST`
+(default `api.xapi.to`) and the same saved or environment API key as other
+commands. In the xAPI Console API Keys settings, grant `service:create`,
+`service:read`, `service:update`, and `service:publish`. Legacy `allowRegister`
+only grants creation, not the remaining lifecycle permissions. Missing
+permissions return a nonzero exit with the required scope.
+
+Start from [examples/provider/openapi.json](examples/provider/openapi.json),
+replace its upstream URL, service details, and endpoint contract, then run:
+
+```bash
+# Inspect current rules; no API key required
+xapi-to provider spec-rules --format pretty
+
+# Import a raw OpenAPI 3.0.3 JSON object (not a {openApiSpec: ...} envelope)
+xapi-to provider import --file openapi.json > imported.json
+
+# Use the serviceId and revisionId from imported.json (jq is optional)
+PROVIDER_SERVICE_ID=$(jq -er '.serviceId' imported.json)
+PROVIDER_REVISION_ID=$(jq -er '.revisionId' imported.json)
+
+# Save version configuration to move the draft revision to SANDBOX.
+# config.json can be {"description":"Initial release"} when the imported
+# endpoints, authentication, and pricing are already complete.
+xapi-to provider update "$PROVIDER_SERVICE_ID" \
+  --revision "$PROVIDER_REVISION_ID" --file config.json
+
+# Submit the specified revision, then wait for the actual publication result
+xapi-to provider submit "$PROVIDER_SERVICE_ID" \
+  --revision "$PROVIDER_REVISION_ID" --changelog "Initial release"
+xapi-to provider wait "$PROVIDER_SERVICE_ID" \
+  --revision "$PROVIDER_REVISION_ID" --interval 2s --timeout 10m
+
+# Inspect owned services, configuration, version overview, or review reports
+xapi-to provider list --format table
+xapi-to provider get "$PROVIDER_SERVICE_ID" --format pretty
+xapi-to provider versions "$PROVIDER_SERVICE_ID" --format pretty
+xapi-to provider review "$PROVIDER_SERVICE_ID" --revision "$PROVIDER_REVISION_ID"
+```
+
+When scripting these steps, stop on nonzero exit (for example, use `set -e`).
+Import returns the backend validation/preview plus `serviceId`, `revisionId`,
+and `state`. An HTTP 201 with `success: false` is a validation failure and exits
+nonzero; its structured validation errors are preserved. Registration creates
+a new service each time. If a response is lost, inspect `provider list` before
+retrying to avoid duplicate services.
+
+For an authenticated upstream, store credentials in a local JSON object such
+as `{"Authorization":"Bearer YOUR_UPSTREAM_KEY"}` and pass
+`--private-headers-file private-headers.json` to `provider import`. Keep this
+file out of version control. `--file -` and `--private-headers-file -` accept
+stdin, but only one input can consume stdin per command. Files must be JSON;
+YAML and URL imports are not supported in this command group.
+
+`provider update --revision <id>` reads a version configuration object, using the backend
+fields `description`, `baseUrl`, `baseUrls`, `authType`, `privateHeaders`,
+`authConfig`, `openApiSpec`, `endpoints`, and `status`. Prefer structured
+`privateHeaders` for upstream credentials. Endpoint fields include billing
+configuration such as `billingType` and `costPerCall`. Update does not accept
+a raw OpenAPI document; the nested backend field is `openApiSpec: {spec: ...}`.
+Saving that field alone does not re-import endpoint definitions; configure
+`endpoints` explicitly when changing the contract.
+
+- `--mode merge` (default) sends PATCH and preserves omitted fields/endpoints.
+  Existing endpoint edits require `id`, e.g.
+  `{"endpoints":[{"id":"ENDPOINT_ID","costPerCall":"0.002"}]}`.
+- `--allow-new-endpoints` explicitly permits ID-less merge entries to create
+  endpoints. Repeating such a merge can create duplicates.
+- `--mode replace` sends PUT. If `endpoints` is provided, it replaces the
+  endpoint list; include every endpoint you intend to keep. Omitted fields
+  otherwise follow backend PUT semantics. Use full configuration for replacement.
+
+`get` retains its existing service response; `--version v1.0` selects the
+configuration returned by the backend. Find endpoint IDs in
+`currentVersion.endpoints`; `provider versions` returns working revision IDs
+in `majors[].working.id`. For an already-published API, use the existing
+`provider revision start <service-id> <major>` command to create a working revision.
+`provider update` without `--revision` continues to update service metadata
+and rate limits. Existing `version update`, `publish`, and positional `review`
+commands remain available. The `submit` and `review --revision` forms are
+additional onboarding commands.
+
+Updates to `IN_REVIEW`, `PUBLISHED`, or `SUSPENDED` revisions return a conflict;
+the backend enforces this check under a transaction lock. When updating
+`privateHeaders`, send the complete desired map: it replaces the old map and
+rebuilds the derived authentication configuration. An empty map without an
+explicit `authConfig` clears those credentials. Omitting both fields preserves them.
+
+`submit` returns `{serviceId, revisionId, submission}`. A successful submission
+does not guarantee publication. `wait` checks the requested revision, succeeds
+only for `PUBLISHED`, and outputs the review report with `success` and `reason`.
+`--changelog` is limited to 2,000 characters by both the CLI and backend.
+Rejection, a draft/sandbox/suspended revision, or a legacy manual-review hold
+exit nonzero. Pending review continues until publication, the timeout (default
+10 minutes), or optional `--max-attempts`. Timeout and attempt-limit results
+include the last received report; polling can be resumed with the same IDs.
+The deadline also bounds in-flight HTTP requests and retry delays.
+
+Reads retry transient errors; writes are never automatically retried. The CLI
+redacts credential fields and known credential values from provider output.
+Redacted reads are for inspection and must not be submitted unchanged as
+configuration. After an ambiguous write failure, use `list`, `get`, or `review`
+to inspect the result before repeating the operation. No npm release is implied
+by a local source checkout; use `bun run src/index.ts provider ...` or build and
+run `node dist/index.js provider ...` while testing unreleased changes.
+
 ### Sandbox Commands
 
 Sandbox commands provide an AI-friendly cloud computer lifecycle. The fastest
@@ -327,11 +443,58 @@ xapi-to register --referral-code xapito                 # register with an invit
 xapi-to register xapito                                 # positional shorthand for --referral-code
 xapi-to register --force                                # replace an existing file-based key
 xapi-to balance                                         # show USD balance
+xapi-to usage <request-id>                              # finalized cost + balance-after receipt
+xapi-to usage wait <request-id> --timeout 1m            # poll until a streaming receipt is finalized
+xapi-to earnings                                        # spendable balance + provider earnings
+xapi-to earnings list --status SETTLED --limit 20       # provider earning records
+xapi-to earnings transfer 1 --idempotency-key reinvest-001 # reinvest settled earnings
 xapi-to topup                                           # generate payment URL
 xapi-to topup --method stripe --amount 10               # stripe, $10
 xapi-to topup --method x402                             # x402 (USDC on Base)
 ```
 
+`earnings` summary/list require the `earnings:read` scope on the current key;
+`earnings transfer` requires `earnings:transfer`. Transfers are one-way and
+idempotent: reuse a key only when retrying the same amount.
+
+### Provider Management
+
+Provider commands use scoped `XAPI-KEY` routes for service and release
+management without a JWT exchange:
+
+```bash
+xapi-to provider list
+xapi-to provider create --file ./service.json
+xapi-to provider update <service-id> --about-file ./ABOUT.md --website https://example.com
+xapi-to provider update <service-id> --rate-limit-requests 100 --rate-limit-period-seconds 60
+xapi-to provider update <service-id> --clear-rate-limit
+xapi-to provider versions <service-id>
+xapi-to provider revision start <service-id> 1
+xapi-to provider version update <service-id> <version-id> --file ./contract.json
+xapi-to provider diff <service-id> 1
+xapi-to provider publish <service-id> <revision-id> --changelog-file ./CHANGELOG.md
+xapi-to provider metrics <service-id> --days 7
+xapi-to provider events --after '<opaque-next-cursor>'
+```
+
+Service rate limits are optional and supported only for proxied services. Both
+numeric flags are required when setting a limit; the quota is shared by all API
+keys belonging to the same user for that service.
+
+Service usage tutorials are Skill packages. Scaffold one from the serving
+contract, submit it for review, wait for publication, then link it:
+
+```bash
+xapi-to provider skill scaffold <service-id> --output ./my-skill/SKILL.md
+xapi-to skill submit --dir ./my-skill
+xapi-to skill wait <submission-id> --timeout 10m
+xapi-to provider skill link <service-id> <skill-id>
+xapi-to provider skill fingerprint <service-id> --skill-version-id <version-id>
+```
+
+Run `xapi-to provider --help` and `xapi-to skill --help` for the complete
+lifecycle, rollback, deletion, GitHub import, scope, and safety options.
+
 ### Config
 
 ```bash

package/dist/{chunk-TYY6JR6O.js → chunk-2YRWNREY.js}

@@ -265,8 +265,25 @@ function parseRetryAfterMs(res) {
   const at = Date.parse(header);
   return Number.isFinite(at) ? Math.max(0, at - Date.now()) : void 0;
 }
-function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+function abortError(signal) {
+  const reason = signal?.reason;
+  return reason instanceof Error ? reason : new DOMException("The operation was aborted", "AbortError");
+}
+function sleep(ms, signal) {
+  if (signal?.aborted) return Promise.reject(abortError(signal));
+  return new Promise((resolve2, reject) => {
+    let timer;
+    const onAbort = () => {
+      if (timer !== void 0) clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(abortError(signal));
+    };
+    timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve2();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
 }
 async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0) {
   assertAllowedHost(url);
@@ -294,7 +311,7 @@ async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0
         if (isRetryableStatus(res.status) && attempt < retries) {
           await res.text().catch(() => "");
           clearTimeout(timer);
-          await sleep(backoffDelayMs(attempt, retryAfterMs));
+          await sleep(backoffDelayMs(attempt, retryAfterMs), callerSignal);
           attempt++;
           continue;
         }
@@ -327,7 +344,7 @@ async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0
       if (timedOut) {
         const timeoutError = new RequestTimeoutError(timeoutMs);
         if (attempt < retries) {
-          await sleep(backoffDelayMs(attempt));
+          await sleep(backoffDelayMs(attempt), callerSignal);
           attempt++;
           continue;
         }
@@ -335,7 +352,7 @@ async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0
       }
       if (isRetryableNetworkError(e) && attempt < retries) {
         clearTimeout(timer);
-        await sleep(backoffDelayMs(attempt));
+        await sleep(backoffDelayMs(attempt), callerSignal);
         attempt++;
         continue;
       }
@@ -351,6 +368,21 @@ function headers(apiKey) {
   if (apiKey) h["XAPI-Key"] = apiKey;
   return h;
 }
+function apiKeyApiRequest(apiHost, apiKey, path, options = {}) {
+  const method = options.method ?? "GET";
+  const requestHeaders = { "XAPI-KEY": apiKey };
+  if (options.body !== void 0) requestHeaders["Content-Type"] = "application/json";
+  return request(
+    `${scheme(apiHost)}://${apiHost}${path}`,
+    {
+      method,
+      headers: requestHeaders,
+      ...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {}
+    },
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    options.retries ?? 0
+  );
+}
 function baseUrl(opts) {
   return `${scheme(opts.actionHost)}://${opts.actionHost}`;
 }
@@ -657,10 +689,10 @@ async function initiateOAuth(apiKeyId, providerId, jwtToken, apiHost, scopes) {
     }
   );
 }
-async function listOAuthBindings(jwtToken, apiHost) {
+async function listOAuthBindings(jwtToken, apiHost, signal) {
   return request(
     `${scheme(apiHost)}://${apiHost}/api/oauth/bindings`,
-    { method: "GET", headers: jwtHeaders(jwtToken) },
+    { method: "GET", headers: jwtHeaders(jwtToken), signal },
     DEFAULT_TIMEOUT_MS,
     IDEMPOTENT_RETRIES
   );
@@ -794,24 +826,43 @@ var sandboxAudit = (opts, id, kind, page = 1, pageSize = 100) => sandboxRequest(
 );
 async function sandboxWait(opts, id, wanted, timeoutMs = 3e5, intervalMs = 2e3, signal) {
   const deadline = Date.now() + timeoutMs;
+  const deadlineController = new AbortController();
+  const abortFromCaller = () => deadlineController.abort();
+  const deadlineTimer = setTimeout(() => deadlineController.abort(), Math.max(0, timeoutMs));
+  if (signal?.aborted) deadlineController.abort();
+  else signal?.addEventListener("abort", abortFromCaller, { once: true });
   let last;
-  while (Date.now() < deadline) {
-    if (signal?.aborted) throw new Error(`sandbox wait interrupted while waiting for ${wanted.join(" or ")}`);
-    last = await sandboxGet(opts, id, signal);
-    const state = String(last.observedState || "");
-    if (wanted.includes(state)) return last;
-    if (["FAILED", "TERMINATED"].includes(state) && !wanted.includes(state)) {
-      throw new Error(`sandbox ${id} entered ${state} while waiting for ${wanted.join(" or ")}`);
+  try {
+    while (Date.now() < deadline) {
+      if (signal?.aborted) throw new Error(`sandbox wait interrupted while waiting for ${wanted.join(" or ")}`);
+      try {
+        last = await sandboxGet(opts, id, deadlineController.signal);
+      } catch (error) {
+        if (signal?.aborted) {
+          throw new Error(`sandbox wait interrupted while waiting for ${wanted.join(" or ")}`);
+        }
+        if (Date.now() >= deadline) break;
+        throw error;
+      }
+      if (Date.now() >= deadline) break;
+      const state = String(last.observedState || "");
+      if (wanted.includes(state)) return last;
+      if (["FAILED", "TERMINATED"].includes(state) && !wanted.includes(state)) {
+        throw new Error(`sandbox ${id} entered ${state} while waiting for ${wanted.join(" or ")}`);
+      }
+      await new Promise((resolve2) => {
+        const done = () => {
+          clearTimeout(timer);
+          signal?.removeEventListener("abort", done);
+          resolve2();
+        };
+        const timer = setTimeout(done, Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+        signal?.addEventListener("abort", done, { once: true });
+      });
     }
-    await new Promise((resolve2) => {
-      const done = () => {
-        clearTimeout(timer);
-        signal?.removeEventListener("abort", done);
-        resolve2();
-      };
-      const timer = setTimeout(done, Math.min(intervalMs, Math.max(0, deadline - Date.now())));
-      signal?.addEventListener("abort", done, { once: true });
-    });
+  } finally {
+    clearTimeout(deadlineTimer);
+    signal?.removeEventListener("abort", abortFromCaller);
   }
   throw new Error(
     `sandbox ${id} did not enter ${wanted.join(" or ")} within ${timeoutMs}ms (last state: ${last?.observedState || "unknown"})`
@@ -835,6 +886,7 @@ export {
   HttpError,
   isRetryableRequestError,
   request,
+  apiKeyApiRequest,
   actionList,
   actionSearch,
   actionCategories,