@alva-ai/toolkit 0.2.1 → 0.3.1

package/dist/cli.js

@@ -28,9 +28,20 @@ var FsResource = class {
   client;
   /** Returns `ArrayBuffer` for binary files, or parsed JSON for time-series virtual paths. */
   async read(params) {
-    return this.client._request("GET", "/api/v1/fs/read", {
+    const result = await this.client._request("GET", "/api/v1/fs/read", {
       query: { path: params.path, offset: params.offset, size: params.size }
     });
+    if (!(result instanceof ArrayBuffer)) return result;
+    try {
+      const text = new TextDecoder("utf-8", { fatal: true }).decode(result);
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    } catch {
+      return result;
+    }
   }
   /** Write file using JSON body (Mode 2). For text content. */
   async write(params) {
@@ -338,6 +349,55 @@ var SdkDocsResource = class {
   }
 };
 
+// src/resources/skills.ts
+var SkillsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async list() {
+    const res = await this.client._request("GET", "/api/v1/skills", {
+      baseUrl: this.client.arraysBaseUrl,
+      noAuth: true
+    });
+    return { skills: res.data ?? [] };
+  }
+  async summary(params) {
+    const encoded = encodeURIComponent(params.name);
+    const res = await this.client._request(
+      "GET",
+      `/api/v1/skills/${encoded}`,
+      {
+        baseUrl: this.client.arraysBaseUrl,
+        noAuth: true
+      }
+    );
+    const doc = res.data?.[0];
+    if (!doc)
+      throw new Error(`empty skills summary response for "${params.name}"`);
+    return doc;
+  }
+  async endpoint(params) {
+    const encoded = encodeURIComponent(params.name);
+    const res = await this.client._request(
+      "GET",
+      `/api/v1/skills/${encoded}`,
+      {
+        baseUrl: this.client.arraysBaseUrl,
+        noAuth: true,
+        query: { endpoint: params.file }
+      }
+    );
+    const doc = res.data?.[0];
+    if (!doc) {
+      throw new Error(
+        `empty skills endpoint response for "${params.name}" file "${params.file}"`
+      );
+    }
+    return doc;
+  }
+};
+
 // src/resources/comments.ts
 var CommentsResource = class {
   constructor(client) {
@@ -493,10 +553,36 @@ var TradingResource = class {
   }
 };
 
+// src/resources/arraysJwt.ts
+var ArraysJwtResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Idempotently sign-or-renew the Arrays JWT server-side. */
+  async ensure() {
+    this.client._requireAuth();
+    return this.client._request(
+      "POST",
+      "/api/v1/arrays-jwt/ensure"
+    );
+  }
+  /** Report the current Arrays JWT state for the authenticated user. */
+  async status() {
+    this.client._requireAuth();
+    return this.client._request(
+      "GET",
+      "/api/v1/arrays-jwt/status"
+    );
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api-llm.prd.alva.ai";
+var DEFAULT_ARRAYS_BASE_URL = "https://data-tools.prd.space.id";
 var AlvaClient = class {
   baseUrl;
+  arraysBaseUrl;
   viewer_token;
   apiKey;
   _fs;
@@ -505,13 +591,16 @@ var AlvaClient = class {
   _release;
   _secrets;
   _sdk;
+  _skills;
   _comments;
   _remix;
   _screenshot;
   _user;
   _trading;
+  _arraysJwt;
   constructor(config) {
     this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.arraysBaseUrl = config.arraysBaseUrl ?? DEFAULT_ARRAYS_BASE_URL;
     this.viewer_token = config.viewer_token;
     this.apiKey = config.apiKey;
   }
@@ -533,6 +622,9 @@ var AlvaClient = class {
   get sdk() {
     return this._sdk ??= new SdkDocsResource(this);
   }
+  get skills() {
+    return this._skills ??= new SkillsResource(this);
+  }
   get comments() {
     return this._comments ??= new CommentsResource(this);
   }
@@ -548,6 +640,9 @@ var AlvaClient = class {
   get trading() {
     return this._trading ??= new TradingResource(this);
   }
+  get arraysJwt() {
+    return this._arraysJwt ??= new ArraysJwtResource(this);
+  }
   _requireAuth() {
     if (!this.viewer_token && !this.apiKey) {
       throw new AlvaError(
@@ -558,7 +653,8 @@ var AlvaClient = class {
     }
   }
   async _request(method, path, options) {
-    let url = `${this.baseUrl}${path}`;
+    const baseUrl = options?.baseUrl ?? this.baseUrl;
+    let url = `${baseUrl}${path}`;
     if (options?.query) {
       const params = new URLSearchParams();
       for (const [key, value] of Object.entries(options.query)) {
@@ -572,10 +668,12 @@ var AlvaClient = class {
       }
     }
     const headers = {};
-    if (this.viewer_token) {
-      headers["x-Playbook-Viewer"] = this.viewer_token;
-    } else if (this.apiKey) {
-      headers["X-Alva-Api-Key"] = this.apiKey;
+    if (!options?.noAuth) {
+      if (this.viewer_token) {
+        headers["x-Playbook-Viewer"] = this.viewer_token;
+      } else if (this.apiKey) {
+        headers["X-Alva-Api-Key"] = this.apiKey;
+      }
     }
     let fetchBody;
     if (options?.rawBody !== void 0) {
@@ -691,6 +789,7 @@ async function writeConfig(config, deps, profileName = "default") {
   return {
     apiKey: profileData.apiKey,
     baseUrl: profileData.baseUrl,
+    arraysBaseUrl: DEFAULT_ARRAYS_BASE_URL,
     profile: profileName
   };
 }
@@ -710,6 +809,8 @@ function loadConfig(deps) {
   const profileName = parseFlag(argv, "--profile") || env.ALVA_PROFILE || "default";
   const baseUrlFlag = parseFlag(argv, "--base-url");
   const baseUrlEnv = env.ALVA_ENDPOINT;
+  const arraysBaseUrlFlag = parseFlag(argv, "--arrays-endpoint");
+  const arraysBaseUrlEnv = env.ARRAYS_ENDPOINT;
   const apiKeyFlag = parseFlag(argv, "--api-key");
   const apiKeyEnv = env.ALVA_API_KEY;
   let fileProfile = {};
@@ -731,6 +832,7 @@ function loadConfig(deps) {
   return {
     apiKey: apiKeyFlag ?? apiKeyEnv ?? fileProfile.apiKey,
     baseUrl: baseUrlFlag ?? baseUrlEnv ?? fileProfile.baseUrl,
+    arraysBaseUrl: arraysBaseUrlFlag ?? arraysBaseUrlEnv ?? DEFAULT_ARRAYS_BASE_URL,
     profile: profileName
   };
 }
@@ -859,11 +961,48 @@ Waiting for login callback...
   });
 }
 
+// src/cli/postConfigureHooks.ts
+function defaultStderr(s) {
+  process.stderr.write(s);
+}
+function formatTier(t) {
+  const stripped = typeof t === "string" && t.startsWith("SUBSCRIPTION_TIER_") ? t.slice("SUBSCRIPTION_TIER_".length) : String(t);
+  return stripped.toLowerCase();
+}
+function formatExpiry(expiresAt) {
+  return new Date(expiresAt * 1e3).toISOString().slice(0, 10);
+}
+var ensureArraysJwtHook = {
+  name: "ensureArraysJwt",
+  async run(client) {
+    const res = await client.arraysJwt.ensure();
+    const date = formatExpiry(res.expires_at);
+    const tier = formatTier(res.tier);
+    const verb = res.renewed ? "Arrays JWT provisioned" : "Arrays JWT already current";
+    process.stderr.write(`${verb} (expires ${date}, tier: ${tier})
+`);
+  }
+};
+var POST_CONFIGURE_HOOKS = [ensureArraysJwtHook];
+async function runPostConfigureHooks(client, deps) {
+  const hooks = deps?.hooks ?? POST_CONFIGURE_HOOKS;
+  const stderr = deps?.stderr ?? defaultStderr;
+  for (const hook of hooks) {
+    try {
+      await hook.run(client);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      stderr(`warning: post-configure hook "${hook.name}" failed: ${msg}
+`);
+    }
+  }
+}
+
 // src/cli/index.ts
 import * as fs from "fs";
 import * as os2 from "os";
 import * as fsPromises2 from "fs/promises";
-var CLI_VERSION = true ? "0.2.1" : "dev";
+var CLI_VERSION = true ? "0.3.1" : "dev";
 function isVersionOlderThan(a, b) {
   const parse = (v) => {
     if (!v) return null;
@@ -893,16 +1032,19 @@ Commands:
   release     Feed and playbook releases (feed, playbook-draft, playbook)
   secrets     Secret management (create, list, get, update, delete)
   sdk         SDK documentation (doc, partitions, partition-summary)
+  skills      Data-skill documentation from the Arrays backend (list, summary, endpoint)
   comments    Playbook comments (create, pin, unpin)
   remix       Save playbook remix lineage
   trading     Trading operations (accounts, portfolio, orders, subscriptions, equity-history, risk-rules, subscribe, unsubscribe, execute, update-risk-rules)
   auth        Authentication (login)
   screenshot  Capture a web screenshot as PNG
+  arrays      Arrays backend operations (token ensure, token status)
 
 Global options:
-  --api-key <key>      API key (overrides env and config file)
-  --base-url <url>     API base URL (overrides env and config file)
-  --profile <name>     Named profile to use (default: "default")
+  --api-key <key>        API key (overrides env and config file)
+  --base-url <url>       API base URL (overrides env and config file)
+  --profile <name>       Named profile to use (default: "default")
+  --arrays-endpoint <url>  Arrays backend URL (or ARRAYS_ENDPOINT env; default: https://data-tools.prd.space.id)
   -v, --version        Show CLI version
   --help               Show help (use 'alva <command> --help' for command details)
 
@@ -919,6 +1061,8 @@ var COMMAND_HELP = {
 Save API credentials to ~/.config/alva/config.json (mode 0600).
 After configuring, subsequent commands use the saved key automatically.
 Multiple profiles allow switching between environments (production, staging, etc.).
+Also auto-runs 'alva arrays token ensure' to provision the server-side Arrays JWT
+(soft-fail: a network/auth failure prints a stderr warning but exit stays 0).
 
 Required:
   --api-key <key>      Your Alva API key (starts with "alva_")
@@ -954,6 +1098,9 @@ Verify that your credentials are valid by calling the Alva API. Shows your
 username, subscription tier, and which profile/endpoint is being used.
 Use this after 'alva configure' to confirm everything works.
 
+Output also includes _meta.arrays_jwt (exists, expires_at, renewal_needed,
+tier) when the backend is reachable; the field is omitted on RPC failure.
+
 Examples:
   alva whoami
   alva --profile staging whoami`,
@@ -1170,7 +1317,7 @@ Playbook-draft flags:
   --name <name>              URL-safe playbook name, unique per user (required)
   --display-name <name>      Human-readable title, max 40 chars (required)
   --feeds <json>             JSON array of {feed_id, feed_major?} (required)
-  --changelog <text>         Release changelog (required)
+  --changelog <text>         Release changelog
   --description <text>       Playbook description
   --trading-symbols <json>   JSON array of tickers, e.g. '["BTC","ETH"]' (max 50)
 
@@ -1238,20 +1385,37 @@ Flags:
   --partition <name>     Partition name for 'partition-summary' (required)
 
 Key partitions:
-  spot_market_price_and_volume         Spot OHLCV for crypto and equities
-  crypto_futures_data                  Perpetual futures, funding rates, OI
-  crypto_technical_metrics             MA, RSI, MACD, MVRV, SOPR, NUPL (20 modules)
-  equity_fundamentals                  Income, balance sheet, PE, ROE (31 modules)
-  equity_estimates_and_targets         Analyst targets, consensus estimates
-  equity_ownership_and_flow            Insider trades, senator trading, institutions
-  macro_and_economics_data             CPI, GDP, Treasury rates, VIX (20 modules)
+  feed_widgets                             Per-handle/channel rolling subscriptions
+  unified_search                           Web search and URL scraping tools (X/Grok, Google, Brave, serper, decodo)
   technical_indicator_calculation_helpers  50+ pure calculators (RSI, MACD, Bollinger)
 
 Examples:
   alva sdk partitions
-  alva sdk partition-summary --partition spot_market_price_and_volume
-  alva sdk doc --name "@arrays/crypto/ohlcv:v1.0.0"
-  alva sdk doc --name "@arrays/data/stock/ohlcv:v1.0.0"`,
+  alva sdk partition-summary --partition feed_widgets
+  alva sdk doc --name "@arrays/data/widget-scrap/twitter:v1.0.0"
+  alva sdk doc --name "@arrays/data/search/search-grok-x:v1.0.0"`,
+  skills: `Usage: alva skills <subcommand> [options]
+
+Browse the Arrays backend's data-skill documentation. These endpoints are
+public \u2014 no Alva credentials required.
+
+Subcommands:
+  list       List all available data skills
+  summary    Get the endpoints table for a skill (requires --name)
+  endpoint   Get full documentation for a specific endpoint (requires --name and --file)
+
+Flags:
+  --name <name>      Skill name (required for summary and endpoint)
+  --file <file>      Endpoint file name from the "File" column of 'skills summary' (required for endpoint)
+
+Global override:
+  --arrays-endpoint <url>   Arrays backend URL (or ARRAYS_ENDPOINT env)
+                            Default: https://data-tools.prd.space.id
+
+Examples:
+  alva skills list
+  alva skills summary --name <skill>
+  alva skills endpoint --name <skill> --file <endpoint-file>`,
   comments: `Usage: alva comments <subcommand> [options]
 
 Manage comments on Alva playbooks. Supports top-level comments and threaded
@@ -1371,7 +1535,20 @@ Examples:
   alva trading subscribe --account-id acc_123 --source-username alice --source-feed btc-signals --playbook-id pb_1 --playbook-version v1.0.0
   alva trading unsubscribe --subscription-id sub_456
   alva trading execute --account-id acc_123 --signal '{"symbol":"BTC","side":"buy","qty":0.1}' --dry-run
-  alva trading update-risk-rules --max-single-order-value 10000 --max-single-order-enabled true --max-daily-turnover-value 50000 --max-daily-turnover-enabled true --max-daily-orders-value 100 --max-daily-orders-enabled true`
+  alva trading update-risk-rules --max-single-order-value 10000 --max-single-order-enabled true --max-daily-turnover-value 50000 --max-daily-turnover-enabled true --max-daily-orders-value 100 --max-daily-orders-enabled true`,
+  arrays: `Usage: alva arrays token <subcommand>
+
+Manage the Arrays JWT used by sandbox scripts (secret.loadPlaintext('ARRAYS_JWT')).
+The JWT is stored server-side as a jagent secret; the CLI never receives the
+token itself. 'alva configure' auto-runs 'token ensure' after saving credentials.
+
+Subcommands:
+  token ensure    Provision or refresh the Arrays JWT (idempotent)
+  token status    Show Arrays JWT presence, expiry, tier, and renewal hint
+
+Examples:
+  alva arrays token ensure
+  alva arrays token status`
 };
 async function handleConfigure(args, deps) {
   const flags = parseFlags2(args.slice(1));
@@ -1396,6 +1573,15 @@ async function handleConfigure(args, deps) {
     readFile: (path) => fsPromises2.readFile(path, "utf-8")
   };
   const result = await writeConfig(configInput, writeDeps, profileName);
+  const client = new AlvaClient(baseUrl ? { apiKey, baseUrl } : { apiKey });
+  const runHooks = writeDeps.runHooks ?? ((c) => runPostConfigureHooks(c));
+  try {
+    await runHooks(client);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr?.write?.(`warning: post-configure hooks crashed: ${msg}
+`);
+  }
   return {
     status: "configured",
     apiKey: result.apiKey,
@@ -1481,12 +1667,21 @@ async function dispatch(client, args, meta) {
     const user = await client.user.me();
     const record = user;
     const version = meta?.cliVersion ?? CLI_VERSION;
+    let arraysJwtStatus;
+    try {
+      arraysJwtStatus = await client.arraysJwt.status();
+    } catch {
+    }
+    const metaBlock = {
+      profile: meta?.profile ?? "default",
+      endpoint: meta?.baseUrl ?? client.baseUrl
+    };
+    if (arraysJwtStatus !== void 0) {
+      metaBlock.arrays_jwt = arraysJwtStatus;
+    }
     const result = {
       ...record,
-      _meta: {
-        profile: meta?.profile ?? "default",
-        endpoint: meta?.baseUrl ?? client.baseUrl
-      }
+      _meta: metaBlock
     };
     const minVersion = record.toolkit_min_version;
     if (typeof minVersion === "string" && version && version !== "dev" && isVersionOlderThan(version, minVersion)) {
@@ -1697,11 +1892,7 @@ async function dispatch(client, args, meta) {
               requireFlag(flags, "feeds", "release playbook-draft")
             ),
             trading_symbols: flags["trading-symbols"] ? jsonParse(flags["trading-symbols"]) : void 0,
-            changelog: requireFlag(
-              flags,
-              "changelog",
-              "release playbook-draft"
-            )
+            changelog: flags["changelog"]
           });
         case "playbook":
           return client.release.playbook({
@@ -1771,6 +1962,28 @@ async function dispatch(client, args, meta) {
           );
       }
     }
+    case "skills": {
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for skills", "skills");
+      switch (subcommand) {
+        case "list":
+          return client.skills.list();
+        case "summary":
+          return client.skills.summary({
+            name: requireFlag(flags, "name", "skills summary")
+          });
+        case "endpoint":
+          return client.skills.endpoint({
+            name: requireFlag(flags, "name", "skills endpoint"),
+            file: requireFlag(flags, "file", "skills endpoint")
+          });
+        default:
+          throw new CliUsageError(
+            `Unknown subcommand: skills ${subcommand}`,
+            "skills"
+          );
+      }
+    }
     case "comments": {
       if (!subcommand)
         throw new CliUsageError("Missing subcommand for comments", "comments");
@@ -1809,6 +2022,30 @@ async function dispatch(client, args, meta) {
         },
         parents: jsonParse(requireFlag(flags, "parents", "remix"))
       });
+    case "arrays": {
+      if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        return { _help: true, text: COMMAND_HELP.arrays };
+      }
+      if (subcommand === "token") {
+        const leaf = args[2];
+        if (!leaf || leaf === "--help" || leaf === "-h") {
+          return { _help: true, text: COMMAND_HELP.arrays };
+        }
+        switch (leaf) {
+          case "ensure":
+            return client.arraysJwt.ensure();
+          case "status":
+            return client.arraysJwt.status();
+          default:
+            throw new Error(
+              `Unknown subcommand 'arrays token ${leaf}'. Use 'alva arrays --help' for usage.`
+            );
+        }
+      }
+      throw new Error(
+        `Unknown subcommand 'arrays ${subcommand}'. Use 'alva arrays --help' for usage.`
+      );
+    }
     case "screenshot": {
       const outFile = requireFlag(flags, "out", "screenshot");
       const result = await client.screenshot.capture({
@@ -1817,6 +2054,12 @@ async function dispatch(client, args, meta) {
         xpath: flags["xpath"]
       });
       const buf = Buffer.from(result);
+      if (buf.length === 0) {
+        throw new CliUsageError(
+          "Screenshot service returned empty response (0 bytes). The service may be overloaded \u2014 retry in a few seconds.",
+          "screenshot"
+        );
+      }
       fs.writeFileSync(outFile, buf);
       return { written: outFile, bytes: buf.length };
     }
@@ -1940,6 +2183,27 @@ async function dispatch(client, args, meta) {
       throw new CliUsageError(`Unknown command: '${group}'`);
   }
 }
+function stripGlobalFlags(argv) {
+  const GLOBAL_FLAGS = [
+    "--api-key",
+    "--base-url",
+    "--profile",
+    "--arrays-endpoint"
+  ];
+  const result = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (GLOBAL_FLAGS.includes(a)) {
+      i++;
+      continue;
+    }
+    if (GLOBAL_FLAGS.some((f) => a.startsWith(`${f}=`))) {
+      continue;
+    }
+    result.push(a);
+  }
+  return result;
+}
 async function main() {
   try {
     const rawArgs = process.argv.slice(2);
@@ -1982,20 +2246,10 @@ async function main() {
     });
     const client = new AlvaClient({
       apiKey: config.apiKey,
-      baseUrl: config.baseUrl
+      baseUrl: config.baseUrl,
+      arraysBaseUrl: config.arraysBaseUrl
     });
-    const cleanArgs = [];
-    for (let i = 0; i < rawArgs.length; i++) {
-      const a = rawArgs[i];
-      if (a === "--api-key" || a === "--base-url" || a === "--profile") {
-        i++;
-        continue;
-      }
-      if (a.startsWith("--api-key=") || a.startsWith("--base-url=") || a.startsWith("--profile=")) {
-        continue;
-      }
-      cleanArgs.push(a);
-    }
+    const cleanArgs = stripGlobalFlags(rawArgs);
     const result = await dispatch(client, cleanArgs, {
       profile: config.profile,
       baseUrl: config.baseUrl,
@@ -2016,6 +2270,10 @@ async function main() {
       process.stdout.write(Buffer.from(result));
       return;
     }
+    if (typeof result === "string") {
+      process.stdout.write(result);
+      return;
+    }
     if (result !== void 0) {
       process.stdout.write(JSON.stringify(result, null, 2) + "\n");
     }
@@ -2053,6 +2311,7 @@ export {
   CLI_VERSION,
   dispatch,
   handleConfigure,
-  isVersionOlderThan
+  isVersionOlderThan,
+  stripGlobalFlags
 };
 //# sourceMappingURL=cli.js.map