@zanfia/cli 0.3.5 → 0.3.10

package/README.md

@@ -0,0 +1,33 @@
+# @zanfia/cli (`zanfia`)
+
+Thin HTTP client over the Zanfia Public API.
+
+> **Status:** published to npm as `@zanfia/cli` (bin `zanfia`), talking to the production Workspace API by default (`ZANFIA_CLI_TARGET=prod` bakes the URLs at build time). Set `ZANFIA_API_URL` to target another environment; local `tsx` runs without baked defaults fall back to the in-memory mock.
+
+## Local usage
+
+```bash
+# from the monorepo root, after `pnpm install`
+pnpm --filter @zanfia/cli dev products list
+
+# or run a one-off
+pnpm --filter @zanfia/cli dev auth whoami
+
+# global flags (--json, --verbose, --api-key) must come BEFORE the subcommand:
+pnpm --filter @zanfia/cli dev --json products list
+```
+
+## Auth resolution order
+
+1. `--api-key` flag
+2. `ZANFIA_API_KEY` environment variable
+3. Stored key in `~/.config/zanfia/credentials.json`
+4. Prompt to run `zanfia auth set-key`
+
+## Environment
+
+| Variable          | Purpose                                          |
+| ----------------- | ------------------------------------------------ |
+| `ZANFIA_API_URL`  | Public API base URL. Unset → mock mode.          |
+| `ZANFIA_API_KEY`  | API key (overrides stored credentials).          |
+| `ZANFIA_CLI_MOCK` | Force mock mode even if `ZANFIA_API_URL` is set. |

package/dist/index.js

@@ -6305,9 +6305,9 @@ var require_retry2 = __commonJS({
   }
 });
 
