@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/semantic/dialects/types.d.ts

@@ -0,0 +1,118 @@
+import type { AggregateFunction, QueryValue } from "../../seo-query-builder";
+export type SqlDialectId = "sqlite" | "postgres" | "clickhouse" | "bigquery" | "snowflake" | "redshift";
+export type SqlParamType = "string" | "number" | "boolean" | "date";
+export type DateUnit = "day" | "week" | "month" | "year";
+/**
+ * Granularites de troncature. `DateUnit` ne couvre que les ecarts
+ * calendaires que `dateDiff` sait mesurer ; la troncature, elle, sait
+ * descendre a la minute et a l'heure et monter au trimestre.
+ */
+export type DateTruncUnit = DateUnit | "minute" | "hour" | "quarter";
+export type SqlValueType = "string" | "number" | "date" | "boolean";
+/**
+ * Un dialecte SQL : tout ce qui varie entre D1 (SQLite), Hyperdrive
+ * (Postgres) et ClickHouse.
+ */
+export interface SqlDialect {
+    id: SqlDialectId;
+    quoteIdent(name: string): string;
+    placeholder(index: number, type: SqlParamType): string;
+    boolLiteral(value: boolean): string;
+    numericCast(expr: string): string;
+    safeDivide(numerator: string, denominator: string): string;
+    round(expr: string, digits: number): string;
+    abs(expr: string): string;
+    floor(expr: string): string;
+    ceil(expr: string): string;
+    lower(expr: string): string;
+    upper(expr: string): string;
+    length(expr: string): string;
+    coalesce(parts: string[]): string;
+    concat(parts: string[]): string;
+    contains(haystack: string, needle: string): string;
+    startsWith(haystack: string, needle: string): string;
+    endsWith(haystack: string, needle: string): string;
+    cast(expr: string, type: SqlValueType): string;
+    dateTrunc(unit: DateTruncUnit, expr: string): string;
+    /**
+     * Le jour calendaire UTC d'un champ temporel, rendu en texte ISO
+     * (`YYYY-MM-DD`).
+     *
+     * Les trois dialectes rendent le **même texte** : les comparaisons de
+     * jours sont donc lexicographiques, et identiques sur D1, Hyperdrive et
+     * ClickHouse.
+     */
+    dateDayExpr(expr: string): string;
+    /**
+     * Difference de dates. Convention de signe : `left - right`.
+     *
+     * - Unites ELAPSED (tronquees vers zero, pas arrondies ni planchées) :
+     *   `day` (periodes de 24h), `week` (periodes de 7x24h).
+     * - Unites CALENDRIER (difference de composantes date) : `month`, `year`.
+     *
+     * Les trois dialectes doivent renvoyer le meme entier pour les unites
+     * elapsed sur une meme paire (left, right), y compris pour les valeurs
+     * negatives (troncature vers zero).
+     */
+    dateDiff(unit: DateTruncUnit, left: string, right: string): string;
+    /**
+     * Convertit un instant dans l'heure murale d'un fuseau IANA.
+     *
+     * SQLite n'embarque pas de base de fuseaux : son implementation leve.
+     */
+    applyTimezone(expr: string, timezone: string): string;
+    /** Troncature dans l'heure murale d'un fuseau IANA. */
+    dateTruncInTimezone(unit: DateTruncUnit, expr: string, timezone: string): string;
+    /** Difference de dates dans l'heure murale d'un fuseau IANA. */
+    dateDiffInTimezone(unit: DateTruncUnit, left: string, right: string, timezone: string): string;
+    aggregate(fn: AggregateFunction, expr: string): string;
+    renderLimit(limit: number, offset?: number): string;
+    renderTemplate(template: string, ctx: Record<string, unknown>): {
+        sql: string;
+        params: unknown[];
+    };
+    paramType(value: QueryValue): SqlParamType;
+    /**
+     * Compile une fonction fenêtrée (ROW_NUMBER, RANK, LAG, LEAD,
+     * SUM OVER, COUNT OVER, AVG OVER, MIN/MAX OVER, NTILE, etc.).
+     */
+    window(expr: string, over: {
+        partitionBy?: string[];
+        orderBy?: string;
+        frame?: string;
+    }): string;
+    /**
+     * Compile un offset par rapport à la ligne courante (LAG/LEAD génériques).
+     */
+    offset(expr: string, offset: number, defaultValue: string | null, over: {
+        partitionBy?: string[];
+        orderBy?: string;
+    }): string;
+    /**
+     * Compile une expression de rang (RANK/DENSE_RANK/ROW_NUMBER).
+     */
+    rank(kind: "row_number" | "rank" | "dense_rank" | "percent_rank" | "cum_dist", over: {
+        partitionBy?: string[];
+        orderBy: string;
+    }): string;
+    /**
+     * Compile une fonction d'agrégation fenêtrée (SUM/COUNT/AVG/MIN/MAX OVER).
+     */
+    windowAggregate(fn: AggregateFunction, expr: string, over: {
+        partitionBy?: string[];
+        orderBy?: string;
+        frame?: string;
+    }): string;
+    /**
+     * Compile un CTE de nom donné à partir d'une sous-requête.
+     */
+    cte(name: string, query: string, columns?: string[]): string;
+    /**
+     * Retourne `true` si le dialecte supporte les CTE (WITH ... AS (...)).
+     */
+    supportsCte(): boolean;
+    /**
+     * Rend la définition d'une table dérivée (sous-requête dans FROM).
+     */
+    derivedTable(query: string, alias: string): string;
+}

