trilium-api 1.0.1 → 1.0.4

package/dist/index.js

@@ -0,0 +1,344 @@
+// src/client.ts
+import createClient from "openapi-fetch";
+
+// 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;
+  }
+};
+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;
+  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,
+  createTriliumClient,
+  transforms
+};

package/package.json

@@ -1,9 +1,26 @@
 {
   "name": "trilium-api",
-  "version": "1.0.1",
-  "description": "",
+  "version": "1.0.4",
+  "description": "A type-safe TypeScript client for the Trilium Notes ETAPI",
   "type": "module",
-  "main": "index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "demo": "tsx src/demo.ts",
@@ -16,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",

package/.github/workflows/ci.yml

@@ -1,37 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main, master]
-  pull_request:
-    branches: [main, master]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [18, 20, 22]
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Type check
-        run: pnpm test:ts
-
-      - name: Run tests
-        run: pnpm test:run

package/.github/workflows/publish.yml

@@ -1,84 +0,0 @@
-name: Publish to npm
-
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Version bump type'
-        required: true
-        default: 'patch'
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: write
-      id-token: write  # Required for npm trusted publishing (OIDC)
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Configure Git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Update npm to latest
-        run: npm install -g npm@latest
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Type check
-        run: pnpm test:ts
-
-      - name: Run tests
-        run: pnpm test:run
-
-      - name: Bump version
-        id: version
-        run: |
-          pnpm version ${{ inputs.version }} --no-git-tag-version
-          VERSION=$(node -p "require('./package.json').version")
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-
-      - name: Commit and tag
-        run: |
-          git add package.json
-          git commit -m "chore: release v${{ steps.version.outputs.version }}"
-          git tag "v${{ steps.version.outputs.version }}"
-          git push && git push --tags
-
-      - name: Build
-        run: pnpm build
-
-      - name: Publish to npm
-        run: npm publish --access public
-        # Uses OIDC trusted publishing - no NPM_TOKEN needed
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: v${{ steps.version.outputs.version }}
-          name: v${{ steps.version.outputs.version }}
-          generate_release_notes: true