trilium-api 1.0.1 → 1.0.2

package/dist/index.cjs

@@ -0,0 +1,307 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TriliumMapper: () => TriliumMapper,
+  buildSearchQuery: () => buildSearchQuery,
+  createClient: () => client_default,
+  createTriliumClient: () => createTriliumClient,
+  transforms: () => transforms
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
+
+// src/mapper.ts
+function buildSearchQuery(helpers) {
+  if ("AND" in helpers && Array.isArray(helpers.AND)) {
+    return helpers.AND.map((h) => {
+      const query = buildSearchQuery(h);
+      return query.includes(" OR ") ? `(${query})` : query;
+    }).join(" AND ");
+  }
+  if ("OR" in helpers && Array.isArray(helpers.OR)) {
+    return helpers.OR.map((h) => {
+      const query = buildSearchQuery(h);
+      return query.includes(" AND ") || query.includes(" OR ") ? `(${query})` : query;
+    }).join(" OR ");
+  }
+  if ("NOT" in helpers && helpers.NOT !== void 0) {
+    const notValue = helpers.NOT;
+    if (typeof notValue === "object" && notValue !== null && !("value" in notValue)) {
+      const query = buildSearchQuery(notValue);
+      return `not(${query})`;
+    }
+    throw new Error("NOT operator requires a query object, not a simple value");
+  }
+  const parts = [];
+  for (const [key, value] of Object.entries(helpers)) {
+    if (value === void 0 || value === null) continue;
+    if (key.startsWith("#")) {
+      const labelName = key.slice(1);
+      if (labelName.includes(".")) {
+        if (typeof value === "object" && "value" in value) {
+          const operator = value.operator || "=";
+          const val = typeof value.value === "string" ? `'${value.value}'` : value.value;
+          parts.push(`${key} ${operator} ${val}`);
+        } else if (typeof value === "string") {
+          parts.push(`${key} = '${value}'`);
+        } else {
+          parts.push(`${key} = ${value}`);
+        }
+      } else {
+        if (value === true) {
+          parts.push(`#${labelName}`);
+        } else if (value === false) {
+          parts.push(`#!${labelName}`);
+        } else if (typeof value === "object" && "value" in value) {
+          const operator = value.operator || "=";
+          const val = typeof value.value === "string" ? `'${value.value}'` : value.value;
+          parts.push(`#${labelName} ${operator} ${val}`);
+        } else if (typeof value === "string") {
+          parts.push(`#${labelName} = '${value}'`);
+        } else {
+          parts.push(`#${labelName} = ${value}`);
+        }
+      }
+    } else if (key.startsWith("~")) {
+      const relationName = key.slice(1);
+      if (relationName.includes(".")) {
+        if (typeof value === "object" && "value" in value) {
+          const operator = value.operator || "=";
+          const val = typeof value.value === "string" ? `'${value.value}'` : value.value;
+          parts.push(`${key} ${operator} ${val}`);
+        } else if (typeof value === "string") {
+          parts.push(`${key} = '${value}'`);
+        } else {
+          parts.push(`${key} = ${value}`);
+        }
+      } else {
+        if (typeof value === "object" && "value" in value) {
+          const operator = value.operator || "*=*";
+          const val = typeof value.value === "string" ? `'${value.value}'` : value.value;
+          parts.push(`${key} ${operator} ${val}`);
+        } else if (typeof value === "string") {
+          parts.push(`${key} *=* '${value}'`);
+        }
+      }
+    } else {
+      const path = key.startsWith("note.") ? key : `note.${key}`;
+      if (typeof value === "object" && "value" in value) {
+        const operator = value.operator || "=";
+        const val = typeof value.value === "string" ? `'${value.value}'` : value.value;
+        parts.push(`${path} ${operator} ${val}`);
+      } else if (typeof value === "string") {
+        parts.push(`${path} = '${value}'`);
+      } else if (typeof value === "boolean") {
+        parts.push(`${path} = ${value}`);
+      } else {
+        parts.push(`${path} = ${value}`);
+      }
+    }
+  }
+  return parts.join(" AND ");
+}
+var TriliumMapper = class {
+  /** The mapping configuration for this mapper */
+  config;
+  /**
+   * Creates a new TriliumMapper instance
+   * @param config - The mapping configuration defining how to map note fields to the target type
+   */
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Merges multiple mapping configurations into a single configuration
+   * Later configs override earlier ones for the same keys
+   * Supports merging configs from base types into derived types
+   * 
+   * @template T - The target type for the merged configuration
+   * @param configs - One or more mapping configurations to merge
+   * @returns A new merged mapping configuration
+   * 
+   * @example
+   * const merged = TriliumMapper.merge<BlogPost>(
+   *   StandardNoteMapping,
+   *   BlogSpecificMapping,
+   *   OverrideMapping
+   * );
+   */
+  static merge(...configs) {
+    return Object.assign({}, ...configs);
+  }
+  /**
+   * Maps one or more Trilium notes to the target type
+   * @param noteOrNotes - A single note or array of notes to map
+   * @returns A single mapped object or array of mapped objects
+   */
+  map(noteOrNotes) {
+    return Array.isArray(noteOrNotes) ? noteOrNotes.map((note) => this.mapSingle(note)) : this.mapSingle(noteOrNotes);
+  }
+  /**
+   * Maps a single note to the target type using the configured field mappings
+   * Processes in two passes: first regular fields, then computed fields
+   * @param note - The Trilium note to map
+   * @returns The mapped object
+   * @throws Error if a required field is missing
+   * @private
+   */
+  mapSingle(note) {
+    const result = {};
+    const computedFields = [];
+    for (const [key, fieldMapping] of Object.entries(this.config)) {
+      if (!fieldMapping) continue;
+      if (typeof fieldMapping === "object" && "computed" in fieldMapping) {
+        computedFields.push([key, fieldMapping]);
+        continue;
+      }
+      const mapping = typeof fieldMapping === "string" ? { from: fieldMapping } : fieldMapping;
+      let value = typeof mapping.from === "function" ? mapping.from(note) : this.extractValue(note, mapping.from);
+      if (mapping.transform) {
+        value = mapping.transform(value, note);
+      }
+      if (value === void 0 && mapping.default !== void 0) {
+        value = mapping.default;
+      }
+      if (mapping.required && value === void 0) {
+        throw new Error(`Required field '${String(key)}' missing from note ${note.noteId} (${note.title})`);
+      }
+      result[key] = value;
+    }
+    for (const [key, mapping] of computedFields) {
+      let value = mapping.computed(result, note);
+      if (value === void 0 && mapping.default !== void 0) {
+        value = mapping.default;
+      }
+      result[key] = value;
+    }
+    return result;
+  }
+  /**
+   * Extracts a value from a note using a string path
+   * 
+   * Supports:
+   * - Label attributes: #labelName
+   * - Relation attributes: ~relationName
+   * - Note properties: note.property.path
+   * 
+   * @param note - The Trilium note to extract from
+   * @param path - The path string indicating where to extract the value
+   * @returns The extracted value or undefined if not found
+   * @private
+   * 
+   * @example
+   * extractValue(note, 'note.title') // => note.title
+   * extractValue(note, '#slug')      // => label attribute 'slug'
+   * extractValue(note, '~template')  // => relation attribute 'template'
+   */
+  extractValue(note, path) {
+    if (!path) return void 0;
+    if (path.startsWith("#")) {
+      return note.attributes?.find((attr) => attr.type === "label" && attr.name === path.slice(1))?.value;
+    }
+    if (path.startsWith("~")) {
+      return note.attributes?.find((attr) => attr.type === "relation" && attr.name === path.slice(1))?.value;
+    }
+    if (path.startsWith("note.")) {
+      return path.slice(5).split(".").reduce((obj, key) => obj?.[key], note);
+    }
+    return void 0;
+  }
+};
+var transforms = {
+  /** Convert to number */
+  number: (value) => {
+    if (value === void 0 || value === null || value === "") return void 0;
+    const num = Number(value);
+    return isNaN(num) ? void 0 : num;
+  },
+  /** Convert to boolean */
+  boolean: (value) => {
+    if (value === void 0 || value === null) return void 0;
+    if (typeof value === "boolean") return value;
+    if (typeof value === "string") {
+      const lower = value.toLowerCase();
+      if (lower === "true" || lower === "1" || lower === "yes") return true;
+      if (lower === "false" || lower === "0" || lower === "no") return false;
+    }
+    return void 0;
+  },
+  /** Split comma-separated string into array */
+  commaSeparated: (value) => {
+    if (value === void 0 || value === null || value === "") return void 0;
+    if (typeof value !== "string") return void 0;
+    return value.split(",").map((s) => s.trim()).filter(Boolean);
+  },
+  /** Parse JSON string */
+  json: (value) => {
+    if (value === void 0 || value === null || value === "") return void 0;
+    if (typeof value !== "string") return void 0;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return void 0;
+    }
+  },
+  /** Parse date string */
+  date: (value) => {
+    if (value === void 0 || value === null || value === "") return void 0;
+    const date = new Date(String(value));
+    return isNaN(date.getTime()) ? void 0 : date;
+  },
+  /** Trim whitespace from string */
+  trim: (value) => {
+    if (value === void 0 || value === null) return void 0;
+    return String(value).trim() || void 0;
+  }
+};
+
+// src/client.ts
+function createTriliumClient(config) {
+  const baseUrl = config.baseUrl.endsWith("/") ? config.baseUrl.slice(0, -1) : config.baseUrl;
+  return (0, import_openapi_fetch.default)({
+    baseUrl: `${baseUrl}/etapi`,
+    headers: {
+      Authorization: config.apiKey
+    }
+  });
+}
+var client_default = createTriliumClient;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TriliumMapper,
+  buildSearchQuery,
+  createClient,
+  createTriliumClient,
+  transforms
+});

