@klevar/portal-cli 0.1.0

package/.portal.env.example

@@ -0,0 +1,3 @@
+PORTAL_API_URL=http://127.0.0.1:3100
+PORTAL_API_KEY=cmp_live_replace_me
+PORTAL_TOKEN=

package/README.md

@@ -0,0 +1,100 @@
+# @klevar/portal-cli
+
+First-class npm CLI for the Klevar Client Management Portal.
+
+## Install
+
+Run without installing:
+
+```bash
+npx klevar-portal help
+```
+
+Install globally for repeated use:
+
+```bash
+npm install -g @klevar/portal-cli
+klevar-portal help
+```
+
+## Configuration
+
+Configuration is read from environment variables or `~/.klevar/portal.env`.
+
+```env
+PORTAL_API_URL=https://api.klevar.ai
+PORTAL_API_KEY=cmp_live_replace_me
+PORTAL_TOKEN=
+```
+
+`PORTAL_API_URL` defaults to `http://127.0.0.1:3100` for local development. Use `PORTAL_TOKEN` only for client portal commands.
+
+Do not paste API keys, portal tokens, or production secrets into chat logs, issue trackers, screenshots, or committed files.
+
+## Command Examples
+
+```bash
+npx klevar-portal health
+npx klevar-portal tenant info
+npx klevar-portal clients list
+npx klevar-portal clients create --name "Stefan" --email "stefan@example.de" --platform direct
+npx klevar-portal projects create <clientId> --name "Idealo" --externalRef "idealo:ksh.de"
+npx klevar-portal metrics push --external_ref "idealo:ksh.de" --source_ref "run:33" --snapshot_date "2026-04-12" --metrics '{"score":88}'
+npx klevar-portal portal me --portal-token "<client-token>"
+```
+
+## Brain Usage
+
+Brain usage should prefer the published `npx klevar-portal` entrypoint.
+
+Brain agents should call:
+
+```bash
+npx klevar-portal <resource> <action> [id] [--key value]
+```
+
+The local compatibility wrapper remains available for old automation after a build:
+
+```bash
+npm run cli:build
+node tools/client.js clients list
+```
+
+New automation should use `npx klevar-portal`.
+
+## Auth Modes
+
+- Admin and integration commands use `X-API-Key`.
+- Portal commands use `PORTAL_TOKEN` or `--portal-token`.
+- Public commands such as health checks and onboarding submission do not require credentials.
+
+Explicit no-CLI exemptions are tracked in `tools/commands/_exemptions.ts`:
+
+- `POST /api/admin/login`, `POST /api/admin/logout`, and `GET /api/admin/me` are browser/session-only routes.
+- `POST /api/tenants/register` is public bootstrap/self-registration, not a normal operational CLI action.
+- `POST /api/integration/klevar-docs/events` is an inbound webhook called by Klevar Docs.
+
+## npm Release Flow
+
+The npm release flow is automated in GitHub Actions and can be dry-run locally.
+
+Dry-run locally:
+
+```bash
+npm run cli:publish:dry
+```
+
+Manual publish:
+
+```bash
+npm run cli:publish
+```
+
+GitHub Actions also provides:
+
+- `.github/workflows/auto-publish-cli.yml`: publishes from `main` when `tools/**` changes.
+- `.github/workflows/publish-cli.yml`: manual or `portal-cli-v*.*.*` tag fallback.
+
+## Security Notes
+
+Do not paste API keys into shell history on shared machines. Prefer `~/.klevar/portal.env` with user-only file permissions or a secret manager. Rotate a key immediately if it appears in logs or commits.

package/dist/bin/klevar-portal.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/klevar-portal.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// @ts-expect-error legacy JavaScript execution engine is copied during post-build.
+await import('../lib/legacy-runner.js');
+export {};
+//# sourceMappingURL=klevar-portal.js.map

package/dist/bin/klevar-portal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"klevar-portal.js","sourceRoot":"","sources":["../../bin/klevar-portal.ts"],"names":[],"mappings":";AAEA,mFAAmF;AACnF,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC"}

package/dist/commands/_exemptions.d.ts

@@ -0,0 +1,31 @@
+export declare const CLI_EXEMPTIONS: readonly [{
+    readonly method: "POST";
+    readonly path: "/api/admin/login";
+    readonly reason: "Browser/session-only authentication route. The CLI uses API key auth.";
+    readonly owner: "Klevar Portal";
+    readonly trackedAs: "Phase 17 browser/session-only exemption";
+}, {
+    readonly method: "POST";
+    readonly path: "/api/admin/logout";
+    readonly reason: "Browser/session-only authentication route. The CLI uses API key auth.";
+    readonly owner: "Klevar Portal";
+    readonly trackedAs: "Phase 17 browser/session-only exemption";
+}, {
+    readonly method: "GET";
+    readonly path: "/api/admin/me";
+    readonly reason: "Session identity route is browser-only in the modular CLI contract; tenant.info covers API key identity.";
+    readonly owner: "Klevar Portal";
+    readonly trackedAs: "Phase 17 browser/session-only exemption";
+}, {
+    readonly method: "POST";
+    readonly path: "/api/tenants/register";
+    readonly reason: "Public tenant self-registration is an installation/bootstrap capability, not an operational CLI action.";
+    readonly owner: "Klevar Portal";
+    readonly trackedAs: "Phase 17 public-bootstrap exemption";
+}, {
+    readonly method: "POST";
+    readonly path: "/api/integration/klevar-docs/events";
+    readonly reason: "Inbound webhook consumer called by Klevar Docs, not by operators or clients.";
+    readonly owner: "Klevar Docs";
+    readonly trackedAs: "Phase 17 inbound-webhook exemption";
+}];

