tina4-nodejs 3.12.10 → 3.13.1

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.12.10)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.1)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.12.10 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.1 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -548,7 +548,7 @@ r.group("/api/v1", (g) => {
 
 ## Module: Database (`packages/orm/src/database.ts`)
 
-Full Database API. The same instance covers all five drivers (sqlite, postgres, mysql, mssql, firebird) — pick the driver via `DATABASE_URL` or pass a `DatabaseConfig` to `initDatabase()`.
+Full Database API. The same instance covers all five drivers (sqlite, postgres, mysql, mssql, firebird) — pick the driver via `TINA4_DATABASE_URL` or pass a `DatabaseConfig` to `initDatabase()`.
 
 ```typescript
 import { initDatabase, Database, DatabaseResult } from "@tina4/orm";
@@ -956,26 +956,26 @@ import { Router } from "./router.js";  // .js even though the file is .ts
 ## Database Configuration
 
 ### Connection string format
-Set `DATABASE_URL` in your `.env` file using `driver://host:port/database` format:
+Set `TINA4_DATABASE_URL` in your `.env` file using `driver://host:port/database` format:
 
 ```bash
 # SQLite (default if nothing configured)
-DATABASE_URL=sqlite:///path/to/db.sqlite
-DATABASE_URL=sqlite://./data/tina4.db
+TINA4_DATABASE_URL=sqlite:///path/to/db.sqlite
+TINA4_DATABASE_URL=sqlite://./data/tina4.db
 
 # PostgreSQL
-DATABASE_URL=postgres://localhost:5432/mydb
-DATABASE_URL=postgresql://localhost:5432/mydb
+TINA4_DATABASE_URL=postgres://localhost:5432/mydb
+TINA4_DATABASE_URL=postgresql://localhost:5432/mydb
 
 # MySQL
-DATABASE_URL=mysql://localhost:3306/mydb
+TINA4_DATABASE_URL=mysql://localhost:3306/mydb
 
 # MSSQL / SQL Server (both schemes work)
-DATABASE_URL=mssql://localhost:1433/mydb
-DATABASE_URL=sqlserver://localhost:1433/mydb
+TINA4_DATABASE_URL=mssql://localhost:1433/mydb
+TINA4_DATABASE_URL=sqlserver://localhost:1433/mydb
 
 # Firebird
-DATABASE_URL=firebird://localhost:3050/mydb
+TINA4_DATABASE_URL=firebird://localhost:3050/mydb
 ```
 
 ### Credentials
@@ -983,15 +983,15 @@ Credentials can be embedded in the URL or provided separately:
 
 ```bash
 # In the URL
-DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+TINA4_DATABASE_URL=postgres://user:pass@localhost:5432/mydb
 
 # Or as separate env vars (merged when URL has no credentials)
-DATABASE_URL=postgres://localhost:5432/mydb
-DATABASE_USERNAME=myuser
-DATABASE_PASSWORD=mypass
+TINA4_DATABASE_URL=postgres://localhost:5432/mydb
+TINA4_DATABASE_USERNAME=myuser
+TINA4_DATABASE_PASSWORD=mypass
 ```
 
-Credential priority: `config.user` > `config.username` > `DATABASE_USERNAME` env var.
+Credential priority: `config.user` > `config.username` > `TINA4_DATABASE_USERNAME` env var.
 
 ### Programmatic configuration
 ```typescript

package/package.json

@@ -3,11 +3,20 @@
 
 
 
-  "version": "3.12.10",
+  "version": "3.13.1",
 
   "type": "module",
-  "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
-  "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],
+  "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",
+  "keywords": [
+    "tina4",
+    "framework",
+    "web",
+    "api",
+    "orm",
+    "graphql",
+    "websocket",
+    "typescript"
+  ],
   "homepage": "https://tina4.com/nodejs",
   "repository": {
     "type": "git",
@@ -51,7 +60,7 @@
     "test": "tsx test/run-all.ts"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "dependencies": {},
   "devDependencies": {
@@ -59,4 +68,4 @@
     "tsx": "^4.19.0",
     "esbuild": "^0.24.0"
   }
-}
+}

package/packages/cli/src/commands/migrate.ts

@@ -10,8 +10,14 @@
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { loadEnv } from "../../../core/src/dotenv.js";
 
 export async function runMigrations(migrationDir?: string): Promise<void> {
+  // Load .env before initialising the DB so DATABASE_URL/TINA4_DATABASE_URL
+  // from the project's .env is visible. Without this the migrate command
+  // falls back to ./data/tina4.db regardless of what the project configured.
+  loadEnv();
+
   const dir = resolve(migrationDir ?? "migrations");
 
   if (!existsSync(dir)) {
@@ -40,11 +46,15 @@ export async function runMigrations(migrationDir?: string): Promise<void> {
     process.exit(1);
   }
 
-  // Ensure database is initialised (uses DATABASE_URL or defaults to sqlite)
+  // Ensure database is initialised (uses TINA4_DATABASE_URL/DATABASE_URL or
+  // defaults to sqlite). initDatabase() is async — MUST be awaited, otherwise
+  // setAdapter() has not run by the time ensureMigrationTable() asks for the
+  // adapter and the whole CLI crashes with "No database adapter configured."
   try {
-    initDatabase();
-  } catch {
-    // Adapter may already be set — ignore
+    await initDatabase();
+  } catch (err) {
+    console.error(`  Error initialising database: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 
   ensureMigrationTable();

package/packages/cli/src/commands/migrateRollback.ts

@@ -9,8 +9,13 @@
  *   tina4 migrate:rollback ./path/to/migrations
  */
 import { resolve } from "node:path";
+import { loadEnv } from "../../../core/src/dotenv.js";
 
 export async function migrateRollback(migrationDir?: string): Promise<void> {
+  // .env must load before initDatabase() — otherwise DATABASE_URL from the
+  // project's .env is invisible and we silently fall back to ./data/tina4.db.
+  loadEnv();
+
   const dir = resolve(migrationDir ?? "migrations");
 
   let initDatabase: typeof import("../../../orm/src/index.js").initDatabase;
@@ -29,11 +34,14 @@ export async function migrateRollback(migrationDir?: string): Promise<void> {
     process.exit(1);
   }
 
-  // Ensure database is initialised
+  // Ensure database is initialised — MUST await; initDatabase() is async
+  // and calls setAdapter() inside the promise. Without await, the next call
+  // to getAdapter() throws "No database adapter configured."
   try {
-    initDatabase();
-  } catch {
-    // Adapter may already be set — ignore
+    await initDatabase();
+  } catch (err) {
+    console.error(`  Error initialising database: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 
   ensureMigrationTable();

package/packages/cli/src/commands/migrateStatus.ts

@@ -6,8 +6,12 @@
  *   tina4 migrate:status ./path/to/migrations
  */
 import { resolve } from "node:path";
+import { loadEnv } from "../../../core/src/dotenv.js";
 
 export async function migrateStatus(migrationDir?: string): Promise<void> {
+  // .env must load before initDatabase() so the project's DATABASE_URL is seen.
+  loadEnv();
+
   const dir = resolve(migrationDir ?? "migrations");
 
   let initDatabase: typeof import("../../../orm/src/index.js").initDatabase;
@@ -24,11 +28,13 @@ export async function migrateStatus(migrationDir?: string): Promise<void> {
     process.exit(1);
   }
 
-  // Ensure database is initialised
+  // Ensure database is initialised — MUST await; initDatabase() is async
+  // and calls setAdapter() inside. Without await, getAdapter() throws.
   try {
-    initDatabase();
-  } catch {
-    // Adapter may already be set — ignore
+    await initDatabase();
+  } catch (err) {
+    console.error(`  Error initialising database: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 
   ensureMigrationTable();

package/packages/core/src/__feedback/widget.js

@@ -0,0 +1,96 @@
+(function(){"use strict";(()=>{try{const t=window.location.pathname||"";return t.startsWith("/__dev")||t.startsWith("/__feedback")}catch{return!1}})()?console.info("tina4-feedback-widget: skipping on developer path"):window.__tina4FeedbackLoaded?console.warn("tina4-feedback-widget already loaded; skipping"):(window.__tina4FeedbackLoaded=!0,b());function b(){const c=(getComputedStyle(document.documentElement).getPropertyValue("--primary")||"").trim()||"#3b82f6";h(c);const l=m();document.body.appendChild(l);let e=null,u;const r=[];l.addEventListener("click",()=>{if(e){e.remove(),e=null,l.style.display="";return}e=g(),document.body.appendChild(e),l.style.display="none",setTimeout(()=>e?.querySelector("textarea")?.focus(),0)});function g(){const o=document.createElement("div");o.className="tina4-fb-modal",o.innerHTML=`
+      <div class="tina4-fb-head">
+        <span class="tina4-fb-title">Tell us what's not working</span>
+        <button type="button" class="tina4-fb-close" aria-label="Close">×</button>
+      </div>
+      <div class="tina4-fb-context">
+        <span>📍 ${p(location.pathname+location.search)}</span>
+        <span>📐 ${window.innerWidth}×${window.innerHeight}</span>
+      </div>
+      <div class="tina4-fb-chat" role="log"></div>
+      <form class="tina4-fb-form">
+        <textarea
+          rows="3"
+          placeholder="What's hard to use here? Be specific — which field, which button, what you expected."
+          aria-label="Feedback message"
+        ></textarea>
+        <button type="submit" class="tina4-fb-send">Send</button>
+      </form>
+    `,o.querySelector(".tina4-fb-close")?.addEventListener("click",()=>{o.remove(),e=null,l.style.display=""});const a=o.querySelector("form");return a.addEventListener("submit",n=>{n.preventDefault();const i=a.querySelector("textarea"),f=i.value.trim();f&&(i.value="",x(f))}),s(o),o}function s(o){const a=o.querySelector(".tina4-fb-chat");if(a){if(!r.length){a.innerHTML=`<div class="tina4-fb-hint">Your feedback lands directly with the team — no email loop. We'll ask a quick follow-up if we need to.</div>`;return}a.innerHTML=r.map(n=>`<div class="tina4-fb-msg ${n.role==="user"?"tina4-fb-user":"tina4-fb-ai"}">${p(n.text)}</div>`).join(""),a.scrollTop=a.scrollHeight}}async function x(o){if(!e)return;r.push({role:"user",text:o}),s(e),d(e,!0);const a={message:o,context:{url:location.pathname+location.search,viewport:`${window.innerWidth}x${window.innerHeight}`,ua:navigator.userAgent},conversation_id:u};let n;try{const i=await fetch("/__feedback/api/turn",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(a)});if(n=await i.json(),!i.ok){const f=n?.error||`HTTP ${i.status}`;r.push({role:"ai",text:`Couldn't send: ${f}`}),s(e),d(e,!1);return}}catch(i){r.push({role:"ai",text:`Network issue: ${i?.message||i}`}),s(e),d(e,!1);return}if("ask"in n)u=n.conversation_id,r.push({role:"ai",text:n.ask}),s(e),d(e,!1),e?.querySelector("textarea")?.focus();else if("final"in n)r.push({role:"ai",text:`Thanks — filed as: "${n.final.title}". The team will take it from here.`}),s(e),d(e,!1),u=void 0,r.length=0,setTimeout(()=>{e?.remove(),e=null,l.style.display=""},4500);else{const i=n?.error||"unexpected response";r.push({role:"ai",text:`Issue: ${i}`}),s(e),d(e,!1)}}function d(o,a){const n=o.querySelector(".tina4-fb-send"),i=o.querySelector("textarea");n&&(n.disabled=a,n.textContent=a?"Sending…":"Send"),i&&(i.disabled=a)}}function m(){const t=document.createElement("button");return t.type="button",t.className="tina4-fb-btn",t.setAttribute("aria-label","Send feedback"),t.innerHTML="💬",t.title="Tell us what's not working",t}function h(t){const c=document.createElement("style");c.id="tina4-fb-styles",c.textContent=`
+    .tina4-fb-btn {
+      position: fixed; bottom: 1.25rem; right: 1.25rem;
+      width: 48px; height: 48px; border-radius: 50%; border: none;
+      background: ${t}; color: white; font-size: 1.4rem;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.18); cursor: pointer;
+      z-index: 2147483646; transition: transform 0.15s, box-shadow 0.15s;
+      display: flex; align-items: center; justify-content: center;
+      line-height: 1; padding: 0;
+    }
+    .tina4-fb-btn:hover { transform: scale(1.06); box-shadow: 0 6px 16px rgba(0,0,0,0.22); }
+    .tina4-fb-btn:active { transform: scale(0.96); }
+    .tina4-fb-modal {
+      position: fixed; bottom: 5rem; right: 1.25rem;
+      width: 340px; max-height: 480px; display: flex; flex-direction: column;
+      background: #1e1e2e; color: #cdd6f4;
+      border: 1px solid #313244; border-radius: 8px;
+      box-shadow: 0 8px 32px rgba(0,0,0,0.35);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+      font-size: 0.85rem; z-index: 2147483647;
+      animation: tina4-fb-in 0.18s ease-out;
+    }
+    @keyframes tina4-fb-in {
+      from { opacity: 0; transform: translateY(8px); }
+      to   { opacity: 1; transform: translateY(0); }
+    }
+    .tina4-fb-head {
+      display: flex; align-items: center; justify-content: space-between;
+      padding: 0.6rem 0.8rem; border-bottom: 1px solid #313244;
+    }
+    .tina4-fb-title { font-weight: 600; font-size: 0.9rem; }
+    .tina4-fb-close {
+      background: transparent; border: none; color: #9399b2;
+      font-size: 1.4rem; line-height: 1; cursor: pointer; padding: 0 0.2rem;
+    }
+    .tina4-fb-close:hover { color: #cdd6f4; }
+    .tina4-fb-context {
+      display: flex; gap: 0.6rem; padding: 0.4rem 0.8rem;
+      font-size: 0.7rem; color: #9399b2;
+      border-bottom: 1px solid #313244;
+      font-family: ui-monospace, "SF Mono", Menlo, monospace;
+    }
+    .tina4-fb-chat {
+      flex: 1; overflow-y: auto; padding: 0.5rem 0.8rem;
+      display: flex; flex-direction: column; gap: 0.4rem;
+      min-height: 80px; max-height: 280px;
+    }
+    .tina4-fb-hint {
+      font-size: 0.75rem; color: #9399b2; line-height: 1.4; padding: 0.3rem 0;
+    }
+    .tina4-fb-msg {
+      padding: 0.4rem 0.6rem; border-radius: 6px;
+      max-width: 85%; word-wrap: break-word; line-height: 1.35;
+    }
+    .tina4-fb-user { align-self: flex-end; background: ${t}; color: white; }
+    .tina4-fb-ai   { align-self: flex-start; background: #313244; }
+    .tina4-fb-form {
+      display: flex; flex-direction: column; gap: 0.4rem;
+      padding: 0.5rem 0.8rem 0.8rem; border-top: 1px solid #313244;
+    }
+    .tina4-fb-form textarea {
+      width: 100%; box-sizing: border-box; resize: vertical;
+      min-height: 60px; font-family: inherit; font-size: 0.82rem;
+      padding: 0.4rem 0.5rem; border: 1px solid #313244;
+      background: #11111b; color: #cdd6f4; border-radius: 4px;
+      line-height: 1.3;
+    }
+    .tina4-fb-form textarea:focus {
+      outline: none; border-color: ${t};
+    }
+    .tina4-fb-send {
+      align-self: flex-end; padding: 0.35rem 0.9rem;
+      background: ${t}; color: white; border: none; border-radius: 4px;
+      font-size: 0.8rem; font-weight: 500; cursor: pointer;
+    }
+    .tina4-fb-send:disabled { opacity: 0.55; cursor: wait; }
+    .tina4-fb-send:hover:not(:disabled) { filter: brightness(1.1); }
+  `,document.head.appendChild(c)}function p(t){return t.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#39;")}})();

package/packages/core/src/api.ts

@@ -18,6 +18,23 @@ export interface ApiResult {
     error: string | null;
 }
 
+/**
+ * Constructor options for {@link Api}. Used as the second argument to
+ * `new Api(url, { ... })` — cross-framework parity with Python
+ * `Api(bearer_token=, ...)` kwargs added in 3.13.x.
+ */
+export interface ApiOptions {
+    authHeader?: string;
+    timeout?: number;
+    ignoreSsl?: boolean;
+    /** Positive form of ignoreSsl — `verifySsl: false` disables verification. */
+    verifySsl?: boolean;
+    bearerToken?: string;
+    username?: string;
+    password?: string;
+    headers?: Record<string, string>;
+}
+
 export class Api {
     private baseUrl: string;
     private headers: Record<string, string>;
@@ -25,11 +42,56 @@ export class Api {
     private authHeader: string;
     private ignoreSsl: boolean;
 
-    constructor(baseUrl: string = "", authHeader: string = "", timeout: number = 30) {
+    /**
+     * Construct an Api client.
+     *
+     * Two construction styles supported:
+     *
+     *     // Legacy positional form
+     *     new Api("https://api.example.com", "Bearer token", 30);
+     *
+     *     // 3.13.1: ergonomic options bag (recommended) — cross-framework
+     *     // parity with Python tina4_python.api.Api kwargs.
+     *     new Api("https://api.example.com", { bearerToken: "sk-abc" });
+     *     new Api("https://api.example.com", { username: "u", password: "p" });
+     *     new Api("https://api.example.com", { headers: { "X-Tenant": "acme" } });
+     *     new Api("https://self-signed.local", { verifySsl: false });
+     *
+     * Bearer wins over basic-auth when both passed. `verifySsl: false` is
+     * the positive form of `ignoreSsl: true`; `ignoreSsl` wins when both
+     * supplied for backward compatibility.
+     */
+    constructor(
+        baseUrl: string = "",
+        authHeaderOrOptions: string | ApiOptions = "",
+        timeout: number = 30
+    ) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
-        this.authHeader = authHeader;
-        this.timeout = timeout;
         this.headers = {};
+
+        // Options-bag form — second arg is an object literal
+        if (typeof authHeaderOrOptions === "object" && authHeaderOrOptions !== null) {
+            const opts = authHeaderOrOptions;
+            this.authHeader = opts.authHeader ?? "";
+            this.timeout = opts.timeout ?? timeout;
+            this.ignoreSsl = (opts.ignoreSsl ?? false) || (opts.verifySsl === false);
+
+            // Bearer wins over basic-auth when both are passed
+            if (opts.bearerToken != null) {
+                this.setBearerToken(opts.bearerToken);
+            } else if (opts.username != null && opts.password != null) {
+                this.setBasicAuth(opts.username, opts.password);
+            }
+
+            if (opts.headers) {
+                this.addHeaders(opts.headers);
+            }
+            return;
+        }
+
+        // Legacy positional form
+        this.authHeader = authHeaderOrOptions;
+        this.timeout = timeout;
         this.ignoreSsl = false;
     }
 

package/packages/core/src/auth.ts

@@ -79,12 +79,19 @@ export function getToken(
 }
 
 /**
- * Validate a JWT token and return the decoded payload, or false if invalid/expired.
+ * Validate a JWT token. Returns the decoded payload on success, `null` if
+ * invalid/expired/malformed.
  *
- * Secret is always read from `process.env.TINA4_SECRET`.
+ * 3.13.0 — return type changed from `boolean` to `Record<string, unknown> | null`.
+ * Matches the convention used by `jsonwebtoken` and the Python / PHP / Ruby
+ * Auth.validToken signatures shipped at the same time. Legacy
+ * `if (validToken(t))` patterns keep working because a non-null object is
+ * truthy and null is falsy.
+ *
+ * Secret is read from `process.env.TINA4_SECRET` when not passed explicitly.
  * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
  */
-export function validToken(token: string, secret?: string, algorithm?: string): boolean {
+export function validToken(token: string, secret?: string, algorithm?: string): Record<string, unknown> | null {
   const resolvedSecret = secret ?? process.env.TINA4_SECRET ?? "";
   if (!resolvedSecret) {
     console.warn("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)");
@@ -92,24 +99,24 @@ export function validToken(token: string, secret?: string, algorithm?: string):
   const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
   try {
     const parts = token.split(".");
-    if (parts.length !== 3) return false;
+    if (parts.length !== 3) return null;
 
     const [h, p, sig] = parts;
     const signingInput = `${h}.${p}`;
 
     if (!verifySignature(signingInput, sig, resolvedSecret, resolvedAlgorithm)) {
-      return false;
+      return null;
     }
 
     const payload = JSON.parse(base64urlDecode(p).toString()) as Record<string, unknown>;
 
     if (typeof payload.exp === "number" && Date.now() / 1000 > payload.exp) {
-      return false;
+      return null;
     }
 
-    return true;
+    return payload;
   } catch {
-    return false;
+    return null;
   }
 }