package/{src/generated/trilium.d.ts → dist/index.d.cts}

@@ -1,9 +1,11 @@
+import * as openapi_fetch from 'openapi-fetch';
+
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
  */
 
-export interface paths {
+interface paths {
     "/create-note": {
         parameters: {
             query?: never;
@@ -450,8 +452,7 @@ export interface paths {
         trace?: never;
     };
 }
-export type webhooks = Record<string, never>;
-export interface components {
+interface components {
     schemas: {
         CreateNoteDef: {
             /** @description Note ID of the parent note in the tree */
@@ -644,8 +645,7 @@ export interface components {
     headers: never;
     pathItems: never;
 }
-export type $defs = Record<string, never>;
-export interface operations {
+interface operations {
     createNote: {
         parameters: {
             query?: never;
@@ -1756,3 +1756,315 @@ export interface operations {
         };
     };
 }
+
+/**
+ * Trilium Note Mapper and Search Query Builder
+ *
+ * Provides utilities for mapping Trilium notes to strongly-typed objects
+ * and building type-safe search queries.
+ */
+
+/**
+ * Comparison operators for search conditions
+ */
+type ComparisonOperator = '=' | '!=' | '<' | '<=' | '>' | '>=' | '*=' | '=*' | '*=*';
+/**
+ * A value with an optional comparison operator
+ */
+interface ConditionValue<T = string | number | boolean> {
+    value: T;
+    operator?: ComparisonOperator;
+}
+/**
+ * Simple value or condition with operator
+ */
+type SearchValue = string | number | boolean | ConditionValue;
+/**
+ * Base search conditions for labels, relations, and note properties.
+ * Use template literal keys for labels (#) and relations (~).
+ * Regular string keys are treated as note properties.
+ */
+type TriliumSearchConditions = {
+    /** Labels: use #labelName as key */
+    [key: `#${string}`]: SearchValue | undefined;
+} & {
+    /** Relations: use ~relationName as key */
+    [key: `~${string}`]: SearchValue | undefined;
+} & {
+    /** Note properties: use note.property as key or just property name */
+    [key: string]: SearchValue | undefined;
+};
+/**
+ * Logical operators for combining search conditions
+ */
+interface TriliumSearchLogical {
+    /** Combine multiple conditions with AND */
+    AND?: TriliumSearchHelpers[];
+    /** Combine multiple conditions with OR */
+    OR?: TriliumSearchHelpers[];
+    /** Negate a condition */
+    NOT?: TriliumSearchHelpers;
+}
+/**
+ * Complete search helpers combining conditions and logical operators.
+ * Can contain field conditions AND/OR logical operators.
+ */
+type TriliumSearchHelpers = TriliumSearchLogical | (TriliumSearchConditions & Partial<TriliumSearchLogical>);
+/**
+ * Builds a Trilium search query string from a structured helper object
+ *
+ * @param helpers - The search conditions and logical operators
+ * @returns A properly formatted Trilium search query string
+ *
+ * @example
+ * // Simple label search
+ * buildSearchQuery({ '#blog': true })
+ * // => '#blog'
+ *
+ * @example
+ * // Label with value
+ * buildSearchQuery({ '#status': 'published' })
+ * // => "#status = 'published'"
+ *
+ * @example
+ * // Complex AND/OR conditions
+ * buildSearchQuery({
+ *   AND: [
+ *     { '#blog': true },
+ *     { OR: [
+ *       { '#status': 'published' },
+ *       { '#status': 'featured' }
+ *     ]}
+ *   ]
+ * })
+ * // => "#blog AND (#status = 'published' OR #status = 'featured')"
+ *
+ * @example
+ * // Note properties with operators
+ * buildSearchQuery({
+ *   'note.type': 'text',
+ *   '#wordCount': { value: 1000, operator: '>=' }
+ * })
+ * // => "note.type = 'text' AND #wordCount >= 1000"
+ */
+declare function buildSearchQuery(helpers: TriliumSearchHelpers): string;
+/**
+ * Transform function that converts a raw value into the target type
+ * @template T - The target object type
+ * @template K - The specific key in the target type
+ */
+type TransformFunction<T, K extends keyof T> = (value: unknown, note: TriliumNote) => T[K] | undefined;
+/**
+ * Computed function that calculates a value from the partially mapped object
+ * @template T - The target object type
+ * @template K - The specific key in the target type
+ */
+type ComputedFunction<T, K extends keyof T> = (partial: Partial<T>, note: TriliumNote) => T[K] | undefined;
+/**
+ * Field mapping configuration for a single property
+ * Can be a simple string path, a detailed configuration object, or a computed value
+ *
+ * @template T - The target object type
+ * @template K - The specific key in the target type
+ *
+ * @example
+ * // Shorthand string path
+ * title: 'note.title'
+ *
+ * @example
+ * // Full configuration
+ * tags: {
+ *   from: '#tags',
+ *   transform: transforms.commaSeparated,
+ *   default: [],
+ *   required: false
+ * }
+ *
+ * @example
+ * // Computed value
+ * readTimeMinutes: {
+ *   computed: (partial) => Math.ceil((partial.wordCount || 0) / 200)
+ * }
+ */
+type FieldMapping<T, K extends keyof T = keyof T> = string | {
+    /** Source path (string) or extractor function */
+    from: string | ((note: TriliumNote) => unknown);
+    /** Optional transform function to convert the raw value */
+    transform?: TransformFunction<T, K>;
+    /** Default value if extraction returns undefined */
+    default?: T[K];
+    /** Whether this field is required (throws if missing) */
+    required?: boolean;
+} | {
+    /** Computed function that calculates value from other mapped fields */
+    computed: ComputedFunction<T, K>;
+    /** Default value if computed returns undefined */
+    default?: T[K];
+};
+/**
+ * Complete mapping configuration for a type
+ * Maps each property key to its field mapping configuration
+ *
+ * @template T - The target object type to map to
+ */
+type MappingConfig<T> = {
+    [K in keyof T]?: FieldMapping<T, K>;
+};
+/**
+ * Maps Trilium notes to strongly-typed objects using declarative field mappings
+ *
+ * Supports:
+ * - Direct property paths (note.title, note.noteId)
+ * - Label attributes (#labelName)
+ * - Relation attributes (~relationName)
+ * - Custom extractor functions
+ * - Transform functions
+ * - Computed values from other fields
+ * - Default values
+ * - Required field validation
+ *
+ * @template T - The target type to map notes to
+ *
+ * @example
+ * const mapper = new TriliumMapper<BlogPost>({
+ *   title: 'note.title',
+ *   slug: { from: '#slug', required: true },
+ *   wordCount: { from: '#wordCount', transform: transforms.number, default: 0 },
+ *   readTimeMinutes: {
+ *     computed: (partial) => Math.ceil((partial.wordCount || 0) / 200)
+ *   }
+ * });
+ *
+ * const posts = mapper.map(notes);
+ */
+declare class TriliumMapper<T> {
+    /** The mapping configuration for this mapper */
+    private readonly config;
+    /**
+     * Creates a new TriliumMapper instance
+     * @param config - The mapping configuration defining how to map note fields to the target type
+     */
+    constructor(config: MappingConfig<T>);
+    /**
+     * Merges multiple mapping configurations into a single configuration
+     * Later configs override earlier ones for the same keys
+     * Supports merging configs from base types into derived types
+     *
+     * @template T - The target type for the merged configuration
+     * @param configs - One or more mapping configurations to merge
+     * @returns A new merged mapping configuration
+     *
+     * @example
+     * const merged = TriliumMapper.merge<BlogPost>(
+     *   StandardNoteMapping,
+     *   BlogSpecificMapping,
+     *   OverrideMapping
+     * );
+     */
+    static merge<T>(...configs: (Partial<MappingConfig<T>> | MappingConfig<unknown>)[]): MappingConfig<T>;
+    /**
+     * Maps a single note to the target type
+     * @param note - The Trilium note to map
+     * @returns The mapped object of type T
+     */
+    map(note: TriliumNote): T;
+    /**
+     * Maps an array of notes to the target type
+     * @param notes - The Trilium notes to map
+     * @returns An array of mapped objects of type T
+     */
+    map(notes: TriliumNote[]): T[];
+    /**
+     * Maps a single note to the target type using the configured field mappings
+     * Processes in two passes: first regular fields, then computed fields
+     * @param note - The Trilium note to map
+     * @returns The mapped object
+     * @throws Error if a required field is missing
+     * @private
+     */
+    private mapSingle;
+    /**
+     * Extracts a value from a note using a string path
+     *
+     * Supports:
+     * - Label attributes: #labelName
+     * - Relation attributes: ~relationName
+     * - Note properties: note.property.path
+     *
+     * @param note - The Trilium note to extract from
+     * @param path - The path string indicating where to extract the value
+     * @returns The extracted value or undefined if not found
+     * @private
+     *
+     * @example
+     * extractValue(note, 'note.title') // => note.title
+     * extractValue(note, '#slug')      // => label attribute 'slug'
+     * extractValue(note, '~template')  // => relation attribute 'template'
+     */
+    private extractValue;
+}
+/**
+ * Common transform functions for use with TriliumMapper
+ */
+declare const transforms: {
+    /** Convert to number */
+    number: (value: unknown) => number | undefined;
+    /** Convert to boolean */
+    boolean: (value: unknown) => boolean | undefined;
+    /** Split comma-separated string into array */
+    commaSeparated: (value: unknown) => string[] | undefined;
+    /** Parse JSON string */
+    json: <T>(value: unknown) => T | undefined;
+    /** Parse date string */
+    date: (value: unknown) => Date | undefined;
+    /** Trim whitespace from string */
+    trim: (value: unknown) => string | undefined;
+};
+
+type TriliumNote = components['schemas']['Note'];
+type TriliumBranch = components['schemas']['Branch'];
+type TriliumAttribute = components['schemas']['Attribute'];
+type TriliumAttachment = components['schemas']['Attachment'];
+type TriliumAppInfo = components['schemas']['AppInfo'];
+
+interface TriliumClientConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+/**
+ * Create a type-safe Trilium API client
+ *
+ * @example
+ * ```ts
+ * const client = createTriliumClient({
+ *   baseUrl: 'http://localhost:37840',
+ *   apiKey: 'your-etapi-token'
+ * });
+ *
+ * // Get app info
+ * const { data, error } = await client.GET('/app-info');
+ *
+ * // Get a note by ID
+ * const { data: note } = await client.GET('/notes/{noteId}', {
+ *   params: { path: { noteId: 'root' } }
+ * });
+ *
+ * // Create a note
+ * const { data: newNote } = await client.POST('/notes', {
+ *   body: {
+ *     parentNoteId: 'root',
+ *     title: 'My Note',
+ *     type: 'text',
+ *     content: '<p>Hello World</p>'
+ *   }
+ * });
+ *
+ * // Search notes
+ * const { data: searchResults } = await client.GET('/notes', {
+ *   params: { query: { search: '#blog' } }
+ * });
+ * ```
+ */
+declare function createTriliumClient(config: TriliumClientConfig): openapi_fetch.Client<paths, `${string}/${string}`>;
+
+export { type ComparisonOperator, type ComputedFunction, type ConditionValue, type FieldMapping, type MappingConfig, type SearchValue, type TransformFunction, type TriliumAppInfo, type TriliumAttachment, type TriliumAttribute, type TriliumBranch, type TriliumClientConfig, TriliumMapper, type TriliumNote, type TriliumSearchConditions, type TriliumSearchHelpers, type TriliumSearchLogical, buildSearchQuery, type components, createTriliumClient as createClient, createTriliumClient, type operations, type paths, transforms };