package/dist/commands/_exemptions.js

@@ -0,0 +1,38 @@
+export const CLI_EXEMPTIONS = [
+    {
+        method: 'POST',
+        path: '/api/admin/login',
+        reason: 'Browser/session-only authentication route. The CLI uses API key auth.',
+        owner: 'Klevar Portal',
+        trackedAs: 'Phase 17 browser/session-only exemption',
+    },
+    {
+        method: 'POST',
+        path: '/api/admin/logout',
+        reason: 'Browser/session-only authentication route. The CLI uses API key auth.',
+        owner: 'Klevar Portal',
+        trackedAs: 'Phase 17 browser/session-only exemption',
+    },
+    {
+        method: 'GET',
+        path: '/api/admin/me',
+        reason: 'Session identity route is browser-only in the modular CLI contract; tenant.info covers API key identity.',
+        owner: 'Klevar Portal',
+        trackedAs: 'Phase 17 browser/session-only exemption',
+    },
+    {
+        method: 'POST',
+        path: '/api/tenants/register',
+        reason: 'Public tenant self-registration is an installation/bootstrap capability, not an operational CLI action.',
+        owner: 'Klevar Portal',
+        trackedAs: 'Phase 17 public-bootstrap exemption',
+    },
+    {
+        method: 'POST',
+        path: '/api/integration/klevar-docs/events',
+        reason: 'Inbound webhook consumer called by Klevar Docs, not by operators or clients.',
+        owner: 'Klevar Docs',
+        trackedAs: 'Phase 17 inbound-webhook exemption',
+    }
+];
+//# sourceMappingURL=_exemptions.js.map

package/dist/commands/_exemptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_exemptions.js","sourceRoot":"","sources":["../../commands/_exemptions.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B;QACE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,kBAAkB;QACxB,MAAM,EAAE,uEAAuE;QAC/E,KAAK,EAAE,eAAe;QACtB,SAAS,EAAE,yCAAyC;KACrD;IACD;QACE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,mBAAmB;QACzB,MAAM,EAAE,uEAAuE;QAC/E,KAAK,EAAE,eAAe;QACtB,SAAS,EAAE,yCAAyC;KACrD;IACD;QACE,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,0GAA0G;QAClH,KAAK,EAAE,eAAe;QACtB,SAAS,EAAE,yCAAyC;KACrD;IACD;QACE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,uBAAuB;QAC7B,MAAM,EAAE,yGAAyG;QACjH,KAAK,EAAE,eAAe;QACtB,SAAS,EAAE,qCAAqC;KACjD;IACD;QACE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,qCAAqC;QAC3C,MAAM,EAAE,8EAA8E;QACtF,KAAK,EAAE,aAAa;QACpB,SAAS,EAAE,oCAAoC;KAChD;CACO,CAAC"}

package/dist/commands/clients.d.ts

@@ -0,0 +1,98 @@
+export declare const clientCommands: {
+    'clients.tags': {
+        method: "GET";
+        path: string;
+        auth: "apiKey";
+        description: string;
+    };
+    'clients.list': {
+        method: "GET";
+        path: string;
+        auth: "apiKey";
+        description: string;
+        queryParams: string[];
+    };
+    'clients.create': {
+        method: "POST";
+        path: string;
+        auth: "apiKey";
+        description: string;
+        body: string[];
+    };
+    'clients.get': {
+        method: "GET";
+        path: string;
+        auth: "apiKey";
+        description: string;
+    };
+    'clients.update': {
+        method: "PATCH";
+        path: string;
+        auth: "apiKey";
+        description: string;
+        body: string[];
+    };
+    'clients.delete': {
+        method: "DELETE";
+        path: string;
+        auth: "apiKey";
+        description: string;
+    };
+    'clients.purge': {
+        method: "DELETE";
+        path: string;
+        auth: "apiKey";
+        description: string;
+        fixedQuery: {
+            hard: string;
+        };
+    };
+    'clients.go-live': {
+        method: "PATCH";
+        path: string;
+        auth: "apiKey";
+        description: string;
+        fixedBody: {
+            notificationsEnabled: boolean;
+        };
+    };
+    'clients.mute': {
+        method: "PATCH";
+        path: string;
+        auth: "apiKey";
+        description: string;
+        fixedBody: {
+            notificationsEnabled: boolean;
+        };
+    };
+    'clients.rotate-token': {
+        method: "POST";
+        path: string;
+        auth: "apiKey";
+        description: string;
+    };
+    'token.rotate': {
+        method: "POST";
+        path: string;
+        auth: "apiKey";
+        description: string;
+    };
+    'clients.docs-sync': {
+        method: "POST";
+        path: string;
+        auth: "apiKey";
+        description: string;
+    };
+    'clients.docs-invoices': {
+        method: "GET";
+        path: string;
+        auth: "apiKey";
+        description: string;
+    };
+    'clients.docs-documents': {
+        method: "GET";
+        path: string;
+        auth: "apiKey";
+        description: string;
+    };
+};

