@xnetjs/data 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Smothers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# @xnetjs/data
+
+Schema system, NodeStore, and Yjs CRDT engine for xNet. This is the central data package -- it defines how structured data and rich text documents are created, stored, and synced.
+
+## Installation
+
+```bash
+pnpm add @xnetjs/data
+```
+
+## Features
+
+- **Schema system** -- `defineSchema()` with 16 typed property helpers
+- **NodeStore** -- Event-sourced LWW (Last-Writer-Wins) storage engine
+- **Built-in schemas** -- Page, Database, Task, Canvas, Comment
+- **Yjs CRDT** -- Y.Doc helpers for signed updates and merge/state-vector workflows
+- **Awareness/presence** -- Real-time user presence
+- **Blob service** -- File upload/download with content addressing
+- **Storage adapters** -- SQLite and in-memory NodeStore adapters
+- **Temp ID mapping** -- Optimistic creates with server-assigned IDs
+
+## Usage
+
+### Define a Schema
+
+```typescript
+import { defineSchema, text, number, select, date, checkbox, relation } from '@xnetjs/data'
+
+const TaskSchema = defineSchema({
+  name: 'Task',
+  namespace: 'myapp://',
+  document: 'yjs', // Enable rich text body
+  properties: {
+    title: text({ required: true }),
+    priority: number(),
+    done: checkbox(),
+    dueDate: date(),
+    status: select({
+      options: [
+        { id: 'todo', name: 'To Do' },
+        { id: 'in-progress', name: 'In Progress' },
+        { id: 'done', name: 'Done' }
+      ] as const
+    }),
+    assignee: relation({ schema: 'myapp://Person' })
+  }
+})
+```
+
+### Property Helpers
+
+| Type          | Import          | Description                 |
+| ------------- | --------------- | --------------------------- |
+| `text`        | `text()`        | String values               |
+| `number`      | `number()`      | Numeric values              |
+| `checkbox`    | `checkbox()`    | Boolean toggle              |
+| `date`        | `date()`        | Single date                 |
+| `dateRange`   | `dateRange()`   | Start + end date            |
+| `select`      | `select()`      | Single choice               |
+| `multiSelect` | `multiSelect()` | Multiple choices            |
+| `person`      | `person()`      | DID reference               |
+| `relation`    | `relation()`    | Link to another node        |
+| `url`         | `url()`         | URL string                  |
+| `email`       | `email()`       | Email address               |
+| `phone`       | `phone()`       | Phone number                |
+| `file`        | `file()`        | File attachment             |
+| `created`     | `created()`     | Auto-set creation timestamp |
+| `updated`     | `updated()`     | Auto-set update timestamp   |
+| `createdBy`   | `createdBy()`   | Auto-set author DID         |
+
+### NodeStore
+
+```typescript
+import { NodeStore, MemoryNodeStorageAdapter } from '@xnetjs/data'
+
+const store = new NodeStore({
+  storage: new MemoryNodeStorageAdapter(),
+  authorDID: identity.did,
+  signingKey: privateKey
+})
+
+// Create
+const task = await store.create(TaskSchema, { title: 'Buy milk', status: 'todo' })
+
+// Read
+const loaded = await store.get(TaskSchema, task.id)
+
+// Update
+await store.update(TaskSchema, task.id, { status: 'done' })
+
+// List
+const tasks = await store.list(TaskSchema)
+
+// Delete (soft)
+await store.remove(task.id)
+```
+
+### Yjs Documents
+
+```typescript
+import { YDoc, captureUpdate, applySignedUpdate, signUpdate, mergeDocuments } from '@xnetjs/data'
+
+const authorDID = identity.did
+const signingKey = keyBundle.signingKey
+
+const docA = new YDoc()
+const docB = new YDoc()
+
+// Edit rich text content
+docA.getText('content').insert(0, 'Hello world')
+
+// Capture and sign update bytes
+const update = captureUpdate(docA)
+const signed = signUpdate(update, { authorDID, signingKey })
+
+// Verify/apply to another replica
+applySignedUpdate(docB, signed)
+
+// Merge full state from one doc into another
+mergeDocuments(docA, docB)
+```
+
+## Architecture
+
+```mermaid
+flowchart TD
+    Schema["defineSchema()<br/><small>16 property helpers</small>"]
+    Store["NodeStore<br/><small>Event-sourced LWW</small>"]
+    Doc["Yjs Documents<br/><small>CRDT rich text</small>"]
+    Blob["BlobService<br/><small>File attachments</small>"]
+    Builtin["Built-in Schemas<br/><small>Page, Database, Task,<br/>Canvas, Comment</small>"]
+
+    Schema --> Store
+    Schema --> Builtin
+    Store --> Doc
+    Store --> Blob
+    Builtin --> Store
+
+    subgraph Adapters["Storage Adapters"]
+        SQLite["SQLite<br/>Adapter"]
+        Mem["Memory<br/>Adapter"]
+    end
+
+    Store --> Adapters
+```
+
+### Storage Adapters
+
+| Adapter                    | Platform | Description                            |
+| -------------------------- | -------- | -------------------------------------- |
+| `SQLiteNodeStorageAdapter` | All      | Primary adapter using `@xnetjs/sqlite` |
+| `MemoryNodeStorageAdapter` | All      | In-memory storage for testing          |
+
+**Recommended:** Use `SQLiteNodeStorageAdapter` with the appropriate `@xnetjs/sqlite` adapter for your platform:
+
+```typescript
+import { NodeStore, SQLiteNodeStorageAdapter } from '@xnetjs/data'
+import { ElectronSQLiteAdapter } from '@xnetjs/sqlite/electron' // or /web, /expo
+
+const sqliteAdapter = new ElectronSQLiteAdapter()
+await sqliteAdapter.open({ path: 'xnet.db' })
+
+const storage = new SQLiteNodeStorageAdapter(sqliteAdapter)
+await storage.open()
+
+const store = new NodeStore({
+  storage,
+  authorDID: identity.did,
+  signingKey: privateKey
+})
+```
+
+### Telemetry Integration
+
+NodeStore supports optional telemetry for tracking CRUD operations, performance, and errors:
+
+```typescript
+import { NodeStore } from '@xnetjs/data'
+import { TelemetryCollector, ConsentManager } from '@xnetjs/telemetry'
+
+const consent = new ConsentManager()
+const telemetry = new TelemetryCollector({ consent })
+
+const store = new NodeStore({
+  storage,
+  authorDID: identity.did,
+  signingKey: privateKey,
+  telemetry // <-- Add telemetry collector
+})
+```
+
+When telemetry is enabled, NodeStore automatically reports:
+
+- **Performance metrics**: `data.create`, `data.update`, `data.delete`, `data.list`, `data.applyRemoteChange`
+- **Usage metrics**: Operation counts
+- **Security events**: Hash/signature verification failures, unauthorized remote changes
+- **Crash reports**: Errors with context
+
+All telemetry respects user consent settings and privacy buckets (no exact values, no PII).
+
+## Modules
+
+| Module                    | Description                            |
+| ------------------------- | -------------------------------------- |
+| `schema/define.ts`        | `defineSchema()` factory               |
+| `schema/node.ts`          | FlatNode type (flattened properties)   |
+| `schema/registry.ts`      | Schema registry                        |
+| `store/store.ts`          | NodeStore engine                       |
+| `store/sqlite-adapter.ts` | SQLite NodeStore adapter (recommended) |
+| `store/memory-adapter.ts` | In-memory NodeStore adapter            |
+| `store/tempids.ts`        | Temp ID mapping for optimistic creates |
+| `updates.ts`              | Signed update and merge utilities      |
+| `blob/blob-service.ts`    | File blob storage                      |
+| `sync/awareness.ts`       | Presence awareness                     |
+| `blocks/registry.ts`      | Block type registry                    |
+
+## Dependencies
+
+- `@xnetjs/core`, `@xnetjs/crypto`, `@xnetjs/identity`, `@xnetjs/storage`, `@xnetjs/sync`, `@xnetjs/sqlite`
+- `yjs`, `y-protocols` -- CRDT engine
+- `nanoid` -- ID generation
+
+## Testing
+
+```bash
+pnpm --filter @xnetjs/data test
+```
+
+10 test files covering schema system, NodeStore, comments, and blob service.

