@getxflow/cli 0.12.1 → 0.14.0

package/dist/bin.js

@@ -133,11 +133,15 @@ async function run(args) {
                 await (0, connections_1.connectionsUnlink)(rest);
                 return;
             }
+            if (second === 'call') {
+                await (0, connections_1.connectionsCall)(rest);
+                return;
+            }
             if (second === undefined || second === 'list') {
                 await (0, connections_1.connectionsList)(rest);
                 return;
             }
-            throw new errors_1.CliError(`Unknown command: connections ${second}`, 'Available: list, link and unlink');
+            throw new errors_1.CliError(`Unknown command: connections ${second}`, 'Available: list, link, unlink and call');
         case 'schedules':
             if (second === 'set') {
                 await (0, schedules_1.schedulesSet)(rest);

package/dist/commands/connections.js

@@ -3,10 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.connectionsList = connectionsList;
 exports.connectionsLink = connectionsLink;
 exports.connectionsUnlink = connectionsUnlink;
+exports.connectionsCall = connectionsCall;
 const api_1 = require("../api");
 const args_1 = require("../args");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
+const json_arg_1 = require("../json-arg");
 const session_1 = require("../session");
 const ui_1 = require("../ui");
 const env_1 = require("./env");
@@ -135,3 +137,139 @@ async function connectionsUnlink(args) {
     (0, ui_1.ok)(`${(0, ui_1.bold)(row.label)} unlinked, ${result.alias} is gone`);
     (0, ui_1.note)((0, ui_1.dim)('  Functions already deployed keep the values until their next deploy'));
 }
+/** Budget for the shown body. Enough to read the shape of an answer, cheap in context. */
+const SHOWN_CHARS = 8000;
+/**
+ * Head of the body, cut on a line boundary so JSON is never sliced mid-structure. Only the
+ * head is kept: a stitched head and tail would read as one answer and invite conclusions the
+ * data does not support.
+ */
+function head(text) {
+    if (text.length <= SHOWN_CHARS)
+        return { text, cut: false };
+    const kept = [];
+    let used = 0;
+    for (const line of text.split('\n')) {
+        if (used + line.length + 1 > SHOWN_CHARS)
+            break;
+        kept.push(line);
+        used += line.length + 1;
+    }
+    // One minified line longer than the whole budget: cut it by characters, there is no
+    // boundary to respect.
+    if (kept.length === 0)
+        return { text: text.slice(0, SHOWN_CHARS), cut: true };
+    return { text: kept.join('\n'), cut: true };
+}
+/**
+ * Response headers worth a line each: rate limits, the type, and where a redirect points.
+ * A CDN adds two dozen more, and on every call that is noise.
+ *
+ * Request headers are not filtered: there are a few, they are yours, and seeing them is how
+ * a `{NAME}` the connection does not have shows itself.
+ */
+function shownHeaders(headers) {
+    const wanted = (name) => name === 'content-type' || name === 'retry-after' || name === 'location' || name.startsWith('x-ratelimit');
+    return Object.entries(headers)
+        .filter(([name]) => wanted(name.toLowerCase()))
+        .map(([name, value]) => `${name}: ${value}`);
+}
+function allHeaders(headers) {
+    return Object.entries(headers).map(([name, value]) => `${name}: ${value}`);
+}
+/** Headers typed as JSON. Values may carry {NAME} placeholders, the platform fills those in. */
+function headerArg(args) {
+    const raw = (0, args_1.flagString)(args, 'header');
+    if (raw === undefined)
+        return undefined;
+    const problem = (0, json_arg_1.jsonProblem)(raw);
+    if (problem)
+        throw new errors_1.CliError(`--header is not valid JSON: ${raw}`, (0, json_arg_1.jsonHint)('header', raw));
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new errors_1.CliError('--header takes an object', 'For example: --header \'{"Client-Id":"{CLIENT_ID}"}\'');
+    }
+    const headers = {};
+    for (const [name, value] of Object.entries(parsed)) {
+        if (typeof value !== 'string') {
+            throw new errors_1.CliError(`The value of ${name} has to be a string`, 'Header values are text');
+        }
+        headers[name] = value;
+    }
+    return headers;
+}
+/** Is the body meant to be JSON? A form content-type says it is not, and then it goes as typed. */
+function looksJson(headers) {
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (name.toLowerCase() === 'content-type')
+            return /json/i.test(value);
+    }
+    return true;
+}
+/**
+ * One-off call to the API behind a connected account, with the platform attaching the
+ * credentials. For looking at what an API returns without deploying a function for it.
+ */
+async function connectionsCall(args) {
+    const connection = args.words[1];
+    const path = args.words[2];
+    if (!connection) {
+        throw new errors_1.CliError('A connection is required', 'Its alias in this project, or its name from the first column of xflow connections');
+    }
+    if (!path) {
+        throw new errors_1.CliError('A path is required', 'For example: xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01');
+    }
+    const headers = headerArg(args);
+    const body = (0, json_arg_1.bodyArg)(args, 'data');
+    // Judged before anything goes over the network, the same as in functions invoke: a broken
+    // body is the caller's own line. A form body is not judged at all, it is text by design.
+    if (body && looksJson(headers)) {
+        const problem = (0, json_arg_1.jsonProblem)(body.text);
+        if (problem) {
+            throw body.fromFile
+                ? new errors_1.CliError(`${body.fromFile} is not valid JSON: ${problem}`, 'The file has to hold one JSON value')
+                : new errors_1.CliError(`--data is not valid JSON: ${body.text}`, (0, json_arg_1.jsonHint)('data', body.text));
+        }
+    }
+    const { projectId, client } = await (0, session_1.projectTarget)(args);
+    const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/connections/call`, {
+        method: 'POST',
+        body: {
+            connection,
+            path,
+            method: (0, args_1.flagString)(args, 'method') ?? (body ? 'POST' : 'GET'),
+            ...(body ? { body: body.text } : {}),
+            ...(headers ? { headers } : {}),
+        },
+        // Past the platform's own cap on the call, so a slow API reads as a slow API and not as
+        // an unreachable platform.
+        timeoutMs: 60_000,
+    });
+    if ((0, args_1.flagBool)(args, 'json')) {
+        (0, ui_1.out)(JSON.stringify(data, null, 2));
+        return;
+    }
+    const { request, response } = data;
+    // Named the account only when it was not called by its alias: with several accounts of one
+    // service under the same name, the alias is the only thing the caller already knew.
+    if (!data.alias)
+        (0, ui_1.note)((0, ui_1.dim)(`  ${data.label} (${data.connection_id}), not linked to this project`));
+    (0, ui_1.note)((0, ui_1.dim)(`  ${request.method} ${request.url}`));
+    for (const line of allHeaders(request.headers))
+        (0, ui_1.note)((0, ui_1.dim)(`  ${line}`));
+    const size = response.truncated ? `at least ${(0, ui_1.formatBytes)(response.bytes)}` : (0, ui_1.formatBytes)(response.bytes);
+    (0, ui_1.note)((0, ui_1.dim)(`  ${response.status} in ${data.elapsed_ms} ms, ${size}`));
+    for (const line of shownHeaders(response.headers))
+        (0, ui_1.note)((0, ui_1.dim)(`  ${line}`));
+    const text = typeof response.body === 'string' ? response.body : JSON.stringify(response.body, null, 2);
+    const shown = head(text);
+    if (shown.text)
+        (0, ui_1.out)(shown.text);
+    if (shown.cut || response.truncated) {
+        (0, ui_1.note)((0, ui_1.dim)('  This is the head of the answer, not all of it. Narrow the request with the API own ' +
+            'parameters (a limit, a shorter period), or process the whole set in a cloud function'));
+    }
+    if (!response.ok) {
+        throw new errors_1.CliError(`The API answered ${response.status}`, 'The answer above is theirs, not the platform own');
+    }
+}

package/dist/flags.js

@@ -61,6 +61,7 @@ exports.KNOWN = {
     'connections list': ['project'],
     'connections link': ['as', 'project'],
     'connections unlink': ['force'],
+    'connections call': ['method', 'data', 'data-file', 'header', 'json', 'project'],
     schedules: ['project'],
     'schedules list': ['project'],
     'schedules set': ['payload', 'payload-file', 'project'],

package/dist/help.js

@@ -367,6 +367,8 @@ the platform into the function.
   xflow connections link <name> --as ALIAS
                                    hand its credentials to the functions
   xflow connections unlink <ALIAS> take them away again
+  xflow connections call <name> <path>
+                                   ask that API something, once, without deploying
 
 Every row says whether the connection is linked to this project (its alias) and what
 state the access is in. ${(0, ui_1.bold)('available, not linked')} is the useful one: the account
@@ -394,7 +396,46 @@ not to look for another route. Either way only the accounts granted to you perso
 be linked at all: that rule holds whatever the key is allowed to do.
 
 Connecting a new account and switching one off stay with a person, in the platform
-interface. There is no command for either.`,
+interface. There is no command for either.
+
+${(0, ui_1.bold)('call')} answers the question an API only answers by being asked: what does this
+endpoint actually return, and is the field you need in it. The platform attaches the
+credentials of the connected account and makes the request itself, so nothing has to be
+deployed to find out, and the key never reaches you.
+
+  xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01
+  xflow connections call AMO /api/v4/leads --method POST --data '{"name":"Test"}'
+  xflow connections call OZON /v1/product/list --method POST --data '{}' \\
+      --header '{"Client-Id":"{CLIENT_ID}"}'
+
+The path is written after the address of the connector, query string and all, or given in
+full as ${(0, ui_1.bold)('https://...')}. Only the hosts of that connector are reachable, and a
+refusal lists them. ${(0, ui_1.bold)('--method')} defaults to GET, or to POST when there is a body.
+
+${(0, ui_1.bold)('{NAME}')} in the path or in a header value is filled in by the platform from the
+fields of the connection. That is how the two-header APIs are called: Ozon wants
+${(0, ui_1.bold)('Client-Id')} beside its key, Yandex Direct wants ${(0, ui_1.bold)('Client-Login')} for an
+agency account, and you never see those values. The names are the ones ${(0, ui_1.bold)('xflow env')}
+shows without the alias in front: ${(0, ui_1.bold)('OZON_CLIENT_ID')} is written ${(0, ui_1.bold)('{CLIENT_ID}')}.
+A name the connection does not have is left in the text as you typed it, so a typo shows up
+in the printed request instead of failing somewhere far away.
+
+The answer is printed head first, at most a few kilobytes, and it says so when there is
+more. Ask for the shape, not the volume: one day and ${(0, ui_1.bold)('limit=1')} tells you what the
+fields are called, while the whole dataset belongs in a cloud function. ${(0, ui_1.bold)('--json')}
+prints the envelope for a pipe: ${(0, ui_1.bold)("--json | jq '.response.body | keys'")} gives the
+field names without the body ever entering your context.
+
+An account linked to this project is called by its alias. One that is only available is
+called by its name, and no linking is needed: what the command asks is that you could have
+linked it yourself, which needs the ${(0, ui_1.bold)('connections:link')} right and the account being
+granted to you personally. Either way nothing widens: linked credentials already reach the
+functions of this project, and an account you may link you may also read by deploying a
+function into it. An account granted to somebody else stays out of reach, and the refusal
+says which of the two is missing, the right or the grant.
+
+The call goes out for real: ${(0, ui_1.bold)('POST')} and ${(0, ui_1.bold)('DELETE')} change things in
+somebody's live account, and no flag will undo that.`,
     schedules: `${(0, ui_1.bold)('xflow schedules')}: running functions on a timer
 
 A schedule is a Yandex timer trigger: it calls the function itself, with no

package/dist/json-arg.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonProblem = jsonProblem;
 exports.jsonHint = jsonHint;
+exports.bodyArg = bodyArg;
 exports.jsonArg = jsonArg;
 const node_fs_1 = require("node:fs");
 const args_1 = require("./args");
@@ -39,8 +40,13 @@ function jsonHint(flag, raw) {
     }
     return `A single JSON value is expected, or keep the body in a file: ${file}`;
 }
-/** The body from --<flag> or --<flag>-file, already known to be JSON. */
-function jsonArg(args, flag) {
+/**
+ * The body from --<flag> or --<flag>-file, whatever it is.
+ *
+ * Not every body is JSON: a connector call carrying a form body sends the text as typed, and
+ * judging it as JSON there would refuse a correct request.
+ */
+function bodyArg(args, flag) {
     const fileFlag = `${flag}-file`;
     const inline = args.flags[flag];
     const path = (0, args_1.flagString)(args, fileFlag);
@@ -49,21 +55,25 @@ function jsonArg(args, flag) {
     }
     if (path !== undefined) {
         if (!(0, node_fs_1.existsSync)(path)) {
-            throw new errors_1.CliError(`No file ${path}`, `--${fileFlag} takes the path to a file with one JSON value`);
+            throw new errors_1.CliError(`No file ${path}`, `--${fileFlag} takes the path to a file with the body`);
         }
-        const text = (0, node_fs_1.readFileSync)(path, 'utf-8').trim();
-        const problem = jsonProblem(text);
-        if (problem)
-            throw new errors_1.CliError(`${path} is not valid JSON: ${problem}`, 'The file has to hold one JSON value');
-        return text;
+        return { text: (0, node_fs_1.readFileSync)(path, 'utf-8').trim(), fromFile: path };
     }
     if (inline === undefined)
         return undefined;
     if (inline === true)
         throw new errors_1.CliError(`--${flag} needs a value`, `For example: --${flag} '{"mode":"full"}'`);
-    const raw = String(inline).trim();
-    const problem = jsonProblem(raw);
-    if (problem)
-        throw new errors_1.CliError(`--${flag} is not valid JSON: ${raw}`, jsonHint(flag, raw));
-    return raw;
+    return { text: String(inline).trim(), fromFile: null };
+}
+/** The body from --<flag> or --<flag>-file, already known to be JSON. */
+function jsonArg(args, flag) {
+    const body = bodyArg(args, flag);
+    if (body === undefined)
+        return undefined;
+    const problem = jsonProblem(body.text);
+    if (!problem)
+        return body.text;
+    throw body.fromFile
+        ? new errors_1.CliError(`${body.fromFile} is not valid JSON: ${problem}`, 'The file has to hold one JSON value')
+        : new errors_1.CliError(`--${flag} is not valid JSON: ${body.text}`, jsonHint(flag, body.text));
 }

package/dist/version.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_URL = exports.CLI_VERSION = void 0;
 /** Keep in sync with cli/package.json. */
-exports.CLI_VERSION = '0.12.1';
+exports.CLI_VERSION = '0.14.0';
 /** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getxflow/cli",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -24,7 +24,7 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.12.1. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.14.0. They travel inside the package, so the copy
 you are reading can be older than the CLI answering your commands, and nothing about that
 is visible in the text itself.
 
@@ -364,10 +364,46 @@ naming rules and the flags. Unlink refuses while a function still reads one of t
 variables and names those functions, so read that list before reaching for `--force`.
 
 Linking needs the `connections:link` right on the key, and only accounts granted to the
-owner of the key personally can be linked at all. If the right was taken away, say so and
+owner of the key personally can be linked at all; the same right covers calling an unlinked
+account. If the right was taken away, say so and
 ask the person to turn it back on in the platform settings under Developers: a key cannot
 grant it to itself. Connecting a new account and switching one off stay with a person too.
 
+### Asking an API what it returns
+
+Before writing a function against an unfamiliar API, find out what it actually answers:
+
+```
+xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01
+xflow connections call "Яндекс Метрика" /management/v1/counters
+xflow connections call OZON /v1/product/list --method POST --data '{}' \
+    --header '{"Client-Id":"{CLIENT_ID}"}'
+```
+
+The platform attaches the credentials and makes the request itself, so no deploy is needed and
+the key never reaches you. A linked account is called by its alias, an `available, not linked`
+one by its name: **linking first is not needed to look**, so do not ask a person about that.
+
+**Calling is looking, not wiring**: no variable reaches the functions because you called
+something. To use the account in code, link it and deploy.
+
+Two refusals do need a person, and different ones: `connections:link` right — the owner of the
+key grants it under Developers; `not granted to you` — ask whoever connected the account.
+
+`{NAME}` in the path or in a header value is filled in from the fields of the connection: the
+names are what `xflow env` shows without the alias in front, so `OZON_CLIENT_ID` is written
+`{CLIENT_ID}`. That is how APIs wanting a second header are called, and you never see the
+value. Only the hosts of that connector are reachable and a refusal lists them.
+
+**Ask for the shape, not the volume.** One day and `limit=1` is enough to learn what the
+fields are called; the answer is printed head first and says when there is more. The whole
+dataset belongs in a cloud function, which is where you were going anyway. `--json | jq
+'.response.body | keys'` gives the field names without the body entering your context at all.
+
+The call goes out for real, against a live account: `POST` and `DELETE` change things there,
+and nothing undoes that. Read the method of the endpoint before calling it, and ask the
+person first when the endpoint is not clearly a read.
+
 ## Schedules
 
 `xflow schedules set report "0 3 ? * * *"` runs a function daily at 03:00. Six fields, UTC,