@getxflow/cli 0.13.0 → 0.14.1

package/dist/api.js

@@ -12,21 +12,20 @@ class ApiError extends Error {
     code;
     status;
     hint;
-    /** Check violations, e.g. why a build was rejected. */
     issues;
-    /** Set when a plan limit was hit. */
     limit;
-    /** Cloud functions a build would delete, with code `confirm_required`. */
     removing;
-    constructor(message, code, status, hint, issues, limit, removing) {
+    request;
+    constructor(message, code, status, hint, details = {}) {
         super(message);
         this.name = 'ApiError';
         this.code = code;
         this.status = status;
         this.hint = hint;
-        this.issues = issues;
-        this.limit = limit;
-        this.removing = removing;
+        this.issues = details.issues;
+        this.limit = details.limit;
+        this.removing = details.removing;
+        this.request = details.request;
     }
 }
 exports.ApiError = ApiError;
@@ -127,7 +126,7 @@ async function readError(response, client) {
     const text = await response.text().catch(() => '');
     try {
         const parsed = JSON.parse(text);
-        return new ApiError(parsed.error || `Request rejected (${response.status})`, parsed.code || 'unknown', response.status, parsed.hint, parsed.issues, parsed.limit, parsed.removing);
+        return new ApiError(parsed.error || `Request rejected (${response.status})`, parsed.code || 'unknown', response.status, parsed.hint, parsed);
     }
     catch {
         return notAnAnswer(response.status, client.apiUrl, text);

package/dist/commands/connections.js

@@ -164,9 +164,6 @@ function head(text) {
 /**
  * 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');
@@ -174,8 +171,18 @@ function shownHeaders(headers) {
         .filter(([name]) => wanted(name.toLowerCase()))
         .map(([name, value]) => `${name}: ${value}`);
 }
-function allHeaders(headers) {
-    return Object.entries(headers).map(([name, value]) => `${name}: ${value}`);
+/**
+ * The request as it went out, printed on the answer and on a refusal alike. On a refusal it
+ * is the whole point: the host of a connector comes from the connection, not from what was
+ * typed, so "check the address" is unfollowable while the address is nowhere on screen.
+ *
+ * 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 showRequest(request) {
+    (0, ui_1.note)((0, ui_1.dim)(`  ${request.method} ${request.url}`));
+    for (const [name, value] of Object.entries(request.headers))
+        (0, ui_1.note)((0, ui_1.dim)(`  ${name}: ${value}`));
 }
 /** Headers typed as JSON. Values may carry {NAME} placeholders, the platform fills those in. */
 function headerArg(args) {
@@ -211,10 +218,10 @@ function looksJson(headers) {
  * credentials. For looking at what an API returns without deploying a function for it.
  */
 async function connectionsCall(args) {
-    const alias = args.words[1];
+    const connection = args.words[1];
     const path = args.words[2];
-    if (!alias) {
-        throw new errors_1.CliError('A connection is required', 'Its alias in this project: xflow connections');
+    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');
@@ -223,36 +230,42 @@ async function connectionsCall(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));
-        }
-    }
+    if (body && looksJson(headers))
+        (0, json_arg_1.assertJson)('data', body);
     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: alias,
-            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,
-    });
+    let data;
+    try {
+        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,
+        });
+    }
+    catch (e) {
+        // Before the refusal itself, in the order of the answer: what went out, then what came of
+        // it. Only the other side's refusals carry it, the rest never assembled an address.
+        if (e instanceof api_1.ApiError && e.request)
+            showRequest(e.request);
+        throw e;
+    }
     if ((0, args_1.flagBool)(args, 'json')) {
         (0, ui_1.out)(JSON.stringify(data, null, 2));
         return;
     }
     const { request, response } = data;
-    (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}`));
+    // 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`));
+    showRequest(request);
     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))

package/dist/help.js

@@ -254,7 +254,7 @@ About destructive ones. The platform keeps no database history and makes no back
 so ${(0, ui_1.bold)('DROP TABLE')}, ${(0, ui_1.bold)('DROP COLUMN')}, ${(0, ui_1.bold)('TRUNCATE')} and ${(0, ui_1.bold)('DELETE FROM')} without a
 condition need two things at once: this flag, and the right to destroy data on the
 access key. That right is off by default, and only its owner turns it on, in the
-platform settings under Developers: a flag is something an agent adds by itself, a
+platform settings, where the key permissions live: a flag is something an agent adds by itself, a
 right is not. With both in place, the contents of the affected tables are dumped and
 kept for 7 days: that is a "caught it right away" safety net, not a backup.
 ${(0, ui_1.bold)('DROP DATABASE')} is never allowed, because the database is shared across the