package/dist/canvas-HSIKIQFK.js

@@ -0,0 +1,7 @@
+import {
+  CanvasSchema
+} from "./chunk-4MTS5KAQ.js";
+import "./chunk-SZC345Z2.js";
+export {
+  CanvasSchema
+};

package/dist/chunk-2L5ZUGG5.js

@@ -0,0 +1,53 @@
+import {
+  checkbox,
+  date,
+  defineSchema,
+  person,
+  relation,
+  select,
+  text
+} from "./chunk-SZC345Z2.js";
+
+// src/schema/schemas/task.ts
+var TaskSchema = defineSchema({
+  name: "Task",
+  namespace: "xnet://xnet.fyi/",
+  properties: {
+    /** Task title */
+    title: text({ required: true, maxLength: 500 }),
+    /** Whether the task is completed */
+    completed: checkbox({ default: false }),
+    /** Task status */
+    status: select({
+      options: [
+        { id: "todo", name: "To Do", color: "gray" },
+        { id: "in-progress", name: "In Progress", color: "blue" },
+        { id: "done", name: "Done", color: "green" },
+        { id: "cancelled", name: "Cancelled", color: "red" }
+      ],
+      default: "todo"
+    }),
+    /** Task priority */
+    priority: select({
+      options: [
+        { id: "low", name: "Low", color: "gray" },
+        { id: "medium", name: "Medium", color: "yellow" },
+        { id: "high", name: "High", color: "orange" },
+        { id: "urgent", name: "Urgent", color: "red" }
+      ],
+      default: "medium"
+    }),
+    /** Due date */
+    dueDate: date({}),
+    /** Assigned person */
+    assignee: person({}),
+    /** Parent task (for subtasks) */
+    parent: relation({ target: "xnet://xnet.fyi/Task" })
+  },
+  document: "yjs"
+  // Collaborative Y.Doc for description
+});
+
+export {
+  TaskSchema
+};