-// ../../node_modules/signal-exit/signals.js
+// ../../node_modules/proper-lockfile/node_modules/signal-exit/signals.js
 var require_signals = __commonJS({
-  "../../node_modules/signal-exit/signals.js"(exports, module) {
+  "../../node_modules/proper-lockfile/node_modules/signal-exit/signals.js"(exports, module) {
     "use strict";
     module.exports = [
       "SIGABRT",
@@ -6343,9 +6343,9 @@ var require_signals = __commonJS({
   }
 });
 
-// ../../node_modules/signal-exit/index.js
+// ../../node_modules/proper-lockfile/node_modules/signal-exit/index.js
 var require_signal_exit = __commonJS({
-  "../../node_modules/signal-exit/index.js"(exports, module) {
+  "../../node_modules/proper-lockfile/node_modules/signal-exit/index.js"(exports, module) {
     "use strict";
     var process2 = global.process;
     var processOk = function(process3) {
@@ -7087,6 +7087,11 @@ var clients = [
     totalSpentCents: 5800,
     activeProducts: 1,
     language: "en",
+    discordId: null,
+    githubId: null,
+    tagIds: [],
+    emailSubscriptionStatus: null,
+    attribution: null,
     createdAt: "2026-03-02T09:00:00.000Z"
   },
   {
@@ -7099,6 +7104,11 @@ var clients = [
     totalSpentCents: 0,
     activeProducts: 0,
     language: null,
+    discordId: null,
+    githubId: null,
+    tagIds: [],
+    emailSubscriptionStatus: null,
+    attribution: null,
     createdAt: "2026-03-05T09:00:00.000Z"
   }
 ];
@@ -7325,6 +7335,11 @@ var mockBackend = {
       totalSpentCents: 0,
       activeProducts: 0,
       language: input.language ?? null,
+      discordId: null,
+      githubId: null,
+      tagIds: [],
+      emailSubscriptionStatus: null,
+      attribution: null,
       createdAt: now()
     });
     return { clientId: id, created: true, createdUser: true };
@@ -9608,38 +9623,9 @@ function registerLogoutCommand(auth, clear) {
 
 // src/commands/auth/register.ts
 import { createHash as createHash2, randomBytes as randomBytes2 } from "crypto";
+
+// src/utils/httpJson.ts
 import { hostname as hostname2 } from "os";
-import { createInterface } from "readline/promises";
-var MAX_CODE_ATTEMPTS = 5;
-var MIN_PASSWORD_LENGTH = 8;
-var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-var CTRL_C = String.fromCharCode(3);
-var DEL = String.fromCharCode(127);
-function resolveRegisterUrls(explicitApiUrl) {
-  const exchangeUrl = process.env.ZANFIA_EXCHANGE_URL ?? backendDefaults.exchangeUrl;
-  let usersUrl = process.env.ZANFIA_USERS_URL ?? backendDefaults.usersUrl;
-  if (!usersUrl && exchangeUrl?.includes("/cli/auth/exchange")) {
-    usersUrl = exchangeUrl.replace(/\/cli\/auth\/exchange\/?$/, "");
-  }
-  if (!usersUrl) {
-    throw new Error(
-      "ZANFIA_USERS_URL is not set. Set it to the users-service base URL (e.g. https://europe-central2-<project>.cloudfunctions.net/users-v1)."
-    );
-  }
-  usersUrl = usersUrl.replace(/\/$/, "");
-  const firebaseApiKey = process.env.ZANFIA_FIREBASE_API_KEY ?? backendDefaults.firebaseApiKey;
-  if (!firebaseApiKey) {
-    throw new Error(
-      "ZANFIA_FIREBASE_API_KEY is not set. Set it to the Firebase web API key of the target project (public client key, not a secret)."
-    );
-  }
-  return {
-    usersUrl,
-    exchangeUrl: exchangeUrl ?? `${usersUrl}/cli/auth/exchange`,
-    firebaseApiKey,
-    apiUrl: explicitApiUrl ?? process.env.ZANFIA_API_URL ?? backendDefaults.apiUrl
-  };
-}
 async function postJson2(label, url, body, options = {}) {
   if (options.verbose) process.stderr.write(`\u2192 POST ${url}
 `);
@@ -9671,6 +9657,19 @@ function extractErrorMessage(text, fallback) {
   }
   return text || fallback;
 }
+function safeHostname2() {
+  try {
+    const h = hostname2();
+    return h && h.length > 0 ? h : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+// src/utils/prompt.ts
+import { createInterface } from "readline/promises";
+var CTRL_C = String.fromCharCode(3);
+var DEL = String.fromCharCode(127);
 async function promptLine(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -9712,13 +9711,35 @@ function promptHidden(question) {
     stdin.on("data", onData);
   });
 }
-function safeHostname2() {
-  try {
-    const h = hostname2();
-    return h && h.length > 0 ? h : "unknown";
-  } catch {
-    return "unknown";
+
+// src/commands/auth/register.ts
+var MAX_CODE_ATTEMPTS = 5;
+var MIN_PASSWORD_LENGTH = 8;
+var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function resolveRegisterUrls(explicitApiUrl) {
+  const exchangeUrl = process.env.ZANFIA_EXCHANGE_URL ?? backendDefaults.exchangeUrl;
+  let usersUrl = process.env.ZANFIA_USERS_URL ?? backendDefaults.usersUrl;
+  if (!usersUrl && exchangeUrl?.includes("/cli/auth/exchange")) {
+    usersUrl = exchangeUrl.replace(/\/cli\/auth\/exchange\/?$/, "");
+  }
+  if (!usersUrl) {
+    throw new Error(
+      "ZANFIA_USERS_URL is not set. Set it to the users-service base URL (e.g. https://europe-central2-<project>.cloudfunctions.net/users-v1)."
+    );
   }
+  usersUrl = usersUrl.replace(/\/$/, "");
+  const firebaseApiKey = process.env.ZANFIA_FIREBASE_API_KEY ?? backendDefaults.firebaseApiKey;
+  if (!firebaseApiKey) {
+    throw new Error(
+      "ZANFIA_FIREBASE_API_KEY is not set. Set it to the Firebase web API key of the target project (public client key, not a secret)."
+    );
+  }
+  return {
+    usersUrl,
+    exchangeUrl: exchangeUrl ?? `${usersUrl}/cli/auth/exchange`,
+    firebaseApiKey,
+    apiUrl: explicitApiUrl ?? process.env.ZANFIA_API_URL ?? backendDefaults.apiUrl
+  };
 }
 function resolveTimezone() {
   try {
@@ -13375,6 +13396,145 @@ function registerFunnelsCommands(program3) {
   );
 }
 
+// src/commands/join/index.ts
+var MAX_CODE_ATTEMPTS2 = 5;
+var HANDLE_REGEX = /^[a-z0-9][a-z0-9-]{1,62}$/;
+var EMAIL_REGEX2 = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var AGENT_DOCS_URL = "https://zanfia.com/help/developer-cli/agents";
+function joinUrl(base, handle, step) {
+  return `${base.replace(/\/$/, "")}/v1/join/${encodeURIComponent(handle)}/${step}`;
+}
+async function runJoin(handleInput, options) {
+  const handle = handleInput.trim().toLowerCase();
+  if (!HANDLE_REGEX.test(handle)) {
+    throw new Error(
+      "Community handle must be lowercase letters, digits and dashes (e.g. crew-of-one)."
+    );
+  }
+  const communityApiUrl = resolveCommunityApiUrl();
+  if (!communityApiUrl) {
+    throw new Error(
+      "No Community API URL configured. Set ZANFIA_COMMUNITY_API_URL (this build has no baked backend)."
+    );
+  }
+  const verbose = options.verbose === true;
+  const email = (options.email ?? await promptLine("Email: ")).trim().toLowerCase();
+  if (!EMAIL_REGEX2.test(email)) {
+    throw new Error("Please enter a valid email address.");
+  }
+  const started = await postJson2(
+    "Join",
+    joinUrl(communityApiUrl, handle, "start"),
+    { email, lang: "en" },
+    { verbose }
+  );
+  if (!options.json) {
+    process.stdout.write(
+      `Joining ${started.communityName} (${started.workspaceName}) \u2014 a 6-digit code was sent to ${email}.
+`
+    );
+  }
+  const firstName = options.name ?? (options.json ? "" : await promptLine("Your name (optional): "));
+  const hostname3 = safeHostname2();
+  let completed = null;
+  for (let attempt = 1; attempt <= MAX_CODE_ATTEMPTS2 && !completed; attempt += 1) {
+    const code = options.code ?? (await promptLine("Code from the email (or 'r' to resend): ")).trim();
+    if (code.toLowerCase() === "r") {
+      await postJson2(
+        "Resend",
+        joinUrl(communityApiUrl, handle, "start"),
+        { email, lang: "en" },
+        { verbose }
+      );
+      process.stdout.write("Code re-sent.\n");
+      attempt -= 1;
+      continue;
+    }
+    try {
+      completed = await postJson2(
+        "Join",
+        joinUrl(communityApiUrl, handle, "complete"),
+        { email, code, firstName, hostname: hostname3 },
+        { verbose }
+      );
+    } catch (err) {
+      if (options.code || attempt === MAX_CODE_ATTEMPTS2) throw err;
+      process.stdout.write(`${err instanceof Error ? err.message : String(err)}
+`);
+    }
+  }
+  if (!completed) {
+    throw new Error("Could not verify the code.");
+  }
+  const path2 = writeCredentials({
+    apiKey: completed.token,
+    apiUrl: communityApiUrl,
+    savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    source: "oauth",
+    expiresAt: completed.expiresAt,
+    userEmail: completed.userEmail,
+    workspaceId: completed.workspaceId,
+    workspaceName: completed.workspaceName,
+    kind: "member"
+  });
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          joined: true,
+          alreadyMember: completed.alreadyMember,
+          communityId: completed.communityId,
+          communityName: completed.communityName,
+          workspaceId: completed.workspaceId,
+          workspaceName: completed.workspaceName,
+          introChannelId: completed.introChannelId,
+          userEmail: completed.userEmail,
+          expiresAt: completed.expiresAt,
+          credentialsPath: path2
+        },
+        null,
+        2
+      )}
+`
+    );
+    return;
+  }
+  const intro = completed.introChannelId ? `  zanfia communities post create ${completed.communityId} ${completed.introChannelId} --content "Hi, I'm <your agent>. I ..."
+` : "";
+  process.stdout.write(
+    `
+${completed.alreadyMember ? "Welcome back to" : "You are in:"} ${completed.communityName}.
+Member key saved to ${path2} (expires ${completed.expiresAt.slice(0, 10)}).
+
+Next:
+  zanfia communities list
+  zanfia communities channels ${completed.communityId}
+` + (intro ? `
+Introduce your agent:
+${intro}` : "") + `
+Plug in your agent: ${AGENT_DOCS_URL}
+`
+  );
+}
+function registerJoinCommand(program3) {
+  program3.command("join <handle>").description("Join a public community from the terminal (emailed code) and get a member key").option("--email <email>", "email to join with (prompted when omitted)").option("--name <name>", "your display name (prompted when omitted)").option("--code <code>", "the 6-digit code from the email (prompted when omitted)").addHelpText(
+    "after",
+    `
+Examples:
+  zanfia join crew-of-one
+  zanfia join crew-of-one --email me@example.com --name "Sam" --code 123456
+
+The key is a MEMBER key: it reaches the Community API for that creator's
+communities only (read/post/comment/chat), never your own workspace. It is
+saved to ~/.config/zanfia/credentials.json and expires in 90 days \u2014 run
+join again to refresh it.
+`
+  ).action(async (handle, options, command) => {
+    const globals = command.optsWithGlobals();
+    await runJoin(handle, { ...options, json: globals.json, verbose: globals.verbose });
+  });
+}
+
 // src/commands/media/index.ts
 import { writeFileSync as writeFileSync2 } from "fs";
 import { readFile, stat as stat3 } from "fs/promises";
@@ -17059,6 +17219,7 @@ function buildPriceInput(options) {
     compareAtAmountCents: options.compareAt ? parsePositiveInt7(options.compareAt, "--compare-at") : void 0,
     accessInterval: options.accessInterval ? parseChoice3(options.accessInterval, PRICE_INTERVALS, "--access-interval") : void 0,
     accessIntervalCount: options.accessCount ? parsePositiveInt7(options.accessCount, "--access-count") : void 0,
+    accessUntil: options.accessUntil || void 0,
     planId: options.plan
   };
 }
@@ -17069,6 +17230,7 @@ var PRICE_PLACEMENT_CHOICES = [
   "belowDescription",
   "aboveDescription"
 ];
+var PLAN_INCLUDES_LAYOUT_CHOICES = ["inline", "list"];
 var JSON_PATCH_REJECTED_KEYS2 = [
   "active",
   "archived",
@@ -17118,8 +17280,22 @@ function buildOfferUpdateInput(options) {
     options.checkoutMediaWidth === void 0 ? void 0 : options.checkoutMediaWidth.trim().toLowerCase() === "none" ? null : parsePositiveInt7(options.checkoutMediaWidth, "--checkout-media-width")
   );
   set("showTestimonials", bool(options.showTestimonials, "--show-testimonials"));
+  set("showPlanIncludes", bool(options.showPlanIncludes, "--show-plan-includes"));
+  set(
+    "planIncludesLayout",
+    options.planIncludesLayout === void 0 ? void 0 : parseChoice3(
+      options.planIncludesLayout,
+      PLAN_INCLUDES_LAYOUT_CHOICES,
+      "--plan-includes-layout"
+    )
+  );
   set("invoiceAsOption", bool(options.invoiceAsOption, "--invoice-as-option"));
   set("hideCountryField", bool(options.hideCountryField, "--hide-country-field"));
+  set(
+    "fixedCountry",
+    options.fixedCountry === void 0 ? void 0 : options.fixedCountry === "none" ? null : options.fixedCountry.toUpperCase()
+  );
+  set("showFixedCountry", bool(options.showFixedCountry, "--show-fixed-country"));
   set(
     "showPhoneField",
     options.showPhoneField === void 0 ? void 0 : parseVisibility(options.showPhoneField, "--show-phone-field")
@@ -17332,7 +17508,19 @@ Order bumps (${checkout.orderBumps.length}):
   );
   offers.command("update").description(
     'Update any offer (checkout-builder) setting \u2014 display, form & UX, legal, invoicing, notifications, tracking. Boolean flags take on|off; "none" clears a nullable field. Deep structured fields (theme, deadline, afterPurchase, paymentMethodsDisplay, customInvoicesClient, multiplePurchaseType, checkoutImages, checkoutMedia, termsContent, privacyPolicyContent, oto) go through --json. Lifecycle stays with publish/unpublish/delete; order bumps with `bumps attach`/`bumps detach`; the reusable OTO offer documents themselves with `oto create`/`update`/`delete`.'
-  ).argument("<checkoutId>", "offer (checkout) id").option("--name <name>", "internal offer name").option("--slug <slug>", "public slug (changing it on a live offer breaks links)").option("--title <title>", "checkout page title").option("--description <description>", "checkout page description").option("--success-url <url|none>", "post-purchase redirect URL (none = clear)").option("--language <code|none>", "checkout page language, e.g. en, pl (none = clear)").option("--checkout-media-width <px|none>", "max media gallery width in px (none = full width)").option("--show-testimonials <on|off>", "show the product testimonials gallery").option("--invoice-as-option <on|off>", "let the buyer opt into invoice data entry").option("--hide-country-field <on|off>", "hide the country field on the form").option("--show-phone-field <off|optional|required>", "phone field visibility").option("--show-additional-info <off|optional|required>", "additional-info field visibility").option("--collect-first-name <on|off>", "free checkouts: collect first name").option("--collect-last-name <on|off>", "free checkouts: collect last name").option(
+  ).argument("<checkoutId>", "offer (checkout) id").option("--name <name>", "internal offer name").option("--slug <slug>", "public slug (changing it on a live offer breaks links)").option("--title <title>", "checkout page title").option("--description <description>", "checkout page description").option("--success-url <url|none>", "post-purchase redirect URL (none = clear)").option("--language <code|none>", "checkout page language, e.g. en, pl (none = clear)").option("--checkout-media-width <px|none>", "max media gallery width in px (none = full width)").option("--show-testimonials <on|off>", "show the product testimonials gallery").option(
+    "--show-plan-includes <on|off>",
+    'show the "Includes" list of bundled products under each price (multi-plan products; default on)'
+  ).option(
+    "--plan-includes-layout <inline|list>",
+    'layout of that "Includes" list: inline = one line (default), list = one product per line'
+  ).option("--invoice-as-option <on|off>", "let the buyer opt into invoice data entry").option("--hide-country-field <on|off>", "hide the country field on the form").option(
+    "--fixed-country <ISO|none>",
+    "country stored on orders while the country field is hidden (none = Poland)"
+  ).option(
+    "--show-fixed-country <on|off>",
+    "with the country field hidden: keep it on the form as a locked, read-only field"
+  ).option("--show-phone-field <off|optional|required>", "phone field visibility").option("--show-additional-info <off|optional|required>", "additional-info field visibility").option("--collect-first-name <on|off>", "free checkouts: collect first name").option("--collect-last-name <on|off>", "free checkouts: collect last name").option(
     "--allow-promotion-code <off|subscriptions|all>",
     "promotion-code input: hidden, subscription prices only, or all prices"
   ).option("--force-b2b <on|off>", "force company (B2B) purchase data").option(
@@ -17488,7 +17676,10 @@ Order bumps (${checkout.orderBumps.length}):
   price.command("add").description("Add a price variant to an offer").argument("<checkoutId>", "offer (checkout) id").requiredOption("--type <type>", "one_time | recurring | installments").requiredOption(
     "--amount <minor-units>",
     "unit price in minor units, e.g. 1999 = 19.99 (installments: each payment)"
-  ).requiredOption("--currency <code>", "pln | usd | eur | gbp").option("--interval <interval>", "billing interval: day | week | month | year").option("--interval-count <n>", "bill every n intervals").option("--cycles <n>", "installments: total number of payments (>= 2)").option("--allow-cancellation", "installments: let the buyer cancel the schedule").option("--trial-days <n>", "recurring: free-trial days before the first charge").option("--label <text>", "display label").option("--invoice-name <text>", "custom invoice line name").option("--hidden", "hide from the public price list (buyable via direct link)").option("--description <text>", "markdown description rendered under the price").option("--sale-ends-at <ISO>", "time-limited sale deadline (ISO 8601, in the future)").option("--sale-days <n>", "convenience: end the sale n days from now").option("--quantity-limit <n>", "seat limit").option("--show-available", "show the remaining quantity publicly").option("--compare-at <minor-units>", 'promo strike-through "was" price in minor units').option("--access-interval <interval>", "one-time: limited access window unit").option("--access-count <n>", "one-time: limited access window length").option("--plan <planId>", "link the price to a plan").action(async (checkoutId, options, command) => {
+  ).requiredOption("--currency <code>", "pln | usd | eur | gbp").option("--interval <interval>", "billing interval: day | week | month | year").option("--interval-count <n>", "bill every n intervals").option("--cycles <n>", "installments: total number of payments (>= 2)").option("--allow-cancellation", "installments: let the buyer cancel the schedule").option("--trial-days <n>", "recurring: free-trial days before the first charge").option("--label <text>", "display label").option("--invoice-name <text>", "custom invoice line name").option("--hidden", "hide from the public price list (buyable via direct link)").option("--description <text>", "markdown description rendered under the price").option("--sale-ends-at <ISO>", "time-limited sale deadline (ISO 8601, in the future)").option("--sale-days <n>", "convenience: end the sale n days from now").option("--quantity-limit <n>", "seat limit").option("--show-available", "show the remaining quantity publicly").option("--compare-at <minor-units>", 'promo strike-through "was" price in minor units').option("--access-interval <interval>", "one-time: limited access window unit").option("--access-count <n>", "one-time: limited access window length").option(
+    "--access-until <iso>",
+    "one-time: fixed access end for every buyer (ISO 8601, future; instead of --access-interval)"
+  ).option("--plan <planId>", "link the price to a plan").action(async (checkoutId, options, command) => {
     const flags = getGlobalFlags(command);
     const input = buildPriceInput(options);
     const client = createApiClient({ apiKey: flags.apiKey, verbose: flags.verbose });
@@ -19966,7 +20157,7 @@ function formatSteps(steps) {
 // src/index.ts
 var PROGRAM_NAME = "zanfia".length > 0 ? "zanfia" : "zanfia";
 var program2 = new Command();
-program2.name(PROGRAM_NAME).description("Zanfia CLI \u2014 manage products, clients, orders and more from your terminal").version("0.3.5").option("--api-key <key>", "override stored API key for this invocation").option("--json", "emit JSON output instead of human-readable tables").option("--verbose", "log request/response debug info").showHelpAfterError().addHelpText(
+program2.name(PROGRAM_NAME).description("Zanfia CLI \u2014 manage products, clients, orders and more from your terminal").version("0.3.10").option("--api-key <key>", "override stored API key for this invocation").option("--json", "emit JSON output instead of human-readable tables").option("--verbose", "log request/response debug info").showHelpAfterError().addHelpText(
   "after",
   `
 New to Zanfia?
@@ -19984,10 +20175,14 @@ Signing in \u2014 two roles, two consent pages:
   ${PROGRAM_NAME} auth set-key --api-url <api-community-url> <key>
       Member alternative without a browser: paste the key generated on the
       creator's platform under Settings \u2192 Developer.
+  ${PROGRAM_NAME} join <handle>
+      Join a public community from the terminal: emailed 6-digit code, then a
+      member key is saved \u2014 no account or browser needed. Try: join crew-of-one
 `
 );
 registerLoginCommand(program2);
 registerRegisterCommand(program2);
+registerJoinCommand(program2);
 registerLogoutCommand(program2, clearCredentials);
 registerAuthCommands(program2);
 registerProductsCommands(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zanfia/cli",
-  "version": "0.3.5",
+  "version": "0.3.10",
   "private": false,
   "description": "Zanfia CLI — thin HTTP client over the Zanfia Public API",
   "type": "module",