komplian 0.3.7 → 0.4.0

package/README.md

@@ -6,8 +6,24 @@
 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. En la terminal:
+
+```bash
+export POSTMAN_API_KEY=pmak-…
+npx komplian postman --yes
+```
+
+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** (carpetas como en el workspace interno), los entornos **Komplian — Local Dev** y **Komplian — Production** (variables `baseUrl`, `apiKey`, `adminApiKey`, IDs, etc.), y deja copia en `./komplian-postman/*.json` por si hace falta importar a mano.
+
+- Solo exportar archivos (sin subir por API): `npx komplian postman --yes --export-only`
+- Otro workspace: `POSTMAN_WORKSPACE_ID=<id>` (si no, se usa un workspace por defecto con permiso de escritura)
+
 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.  
-**npm install** runs with `--no-audit --no-fund` unless `KOMPLIAN_NPM_AUDIT=1`. Run `npm audit` in each repo when you work on it.
+**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`.
 
 **Maintainers:** publish from **`scripts/`** (folder with `package.json`), not the monorepo root:
 

package/komplian-onboard.mjs

@@ -304,36 +304,99 @@ function copyCursorPack(workspace, cursorRepoUrl) {
   );
 }
 
-function npmInstallEach(workspace) {
-  log("");
-  log(`${c.cyan}━━ npm install por repo ━━${c.reset}`);
-  if (!canRun("npm", ["--version"])) {
-    log(`${c.yellow}○${c.reset} npm no está en PATH — omito installs`);
-    return;
-  }
+/** Sin esto, `npm install` crea o retoca package-lock.json y git muestra cambios sin querer. */
+function npmQuietFlags() {
   const audit =
     process.env.KOMPLIAN_NPM_AUDIT === "1" || process.env.KOMPLIAN_NPM_AUDIT === "true";
-  const installArgs = audit
-    ? ["install"]
-    : ["install", "--no-audit", "--no-fund"];
+  return audit ? [] : ["--no-audit", "--no-fund"];
+}
+
+function npmInstallOneRepo(dir, name) {
+  const pkg = join(dir, "package.json");
+  if (!existsSync(pkg)) return { ok: true, skipped: true };
+
+  const yarnLock = join(dir, "yarn.lock");
+  const pnpmLock = join(dir, "pnpm-lock.yaml");
+  const npmLock = join(dir, "package-lock.json");
+
+  if (existsSync(yarnLock)) {
+    if (!canRun("yarn", ["--version"])) {
+      log(
+        `${c.yellow}○${c.reset} ${name} ${c.dim}(yarn.lock; instala yarn o ejecuta yarn install a mano)${c.reset}`
+      );
+      return { ok: true, skipped: true };
+    }
+    log(`${c.dim}→${c.reset} ${name} ${c.dim}(yarn)${c.reset}`);
+    const r = spawnSync(
+      "yarn",
+      ["install", "--frozen-lockfile"],
+      spawnWin({ cwd: dir, stdio: "inherit" })
+    );
+    return { ok: r.status === 0, skipped: false };
+  }
+
+  if (existsSync(pnpmLock)) {
+    if (!canRun("pnpm", ["--version"])) {
+      log(
+        `${c.yellow}○${c.reset} ${name} ${c.dim}(pnpm-lock; instala pnpm o pnpm install a mano)${c.reset}`
+      );
+      return { ok: true, skipped: true };
+    }
+    log(`${c.dim}→${c.reset} ${name} ${c.dim}(pnpm)${c.reset}`);
+    const r = spawnSync(
+      "pnpm",
+      ["install", "--frozen-lockfile"],
+      spawnWin({ cwd: dir, stdio: "inherit" })
+    );
+    return { ok: r.status === 0, skipped: false };
+  }
+
+  if (!canRun("npm", ["--version"])) {
+    log(`${c.yellow}○${c.reset} npm no está en PATH — omito ${name}`);
+    return { ok: true, skipped: true };
+  }
+
+  const quiet = npmQuietFlags();
+
+  if (existsSync(npmLock)) {
+    log(`${c.dim}→${c.reset} ${name} ${c.dim}(npm ci — lock sin cambios)${c.reset}`);
+    const r = spawnSync("npm", ["ci", ...quiet], spawnWin({ cwd: dir, stdio: "inherit" }));
+    if (r.status === 0) return { ok: true, skipped: false };
+    log(
+      `${c.yellow}○${c.reset} ${name}: npm ci falló (¿lock desincronizado?). ${c.dim}Revisa con npm install en ese repo.${c.reset}`
+    );
+    return { ok: false, skipped: false };
+  }
+
+  log(`${c.dim}→${c.reset} ${name} ${c.dim}(npm install — sin crear package-lock)${c.reset}`);
+  const r = spawnSync(
+    "npm",
+    ["install", ...quiet, "--no-package-lock"],
+    spawnWin({ cwd: dir, stdio: "inherit" })
+  );
+  return { ok: r.status === 0, skipped: false };
+}
+
+function npmInstallEach(workspace) {
+  log("");
+  log(`${c.cyan}━━ Dependencias por repo ━━${c.reset}`);
   for (const ent of readdirSync(workspace)) {
     const d = join(workspace, ent);
     if (!statSync(d).isDirectory()) continue;
-    const pkg = join(d, "package.json");
-    if (!existsSync(pkg)) continue;
-    log(`${c.dim}→${c.reset} ${ent}`);
-    const ir = spawnSync("npm", installArgs, spawnWin({ cwd: d, stdio: "inherit" }));
-    if (ir.status !== 0) {
-      log(`${c.yellow}○${c.reset} npm install con avisos en ${ent}`);
-    } else {
+    const { ok, skipped } = npmInstallOneRepo(d, ent);
+    if (skipped) continue;
+    if (ok) {
       log(`${c.green}✓${c.reset} ${ent}`);
+    } else {
+      log(`${c.yellow}○${c.reset} ${ent}`);
     }
   }
 }
 
 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 --yes   ${c.dim}(POSTMAN_API_KEY + 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)`);