package/dist/semantic/eval-memory.d.ts

@@ -0,0 +1,41 @@
+import type { QueryFilter, QueryValue } from "../seo-query-builder";
+import type { ResolvedParameters } from "./parameters/resolve";
+import { type MetricExpr } from "./expr";
+import { type SandboxAttributes, type SandboxContext } from "./sandbox";
+/**
+ * Évaluateur en mémoire de la couche sémantique.
+ *
+ * Miroir exact du compilateur SQL : une expression doit produire le même
+ * résultat en mémoire et en base. Toute divergence entre les deux est un bug.
+ *
+ * Contrat de `dateDiff` (identique aux trois dialectes SQL) :
+ * - unités **écoulées** (`day` = 24 h, `week` = 7 × 24 h) : périodes entières
+ *   **tronquées vers zéro**, ni arrondies ni planchées ;
+ * - unités **calendaires** (`month`, `year`) : différence de composantes de
+ *   date ;
+ * - convention de signe : `left - right` ;
+ * - une date invalide rend `null` (et non `0`).
+ */
+export type EvalRow = Record<string, QueryValue>;
+/** Évalue une expression sur une ligne. */
+export declare function evalExpr(expr: MetricExpr, row: EvalRow, aggregates?: Map<MetricExpr, QueryValue>): QueryValue;
+/**
+ * Évalue une expression **sur un groupe de lignes** : les agrégats qu'elle
+ * contient sont calculés sur le groupe, puis substitués.
+ */
+export declare function evalAggregate(expr: MetricExpr, rows: EvalRow[]): QueryValue;
+/**
+ * Filtre sémantique : délègue à `evaluateFilter` de `seo-query-builder.ts`,
+ * qui en reste la référence unique (contains/starts_with/ends_with insensibles
+ * à la casse, comparaisons numériques strictes).
+ *
+ * Les options sont transmises telles quelles : une période relative et un
+ * paramètre typé doivent se résoudre **de la même façon** en mémoire et en
+ * SQL, sinon les deux moteurs de sélection divergeraient.
+ */
+export declare function evaluateSemanticFilter(row: EvalRow, filter: QueryFilter, options?: {
+    now?: Date;
+    parameters?: ResolvedParameters;
+    sandbox?: SandboxContext;
+    sandboxAttributes?: SandboxAttributes;
+}): boolean;

package/dist/semantic/expr-json.d.ts