@@ -321,8 +321,8 @@ Dot entries and symbolic links are skipped, and ${(0, ui_1.bold)('.xflowignore')
 those are the rules for the sources, and a media folder is exactly what one is
 asked to put there so it stays out of the archive.
 
-${(0, ui_1.bold)('rm')} needs a right of its own (${(0, ui_1.bold)('Delete files')} in the Developers section of the
-platform), off by default. The reason is the neighbourhood: whatever the users of
+${(0, ui_1.bold)('rm')} needs a right of its own (${(0, ui_1.bold)('Delete files')}, where the key permissions live in
+the platform settings), off by default. The reason is the neighbourhood: whatever the users of
 the application uploaded lives in the same folders, and there is no undo. A folder
 first answers with the number of files it holds and deletes only on ${(0, ui_1.bold)('--yes')}.
 
@@ -367,7 +367,7 @@ 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 <ALIAS> <path>
+  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
@@ -390,7 +390,7 @@ run ${(0, ui_1.bold)('xflow deploy')}. A token close to expiry is renewed by any
 a revoked one is not renewed by anything until a human reconnects the account.
 
 Linking needs a right on the key, ${(0, ui_1.bold)('connections:link')}. Keys are issued with it,
-and a person can take it away in the platform settings under Developers; a key cannot give
+and a person can take it away in the platform settings, where the key permissions live; a key cannot give
 it back to itself. Losing it is what the refusal says, and the answer is to ask a person,
 not to look for another route. Either way only the accounts granted to you personally can
 be linked at all: that rule holds whatever the key is allowed to do.
@@ -426,11 +426,16 @@ fields are called, while the whole dataset belongs in a cloud function. ${(0, ui
 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.
 
-Only an account already linked to this project can be called, because its credentials
-already reach the functions of that project: the command saves a deploy, it does not widen
-what you may touch. An account that is merely available has to be linked first, and that is
-a separate right and a personal grant. The call also 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.`,
+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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonProblem = jsonProblem;
 exports.jsonHint = jsonHint;
 exports.bodyArg = bodyArg;
+exports.assertJson = assertJson;
 exports.jsonArg = jsonArg;
 const node_fs_1 = require("node:fs");
 const args_1 = require("./args");
@@ -30,15 +31,19 @@ function jsonProblem(raw) {
         return e instanceof Error ? e.message : String(e);
     }
 }
-/** Where to look, and on a stripped value the shell is the first suspect. */
+/**
+ * Where to look, and on a stripped value the shell is the first suspect.
+ *
+ * No file is offered here: not every JSON flag has that twin, and --header used to be sent
+ * to --header-file, which the flag check refuses one line later. A hint has to survive being
+ * followed, so the offer lives in assertJson, the one path that reads a file.
+ */
 function jsonHint(flag, raw) {
-    const file = `--${flag}-file body.json`;
     if (quotesStripped(raw.trim())) {
         return (`Not one double quote survived: the shell removed them, PowerShell does this to ` +
-            `native calls. Escape them: --${flag} '{\\"key\\":\\"value\\"}', or keep the body ` +
-            `in a file: ${file}`);
+            `native calls. Escape them: --${flag} '{\\"key\\":\\"value\\"}'`);
     }
-    return `A single JSON value is expected, or keep the body in a file: ${file}`;
+    return 'A single JSON value is expected';
 }
 /**
  * The body from --<flag> or --<flag>-file, whatever it is.
@@ -65,15 +70,23 @@ function bodyArg(args, flag) {
         throw new errors_1.CliError(`--${flag} needs a value`, `For example: --${flag} '{"mode":"full"}'`);
     return { text: String(inline).trim(), fromFile: null };
 }
+/**
+ * Refuse a body that is not JSON. Takes what bodyArg returned, and only this path names
+ * --<flag>-file: a flag read through bodyArg has that twin by construction.
+ */
+function assertJson(flag, body) {
+    const problem = jsonProblem(body.text);
+    if (!problem)
+        return;
+    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)}, or keep the body in a file: --${flag}-file body.json`);
+}
 /** 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));
+    assertJson(flag, body);
+    return 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.13.0';
+exports.CLI_VERSION = '0.14.1';
 /** 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.13.0",
+  "version": "0.14.1",
   "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.13.0. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.14.1. 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,8 +364,9 @@ 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
-ask the person to turn it back on in the platform settings under Developers: a key cannot
+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 where the key permissions live in the platform settings: 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
@@ -374,15 +375,20 @@ Before writing a function against an unfamiliar API, find out what it actually a
 
 ```
 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. Only an account already linked to this project can be called:
-its credentials already reach that project's functions, so this saves a deploy rather than
-widening what you may touch. An account that is only `available, not linked` has to be linked
-first, and that stays a decision for a person.
+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 where the key permissions live; `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
@@ -442,8 +448,8 @@ fills those in itself, and your value under one of them would shadow the real on
 The platform keeps no database history and no backups, so anything that destroys data
 (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) needs two
 things at once: the `--allow-destructive` flag, and the right to destroy data on the key.
-That right is off by default and only its owner turns it on, under Developers in the
-platform settings. When the refusal is about the right rather than the flag, adding the flag
+That right is off by default and only its owner turns it on, where the key permissions live in
+the platform settings. When the refusal is about the right rather than the flag, adding the flag
 changes nothing: say what needs deleting and why, and let the person decide. With both in
 place the affected tables are dumped first and kept for 7 days. Check with `--dry-run` first.
 
@@ -482,8 +488,8 @@ whose size differs. An address belongs to the record rather than to the bytes, s
 replacement keeps it and the links in your code and tables keep working. Put those addresses
 into the code or into a table: there is no command that fetches files back to a machine.
 
-Deleting needs a right of its own, off by default (**Delete files** in the Developers
-section of the platform), so `xflow storage rm` may answer that the key was not granted it.
+Deleting needs a right of its own, off by default (**Delete files**, where the key permissions
+live in the platform settings), so `xflow storage rm` may answer that the key was not granted it.
 Ask the person to switch it on, and do not look for a way around: whatever the users of the
 application uploaded lives in the same folders, and there is no undo. A folder first tells
 you how many files it holds and deletes them only with `--yes`.