@@ -416,8 +479,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;
@@ -521,7 +591,7 @@ async function main() {
   }
   log(`${c.green}✓${c.reset} Cursor: ${c.bold}File → Open Folder → ${abs}${c.reset}`);
   log(
-    `${c.dim}  npm install usa --no-audit --no-fund (menos ruido). Auditoría: cd cada repo y npm audit. KOMPLIAN_NPM_AUDIT=1 para resumen completo.${c.reset}`
+    `${c.dim}  Con package-lock.json: npm ci (no retoca el lock). Sin lock: npm install --no-package-lock. yarn/pnpm: lock congelado. KOMPLIAN_NPM_AUDIT=1 activa auditoría en npm.${c.reset}`
   );
   log(`${c.dim}  .env.example → .env por proyecto; secretos en 1Password — nunca commit.${c.reset}`);
 }

package/komplian-postman.mjs

@@ -0,0 +1,466 @@
+#!/usr/bin/env node
+/**
+ * Komplian Postman — API key + email @komplian.com (Postman /me), luego colección + entornos.
+ *
+ * Requisitos: Node 18+, variable POSTMAN_API_KEY (Postman → Settings → API keys)
+ *
+ *   export POSTMAN_API_KEY=pmak-...
+ *   npx komplian postman --yes
+ *
+ * Opcional: POSTMAN_WORKSPACE_ID (si no, usa el primer workspace con permiso de escritura)
+ * Opcional: KOMPLIAN_EMAIL_DOMAIN=komplian.com (solo para pruebas internas del script)
+ */
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+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 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} POSTMAN_API_KEY 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 usage() {
+  log(`Uso: komplian postman [opciones]`);
+  log(`  ${c.dim}POSTMAN_API_KEY${c.reset}   Obligatoria (Postman → Settings → API keys)`);
+  log(`  ${c.dim}Dominio email${c.reset}      Solo cuentas @komplian.com (verificado vía GET /me)`);
+  log(``);
+  log(`  -y, --yes           Sin confirmaciones interactivas`);
+  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 (defecto: komplian.com)`);
+}
+
+export async function runPostman(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  const apiKey = process.env.POSTMAN_API_KEY?.trim();
+  if (!apiKey) {
+    log(`${c.red}✗${c.reset} Falta ${c.bold}POSTMAN_API_KEY${c.reset} en el entorno.`);
+    log(
+      `${c.dim}  Postman → Settings (avatar) → API keys → Generate.${c.reset}`
+    );
+    process.exit(1);
+  }
+
+  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.7",
-  "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.0",
+  "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",