@@ -0,0 +1,6 @@
+import type { QueryFilter } from "../seo-query-builder";
+import type { MetricExpr } from "./expr";
+export declare function parseMetricExpr(raw: string): MetricExpr;
+export declare function stringifyMetricExpr(expr: MetricExpr): string;
+export declare function parseQueryFilter(raw: string): QueryFilter;
+export declare function stringifyQueryFilter(filter: QueryFilter): string;

package/dist/semantic/expr.d.ts

@@ -0,0 +1,59 @@
+import type { AggregateFunction, QueryValue } from "../seo-query-builder";
+/**
+ * Le langage d'expression de la couche sémantique.
+ *
+ * Une expression est un **AST JSON** : sérialisable, versionnable, diffable,
+ * et exploitable par deux backends — un évaluateur en mémoire et un
+ * compilateur SQL. C'est ce qui permet à un catalogue livré par le code et
+ * à un modèle écrit par l'utilisateur d'être interchangeables.
+ */
+export declare const METRIC_FNS: readonly ["safeRatio", "safePercent", "normalizeCtrInput", "abs", "round", "floor", "ceil", "lower", "upper", "length", "coalesce", "concat", "contains", "startsWith", "endsWith", "dateTrunc", "dateDiff"];
+export type MetricFn = (typeof METRIC_FNS)[number];
+export declare const METRIC_OPS: readonly ["+", "-", "*", "/", "=", "!=", "<>", ">", ">=", "<", "<="];
+export type MetricOp = (typeof METRIC_OPS)[number];
+export type MetricExpr = {
+    kind: "column";
+    name: string;
+} | {
+    kind: "literal";
+    value: QueryValue;
+} | {
+    kind: "call";
+    fn: MetricFn;
+    args: MetricExpr[];
+} | {
+    kind: "binary";
+    op: MetricOp;
+    left: MetricExpr;
+    right: MetricExpr;
+} | {
+    kind: "agg";
+    fn: AggregateFunction;
+    expr: MetricExpr;
+} | {
+    kind: "case";
+    whens: {
+        when: MetricExpr;
+        then: MetricExpr;
+    }[];
+    else?: MetricExpr;
+} | {
+    kind: "ifnull";
+    left: MetricExpr;
+    right: MetricExpr;
+};
+export declare const col: (name: string) => MetricExpr;
+export declare const lit: (value: QueryValue) => MetricExpr;
+export declare const call: (fn: MetricFn, ...args: MetricExpr[]) => MetricExpr;
+export declare const bin: (op: MetricOp, left: MetricExpr, right: MetricExpr) => MetricExpr;
+export declare const agg: (fn: AggregateFunction, expr: MetricExpr) => MetricExpr;
+export declare const caseOf: (whens: {
+    when: MetricExpr;
+    then: MetricExpr;
+}[], elseExpr?: MetricExpr) => MetricExpr;
+export declare const ifnull: (left: MetricExpr, right: MetricExpr) => MetricExpr;
+/**
+ * Parcourt l'arbre et retourne les noeuds d'agrégat **sans** descendre dans
+ * leur expression interne (l'agrégat est opaque : `sum(sum(x))` n'existe pas).
+ */
+export declare function collectAggregates(expr: MetricExpr): MetricExpr[];

package/dist/semantic/filters/coerce.d.ts

