komplian 0.3.8 → 0.4.1

package/README.md

@@ -6,6 +6,30 @@
 2. Browser login: `gh auth login -h github.com -s repo -s read:org -w`
 3. `npx komplian onboard --yes`
 
+### Postman (colección + entornos)
+
+1. En [Postman](https://postman.com) usa una cuenta con email **`@komplian.com`** (o añade ese email a tu perfil).
+2. Crea una **API key**: Settings → **API keys** → Generate.
+3. **Una vez por máquina** (guarda la clave en `~/.komplian/postman-api-key`; no hace falta `export` después):
+
+```bash
+npx komplian postman login
+```
+
+4. Cuando quieras sincronizar la colección:
+
+```bash
+npx komplian postman --yes
+```
+
+Opcional: `export POSTMAN_API_KEY=…` solo para la sesión actual (tiene prioridad sobre el archivo).
+
+El comando llama a `GET https://api.getpostman.com/me` y **solo continúa** si el email de la cuenta es `@komplian.com`. Crea la colección **Komplian API**, los entornos **Komplian — Local Dev** y **Komplian — Production**, y deja copia en `./komplian-postman/*.json`.
+
+- Solo exportar archivos (sin subir por API): `npx komplian postman --yes --export-only`
+- Otro workspace: `POSTMAN_WORKSPACE_ID=<id>`
+- Ruta alternativa del archivo de clave: `KOMPLIAN_POSTMAN_KEY_FILE`
+
 No OAuth App registration — `gh` uses GitHub’s built-in flow. **Default workspace:** current working directory (`process.cwd()`), not `~/komplian`. Pass a path as last argument to clone elsewhere.  
 **Dependencies:** repos with `package-lock.json` use **`npm ci`** (does not modify the lockfile, so no spurious git changes). Repos without a lockfile use **`npm install --no-package-lock`** so onboarding does not create a new `package-lock.json`. Yarn / pnpm repos use frozen lock installs when `yarn` / `pnpm` is on PATH. Unless `KOMPLIAN_NPM_AUDIT=1`, npm runs with `--no-audit --no-fund`.
 

package/komplian-onboard.mjs

@@ -394,8 +394,10 @@ function npmInstallEach(workspace) {
 }
 
 function usage() {
-  log(`Uso: komplian onboard [opciones] [carpeta]`);
+  log(`Uso: komplian onboard [opciones] [carpeta]  |  komplian postman [opciones]`);
   log(`  npx komplian onboard --yes`);
+  log(`  npx komplian postman login   ${c.dim}(una vez · guarda API key)${c.reset}`);
+  log(`  npx komplian postman --yes    ${c.dim}(email @komplian.com)${c.reset}`);
   log(``);
   log(`  Antes (una vez): gh auth login -h github.com -s repo -s read:org -w`);
   log(`  Requisitos: Node 18+, git, GitHub CLI (gh)`);
@@ -478,8 +480,15 @@ function normalizeArgv(argv) {
 }
 
 async function main() {
+  const rawArgv = process.argv.slice(2);
+  if (rawArgv[0] === "postman") {
+    const { runPostman } = await import("./komplian-postman.mjs");
+    await runPostman(rawArgv.slice(1));
+    return;
+  }
+
   const configPath = join(__dirname, "komplian-team-repos.json");
-  const { argv, fromOnboardSubcommand } = normalizeArgv(process.argv.slice(2));
+  const { argv, fromOnboardSubcommand } = normalizeArgv(rawArgv);
   const args = parseArgs(argv);
   if (fromOnboardSubcommand && !args.noInstall && !args.listTeams && !args.help) {
     args.install = true;

package/komplian-postman.mjs

@@ -0,0 +1,599 @@
+#!/usr/bin/env node
+/**
+ * Komplian Postman — API key + email @komplian.com (Postman /me), luego colección + entornos.
+ *
+ * Requisitos: Node 18+. Primera vez: npx komplian postman login
+ *
+ * Clave: POSTMAN_API_KEY o ~/.komplian/postman-api-key (npx komplian postman login)
+ * Opcional: POSTMAN_WORKSPACE_ID, KOMPLIAN_EMAIL_DOMAIN, KOMPLIAN_POSTMAN_KEY_FILE
+ */
+
+import {
+  writeFileSync,
+  mkdirSync,
+  readFileSync,
+  existsSync,
+  chmodSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+
+const POSTMAN_API = "https://api.getpostman.com";
+
+const c = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+};
+
+function log(s = "") {
+  console.log(s);
+}
+
+function defaultKeyPath() {
+  const override = process.env.KOMPLIAN_POSTMAN_KEY_FILE?.trim();
+  if (override) return resolve(override);
+  return join(homedir(), ".komplian", "postman-api-key");
+}
+
+/**
+ * Orden: POSTMAN_API_KEY → ~/.komplian/postman-api-key (o KOMPLIAN_POSTMAN_KEY_FILE).
+ */
+function resolveApiKey() {
+  const env = process.env.POSTMAN_API_KEY?.trim();
+  if (env) return { key: env, source: "POSTMAN_API_KEY" };
+  const path = defaultKeyPath();
+  if (existsSync(path)) {
+    const k = readFileSync(path, "utf8").trim();
+    if (k) return { key: k, source: path };
+  }
+  return { key: "", source: null };
+}
+
+function printMissingKeyHelp() {
+  log(`${c.red}✗${c.reset} No hay API key de Postman.`);
+  log(``);
+  log(`  ${c.bold}Una vez por máquina:${c.reset}`);
+  log(`    ${c.cyan}npx komplian postman login${c.reset}`);
+  log(`    (pega la clave de Postman → Settings → API keys → Generate)`);
+  log(``);
+  log(`  ${c.dim}O en la sesión actual: export POSTMAN_API_KEY=…${c.reset}`);
+  log(
+    `${c.dim}  Archivo manual: ${defaultKeyPath()}${c.reset}`
+  );
+  process.exit(1);
+}
+
+function headers(apiKey) {
+  return {
+    "X-API-Key": apiKey,
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  };
+}
+
+async function pmFetch(apiKey, path, opts = {}) {
+  const url = path.startsWith("http") ? path : `${POSTMAN_API}${path}`;
+  const r = await fetch(url, {
+    ...opts,
+    headers: { ...headers(apiKey), ...opts.headers },
+  });
+  const text = await r.text();
+  let body;
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = { _raw: text };
+  }
+  return { ok: r.ok, status: r.status, body };
+}
+
+function extractEmail(meBody) {
+  const b = meBody ?? {};
+  const u = b.user ?? b.data?.user ?? b;
+  const e = u?.email ?? b.email ?? b.data?.email;
+  return typeof e === "string" ? e.trim().toLowerCase() : "";
+}
+
+function emailAllowed(email, domain) {
+  const d = domain.toLowerCase().replace(/^@/, "");
+  return email.endsWith(`@${d}`);
+}
+
+function req(name, method, path, auth = "apiKey") {
+  const h = [];
+  if (auth === "apiKey") {
+    h.push({ key: "X-API-Key", value: "{{apiKey}}", type: "text" });
+  } else if (auth === "admin") {
+    h.push({ key: "X-API-Key", value: "{{adminApiKey}}", type: "text" });
+  }
+  const raw = path.startsWith("http") ? path : `{{baseUrl}}${path}`;
+  return {
+    name,
+    request: {
+      method,
+      header: h,
+      url: raw,
+      description:
+        auth === "none"
+          ? "Sin cabecera X-API-Key (público)."
+          : auth === "admin"
+            ? "Cabecera X-API-Key con valor de adminApiKey."
+            : "Cabecera X-API-Key con valor de apiKey (workspace).",
+    },
+  };
+}
+
+function folder(name, items) {
+  return { name, item: items };
+}
+
+function buildCollection() {
+  return {
+    info: {
+      name: "Komplian API",
+      description:
+        "Colección generada por `npx komplian postman`. Variables: baseUrl, apiKey, adminApiKey, workspaceId, widgetId, sessionId, leadId, flowId, sourceId.",
+      schema:
+        "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+    },
+    item: [
+      folder("Health", [
+        req("Root", "GET", "/", "none"),
+        req("Health check", "GET", "/health", "none"),
+      ]),
+      folder("Public", [
+        req("Lead capture (web)", "POST", "/api/web/leads", "none"),
+      ]),
+      folder("Widget (Public)", [
+        req("Get widget config", "GET", "/api/widget/{{widgetId}}/config", "none"),
+        req("Create session", "POST", "/api/widget/{{widgetId}}/session", "none"),
+        req("Send message", "POST", "/api/widget/{{widgetId}}/message", "none"),
+        req("Get messages", "GET", "/api/widget/{{widgetId}}/messages/{{sessionId}}", "none"),
+        req("List sessions", "GET", "/api/widget/{{widgetId}}/sessions", "none"),
+      ]),
+      folder("Workspaces", [
+        req("List workspaces", "GET", "/api/workspaces", "apiKey"),
+        req("Get workspace", "GET", "/api/workspaces/{{workspaceId}}", "apiKey"),
+        req("Update workspace", "PUT", "/api/workspaces/{{workspaceId}}", "apiKey"),
+        req("Delete workspace", "DELETE", "/api/workspaces/{{workspaceId}}", "apiKey"),
+        req("Restore workspace", "POST", "/api/workspaces/{{workspaceId}}/restore", "apiKey"),
+        req("Regenerate API key", "POST", "/api/workspaces/{{workspaceId}}/api-key", "apiKey"),
+        req("Update logo", "PUT", "/api/workspaces/{{workspaceId}}/logo", "apiKey"),
+        req("Diagnostic", "GET", "/api/workspaces/{{workspaceId}}/diagnostic", "apiKey"),
+      ]),
+      folder("AI & Chat", [
+        req("AI chat", "POST", "/api/ai/chat", "apiKey"),
+        req("AI chat (stream)", "POST", "/api/ai/chat/stream", "apiKey"),
+        req("Test knowledge", "POST", "/api/ai/test-knowledge", "apiKey"),
+        req("Generate flow (AI)", "POST", "/api/ai/flows/generate", "apiKey"),
+      ]),
+      folder("Knowledge Base", [
+        req("Create source", "POST", "/api/knowledge/sources", "apiKey"),
+        req("List sources", "GET", "/api/knowledge/sources", "apiKey"),
+        req("Get source", "GET", "/api/knowledge/sources/{{sourceId}}", "apiKey"),
+        req("Update source", "PUT", "/api/knowledge/sources/{{sourceId}}", "apiKey"),
+        req("Delete source", "DELETE", "/api/knowledge/sources/{{sourceId}}", "apiKey"),
+        req("Scrape source", "POST", "/api/knowledge/sources/{{sourceId}}/scrape", "apiKey"),
+        req("Source jobs", "GET", "/api/knowledge/sources/{{sourceId}}/jobs", "apiKey"),
+        req("Search knowledge", "POST", "/api/knowledge/search", "apiKey"),
+        req("Knowledge stats", "GET", "/api/knowledge/stats", "apiKey"),
+        req("Upload document", "POST", "/api/knowledge/documents", "apiKey"),
+        req("Process document", "POST", "/api/knowledge/documents/{{documentId}}/process", "apiKey"),
+        req("Process document URL", "POST", "/api/knowledge/documents/{{documentId}}/process-url", "apiKey"),
+        req("Detect doc type", "GET", "/api/knowledge/documents/detect-type", "apiKey"),
+        req("Get manual entries", "GET", "/api/knowledge/manual/{{workspaceId}}", "apiKey"),
+        req("Create manual entry", "POST", "/api/knowledge/manual", "apiKey"),
+        req("Update manual entry", "PUT", "/api/knowledge/manual/{{entryId}}", "apiKey"),
+        req("Delete manual entry", "DELETE", "/api/knowledge/manual/{{entryId}}", "apiKey"),
+      ]),
+      folder("Widget Config", [
+        req("Get config", "GET", "/api/widget/config/{{workspaceId}}", "apiKey"),
+        req("Update config", "PUT", "/api/widget/config/{{workspaceId}}", "apiKey"),
+        req("Publish", "POST", "/api/widget/config/{{workspaceId}}/publish", "apiKey"),
+        req("Unpublish", "POST", "/api/widget/config/{{workspaceId}}/unpublish", "apiKey"),
+      ]),
+      folder("Inbox", [
+        req("List sessions", "GET", "/api/inbox/{{workspaceId}}/sessions", "apiKey"),
+        req("Get session", "GET", "/api/inbox/session/{{sessionId}}", "apiKey"),
+        req("Takeover", "POST", "/api/inbox/session/{{sessionId}}/takeover", "apiKey"),
+        req("Agent message", "POST", "/api/inbox/session/{{sessionId}}/message", "apiKey"),
+        req("Typing", "POST", "/api/inbox/session/{{sessionId}}/typing", "apiKey"),
+        req("Mark read", "POST", "/api/inbox/session/{{sessionId}}/read", "apiKey"),
+        req("Archive", "POST", "/api/inbox/session/{{sessionId}}/archive", "apiKey"),
+        req("Translate", "POST", "/api/inbox/session/{{sessionId}}/translate", "apiKey"),
+        req("Products for inbox", "GET", "/api/inbox/{{workspaceId}}/products", "apiKey"),
+      ]),
+      folder("Analytics", [
+        req("Knowledge analytics", "GET", "/api/analytics/knowledge/{{workspaceId}}", "apiKey"),
+        req("Query log", "GET", "/api/analytics/knowledge/{{workspaceId}}/queries", "apiKey"),
+        req("Knowledge gaps", "GET", "/api/analytics/knowledge/{{workspaceId}}/gaps", "apiKey"),
+        req("Query chunks", "GET", "/api/analytics/knowledge/query/{{queryId}}/chunks", "apiKey"),
+        req("AI analytics", "GET", "/api/analytics/ai/{{workspaceId}}", "apiKey"),
+      ]),
+      folder("Leads", [
+        req("List leads", "GET", "/api/leads", "apiKey"),
+        req("Create lead", "POST", "/api/leads", "apiKey"),
+        req("Get lead", "GET", "/api/leads/{{leadId}}", "apiKey"),
+        req("Update lead", "PATCH", "/api/leads/{{leadId}}", "apiKey"),
+        req("Delete lead", "DELETE", "/api/leads/{{leadId}}", "apiKey"),
+        req("Timeline", "GET", "/api/leads/{{leadId}}/timeline", "apiKey"),
+        req("Get notes", "GET", "/api/leads/{{leadId}}/notes", "apiKey"),
+        req("Add note", "POST", "/api/leads/{{leadId}}/notes", "apiKey"),
+        req("Lead stats", "GET", "/api/leads/stats/{{workspaceId}}", "apiKey"),
+      ]),
+      folder("Flows", [
+        req("List flows", "GET", "/api/flows", "apiKey"),
+        req("Create flow", "POST", "/api/flows", "apiKey"),
+        req("Flow templates", "GET", "/api/flows/templates", "apiKey"),
+        req("Get flow", "GET", "/api/flows/{{flowId}}", "apiKey"),
+        req("Update flow", "PATCH", "/api/flows/{{flowId}}", "apiKey"),
+        req("Delete flow", "DELETE", "/api/flows/{{flowId}}", "apiKey"),
+        req("Publish", "POST", "/api/flows/{{flowId}}/publish", "apiKey"),
+        req("Pause", "POST", "/api/flows/{{flowId}}/pause", "apiKey"),
+        req("Duplicate", "POST", "/api/flows/{{flowId}}/duplicate", "apiKey"),
+        req("Flow analytics", "GET", "/api/flows/{{flowId}}/analytics", "apiKey"),
+        req("Executions", "GET", "/api/flows/{{flowId}}/executions", "apiKey"),
+        req("Test flow", "POST", "/api/flows/{{flowId}}/test", "apiKey"),
+        req("Trigger event", "POST", "/api/flows/events", "apiKey"),
+        req("Cron (flows)", "POST", "/api/flows/cron", "apiKey"),
+      ]),
+      folder("Email", [req("Send email", "POST", "/api/email/send", "apiKey")]),
+      folder("Users & Plans", [
+        req("List users", "GET", "/api/users", "apiKey"),
+        req("Get user", "GET", "/api/users/{{userId}}", "apiKey"),
+        req("Plans", "GET", "/api/plans", "apiKey"),
+      ]),
+      folder("Webhooks", [
+        req("WhatsApp verify", "GET", "/webhooks/whatsapp", "none"),
+        req("WhatsApp", "POST", "/webhooks/whatsapp", "none"),
+        req("Instagram verify", "GET", "/webhooks/instagram", "none"),
+        req("Instagram", "POST", "/webhooks/instagram", "none"),
+        req("Shopify GDPR data_request", "POST", "/webhooks/shopify/customers/data_request", "none"),
+        req("Shopify GDPR customers/redact", "POST", "/webhooks/shopify/customers/redact", "none"),
+        req("Shopify GDPR shop/redact", "POST", "/webhooks/shopify/shop/redact", "none"),
+      ]),
+      folder("N8N", [
+        req("n8n healthz", "GET", "https://n8n.komplian.com/healthz", "none"),
+        {
+          name: "Lead pipeline webhook (info)",
+          request: {
+            method: "GET",
+            header: [],
+            url: "https://n8n.komplian.com/webhook/komplian-lead-pipeline",
+            description:
+              "POST real desde automatización; GET solo como referencia de URL en Postman.",
+          },
+        },
+      ]),
+    ],
+    variable: [
+      { key: "baseUrl", value: "https://api.komplian.com", type: "string" },
+    ],
+  };
+}
+
+function buildEnvironments() {
+  const secret = (key) => ({
+    key,
+    value: "",
+    type: "secret",
+    enabled: true,
+  });
+  const plain = (key, value) => ({
+    key,
+    value,
+    type: "default",
+    enabled: true,
+  });
+
+  const common = [
+    plain("baseUrl", ""),
+    secret("apiKey"),
+    secret("adminApiKey"),
+    plain("workspaceId", ""),
+    plain("widgetId", ""),
+    plain("sessionId", ""),
+    plain("leadId", ""),
+    plain("flowId", ""),
+    plain("sourceId", ""),
+    plain("documentId", ""),
+    plain("queryId", ""),
+    plain("userId", ""),
+    plain("entryId", ""),
+  ];
+
+  return [
+    {
+      name: "Komplian — Local Dev",
+      values: common.map((v) =>
+        v.key === "baseUrl"
+          ? { ...v, value: "http://localhost:4000", type: "default" }
+          : { ...v }
+      ),
+    },
+    {
+      name: "Komplian — Production",
+      values: common.map((v) =>
+        v.key === "baseUrl"
+          ? { ...v, value: "https://api.komplian.com", type: "default" }
+          : { ...v }
+      ),
+    },
+  ];
+}
+
+async function pickWorkspaceId(apiKey, explicit) {
+  if (explicit && explicit.trim()) return explicit.trim();
+  const { ok, body } = await pmFetch(apiKey, "/workspaces");
+  if (!ok || !body.workspaces?.length) {
+    log(`${c.red}✗${c.reset} No se pudieron listar workspaces. ¿API key válida?`);
+    process.exit(1);
+  }
+  const w =
+    body.workspaces.find((x) => x.type === "personal") || body.workspaces[0];
+  return w.id;
+}
+
+async function verifyKomplianEmail(apiKey, domain) {
+  const { ok, status, body } = await pmFetch(apiKey, "/me");
+  if (!ok) {
+    log(
+      `${c.red}✗${c.reset} API key de Postman inválida o sin acceso (${status}).`
+    );
+    process.exit(1);
+  }
+  const email = extractEmail(body);
+  if (!email) {
+    log(
+      `${c.red}✗${c.reset} La API de Postman no devolvió email en /me. Usa una cuenta Postman con email visible.`
+    );
+    process.exit(1);
+  }
+  if (!emailAllowed(email, domain)) {
+    log(
+      `${c.red}✗${c.reset} Este comando solo permite cuentas **@${domain}**. Sesión Postman: ${c.bold}${email}${c.reset}`
+    );
+    log(
+      `${c.dim}  Crea la API key desde una cuenta @${domain} o añade ese email a tu usuario en Postman.${c.reset}`
+    );
+    process.exit(1);
+  }
+  log(
+    `${c.green}✓${c.reset} Postman: ${c.bold}${email}${c.reset} (${c.dim}dominio permitido${c.reset})`
+  );
+  return email;
+}
+
+async function createCollection(apiKey, workspaceId, collection) {
+  const q = new URLSearchParams({ workspace: workspaceId });
+  return pmFetch(apiKey, `/collections?${q}`, {
+    method: "POST",
+    body: JSON.stringify({ collection }),
+  });
+}
+
+async function createEnvironment(apiKey, workspaceId, env) {
+  const q = new URLSearchParams({ workspace: workspaceId });
+  return pmFetch(apiKey, `/environments?${q}`, {
+    method: "POST",
+    body: JSON.stringify({ environment: env }),
+  });
+}
+
+function parseArgs(argv) {
+  const out = { yes: false, exportOnly: false, outDir: "", help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--yes" || a === "-y") out.yes = true;
+    else if (a === "--export-only") out.exportOnly = true;
+    else if (a === "--out") out.outDir = argv[++i] || "";
+    else if (a === "-h" || a === "--help") out.help = true;
+    else if (a.startsWith("-")) {
+      log(`${c.red}✗${c.reset} Opción desconocida: ${a}`);
+      process.exit(1);
+    }
+  }
+  return out;
+}
+
+function parseLoginArgs(argv) {
+  const out = { help: false };
+  for (const a of argv) {
+    if (a === "-h" || a === "--help") out.help = true;
+    else if (a.startsWith("-")) {
+      log(`${c.red}✗${c.reset} Opción desconocida: ${a}`);
+      process.exit(1);
+    }
+  }
+  return out;
+}
+
+function usage() {
+  log(`Uso: komplian postman [opciones]  |  komplian postman login`);
+  log(`  Clave: ${c.dim}POSTMAN_API_KEY${c.reset} o archivo ${c.dim}~/.komplian/postman-api-key${c.reset} (véase ${c.cyan}postman login${c.reset})`);
+  log(`  Dominio email: solo @komplian.com (GET /me)`);
+  log(``);
+  log(`  -y, --yes           Sin prompts extra`);
+  log(`  --export-only       Solo escribe JSON en disco (no llama a la API de Postman)`);
+  log(`  --out <dir>         Carpeta para export (por defecto: ./komplian-postman)`);
+  log(`  -h, --help`);
+  log(``);
+  log(`  Opcional: POSTMAN_WORKSPACE_ID, KOMPLIAN_EMAIL_DOMAIN, KOMPLIAN_POSTMAN_KEY_FILE`);
+}
+
+function usageLogin() {
+  log(`Uso: komplian postman login`);
+  log(`  Guarda la API key de Postman en ${c.dim}~/.komplian/postman-api-key${c.reset} (permiso 600).`);
+  log(`  Tras esto: ${c.cyan}npx komplian postman --yes${c.reset} sin exportar variables.`);
+  log(``);
+  log(`  Postman → Settings (avatar) → API keys → Generate`);
+}
+
+async function promptApiKey() {
+  if (input.isTTY) {
+    const rl = createInterface({ input, output });
+    const line = await rl.question(
+      `${c.cyan}Pega tu Postman API key${c.reset} (Settings → API keys): `
+    );
+    rl.close();
+    return line.trim();
+  }
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    input.on("data", (d) => chunks.push(d));
+    input.on("end", () => {
+      resolve(Buffer.concat(chunks).toString("utf8").trim());
+    });
+    input.on("error", reject);
+  });
+}
+
+async function runPostmanLogin(argv) {
+  const la = parseLoginArgs(argv);
+  if (la.help) {
+    usageLogin();
+    return;
+  }
+
+  log(`${c.cyan}━━ Postman login (Komplian) ━━${c.reset}`);
+  log(
+    `${c.dim}Cuenta con email @komplian.com. Genera la clave en Postman → Settings → API keys.${c.reset}`
+  );
+  log("");
+
+  const domain = (process.env.KOMPLIAN_EMAIL_DOMAIN || "komplian.com").trim();
+  const keyPath = defaultKeyPath();
+
+  let apiKey = await promptApiKey();
+  if (!apiKey) {
+    log(`${c.red}✗${c.reset} Clave vacía.`);
+    process.exit(1);
+  }
+
+  await verifyKomplianEmail(apiKey, domain);
+
+  mkdirSync(join(homedir(), ".komplian"), { recursive: true });
+  writeFileSync(keyPath, `${apiKey}\n`, { encoding: "utf8", mode: 0o600 });
+  try {
+    chmodSync(keyPath, 0o600);
+  } catch {
+    /* Windows puede ignorar chmod */
+  }
+
+  log("");
+  log(
+    `${c.green}✓${c.reset} Guardada en ${c.bold}${keyPath}${c.reset} (solo tu usuario).`
+  );
+  log(
+    `${c.dim}  Siguiente: ${c.reset}${c.cyan}npx komplian postman --yes${c.reset}`
+  );
+}
+
+function normalizePostmanArgv(argv) {
+  const a = [...argv];
+  if (a[0] === "login") {
+    return { mode: "login", rest: a.slice(1) };
+  }
+  return { mode: "sync", rest: a };
+}
+
+export async function runPostman(argv) {
+  const { mode, rest } = normalizePostmanArgv(argv);
+  if (mode === "login") {
+    await runPostmanLogin(rest);
+    return;
+  }
+
+  const args = parseArgs(rest);
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  const { key: apiKey, source } = resolveApiKey();
+  if (!apiKey) {
+    printMissingKeyHelp();
+  }
+  if (source && source !== "POSTMAN_API_KEY") {
+    log(`${c.dim}→ API key: ${source}${c.reset}`);
+  }
+
+  const domain = (process.env.KOMPLIAN_EMAIL_DOMAIN || "komplian.com").trim();
+  await verifyKomplianEmail(apiKey, domain);
+
+  const collection = buildCollection();
+  const envs = buildEnvironments();
+  const workspaceId = await pickWorkspaceId(
+    apiKey,
+    process.env.POSTMAN_WORKSPACE_ID
+  );
+  log(
+    `${c.green}✓${c.reset} Workspace Postman: ${c.bold}${workspaceId}${c.reset}`
+  );
+
+  const outBase = args.outDir
+    ? resolve(args.outDir)
+    : resolve(process.cwd(), "komplian-postman");
+  mkdirSync(outBase, { recursive: true });
+
+  const collPath = join(outBase, "Komplian-API.postman_collection.json");
+  writeFileSync(collPath, JSON.stringify(collection, null, 2), "utf8");
+  log(`${c.green}✓${c.reset} Export: ${c.dim}${collPath}${c.reset}`);
+
+  for (const env of envs) {
+    const safe = env.name.replace(/[\\/]/g, "-") + ".postman_environment.json";
+    writeFileSync(join(outBase, safe), JSON.stringify({ ...env }, null, 2), "utf8");
+    log(`${c.green}✓${c.reset} Export: ${c.dim}${join(outBase, safe)}${c.reset}`);
+  }
+
+  if (args.exportOnly) {
+    log("");
+    log(
+      `${c.cyan}━━ Listo (solo archivos) ━━${c.reset} Importa en Postman: ${c.bold}Import${c.reset} → arrastra la carpeta o los JSON.`
+    );
+    return;
+  }
+
+  log("");
+  log(`${c.cyan}━━ Subiendo a Postman (API) ━━${c.reset}`);
+
+  const cr = await createCollection(apiKey, workspaceId, collection);
+  if (!cr.ok) {
+    log(
+      `${c.yellow}○${c.reset} Colección API: ${cr.status} — ${JSON.stringify(cr.body).slice(0, 400)}`
+    );
+    log(
+      `${c.dim}  Si el nombre ya existe, borra la colección antigua en Postman o importa el JSON exportado.${c.reset}`
+    );
+  } else {
+    const uid = cr.body?.collection?.uid || cr.body?.collection?.id || "?";
+    log(`${c.green}✓${c.reset} Colección creada en Postman (${uid})`);
+  }
+
+  for (const env of envs) {
+    const er = await createEnvironment(apiKey, workspaceId, {
+      name: env.name,
+      values: env.values,
+    });
+    if (!er.ok) {
+      log(
+        `${c.yellow}○${c.reset} Entorno "${env.name}": ${er.status} — ${JSON.stringify(er.body).slice(0, 200)}`
+      );
+    } else {
+      log(`${c.green}✓${c.reset} Entorno: ${c.bold}${env.name}${c.reset}`);
+    }
+  }
+
+  log("");
+  log(`${c.green}✓${c.reset} Abre Postman → workspace → revisa ${c.bold}Komplian API${c.reset} y los entornos.`);
+  log(
+    `${c.dim}  Rellena apiKey / adminApiKey / IDs en el entorno (secret).${c.reset}`
+  );
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "komplian",
-  "version": "0.3.8",
-  "description": "Komplian developer workspace setup: GitHub CLI (browser login) + git clone by team. Node 18+, git, gh — no OAuth App to register.",
+  "version": "0.4.1",
+  "description": "Komplian developer workspace: GitHub clone (onboard) + Postman collection/environments (postman). Node 18+.",
   "type": "module",
   "engines": {
     "node": ">=18"
@@ -11,6 +11,7 @@
   },
   "files": [
     "komplian-onboard.mjs",
+    "komplian-postman.mjs",
     "komplian-team-repos.json",
     "README.md"
   ],
@@ -18,7 +19,7 @@
     "access": "public"
   },
   "scripts": {
-    "prepublishOnly": "node --check komplian-onboard.mjs"
+    "prepublishOnly": "node --check komplian-onboard.mjs && node --check komplian-postman.mjs"
   },
   "keywords": [
     "komplian",