@vitgranen/markie-sdk

TypeScript SDK for building apps on top of Markie — your personal asset library.

Browse, search, upload, and display images, videos, PDFs, and design assets from your local Markie library in any web app.

Prerequisites

1. Markie desktop app must be running (the SDK talks to its local server on localhost:3210)
2. Developer Access must be enabled in Markie Settings > Developer tab

Install

npm install @vitgranen/markie-sdk

Quick Start

import { MarkieClient } from '@vitgranen/markie-sdk';

const markie = new MarkieClient();
await markie.connect();

// Browse assets
const { assets, total } = await markie.getCatalog({ limit: 20 });

// Display thumbnails
for (const asset of assets) {
  const url = markie.getThumbnailUrl(asset.id, 'sm');
  console.log(asset.originalName, url);
}

Use in HTML / React / Vue / Svelte

Thumbnail and file URLs don't require auth headers, so you can use them directly:

<img src="http://localhost:3210/api/assets/{id}/thumbnail" />

Or with the SDK:

<img src={markie.getThumbnailUrl(asset.id)} alt={asset.originalName} />

API Reference

Constructor

const markie = new MarkieClient({
  baseUrl?: string,  // Default: 'http://localhost:3210'
  token?: string,    // Pre-known token (skip connect())
});

Connection

Method	Returns	Description
connect()	Promise<void>	Register and obtain a bearer token
health()	Promise<boolean>	Check if Markie is running
getInfo()	Promise<ServerInfo>	Server name, version, API version

Catalog

const { assets, total } = await markie.getCatalog({
  limit: 50,          // Max assets to return
  offset: 0,          // Skip N assets (for pagination)
  since: '2024-01-01' // Only assets saved after this ISO date
});

Assets

Method	Returns	Description
getAsset(id)	Promise<Asset>	Get a single asset by ID
updateAsset(id, patch)	Promise<Asset>	Update tags, description, or category
deleteAsset(id)	Promise<void>	Delete an asset

Files & Thumbnails

Method	Returns	Description
getThumbnailUrl(id, size?)	string	URL for thumbnail ('full', 'sm', 'xs')
getFileUrl(id)	string	URL for original file
getFile(id)	Promise<Blob>	Download original file as Blob

Upload

const file = new File([buffer], 'photo.jpg', { type: 'image/jpeg' });
const { id } = await markie.save(file, {
  sourceUrl: 'https://example.com/photo.jpg',
  pageTitle: 'Example Gallery',
});

Search

// Requires Ollama embedding model configured in Markie
const results = await markie.search('mountain landscape');
// [{ id: '...', score: 0.87 }, ...]

const status = await markie.getSearchStatus();
// { available: true, model: 'nomic-embed-text', indexed: 450, total: 500 }

Plan

const plan = await markie.getPlan();
// { isPro: false, assetCount: 123, limit: 500 }

Error Handling

import {
  MarkieOfflineError,
  MarkieUnauthorizedError,
  MarkieLimitError,
} from '@vitgranen/markie-sdk';

try {
  await markie.save(file);
} catch (err) {
  if (err instanceof MarkieOfflineError) {
    // Markie desktop app is not running
  } else if (err instanceof MarkieLimitError) {
    // Free plan limit reached (500 assets)
  } else if (err instanceof MarkieUnauthorizedError) {
    // Token is invalid — call connect() again
  }
}

License

MIT