@getxflow/cli 0.6.4 → 0.6.6

package/dist/api.js

@@ -98,26 +98,50 @@ async function send(client, path, options = {}) {
     assertProtocol(response);
     return response;
 }
-async function readError(response) {
+/**
+ * The body is not an answer of the API: every one of those is JSON with content.
+ * A page in its place, or nothing at all, means the request never reached a
+ * route, so we say that instead of quoting what came back.
+ *
+ * Markup never goes into the hint. The reader is an agent, and 200 characters of
+ * HTML read like a bug in its own code rather than like a platform that has not
+ * deployed this endpoint yet. An empty body is worse still: it used to leave no
+ * hint at all.
+ *
+ * Plain text is kept: some proxies say something useful in one line.
+ */
+function notAnAnswer(status, apiUrl, body) {
+    const text = body.trim();
+    if (text.length > 0 && !text.startsWith('<')) {
+        return new ApiError(`Request rejected (${status})`, 'unknown', status, text.slice(0, 200));
+    }
+    // 404 is a missing route, 405 a route without this method. Both mean the same
+    // thing to the caller: this platform does not serve the endpoint yet.
+    if (status === 404 || status === 405) {
+        return new ApiError(`The platform does not serve that endpoint (${status})`, 'not_deployed', status, `This CLI is ${version_1.CLI_VERSION} and ${apiUrl} is older than it. Wait for the platform to deploy, or check XFLOW_API_URL`);
+    }
+    return new ApiError(`The platform is not answering (${status})`, 'unavailable', status, `Something on the way to ${apiUrl} answered with a page instead of an answer. Retry in a minute`);
+}
+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);
     }
     catch {
-        return new ApiError(`Request rejected (${response.status})`, 'unknown', response.status, text.slice(0, 200) || undefined);
+        return notAnAnswer(response.status, client.apiUrl, text);
     }
 }
 async function apiJson(client, path, options = {}) {
     const response = await send(client, path, options);
     if (!response.ok)
-        throw await readError(response);
+        throw await readError(response, client);
     return (await response.json());
 }
 async function apiBinary(client, path) {
     const response = await send(client, path, { timeoutMs: TRANSFER_TIMEOUT_MS });
     if (!response.ok)
-        throw await readError(response);
+        throw await readError(response, client);
     return Buffer.from(await response.arrayBuffer());
 }
 async function apiUpload(client, path, body, headers = {}) {

package/dist/bin.js

@@ -13,6 +13,7 @@ const zip_1 = require("./zip");
 const version_1 = require("./version");
 const auth_1 = require("./commands/auth");
 const projects_1 = require("./commands/projects");
+const connections_1 = require("./commands/connections");
 const db_1 = require("./commands/db");
 const env_1 = require("./commands/env");
 const functions_1 = require("./commands/functions");
@@ -105,6 +106,20 @@ async function run(args) {
                 return;
             }
             throw new errors_1.CliError(`Unknown command: env ${second}`, 'Available: list, check, set and rm');
+        case 'connections':
+            if (second === 'link') {
+                await (0, connections_1.connectionsLink)(rest);
+                return;
+            }
+            if (second === 'unlink') {
+                await (0, connections_1.connectionsUnlink)(rest);
+                return;
+            }
+            if (second === undefined || second === 'list') {
+                await (0, connections_1.connectionsList)();
+                return;
+            }
+            throw new errors_1.CliError(`Unknown command: connections ${second}`, 'Available: list, link and unlink');
         case 'schedules':
             if (second === 'set') {
                 await (0, schedules_1.schedulesSet)(rest);

package/dist/commands/connections.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectionsList = connectionsList;
+exports.connectionsLink = connectionsLink;
+exports.connectionsUnlink = connectionsUnlink;
+const api_1 = require("../api");
+const args_1 = require("../args");
+const config_1 = require("../config");
+const errors_1 = require("../errors");
+const session_1 = require("../session");
+const ui_1 = require("../ui");
+const env_1 = require("./env");
+// An expiring token is renewed by any build, a revoked one is not renewed by
+// anything until a human reconnects the account. Telling them apart saves a
+// pointless rebuild, so every case gets its own line.
+function state(row) {
+    if (!row.alias)
+        return 'available, not linked';
+    if (row.disabled)
+        return 'linked but switched off, the functions get nothing';
+    switch (row.health) {
+        case 'expiring':
+            return `linked, token expires in ${row.days_left} days, any build renews it`;
+        case 'expired':
+            return 'linked, access has expired, reconnect the account';
+        case 'revoked':
+            return 'linked, access was revoked by the provider, a rebuild will not help';
+        case 'ok':
+            return row.days_left === null ? 'linked' : `linked, token valid ${row.days_left} days`;
+        default:
+            return 'linked';
+    }
+}
+function endpoint(projectId) {
+    return `/api/v1/projects/${projectId}/connections`;
+}
+/**
+ * Which connection the argument means. Identifiers are what the platform knows,
+ * names are what the list shows and what a human said out loud; both are
+ * accepted, so nobody has to copy a UUID from somewhere the command never
+ * printed it. Names repeat across accounts of the same service, so an ambiguous
+ * one is refused with the identifiers rather than resolved by luck.
+ */
+function resolve(connections, target) {
+    const byId = connections.find((row) => row.id === target);
+    if (byId)
+        return byId;
+    const wanted = target.toLowerCase();
+    const named = connections.filter((row) => row.label.toLowerCase() === wanted);
+    if (named.length === 1)
+        return named[0];
+    if (named.length > 1) {
+        (0, ui_1.fail)(`The organization has ${named.length} connections named ${target}:`);
+        (0, ui_1.table)(named.map((row) => [row.id, row.connector_name ?? row.connector_key ?? '-']));
+        throw new errors_1.CliError('The name is ambiguous', 'Repeat with one of the identifiers above');
+    }
+    throw new errors_1.CliError(`No connection ${target}`, 'What this project can use: xflow connections');
+}
+async function connectionsList() {
+    const { config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const data = await (0, api_1.apiJson)(client, endpoint(config.projectId));
+    if (data.connections.length === 0) {
+        (0, ui_1.note)('No connections you can use in this organization');
+        (0, ui_1.note)((0, ui_1.dim)('  Somebody connects an account first: platform settings, Connectors'));
+        return;
+    }
+    (0, ui_1.table)(data.connections.map((row) => [
+        row.label,
+        row.connector_key ?? '-',
+        row.alias ?? '-',
+        state(row),
+    ]));
+    const variables = data.connections.flatMap((row) => row.env);
+    if (variables.length > 0) {
+        (0, ui_1.note)((0, ui_1.dim)(`  The functions get: ${variables.join(', ')}`));
+        (0, ui_1.note)((0, ui_1.dim)('  A change reaches a function on its next deploy: xflow deploy'));
+    }
+    if (data.connections.some((row) => !row.alias)) {
+        (0, ui_1.note)((0, ui_1.dim)('  To link one: xflow connections link <name> --as ALIAS'));
+    }
+}
+async function connectionsLink(args) {
+    const target = args.words[1];
+    if (!target) {
+        throw new errors_1.CliError('A connection is required', 'Its name is the first column of xflow connections');
+    }
+    // The alias is asked for, never guessed: it becomes the prefix of the
+    // variables, it ends up in the code of the functions, and renaming it later
+    // means editing that code.
+    const alias = (0, args_1.flagString)(args, 'as');
+    if (!alias) {
+        throw new errors_1.CliError('An alias is required', 'For example: xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA');
+    }
+    const { config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const data = await (0, api_1.apiJson)(client, endpoint(config.projectId));
+    const connectionId = resolve(data.connections, target).id;
+    const result = await (0, api_1.apiJson)(client, endpoint(config.projectId), { method: 'POST', body: { connection_id: connectionId, alias } });
+    (0, ui_1.ok)(`${(0, ui_1.bold)(result.label)} linked as ${result.alias}`);
+    if (result.env.length > 0)
+        (0, ui_1.note)((0, ui_1.dim)(`  The functions will get: ${result.env.join(', ')}`));
+    (0, ui_1.note)((0, ui_1.dim)('  The values arrive on the next deploy: xflow deploy'));
+}
+async function connectionsUnlink(args) {
+    const target = args.words[1];
+    if (!target) {
+        throw new errors_1.CliError('A connection is required', 'For example: xflow connections unlink YANDEX_METRIKA');
+    }
+    const { root, config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    // The alias is what the code of the functions knows, and it wins: it is the
+    // most precise of the three, since it names the link and not just the account.
+    const data = await (0, api_1.apiJson)(client, endpoint(config.projectId));
+    const byAlias = data.connections.find((item) => item.alias !== null && item.alias === target.toUpperCase());
+    const row = byAlias ?? resolve(data.connections, target);
+    if (!row.alias) {
+        (0, ui_1.note)(`${row.label} is not linked to this project`);
+        return;
+    }
+    // The platform does not see the sources, so this check lives here. Without it
+    // the unlink is silent and the breakage shows up one deploy later.
+    const needed = (0, env_1.referencedByFunctions)(root).needed;
+    const inUse = row.env
+        .map((name) => ({ name, users: needed.get(name) ?? [] }))
+        .filter((entry) => entry.users.length > 0);
+    if (inUse.length > 0 && !(0, args_1.flagBool)(args, 'force')) {
+        (0, ui_1.fail)(`The functions of this project read the variables of ${row.alias}:`);
+        (0, ui_1.table)(inUse.map((entry) => [entry.name, entry.users.join(', ')]));
+        throw new errors_1.CliError('They would lose these variables on the next deploy', 'Repeat with --force if that is intended');
+    }
+    const result = await (0, api_1.apiJson)(client, `${endpoint(config.projectId)}?connection_id=${encodeURIComponent(row.id)}`, { method: 'DELETE' });
+    if (!result.removed) {
+        (0, ui_1.note)(`${row.label} is not linked to this project`);
+        return;
+    }
+    (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'));
+}

package/dist/commands/env.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.referencedByFunctions = referencedByFunctions;
 exports.envList = envList;
 exports.envCheck = envCheck;
 exports.envSet = envSet;

package/dist/help.js

@@ -43,6 +43,11 @@ ${(0, ui_1.bold)('Functions')}
   xflow env [check]               function variables: what is stored, what is missing
   xflow env set NAME=value        store a variable
   xflow env rm NAME               delete a variable
+  xflow connections               connected accounts the project can use, and their variables
+  xflow connections link <name> --as ALIAS
+                                  give the functions the credentials of an account
+  xflow connections unlink <ALIAS> [--force]
+                                  take them away again
 
 ${(0, ui_1.bold)('Database')}
   xflow db status                 which migrations are applied and which are waiting
@@ -166,6 +171,46 @@ The value reaches the function on deploy, not at the moment it is stored: after
 ${(0, ui_1.bold)('env set')} run ${(0, ui_1.bold)('xflow deploy')}. The build ships a function whose code did not
 change but whose variables did, so nothing is left holding an old value. The same after a
 delete: a function already deployed keeps the old value until its next deploy.`,
+    connections: `${(0, ui_1.bold)('xflow connections')}: accounts connected to the organization
+
+Somebody signs in to Yandex Metrika, Bitrix or a mail service once, in the platform,
+and that account becomes a connection of the organization. Linked to a project, it
+hands its credentials to the cloud functions as environment variables. Nobody has to
+paste a token into the repository, and nobody sees the value: it goes straight from
+the platform into the function.
+
+  xflow connections                what this project can use, and what it already uses
+  xflow connections link <name> --as ALIAS
+                                   hand its credentials to the functions
+  xflow connections unlink <ALIAS> take them away again
+
+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
+exists in the organization, but this project gets nothing from it yet: link it.
+
+Both commands take the name of the connection, the first column of the list, and both
+also take its identifier. ${(0, ui_1.bold)('unlink')} takes the alias as well, and prefers it: the
+alias is the name your own code already uses. One organization can hold several accounts
+of the same service under one name; then the command prints their identifiers and asks
+for one of those instead of guessing.
+
+${(0, ui_1.bold)('unlink')} refuses while a function still reads one of the variables and names
+those functions; ${(0, ui_1.bold)('--force')} goes through anyway.
+
+Variables are named after the alias: an OAuth connection called ${(0, ui_1.bold)('YANDEX_METRIKA')}
+gives ${(0, ui_1.bold)('YANDEX_METRIKA_TOKEN')}, a key-based one gives a variable per field. They
+arrive at a function on its next deploy, like every other variable, so after a change
+run ${(0, ui_1.bold)('xflow deploy')}. A token close to expiry is renewed by any build on the way;
+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
+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.
+
+Connecting a new account and switching one off stay with a person, in the platform
+interface. There is no command for either.`,
     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/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.6.4';
+exports.CLI_VERSION = '0.6.6';
 /** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/package.json

@@ -1,23 +1,23 @@
-{
-  "name": "@getxflow/cli",
-  "version": "0.6.4",
-  "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
-  "license": "UNLICENSED",
-  "engines": {
-    "node": ">=20"
-  },
-  "bin": {
-    "xflow": "dist/bin.js"
-  },
-  "files": [
-    "dist",
-    "skills"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@getxflow/cli",
+  "version": "0.6.6",
+  "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "xflow": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/xflow/SKILL.md

@@ -261,6 +261,25 @@ and refuses. If a call to that service starts failing with an authorisation erro
 account was disconnected on the provider's side, which only a human can fix by reconnecting
 it in the platform settings.
 
+`xflow connections` lists those accounts: the ones already linked to this project, with the
+alias and the state of the access, and the ones the organization has but this project does
+not use yet, marked `available, not linked`. Check it before telling anyone a service is
+unavailable: the account you need is often connected already, one link away.
+
+`xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA` is that link, and
+`xflow connections unlink YANDEX_METRIKA` undoes it. Name the connection the way the list
+does, in its first column, or by its identifier; unlink also takes the alias, which your
+own code already knows. If two accounts of the same service share a name, the command
+prints their identifiers instead of guessing. Unlink refuses while a function still reads
+one of the variables and names those functions, so read that list before reaching for
+`--force`.
+
+Linking needs the `connections:link` right, which keys are issued with. If it 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. Only accounts granted to the owner of the key
+personally can be linked at all. Connecting a new account and switching one off stay with a
+person too.
+
 To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily at 03:00).
 Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
 how Yandex wants it. A scheduled run reaches the handler as a POST with no headers.