@seedprotocol/sdk 0.7.3-next.613.g79a8dfd → 0.7.3

package/dist/src/helpers/itemStorageFile.d.ts

@@ -0,0 +1,57 @@
+import { type MetadataType } from '../seedSchema';
+export type ItemStorageFileTarget = {
+    /** The item's seedUid, else its seedLocalId: the file is `<seedId><extension>`. */
+    seedId: string;
+    /** The property's `storage.path` (e.g. `/html`); `files` when unset. */
+    localStorageDir?: string | null;
+    /** The property's `storage.extension` (e.g. `.html`). */
+    filenameSuffix?: string | null;
+    /** An existing file name to write to instead (the row's refResolvedValue). */
+    fileName?: string | null;
+};
+/** Absolute path of the file {@link writeItemStorageFile} writes for `target`. */
+export declare const getItemStorageFilePath: (target: ItemStorageFileTarget) => string;
+/**
+ * Write an ItemStorage property's content to its local file, where saveItemStorage, reads, publish
+ * (resolveItemStorageChildFile) and download all look for it. Returns what the metadata row records:
+ * `refResolvedValue` (the file name) and `localStorageDir` (with a leading slash).
+ *
+ * Callers that also update the file's metadata row hold {@link withItemStorageFileLock} around
+ * both, so another writer of the same file can't land in between.
+ */
+export declare const writeItemStorageFile: (target: ItemStorageFileTarget, content: string | Blob | ArrayBuffer) => Promise<{
+    fileName: string;
+    filePath: string;
+    localStorageDir: string;
+}>;
+/**
+ * Lock name for one ItemStorage file: `seed:item-storage:<absolute file path>`. The path starts
+ * with the files root, which also names the database (`<filesDir>/db/seed.db`), so the name is
+ * per database as well as per file.
+ */
+export declare const itemStorageFileLockName: (filePath: string) => string;
+/**
+ * Runs `fn` holding the lock of one ItemStorage file, across tabs (Web Locks) and within this JS
+ * realm (an in-process queue where Web Locks are missing, e.g. Node < 24.5; see `withTabLock`).
+ *
+ * Writers of a local draft's file (saveItemStorage, convertVerbatimItemStorageRow, createNewItem)
+ * hold it across "read the row → write the file → update the row", so the file and the row end
+ * with the same writer's content. See docs/MULTI_TAB.md.
+ *
+ * Lock ordering: this lock is always the innermost. It may be taken while holding a broader lock
+ * (`seed:item-storage-migration:<db>`, `seed:publish:<seedLocalId>`), never the other way round,
+ * and no other lock (nor a second file lock) is requested while it is held. Keep the section to
+ * local DB and file I/O: no network. Not re-entrant.
+ */
+export declare function withItemStorageFileLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Runs `fn` with a fresh read of metadata row `localId`, holding the lock of the file that row's
+ * content goes to. `fileOf` names that file (absolute path) for a row, or returns undefined when
+ * there is nothing to write (then `fn` isn't called and the result is undefined).
+ *
+ * The file depends on the row, so the row is read once to pick the lock and again once it is held;
+ * if the row now points at another file (another writer changed it meanwhile), the lock is
+ * released and taken again for that file.
+ */
+export declare function withLockedItemStorageRow<T>(localId: string, fileOf: (row: MetadataType) => string | undefined, fn: (row: MetadataType, filePath: string) => Promise<T>): Promise<T | undefined>;
+//# sourceMappingURL=itemStorageFile.d.ts.map

package/dist/src/helpers/itemStorageFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"itemStorageFile.d.ts","sourceRoot":"","sources":["../../../src/helpers/itemStorageFile.ts"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AAK1D,MAAM,MAAM,qBAAqB,GAAG;IAClC,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,GAAI,QAAQ,qBAAqB,KAAG,MAIpE,CAAA;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,qBAAqB,EAC7B,SAAS,MAAM,GAAG,IAAI,GAAG,WAAW,KACnC,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAOzE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,MAAM,KAAG,MAAyC,CAAA;AAEpG;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE7F;AAcD;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,EACjD,EAAE,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACtD,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAgBxB"}

package/dist/src/helpers/mapWithConcurrency.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `Promise.all(items.map(fn))` with at most `limit` calls in flight. Results keep the input order.
+ * Rejects with the first error (by time); after that no new calls start, though calls already in
+ * flight run to completion.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=mapWithConcurrency.d.ts.map

package/dist/src/helpers/mapWithConcurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapWithConcurrency.d.ts","sourceRoot":"","sources":["../../../src/helpers/mapWithConcurrency.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAoBd"}

package/dist/src/helpers/mimeTypes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * File extension <-> MIME type, shared by the upload side (`getPublishUploads.ts`, which sets the
+ * `Content-Type` tag) and the download worker (`browser/workers/filesDownload.ts`, which picks the
+ * extension of a file saved under `files/`). The worker runs from a string and cannot import this
+ * module, so {@link MIME_TO_EXTENSION} is injected into its source as JSON.
+ */
+/**
+ * Lowercase extension (no dot) to MIME type. Includes the odd extensions the SDK itself produces:
+ * `saveImage` names a file `<id>.<subtype>` (e.g. `.svg+xml`, `.x-icon`), so subtypes appear here too.
+ */
+export declare const EXTENSION_TO_MIME: Readonly<Record<string, string>>;
+/**
+ * MIME type to the extension a downloaded file gets. One canonical extension per type (the
+ * first one listed here wins over {@link EXTENSION_TO_MIME}'s aliases), plus a few common
+ * non-canonical spellings a gateway may send.
+ */
+export declare const MIME_TO_EXTENSION: Readonly<Record<string, string>>;
+/**
+ * Content types that say nothing about the content. A Blob carrying one of these is treated as
+ * untyped.
+ */
+export declare const GENERIC_MIME_TYPES: readonly string[];
+/** Lowercase `type/subtype` without parameters; `undefined` when empty or generic. */
+export declare const normalizeMimeType: (mimeType: string | null | undefined) => string | undefined;
+/** MIME type for a path or file name by its extension, if it has a known one. */
+export declare const getMimeTypeFromPath: (filePathOrName: string) => string | undefined;
+/** Extension (no dot) for a MIME type, if it has a well-known one. */
+export declare const getExtensionForMimeType: (mimeType: string | null | undefined) => string | undefined;
+/**
+ * MIME type from the leading bytes, for formats with an unambiguous signature. Used when a local
+ * file has no (known) extension, e.g. a file seed named after its id.
+ */
+export declare const sniffMimeType: (bytes: Uint8Array) => string | undefined;
+/**
+ * Best MIME type for upload bytes: the source's own type (a Blob/File `type`) when it is specific,
+ * then the file name's extension, then the bytes' signature.
+ */
+export declare const resolveUploadMimeType: (params: {
+    sourceType?: string | null;
+    fileName?: string | null;
+    bytes?: Uint8Array;
+}) => string | undefined;
+//# sourceMappingURL=mimeTypes.d.ts.map

package/dist/src/helpers/mimeTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mimeTypes.d.ts","sourceRoot":"","sources":["../../../src/helpers/mimeTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwE9D,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiC3D,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAI/C,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,SAIhF,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,GAAI,gBAAgB,MAAM,KAAG,MAAM,GAAG,SAKrE,CAAA;AAED,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,GAAI,UAAU,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,SAGtF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,UAAU,KAAG,MAAM,GAAG,SA4B1D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ;IAC5C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,UAAU,CAAA;CACnB,KAAG,MAAM,GAAG,SAG6C,CAAA"}

package/dist/src/helpers/ownership.d.ts

@@ -1,6 +1,13 @@
 import type { IItem } from '../interfaces/IItem';
 import { seeds } from '../seedSchema';
 import { type SQL } from 'drizzle-orm';
+/**
+ * Thrown by write operations (save, destroy, publish, unpublish) on an item none
+ * of the client's addresses own. See isItemOwned for what counts as owned.
+ */
+export declare class OwnershipError extends Error {
+    constructor(message?: string);
+}
 type ItemLike = {
     seedLocalId?: string;
     seedUid?: string;
@@ -25,12 +32,28 @@ export declare function publisherIsInOwnedSet(publisher: string | null | undefin
  */
 export declare function isSeedRowOwned(row: SeedOwnershipRow, ownedAddresses: readonly string[]): boolean;
 /**
- * SQL for `addressFilter: 'owned' | 'watched'`. Empty list → no rows (`1=0`).
- * Compares `lower(publisher)` so checksummed rows match persisted lowercase owned.
+ * SQL for an address list on `publisher`. Empty list → no rows (`1=0`).
+ * Compares `lower(publisher)` so checksummed rows match persisted lowercase addresses.
+ * Used for `addressFilter: 'watched'`; `'owned'` uses {@link ownedSeedsSql}.
  */
 export declare function publisherInAddressListSql(column: typeof seeds.publisher, addresses: readonly string[]): SQL;
-/** Owned-list SQL on `seeds.publisher`. */
+/**
+ * @deprecated Matches `seeds.publisher` only. Use {@link ownedSeedsSql}, which agrees
+ * with {@link isSeedRowOwned} (empty owned → local unsealed drafts; attester fallback).
+ */
 export declare function ownedPublisherSql(ownedAddresses: readonly string[]): SQL;
+/** SQL form of {@link isPlaceholderUid}: null, `''`, `'NULL'`, or zero bytes32 (trimmed, any case). */
+export declare function placeholderUidSql(column: typeof seeds.uid): SQL;
+/** SQL form of {@link isLocalUnsealedDraft} on `seeds`. */
+export declare function localUnsealedDraftSql(): SQL;
+/**
+ * SQL for `addressFilter: 'owned'`: a row passes exactly when {@link isSeedRowOwned} is true.
+ * - Empty owned → local unsealed drafts (pre-connect authoring), not every row.
+ * - Owned set → `lower(trim(publisher))` in the set, or, when publisher is blank, the
+ *   `attestationRaw.attester` ({@link resolvePublisherFromSeedRow}). `json_valid` guards
+ *   `json_extract`, which throws on malformed JSON.
+ */
+export declare function ownedSeedsSql(ownedAddresses: readonly string[]): SQL;
 /**
  * Checks if the current user owns the item (publisher is in persisted owned addresses).
  *
@@ -46,7 +69,8 @@ export declare function ownedPublisherSql(ownedAddresses: readonly string[]): SQ
  */
 export declare function isItemOwned(item: ItemLike | IItem<any>): Promise<boolean>;
 /**
- * Throws if the item is not owned. Use before write operations (publish, save, destroy).
+ * Throws OwnershipError if the item is not owned. Use before write operations
+ * (publish, save, destroy).
  */
 export declare function assertItemOwned(item: ItemLike | IItem<any>): Promise<void>;
 export {};

package/dist/src/helpers/ownership.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ownership.d.ts","sourceRoot":"","sources":["../../../src/helpers/ownership.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE/C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACpC,OAAO,EAAoB,KAAK,GAAG,EAAE,MAAM,aAAa,CAAA;AAOxD,KAAK,QAAQ,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB,CAAA;AA6BD,2FAA2F;AAC3F,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAWhF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAMnE;AAED,8DAA8D;AAC9D,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,OAAO,CAIT;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,gBAAgB,EACrB,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,OAAO,CAMT;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,KAAK,CAAC,SAAS,EAC9B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,GAAG,CAML;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAExE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAK/E;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhF"}
+{"version":3,"file":"ownership.d.ts","sourceRoot":"","sources":["../../../src/helpers/ownership.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE/C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACpC,OAAO,EAAqC,KAAK,GAAG,EAAE,MAAM,aAAa,CAAA;AAQzE;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,SAAkB;CAKtC;AAED,KAAK,QAAQ,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB,CAAA;AA6BD,2FAA2F;AAC3F,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAWhF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAMnE;AAED,8DAA8D;AAC9D,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,OAAO,CAIT;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,gBAAgB,EACrB,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,OAAO,CAMT;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,KAAK,CAAC,SAAS,EAC9B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,GAAG,CAML;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAExE;AAED,uGAAuG;AACvG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,KAAK,CAAC,GAAG,GAAG,GAAG,CAO/D;AAKD,2DAA2D;AAC3D,wBAAgB,qBAAqB,IAAI,GAAG,CAM3C;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAUpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAK/E;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhF"}