@wrangled/cli 0.3.43 → 0.3.45

package/dist/api.js

@@ -1,8 +1,8 @@
 import { mkdir, readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { brand, envPrefix } from "./brand.js";
-import { writeFileAtomic } from "./files.js";
+import { RUN_ROOT_ENV, writeFileAtomic } from "./files.js";
 export const exitCodes = { ok: 0, error: 1, usage: 2, auth: 3, interrupted: 130 };
 export class CliError extends Error {
     exitCode;
@@ -30,8 +30,17 @@ export const IMPORT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
 export function credentialsPath(configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config")) {
     return join(configHome, brand.slug, "credentials.json");
 }
-export async function readCredentials() {
-    const path = credentialsPath();
+const CLIENT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+/** The file that names a folder's client; it holds only the name, never a key. */
+export const CLIENT_FILE = `.${brand.slug}-client`;
+export function parseClientName(name) {
+    if (!CLIENT_NAME.test(name)) {
+        throw new CliError(`'${name}' is not a client name: use lowercase letters, digits and dashes, starting with a letter or digit.`, exitCodes.usage);
+    }
+    return name;
+}
+export async function readSavedLogins(configHome) {
+    const path = credentialsPath(configHome);
     let text;
     try {
         text = await readFile(path, "utf8");
@@ -41,38 +50,146 @@ export async function readCredentials() {
             return null;
         throw error;
     }
-    const credentials = parseCredentials(text);
-    if (!credentials)
+    const saved = parseSavedLogins(text);
+    if (!saved)
         throw new UnreadableCredentialsError(path);
-    return credentials;
+    return saved;
 }
-function parseCredentials(text) {
+function parseSavedLogins(text) {
+    let value;
     try {
-        const value = JSON.parse(text);
-        if (typeof value?.apiKey !== "string" || typeof value.apiUrl !== "string")
-            return null;
-        return { apiKey: value.apiKey, apiUrl: value.apiUrl };
+        value = JSON.parse(text);
     }
     catch {
         return null;
     }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const { apiKey, apiUrl, clients } = value;
+    const top = parseLogin({ apiKey, apiUrl });
+    if (top === null && (apiKey !== undefined || apiUrl !== undefined))
+        return null;
+    // No prototype, so a client named like an Object method (`constructor`) finds nothing rather than a function.
+    const named = Object.create(null);
+    if (clients !== undefined) {
+        if (typeof clients !== "object" || clients === null || Array.isArray(clients))
+            return null;
+        for (const [name, entry] of Object.entries(clients)) {
+            const login = parseLogin(entry);
+            if (!CLIENT_NAME.test(name) || login === null)
+                return null;
+            named[name] = login;
+        }
+    }
+    if (top === null && Object.keys(named).length === 0)
+        return null;
+    return { default: top, clients: named };
 }
-export async function writeCredentials(credentials, configHome) {
-    const path = credentialsPath(configHome);
+function parseLogin(value) {
+    const { apiKey, apiUrl } = (value ?? {});
+    return typeof apiKey === "string" && typeof apiUrl === "string" ? { apiKey, apiUrl } : null;
+}
+/** Saves `credentials` as the default login, or as the named client's, keeping every other saved login. */
+export async function writeCredentials(credentials, options = {}) {
+    const path = credentialsPath(options.configHome);
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    await writeFileAtomic(path, `${JSON.stringify(credentials, null, 2)}\n`, 0o600);
+    const saved = (await readSavedLogins(options.configHome).catch(ignoreUnreadable)) ?? { default: null, clients: {} };
+    const next = options.client === undefined ? { ...saved, default: credentials } : { ...saved, clients: { ...saved.clients, [options.client]: credentials } };
+    await writeSavedLogins(path, next);
     return path;
 }
-export async function removeCredentials() {
-    await rm(credentialsPath(), { force: true });
+/** Removes the default login, or the named client's, keeping the rest; the file goes once nothing is left in it. */
+export async function removeCredentials(client) {
+    const path = credentialsPath();
+    const saved = await readSavedLogins().catch(ignoreUnreadable);
+    const clients = { ...saved?.clients };
+    if (client !== undefined)
+        delete clients[client];
+    const next = { default: client === undefined ? null : (saved?.default ?? null), clients };
+    if (next.default === null && Object.keys(clients).length === 0)
+        return rm(path, { force: true });
+    await writeSavedLogins(path, next);
+}
+async function writeSavedLogins(path, saved) {
+    const file = { ...saved.default, ...(Object.keys(saved.clients).length > 0 && { clients: saved.clients }) };
+    await writeFileAtomic(path, `${JSON.stringify(file, null, 2)}\n`, 0o600);
+}
+/** An unreadable file is replaced by the next login, as nothing in it can be used. */
+function ignoreUnreadable(error) {
+    if (error instanceof UnreadableCredentialsError)
+        return null;
+    throw error;
+}
+/** The API key env var beats `--client`, which beats the nearest client file above `cwd`, which beats the default login. */
+export async function chooseClient(clientFlag, cwd = process.cwd()) {
+    const flagged = clientFlag === undefined ? undefined : parseClientName(clientFlag);
+    if (process.env[`${envPrefix}_API_KEY`])
+        return { source: "env" };
+    if (flagged !== undefined)
+        return { source: "flag", client: flagged };
+    // A scheduled hand's run holds only its own default key, and must not be steered by files outside its folder.
+    if (process.env[RUN_ROOT_ENV])
+        return { source: "default" };
+    const found = await findClientFile(cwd);
+    return found ? { source: "folder", ...found } : { source: "default" };
+}
+async function findClientFile(from) {
+    for (let dir = resolve(from);; dir = dirname(dir)) {
+        const path = join(dir, CLIENT_FILE);
+        const text = await readFile(path, "utf8").catch((error) => {
+            if (error.code === "ENOENT" || error.code === "ENOTDIR")
+                return null;
+            throw new CliError(`Could not read the client file at ${path} (${error.code ?? error.message}), so the client to use is unknown.`, exitCodes.usage);
+        });
+        if (text !== null)
+            return { client: parseClientFile(text, path), path };
+        if (dirname(dir) === dir)
+            return null;
+    }
 }
-export async function resolveConnection(apiUrlFlag) {
-    const stored = await readCredentials();
-    const apiKey = process.env[`${envPrefix}_API_KEY`] || stored?.apiKey;
-    if (!apiKey) {
-        throw new CliError(`Not logged in. Run \`${brand.slug} login\` or set ${envPrefix}_API_KEY.`, exitCodes.auth);
+function parseClientFile(text, path) {
+    const malformed = new CliError(`The client file at ${path} is malformed. It should hold {"client": "<name>"}, a lowercase name with letters, digits and dashes.`, exitCodes.usage);
+    let value;
+    try {
+        value = JSON.parse(text);
     }
-    return { apiUrl: resolveApiUrl(apiUrlFlag, stored), apiKey };
+    catch {
+        throw malformed;
+    }
+    const client = value?.client;
+    if (typeof client !== "string" || !CLIENT_NAME.test(client))
+        throw malformed;
+    return client;
+}
+export async function resolveLogin(options) {
+    const choice = await chooseClient(options.client);
+    const saved = await readSavedLogins();
+    if (choice.source === "env") {
+        return { choice, connection: { apiUrl: resolveApiUrl(options.apiUrl, saved?.default ?? null), apiKey: process.env[`${envPrefix}_API_KEY`] } };
+    }
+    if (choice.source === "default") {
+        if (!saved?.default)
+            throw new CliError(`Not logged in. Run \`${brand.slug} login\` or set ${envPrefix}_API_KEY.`, exitCodes.auth);
+        return { choice, connection: { apiUrl: resolveApiUrl(options.apiUrl, saved.default), apiKey: saved.default.apiKey } };
+    }
+    const login = saved?.clients[choice.client];
+    const relogin = `\`${brand.slug} login --client ${choice.client}\``;
+    if (!login) {
+        const why = choice.source === "folder" ? `, named by ${choice.path}` : "";
+        throw new CliError(`No saved key for client ${choice.client}${why}. Run ${relogin}.`, exitCodes.auth);
+    }
+    const apiUrl = resolveApiUrl(options.apiUrl, login);
+    return { choice, connection: { apiUrl, apiKey: login.apiKey, rejected: `The API key for client ${choice.client} was rejected by ${apiUrl}. Run ${relogin} with a valid key.` } };
+}
+export async function resolveConnection(options) {
+    return (await resolveLogin(options)).connection;
+}
+/** The API URL the chosen login points at, for connections that carry another key; a missing or unreadable login is no error. */
+export async function chosenApiUrl(options) {
+    const choice = await chooseClient(options.client);
+    const saved = await readSavedLogins().catch(ignoreUnreadable);
+    const login = choice.source === "flag" || choice.source === "folder" ? saved?.clients[choice.client] : saved?.default;
+    return resolveApiUrl(options.apiUrl, login ?? null);
 }
 export function resolveApiUrl(apiUrlFlag, stored) {
     return (apiUrlFlag || process.env[`${envPrefix}_API_URL`] || stored?.apiUrl || brand.apiUrl).replace(/\/+$/, "");

package/dist/guide.js

@@ -23,8 +23,8 @@ export const guide = `# ${brand.name} CLI
 
 ## Setup
 
-1. Check the login: \`${cli} whoami\`. It prints the workspace name, slug, and id, and whether the key has library access.
-2. If it exits with code 3, you are not logged in. Ask the user to run \`${cli} login\` in their own terminal. It prompts for the key without showing it. Never ask for the key in chat and never put it on a command line, where it lands in shell history and logs. In CI, the key comes from the \`${envPrefix}_API_KEY\` environment variable.
+1. Check the login: \`${cli} whoami\`. It prints the workspace name, slug, and id, whether the key has library access, and which client's key is in use and why.
+2. If it exits with code 3, you are not logged in. Ask the user to run the \`${cli} login\` command the error names (\`${cli} login --client <name>\` for a named client) in their own terminal. It prompts for the key without showing it. Never ask for the key in chat and never put it on a command line, where it lands in shell history and logs. In CI, the key comes from the \`${envPrefix}_API_KEY\` environment variable.
 
 ## Start with the data guide
 
@@ -40,7 +40,7 @@ ${brand.name} does not build pages; it hands whoever builds one what is already
 
 ## Which Facebook ads and pages won: winners and flops
 
-\`${cli} winners\` says which Facebook ads won and which flopped, for the dates asked for and for the 30 days ending on their last day, judged on real sales: each sale goes to the Facebook ad that first brought the buyer in, and payments typed into GoHighLevel by hand never count toward an ad. An ad with no sales that has spent less than twice the account's cost per sale is too new to judge on sales, so it is judged on cost per first lead and listed apart. Each ad says in a sentence why it is on its list. Each currency also says how many of its Facebook sales could be tied to a specific ad (\`adSales\` of \`facebookSales\` in the JSON): a sale whose link names no single ad counts toward Facebook but toward no ad. It judges the landing pages the ads sent people to the same way, and each ad on each page as an ad-and-page pair: a page or pair counts only once the page reader has read the page and it got at least 100 visits in the dates, and pairs are listed only for an ad that sent people to two or more pages, or a page that got people from two or more ads, each naming what the same ad cost on its other pages. \`--week <YYYY-MM-DD>\` picks any day of a Monday-to-Sunday week (default: the latest complete week), \`--days <n>\` the last n complete days ending yesterday, and \`--from <YYYY-MM-DD> --to <YYYY-MM-DD>\` any dates; use one of them, at most 90 days. Check as often as suits the client, daily or every few days: a short window holds few sales, so more ads are judged on first leads, and the report says so. \`--top <n>\` how many ads, pages or pairs each list shows (default 5, at most 20), \`--ad-format image|video|carousel\` ranks only ads with that format tag (run \`${cli} ads tag-formats\` first; the account's cost per sale still counts every ad), and \`--format json\` gives the report as data.
+\`${cli} winners\` says which Facebook ads won and which flopped, for the dates asked for and for the 30 days ending on their last day, judged on the client's goal. Each client has an ordered list of goals, and winners uses the first one whose data is connected: \`sales\` (first-touch sales from every connected payment source: each sale goes to the Facebook ad that first brought the buyer in, and payments typed into GoHighLevel by hand never count toward an ad), \`sales:triple_whale\` (the orders Triple Whale credits to each ad), \`booked_calls\` (calls booked by someone whose first touch was the ad), \`meta_results\` (Facebook's own count of the result types set on the Meta source, such as applications, \`submit_application_website\`) or \`first_leads\`. The default list is Triple Whale's orders, then first-touch sales, then first leads, which is how winners judged before goals could be set. \`${cli} winners goals\` shows the list, whether each goal has data and which one is used now; \`${cli} winners goals set booked_calls first_leads\` sets it, and \`${cli} winners goals reset\` goes back to the default. To judge on Stripe sales, connect Stripe, then put \`sales\` first. The report starts with a sentence saying which goal it judged on, and in the JSON every "sales" field (\`numbers.sales\`, \`costPerSale\`, \`accountCostPerSale\`, \`adSales\`, \`judgedOn: "sales"\`) holds that goal, named in \`goal\`, and every "signups" field the fallback goal, named in \`fallbackGoal\`. An ad with none of the goal that has spent less than twice the account's cost per one is too new to judge on it, so it is judged on the fallback goal, the next connected goal of another kind, and listed apart. Landing pages and ad-and-page pairs are always judged on first-touch sales and first leads. Each ad says in a sentence why it is on its list. Each currency also says how many of its Facebook sales could be tied to a specific ad (\`adSales\` of \`facebookSales\` in the JSON): a sale whose link names no single ad counts toward Facebook but toward no ad. It judges the landing pages the ads sent people to the same way, and each ad on each page as an ad-and-page pair: a page or pair counts only once the page reader has read the page and it got at least 100 visits in the dates, and pairs are listed only for an ad that sent people to two or more pages, or a page that got people from two or more ads, each naming what the same ad cost on its other pages. \`--week <YYYY-MM-DD>\` picks any day of a Monday-to-Sunday week (default: the latest complete week), \`--days <n>\` the last n complete days ending yesterday, and \`--from <YYYY-MM-DD> --to <YYYY-MM-DD>\` any dates; use one of them, at most 90 days. Check as often as suits the client, daily or every few days: a short window holds few sales, so more ads are judged on first leads, and the report says so. \`--top <n>\` how many ads, pages or pairs each list shows (default 5, at most 20), \`--ad-format image|video|carousel\` ranks only ads with that format tag (run \`${cli} ads tag-formats\` first; the account's cost per sale still counts every ad), and \`--format json\` gives the report as data.
 
 ## What winners and flops taught: lessons
 
@@ -54,7 +54,7 @@ Write one as JSON, \`{"text": "...", "dimension": "hook", "evidence": [{"ad": "<
 
 ## The weekly loop: a sample for an orchestrator agent
 
-The \`weekly-loop\` playbook (\`${cli} skill install weekly-loop\` installs it as the \`${WEEKLY_LOOP_SKILL_NAME}\` skill; \`${cli} docs weekly-loop\` prints it) is a sample to borrow from, not a schedule, for a local agent that runs a client's Facebook ads with its owner: its steps can run daily, several times a week or weekly, and the winners report covers whatever dates are asked for. It names the command and the MCP tool for each step: the winners and flops report, lessons, fresh customer words, the brief, the offers and funnels map, making ads (Exodus, paid tools or the agent's own skills), and the results of what was published, read back by Adzara's labels. Judge winners by ${brand.name}'s real-sales report (\`${cli} winners\`); Adzara's results are Meta's count. Approvals and decisions happen in the agent's own session with the owner; ${brand.name} records none. Ads are published and changed through Adzara, never through ${brand.name}.
+The \`weekly-loop\` playbook (\`${cli} skill install weekly-loop\` installs it as the \`${WEEKLY_LOOP_SKILL_NAME}\` skill; \`${cli} docs weekly-loop\` prints it) is a sample to borrow from, not a schedule, for a local agent that runs a client's Facebook ads with its owner: its steps can run daily, several times a week or weekly, and the winners report covers whatever dates are asked for. It names the command and the MCP tool for each step: the winners and flops report, lessons, fresh customer words, the brief, the offers and funnels map, making ads (Exodus, paid tools or the agent's own skills), and the results of what was published, read back by Adzara's labels. Judge winners by ${brand.name}'s Winners and flops report, which judges each client on its goal (\`${cli} winners\`); Adzara's results are Meta's count. Approvals and decisions happen in the agent's own session with the owner; ${brand.name} records none. Ads are published and changed through Adzara, never through ${brand.name}.
 
 ## Trying one change: funnel tests
 
@@ -291,9 +291,9 @@ A scheduled hand's run acts as its skill's agent, the way the Facebook ads agent
 ## Commands
 
 \`\`\`
-${cli} login                        validate a key (prompted, piped, or ${envPrefix}_API_KEY) and save it
-${cli} logout                       delete saved credentials
-${cli} whoami                       show the current workspace and library access
+${cli} login [--client <name>]      validate a key (prompted, piped, or ${envPrefix}_API_KEY) and save it, as the default or under a client's name
+${cli} logout [--client <name>]     delete the default saved login, or one client's
+${cli} whoami                       show the current workspace, library access, and which client's key is in use and why
 ${cli} knowledge search "<question>" [--limit <n>] [--kind <kind>] [--hook-kind <v> ...]   short, cited snippets from the know-how libraries (keys with library access)
 ${cli} knowledge tag <entry-id> --hook-kind <v> --confidence <c>   tag a library entry with the marketing grammar (or --file tags.json)
 ${cli} guide                        what this workspace's data holds, how fresh it is, and what is missing: read it first
@@ -301,7 +301,8 @@ ${cli} brief [--from <date>] [--to <date>] [--channel <channel>] [--campaign <id
 ${cli} pages brief --step <key> [--funnel <key>] | --page <ref>   the offer, step, current page, best and worst pages of its kind, its ads and how to hand a page back: start here before writing a landing page
 ${cli} pages results [--from <date>] [--to <date>] [--page <ref>]   each landing page's, and each ad and page pair's, real first-touch sales, cost per sale and sales per page view
 ${cli} messages results [--from <date>] [--to <date>] [--channel email|text] [--sequence <id>]   real sales after each follow-up email, text and sequence: every message the buyer clicked or replied to in the ${MESSAGE_CREDIT_DAYS} days before buying (helped), and the latest one (last nudge)
-${cli} winners [--week <date> | --days <n> | --from <date> --to <date>] [--top <n>] [--ad-format image|video|carousel]   which Facebook ads and landing pages won and flopped in a week or any dates and over 30 days, judged on first-touch sales, or on Triple Whale's orders for a shop that has them
+${cli} winners [--week <date> | --days <n> | --from <date> --to <date>] [--top <n>] [--ad-format image|video|carousel]   which Facebook ads and landing pages won and flopped in a week or any dates and over 30 days, judged on the client's goal
+${cli} winners goals | winners goals set <goal> [<goal> ...] | winners goals reset   the goals winners judges this client on, tried in order (sales, sales:triple_whale, booked_calls, meta_results, first_leads), setting them, going back to the default
 ${cli} winners send-to-exodus [--week <date> | --days <n> | --from <date> --to <date>] [--dry-run]   send the winners, with their reasons, lessons and customer words, to Exodus; safe to send again
 ${cli} warehouse schema [--summary] [--table <name> ...] [--search <words>]   list tables and columns; --summary for one row per table
 ${cli} warehouse query "<sql>"      run one read-only query (or --file <path>, or stdin); --out <file.csv | file.ndjson | file.json> saves the rows; add --all for every row