trilium-api 1.0.2 → 1.0.4

package/README.md

@@ -10,6 +10,7 @@ A type-safe TypeScript client for the [Trilium Notes](https://github.com/Trilium
 - [API Reference](#api-reference)
 - [Search Query Builder](#search-query-builder)
 - [Note Mapper](#note-mapper)
+- [Search and Map](#search-and-map)
 - [Types](#types)
 - [Error Handling](#error-handling)
 - [Demo](#demo)
@@ -23,6 +24,7 @@ A type-safe TypeScript client for the [Trilium Notes](https://github.com/Trilium
 -  **Lightweight** - Built on [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) (~6kb)
 -  **Query Builder** - Type-safe search query construction
 -  **Mapper** - Declarative note-to-object mapping with transforms
+-  **StandardNote** - Consistent base fields (id, title, dates) on all mapped types
 
 ## Installation
 
@@ -38,7 +40,7 @@ pnpm add trilium-api
 import { createTriliumClient } from 'trilium-api';
 
 const client = createTriliumClient({
-  baseUrl: 'http://localhost:37840',
+  baseUrl: 'http://localhost:8080',
   apiKey: 'your-etapi-token',
 });
 
@@ -65,7 +67,7 @@ const { data: results } = await client.GET('/notes', {
 import { createTriliumClient } from 'trilium-api';
 
 const client = createTriliumClient({
-  baseUrl: 'http://localhost:37840', // Your Trilium server URL
+  baseUrl: 'http://localhost:8080', // Your Trilium server URL
   apiKey: 'your-etapi-token',        // ETAPI token from Trilium settings
 });
 ```
@@ -261,54 +263,61 @@ const { data } = await client.GET('/notes', {
 
 ## Note Mapper
 
-Map Trilium notes to strongly-typed objects using declarative field mappings:
+Map Trilium notes to strongly-typed objects using declarative field mappings.
+
+### StandardNote Base Type
+
+All mapped types should extend `StandardNote`, which provides consistent base fields:
 
 ```typescript
-import { TriliumMapper, transforms } from 'trilium-api';
+import type { StandardNote } from 'trilium-api';
+
+// StandardNote includes:
+// - id: string (note ID)
+// - title: string (note title)  
+// - dateCreatedUtc: Date
+// - dateLastModifiedUtc: Date
 
-// Define your target type
-interface BlogPost {
-  id: string;
-  title: string;
+interface BlogPost extends StandardNote {
+  slug: string;
+  tags: string[];
+  isPublished: boolean;
+}
+```
+
+### Using TriliumMapper Directly
+
+For standalone mapping (outside of `searchAndMap`), use `TriliumMapper`:
+
+```typescript
+import { TriliumMapper, StandardNoteMapping, transforms, type StandardNote } from 'trilium-api';
+
+interface BlogPost extends StandardNote {
   slug: string;
-  publishDate: Date;
   wordCount: number;
   readTimeMinutes: number;
   tags: string[];
   isPublished: boolean;
 }
 
-// Create a mapper
-const blogMapper = new TriliumMapper<BlogPost>({
-  // Simple property mapping (shorthand)
-  id: 'note.noteId',
-  title: 'note.title',
-  
-  // Label attribute with required validation
-  slug: { from: '#slug', required: true },
-  
-  // Transform string to Date
-  publishDate: { from: '#publishDate', transform: transforms.date },
-  
-  // Transform string to number with default
-  wordCount: { from: '#wordCount', transform: transforms.number, default: 0 },
-  
-  // Computed field based on other mapped values
-  readTimeMinutes: {
-    computed: (partial) => Math.ceil((partial.wordCount || 0) / 200),
-  },
-  
-  // Transform comma-separated string to array
-  tags: { from: '#tags', transform: transforms.commaSeparated, default: [] },
-  
-  // Transform to boolean
-  isPublished: { from: '#published', transform: transforms.boolean, default: false },
-});
+// Merge StandardNoteMapping with your custom fields
+const blogMapper = new TriliumMapper<BlogPost>(
+  TriliumMapper.merge(
+    StandardNoteMapping,
+    {
+      slug: { from: '#slug', required: true },
+      wordCount: { from: '#wordCount', transform: transforms.number, default: 0 },
+      readTimeMinutes: {
+        computed: (partial) => Math.ceil((partial.wordCount || 0) / 200),
+      },
+      tags: { from: '#tags', transform: transforms.commaSeparated, default: [] },
+      isPublished: { from: '#published', transform: transforms.boolean, default: false },
+    }
+  )
+);
 
-// Map a single note
+// Map notes
 const post = blogMapper.map(note);
-
-// Map an array of notes
 const posts = blogMapper.map(notes);
 ```
 
@@ -369,44 +378,149 @@ const posts = blogMapper.map(notes);
 | `transforms.date` | Parse date string | `"2024-01-15"` → `Date` |
 | `transforms.trim` | Trim whitespace | `"  hello  "` → `"hello"` |
 
-### Merging Configurations
+## Search and Map
 
-Reuse and extend mapping configurations:
+The `searchAndMap` method combines searching and mapping in a single call. It **automatically includes `StandardNoteMapping`**, so you only need to define your custom fields!
 
 ```typescript
-// Base configuration for common fields
-const baseMapping = {
-  id: 'note.noteId',
-  title: 'note.title',
-  createdAt: { from: 'note.utcDateCreated', transform: transforms.date },
-};
+import { createTriliumClient, transforms, type StandardNote, type CustomMapping } from 'trilium-api';
+
+const client = createTriliumClient({
+  baseUrl: 'http://localhost:8080',
+  apiKey: 'your-etapi-token',
+});
+
+// Extend StandardNote with your custom fields
+interface BlogPost extends StandardNote {
+  slug: string;
+  published: boolean;
+}
 
-// Extended configuration for blog posts
-const blogMapping = {
+// Use CustomMapping<T> for clean typing - excludes StandardNote fields automatically
+const blogMapping: CustomMapping<BlogPost> = {
   slug: '#slug',
-  tags: { from: '#tags', transform: transforms.commaSeparated, default: [] },
+  published: { from: '#published', transform: transforms.boolean, default: false },
 };
 
-// Merge configurations
-const merged = TriliumMapper.merge<BlogPost>(baseMapping, blogMapping);
-const mapper = new TriliumMapper<BlogPost>(merged);
+// Just pass your custom mapping - StandardNoteMapping is auto-merged!
+const { data, failures } = await client.searchAndMap<BlogPost>({
+  query: { '#blog': true, '#published': true },
+  mapping: blogMapping,
+  limit: 10,
+  orderBy: 'dateModified',
+  orderDirection: 'desc',
+});
+
+// Each post has: id, title, dateCreatedUtc, dateLastModifiedUtc, slug, published
+data.forEach(post => {
+  console.log(`${post.title} (${post.id}) - ${post.slug}`);
+});
+
+// Check for mapping failures
+if (failures.length > 0) {
+  console.warn(`${failures.length} notes failed to map:`);
+  failures.forEach(f => console.warn(`  - ${f.noteTitle}: ${f.reason}`));
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `query` | `string \| object` | Search query string or structured query object |
+| `mapping` | `CustomMapping<T>` | Field mapping for your custom fields (StandardNote fields auto-merged) |
+| `limit` | `number` | Maximum number of results |
+| `orderBy` | `string` | Field to order by (e.g., `'dateModified'`, `'title'`) |
+| `orderDirection` | `'asc' \| 'desc'` | Sort direction |
+| `fastSearch` | `boolean` | Enable fast search mode (less accurate but faster) |
+
+### Return Value
+
+```typescript
+{
+  data: T[],              // Successfully mapped objects
+  failures: MappingFailure[]  // Notes that failed to map
+}
+```
+
+### Handling Failures
+
+When a note fails to map (e.g., missing required field, transform error), it's added to the `failures` array instead of throwing:
+
+```typescript
+interface MappingFailure {
+  noteId: string;    // The note ID that failed
+  noteTitle: string; // The note title for identification
+  reason: string;    // Error message explaining the failure
+  note: TriliumNote; // The original note object for debugging
+}
+```
+
+This allows you to process partial results while still knowing which notes had issues:
+
+```typescript
+interface BlogPost extends StandardNote {
+  slug: string;
+}
+
+const { data, failures } = await client.searchAndMap<BlogPost>({
+  query: '#blog',
+  mapping: {
+    slug: { from: '#slug', required: true }, // Will fail if missing
+  },
+});
+
+// data contains all successfully mapped posts
+// failures contains notes missing the required #slug label
+```
+
+### Error Handling
+
+API or network errors throw an exception:
+
+```typescript
+try {
+  const { data, failures } = await client.searchAndMap<BlogPost>({
+    query: '#blog',
+    mapping: blogMapping,
+  });
+} catch (err) {
+  console.error('Search failed:', err);
+}
 ```
 
 ## Types
 
-The package exports all types from the OpenAPI specification:
+The package exports a focused set of types for common use cases:
 
 ```typescript
-import type {
+// Main imports for typical usage
+import { 
+  createTriliumClient, 
+  transforms, 
+  buildSearchQuery,
+} from 'trilium-api';
+
+import type { 
+  // Your mapped types should extend this
+  StandardNote,
+  // For typing your custom field mappings
+  CustomMapping,
+  // For typing query objects
+  TriliumSearchHelpers,
+  // For error handling
+  MappingFailure,
+  // Trilium entity types (for API responses)
   TriliumNote,
   TriliumBranch,
   TriliumAttribute,
   TriliumAttachment,
   TriliumAppInfo,
-  paths,
-  components,
-  operations,
 } from 'trilium-api';
+
+// Advanced: for standalone TriliumMapper usage (outside searchAndMap)
+import { TriliumMapper, StandardNoteMapping } from 'trilium-api';
+import type { MappingConfig } from 'trilium-api';
 ```
 
 ## Error Handling
@@ -620,7 +734,7 @@ function createMockResponse(body: any, status = 200, contentType = 'application/
 
 describe('my new feature', () => {
   const config = {
-    baseUrl: 'http://localhost:37840',
+    baseUrl: 'http://localhost:8080',
     apiKey: 'test-api-key',
   };
 
@@ -647,7 +761,7 @@ describe('my new feature', () => {
 
     // 4. Verify the request (openapi-fetch uses Request objects)
     const request = mockFetch.mock.calls[0]![0] as Request;
-    expect(request.url).toBe('http://localhost:37840/etapi/notes/test123');
+    expect(request.url).toBe('http://localhost:8080/etapi/notes/test123');
     expect(request.method).toBe('GET');
     expect(request.headers.get('Authorization')).toBe('test-api-key');
   });

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  StandardNoteMapping: () => StandardNoteMapping,
   TriliumMapper: () => TriliumMapper,
   buildSearchQuery: () => buildSearchQuery,
   createClient: () => client_default,
@@ -285,20 +286,98 @@ var transforms = {
     return String(value).trim() || void 0;
   }
 };
+var StandardNoteMapping = {
+  id: {
+    from: "note.noteId",
+    required: true
+  },
+  title: {
+    from: "note.title",
+    required: true
+  },
+  dateCreatedUtc: {
+    from: "note.utcDateCreated",
+    transform: transforms.date,
+    required: true
+  },
+  dateLastModifiedUtc: {
+    from: "note.utcDateModified",
+    transform: transforms.date,
+    required: true
+  }
+};
 
 // src/client.ts
 function createTriliumClient(config) {
   const baseUrl = config.baseUrl.endsWith("/") ? config.baseUrl.slice(0, -1) : config.baseUrl;
-  return (0, import_openapi_fetch.default)({
+  const client = (0, import_openapi_fetch.default)({
     baseUrl: `${baseUrl}/etapi`,
     headers: {
       Authorization: config.apiKey
     }
   });
+  const searchAndMap = async (options) => {
+    const searchQuery = typeof options.query === "string" ? options.query : buildSearchQuery(options.query);
+    const params = [];
+    if (options.orderBy) {
+      params.push(`orderBy:${options.orderBy}`);
+      if (options.orderDirection) {
+        params.push(options.orderDirection);
+      }
+    }
+    if (options.limit) {
+      params.push(`limit:${options.limit}`);
+    }
+    if (options.fastSearch) {
+      params.push("fastSearch");
+    }
+    const fullQuery = params.length > 0 ? `${searchQuery} ${params.join(" ")}` : searchQuery;
+    const { data, error } = await client.GET("/notes", {
+      params: { query: { search: fullQuery } }
+    });
+    if (error) {
+      throw error;
+    }
+    if (!data?.results) {
+      throw new Error("No results returned from search");
+    }
+    const fullMapping = TriliumMapper.merge(
+      StandardNoteMapping,
+      options.mapping
+    );
+    const mapper = new TriliumMapper(fullMapping);
+    const mappedData = [];
+    const failures = [];
+    for (const note of data.results) {
+      try {
+        const [mapped] = mapper.map([note]);
+        if (mapped !== void 0) {
+          mappedData.push(mapped);
+        } else {
+          failures.push({
+            noteId: note.noteId ?? "unknown",
+            noteTitle: note.title ?? "Untitled",
+            reason: "Mapping returned undefined",
+            note
+          });
+        }
+      } catch (err) {
+        failures.push({
+          noteId: note.noteId ?? "unknown",
+          noteTitle: note.title ?? "Untitled",
+          reason: err instanceof Error ? err.message : String(err),
+          note
+        });
+      }
+    }
+    return { data: mappedData, failures };
+  };
+  return Object.assign(client, { searchAndMap });
 }
 var client_default = createTriliumClient;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  StandardNoteMapping,
   TriliumMapper,
   buildSearchQuery,
   createClient,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import * as openapi_fetch from 'openapi-fetch';
+import { Client } from 'openapi-fetch';
 
 /**
  * This file was auto-generated by openapi-typescript.
@@ -1848,12 +1848,6 @@ type TriliumSearchHelpers = TriliumSearchLogical | (TriliumSearchConditions & Pa
  * // => "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
@@ -1889,8 +1883,8 @@ type ComputedFunction<T, K extends keyof T> = (partial: Partial<T>, note: Triliu
 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>;
+    /** 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) */
@@ -1939,7 +1933,7 @@ type MappingConfig<T> = {
  */
 declare class TriliumMapper<T> {
     /** The mapping configuration for this mapper */
-    private readonly config;
+    readonly config: MappingConfig<T>;
     /**
      * Creates a new TriliumMapper instance
      * @param config - The mapping configuration defining how to map note fields to the target type
@@ -2020,6 +2014,83 @@ declare const transforms: {
     /** 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'];
@@ -2031,13 +2102,88 @@ 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:37840',
+ *   baseUrl: 'http://localhost:8080',
  *   apiKey: 'your-etapi-token'
  * });
  *
@@ -2063,8 +2209,17 @@ interface TriliumClientConfig {
  * 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): openapi_fetch.Client<paths, `${string}/${string}`>;
+declare function createTriliumClient(config: TriliumClientConfig): TriliumClient;
 
-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 };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import * as openapi_fetch from 'openapi-fetch';
+import { Client } from 'openapi-fetch';
 
 /**
  * This file was auto-generated by openapi-typescript.
@@ -1848,12 +1848,6 @@ type TriliumSearchHelpers = TriliumSearchLogical | (TriliumSearchConditions & Pa
  * // => "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
@@ -1889,8 +1883,8 @@ type ComputedFunction<T, K extends keyof T> = (partial: Partial<T>, note: Triliu
 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>;
+    /** 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) */
@@ -1939,7 +1933,7 @@ type MappingConfig<T> = {
  */
 declare class TriliumMapper<T> {
     /** The mapping configuration for this mapper */
-    private readonly config;
+    readonly config: MappingConfig<T>;
     /**
      * Creates a new TriliumMapper instance
      * @param config - The mapping configuration defining how to map note fields to the target type
@@ -2020,6 +2014,83 @@ declare const transforms: {
     /** 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'];
@@ -2031,13 +2102,88 @@ 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:37840',
+ *   baseUrl: 'http://localhost:8080',
  *   apiKey: 'your-etapi-token'
  * });
  *
@@ -2063,8 +2209,17 @@ interface TriliumClientConfig {
  * 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): openapi_fetch.Client<paths, `${string}/${string}`>;
+declare function createTriliumClient(config: TriliumClientConfig): TriliumClient;
 
-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 };
+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 };

package/dist/index.js

@@ -245,19 +245,97 @@ var transforms = {
     return String(value).trim() || void 0;
   }
 };
+var StandardNoteMapping = {
+  id: {
+    from: "note.noteId",
+    required: true
+  },
+  title: {
+    from: "note.title",
+    required: true
+  },
+  dateCreatedUtc: {
+    from: "note.utcDateCreated",
+    transform: transforms.date,
+    required: true
+  },
+  dateLastModifiedUtc: {
+    from: "note.utcDateModified",
+    transform: transforms.date,
+    required: true
+  }
+};
 
 // src/client.ts
 function createTriliumClient(config) {
   const baseUrl = config.baseUrl.endsWith("/") ? config.baseUrl.slice(0, -1) : config.baseUrl;
-  return createClient({
+  const client = createClient({
     baseUrl: `${baseUrl}/etapi`,
     headers: {
       Authorization: config.apiKey
     }
   });
+  const searchAndMap = async (options) => {
+    const searchQuery = typeof options.query === "string" ? options.query : buildSearchQuery(options.query);
+    const params = [];
+    if (options.orderBy) {
+      params.push(`orderBy:${options.orderBy}`);
+      if (options.orderDirection) {
+        params.push(options.orderDirection);
+      }
+    }
+    if (options.limit) {
+      params.push(`limit:${options.limit}`);
+    }
+    if (options.fastSearch) {
+      params.push("fastSearch");
+    }
+    const fullQuery = params.length > 0 ? `${searchQuery} ${params.join(" ")}` : searchQuery;
+    const { data, error } = await client.GET("/notes", {
+      params: { query: { search: fullQuery } }
+    });
+    if (error) {
+      throw error;
+    }
+    if (!data?.results) {
+      throw new Error("No results returned from search");
+    }
+    const fullMapping = TriliumMapper.merge(
+      StandardNoteMapping,
+      options.mapping
+    );
+    const mapper = new TriliumMapper(fullMapping);
+    const mappedData = [];
+    const failures = [];
+    for (const note of data.results) {
+      try {
+        const [mapped] = mapper.map([note]);
+        if (mapped !== void 0) {
+          mappedData.push(mapped);
+        } else {
+          failures.push({
+            noteId: note.noteId ?? "unknown",
+            noteTitle: note.title ?? "Untitled",
+            reason: "Mapping returned undefined",
+            note
+          });
+        }
+      } catch (err) {
+        failures.push({
+          noteId: note.noteId ?? "unknown",
+          noteTitle: note.title ?? "Untitled",
+          reason: err instanceof Error ? err.message : String(err),
+          note
+        });
+      }
+    }
+    return { data: mappedData, failures };
+  };
+  return Object.assign(client, { searchAndMap });
 }
 var client_default = createTriliumClient;
 export {
+  StandardNoteMapping,
   TriliumMapper,
   buildSearchQuery,
   client_default as createClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trilium-api",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A type-safe TypeScript client for the Trilium Notes ETAPI",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -33,9 +33,23 @@
     "test:ts": "tsc --noEmit",
     "prepublishOnly": "pnpm build"
   },
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "trilium",
+    "trilium-notes",
+    "etapi",
+    "api-client",
+    "typescript"
+  ],
+  "author": "lzinga",
   "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lzinga/trilium-api"
+  },
+  "bugs": {
+    "url": "https://github.com/lzinga/trilium-api/issues"
+  },
+  "homepage": "https://github.com/lzinga/trilium-api#readme",
   "packageManager": "pnpm@10.25.0",
   "devDependencies": {
     "@types/node": "^25.0.3",