mpb-localkit 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LocalKit Contributors
+
+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,375 @@
+# MPB LocalKit
+
+> Type-driven, offline-first SDK for TypeScript developers. Define your data schema once — get local storage, sync, auth, and error tracking out of the box.
+
+## Quick Start
+
+```bash
+npm install mpb-localkit
+```
+
+```ts
+import { createApp, collection, z } from 'mpb-localkit'
+
+const app = createApp({
+  collections: {
+    brews: collection(z.object({
+      brewDate: z.date(),
+      style: z.string(),
+      og: z.number(),
+      fg: z.number().optional(),
+      notes: z.string().optional(),
+    })),
+  },
+})
+
+// Fully typed CRUD — works offline immediately
+const brew = await app.brews.create({ brewDate: new Date(), style: 'IPA', og: 1.065 })
+const allBrews = await app.brews.findMany()
+await app.brews.update(brew._id, { fg: 1.012 })
+await app.brews.delete(brew._id)
+```
+
+## API Reference
+
+### `createApp(config)`
+
+Creates a typed app instance with CRUD methods for each collection.
+
+```ts
+const app = createApp({
+  collections: { ... },      // Required: collection definitions
+  sync: {                    // Optional: sync configuration
+    endpoint: 'https://...',
+    interval: 30000,
+    enabled: true,
+  },
+  errorTracking: {           // Optional: error tracking config
+    enabled: true,
+    snapshot: true,
+    maxLocalErrors: 100,
+  },
+})
+```
+
+### `collection(schema)`
+
+Wraps a Zod schema into a typed collection descriptor. TypeScript infers the document type automatically.
+
+```ts
+const todos = collection(z.object({
+  text: z.string(),
+  done: z.boolean().default(false),
+}))
+// todos._inferredType is { text: string; done: boolean }
+```
+
+### `z`
+
+Re-exported from [Zod](https://zod.dev). Use it to define your schemas.
+
+## Collection CRUD
+
+Every collection in `app.collections` gets these methods:
+
+```ts
+// Create — returns the document with metadata fields
+const doc = await app.todos.create({ text: 'Buy hops', done: false })
+// doc._id, doc._collection, doc._updatedAt, doc._deleted are added automatically
+
+// Read
+const all = await app.todos.findMany()
+const one = await app.todos.findOne(doc._id)
+
+// Update — merges partial data
+await app.todos.update(doc._id, { done: true })
+
+// Delete — soft delete (sets _deleted: true for sync propagation)
+await app.todos.delete(doc._id)
+```
+
+## Auth
+
+```ts
+// Sign up
+await app.auth.signUp({ email: 'user@example.com', password: 'secret' })
+
+// Sign in
+await app.auth.signIn({ email: 'user@example.com', password: 'secret' })
+
+// Sign out
+await app.auth.signOut()
+
+// Current user
+const user = app.auth.currentUser() // { id, email } | null
+```
+
+Passwords are hashed client-side (PBKDF2) before transmission. Sessions are JWTs cached locally for offline access.
+
+## Sync
+
+Sync happens automatically when configured with an `endpoint`. MPB LocalKit uses a Last-Write-Wins (LWW) protocol — the document with the highest `_updatedAt` timestamp wins conflicts.
+
+```ts
+// Manual sync
+await app.sync()
+```
+
+Sync triggers automatically on:
+- Tab focus (returning to the app)
+- Network reconnect (coming back online)
+- Periodic interval (configurable, default 30s)
+
+All reads and writes hit local storage immediately — sync never blocks the UI.
+
+## React Hooks
+
+```tsx
+import { useCollection, useAuth, useSync } from 'mpb-localkit/react'
+import { app } from './schema'
+
+function BrewList() {
+  const { data: brews, isLoading } = useCollection(app.brews)
+  const { user, signIn, signOut } = useAuth(app)
+  const { status, lastSyncAt } = useSync(app)
+
+  if (isLoading) return <div>Loading...</div>
+
+  return (
+    <ul>
+      {brews.map(brew => <li key={brew._id}>{brew.style}</li>)}
+    </ul>
+  )
+}
+```
+
+## CLI
+
+```bash
+# Start local dev (SDK works without a Worker)
+npx mpb-localkit dev
+
+# Generate Cloudflare Worker from your schema
+npx mpb-localkit build --name my-app
+
+# Build + deploy to Cloudflare
+npx mpb-localkit deploy
+```
+
+The generated Worker handles auth, sync, and error storage via Cloudflare R2 + KV.
+
+## Architecture
+
+```
+Your App (React/Vue/Svelte)
+        ↓
+  Framework Bindings
+  (useCollection, useAuth)
+        ↓
+     Core SDK
+  ┌──────────────────────────────┐
+  │  Schema  │  Sync  │  Auth   │
+  │  Engine  │ Engine │ Module  │
+  ├──────────────────────────────┤
+  │      Local Storage           │
+  │    (IndexedDB, via idb)      │
+  └──────────────────────────────┘
+        ↓ (when online)
+  Cloudflare Worker (generated)
+  ┌──────────────────────────────┐
+  │  Auth   │  Sync  │  Errors  │
+  │ Routes  │ Routes │  Routes  │
+  ├──────────────────────────────┤
+  │    Cloudflare R2 + KV        │
+  └──────────────────────────────┘
+```
+
+**All writes hit IndexedDB first** — your app works fully offline. The sync engine pushes/pulls changes to the Cloudflare Worker when connectivity is available.
+
+## Document Shape
+
+Every document has these metadata fields added automatically:
+
+```ts
+{
+  _id: string          // UUIDv7 — sortable by creation time
+  _collection: string  // Collection name
+  _updatedAt: number   // Unix ms — the sync cursor
+  _deleted: boolean    // Soft delete for sync propagation
+  // ...your fields
+}
+```
+
+## Create a New App
+
+The fastest way to start is with the scaffolder:
+
+```bash
+npm create mpb-localkit@latest
+# or
+pnpm create mpb-localkit@latest
+```
+
+It prompts for project name, framework, auth method, sync transport, and deploy target — then scaffolds a ready-to-run project and installs dependencies.
+
+```
+? Project name: my-app
+? Framework: React
+? Auth method: Email + Password
+? Sync transport: Auto (WebSocket with HTTP fallback)
+? Deploy target: Cloudflare Workers
+
+Done! Your project is ready.
+  cd my-app
+  pnpm run dev
+```
+
+## Transport Configuration
+
+MPB LocalKit supports three sync transports, configurable at `createApp` time:
+
+### HTTP Transport (default)
+
+Polling-based sync. Works everywhere, no persistent connection required.
+
+```ts
+const app = createApp({
+  collections: { ... },
+  sync: {
+    transport: 'http',
+    endpoint: 'https://your-worker.workers.dev',
+    interval: 30000,
+  },
+})
+```
+
+### WebSocket Transport
+
+Persistent connection for real-time sync. The server pushes changes as they happen.
+
+```ts
+const app = createApp({
+  collections: { ... },
+  sync: {
+    transport: 'websocket',
+    endpoint: 'wss://your-worker.workers.dev',
+  },
+})
+```
+
+### Auto Transport (recommended)
+
+Starts a WebSocket connection and falls back to HTTP polling if WebSocket is unavailable. Best of both worlds.
+
+```ts
+const app = createApp({
+  collections: { ... },
+  sync: {
+    transport: 'auto',
+    endpoint: 'https://your-worker.workers.dev',
+  },
+})
+```
+
+With `auto`, MPB LocalKit upgrades to WebSocket when the server supports it and degrades gracefully on restricted networks.
+
+## WebSocket Sync
+
+When using `transport: 'websocket'` or `transport: 'auto'`, MPB LocalKit maintains a persistent WebSocket connection to your sync Worker. The Worker sends change events as they occur — no polling delay.
+
+```ts
+import { createApp, collection, z } from 'mpb-localkit'
+
+const app = createApp({
+  collections: {
+    messages: collection(z.object({
+      text: z.string(),
+      author: z.string(),
+    })),
+  },
+  sync: {
+    transport: 'auto',
+    endpoint: 'https://chat.your-subdomain.workers.dev',
+  },
+})
+
+// Writes go to IndexedDB immediately (no await on network)
+await app.messages.create({ text: 'Hello!', author: 'alice' })
+
+// The Worker broadcasts the change to all connected clients via WebSocket
+// Recipients see the new message arrive without polling
+```
+
+The WebSocket connection is managed automatically:
+- Reconnects with exponential backoff on disconnect
+- Replays missed changes on reconnect using the LWW cursor
+- Falls back to HTTP polling when WebSocket is unavailable (Auto mode)
+
+## Better Auth Integration
+
+MPB LocalKit integrates with [Better Auth](https://better-auth.com) for full-featured server-side authentication.
+
+### Setup
+
+```ts
+import { createApp, collection, z } from 'mpb-localkit'
+
+const app = createApp({
+  collections: {
+    notes: collection(z.object({ text: z.string() })),
+  },
+  auth: {
+    type: 'better-auth',
+    baseURL: 'https://auth.your-domain.com',
+  },
+  sync: {
+    transport: 'auto',
+    endpoint: 'https://sync.your-domain.com',
+  },
+})
+```
+
+### Session handling
+
+Better Auth sessions are cached locally so the app stays functional offline. The session is re-validated against the server on reconnect.
+
+```ts
+// Sign in — stores session locally for offline access
+await app.auth.signIn({ email: 'user@example.com', password: 'secret' })
+
+// Current user is available immediately (from local cache)
+const user = app.auth.currentUser() // { id, email, name } | null
+
+// Sync automatically includes the session token in requests
+await app.sync()
+
+// Sign out clears the local session
+await app.auth.signOut()
+```
+
+### React hooks with Better Auth
+
+```tsx
+import { useAuth, useCollection } from 'mpb-localkit/react'
+import { app } from './schema'
+
+function App() {
+  const { user, signIn, signOut, isLoading } = useAuth(app)
+  const { data: notes } = useCollection(app.notes)
+
+  if (isLoading) return <div>Loading...</div>
+  if (!user) return <SignInForm onSignIn={signIn} />
+
+  return (
+    <div>
+      <p>Signed in as {user.email}</p>
+      <ul>{notes.map(n => <li key={n._id}>{n.text}</li>)}</ul>
+      <button onClick={signOut}>Sign out</button>
+    </div>
+  )
+}
+```
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node