package/dist/chunk-4MTS5KAQ.js

@@ -0,0 +1,22 @@
+import {
+  defineSchema,
+  text
+} from "./chunk-SZC345Z2.js";
+
+// src/schema/schemas/canvas.ts
+var CanvasSchema = defineSchema({
+  name: "Canvas",
+  namespace: "xnet://xnet.fyi/",
+  properties: {
+    /** Canvas title */
+    title: text({ required: true, maxLength: 500 }),
+    /** Emoji or icon URL */
+    icon: text({})
+  },
+  document: "yjs"
+  // Collaborative Y.Doc for canvas data (nodes, edges)
+});
+
+export {
+  CanvasSchema
+};

package/dist/chunk-BQBPA5HS.js

@@ -0,0 +1,76 @@
+import {
+  checkbox,
+  created,
+  createdBy,
+  date,
+  defineSchema,
+  file,
+  person,
+  relation,
+  select,
+  text
+} from "./chunk-SZC345Z2.js";
+
+// src/schema/schemas/comment.ts
+var CommentSchema = defineSchema({
+  name: "Comment",
+  namespace: "xnet://xnet.fyi/",
+  properties: {
+    // ─── Universal Targeting (schema-agnostic relation) ────────────────────────
+    /** The Node this comment is on (any schema - Page, Task, Database, Canvas, etc.) */
+    target: relation({ required: true }),
+    /** Schema IRI of the target Node (optimization hint, not enforced) */
+    targetSchema: text({}),
+    // ─── Threading (flat - all replies point to root) ──────────────────────────
+    /** Root comment ID for threading (null = this IS the root) */
+    inReplyTo: relation({}),
+    // ─── Anchor Data (polymorphic positioning) ─────────────────────────────────
+    /** Type of anchor point */
+    anchorType: select({
+      options: [
+        { id: "text", name: "Text Selection", color: "blue" },
+        { id: "cell", name: "Database Cell", color: "green" },
+        { id: "row", name: "Database Row", color: "green" },
+        { id: "column", name: "Database Column", color: "green" },
+        { id: "canvas-position", name: "Canvas Position", color: "purple" },
+        { id: "canvas-object", name: "Canvas Object", color: "purple" },
+        { id: "node", name: "Whole Node", color: "gray" }
+      ],
+      required: true,
+      default: "node"
+    }),
+    /** JSON-encoded anchor position data */
+    anchorData: text({ required: true }),
+    // ─── Content ───────────────────────────────────────────────────────────────
+    /** Comment body in GitHub-flavored markdown (stored as plain text) */
+    content: text({ required: true, maxLength: 1e4 }),
+    /** Optional file attachments */
+    attachments: file({ multiple: true }),
+    // ─── Pseudo Reply-To (for UI, not structural threading) ────────────────────
+    /** DID of user being replied to (UI hint) */
+    replyToUser: person({}),
+    /** Comment ID being referenced (for "in reply to" display) */
+    replyToCommentId: relation({}),
+    // ─── Thread State (on root comment only) ───────────────────────────────────
+    /** Whether the thread has been resolved */
+    resolved: checkbox({ default: false }),
+    /** Who resolved the thread */
+    resolvedBy: person({}),
+    /** When the thread was resolved */
+    resolvedAt: date({}),
+    // ─── Edit State ────────────────────────────────────────────────────────────
+    /** Whether the comment has been edited */
+    edited: checkbox({ default: false }),
+    /** When the comment was last edited */
+    editedAt: date({}),
+    // ─── Auto-populated Metadata ───────────────────────────────────────────────
+    createdAt: created(),
+    createdBy: createdBy()
+  },
+  // Comments are plain text + markdown, no collaborative Y.Doc needed
+  document: void 0
+});
+
+export {
+  CommentSchema
+};

