canto-data 1.0.0 → 1.0.1

package/README.md

@@ -1,12 +1,47 @@
 # canto-data
 
-[![npm version](https://img.shields.io/npm/v/canto-data.svg)](https://www.npmjs.com/package/canto-data)
+Data model library for [Canto](https://github.com/pboueke/canto), a private encrypted journaling app.
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Version](https://img.shields.io/badge/version-1.0.1-green)
+![Tests](https://img.shields.io/badge/tests-156%2F156%20passed-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
 [![CI](https://github.com/pboueke/canto-data/actions/workflows/ci.yml/badge.svg)](https://github.com/pboueke/canto-data/actions/workflows/ci.yml)
 
-Data model library for [Canto](https://github.com/pboueke/canto), a private encrypted journaling app. Provides TypeScript types, runtime validation, schema versioning, migration infrastructure, and export format utilities for Canto journals.
+`canto-data` provides TypeScript types, runtime validation, schema versioning, migration infrastructure, and export format utilities for Canto journals.
+
+This package is **MIT-licensed** and has **zero dependencies**. It can be used independently of the Canto app to read, validate, and manipulate Canto journal data.
+
+## Relationship to the Canto App
+
+Canto (the app) is GPLv3-licensed. `canto-data` (this library) is MIT-licensed to enable data portability: anyone can build tools that interoperate with Canto journals without being bound by the app's copyleft license.
+
+```text
+canto-data (MIT)
+└── src/
+    ├── types.ts              # All TypeScript interfaces
+    ├── validation.ts         # Type guards and structural validators
+    ├── version.ts            # Schema version constant and semver utils
+    ├── migration.ts          # Forward-only migration runner
+    ├── migrations/           # Migration registry
+    └── format.ts             # Export manifest and ZIP format utilities
+```
+
+What `canto-data` owns:
+
+- All journal data types (Journal, Page, Attachment, Comment, and related structures)
+- Runtime validation and type guards
+- Schema versioning and migration framework
+- Export format specification (manifest structure and attachment naming)
+
+What it does **not** include:
 
-**MIT-licensed** with **zero dependencies** — use it to build tools that read, validate, or manipulate Canto journals without copyleft obligations.
+- Encryption and decryption
+- Storage backends
+- Sync integrations
+- UI components
+
+Those pieces live in the [Canto app](https://github.com/pboueke/canto).
 
 ## Installation
 
@@ -20,65 +55,255 @@ npm install canto-data
 import {
   type JournalContent,
   type Page,
+  type Attachment,
   SCHEMA_VERSION,
+  DEFAULT_JOURNAL_SETTINGS,
   validateJournalContent,
   ValidationError,
   parseManifest,
   migrateIfNeeded,
-} from 'canto-data';
+} from "canto-data";
+```
+
+### Validating Journal Data
+
+```typescript
+import { validateJournalContent, ValidationError } from "canto-data";
 
-// Validate untrusted journal data
 try {
   const journal = validateJournalContent(untrustedData);
 } catch (err) {
   if (err instanceof ValidationError) {
-    console.error(`${err.field}: expected ${err.expected}, got ${err.received}`);
+    console.error(`Field: ${err.field}`);
+    console.error(`Expected: ${err.expected}, got: ${err.received}`);
   }
 }
+```
+
+### Reading an Export Manifest
+
+```typescript
+import { parseManifest } from "canto-data";
 
-// Parse an export manifest
 const manifest = parseManifest(manifestJsonString);
+console.log(manifest.encrypted);
+console.log(manifest.journalTitle);
+```
+
+### Checking Schema Version and Migrating
+
+```typescript
+import { migrateIfNeeded } from "canto-data";
 
-// Migrate data to latest schema
 const result = migrateIfNeeded(rawData, manifest.schemaVersion);
+if (result.migrated) {
+  console.log(`Migrated from ${result.fromVersion} to ${result.toVersion}`);
+}
 ```
 
-## Documentation
+### Working with Exported Journals
 
-See **[DATA.md](DATA.md)** for the full data model reference, export format specification, filesystem structure, and usage examples.
+A `.canto.zip` file contains:
 
-## Development
+```text
+{journal-title}.canto.zip
+├── manifest.json
+├── journal.json
+├── settings.json
+├── pages/
+│   ├── {pageId}.json
+│   └── ...
+└── attachments/
+    ├── {type}-{id}.{ext}
+    └── ...
+```
 
-```bash
-git clone https://github.com/pboueke/canto-data.git
-cd canto-data
-npm install
-npm test            # run tests
-npm run test:ci     # run tests with 100% coverage enforcement
-npm run build       # compile to dist/
+Example: list all entries from an unencrypted export.
+
+```typescript
+import JSZip from "jszip";
+import { parseManifest } from "canto-data";
+import type { Page } from "canto-data";
+
+const zip = await JSZip.loadAsync(zipBuffer);
+const manifest = parseManifest(
+  await zip.file("manifest.json")!.async("string"),
+);
+
+if (manifest.encrypted) {
+  console.log("This export is encrypted and requires the journal password.");
+} else {
+  const pageFiles = zip.file(/^pages\/.*\.json$/);
+  for (const pf of pageFiles) {
+    const page: Page = JSON.parse(await pf.async("string"));
+    console.log(`${page.date}: ${page.text.substring(0, 80)}...`);
+  }
+}
 ```
 
-## Publishing
+## Data Model
 
-See the [npm Publishing Setup](#npm-publishing-setup) section below.
+```text
+JournalContent
+├── id: string (UUID)
+├── title: string
+├── icon: string (emoji)
+├── date: string (ISO 8601, creation date)
+├── secure: boolean
+├── salt: string (base64, always present)
+├── biometric?: boolean
+├── kdfIterations?: number (PBKDF2, default 50000)
+├── themeOverride?: string
+├── schemaVersion?: string (semver)
+├── version: number (deprecated, always 1)
+├── settings: JournalSettings
+│   ├── use24h: boolean
+│   ├── previewTags: boolean
+│   ├── previewThumbnail: boolean
+│   ├── previewIcons: boolean
+│   ├── filterBar: boolean
+│   ├── sort: 'ascending' | 'descending' | 'none'
+│   ├── autoLocation: boolean
+│   ├── remoteSync: boolean
+│   ├── syncProvider?: 'gdrive'
+│   ├── autoSync: boolean
+│   └── themeOverride?: string
+└── pages: Page[]
+    ├── id: string (UUID)
+    ├── text: string (Markdown)
+    ├── date: string (ISO 8601, entry date)
+    ├── modified: number (Unix timestamp ms)
+    ├── deleted: boolean
+    ├── thumbnail?: string (base64)
+    ├── tags: string[]
+    ├── location?: GeoLocation
+    │   ├── latitude: number
+    │   ├── longitude: number
+    │   ├── altitude?: number
+    │   └── accuracy?: number
+    ├── comments: Comment[]
+    │   ├── id: string
+    │   ├── text: string
+    │   └── date: string (ISO 8601)
+    ├── images: Attachment[]
+    │   ├── id: string (UUID)
+    │   ├── path: string
+    │   ├── name: string (original filename)
+    │   ├── type: 'image'
+    │   ├── encrypted: boolean
+    │   ├── size?: number (bytes)
+    │   └── deleted: boolean
+    └── files: Attachment[]
+        └── same fields as images, with type: 'file'
+```
+
+## Schema Versioning
+
+Canto journal schemas follow [semver](https://semver.org/):
+
+| Change type                            | Version bump | Migration needed? |
+| -------------------------------------- | ------------ | ----------------- |
+| Breaking (field removed, type changed) | MAJOR        | Yes               |
+| New optional field                     | MINOR        | No                |
+| Documentation or validation fix        | PATCH        | No                |
+
+The schema version is stored in `JournalContent.schemaVersion` and `ExportManifest.schemaVersion`. Legacy data without `schemaVersion` is treated as `0.16.0`. Migrations are forward-only.
+
+### Migration History
+
+| From   | To     | Description                                         |
+| ------ | ------ | --------------------------------------------------- |
+| 0.16.0 | 0.17.0 | Remove deprecated `showMarkdownPlaceholder` setting |
+
+## Export Format Details
+
+### `manifest.json`
+
+```json
+{
+  "version": 1,
+  "schemaVersion": "0.17.0",
+  "appVersion": "0.17.0",
+  "exportDate": "2026-01-01T00:00:00.000Z",
+  "encrypted": false,
+  "journalTitle": "My Journal",
+  "salt": "base64...",
+  "kdfIterations": 50000
+}
+```
+
+- `version`: Manifest format version, always `1`
+- `schemaVersion`: Journal schema version; absent in legacy exports and treated as `0.16.0`
+- `encrypted`: If `true`, all JSON and attachment content is AES-256-GCM encrypted
+- `salt` and `kdfIterations`: Present for password-protected journals
+
+### Encrypted Exports
+
+When `encrypted: true`, decryption requires the journal password. The ciphertext format is `[12-byte nonce][ciphertext][16-byte GCM tag]` using AES-256-GCM. See [Canto SECURITY.md](https://github.com/pboueke/canto/blob/main/SECURITY.md) for the full encryption model.
+
+### Import Behavior
+
+Importing always creates a new journal with new UUIDs, so re-importing the same archive is safe. Shared attachments get individual copies per page.
 
-### npm Publishing Setup
+## Filesystem Structure
 
-1. **npm account**: Create/login at [npmjs.com](https://www.npmjs.com/signup)
-2. **npm token**: Generate an automation token at npmjs.com > Access Tokens > Generate New Token (Automation)
-3. **GitHub secret**: Add the token as `NPM_TOKEN` in the repo's Settings > Secrets and variables > Actions
-4. **First publish**: Run `npm run build && npm publish` after `npm login`, or push v1.0.0 to main
-5. **Subsequent publishes**: Bump version in `package.json`, merge to `main` — GitHub Actions auto-publishes
+### Native (Android and iOS)
 
-### Version bump
+```text
+{documentDirectory}/canto/
+├── journals.json
+├── {journalId}/
+│   ├── metadata.json
+│   ├── pages/
+│   │   └── {pageId}.json
+│   └── attachments/
+│       └── [e]{img|fl}-{pageId}-{hash}.{ext}
+```
+
+Attachment naming uses `{encPrefix}{typePrefix}-{pageId}-{hash}.{ext}` where `e` means password-encrypted and `img` or `fl` indicates the attachment type.
+
+### Web (IndexedDB)
+
+```text
+Database: 'canto' (version 1), Object store: 'files' (keyPath: 'path')
+
+Virtual paths mirror native layout:
+  canto/journals.json
+  canto/{journalId}/metadata.json
+  canto/{journalId}/pages/{pageId}.json
+  canto/{journalId}/attachments/{typePrefix}-{pageId}-{hash}.{ext}
+```
+
+### Google Drive
+
+All journal content on Google Drive is AES-256-GCM encrypted before upload. Only the registry and sync index are stored unencrypted.
+
+```text
+My Drive/Canto/
+├── {journalId}/
+│   ├── meta.json
+│   ├── index.json
+│   ├── pages/{pageId}.json
+│   └── attachments/{filename}
+App Data (hidden):
+└── canto-journals.json
+```
+
+## Development
 
 ```bash
-npm version patch   # 1.0.0 -> 1.0.1 (bug fix)
-npm version minor   # 1.0.0 -> 1.1.0 (new feature)
-npm version major   # 1.0.0 -> 2.0.0 (breaking change)
-git push && git push --tags
+git clone https://github.com/pboueke/canto-data.git
+cd canto-data
+npm install
+npm test
+npm run test:ci
+npm run build
 ```
 
+The repository requires `100%` test coverage. Local hooks keep the README version, test count, and coverage badges in sync with the current test suite.
+
+Release versioning is derived from the top entry in [CHANGELOG.md](CHANGELOG.md). The pre-commit hook syncs `package.json` and the README version badge from that changelog entry automatically.
+
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canto-data",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Canto journal data model — types, validation, versioning, and format utilities",
   "license": "MIT",
   "main": "dist/index.js",
@@ -40,6 +40,9 @@
     "test": "jest",
     "test:coverage": "jest --coverage",
     "test:ci": "jest --coverage --ci",
+    "format": "prettier --write \"**/*.{ts,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,json,md}\"",
+    "prepare": "husky",
     "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
@@ -58,8 +61,16 @@
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
+    "husky": "^9.1.7",
     "jest": "^30.3.0",
+    "lint-staged": "^16.3.3",
+    "prettier": "^3.8.1",
     "ts-jest": "^29.4.6",
     "typescript": "^5.9.3"
+  },
+  "lint-staged": {
+    "*.{ts,json,md}": [
+      "prettier --write"
+    ]
   }
 }