@seedprotocol/sdk 0.4.4 → 0.4.6

package/README.md

@@ -1,377 +1,67 @@
 # Seed Protocol SDK
 
-The official SDK for [Seed Protocol](https://seedprotocol.io/).
+The official JavaScript/TypeScript SDK for [Seed Protocol](https://seedprotocol.io)—a local-first, decentralized data layer.
 
-The SDK is a heavily opinionated ORM that saves its database (SQLite) and files (OPFS) within the user's browser. All
-user data
-is fetched from, or written to, the Ethereum Attestation Service (EAS) and Arweave (More attestation services
-and decentralized storage providers will be supported in the future).
+**[→ Full documentation at seedprotocol.io](https://seedprotocol.io)**
 
-With all the remote storage on decentralized, public infrastructure, there's no server component to manage or rely on.
-
-The hope is that this local-first and distributed approach will make it easier for developers to build apps with Seed
-Protocol
-without ever custodying user data on their own infrastructure.
-
-The SDK is currently used and developed by [PermaPress](https://permapress.xyz), the first client for Seed Protocol.
-PermaPress is a product developed by JournoLabs (formerly JournoDAO).
-
-## Installing
-
-```bash
-npm install @seedprotocol/sdk
-# or
-pnpm add @seedprotocol/sdk
-# or
-bun add @seedprotocol/sdk
-```
-
-### Module System Support
-
-The SDK supports both ESM and CommonJS module systems:
-
-**ESM (Recommended):**
-```javascript
-import { Model, Property, Item } from '@seedprotocol/sdk'
-```
-
-**CommonJS:**
-```javascript
-const { Model, Property, Item } = require('@seedprotocol/sdk')
-```
-
-## Getting Started
-
-The first thing to do when integrating Seed SDK is define your data model by creating a configuration file in the root
-of your project. The SDK supports the following file names (in order of preference):
-
-- `seed.config.ts` (recommended)
-- `seed.schema.ts` 
-- `schema.ts` (legacy)
-
-As an example, here's the actual data model for PermaPress using `seed.config.ts`:
-
-```typescript
-import { ImageSrc, List, Model, Relation, Text } from '@/browser/schema'
-
-@Model
-class Image {
-  @Text() storageTransactionId!: string
-  @Text() uri!: string
-  @Text() alt!: string
-  @ImageSrc() src!: string
-}
-
-@Model
-class Post {
-  @Text() title!: string
-  @Text() summary!: string
-  @Relation('Image', 'ImageSrc') featureImage!: string
-  @Text('ItemStorage', '/html', '.html') html!: string
-  @Text('ItemStorage', '/json', '.json') json!: string
-  @Text() storageTransactionId!: string
-  @List('Identity') authors!: string[]
-  @Text() importUrl!: string
-}
-
-@Model
-class Identity {
-  @Text() name!: string
-  @Text() profile!: string
-  @Text() displayName!: string
-  @Relation('Image', 'ImageSrc') avatarImage!: string
-  @Relation('Image', 'ImageSrc') coverImage!: string
-}
-
-@Model
-class Link {
-  @Text() url!: string
-  @Text() text!: string
-}
-
-const models = {
-  Identity,
-  Image,
-  Link,
-  Post,
-}
-
-const endpoints = {
-  filePaths: '/api/seed/migrations',
-  files: '/app-files',
-}
-
-export { models, endpoints }
-
-export default { models, endpoints }
-
-```
-
-This will create a database locally in the browser with all the tables and fields necessary to support your Models.
-
-> [!NOTE]
-> The database is a SQLite file stored
-> in [OPFS](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system).
-> We recommend using
-> the [OPFS Explorer](https://chromewebstore.google.com/detail/opfs-explorer/acndjpgkpaclldomagafnognkcgjignd)
-> browser extension to see the files managed by the SDK.
-
-Notice that we create relationships by defining a `Property` that takes its related `Model` as its type. For one-to-many
-relationships, we use the `List` type and pass in the `Model` type we want.
-
-So creating a Post would look like this:
-
-```typescript
-import { Post, Image, Identity } from './seed/models'
-import html                      from './index.html'
-
-const image = await Image.create({
-  src: 'https://imgr.com/image.jpg',
-})
-
-const author = await Identity.create({
-  name: 'Keith Axline',
-  profile: 'Developer for Seed Protocol',
-})
-
-const authors = [
-  author
-]
-
-const post = await Post.create({
-  title: 'Some title',
-  summary: 'My summary',
-  featureImage: image,
-  authors,
-})
-
-await post.publish()
-
-// And later when we want to update the post
-post.title = 'Something else'
-
-await post.publish()
-
-```
-
-## Usage
-
-### `Item`
-
-Create
-
-```typescript
-
-```
-
-### Files
-
-Subscribe to events:
-
-```typescript
-import { SeedFile } from '@seedprotocol/sdk'
+---
 
-const fileFromUrl = new SeedFile('https://example.com/file.txt')
+## What it does
 
-fileFromUrl.subscribe(( event, status ) => {
-  console.log(`Event: ${event}, Status: ${status}`)
-})
+- **Local-first ORM** — Define models and properties; the SDK stores data in SQLite and OPFS in the user’s browser.
+- **Decentralized sync** — Data is read from and written to the [Ethereum Attestation Service (EAS)](https://attest.sh) and [Arweave](https://www.arweave.org). No backend for you to run or maintain.
+- **No custody** — User data stays on public infrastructure and in the user’s browser, not on your servers.
 
-await fileFromUrl.save()
+Built and used by [PermaPress](https://permapress.xyz), the first client for Seed Protocol (by [JournoLabs](https://journolabs.xyz)).
 
-```
+## Documentation
 
-Create files from various sources:
+For setup, schema definition, models, items, files, and React integration, see:
 
-```typescript
-const fileFromPath = new SeedFile('path/to/file.txt')
+**https://seedprotocol.io**
 
-const fileFromBlob = new SeedFile(new Blob([ 'Hello, World!' ]))
+## Requirements
 
-const fileFromBuffer = new SeedFile(Buffer.from('Hello, World!'))
+- **Node.js** `>= 20` and `<= 24`
+- **Browser** support: modern browsers with OPFS (e.g. Chromium-based, recent Firefox)
 
-const fileFromFile = new SeedFile(new File([ 'Hello, World!' ], 'file.txt'))
+## Installation
 
-if ( fileFromPath.isSaved ) {
-  console.log('File is saved to Arweave and EAS')
-}
+```bash
+bun add @seedprotocol/sdk
+# or
+npm install @seedprotocol/sdk
+# or
+pnpm add @seedprotocol/sdk
 ```
 
-Use the `SeedFileSystem`
-
-```typescript
-import { SeedFileSystem } from '@seedprotocol/sdk'
-
-const fs = new SeedFileSystem()
-
-fs.subscribe(( event, status ) => {
-  console.log(`Event: ${event}, Status: ${status}`)
-  if ( event === 'connection.success' && status === 'connected' ) {
-    console.log('Connected to user\'s file system')
-  }
-
-  if ( event === 'connection.error' ) {
-    console.error('Error connecting to user\'s file system', event.error)
-  }
-})
-
-await fs.connect() // User prompted to connect browser wallet
-
-const files = await fs.listFiles('/')
-
-files.forEach(file => {
-  console.log(file.name)
-  console.log(file.size)
-  console.log(file.seedPath) // Each wallet address has a virtual root directory with directories and file system paths
-})
+**Optional (React):** If you use React hooks (`useModel`, `useSchema`, etc.), install peer dependencies:
 
+```bash
+bun add react @tanstack/react-query
 ```
 
-### Images
-
-```typescript
+## Quick start
 
-import { SeedImage } from '@seedprotocol/sdk'
+1. **Define your schema** in a config file at the project root: `seed.config.ts` (recommended), `seed.schema.ts`, or `schema.ts`.
 
-const imgFromUrl = new SeedImage('https://example.com/image.png')
+2. **Use the SDK** in your app:
 
-const imgFromDataUrl = new SeedImage('data:image/png;base64,iVB....')
-
-await imgFromUrl.save()
-
-const imgBlob    = imgFromUrl.blob()
-const imgBuffer  = imgFromUrl.buffer()
-const imgDataUrl = imgFromUrl.dataUrl()
+```ts
+import { Model, Property, Item } from '@seedprotocol/sdk'
 
+// Define models in your schema; then create and publish items:
+const post = await Post.create({ title: 'Hello', summary: '...', ... })
+await post.publish()
 ```
 
-```mermaid
----
-Title: Seed Protocol SDK
----
-%%{
-  init: {
-    'theme': 'base',
-    'themeVariables': {
-      'primaryColor': '#e0f2fe',
-      'primaryTextColor': '#0c4a6e',
-      'primaryBorderColor': '#38bdf8',
-      'lineColor': '#475569',
-      'secondaryColor': '#d9f99d',
-      'tertiaryColor': '#fff',
-      'tertiaryBorderColor': '#7e22ce',
-      'tertiaryTextColor': '#7e22ce',
-      'clusterBkg': '#fff'
-    }
-  }
-}%%
-flowchart TD
-    A{Developer}
-    B{User}
-    C{Seed Dev}
-    N{SDK}
-    Q[App Code]
-    D[(sdk_config_db)]
-    E[(seed)]
-    L[(seeds_db)]
-    G[Schema/Migration files
-    browser/db/seedSchema]
-H[Schema/Migration files
-.seed/schema]
-R[Schema/Migration files
-node/db/sdkSchema]
-
-I[browser.seed.db.config.mjs]
-J[sdk.db.config.mjs]
-
-O[files.json
-seed/endpoint/list]
-P[Files
-seed/endpoint/files]
-
-S[$> seed init]
-T[scripts/bin]
+For full guides on schema, models, properties, items, files, and the CLI, see **[the docs](https://seedprotocol.io)**.
 
-subgraph SDK Code
-C--changes Seeds or Versions --> I
-C-- changes Models or Properties --> J
-J-- generates -->R
-I-- generates --> G
-subgraph Package Bundle
-R
-G
-end
-end
+## Module support
 
+- **ESM** (recommended): `import { Model, Property, Item } from '@seedprotocol/sdk'`
+- **CommonJS**: `const { Model, Property, Item } = require('@seedprotocol/sdk')`
 
+## License
 
-subgraph App Code
-A-- adds Models and Properties --> K
-subgraph SDK
-D
-H
-end
-A-- runs --> S
-S-- calls --> T
-T-- reads--> K
-T-- generates --> D
-T-- generates --> H
-end
-
-subgraph App Server
-H-- served at endpoint --> O
-H-- served at endpoint --> P
-end
-
-
-
-subgraph Browser
-B-- adds data--> Q
-subgraph App
-Q-- calls SDK--> N
-subgraph SDK
-E-- notifies -->N
-N<-- files . json --> O
-N<-- files --> P
-N-- updates -->E
-N-- updates --> L
-
-end
-end
-end
-
-
-```
-
-A[Versions From EAS]
-B[Seeds From EAS]
-C[List of Items]
-D[List of Properties]
-E{Property Machine}
-F{Item Machine}
-G{Items Machine}
-
-```mermaid
-sequenceDiagram
-    Items Service ->>+ EAS: Seeds Request
-    EAS -->>+ Items Service: Seed Attestations
-    loop Each Seed Attestation
-        Items Service ->>+ Items Service: Extract Seed Uid
-    end
-    Note over Items Service: Now we have SeedUid[]
-    Items Service ->>+ EAS: Versions Request w/ SeedUid[]
-    EAS -->>+ Items Service: Version Attestations
-    loop Each SeedUid
-        Items Service ->>+ Items Service: Sort Version Uids DESC
-    end
-    loop Each most recent Version for Seed
-        Items Service ->>+ Item Service: Create Item
-    end
-    Note over Items Service: Now we have VersionUid[] for each SeedUid<br />sorted by `createdAt` DESC
-    Item Service ->>+ EAS: Properties Request w/ VersionUid[]
-    EAS -->>+ Item Service: Properties Attestations
-    loop Each Property Attestation
-        Item Service ->>+ Property Service: Create Property Service
-    end
-    Note over Item Service: Now has all Property Services<br />under this._services
-```
+MIT

package/dist/{ArweaveClient-DkNLWiSZ.js → ArweaveClient-Caio37h1.js}

@@ -1,20 +1,20 @@
-import { z as BaseArweaveClient } from './ClientManager-DoHUt8tU.js';
+import { u as BaseArweaveClient } from './index-Dk73a7JE.js';
 import { GraphQLClient } from 'graphql-request';
 import Arweave from 'arweave';
-import { G as GET_TRANSACTION_TAGS } from './queries-DGOk16cd.js';
+import { G as GET_TRANSACTION_TAGS } from './queries-DA4G0iEN.js';
 import debug from 'debug';
 import 'xstate';
+import 'drizzle-orm/sqlite-core';
 import 'drizzle-orm';
+import 'nanoid';
+import 'nanoid-dictionary';
 import 'pluralize';
+import 'ethers';
 import 'rxjs';
 import 'lodash-es';
 import 'drizzle-orm/casing';
-import '@sinclair/typebox';
 import 'eventemitter3';
-import 'drizzle-orm/sqlite-core';
-import 'nanoid';
-import 'nanoid-dictionary';
-import 'ethers';
+import '@sinclair/typebox';
 
 const logger = debug("seedSdk:browser:ArweaveClient");
 // Cached Arweave instance
@@ -199,4 +199,4 @@ class ArweaveClient extends BaseArweaveClient {
 BaseArweaveClient.setPlatformClass(ArweaveClient);
 
 export { ArweaveClient };
-//# sourceMappingURL=ArweaveClient-DkNLWiSZ.js.map
+//# sourceMappingURL=ArweaveClient-Caio37h1.js.map

package/dist/ArweaveClient-Caio37h1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArweaveClient-Caio37h1.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/{ArweaveClient-CczHvccG.js → ArweaveClient-DLKAaS3K.js}

@@ -1,20 +1,20 @@
-import { z as BaseArweaveClient } from './ClientManager-DoHUt8tU.js';
+import { u as BaseArweaveClient } from './index-Dk73a7JE.js';
 import { GraphQLClient } from 'graphql-request';
 import Arweave from 'arweave';
-import { G as GET_TRANSACTION_TAGS } from './queries-DGOk16cd.js';
+import { G as GET_TRANSACTION_TAGS } from './queries-DA4G0iEN.js';
 import debug from 'debug';
 import 'xstate';
+import 'drizzle-orm/sqlite-core';
 import 'drizzle-orm';
+import 'nanoid';
+import 'nanoid-dictionary';
 import 'pluralize';
+import 'ethers';
 import 'rxjs';
 import 'lodash-es';
 import 'drizzle-orm/casing';
-import '@sinclair/typebox';
 import 'eventemitter3';
-import 'drizzle-orm/sqlite-core';
-import 'nanoid';
-import 'nanoid-dictionary';
-import 'ethers';
+import '@sinclair/typebox';
 
 const logger = debug('seedSdk:node:ArweaveClient');
 // Cached Arweave instance
@@ -199,4 +199,4 @@ class ArweaveClient extends BaseArweaveClient {
 BaseArweaveClient.setPlatformClass(ArweaveClient);
 
 export { ArweaveClient };
-//# sourceMappingURL=ArweaveClient-CczHvccG.js.map
+//# sourceMappingURL=ArweaveClient-DLKAaS3K.js.map

package/dist/ArweaveClient-DLKAaS3K.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArweaveClient-DLKAaS3K.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/{Db-DJvjXVlp.js → Db-C9fppVRl.js}

@@ -1,23 +1,23 @@
-import { p as BaseDb, s as BaseFileManager } from './ClientManager-DoHUt8tU.js';
+import { p as BaseDb, x as BaseFileManager } from './index-Dk73a7JE.js';
 import debug from 'debug';
 import { sql } from 'drizzle-orm';
 import { readMigrationFiles } from 'drizzle-orm/migrator';
 import { drizzle } from 'drizzle-orm/sqlite-proxy';
 import { migrate } from 'drizzle-orm/sqlite-proxy/migrator';
-import { s as schema } from './index-D2OGsG4v.js';
+import { s as schema } from './index-DBy53qbb.js';
 import { SQLocalDrizzle } from 'sqlocal/drizzle';
 import { Observable, distinctUntilChanged } from 'rxjs';
 import 'xstate';
-import 'pluralize';
-import 'lodash-es';
-import 'drizzle-orm/casing';
-import '@sinclair/typebox';
-import 'arweave';
-import 'eventemitter3';
 import 'drizzle-orm/sqlite-core';
 import 'nanoid';
 import 'nanoid-dictionary';
+import 'pluralize';
 import 'ethers';
+import 'lodash-es';
+import 'drizzle-orm/casing';
+import 'eventemitter3';
+import 'arweave';
+import '@sinclair/typebox';
 
 // This file embeds the drizzle migration files as strings for browser runtime
 // These files are copied from src/db/drizzle at build time
@@ -1511,4 +1511,4 @@ class Db extends BaseDb {
 }
 
 export { Db };
-//# sourceMappingURL=Db-DJvjXVlp.js.map
+//# sourceMappingURL=Db-C9fppVRl.js.map

package/dist/Db-C9fppVRl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Db-C9fppVRl.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/{Db-BzQR2KX9.js → Db-DJAG-5Di.js}

@@ -1,29 +1,30 @@
-import { p as BaseDb, u as appState } from './ClientManager-DoHUt8tU.js';
+import { p as BaseDb, y as appState } from './index-Dk73a7JE.js';
 import path from 'path';
 import debug from 'debug';
-import { s as schema } from './index-D2OGsG4v.js';
+import { s as schema } from './index-DBy53qbb.js';
 import fs__default from 'fs';
 import { createClient } from '@libsql/client';
 import { drizzle } from 'drizzle-orm/libsql';
 import { pushSQLiteSchema } from 'drizzle-kit/api';
 import { interval, startWith, switchMap, distinctUntilChanged } from 'rxjs';
 import 'xstate';
+import 'drizzle-orm/sqlite-core';
 import 'drizzle-orm';
+import 'nanoid';
+import 'nanoid-dictionary';
 import 'pluralize';
+import 'ethers';
 import 'lodash-es';
 import 'drizzle-orm/casing';
-import '@sinclair/typebox';
-import 'arweave';
 import 'eventemitter3';
-import 'drizzle-orm/sqlite-core';
-import 'nanoid';
-import 'nanoid-dictionary';
-import 'ethers';
+import 'arweave';
+import '@sinclair/typebox';
 
 const logger = debug('seedSdk:node:db:Db');
 const getConfig = async (dotSeedDir, config) => {
     // Create config inline - config values can be passed in or use defaults
-    const { defineConfig } = await import('drizzle-kit');
+    const drizzleKitMod = await import('drizzle-kit');
+    const { defineConfig } = drizzleKitMod;
     const appSchemaDir = config?.schemaDir || path.join(dotSeedDir, 'schema');
     const outDir = config?.outDir || `${dotSeedDir}/db`;
     const dbUrl = config?.dbUrl || `${dotSeedDir}/db/seed.db`;
@@ -239,7 +240,8 @@ class Db extends BaseDb {
             // In drizzle-kit, migrations are generated in the 'out' directory (which is pathToDbDir)
             // migrate(this.db, { migrationsFolder: pathToDbDir })
             // NEW CODE: Use libsql migrator
-            const { migrate } = await import('drizzle-orm/libsql/migrator');
+            const migratorMod = await import('drizzle-orm/libsql/migrator');
+            const { migrate } = migratorMod;
             // migrationsFolder should point to the directory containing migration SQL files
             // In drizzle-kit, migrations are generated in the 'out' directory (which is pathToDbDir)
             await migrate(this.db, { migrationsFolder: pathToDbDir });
@@ -340,4 +342,4 @@ class Db extends BaseDb {
 BaseDb.setPlatformClass(Db);
 
 export { Db };
-//# sourceMappingURL=Db-BzQR2KX9.js.map
+//# sourceMappingURL=Db-DJAG-5Di.js.map

package/dist/Db-DJAG-5Di.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Db-DJAG-5Di.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/{EasClient-CHQYmjj2.js → EasClient-DQGAIj-b.js}

@@ -1,19 +1,19 @@
-import { x as BaseEasClient, E as EAS_ENDPOINT } from './ClientManager-DoHUt8tU.js';
+import { w as BaseEasClient, E as EAS_ENDPOINT } from './index-Dk73a7JE.js';
 import { GraphQLClient } from 'graphql-request';
 import 'xstate';
+import 'drizzle-orm/sqlite-core';
 import 'drizzle-orm';
+import 'nanoid';
+import 'nanoid-dictionary';
 import 'debug';
 import 'pluralize';
+import 'ethers';
 import 'rxjs';
 import 'lodash-es';
 import 'drizzle-orm/casing';
-import '@sinclair/typebox';
-import 'arweave';
 import 'eventemitter3';
-import 'drizzle-orm/sqlite-core';
-import 'nanoid';
-import 'nanoid-dictionary';
-import 'ethers';
+import 'arweave';
+import '@sinclair/typebox';
 
 class EasClient extends BaseEasClient {
     static getEasClient() {
@@ -26,4 +26,4 @@ class EasClient extends BaseEasClient {
 BaseEasClient.setPlatformClass(EasClient);
 
 export { EasClient };
-//# sourceMappingURL=EasClient-CHQYmjj2.js.map
+//# sourceMappingURL=EasClient-DQGAIj-b.js.map

package/dist/EasClient-DQGAIj-b.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EasClient-DQGAIj-b.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/{EasClient-CodrIgW-.js → EasClient-T7Nx9185.js}

@@ -1,19 +1,19 @@
-import { x as BaseEasClient, E as EAS_ENDPOINT } from './ClientManager-DoHUt8tU.js';
+import { w as BaseEasClient, E as EAS_ENDPOINT } from './index-Dk73a7JE.js';
 import { GraphQLClient } from 'graphql-request';
 import 'xstate';
+import 'drizzle-orm/sqlite-core';
 import 'drizzle-orm';
+import 'nanoid';
+import 'nanoid-dictionary';
 import 'debug';
 import 'pluralize';
+import 'ethers';
 import 'rxjs';
 import 'lodash-es';
 import 'drizzle-orm/casing';
-import '@sinclair/typebox';
-import 'arweave';
 import 'eventemitter3';
-import 'drizzle-orm/sqlite-core';
-import 'nanoid';
-import 'nanoid-dictionary';
-import 'ethers';
+import 'arweave';
+import '@sinclair/typebox';
 
 class EasClient extends BaseEasClient {
     static getEasClient() {
@@ -26,4 +26,4 @@ class EasClient extends BaseEasClient {
 BaseEasClient.setPlatformClass(EasClient);
 
 export { EasClient };
-//# sourceMappingURL=EasClient-CodrIgW-.js.map
+//# sourceMappingURL=EasClient-T7Nx9185.js.map

package/dist/EasClient-T7Nx9185.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EasClient-T7Nx9185.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}