package/dist/commands/clients.js

@@ -0,0 +1,17 @@
+export const clientCommands = {
+    'clients.tags': { method: 'GET', path: '/api/admin/clients/tags', auth: 'apiKey', description: 'List client tags' },
+    'clients.list': { method: 'GET', path: '/api/admin/clients', auth: 'apiKey', description: 'List clients', queryParams: ['status', 'platform', 'tier', 'tag'] },
+    'clients.create': { method: 'POST', path: '/api/admin/clients', auth: 'apiKey', description: 'Create a client', body: ['name', 'email', 'company', 'phone', 'platform', 'platformId', 'tier', 'currency', 'notes', 'tags'] },
+    'clients.get': { method: 'GET', path: '/api/admin/clients/:id', auth: 'apiKey', description: 'Get a client' },
+    'clients.update': { method: 'PATCH', path: '/api/admin/clients/:id', auth: 'apiKey', description: 'Update a client', body: ['name', 'email', 'company', 'phone', 'platform', 'platformId', 'status', 'tier', 'currency', 'notes', 'tags', 'notificationsEnabled'] },
+    'clients.delete': { method: 'DELETE', path: '/api/admin/clients/:id', auth: 'apiKey', description: 'Delete or churn a client' },
+    'clients.purge': { method: 'DELETE', path: '/api/admin/clients/:id', auth: 'apiKey', description: 'Hard-delete client and related data', fixedQuery: { hard: 'true' } },
+    'clients.go-live': { method: 'PATCH', path: '/api/admin/clients/:id', auth: 'apiKey', description: 'Enable notifications', fixedBody: { notificationsEnabled: true } },
+    'clients.mute': { method: 'PATCH', path: '/api/admin/clients/:id', auth: 'apiKey', description: 'Disable notifications', fixedBody: { notificationsEnabled: false } },
+    'clients.rotate-token': { method: 'POST', path: '/api/admin/clients/:id/rotate-token', auth: 'apiKey', description: 'Rotate portal token' },
+    'token.rotate': { method: 'POST', path: '/api/admin/clients/:id/rotate-token', auth: 'apiKey', description: 'Rotate portal token' },
+    'clients.docs-sync': { method: 'POST', path: '/api/admin/clients/:id/docs-sync', auth: 'apiKey', description: 'Sync client to Docs' },
+    'clients.docs-invoices': { method: 'GET', path: '/api/admin/clients/:id/docs/invoices', auth: 'apiKey', description: 'List client invoices' },
+    'clients.docs-documents': { method: 'GET', path: '/api/admin/clients/:id/docs/documents', auth: 'apiKey', description: 'List client documents' },
+};
+//# sourceMappingURL=clients.js.map

package/dist/commands/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../../commands/clients.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,cAAc,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE;IACnH,cAAc,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;IAC9J,gBAAgB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE;IAC5N,aAAa,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;IAC7G,gBAAgB,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,sBAAsB,CAAC,EAAE;IACnQ,gBAAgB,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0BAA0B,EAAE;IAC/H,eAAe,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qCAAqC,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;IACvK,iBAAiB,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE,SAAS,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,EAAE;IACtK,cAAc,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uBAAuB,EAAE,SAAS,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,EAAE;IACrK,sBAAsB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qCAAqC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE;IAC3I,cAAc,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qCAAqC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE;IACnI,mBAAmB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kCAAkC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE;IACrI,uBAAuB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sCAAsC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE;IAC7I,wBAAwB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,uCAAuC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uBAAuB,EAAE;CAC1H,CAAC"}

package/dist/commands/docs.d.ts

@@ -0,0 +1,16 @@
+export declare const docsCommands: {
+    'docs.document-download': {
+        method: "DOWNLOAD";
+        path: string;
+        auth: "apiKey";
+        description: string;
+        body: string[];
+    };
+    'docs.invoice-download': {
+        method: "DOWNLOAD";
+        path: string;
+        auth: "apiKey";
+        description: string;
+        body: string[];
+    };
+};

package/dist/commands/docs.js

@@ -0,0 +1,5 @@
+export const docsCommands = {
+    'docs.document-download': { method: 'DOWNLOAD', path: '/api/admin/docs/documents/:id/download', auth: 'apiKey', description: 'Download document', body: ['output'] },
+    'docs.invoice-download': { method: 'DOWNLOAD', path: '/api/admin/docs/invoices/:id/download', auth: 'apiKey', description: 'Download invoice', body: ['output'] },
+};
+//# sourceMappingURL=docs.js.map

package/dist/commands/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../commands/docs.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,wBAAwB,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,wCAAwC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE;IACpK,uBAAuB,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,uCAAuC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE;CAC3I,CAAC"}