canto-data

Data model library for Canto, a private encrypted journaling app.

canto-data provides TypeScript types, runtime validation, schema versioning, migration infrastructure and export format utilities for Canto journals. It defines attachment metadata only; it does not encrypt, store, stream or upload attachment bytes.

MIT-licensed, zero runtime dependencies, Node.js 18+. Use it independently of the Canto app to read, validate and manipulate Canto journal data.

Install

npm install canto-data

Quick start

import { validateJournalContent, ValidationError } from 'canto-data';

try {
  const journal = validateJournalContent(untrustedData);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Field: ${error.field}`);
    console.error(`Expected: ${error.expected}, got: ${error.received}`);
  }
}

import { migrateIfNeeded, parseManifest } from 'canto-data';

const manifest = parseManifest(manifestJsonString);
const result = migrateIfNeeded(rawData, manifest.schemaVersion);

if (result.migrated) {
  console.log(`Migrated from ${result.fromVersion} to ${result.toVersion}`);
}

Documentation

The full reference is published at pboueke.github.io/canto-data:

Page	Covers
Getting started	install, validation, first migration
Data model	the complete JournalContent tree
Usage	guards, serialization, attachments
Export format	archives, manifests, content descriptors
Schema versions	semver policy and migration history
API	every export and subpath
Canto app storage	native, IndexedDB and Drive layouts
Relationship to the app	licensing and the library boundary
Development and verification	make targets, support matrix, release steps

Development

make verify is the authoritative gate and runs in pinned rootless Podman containers. See CONTRIBUTING.md, AGENTS.md and the development page.

License

MIT. See LICENSE.