xapi-to 0.1.20 → 0.1.21

package/README.md

@@ -327,11 +327,52 @@ 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 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 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-UEQCIJ7T.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}`;
 }
@@ -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,