trilium-api 1.0.1 → 1.0.4

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

@@ -1,9 +1,11 @@
+import { Client } 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,470 @@ 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;
+/**
+ * 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 - accepts any input type */
+    transform?: (value: any, note: TriliumNote) => T[K] | undefined;
+    /** 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 */
+    readonly config: MappingConfig<T>;
+    /**
+     * 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;
+};
+/**
+ * Standard note fields that all mapped types must include.
+ * Extend this interface when creating your own mapped types.
+ *
+ * @example
+ * ```ts
+ * interface BlogPost extends StandardNote {
+ *   slug: string;
+ *   published: boolean;
+ * }
+ * ```
+ */
+interface StandardNote {
+    /** The unique note ID */
+    id: string;
+    /** The note title */
+    title: string;
+    /** UTC date when the note was created */
+    dateCreatedUtc: Date;
+    /** UTC date when the note was last modified */
+    dateLastModifiedUtc: Date;
+}
+/**
+ * Standard mapping configuration for StandardNote fields.
+ * Use with TriliumMapper.merge() to create mappings for types extending StandardNote.
+ *
+ * @example
+ * ```ts
+ * interface BlogPost extends StandardNote {
+ *   slug: string;
+ *   published: boolean;
+ * }
+ *
+ * const blogMapping = TriliumMapper.merge<BlogPost>(
+ *   StandardNoteMapping,
+ *   {
+ *     slug: '#slug',
+ *     published: { from: '#published', transform: transforms.boolean, default: false },
+ *   }
+ * );
+ * ```
+ */
+declare const StandardNoteMapping: MappingConfig<StandardNote>;
+/**
+ * Helper type for defining custom field mappings.
+ * Use this when defining mappings for types that extend StandardNote.
+ * It automatically excludes StandardNote fields since they're auto-merged.
+ *
+ * @template T - Your custom type that extends StandardNote
+ *
+ * @example
+ * ```ts
+ * interface BlogPost extends StandardNote {
+ *   slug: string;
+ *   published: boolean;
+ * }
+ *
+ * // Clean type - no need for verbose Omit<>
+ * const blogMapping: CustomMapping<BlogPost> = {
+ *   slug: '#slug',
+ *   published: { from: '#published', transform: transforms.boolean, default: false },
+ * };
+ *
+ * const { data } = await client.searchAndMap<BlogPost>({
+ *   query: '#blog',
+ *   mapping: blogMapping,
+ * });
+ * ```
+ */
+type CustomMapping<T extends StandardNote> = MappingConfig<Omit<T, keyof StandardNote>>;
+
+/**
+ * Trilium API Client using openapi-fetch
+ *
+ * This provides a type-safe client for the Trilium ETAPI.
+ * Types are auto-generated from the OpenAPI specification.
+ */
+
+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;
+}
+interface SearchAndMapOptions<T extends StandardNote> {
+    /** Search query - either a string or structured search helpers */
+    query: string | TriliumSearchHelpers;
+    /**
+     * Mapping configuration for your custom fields only.
+     * StandardNoteMapping (id, title, dates) is automatically merged.
+     */
+    mapping: CustomMapping<T>;
+    /** Optional: limit number of results */
+    limit?: number;
+    /** Optional: order by field (e.g., 'dateModified', 'title') */
+    orderBy?: string;
+    /** Optional: order direction */
+    orderDirection?: 'asc' | 'desc';
+    /** Optional: fast search mode (less accurate but faster) */
+    fastSearch?: boolean;
+}
+/** Details about a note that failed to map */
+interface MappingFailure {
+    /** The note ID that failed to map */
+    noteId: string;
+    /** The note title for easier identification */
+    noteTitle: string;
+    /** The error message explaining why mapping failed */
+    reason: string;
+    /** The original note object */
+    note: TriliumNote;
+}
+interface SearchAndMapResult<T extends StandardNote> {
+    /** Mapped results as typed objects */
+    data: T[];
+    /** Notes that failed to map (e.g., missing required fields) */
+    failures: MappingFailure[];
+}
+/** Extended Trilium client with search and map helper */
+interface TriliumClient extends Client<paths> {
+    /**
+     * Search notes and automatically map results to typed objects.
+     * Type T must extend StandardNote to ensure consistent base fields.
+     * StandardNoteMapping is automatically included - just define your custom fields!
+     * Throws on API/network errors.
+     *
+     * @see {@link https://triliumnext.github.io/Docs/Wiki/search.html} for Trilium search syntax
+     *
+     * @example
+     * ```ts
+     * interface BlogPost extends StandardNote {
+     *   slug: string;
+     *   published: boolean;
+     * }
+     *
+     * // Just define your custom fields - StandardNoteMapping is auto-merged!
+     * const { data: posts, failures } = await client.searchAndMap<BlogPost>({
+     *   query: { '#blog': true, '#published': true },
+     *   mapping: {
+     *     slug: '#slug',
+     *     published: { from: '#published', transform: transforms.boolean, default: false },
+     *   },
+     *   limit: 10,
+     *   orderBy: 'dateModified',
+     *   orderDirection: 'desc',
+     * });
+     *
+     * // Each post has id, title, dateCreatedUtc, dateLastModifiedUtc + your custom fields
+     * posts.forEach(post => {
+     *   console.log(`${post.title} (${post.slug}) - ${post.id}`);
+     * });
+     *
+     * if (failures.length > 0) {
+     *   console.warn(`${failures.length} notes failed to map`);
+     * }
+     * ```
+     */
+    searchAndMap<T extends StandardNote>(options: SearchAndMapOptions<T>): Promise<SearchAndMapResult<T>>;
+}
+/**
+ * Create a type-safe Trilium API client
+ *
+ * @example
+ * ```ts
+ * const client = createTriliumClient({
+ *   baseUrl: 'http://localhost:8080',
+ *   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' } }
+ * });
+ *
+ * // Search and map to typed objects
+ * const { data: posts } = await client.searchAndMap<BlogPost>({
+ *   query: { '#blog': true },
+ *   mapping: {
+ *     title: 'note.title',
+ *     slug: '#slug',
+ *   },
+ * });
+ * ```
+ */
+declare function createTriliumClient(config: TriliumClientConfig): TriliumClient;
+
+export { type CustomMapping, type MappingConfig, type MappingFailure, type StandardNote, StandardNoteMapping, type TriliumAppInfo, type TriliumAttachment, type TriliumAttribute, type TriliumBranch, type TriliumClientConfig, TriliumMapper, type TriliumNote, type TriliumSearchHelpers, buildSearchQuery, type components, createTriliumClient as createClient, createTriliumClient, type operations, type paths, transforms };