@oxygen-agent/cli 1.1014.1600 → 1.1014.1763

package/dist/commands/subscriptions.js

@@ -1,9 +1,16 @@
 import { requestOxygen } from "../http-client.js";
 import { isRecord, readOption } from "../util.js";
 import { OxygenError } from "@oxygen/shared/cli-result";
+import { EmailSubscriptionInputError, chunkContactImport, keepContactProperties, parseContactsCsv, } from "@oxygen/shared/email-subscriptions";
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+/** --description / --parent on update: absent leaves it, "" clears it (null). */
+function clearableOption(value) {
+    if (value === undefined)
+        return {};
+    return { value: readOption(value) ?? null };
+}
 function evidenceBody(options) {
     const noticeVersion = readOption(options.noticeVersion);
     const noticeTextHash = readOption(options.noticeTextHash);
@@ -25,48 +32,25 @@ function requireSubscribeEvidence(options, status) {
         throw new OxygenError("consent_evidence_required", "Subscribing needs consent evidence: --notice-version with --notice-text-hash, or --basis naming where consent came from.", { details: { field: "evidence" }, exitCode: 2 });
     }
 }
-/** Split one CSV line, honouring double-quoted fields with "" escapes. */
-function splitCsvLine(line) {
-    const cells = [];
-    let cell = "";
-    let quoted = false;
-    for (let index = 0; index < line.length; index += 1) {
-        const char = line[index];
-        if (quoted) {
-            if (char === "\"" && line[index + 1] === "\"") {
-                cell += "\"";
-                index += 1;
-            }
-            else if (char === "\"")
-                quoted = false;
-            else
-                cell += char;
-        }
-        else if (char === "\"")
-            quoted = true;
-        else if (char === ",") {
-            cells.push(cell.trim());
-            cell = "";
-        }
-        else
-            cell += char;
-    }
-    cells.push(cell.trim());
-    return cells;
-}
 function csvEntries(text) {
-    const lines = text.replace(/^/, "").split(/\r?\n/).filter((line) => line.trim());
-    const header = splitCsvLine(lines[0] ?? "").map((cell) => cell.toLowerCase());
-    const emailIndex = header.findIndex((cell) => cell === "email" || cell === "email_address" || cell === "e-mail");
-    if (emailIndex < 0) {
-        throw new OxygenError("invalid_request", "The CSV needs an email column in its header row.", { exitCode: 2 });
+    try {
+        return parseContactsCsv(text).entries;
     }
-    const personIndex = header.findIndex((cell) => cell === "person_id");
-    return lines.slice(1).map((line) => {
-        const cells = splitCsvLine(line);
-        const personId = personIndex >= 0 ? cells[personIndex] : undefined;
-        return { email: cells[emailIndex] ?? "", ...(personId ? { person_id: personId } : {}) };
-    });
+    catch (error) {
+        if (error instanceof EmailSubscriptionInputError)
+            throw new OxygenError("invalid_request", error.message, { details: { field: error.field }, exitCode: 2 });
+        throw error;
+    }
+}
+/**
+ * Keep only the columns that are contact properties of this workspace, so a
+ * stray column (a CRM export's "company", an index) is reported, not refused.
+ */
+async function keepKnownProperties(entries) {
+    if (!entries.some((entry) => entry.properties && Object.keys(entry.properties).length > 0))
+        return { entries, ignored: [] };
+    const known = await requestOxygen("/api/cli/subscriptions/properties");
+    return keepContactProperties(entries, new Set((known.properties ?? []).map((property) => property.key)));
 }
 function jsonEntries(value) {
     const list = Array.isArray(value) ? value : isRecord(value) && Array.isArray(value.entries) ? value.entries : null;
@@ -77,7 +61,16 @@ function jsonEntries(value) {
         if (typeof entry === "string")
             return { email: entry };
         if (isRecord(entry) && typeof entry.email === "string") {
-            return { email: entry.email, ...(typeof entry.person_id === "string" ? { person_id: entry.person_id } : {}) };
+            const properties = isRecord(entry.properties)
+                ? Object.fromEntries(Object.entries(entry.properties).flatMap(([key, value]) => (typeof value === "string" || typeof value === "number" ? [[key, String(value)]] : [])))
+                : {};
+            return {
+                email: entry.email,
+                ...(typeof entry.person_id === "string" ? { person_id: entry.person_id } : {}),
+                ...(typeof entry.first_name === "string" && entry.first_name ? { first_name: entry.first_name } : {}),
+                ...(typeof entry.last_name === "string" && entry.last_name ? { last_name: entry.last_name } : {}),
+                ...(Object.keys(properties).length > 0 ? { properties } : {}),
+            };
         }
         return { email: "" };
     });
@@ -121,24 +114,133 @@ function runSubscriptionsSet(email, options) {
         },
     });
 }
