@quadrokit/client 0.2.4 → 0.2.6

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
-import { defaultLoginUrlFromCatalogUrl, fetch4DAdminSessionCookie, } from './generate/catalog-session.mjs';
+import { catalogFetchInit, defaultLoginUrlFromCatalogUrl, fetch4DAdminSessionCookie, vLog, wrapFetchError, } from './generate/catalog-session.mjs';
 import { writeGenerated } from './generate/codegen.mjs';
 import { applyGenerateDotenv } from './generate/dotenv-cwd.mjs';
 function parseArgs(argv) {
@@ -11,6 +11,8 @@ function parseArgs(argv) {
     let accessKey;
     let loginUrl;
     let out = '.quadrokit/generated';
+    let verbose = false;
+    let insecureTls = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--url' && argv[i + 1]) {
@@ -28,16 +30,36 @@ function parseArgs(argv) {
         else if (a === '--out' && argv[i + 1]) {
             out = argv[++i];
         }
+        else if (a === '--verbose' || a === '-v') {
+            verbose = true;
+        }
+        else if (a === '--insecure-tls') {
+            insecureTls = true;
+        }
         else if (!a.startsWith('-') && !command) {
             command = a;
         }
     }
-    return { command, url, token, accessKey, loginUrl, out };
+    return { command, url, token, accessKey, loginUrl, out, verbose, insecureTls };
+}
+function envFlag(name) {
+    const v = process.env[name]?.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes';
 }
-async function loadCatalog(url, auth) {
+function buildDebug(parsed) {
+    return {
+        verbose: parsed.verbose || envFlag('QUADROKIT_GENERATE_VERBOSE'),
+        insecureTls: parsed.insecureTls || envFlag('QUADROKIT_INSECURE_TLS'),
+    };
+}
+async function loadCatalog(url, auth, debug) {
+    vLog(debug, '🦙', 'QuadroKit catalog generate', 'Loading catalog…');
+    vLog(debug, '📍', 'Catalog URL', url);
     if (url.startsWith('file:')) {
-        const path = fileURLToPath(url);
-        const text = await readFile(path, 'utf8');
+        const p = fileURLToPath(url);
+        vLog(debug, '📂', 'Local file', p);
+        const text = await readFile(p, 'utf8');
+        vLog(debug, '✅', 'Catalog JSON', `Read ${text.length} bytes from disk`);
         return JSON.parse(text);
     }
     const headers = {
@@ -49,29 +71,43 @@ async function loadCatalog(url, auth) {
         if (!login) {
             try {
                 login = defaultLoginUrlFromCatalogUrl(url);
+                vLog(debug, '🔗', 'Derived login URL', login);
             }
             catch {
                 throw new Error('quadrokit: --access-key requires an http(s) catalog --url, or pass --login-url');
             }
         }
-        headers.Cookie = await fetch4DAdminSessionCookie(login, key);
+        headers.Cookie = await fetch4DAdminSessionCookie(login, key, debug);
     }
     else if (auth?.token) {
-        headers.Authorization = `Bearer ${auth.token}`;
+        vLog(debug, '🔒', 'Catalog auth', 'Authorization: Bearer (token set)');
+    }
+    else {
+        vLog(debug, '🔓', 'Catalog auth', 'No access key or bearer token');
     }
-    const res = await fetch(url, { headers });
+    const extra = catalogFetchInit(debug);
+    let res;
+    try {
+        res = await fetch(url, { headers, ...extra });
+    }
+    catch (e) {
+        throw wrapFetchError('Catalog fetch', e, debug);
+    }
+    vLog(debug, '📥', 'Catalog HTTP', `${res.status} ${res.statusText}`);
     if (!res.ok) {
         const t = await res.text();
         throw new Error(`Failed to fetch catalog (${res.status}): ${t.slice(0, 500)}`);
     }
-    return res.json();
+    const catalog = (await res.json());
+    vLog(debug, '✅', 'Catalog JSON', 'Parsed — writing generated files…');
+    return catalog;
 }
 async function main() {
     const argv = process.argv.slice(2);
     const parsed = parseArgs(argv);
     const { command, token, accessKey: accessKeyArg, loginUrl: loginUrlArg, out } = parsed;
     if (command !== 'generate') {
-        console.error(`Usage: quadrokit-client generate [--url <catalog_url>] [auth] [--out <dir>]
+        console.error(`Usage: quadrokit-client generate [--url <catalog_url>] [auth] [options] [--out <dir>]
 
   --url defaults to \${VITE_4D_ORIGIN}/rest/\\$catalog (from env or .env in cwd), else http://127.0.0.1:7080/rest/\\$catalog
 
@@ -80,11 +116,16 @@ Auth (generator only; not used by the app runtime):
   --login-url <url>    Full login URL (default: {catalog origin}/api/login)
   --token <secret>     Authorization: Bearer (when you do not use --access-key)
 
-Env / .env: VITE_4D_ORIGIN, QUADROKIT_ACCESS_KEY, QUADROKIT_LOGIN_URL, QUADROKIT_CATALOG_TOKEN
+Debug / TLS:
+  -v, --verbose        Friendly step-by-step logs (emojis) on stderr
+  --insecure-tls       Skip TLS certificate verification (dev/self-signed HTTPS only)
+
+Env / .env: VITE_4D_ORIGIN, QUADROKIT_ACCESS_KEY, QUADROKIT_LOGIN_URL, QUADROKIT_CATALOG_TOKEN,
+            QUADROKIT_GENERATE_VERBOSE, QUADROKIT_INSECURE_TLS (set to 1 / true / yes)
 
 Examples:
-  quadrokit-client generate
-  quadrokit-client generate --url https://localhost:7443/rest/\\$catalog --access-key MY_TOKEN
+  quadrokit-client generate -v
+  quadrokit-client generate --url https://localhost:7443/rest/\\$catalog --access-key MY_TOKEN --insecure-tls -v
   quadrokit-client generate --url http://localhost:7080/rest/\\$catalog --token secret
   quadrokit-client generate --url file://./assets/catalog.json --out .quadrokit/generated
 
@@ -93,6 +134,7 @@ Examples:
         process.exit(1);
     }
     applyGenerateDotenv();
+    const debug = buildDebug(parsed);
     let url = parsed.url;
     if (!url) {
         const origin = (process.env.VITE_4D_ORIGIN || 'http://127.0.0.1:7080').replace(/\/$/, '');
@@ -105,9 +147,14 @@ Examples:
         accessKey,
         loginUrl,
         token: accessKey ? undefined : bearer,
-    });
+    }, debug);
     await writeGenerated(out, catalog);
-    console.error(`Wrote generated client to ${out}`);
+    if (debug.verbose) {
+        vLog(debug, '🎉', 'All set', `Generated client → ${out}`);
+    }
+    else {
+        console.error(`Wrote generated client to ${out}`);
+    }
 }
 main().catch((e) => {
     console.error(e);

package/dist/generate/catalog-session.d.ts

@@ -2,6 +2,17 @@
  * Generator-only: obtain `4DAdminSID` via POST `/api/login` (multipart `accessKey`).
  * Not used by the runtime REST client.
  */
+import { Agent } from 'undici';
+export type CatalogHttpDebug = {
+    verbose?: boolean;
+    /** Accept self-signed / invalid TLS (generator CLI only — never for production apps). */
+    insecureTls?: boolean;
+};
+export declare function catalogFetchInit(debug: CatalogHttpDebug | undefined): {
+    dispatcher: Agent;
+} | Record<string, never>;
+export declare function vLog(debug: CatalogHttpDebug | undefined, emoji: string, title: string, detail?: string): void;
 export declare function defaultLoginUrlFromCatalogUrl(catalogUrl: string): string;
-export declare function fetch4DAdminSessionCookie(loginUrl: string, accessKey: string): Promise<string>;
+export declare function fetch4DAdminSessionCookie(loginUrl: string, accessKey: string, debug?: CatalogHttpDebug): Promise<string>;
+export declare function wrapFetchError(label: string, e: unknown, debug?: CatalogHttpDebug): Error;
 //# sourceMappingURL=catalog-session.d.ts.map

package/dist/generate/catalog-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-session.d.ts","sourceRoot":"","sources":["../../src/generate/catalog-session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAcjB"}
+{"version":3,"file":"catalog-session.d.ts","sourceRoot":"","sources":["../../src/generate/catalog-session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAE9B,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yFAAyF;IACzF,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAeD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,gBAAgB,GAAG,SAAS,GAClC;IAAE,UAAU,EAAE,KAAK,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAK/C;AAED,wBAAgB,IAAI,CAClB,KAAK,EAAE,gBAAgB,GAAG,SAAS,EACnC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAON;AAED,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,MAAM,CAAC,CAoCjB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAgBzF"}

package/dist/generate/catalog-session.mjs

@@ -2,25 +2,84 @@
  * Generator-only: obtain `4DAdminSID` via POST `/api/login` (multipart `accessKey`).
  * Not used by the runtime REST client.
  */
+import { Agent } from 'undici';
+let insecureAgent;
+function getInsecureDispatcher() {
+    if (!insecureAgent) {
+        insecureAgent = new Agent({
+            connect: {
+                rejectUnauthorized: false,
+            },
+        });
+    }
+    return insecureAgent;
+}
+export function catalogFetchInit(debug) {
+    if (!debug?.insecureTls) {
+        return {};
+    }
+    return { dispatcher: getInsecureDispatcher() };
+}
+export function vLog(debug, emoji, title, detail) {
+    if (!debug?.verbose)
+        return;
+    if (detail !== undefined && detail !== '') {
+        console.error(`${emoji}  ${title}\n   ${detail}`);
+    }
+    else {
+        console.error(`${emoji}  ${title}`);
+    }
+}
 export function defaultLoginUrlFromCatalogUrl(catalogUrl) {
     const u = new URL(catalogUrl);
     return `${u.origin}/api/login`;
 }
-export async function fetch4DAdminSessionCookie(loginUrl, accessKey) {
+export async function fetch4DAdminSessionCookie(loginUrl, accessKey, debug) {
+    vLog(debug, '🔐', 'Generator login', `POST ${loginUrl} (multipart field accessKey)`);
+    if (debug?.insecureTls) {
+        vLog(debug, '⚠️', 'TLS certificate verification is off', 'Only for local/dev. Remove --insecure-tls for real servers.');
+    }
+    vLog(debug, '🔑', 'Access key', accessKey ? `provided (${accessKey.length} chars)` : '(empty)');
     const form = new FormData();
     form.append('accessKey', accessKey);
-    const res = await fetch(loginUrl, { method: 'POST', body: form });
+    const extra = catalogFetchInit(debug);
+    let res;
+    try {
+        res = await fetch(loginUrl, { method: 'POST', body: form, ...extra });
+    }
+    catch (e) {
+        throw wrapFetchError('Login request', e, debug);
+    }
+    vLog(debug, '📥', 'Login response', `${res.status} ${res.statusText}`);
     if (!res.ok) {
         const t = await res.text();
         throw new Error(`quadrokit login failed (${res.status}): ${t.slice(0, 500)}`);
     }
     const lines = readSetCookieLines(res.headers);
+    vLog(debug, '🍪', 'Set-Cookie headers', `${lines.length} cookie line(s)`);
     const value = parse4DAdminSidValue(lines);
     if (!value) {
         throw new Error('quadrokit login: response had no 4DAdminSID Set-Cookie');
     }
+    vLog(debug, '✅', 'Session cookie', '4DAdminSID received — using it for the catalog request');
     return `4DAdminSID=${value}`;
 }
+export function wrapFetchError(label, e, debug) {
+    const err = e instanceof Error ? e : new Error(String(e));
+    if (debug?.verbose) {
+        vLog(debug, '💥', `${label} failed`, err.message);
+        if (err.cause instanceof Error) {
+            vLog(debug, '🔗', 'Underlying cause', err.cause.message);
+        }
+    }
+    const hint = err.message.includes('certificate') ||
+        err.message.includes('CERT') ||
+        (err.cause instanceof Error &&
+            (err.cause.message.includes('certificate') || err.cause.message.includes('CERT')))
+        ? ' Tip: try --insecure-tls for self-signed HTTPS in development.'
+        : '';
+    return new Error(`${label}: ${err.message}${hint}`, { cause: err });
+}
 function readSetCookieLines(headers) {
     const ext = headers;
     if (typeof ext.getSetCookie === 'function') {

package/dist/generate/dotenv-cwd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dotenv-cwd.d.ts","sourceRoot":"","sources":["../../src/generate/dotenv-cwd.ts"],"names":[],"mappings":"AAUA,sGAAsG;AACtG,wBAAgB,mBAAmB,IAAI,IAAI,CAuB1C"}
+{"version":3,"file":"dotenv-cwd.d.ts","sourceRoot":"","sources":["../../src/generate/dotenv-cwd.ts"],"names":[],"mappings":"AAYA,sGAAsG;AACtG,wBAAgB,mBAAmB,IAAI,IAAI,CAuB1C"}

package/dist/generate/dotenv-cwd.mjs

@@ -5,6 +5,8 @@ const KEYS = [
     'QUADROKIT_ACCESS_KEY',
     'QUADROKIT_LOGIN_URL',
     'QUADROKIT_CATALOG_TOKEN',
+    'QUADROKIT_GENERATE_VERBOSE',
+    'QUADROKIT_INSECURE_TLS',
 ];
 /** Merge project `.env` into `process.env` for keys that are not already set (generator CLI only). */
 export function applyGenerateDotenv() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadrokit/client",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Typed 4D REST client and catalog code generator for QuadroKit",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -29,7 +29,8 @@
     "generate:fixture": "bun run src/cli.ts generate --url file://../../assets/catalog.json --out ../../.quadrokit/generated-demo"
   },
   "dependencies": {
-    "@quadrokit/shared": "^0.2.4"
+    "@quadrokit/shared": "^0.2.6",
+    "undici": "^6.21.0"
   },
   "peerDependencies": {
     "typescript": ">=5.4"