package/dist/chunk-GZHARFKC.js

@@ -0,0 +1,25 @@
+import {
+  defineSchema,
+  file,
+  text
+} from "./chunk-SZC345Z2.js";
+
+// src/schema/schemas/page.ts
+var PageSchema = defineSchema({
+  name: "Page",
+  namespace: "xnet://xnet.fyi/",
+  properties: {
+    /** Page title */
+    title: text({ required: true, maxLength: 500 }),
+    /** Emoji or icon URL */
+    icon: text({}),
+    /** Cover image */
+    cover: file({ accept: ["image/*"] })
+  },
+  document: "yjs"
+  // Collaborative Y.Doc for rich text
+});
+
+export {
+  PageSchema
+};

package/dist/chunk-IDMBCRUC.js

@@ -0,0 +1,29 @@
+import {
+  defineSchema,
+  number,
+  person,
+  text
+} from "./chunk-SZC345Z2.js";
+
+// src/schema/schemas/grant.ts
+var GrantSchema = defineSchema({
+  name: "Grant",
+  namespace: "xnet://xnet.fyi/",
+  properties: {
+    issuer: person({ required: true }),
+    grantee: person({ required: true }),
+    resource: text({ required: true }),
+    resourceSchema: text({ required: true }),
+    actions: text({ required: true }),
+    expiresAt: number({}),
+    revokedAt: number({}),
+    revokedBy: person({}),
+    ucanToken: text({}),
+    proofDepth: number({}),
+    parentGrantId: text({})
+  }
+});
+
+export {
+  GrantSchema
+};