tina4-nodejs 3.13.95 → 3.13.97

package/packages/swagger/dist/index.js

@@ -73,8 +73,12 @@ function sanitizeSecurity(reqs, schemes) {
 function generate(routes, models = []) {
   const info = {
     title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
-    version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
-    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation"
+    // The app's version, defaulting to 1.0.0 — NOT the framework's (Node shipped
+    // 0.0.1). description defaults to the empty string, not a canned sentence.
+    // Both are the settled cross-framework defaults (parity with the Python
+    // master); TINA4_SWAGGER_VERSION / _DESCRIPTION still override.
+    version: process.env.TINA4_SWAGGER_VERSION ?? "1.0.0",
+    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? ""
   };
   const contactEmail = (process.env.TINA4_SWAGGER_CONTACT_EMAIL ?? "").trim();
   const contactName = (process.env.TINA4_SWAGGER_CONTACT_TEAM ?? "").trim();
@@ -107,9 +111,11 @@ function generate(routes, models = []) {
   const includePrefixes = csv(process.env.TINA4_SWAGGER_INCLUDE);
   const excludePrefixes = csv(process.env.TINA4_SWAGGER_EXCLUDE);
   const refSchemas = /* @__PURE__ */ new Set();
+  const tableToSchema = /* @__PURE__ */ new Map();
   for (const model of models) {
-    const schema = modelToSchema(model);
-    spec.components.schemas[model.tableName] = schema;
+    const schemaKey = schemaNameForModel(model);
+    tableToSchema.set(model.tableName, schemaKey);
+    spec.components.schemas[schemaKey] = modelToSchema(model);
   }
   const usedTags = [];
   const seenIds = /* @__PURE__ */ new Set();
@@ -136,11 +142,11 @@ function generate(routes, models = []) {
     if (route.meta?.deprecated) operation.deprecated = true;
     const pathParams = extractPathParams(route.pattern);
     if (pathParams.length > 0) {
-      operation.parameters = pathParams.map((name) => ({
+      operation.parameters = pathParams.map(({ name, schema }) => ({
         name,
         in: "path",
         required: true,
-        schema: { type: "string" }
+        schema
       }));
     }
     if (method === "get" && !route.pattern.includes("[id]") && !route.pattern.includes("[...")) {
@@ -166,19 +172,20 @@ function generate(routes, models = []) {
       };
     } else if (method === "post" || method === "put") {
       const modelName = inferModelFromPath(route.pattern);
-      if (modelName && models.some((m) => m.tableName === modelName)) {
-        const media = {
-          schema: { $ref: `#/components/schemas/${modelName}` }
-        };
+      const schemaKey = modelName ? tableToSchema.get(modelName) : void 0;
+      if (schemaKey) {
+        const sref = `#/components/schemas/${schemaKey}`;
+        const media = { schema: { $ref: sref } };
         if (route.meta?.example !== void 0) media.example = route.meta.example;
         operation.requestBody = {
           required: true,
           content: { "application/json": media }
         };
-        operation.responses = {
-          ...method === "post" ? { "201": { description: "Created", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } } : { "200": { description: "Updated", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } },
-          "422": { description: "Validation failed" }
-        };
+        if (route.meta?.responses === void 0) {
+          operation.responses = {
+            "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } }
+          };
+        }
       } else if (route.meta?.example !== void 0) {
         operation.requestBody = {
           content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } }
@@ -265,6 +272,21 @@ function resolveServers() {
   const dev = (process.env.SWAGGER_DEV_URL ?? "").trim();
   return dev.length > 0 ? [{ url: dev }] : [{ url: "/" }];
 }
+function schemaNameForModel(model) {
+  const explicit = model.className?.trim();
+  if (explicit) return explicit;
+  return deriveClassName(model.tableName);
+}
+function deriveClassName(tableName) {
+  return singularize(tableName).split(/[_\s-]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("") || tableName;
+}
+function singularize(word) {
+  if (/ies$/i.test(word) && word.length > 3) return word.slice(0, -3) + "y";
+  if (/(ses|xes|zes|ches|shes)$/i.test(word)) return word.slice(0, -2);
+  if (/ss$/i.test(word)) return word;
+  if (/s$/i.test(word) && word.length > 1) return word.slice(0, -1);
+  return word;
+}
 function modelToSchema(model) {
   const properties = {};
   const required = [];
@@ -338,15 +360,47 @@ function inferSchema(value) {
   if (typeof value === "number") return { type: Number.isInteger(value) ? "integer" : "number" };
   return { type: "string" };
 }
+var PARAM_TYPE_SCHEMA = {
+  int: { type: "integer" },
+  integer: { type: "integer" },
+  float: { type: "number" },
+  number: { type: "number" },
+  uuid: { type: "string", format: "uuid" },
+  slug: { type: "string", pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+  alpha: { type: "string", pattern: "^[A-Za-z]+$" },
+  alnum: { type: "string", pattern: "^[A-Za-z0-9]+$" },
+  path: { type: "string" },
+  string: { type: "string" }
+};
+function segmentParam(segment) {
+  if (segment.startsWith("{") && segment.endsWith("}")) {
+    const inner = segment.slice(1, -1);
+    if (inner.startsWith("...")) return { name: inner.slice(3), type: "string" };
+    const colon = inner.indexOf(":");
+    if (colon >= 0) return { name: inner.slice(0, colon), type: inner.slice(colon + 1) };
+    return { name: inner, type: "string" };
+  }
+  if (segment.startsWith("[") && segment.endsWith("]")) {
+    const inner = segment.slice(1, -1);
+    return { name: inner.startsWith("...") ? inner.slice(3) : inner, type: "string" };
+  }
+  if (segment.startsWith(":") && segment.length > 1) {
+    return { name: segment.slice(1), type: "string" };
+  }
+  return null;
+}
 function patternToOpenAPI(pattern) {
-  return pattern.replace(/\[\.\.\.(\w+)\]/g, "{$1}").replace(/\[(\w+)\]/g, "{$1}");
+  return pattern.split("/").map((segment) => {
+    const p = segmentParam(segment);
+    return p ? `{${p.name}}` : segment;
+  }).join("/");
 }
 function extractPathParams(pattern) {
   const params = [];
-  const regex = /\[(?:\.\.\.)?(\w+)\]/g;
-  let match;
-  while ((match = regex.exec(pattern)) !== null) {
-    params.push(match[1]);
+  for (const segment of pattern.split("/")) {
+    const p = segmentParam(segment);
+    if (!p) continue;
+    params.push({ name: p.name, schema: { ...PARAM_TYPE_SCHEMA[p.type] ?? { type: "string" } } });
   }
   return params;
 }
@@ -368,8 +422,12 @@ function inferModelFromPath(pattern) {
   if (rest.length === 1 && /^[[{]\.{0,3}\w+[\]}]$/.test(rest[0])) return candidate;
   return null;
 }
+function operationIdBase(method, openApiPath) {
+  const clean = openApiPath.replace(/^\/+|\/+$/g, "").replace(/\//g, "_").replace(/\.\.\./g, "").replace(/[{}]/g, "").replace(/\*/g, "wildcard");
+  return clean ? `${method}_${clean}` : method;
+}
 function uniqueOperationId(method, openApiPath, seen) {
-  const base = (method + openApiPath.replace(/[/{}]/g, "_")).replace(/_+/g, "_").replace(/_$/, "");
+  const base = operationIdBase(method, openApiPath);
   let oid = base;
   let n = 2;
   while (seen.has(oid)) {

package/packages/swagger/src/generator.ts

@@ -140,8 +140,12 @@ export function generate(
 ): OpenAPISpec {
   const info: OpenAPISpecInfo = {
     title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
-    version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
-    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation",
+    // The app's version, defaulting to 1.0.0 — NOT the framework's (Node shipped
+    // 0.0.1). description defaults to the empty string, not a canned sentence.
+    // Both are the settled cross-framework defaults (parity with the Python
+    // master); TINA4_SWAGGER_VERSION / _DESCRIPTION still override.
+    version: process.env.TINA4_SWAGGER_VERSION ?? "1.0.0",
+    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "",
   };
 
   // Optional contact — email, plus name/url (the interface declares them; they
@@ -188,10 +192,15 @@ export function generate(
   // Reusable custom schemas referenced by routes via meta.requestSchema/responseSchemas.
   const refSchemas = new Set<string>();
 
-  // Generate schemas from models
+  // Generate schemas from models, keyed by the model CLASS name ('Item'), which
+  // is the type name a generated client wants — never the tableName ('items').
+  // `tableToSchema` maps a path-inferred tableName back to that schema key so a
+  // POST/PUT request body $ref resolves to the same 'Item' entry.
+  const tableToSchema = new Map<string, string>();
   for (const model of models) {
-    const schema = modelToSchema(model);
-    spec.components!.schemas![model.tableName] = schema;
+    const schemaKey = schemaNameForModel(model);
+    tableToSchema.set(model.tableName, schemaKey);
+    spec.components!.schemas![schemaKey] = modelToSchema(model);
   }
 
   const usedTags: string[] = [];
@@ -224,14 +233,18 @@ export function generate(
     if (route.meta?.description) operation.description = route.meta.description;
     if (route.meta?.deprecated) operation.deprecated = true;
 
-    // Add path parameters
+    // Add path parameters. Each typed token maps to its JSON Schema fragment
+    // (int -> integer, uuid -> string+format, slug -> string+pattern, ...) via
+    // PARAM_TYPE_SCHEMA below, mirroring the Python master's _PARAM_TYPE_SCHEMA
+    // and the router's accepted token set. An unknown token degrades to string
+    // rather than dropping the parameter, and the token never reaches the key.
     const pathParams = extractPathParams(route.pattern);
     if (pathParams.length > 0) {
-      operation.parameters = pathParams.map((name) => ({
+      operation.parameters = pathParams.map(({ name, schema }) => ({
         name,
         in: "path",
         required: true,
-        schema: { type: "string" },
+        schema,
       }));
     }
 
@@ -263,23 +276,27 @@ export function generate(
       };
     } else if (method === "post" || method === "put") {
       const modelName = inferModelFromPath(route.pattern);
-      if (modelName && models.some((m) => m.tableName === modelName)) {
-        const media: Record<string, unknown> = {
-          schema: { $ref: `#/components/schemas/${modelName}` },
-        };
+      const schemaKey = modelName ? tableToSchema.get(modelName) : undefined;
+      if (schemaKey) {
+        const sref = `#/components/schemas/${schemaKey}`;
+        const media: Record<string, unknown> = { schema: { $ref: sref } };
         if (route.meta?.example !== undefined) media.example = route.meta.example;
         operation.requestBody = {
           required: true,
           content: { "application/json": media },
         };
 
-        // Add response schema
-        operation.responses = {
-          ...(method === "post"
-            ? { "201": { description: "Created", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } }
-            : { "200": { description: "Updated", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } }),
-          "422": { description: "Validation failed" },
-        };
+        // Response documents 200 with the resource schema — parity with the
+        // Python master, which emits ONLY 200 for a model write. The old code
+        // stamped an unconditional 422 and a 201 the generator has no way to know
+        // a given route returns; both were fiction on a path-inferred write. A
+        // route that genuinely answers another code declares it via
+        // meta.responses, which is honoured above and never clobbered here.
+        if (route.meta?.responses === undefined) {
+          operation.responses = {
+            "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } },
+          };
+        }
       } else if (route.meta?.example !== undefined) {
         // Non-model body with an explicit example.
         operation.requestBody = {
@@ -394,6 +411,36 @@ function resolveServers(): { url: string }[] {
   return dev.length > 0 ? [{ url: dev }] : [{ url: "/" }];
 }
 
+/**
+ * The `components.schemas` key for a model: its CLASS name when carried from
+ * discovery (`ModelClass.name`, e.g. `Item`), else a singular PascalCase
+ * derivation of the tableName so a raw `{tableName, fields}` still yields a
+ * client-friendly type name ('items' -> 'Item').
+ */
+function schemaNameForModel(model: ModelDefinition): string {
+  const explicit = model.className?.trim();
+  if (explicit) return explicit;
+  return deriveClassName(model.tableName);
+}
+
+/** 'items' -> 'Item', 'blog_posts' -> 'BlogPost', 'categories' -> 'Category'. */
+function deriveClassName(tableName: string): string {
+  return singularize(tableName)
+    .split(/[_\s-]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("") || tableName;
+}
+
+/** Best-effort English singularisation for the common plural-table convention. */
+function singularize(word: string): string {
+  if (/ies$/i.test(word) && word.length > 3) return word.slice(0, -3) + "y";
+  if (/(ses|xes|zes|ches|shes)$/i.test(word)) return word.slice(0, -2);
+  if (/ss$/i.test(word)) return word;      // "class"/"address" stay as-is
+  if (/s$/i.test(word) && word.length > 1) return word.slice(0, -1);
+  return word;
+}
+
 function modelToSchema(model: ModelDefinition): Record<string, unknown> {
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
@@ -479,16 +526,93 @@ function inferSchema(value: unknown): Record<string, unknown> {
   return { type: "string" };
 }
 
+/**
+ * Path-param type token -> JSON Schema fragment. Mirrors the Python master's
+ * `_PARAM_TYPE_SCHEMA` (tina4_python/swagger/__init__.py) and the router's
+ * `PARAM_TYPE_PATTERNS`, so the documented contract matches EXACTLY what the
+ * router accepts. `int`/`integer` -> integer, `float`/`number` -> number,
+ * `uuid` -> string+format, `slug`/`alpha`/`alnum` -> string+pattern, bare/`path`
+ * -> string. A token NOT in this table degrades to `{type:"string"}` (see
+ * `extractPathParams`) rather than dropping the parameter.
+ */
+const PARAM_TYPE_SCHEMA: Record<string, Record<string, unknown>> = {
+  int: { type: "integer" },
+  integer: { type: "integer" },
+  float: { type: "number" },
+  number: { type: "number" },
+  uuid: { type: "string", format: "uuid" },
+  slug: { type: "string", pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+  alpha: { type: "string", pattern: "^[A-Za-z]+$" },
+  alnum: { type: "string", pattern: "^[A-Za-z0-9]+$" },
+  path: { type: "string" },
+  string: { type: "string" },
+};
+
+/**
+ * The (name, type) of a single dynamic path segment, or null for a static one.
+ *
+ * Accepts EVERY shape a route pattern can carry: the brace form `{id}` /
+ * `{id:int}` / `{...slug}` (the runtime/programmatic spelling), the file-system
+ * form `[id]` / `[...slug]` (route discovery converts these to `{...}` before a
+ * route is registered, but `generate()` is public and a caller may hand either),
+ * and the Express form `:id`. A catch-all (`...`) carries no type token, so it
+ * is always a string.
+ */
+function segmentParam(segment: string): { name: string; type: string } | null {
+  if (segment.startsWith("{") && segment.endsWith("}")) {
+    const inner = segment.slice(1, -1);
+    if (inner.startsWith("...")) return { name: inner.slice(3), type: "string" };
+    const colon = inner.indexOf(":");
+    if (colon >= 0) return { name: inner.slice(0, colon), type: inner.slice(colon + 1) };
+    return { name: inner, type: "string" };
+  }
+  if (segment.startsWith("[") && segment.endsWith("]")) {
+    const inner = segment.slice(1, -1);
+    return { name: inner.startsWith("...") ? inner.slice(3) : inner, type: "string" };
+  }
+  if (segment.startsWith(":") && segment.length > 1) {
+    return { name: segment.slice(1), type: "string" };
+  }
+  return null;
+}
+
+/**
+ * The OpenAPI path key for a route pattern: every dynamic segment collapses to a
+ * bare `{name}`, so the type token NEVER leaks into the key (PHP shipped
+ * `/api/typed/{id:int}` as the key — invalid, and a mismatch with the declared
+ * parameter). File-system `[id]`/`[...slug]`, runtime `{id:int}`/`{...slug}` and
+ * Express `:id` all normalise to `{name}`.
+ */
 function patternToOpenAPI(pattern: string): string {
-  return pattern.replace(/\[\.\.\.(\w+)\]/g, "{$1}").replace(/\[(\w+)\]/g, "{$1}");
+  return pattern
+    .split("/")
+    .map((segment) => {
+      const p = segmentParam(segment);
+      return p ? `{${p.name}}` : segment;
+    })
+    .join("/");
 }
 
-function extractPathParams(pattern: string): string[] {
-  const params: string[] = [];
-  const regex = /\[(?:\.\.\.)?(\w+)\]/g;
-  let match;
-  while ((match = regex.exec(pattern)) !== null) {
-    params.push(match[1]);
+/**
+ * Every dynamic path parameter of a route pattern as a `{name, schema}` pair.
+ *
+ * This once matched only `[id]` - the FILE-SYSTEM spelling - while route
+ * discovery had already converted `[id]` to `{id}`, so at runtime the regex ran
+ * against `{id}` looking for `[id]` and returned nothing: every operation
+ * shipped with no `in: path` parameter, an invalid document (measured against
+ * openapi-spec-validator), unconditionally, because the framework registers
+ * `/__frond/live/{name}` itself. Beyond that first fix, a TYPED token like
+ * `{id:int}` was still dropped (the name-only regex did not match past the
+ * colon) and its type leaked into the path key. This segment-based walk resolves
+ * both spellings AND the type token, mapping it through PARAM_TYPE_SCHEMA so the
+ * documented type matches the route the router compiled.
+ */
+function extractPathParams(pattern: string): Array<{ name: string; schema: Record<string, unknown> }> {
+  const params: Array<{ name: string; schema: Record<string, unknown> }> = [];
+  for (const segment of pattern.split("/")) {
+    const p = segmentParam(segment);
+    if (!p) continue;
+    params.push({ name: p.name, schema: { ...(PARAM_TYPE_SCHEMA[p.type] ?? { type: "string" }) } });
   }
   return params;
 }
@@ -517,10 +641,29 @@ function inferModelFromPath(pattern: string): string | null {
   return null;
 }
 
+/**
+ * operationId base from method + path, mirroring the Python master's
+ * `_operation_id`: strip leading/trailing slashes, turn internal `/` into `_`,
+ * drop braces, catch-all `...` and a bare splat `*` -> `wildcard`.
+ *
+ * Underscores are deliberately NOT collapsed. Collapsing made `/__health` and
+ * `/health` both reduce to `get_health`, so one got a `_2` suffix and WHICH one
+ * depended on registration order — a generated client's method name flipping
+ * between builds. Preserving them yields `get___health` vs `get_health`, two
+ * distinct ids straight from the two distinct paths.
+ */
+function operationIdBase(method: string, openApiPath: string): string {
+  const clean = openApiPath
+    .replace(/^\/+|\/+$/g, "")   // strip leading/trailing slashes (Python .strip("/"))
+    .replace(/\//g, "_")          // internal slash -> underscore
+    .replace(/\.\.\./g, "")       // catch-all '...' inside braces -> nothing ({...slug} -> slug)
+    .replace(/[{}]/g, "")         // drop braces
+    .replace(/\*/g, "wildcard");  // bare splat -> wildcard
+  return clean ? `${method}_${clean}` : method;
+}
+
 function uniqueOperationId(method: string, openApiPath: string, seen: Set<string>): string {
-  const base = (method + openApiPath.replace(/[/{}]/g, "_"))
-    .replace(/_+/g, "_")
-    .replace(/_$/, "");
+  const base = operationIdBase(method, openApiPath);
   let oid = base;
   let n = 2;
   while (seen.has(oid)) {

package/types/core/src/index.d.ts

@@ -23,8 +23,6 @@ export { Session, FileSessionHandler, RedisSessionHandler, buildSessionCookie, i
 export type { SessionConfig, SessionHandler } from "./session.js";
 export { I18n } from "./i18n.js";
 export { FakeData } from "./fakeData.js";
-export { ScssCompiler } from "./scss.js";
-export type { ScssConfig } from "./scss.js";
 export { Queue } from "./queue.js";
 export type { QueueConfig, QueueJob, ProcessOptions } from "./queue.js";
 export { createJob } from "./job.js";
@@ -57,7 +55,7 @@ export { HtmlElement, htmlElement, addHtmlHelpers, Raw, SafeString } from "./htm
 export { renderErrorOverlay, renderProductionError, isDebugMode } from "./errorOverlay.js";
 export { AI_TOOLS, isInstalled, showMenu, installSelected, installAll, generateContext } from "./ai.js";
 export type { AiTool } from "./ai.js";
-export type { ImapMessage, ImapFullMessage } from "./messenger.js";
+export type { ImapMessage, ImapFullMessage, ImapAttachment } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
 export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";
 export type { RabbitMQConfig } from "./queueBackends/rabbitmqBackend.js";

package/types/core/src/messenger.d.ts

@@ -2,7 +2,13 @@ import { DevMailbox } from "./devMailbox.js";
 export interface SendResult {
     success: boolean;
     message: string;
-    id?: string;
+    /**
+     * The real Message-ID on success, `null` on failure — but ALWAYS present, so a
+     * caller reading `result.id` gets one shape from both branches (G6). It used to
+     * be omitted on the failure path, handing back `undefined` there and a string on
+     * success.
+     */
+    id: string | null;
 }
 /**
  * Raised when an IMAP read fails to connect, authenticate, or speak the
@@ -62,15 +68,33 @@ export interface ImapMessage {
     snippet: string;
     seen: boolean;
 }
+/**
+ * An attachment from a read() message. `content` is the RAW DECODED BYTES of the
+ * part (transfer-decoded from base64 / quoted-printable), the SAME convention as
+ * req.files[x].content — raw bytes, not base64 — so an attachment is downloadable
+ * as-is; `size` is that decoded byte length. Parity with Python's read()
+ * attachment dict {filename, content_type, size, content}, in Node's idiomatic
+ * camelCase (ADR-0008 / G5). #69 folded the bytes in HERE — there is no separate
+ * carrier (Python retired its attachments_data in 3.13.96).
+ */
+export interface ImapAttachment {
+    filename: string;
+    contentType: string;
+    size: number;
+    content: Buffer;
+}
 export interface ImapFullMessage {
     uid: string;
     subject: string;
     from: string;
     to: string;
     cc: string;
+    /** ISO-8601, parsed from the Date header (parity with Python's _iso_date). */
     date: string;
     bodyText: string;
     bodyHtml: string;
+    /** Attachments, each carrying its decoded bytes. Empty when the message has none (G5 / #69). */
+    attachments: ImapAttachment[];
     headers: Record<string, string>;
 }
 export declare class Messenger {
@@ -116,6 +140,13 @@ export declare class Messenger {
     /** The local mailbox, created on first capture and reused after. */
     private getDevMailbox;
     send(to: string | string[], subject: string, body: string, html?: boolean, text?: string, cc?: string | string[], bcc?: string | string[], replyTo?: string, attachments?: string[], headers?: Record<string, string>): Promise<SendResult>;
+    /**
+     * Render a Frond template STRING and send it as an HTML email (G7, parity with
+     * Python's send_template). Extra send() options (cc, bcc, replyTo, attachments,
+     * headers) pass through. If the Frond package cannot be loaded the raw template
+     * is sent verbatim (matches Python's ImportError fallback) rather than failing.
+     */
+    sendTemplate(to: string | string[], subject: string, template: string, data?: Record<string, unknown>, cc?: string | string[], bcc?: string | string[], replyTo?: string, attachments?: string[], headers?: Record<string, string>): Promise<SendResult>;
     /**
      * Test the SMTP connection without sending an email.
      */
@@ -138,7 +169,7 @@ export declare class Messenger {
      */
     inbox(folder?: string, limit?: number, offset?: number): Promise<ImapMessage[]>;
     /**
-     * Read a single message by sequence number or UID.
+     * Read a single message by its IMAP UID.
      */
     read(uid: string, folder?: string): Promise<ImapFullMessage | null>;
     /**
@@ -146,13 +177,23 @@ export declare class Messenger {
      */
     search(folder?: string, subject?: string, sender?: string, since?: string, before?: string, unseenOnly?: boolean, limit?: number): Promise<ImapMessage[]>;
     /**
-     * Delete a message by UID.
+     * Delete a message by UID (mark \Deleted, then EXPUNGE).
+     *
+     * `delete` is the one cross-framework name (python/php/ruby/node all spell it
+     * `delete`). `deleteMessage` remains as a DEPRECATED alias for one release.
      */
+    delete(uid: string, folder?: string): Promise<void>;
+    /** @deprecated Use {@link delete} — kept as an alias for one release (G7). */
     deleteMessage(uid: string, folder?: string): Promise<void>;
     /**
-     * Mark a message as read.
+     * Mark a message as read (+FLAGS \Seen).
      */
     markRead(uid: string, folder?: string): Promise<void>;
+    /**
+     * Mark a message as unread (-FLAGS \Seen) — the inverse of markRead (G7,
+     * parity with Python's mark_unread).
+     */
+    markUnread(uid: string, folder?: string): Promise<void>;
     /**
      * Count unseen messages in a folder.
      */

package/types/core/src/queueBackends/kafkaBackend.d.ts

@@ -114,4 +114,5 @@ export declare class KafkaBackend implements QueueBackend {
     pop(queue: string): QueueJob | null;
     size(_queue: string): number;
     clear(_queue: string): void;
+    purge(_queue: string, _status?: string): number;
 }

package/types/core/src/queueBackends/rabbitmqBackend.d.ts

@@ -51,5 +51,6 @@ export declare class RabbitMQBackend implements QueueBackend {
     push(queue: string, payload: unknown, _delay?: number): string;
     pop(queue: string): QueueJob | null;
     size(queue: string): number;
-    clear(queue: string): void;
+    clear(_queue: string): void;
+    purge(_queue: string, _status?: string): number;
 }

package/types/core/src/server.d.ts

@@ -120,10 +120,6 @@ export declare function resetTemplateCache(): void;
  * The whole feature can be turned off with `TINA4_TEMPLATE_ROUTING=off`.
  */
 export declare function resolveTemplate(pathname: string, templatesDir: string): string | null;
-/**
- * Start the Tina4 HTTP server.
- * Thin wrapper around startServer() for cross-framework parity with PHP and Ruby.
- */
 export declare function start(config?: Tina4Config): Promise<{
     close: () => void;
     router: Router;

package/types/core/src/session.d.ts

@@ -233,6 +233,13 @@ export declare class Session {
      *
      *   session.flash("message", "Saved!")  // set
      *   session.flash("message")            // get + auto-remove → "Saved!"
+     *   session.flash("message", null)      // get + auto-remove (null is a GET sentinel)
+     *
+     * `null` — NOT just `undefined` — is the GET sentinel, so `flash(key, null)`
+     * READS and clears rather than STORING null. This matches the Python master
+     * (`if value is not None`), PHP (`if ($value !== null)`) and Ruby
+     * (`if value.nil?`): passing the language's "no value" literal means GET. A
+     * caller wanting to persist an explicit null should store it with `set()`.
      */
     flash(key: string, value?: unknown): unknown;
     /**