@@ -0,0 +1,54 @@
+/**
+ * La coercition des valeurs de filtre.
+ *
+ * Un filtre compare une valeur de champ à une valeur saisie par
+ * l'utilisateur. Les deux ne sont pas forcément du même type : une
+ * colonne `TEXT` porte « 42 », un formulaire saisit `42`, une API envoie
+ * `"42"`. Sans coercition, la comparaison échoue et le filtre ne retient
+ * rien.
+ *
+ * La coercition ne s'applique **que** quand le type du champ est connu. Un
+ * filtre historique, persisté en base, ne porte pas de type : sa sémantique
+ * est alors laissée strictement inchangée, pour que les filtres déjà
+ * enregistrés continuent de retenir exactement les mêmes lignes.
+ */
+import type { FilterFieldType, QueryValue } from "./types";
+/** Le résultat d'une coercition : la valeur convertie, ou l'échec. */
+export type CoercionResult = {
+    ok: true;
+    value: QueryValue;
+} | {
+    ok: false;
+};
+/**
+ * Convertit une valeur dans le type du champ.
+ *
+ * Une valeur nulle ou absente est **toujours** valide : elle vaut `null`.
+ * Une valeur non convertible fait échouer la coercition.
+ */
+export declare function tryCoerceFilterValue(type: FilterFieldType, value: unknown): CoercionResult;
+/**
+ * Convertit une valeur dans le type du champ, ou renvoie `null` si la
+ * conversion échoue. `null` est aussi la valeur nulle : appelez
+ * `tryCoerceFilterValue` quand la distinction importe.
+ */
+export declare function coerceFilterValue(type: FilterFieldType, value: unknown): QueryValue | null;
+/**
+ * Prépare la comparaison des deux côtés d'un filtre.
+ *
+ * Sans type de champ, les valeurs sont reprises telles quelles : c'est la
+ * sémantique historique. Avec un type, les deux côtés sont convertis ; si
+ * l'une des deux conversions échoue, la comparaison n'est pas possible.
+ */
+export declare function coerceComparison(type: FilterFieldType | undefined, left: unknown, right: unknown): {
+    left: QueryValue;
+    right: QueryValue;
+    comparable: boolean;
+};
+/**
+ * Le jour UTC d'une valeur temporelle, au format `YYYY-MM-DD`.
+ *
+ * Les opérateurs temporels (`on`) comparent des **jours**, pas des instants :
+ * une donnée du 20 octobre à 08:00 appartient au 20 octobre.
+ */
+export declare function toUtcDay(value: unknown): string | null;

package/dist/semantic/filters/evaluate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * L'évaluation des filtres, en mémoire.
+ *
+ * Ce module est le pendant de `semantic/compiler.ts` : les deux doivent
+ * retenir exactement les mêmes lignes. Le compilateur produit du SQL, ce
+ * module produit un booléen ; ils lisent le même `QueryFilter` et appliquent
+ * la même sémantique.
+ *
+ * La sémantique des douze opérateurs historiques est **figée** : des filtres
+ * sont persistés en base (`semantic_segments.filter`,
+ * `semantic_metrics.filters`) et doivent continuer de retenir les mêmes
+ * lignes. Un filtre qui ne porte pas de `fieldType` est donc comparé
+ * « à la brute », exactement comme avant l'extension J6.
+ */
+import type { ResolvedParameters } from "../parameters/resolve";
+import type { QueryFilter, QueryRow } from "./types";
+/**
+ * Évalue un filtre sur une ligne.
+ *
+ * Un opérateur inconnu lève une erreur : le filtre porte souvent
+ * l'isolation du tenant, et un prédicat neutre exposerait les données de
+ * tous les tenants.
+ */
+export declare function evaluateFilter(row: QueryRow, filter: QueryFilter, options?: {
+    now?: Date;
+    parameters?: ResolvedParameters;
+}): boolean;

