@seedprotocol/sdk 0.7.4 → 0.7.5-next.850.g9ab585b

package/README.md

@@ -0,0 +1,99 @@
+# @seedprotocol/sdk
+
+[![npm](https://img.shields.io/npm/v/@seedprotocol/sdk.svg)](https://www.npmjs.com/package/@seedprotocol/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/node/v/@seedprotocol/sdk.svg)](https://nodejs.org)
+[![Docs](https://img.shields.io/badge/docs-seedprotocol.io-0B6E4F)](https://seedprotocol.io)
+
+The official TypeScript SDK for [Seed Protocol](https://seedprotocol.io): a local-first, decentralized data layer.
+
+**[→ Full documentation at seedprotocol.io](https://seedprotocol.io)**
+
+## What it does
+
+- **Local-first ORM.** Define schemas, models and properties; the SDK stores items in SQLite and files in OPFS in the user's browser (or on disk in Node).
+- **Decentralized sync.** Data is read from and published to the [Ethereum Attestation Service (EAS)](https://attest.sh) and [Arweave](https://www.arweave.org). There is no backend for you to run.
+- **No custody.** User data lives on public infrastructure and in the user's browser, not on your servers.
+
+Built and used by [PermaPress](https://permapress.xyz), the first client for Seed Protocol (by [JournoLabs](https://journolabs.xyz)).
+
+## Requirements
+
+- **Node.js** `>= 20` and `<= 24`
+- **Browser:** a modern browser with OPFS (e.g. Chromium-based, recent Firefox)
+
+## Installation
+
+```bash
+npm install @seedprotocol/sdk
+# or
+bun add @seedprotocol/sdk
+# or
+pnpm add @seedprotocol/sdk
+```
+
+Browser apps built with Vite should also add [`@seedprotocol/vite`](https://www.npmjs.com/package/@seedprotocol/vite). For React hooks, add [`@seedprotocol/react`](https://www.npmjs.com/package/@seedprotocol/react).
+
+## Quick start
+
+Initialize the client once, then create schemas, models and items:
+
+```ts
+import { client, Schema, Model } from '@seedprotocol/sdk'
+
+await client.init({
+  config: {
+    filesDir: '.seed',
+    endpoints: { filePaths: '/files', files: '.seed' }, // optional on Node when filesDir is set
+  },
+})
+
+const schema = await Schema.create('Blog')
+
+const Post = await Model.create('Post', schema, {
+  properties: {
+    title: { dataType: 'Text' },
+    content: { dataType: 'Html' },
+    publishedAt: { dataType: 'Date' },
+  },
+})
+
+const post = await Post.create({ title: 'Hello', content: '<p>First post</p>' })
+
+// Update by assignment; the SDK persists the change.
+post.title = 'Hello, world'
+```
+
+You can also declare your schema in a config file at the project root: `seed.config.ts` (recommended), `seed.schema.ts`, or `schema.ts`.
+
+To publish items to EAS and Arweave, use [`@seedprotocol/publish`](https://www.npmjs.com/package/@seedprotocol/publish).
+
+See the [Getting Started guide](https://github.com/JournoLabs/seed-protocol-sdk/blob/main/docs/GETTING_STARTED.md) for configuration, address sessions, property types, files and images.
+
+## Entry points
+
+| Import | Use |
+| --- | --- |
+| `@seedprotocol/sdk` | Main API: `client`, `Schema`, `Model`, `Item`, `ItemProperty`, query helpers |
+| `@seedprotocol/sdk/node` | Node entry: `client`, `Item`, `FileManager`, `Db`, and `withSeed` for webpack configs |
+| `@seedprotocol/sdk/platform` | Platform services: `configurePlatform`, `createPlatformServices` |
+| `@seedprotocol/sdk/vite` | Re-export of `seedVitePlugin` from `@seedprotocol/vite` |
+
+ESM is recommended. CommonJS also works: `const { Schema, Model, Item } = require('@seedprotocol/sdk')`.
+
+## Related packages
+
+| Package | Description |
+| --- | --- |
+| [`@seedprotocol/react`](https://www.npmjs.com/package/@seedprotocol/react) | React hooks and components |
+| [`@seedprotocol/publish`](https://www.npmjs.com/package/@seedprotocol/publish) | Publish flow (EAS attestations + Arweave uploads) |
+| [`@seedprotocol/vite`](https://www.npmjs.com/package/@seedprotocol/vite) | Vite plugin for browser apps |
+| [`@seedprotocol/query`](https://www.npmjs.com/package/@seedprotocol/query) | Canonical Seed JSON queries over EAS or local SQLite |
+| [`@seedprotocol/feed`](https://www.npmjs.com/package/@seedprotocol/feed) | RSS, Atom and JSON Feed generation |
+| [`@seedprotocol/mapping`](https://www.npmjs.com/package/@seedprotocol/mapping) | Field mapping from external sources to models |
+| [`@seedprotocol/eas`](https://www.npmjs.com/package/@seedprotocol/eas) | EAS GraphQL read client |
+| [`@seedprotocol/arweave`](https://www.npmjs.com/package/@seedprotocol/arweave) | Arweave gateway client |
+
+## License
+
+MIT

package/dist/{BasePathResolver-DrzGVH9L.js → BasePathResolver-CsZHPrk9.js}

@@ -1,6 +1,6 @@
 import debug from 'debug';
 import { isEasAttestationExplorerUrl, BaseArweaveClient, ensureReadGatewaySelected, getArweaveReadBaseUrls, getTransactionTagsByIds } from '@seedprotocol/arweave';
-import { easName, localNamesInBestMatchTier, BaseQueryClient, BaseEasClient, GET_FILES_METADATA } from '@seedprotocol/eas';
+import { easName, DEFAULT_NAME_MATCH_LEVEL, compareNameMatchTiers, isNameMatchLevel, localNamesInBestMatchTier, BaseQueryClient, BaseEasClient, GET_FILES_METADATA } from '@seedprotocol/eas';
 import { waitFor } from 'xstate';
 import pluralize from 'pluralize';
 import { Type } from '@sinclair/typebox';
@@ -1307,6 +1307,133 @@ function stackWithoutFrames(stack) {
         .join('\n');
 }
 
+const level = (value) => (isNameMatchLevel(value) ? value : undefined);
+const tighter = (a, b) => a === undefined || compareNameMatchTiers(b, a) < 0 ? b : a;
+/** The levels in one schema file for one of its models, or undefined when the file lacks the model. */
+const modelLevelsFromFile = (file, modelName) => {
+    const modelDef = file.models?.[modelName];
+    if (!modelDef)
+        return undefined;
+    const model = level(modelDef.nameMatch) ?? level(file.nameMatch) ?? DEFAULT_NAME_MATCH_LEVEL;
+    const properties = new Map();
+    for (const [propertyName, def] of Object.entries(modelDef.properties ?? {})) {
+        properties.set(propertyName, level(def?.nameMatch) ?? model);
+    }
+    return { model, properties };
+};
+/**
+ * Builds NameMatchLevels from the schema files that own each model row. Exported for tests;
+ * use {@link nameMatchLevels}.
+ */
+const nameMatchLevelsFromRows = (rows) => {
+    const byFileId = new Map();
+    const byName = new Map();
+    const parsed = new Map();
+    for (const row of rows) {
+        if (!row.schemaData)
+            continue;
+        if (!parsed.has(row.schemaData)) {
+            try {
+                parsed.set(row.schemaData, JSON.parse(row.schemaData));
+            }
+            catch {
+                parsed.set(row.schemaData, undefined);
+            }
+        }
+        const file = parsed.get(row.schemaData);
+        const levels = file && modelLevelsFromFile(file, row.modelName);
+        if (!levels)
+            continue;
+        if (row.modelFileId)
+            byFileId.set(row.modelFileId, levels);
+        const seen = byName.get(row.modelName);
+        if (!seen) {
+            byName.set(row.modelName, { model: levels.model, properties: new Map(levels.properties) });
+            continue;
+        }
+        seen.model = tighter(seen.model, levels.model);
+        for (const [name, value] of levels.properties)
+            seen.properties.set(name, tighter(seen.properties.get(name), value));
+    }
+    return {
+        model: (modelName) => byName.get(modelName)?.model ?? DEFAULT_NAME_MATCH_LEVEL,
+        property: (modelName, propertyName, modelFileId) => {
+            const levels = (modelFileId ? byFileId.get(modelFileId) : undefined) ?? byName.get(modelName);
+            return levels?.properties.get(propertyName) ?? levels?.model ?? DEFAULT_NAME_MATCH_LEVEL;
+        },
+    };
+};
+const DEFAULT_LEVELS = {
+    model: () => DEFAULT_NAME_MATCH_LEVEL,
+    property: () => DEFAULT_NAME_MATCH_LEVEL,
+};
+let current;
+let loading;
+/** Reads the levels from the schema files stored with each model's schema row (schemas.schema_data). */
+const loadNameMatchLevels = async (db = BaseDb.getAppDb()) => {
+    if (!db)
+        return DEFAULT_LEVELS;
+    const load = (async () => {
+        const rows = (await db
+            .select({ modelName: models.name, modelFileId: models.schemaFileId, schemaData: schemas.schemaData })
+            .from(models)
+            .innerJoin(modelSchemas, eq(models.id, modelSchemas.modelId))
+            .innerJoin(schemas, eq(modelSchemas.schemaId, schemas.id)));
+        return nameMatchLevelsFromRows(rows);
+    })();
+    loading = load;
+    try {
+        const levels = await load;
+        if (loading === load)
+            current = levels;
+        return levels;
+    }
+    finally {
+        if (loading === load)
+            loading = undefined;
+    }
+};
+/** The levels, loaded once and reused until a schema write clears them. */
+const nameMatchLevels = async (db = BaseDb.getAppDb()) => current ?? loading ?? loadNameMatchLevels(db);
+/**
+ * The last loaded levels, for synchronous callers (Model.findByModelType). Sync and the post-init
+ * model type pass load them; before that every name is at DEFAULT_NAME_MATCH_LEVEL.
+ */
+const currentNameMatchLevels = () => current ?? DEFAULT_LEVELS;
+/** Called when a schema row or its models are written, so the next read reloads. */
+const clearNameMatchLevels = () => {
+    current = undefined;
+    loading = undefined;
+};
+/**
+ * `nameMatch` values in a schema file that aren't a level. They are ignored (the next level up
+ * applies); schema loads warn about them.
+ */
+const invalidNameMatchValues = (file) => {
+    const problems = [];
+    const check = (where, value) => {
+        if (value !== undefined && !isNameMatchLevel(value)) {
+            problems.push(`${where} nameMatch ${JSON.stringify(value)} is not 'exact', 'normalized' or 'fuzzy'`);
+        }
+    };
+    check('schema', file.nameMatch);
+    for (const [modelName, modelDef] of Object.entries(file.models ?? {})) {
+        check(modelName, modelDef?.nameMatch);
+        for (const [propertyName, def] of Object.entries(modelDef?.properties ?? {})) {
+            check(`${modelName}.${propertyName}`, def?.nameMatch);
+        }
+    }
+    return problems;
+};
+/** Warns about {@link invalidNameMatchValues}. */
+const warnOnInvalidNameMatch = (file) => {
+    const problems = invalidNameMatchValues(file);
+    for (const problem of problems) {
+        console.warn(`[seed] schema ${file.metadata?.name ?? ''}: ${problem}; it is ignored.`);
+    }
+    return problems;
+};
+
 /**
  * Thrown when a model name exists in more than one schema and nothing says which one is meant.
  * Model names are only unique within a schema; pass `schemaName` (or `modelFileId`) to choose.
@@ -1390,14 +1517,16 @@ const resolveModelRecordByNameOnly = async (modelName, db, label = Array.isArray
 /**
  * The model names a model name or EAS model type can refer to: the name itself, else the names
  * that match it in the tightest tier (ADR 0008, as Model.findByModelType matches): `new_model` →
- * "New model", `sync_storage_post` → "SyncStoragePost", `htmlpage` → "HTMLPage".
+ * "New model", `sync_storage_post` → "SyncStoragePost", `htmlpage` → "HTMLPage". Each name at its
+ * nameMatch level (ADR 0009).
  */
 const modelNamesForNameOrType = async (nameOrType, db) => {
     const rows = (await db.selectDistinct({ name: models.name }).from(models));
     const names = rows.map((r) => r.name);
     if (names.includes(nameOrType))
         return [nameOrType];
-    return [...localNamesInBestMatchTier(nameOrType, names)];
+    const levels = await nameMatchLevels(db);
+    return [...localNamesInBestMatchTier(nameOrType, names, { level: (name) => levels.model(name) })];
 };
 /**
  * resolveModelRecord for a model name **or** an EAS model type (snake_case model name, what sync
@@ -2085,6 +2214,8 @@ const addSchemaToDb = async (schema, schemaFileId, schemaData, isDraft, isEdited
     if (!db) {
         throw new Error('Database not found');
     }
+    // The stored schema file may change its nameMatch levels (ADR 0009).
+    clearNameMatchLevels();
     // First, try to find existing schema by schemaFileId (preferred for change tracking)
     if (schemaFileId) {
         const existingByFileId = await db
@@ -2553,6 +2684,8 @@ const addModelsToDb = async (models$1, schema, modelRenames, schemaFileData) =>
     if (!db) {
         throw new Error('Database not found');
     }
+    // Model rows and their schema links decide which schema file's nameMatch applies (ADR 0009).
+    clearNameMatchLevels();
     // If schema is provided, add it to the database
     // Note: schema might already be a database record (with id) if passed from importJsonSchema
     let schemaRecord;
@@ -3938,7 +4071,7 @@ const syncDbFiles = async (endpoints) => {
 const getAppDbReady = async () => {
     if (!BaseDb.isAppDbReady()) {
         // Wait for ClientManager to be ready (DB_INIT state or later)
-        const _mod_0 = await import('./ClientManager-Dfu4jcgm.js');
+        const _mod_0 = await import('./ClientManager-DETTj0_z.js');
         const _ns_0 = _mod_0.M;
         const clientManagerMod = _ns_0;
         const { getClient } = clientManagerMod;
@@ -4334,8 +4467,9 @@ const INTERNAL_DATA_TYPES = {
     Text: {
         eas: 'string',
     },
+    // ADR 0010: decimal strings, so negatives, fractions and values above 255 publish.
     Number: {
-        eas: 'uint8',
+        eas: 'string',
     },
     Image: {
         eas: 'bytes32',
@@ -4831,5 +4965,5 @@ class BasePathResolver {
 }
 BasePathResolver._impl = null;
 
-export { generateId as $, seeds as A, uploadProcesses as B, versions as C, DEFAULT_TEXT_MAX_LENGTH as D, BaseDb as E, resolveStorageNameToSchemaName as F, AmbiguousModelError as G, eventEmitter as H, BasePathResolver as I, BaseFileManager as J, getPropertyIdForModelAndName as K, resolveItemModelFileId as L, ModelPropertyDataTypes as M, resolveSeedIdsFromRefString as N, normalizeRelationPropertyValue as O, Property as P, isPublishedSeedRef as Q, getStorageDirForDataType as R, getContentSha256 as S, THtmlEmbeddedDataUriPolicy as T, buildArweaveContentTags as U, getItemStorageSubdir as V, getItemStorageLocalFileName as W, normalizePublisher as X, getAllAddressesFromDb as Y, scheduleBulkFilesDownloadFromEasSync as Z, EAS_SEED_DATA_SYNCED_TO_DB_EVENT as _, TProperty as a, getPropertyIdForSchemaFileId as a$, normalizeHexAddress as a0, listRelationEasPropertyName as a1, easPropertyNameForPublish as a2, toMetadataPropertyName as a3, getItemStoragePropertiesForModel as a4, addModelsToDb as a5, INIT_SCRIPT_SUCCESS_MESSAGE as a6, SCHEMA_TS as a7, getCorrectId as a8, SEED_CONFIG_FILE as a9, ensureImageLocal as aA, getAddressesForItemsFilter as aB, getFeedItemStringField as aC, normalizeAddressConfig as aD, normalizeAddressList as aE, normalizeArweaveTxIdForEnsure as aF, normalizeFeedItemFields as aG, resolveMediaRef as aH, isInternalSchema as aI, writeModelToDb as aJ, writePropertyToDb as aK, addSchemaToDb as aL, renameModelInDb as aM, loadModelsFromDbForSchema as aN, downloadAllFilesRequestHandler as aO, downloadAllFilesBinaryRequestHandler as aP, INTERNAL_SCHEMA_IDS as aQ, linkModelToSchema as aR, getWatchedAddressesFromDb as aS, getOwnedAddressesFromDb as aT, CLIENT_NOT_INITIALIZED as aU, toSchemaPropertyName as aV, getStorageTransactionIdForSeedUid as aW, convertTxIdToImage as aX, getMetadataPropertyNamesForQuery as aY, downloadTransactionIdWithDedupe as aZ, resolveMetadataRecord as a_, SEED_CONFIG_FALLBACKS as aa, isNode as ab, ZERO_BYTES32 as ac, resolveModelRecord as ad, getItemModelScope as ae, VERSION_SCHEMA_UID as af, INTERNAL_PROPERTY_NAMES as ag, isStorageSeedRef as ah, defaultAttestationData as ai, INTERNAL_DATA_TYPES as aj, isBrowser as ak, getModelIdByFileId as al, getModelId as am, setCachedPropertyRefresher as an, getArweaveUrlForTransaction as ao, INTERNAL_STORAGE_MODEL_FILE_IDS as ap, CONTENT_SHA256_TAG as aq, CONTENT_TYPE_TAG as ar, ImageSize as as, SEED_PROTOCOL_SCHEMA_NAME as at, SeedModels as au, VERSION_SCHEMA_DEF as av, VERSION_SCHEMA_UID_OPTIMISM_SEPOLIA as aw, classifyMediaRef as ax, closestImageSize as ay, contentSha256TagMatches as az, TPropertyConstructor as b, getDataTypeFromString as b0, getMimeType as b1, listRelationStoragePropertyName as b2, PROPERTY_NAMES_EXEMPT_FROM_ID_SUFFIX_STRIP as b3, getAlternatePropertyNameForInstanceLookup as b4, BaseDb$1 as b5, ModelSchema as b6, BaseFileManager$1 as b7, SchemaSchema as b8, ModelSchemaSchema as b9, resolveModelRecord$1 as ba, db as bb, download as bc, generateId$1 as bd, TPropertyDataType as c, TPropertyDefs as d, TStorageType as e, TValidationRules as f, normalizePropertyRecordSchema as g, appState as h, isDataType as i, arweaveL1FinalizeJobs as j, config as k, easSyncProcesses as l, metadata as m, normalizeDataType as n, htmlEmbeddedImageCoPublish as o, modelRelations as p, modelSchemas as q, modelUids as r, models as s, modelsRelations as t, properties as u, propertiesRelations as v, propertyUidRelations as w, propertyUids as x, publishProcesses as y, schemas as z };
-//# sourceMappingURL=BasePathResolver-DrzGVH9L.js.map
+export { getCorrectId as $, seeds as A, uploadProcesses as B, versions as C, DEFAULT_TEXT_MAX_LENGTH as D, BaseDb as E, resolveStorageNameToSchemaName as F, AmbiguousModelError as G, eventEmitter as H, nameMatchLevels as I, BasePathResolver as J, BaseFileManager as K, getPropertyIdForModelAndName as L, ModelPropertyDataTypes as M, resolveItemModelFileId as N, resolveSeedIdsFromRefString as O, Property as P, normalizeRelationPropertyValue as Q, isPublishedSeedRef as R, getStorageDirForDataType as S, THtmlEmbeddedDataUriPolicy as T, getContentSha256 as U, buildArweaveContentTags as V, getItemStorageSubdir as W, getItemStorageLocalFileName as X, addModelsToDb as Y, INIT_SCRIPT_SUCCESS_MESSAGE as Z, SCHEMA_TS as _, TProperty as a, getStorageTransactionIdForSeedUid as a$, SEED_CONFIG_FILE as a0, SEED_CONFIG_FALLBACKS as a1, isNode as a2, ZERO_BYTES32 as a3, resolveModelRecord as a4, getItemModelScope as a5, VERSION_SCHEMA_UID as a6, INTERNAL_PROPERTY_NAMES as a7, isStorageSeedRef as a8, defaultAttestationData as a9, closestImageSize as aA, contentSha256TagMatches as aB, ensureImageLocal as aC, getAddressesForItemsFilter as aD, getFeedItemStringField as aE, normalizeAddressConfig as aF, normalizeAddressList as aG, normalizeArweaveTxIdForEnsure as aH, normalizeFeedItemFields as aI, resolveMediaRef as aJ, isInternalSchema as aK, writeModelToDb as aL, writePropertyToDb as aM, addSchemaToDb as aN, renameModelInDb as aO, currentNameMatchLevels as aP, loadModelsFromDbForSchema as aQ, clearNameMatchLevels as aR, downloadAllFilesRequestHandler as aS, downloadAllFilesBinaryRequestHandler as aT, warnOnInvalidNameMatch as aU, INTERNAL_SCHEMA_IDS as aV, linkModelToSchema as aW, getWatchedAddressesFromDb as aX, getOwnedAddressesFromDb as aY, CLIENT_NOT_INITIALIZED as aZ, toSchemaPropertyName as a_, INTERNAL_DATA_TYPES as aa, listRelationEasPropertyName as ab, easPropertyNameForPublish as ac, isBrowser as ad, EAS_SEED_DATA_SYNCED_TO_DB_EVENT as ae, normalizePublisher as af, getAllAddressesFromDb as ag, loadNameMatchLevels as ah, scheduleBulkFilesDownloadFromEasSync as ai, generateId as aj, normalizeHexAddress as ak, toMetadataPropertyName as al, getItemStoragePropertiesForModel as am, getModelIdByFileId as an, getModelId as ao, setCachedPropertyRefresher as ap, getArweaveUrlForTransaction as aq, INTERNAL_STORAGE_MODEL_FILE_IDS as ar, CONTENT_SHA256_TAG as as, CONTENT_TYPE_TAG as at, ImageSize as au, SEED_PROTOCOL_SCHEMA_NAME as av, SeedModels as aw, VERSION_SCHEMA_DEF as ax, VERSION_SCHEMA_UID_OPTIMISM_SEPOLIA as ay, classifyMediaRef as az, TPropertyConstructor as b, convertTxIdToImage as b0, getMetadataPropertyNamesForQuery as b1, downloadTransactionIdWithDedupe as b2, resolveMetadataRecord as b3, getPropertyIdForSchemaFileId as b4, getDataTypeFromString as b5, getMimeType as b6, listRelationStoragePropertyName as b7, PROPERTY_NAMES_EXEMPT_FROM_ID_SUFFIX_STRIP as b8, getAlternatePropertyNameForInstanceLookup as b9, BaseDb$1 as ba, ModelSchema as bb, BaseFileManager$1 as bc, SchemaSchema as bd, ModelSchemaSchema as be, resolveModelRecord$1 as bf, db as bg, download as bh, generateId$1 as bi, TPropertyDataType as c, TPropertyDefs as d, TStorageType as e, TValidationRules as f, normalizePropertyRecordSchema as g, appState as h, isDataType as i, arweaveL1FinalizeJobs as j, config as k, easSyncProcesses as l, metadata as m, normalizeDataType as n, htmlEmbeddedImageCoPublish as o, modelRelations as p, modelSchemas as q, modelUids as r, models as s, modelsRelations as t, properties as u, propertiesRelations as v, propertyUidRelations as w, propertyUids as x, publishProcesses as y, schemas as z };
+//# sourceMappingURL=BasePathResolver-CsZHPrk9.js.map