-function runSubscriptionsImport(options) {
+/**
+ * Send the import in route-sized calls (one consent evidence record covers
+ * every call: the same source vouched for the whole file) and add up the
+ * counts. Invalid indexes refer to the file's own rows.
+ */
+async function runSubscriptionsImport(options) {
     const list = requireFlag(options.list, "--list");
     const source = requireFlag(options.source, "--source");
     const status = readOption(options.status) ?? "subscribed";
     requireSubscribeEvidence(options, status);
-    const entries = readSubscriptionImportFile(requireFlag(options.file, "--file"));
+    const read = readSubscriptionImportFile(requireFlag(options.file, "--file"));
+    const { entries, ignored } = await keepKnownProperties(read);
     const evidence = evidenceBody(options);
-    return requestOxygen("/api/cli/subscriptions/import", {
+    const chunks = chunkContactImport(entries);
+    let last = {};
+    const totals = { received: 0, created: 0, updated: 0, unchanged: 0, kept_cleaned: 0, people_written: 0, people_matched: 0 };
+    const invalid = [];
+    let offset = 0;
+    for (const chunk of chunks) {
+        last = await requestOxygen("/api/cli/subscriptions/import", {
+            method: "POST",
+            body: {
+                list,
+                entries: chunk,
+                status,
+                source,
+                ...(evidence ? { evidence } : {}),
+            },
+        });
+        for (const key of Object.keys(totals))
+            totals[key] += Number(last[key] ?? 0);
+        for (const entry of last.invalid ?? [])
+            invalid.push({ ...entry, index: entry.index + offset });
+        offset += chunk.length;
+    }
+    if (chunks.length === 1 && ignored.length === 0)
+        return last;
+    const written = totals.created + totals.updated;
+    return {
+        ...last,
+        ...totals,
+        invalid,
+        calls: chunks.length,
+        ...(ignored.length > 0 ? { ignored_columns: ignored } : {}),
+        changed: written > 0,
+        effect_outcome: written > 0 ? (invalid.length > 0 ? "partial" : "applied") : totals.received === 0 ? "no_data" : "no_change",
+        message: `${written} of ${totals.received} addresses changed on ${list} in ${chunks.length} call(s)`
+            + (ignored.length > 0 ? `; columns that are not contact properties were skipped: ${ignored.join(", ")}` : "")
+            + ".",
+    };
+}
+/** --property key=value, repeatable; key= (empty) clears the property. */
+function readPropertyFlags(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const properties = {};
+    for (const value of values) {
+        const at = value.indexOf("=");
+        if (at <= 0) {
+            throw new OxygenError("invalid_request", "--property takes key=value (key= clears it).", { details: { field: "properties", value }, exitCode: 2 });
+        }
+        const raw = value.slice(at + 1);
+        properties[value.slice(0, at).trim()] = raw === "" ? null : raw;
+    }
+    return properties;
+}
+function contactFieldBody(options) {
+    const properties = readPropertyFlags(options.property);
+    return {
+        // An explicit empty flag clears the field on the person.
+        ...(options.firstName !== undefined ? { first_name: options.firstName === "" ? null : options.firstName } : {}),
+        ...(options.lastName !== undefined ? { last_name: options.lastName === "" ? null : options.lastName } : {}),
+        ...(properties ? { properties } : {}),
+    };
+}
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+function runContactsList(options) {
+    const params = new URLSearchParams({ list: requireFlag(options.list, "--list") });
+    for (const [key, value] of [["search", options.search], ["status", options.status], ["after", options.after], ["limit", options.limit]]) {
+        const read = readOption(value);
+        if (read)
+            params.set(key, read);
+    }
+    return requestOxygen(`/api/cli/subscriptions/contacts?${params.toString()}`);
+}
+function runContactsAdd(email, options) {
+    const list = requireFlag(options.list, "--list");
+    const status = readOption(options.status) ?? "subscribed";
+    const note = readOption(options.note);
+    if (!note)
+        requireSubscribeEvidence(options, status);
+    const source = readOption(options.source);
+    const evidence = evidenceBody(options);
+    return requestOxygen("/api/cli/subscriptions/contacts", {
         method: "POST",
         body: {
             list,
-            entries,
+            email,
             status,
-            source,
+            ...(source ? { source } : {}),
+            ...(note ? { note } : {}),
             ...(evidence ? { evidence } : {}),
+            ...contactFieldBody(options),
         },
     });
 }
+function runContactsEdit(email, options) {
+    return requestOxygen("/api/cli/subscriptions/contacts", {
+        method: "PATCH",
+        body: { list: requireFlag(options.list, "--list"), email, ...contactFieldBody(options) },
+    });
+}
+function runContactsRemove(email, options) {
+    const params = new URLSearchParams({ list: requireFlag(options.list, "--list"), email });
+    return requestOxygen(`/api/cli/subscriptions/contacts?${params.toString()}`, { method: "DELETE" });
+}
+async function runSubscriptionsExport(options) {
+    const list = requireFlag(options.list, "--list");
+    const output = resolve(requireFlag(options.output, "--output"));
+    const params = new URLSearchParams({ list, format: "csv" });
+    const saved = await requestOxygen(`/api/cli/subscriptions/contacts/export?${params.toString()}`, {
+        binaryOutputPath: output,
+    });
+    return { list, path: saved.path, bytes: saved.bytes, message: `Saved ${list}'s contacts to ${saved.path}.` };
+}
 function addEvidenceFlags(command) {
     return command
         .option("--notice-version <version>", "Version of the consent notice the person saw (with --notice-text-hash).")
@@ -158,18 +260,64 @@ export function registerSubscriptionsFamily(program, handleAsyncAction) {
         await handleAsyncAction("subscriptions lists list", options, () => requestOxygen("/api/cli/subscriptions/lists"));
     }))
         .addCommand(new Command("create")
-        .description("Create a subscription list.")
+        .description("Create a subscription list or a topic. A topic (--kind topic --parent <list>) is a narrower subject inside an audience list; a newsletter on a topic mails only its subscribers. --default opt_out puts the list's subscribers on the topic (same consent); opt_in waits for each recipient's choice on their preference page.")
         .argument("<key>", "Stable key: lowercase letters, digits, - and _, such as newsletter.")
         .requiredOption("--name <name>", "Display name.")
-        .requiredOption("--kind <kind>", "marketing, product_updates or onboarding.")
+        .requiredOption("--kind <kind>", "marketing, product_updates, onboarding or topic.")
         .option("--description <text>", "What subscribers get.")
+        .option("--visibility <visibility>", "public (default; on the preference page) or private (shown only to subscribers).")
+        .option("--default <subscription>", "Topics: opt_in (default) or opt_out (joined with the parent list).")
+        .option("--parent <key-or-id>", "Topics: the audience list this topic belongs to.")
         .option("--json", "Print a JSON envelope.")
         .action(async (key, options) => {
         await handleAsyncAction("subscriptions lists create", options, () => {
             const description = readOption(options.description);
+            const visibility = readOption(options.visibility);
+            const defaultSubscription = readOption(options.default);
+            const parent = readOption(options.parent);
             return requestOxygen("/api/cli/subscriptions/lists", {
                 method: "POST",
-                body: { key, name: options.name, kind: options.kind, ...(description ? { description } : {}) },
+                body: {
+                    key,
+                    name: options.name,
+                    kind: options.kind,
+                    ...(description ? { description } : {}),
+                    ...(visibility ? { visibility } : {}),
+                    ...(defaultSubscription ? { default_subscription: defaultSubscription } : {}),
+                    ...(parent ? { parent } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Change a list or topic: name, description, kind, visibility, default subscription or parent. Turning a topic opt_out puts its list's current subscribers on it, each with their own consent evidence. The key never changes.")
+        .argument("<list>", "List key or id.")
+        .option("--name <name>", "Display name.")
+        .option("--kind <kind>", "marketing, product_updates, onboarding or topic.")
+        .option("--description <text>", "What subscribers get (\"\" clears it).")
+        .option("--visibility <visibility>", "public or private.")
+        .option("--default <subscription>", "Topics: opt_in or opt_out.")
+        .option("--parent <key-or-id>", "Topics: the audience list (\"\" clears it).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (list, options) => {
+        await handleAsyncAction("subscriptions lists update", options, () => {
+            const name = readOption(options.name);
+            const kind = readOption(options.kind);
+            const visibility = readOption(options.visibility);
+            const defaultSubscription = readOption(options.default);
+            const description = clearableOption(options.description);
+            const parent = clearableOption(options.parent);
+            return requestOxygen("/api/cli/subscriptions/lists", {
+                method: "PATCH",
+                body: {
+                    list,
+                    ...(name ? { name } : {}),
+                    ...(kind ? { kind } : {}),
+                    ...(visibility ? { visibility } : {}),
+                    ...(defaultSubscription ? { default_subscription: defaultSubscription } : {}),
+                    ...("value" in description ? { description: description.value } : {}),
+                    ...("value" in parent ? { parent: parent.value } : {}),
+                },
             });
         });
     })))
@@ -191,7 +339,7 @@ export function registerSubscriptionsFamily(program, handleAsyncAction) {
         await handleAsyncAction("subscriptions set", options, () => runSubscriptionsSet(email, options));
     }))
         .addCommand(addEvidenceFlags(new Command("import")
-        .description("Import up to 5,000 addresses onto one list under one consent evidence record. --file is JSON (emails or { email, person_id }) or CSV with an email column. Addresses cleaned by a complaint or hard bounce stay off; invalid rows are reported by index.")
+        .description("Import addresses onto one list under one consent evidence record. --file is JSON (emails or { email, first_name, last_name, properties }) or CSV with an email column; first_name, last_name and contact-property columns go to each person on Records People (created or matched by email). Large files are sent in batches. Addresses cleaned by a complaint or hard bounce stay off; invalid rows are reported by index.")
         .requiredOption("--list <key-or-id>", "Subscription list key or id.")
         .requiredOption("--file <path>", "JSON or CSV file of addresses.")
         .requiredOption("--source <source>", "Where these addresses came from, e.g. webinar_2026_10.")
@@ -199,5 +347,103 @@ export function registerSubscriptionsFamily(program, handleAsyncAction) {
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("subscriptions import", options, () => runSubscriptionsImport(options));
-    })));
+    }))
+        .addCommand(new Command("export")
+        .description("Save every contact of a list as CSV: each status, the consent that subscribed it (when, source, basis or notice), name and contact properties.")
+        .requiredOption("--list <key-or-id>", "Subscription list key or id.")
+        .requiredOption("--output <path>", "CSV file to create (must not exist).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("subscriptions export", options, () => runSubscriptionsExport(options));
+    }))
+        .addCommand(registerContactsCommands(handleAsyncAction))
+        .addCommand(registerPropertiesCommands(handleAsyncAction)));
+}
+function addContactFieldFlags(command) {
+    return command
+        .requiredOption("--list <key-or-id>", "Subscription list key or id.")
+        .option("--first-name <name>", "First name on the person's Records People record (\"\" clears it).")
+        .option("--last-name <name>", "Last name on the person's Records People record (\"\" clears it).")
+        .option("--property <key=value>", "A contact property, repeatable; key= clears it. List keys with subscriptions properties list.", collect);
+}
+function registerContactsCommands(handleAsyncAction) {
+    return new Command("contacts")
+        .description("Contacts of a subscription list: each address with its status, consent source and its Records person (name and contact properties).")
+        .addCommand(new Command("list")
+        .description("List a list's contacts with status, source, subscribed date, name and properties; search by email or name.")
+        .requiredOption("--list <key-or-id>", "Subscription list key or id.")
+        .option("--search <text>", "Match the email or the person's name.")
+        .option("--status <status>", "Only subscribed, unsubscribed, pending or cleaned.")
+        .option("--after <email>", "next_cursor of the previous page.")
+        .option("--limit <n>", "Contacts per page, 1 to 200 (default 50).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("subscriptions contacts list", options, () => runContactsList(options));
+    }))
+        .addCommand(addEvidenceFlags(addContactFieldFlags(new Command("add")
+        .description("Add one contact to a list by hand, with consent evidence (--note says where consent came from), and write its name and properties to Records People.")
+        .argument("<email>", "Email address."))
+        .option("--status <status>", "Status to set (default subscribed).")
+        .option("--source <source>", "Where this contact came from (default manual).")
+        .option("--note <text>", "How you got this person's consent; recorded as the consent basis with your name."))
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleAsyncAction("subscriptions contacts add", options, () => runContactsAdd(email, options));
+    }))
+        .addCommand(addContactFieldFlags(new Command("edit")
+        .description("Edit a contact's name or properties on its Records People record. Status and consent stay as they are.")
+        .argument("<email>", "Email address."))
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleAsyncAction("subscriptions contacts edit", options, () => runContactsEdit(email, options));
+    }))
+        .addCommand(new Command("remove")
+        .description("Remove a contact from a list. Its consent history is kept and its Records person is untouched; to stop mail but keep it listed, use subscriptions set --status unsubscribed.")
+        .argument("<email>", "Email address.")
+        .requiredOption("--list <key-or-id>", "Subscription list key or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleAsyncAction("subscriptions contacts remove", options, () => runContactsRemove(email, options));
+    }));
+}
+function registerPropertiesCommands(handleAsyncAction) {
+    return new Command("properties")
+        .description("Contact properties: text or number fields on Records People that newsletters use as {{contact.<key>}}.")
+        .addCommand(new Command("list")
+        .description("List contact properties (key, label, type).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("subscriptions properties list", options, () => requestOxygen("/api/cli/subscriptions/properties"));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a contact property: a new text or number field on Records People.")
+        .argument("<key>", "Field key, e.g. plan; {{contact.plan}} in a template.")
+        .option("--label <label>", "Display name (default the key).")
+        .option("--type <type>", "string or number (default string).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (key, options) => {
+        await handleAsyncAction("subscriptions properties create", options, () => {
+            const label = readOption(options.label);
+            const type = readOption(options.type);
+            return requestOxygen("/api/cli/subscriptions/properties", {
+                method: "POST",
+                body: { key, ...(label ? { label } : {}), ...(type ? { type } : {}) },
+            });
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Rename a contact property. Its key never changes.")
+        .argument("<key>", "Property key.")
+        .requiredOption("--label <label>", "New display name.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (key, options) => {
+        await handleAsyncAction("subscriptions properties update", options, () => requestOxygen("/api/cli/subscriptions/properties", { method: "PATCH", body: { key, label: options.label } }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete a contact property: the People field is removed and its values archived (restorable on the People table).")
+        .argument("<key>", "Property key.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (key, options) => {
+        await handleAsyncAction("subscriptions properties delete", options, () => requestOxygen(`/api/cli/subscriptions/properties?${new URLSearchParams({ key }).toString()}`, { method: "DELETE" }));
+    }));
 }

package/dist/credential-storage/store.d.ts

@@ -0,0 +1,10 @@
+/** The CLI's per-user config directory; `OXYGEN_CONFIG_DIR` overrides it. */
+export declare function resolveConfigDir(env?: NodeJS.ProcessEnv): string;
+/** Own raw credential IO. The same live environment is read at every original
+ * operation boundary; the application still owns documents and profiles.
+ * Construct once at the application's original promisify initialization point. */
+export declare function createCredentialStorage(): {
+    readSystemCredentialPayload: (env: NodeJS.ProcessEnv) => Promise<string | null>;
+    writeSystemCredentialPayload: (payload: string, env: NodeJS.ProcessEnv) => Promise<void>;
+    deleteSystemCredentialPayload: (env: NodeJS.ProcessEnv) => Promise<void>;
+};