package/dist/semantic/filters/operators.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Le catalogue des opérateurs de filtre.
+ *
+ * Ce fichier est une **réécriture** du catalogue d'opérateurs de Metabase
+ * (`frontend/src/metabase-lib/v1/operators/constants.ts`).
+ * Rien n'y est repris tel quel : l'amont exprime ses opérateurs avec des
+ * symboles (`=`, `is-null`, `does-not-contain`) et un système d'arguments
+ * dynamiques (`validArgumentsFilters`) ; LynxSEO conserve ses **propres noms**
+ * d'opérateurs, parce que des filtres sont persistés en base et que l'API
+ * publique du moteur ne peut pas changer.
+ *
+ * Ce que le port apporte : chaque opérateur sait **quels types de champ** il
+ * accepte, **combien d'arguments** il prend, et à quelle catégorie
+ * d'interface il appartient. C'est ce qui permet à un formulaire de proposer
+ * le bon opérateur, et à l'évaluateur et au compilateur SQL de s'accorder.
+ */
+import type { FilterFieldType, FilterOperator } from "./types";
+/** La catégorie d'interface d'un opérateur. */
+export type FilterOperatorCategory = "comparison" | "text" | "emptiness" | "membership" | "range" | "temporal";
+/** La description d'un opérateur. */
+export interface FilterOperatorSpec {
+    /** L'identifiant de l'opérateur, tel qu'il est persisté. */
+    name: FilterOperator;
+    /** Le libellé affiché dans l'interface, en français. */
+    label: string;
+    /** Les types de champ compatibles avec l'opérateur. */
+    fieldTypes: readonly FilterFieldType[];
+    /** Le nombre d'arguments attendus (0, 1 ou 2). */
+    arity: 0 | 1 | 2;
+    /** La catégorie d'interface. */
+    category: FilterOperatorCategory;
+    /** L'opérateur compare à une collection de valeurs. */
+    multi?: boolean;
+    /** L'opérateur textuel distingue la casse. */
+    caseSensitive?: boolean;
+}
+/**
+ * Le catalogue. L'ordre est celui d'affichage : d'abord l'égalité, puis les
+ * comparaisons ordonnées, puis le texte, puis l'emptiness, puis les
+ * collections, puis les plages, puis le temporel.
+ */
+export declare const FILTER_OPERATOR_SPECS: readonly FilterOperatorSpec[];
+/**
+ * La description d'un opérateur.
+ *
+ * Un opérateur inconnu est une **erreur** : le filtre porte souvent
+ * l'isolation du tenant, et un opérateur méconnu ne doit jamais se dégrader
+ * en prédicat neutre.
+ */
+export declare function filterOperatorSpec(name: FilterOperator): FilterOperatorSpec;
+/**
+ * Les opérateurs compatibles avec un type de champ, dans l'ordre du
+ * catalogue.
+ */
+export declare function operatorsForFieldType(type: FilterFieldType): readonly FilterOperatorSpec[];

