@fileverse-dev/ddoc 5.1.13 → 5.1.14-storage-agnostic.0

package/dist/package/types.d.ts

@@ -136,6 +136,15 @@ export interface DdocProps extends CommentAccountProps {
     };
     tabSectionContainer?: HTMLElement;
     isCollabDocumentPublished?: boolean;
+    /**
+     * Storage-agnostic image fetch function. Receives the stored location of an
+     * encrypted image (`url` + `contentRef`, e.g. an IPFS gateway URL + CID or a
+     * Swarm URL + reference) along with its decryption parameters, and returns
+     * the decrypted image. Preferred over the deprecated `ipfsImageFetchFn`;
+     * when both are provided, `imageFetchFn` wins.
+     */
+    imageFetchFn?: ImageFetchFn;
+    /** @deprecated Use the storage-agnostic `imageFetchFn` instead. */
     ipfsImageFetchFn?: (_data: IpfsImageFetchPayload) => Promise<{
         url: string;
         file: File;
@@ -174,6 +183,15 @@ export interface DdocProps extends CommentAccountProps {
     isPreviewMode: boolean;
     viewerMode?: 'suggest' | 'view-only';
     ensResolutionUrl?: string;
+    /**
+     * Storage-agnostic image upload function. Encrypts and stores the file on
+     * the host's storage backend (IPFS, Swarm, ...) and returns its location
+     * (`url` + `contentRef`) plus the decryption parameters. Preferred over the
+     * deprecated `ipfsImageUploadFn`; when both are provided, `imageUploadFn`
+     * wins.
+     */
+    imageUploadFn?: ImageUploadFn;
+    /** @deprecated Use the storage-agnostic `imageUploadFn` instead. */
     ipfsImageUploadFn?: (file: File) => Promise<IpfsImageUploadResponse>;
     enableIndexeddbSync?: boolean;
     ddocId?: string;
@@ -290,6 +308,39 @@ export interface IUser {
     isEns: boolean;
 }
 export { type IComment };
+/**
+ * Storage-agnostic result of an image upload. The editor treats both fields
+ * as opaque: `url` is a fetchable location of the encrypted blob (e.g. an
+ * IPFS gateway URL or a Swarm `/bytes` URL) and `contentRef` is the backend's
+ * content address (IPFS CID, Swarm reference, ...). Both are stored in the
+ * document and handed back verbatim to `imageFetchFn`.
+ */
+export interface StorageImageUploadResponse {
+    encryptionKey: string;
+    nonce: string;
+    authTag: string;
+    url: string;
+    contentRef: string;
+}
+/**
+ * Storage-agnostic payload handed to `imageFetchFn`: the `url`/`contentRef`
+ * returned by `imageUploadFn` at upload time, plus the parameters needed to
+ * decrypt the blob.
+ */
+export interface StorageImageFetchPayload {
+    encryptionKey: string;
+    nonce: string;
+    authTag: string;
+    mimeType: string;
+    url: string;
+    contentRef: string;
+}
+export type ImageUploadFn = (file: File) => Promise<StorageImageUploadResponse>;
+export type ImageFetchFn = (_data: StorageImageFetchPayload) => Promise<{
+    url: string;
+    file: File;
+}>;
+/** @deprecated Use the storage-agnostic {@link StorageImageUploadResponse} instead. */
 export interface IpfsImageUploadResponse {
     encryptionKey: string;
     nonce: string;
@@ -297,6 +348,7 @@ export interface IpfsImageUploadResponse {
     ipfsHash: string;
     authTag: string;
 }
+/** @deprecated Use the storage-agnostic {@link StorageImageFetchPayload} instead. */
 export interface IpfsImageFetchPayload {
     encryptionKey: string;
     nonce: string;

package/dist/package/utils/storage-adapter.d.ts

@@ -0,0 +1,30 @@
+import { ImageFetchFn, ImageUploadFn, IpfsImageFetchPayload, IpfsImageUploadResponse } from '../types';
+
+/**
+ * Boundary adapters between the storage-agnostic public props
+ * (`imageUploadFn` / `imageFetchFn`) and the IPFS-shaped interface the editor
+ * internals still use. Internals are untouched: a storage-agnostic host
+ * function is wrapped here, at the prop boundary, so that downstream code
+ * keeps seeing the legacy `ipfsUrl` / `ipfsHash` field names regardless of
+ * which backend the host actually stores on.
+ */
+type LegacyImageUploadFn = (file: File) => Promise<IpfsImageUploadResponse>;
+type LegacyImageFetchFn = (_data: IpfsImageFetchPayload) => Promise<{
+    url: string;
+    file: File;
+}>;
+/**
+ * Resolve the upload function to use internally. The storage-agnostic
+ * `imageUploadFn` wins over the deprecated `ipfsImageUploadFn`; its response
+ * is mapped onto the legacy field names (`url` → `ipfsUrl`,
+ * `contentRef` → `ipfsHash`).
+ */
+export declare const resolveImageUploadFn: (imageUploadFn?: ImageUploadFn, ipfsImageUploadFn?: LegacyImageUploadFn) => LegacyImageUploadFn | undefined;
+/**
+ * Resolve the fetch function to use internally. The storage-agnostic
+ * `imageFetchFn` wins over the deprecated `ipfsImageFetchFn`; the legacy
+ * payload built by the internals is mapped onto the agnostic field names
+ * (`ipfsUrl` → `url`, `ipfsHash` → `contentRef`).
+ */
+export declare const resolveImageFetchFn: (imageFetchFn?: ImageFetchFn, ipfsImageFetchFn?: LegacyImageFetchFn) => LegacyImageFetchFn | undefined;
+export {};

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fileverse-dev/ddoc",
   "private": false,
   "description": "DDoc",
-  "version": "5.1.13",
+  "version": "5.1.14-storage-agnostic.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fileverse/fileverse-ddocs.git"