package/dist/semantic/filters/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Le vocabulaire des filtres du noyau sémantique.
+ *
+ * Ces types sont extraits de `seo-query-builder.ts` pour que le module des
+ * filtres (`filters/operators.ts`, `filters/coerce.ts`, `filters/evaluate.ts`)
+ * n'ait aucune dépendance vers `seo-query-builder.ts` : sans cela, le
+ * re-export du filtre évalué créerait un cycle d'imports.
+ *
+ * `seo-query-builder.ts` ré-exporte tout ce qui est déclaré ici : l'API
+ * publique du moteur (`packages/lynx-seo-engine/src/index.ts` fait
+ * `export * from "./seo-query-builder"`) reste donc inchangée.
+ */
+/**
+ * Le type d'un champ filtrable. Aligné sur `SemanticFieldType` du noyau
+ * sémantique : les deux listes décrivent le même système.
+ */
+export type FilterFieldType = "string" | "number" | "date" | "boolean";
+/**
+ * Les opérateurs de filtre.
+ *
+ * Les douze premiers sont historiques : leur sémantique est **figée** et ne
+ * doit pas changer, parce que des filtres sont persistés en base
+ * (`semantic_segments.filter`, `semantic_metrics.filters`). Les huit
+ * suivants sont l'extension J6.
+ */
+export declare const FILTER_OPERATORS: readonly ["equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "greater_than", "greater_than_or_equal", "less_than", "less_than_or_equal", "is_empty", "is_not_empty", "in", "not_in", "is_null", "is_not_null", "between", "before", "after", "on"];
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+/** Une valeur scalaire de cellule ou de filtre. */
+export type QueryValue = string | number | boolean | null;
+/** Une ligne de résultat, indexée par nom de champ. */
+export type QueryRow = Record<string, QueryValue>;
+/**
+ * Un filtre posé sur un champ.
+ *
+ * `value` est un scalaire pour les opérateurs unaires, un **tableau** pour
+ * `in` / `not_in`, et un couple `[borne, borne]` pour `between`.
+ */
+export interface QueryFilter {
+    field: string;
+    operator: FilterOperator;
+    value?: QueryValue | QueryValue[];
+    /**
+     * Type du champ filtré. Quand il est absent, la coercition est best-effort
+     * (comparaison directe). Quand il est présent, la valeur est convertie
+     * avant comparaison.
+     */
+    fieldType?: FilterFieldType;
+    /**
+     * Période relative, pour les filtres temporels. Quand elle est présente,
+     * elle remplace `value` et produit un intervalle `[début, fin)`.
+     */
+    period?: RelativePeriod;
+    /**
+     * Nom du paramètre qui fournit la valeur du filtre. Quand il est présent,
+     * la valeur du paramètre l'emporte sur `value`.
+     */
+    parameter?: string;
+    /**
+     * Nom du paramètre qui fournit la borne haute d'un `between`.
+     */
+    parameterTo?: string;
+}
+/** Les unités calendaires supportées par les périodes relatives. */
+export declare const RELATIVE_UNITS: readonly ["day", "week", "month", "quarter", "year"];
+export type RelativeUnit = (typeof RELATIVE_UNITS)[number];
+/**
+ * Une période relative, exprimée en unités calendaires.
+ *
+ * `value` est négatif pour le passé : `-7` avec `unit: "day"` signifie
+ * « les sept derniers jours complets ». La résolution en intervalle est faite
+ * par `semantic/periods/relative.ts`.
+ */
+export interface RelativePeriod {
+    unit: RelativeUnit;
+    value: number;
+    offsetUnit?: RelativeUnit;
+    offsetValue?: number;
+    includeCurrent?: boolean;
+}

package/dist/semantic/hogql-transpiler.d.ts

@@ -0,0 +1,49 @@
+/**
+ * HogQL-style SQL ergonomics for LynxSEO.
+ *
+ * - Dot-property access (`properties.utm_source`, `props.revenue`) is rewritten
+ *   to the dialect's JSON extraction function.
+ * - `cohort('name')` expands to a visitor-id subquery. Custom subqueries can be
+ *   supplied by the caller; otherwise a built-in `active_users` cohort or a
+ *   property-based convention is used.
+ * - `formatSqlStatement` is re-exported for the SQL editor toolbar.
+ *
+ * Rewrites never touch string literals, quoted identifiers or comments.
+ */
+export { formatSqlStatement } from "./sql-formatter";
+export type TargetSqlDialect = "clickhouse" | "postgres" | "sqlite";
+export interface HogqlTranspileOptions {
+    /** Physical JSON column. Defaults to `properties`; LynxSEO ClickHouse uses `props`. */
+    jsonColumn?: string;
+    /** Logical names accepted in dot notation. Defaults to properties and props. */
+    propertyColumns?: readonly string[];
+}
+export interface CohortMacroOptions extends HogqlTranspileOptions {
+    table?: string;
+    visitorColumn?: string;
+    timeColumn?: string;
+    botColumn?: string;
+    jsonProperty?: string;
+}
+export interface PrepareHogqlSqlOptions extends CohortMacroOptions {
+    dialect?: TargetSqlDialect;
+    cohortSubqueries?: Record<string, string>;
+}
+/**
+ * Rewrites dot notation outside strings/comments.
+ * `properties.utm_source` -> `JSONExtractString(properties, 'utm_source')`
+ * (ClickHouse), `properties->>'utm_source'` (Postgres), `json_extract(...)`
+ * (SQLite). Qualified references such as `t.properties.x` are left untouched.
+ */
+export declare function transpileHogqlProperties(sql: string, dialect?: TargetSqlDialect, options?: HogqlTranspileOptions): string;
+/**
+ * Expands PostHog-style `cohort('name')` macros.
+ *
+ * Resolution order: caller-supplied subquery, built-in `active_users`, then a
+ * property-based convention (`<jsonColumn>.cohort = 'name'`). The generated
+ * subquery selects the dialect's visitor column so the macro can be used as
+ * `visitor_id IN cohort('...')`.
+ */
+export declare function expandCohortMacro(sql: string, cohortSubqueries?: Record<string, string>, dialect?: TargetSqlDialect, options?: CohortMacroOptions): string;
+/** Applies cohort macros first, then property dot-notation transpilation. */
+export declare function prepareHogqlSql(sql: string, options?: PrepareHogqlSqlOptions): string;

package/dist/semantic/metadata.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Le modele de metadonnees : champ, table, base.
+ *
+ * Ce fichier est une **reecriture** du modele de metadonnees de Metabase
+ * (`frontend/src/metabase-lib/v1/metadata/{Field,Table,Database}.ts`). Rien
+ * n'y est repris tel quel : l'amont modélise des references de champ
+ * (`["field", 42, {"base-type": "type/Text"}]`), des cles etrangeres et des
+ * options de dimension ; LynxSEO n'a pas de store de metadonnees, donc ses
+ * tables sont decrites par un catalogue derive des schemas de l'application.
+ *
+ * Ce que le port apporte : un **type semantique** de champ, distinct du type
+ * de stockage. Un `text` peut etre un libelle, une URL, un email ou un
+ * identifiant ; le type de stockage dit comment la valeur est comparee, le
+ * type semantique dit comment elle doit etre presentee et segmentee. C'est ce
+ * qui permet a l'interface de proposer des dimensions pertinentes sans
+ * deviner le role d'une colonne.
+ */
+import type { SemanticFieldType, SemanticSourceKind } from "./types";
+/**
+ * Le role semantique d'un champ.
+ *
+ * Sous-ensemble de la hierarchie de Metabase (`metabase-types/api`),
+ * reecrite pour LynxSEO : on ne garde que les roles qui se traduisent par un
+ * traitement different en requete ou en presentation.
+ */
+export type SemanticFieldSemanticType = 
+/** Peu de valeurs distinctes : pays, appareil, canal. */
+"category"
+/** Texte libre, non segmentable. */
+ | "text"
+/** Libelle d'une entite. */
+ | "title"
+/** Adresse d'une page. */
+ | "url"
+/** Adresse de courrier. */
+ | "email"
+/** Nombre, mesure ou compte. */
+ | "number"
+/** Ratio presente en pourcentage. */
+ | "percentage"
+/** Montant. */
+ | "currency"
+/** Date sans heure. */
+ | "date"
+/** Date et heure. */
+ | "datetime"
+/** Instant horodate. */
+ | "timestamp"
+/** Booleen. */
+ | "boolean"
+/** Identifiant. */
+ | "id"
+/** Cle etrangere vers une autre table. */
+ | "fk"
+/** Role inconnu : le type de stockage fait foi. */
+ | "unknown";
+/**
+ * Un champ d'une table.
+ *
+ * Un champ est une **colonne physique**. La dimension d'un modele semantique
+ * est une expression qui peut referencing un champ, mais aussi une agregation
+ * ou une transformation : les deux niveaux restent distincts.
+ */
+export interface SemanticField {
+    /** Le nom de la colonne, tel qu'il existe en base. */
+    name: string;
+    /** Le type de stockage, compare et compile. */
+    type: SemanticFieldType;
+    /** Le role semantique, s'il est connu. */
+    semanticType?: SemanticFieldSemanticType;
+    /** Le type de la base, tel qu'il est declare (`TEXT`, `INTEGER`...). */
+    databaseType?: string;
+    /** La description, si elle est connue. */
+    description?: string;
+    /** La table qui porte ce champ. */
+    table?: string;
+    /** Le champ fait partie de la cle primaire. */
+    primaryKey?: boolean;
+}
+/** Une table : un ensemble nomme de champs. */
+export interface SemanticTable {
+    /** Le nom de la table, tel qu'il existe en base. */
+    name: string;
+    /** La description, si elle est connue. */
+    description?: string;
+    /** Les champs de la table. */
+    fields: SemanticField[];
+    /** Les noms des champs de la cle primaire. */
+    primaryKey?: string[];
+}
+/** Une base : un ensemble nomme de tables. */
+export interface SemanticDatabase {
+    /** L'identifiant de la base. */
+    id: string;
+    /** Le libelle de la base. */
+    name: string;
+    /** Le dialecte SQL de la base. */
+    dialect: SemanticSourceKind;
+    /** Les tables de la base. */
+    tables: SemanticTable[];
+}
+/**
+ * Le type semantique correspondant a un type de stockage.
+ *
+ * La correspondance est celle par defaut : un `text` est un texte libre tant
+ * qu'aucune autre information ne dit le contraire. Un champ dont le nom ou la
+ * description designe un role plus precis (une URL, un email, un identifiant)
+ * voit son type semantique corrige a la construction du catalogue.
+ */
+export declare function semanticTypeOf(type: SemanticFieldType): SemanticFieldSemanticType;
+/**
+ * Le type a utiliser pour la dimension semantique d'un champ.
+ *
+ * Le type de stockage ne suffit pas : les horodatages de LynxSEO sont stockes
+ * en texte ISO (`created_at` est un `text`), et un montant ou un pourcentage
+ * est un nombre. C'est le role semantique qui dit comment comparer la valeur,
+ * donc c'est lui qui fait foi pour une dimension.
+ */
+export declare function effectiveFieldType(field: SemanticField): SemanticFieldType;
+/** Recherche une table par son nom, sans distinction de casse. */
+export declare function findTable(database: SemanticDatabase, name: string): SemanticTable | undefined;
+/** Recherche un champ par son nom, sans distinction de casse. */
+export declare function findField(table: SemanticTable, name: string): SemanticField | undefined;
+/**
+ * Les champs d'une table, indexes par nom.
+ *
+ * L'index est construit a la demande : une table du catalogue est petite, et
+ * la construction a chaque appel evite de porter un cache invalide quand le
+ * catalogue change.
+ */
+export declare function tableFieldsMap(table: SemanticTable): Record<string, SemanticField>;
+/**
+ * Une description courte d'un champ, pour l'interface.
+ *
+ * Exemple : `url_path — texte (chemin de la page)`. La partie entre
+ * parentheses n'apparait que si le type semantique ajoute une information a
+ * celle du type de stockage.
+ */
+export declare function describeField(field: SemanticField): string;

package/dist/semantic/parameters/filter-parameter.d.ts

@@ -0,0 +1,19 @@
+import type { QueryFilter } from "../filters/types";
+import type { ResolvedParameters } from "./resolve";
+declare const FIELD_TYPE_BY_PARAMETER_TYPE: {
+    readonly string: "string";
+    readonly number: "number";
+    readonly boolean: "boolean";
+    readonly date: "date";
+    readonly category: "string";
+};
+/**
+ * Remplace la valeur d'un filtre par celle d'un parametre.
+ *
+ * Le filtre conserve sa reference au parametre (`parameter`, `parameterTo`)
+ * pour rester relisible, mais sa valeur effective est copiee dans `value` :
+ * les deux backends — compilation SQL et evaluation memoire — consomment la
+ * meme forme resolue, donc ils ne peuvent pas diverger.
+ */
+export declare function resolveParameterFilter(filter: QueryFilter, parameters: ResolvedParameters): QueryFilter;
+export { FIELD_TYPE_BY_PARAMETER_TYPE };

package/dist/semantic/parameters/json.d.ts

@@ -0,0 +1,11 @@
+import { type SemanticParameter } from "./types";
+/**
+ * Relit les parametres d'un modele depuis leur forme serialisee.
+ *
+ * Une colonne corrompue fait echouer la lecture du modele : un `baseSql` qui
+ * reference `{{country}}` sans declaration echouerait plus tard, avec un
+ * message qui ne designe pas la cause.
+ */
+export declare function parseSemanticParameters(raw: string | null | undefined): SemanticParameter[];
+/** Serialise les parametres d'un modele. Une liste vide ne produit rien. */
+export declare function stringifySemanticParameters(parameters?: SemanticParameter[]): string | null;