@rakelabs/evidence-publisher 0.1.0

package/dist/src/EvidencePublisher.d.ts

@@ -0,0 +1,35 @@
+import { HttpPinByCidClient } from './http/HttpPinByCidClient.js';
+import type { AttachmentStore, EvidenceStore } from './storage-types.js';
+import type { Attachment, CidInput, EvidencePublishRequest, EvidencePublishResult, PinResult, PublishedAttachment, RemotePinningConfig } from './types.js';
+export interface EvidencePublisherOptions {
+    attachmentStore?: AttachmentStore;
+    documentStore: EvidenceStore;
+    /** Optional client for explicit CID pinning operations via {@link EvidencePublisher.pinCid}. */
+    pinByCidClient?: HttpPinByCidClient;
+    /**
+     * Optional remote pinning configuration.
+     * When set (and not disabled), the publisher forwards every produced CID to the
+     * configured pinning service as a post-publish durability step.
+     */
+    remotePinning?: RemotePinningConfig;
+    /** Called by {@link EvidencePublisher.close} to release underlying resources (e.g. stop Helia). */
+    onClose?: () => Promise<void>;
+}
+export declare class EvidencePublisher {
+    private readonly options;
+    constructor(options: EvidencePublisherOptions);
+    publish(input: EvidencePublishRequest): Promise<EvidencePublishResult>;
+    uploadAttachment(input: Attachment): Promise<PublishedAttachment>;
+    pinCid(input: CidInput): Promise<PinResult>;
+    /**
+     * Release underlying resources (e.g. stop the Helia node).
+     * Always call this when the publisher is no longer needed.
+     */
+    close(): Promise<void>;
+    /**
+     * Runs the remote pinning step if configured.
+     * Failures are caught and surfaced via {@link RemotePinOutcome.error} so the
+     * publish result is never hidden by a persistence failure.
+     */
+    private runRemotePinning;
+}

package/dist/src/EvidencePublisher.js

@@ -0,0 +1,105 @@
+import { EvidenceHasher } from './EvidenceHasher.js';
+import { EvidenceJsonBuilder } from './EvidenceJsonBuilder.js';
+import { HttpPinByCidClient } from './http/HttpPinByCidClient.js';
+export class EvidencePublisher {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async publish(input) {
+        let documentDraft;
+        let publishedAttachment;
+        if (input.attachment) {
+            if (!this.options.attachmentStore) {
+                throw new Error('attachmentStore is required when attachment is provided');
+            }
+            publishedAttachment = await this.options.attachmentStore.putAttachment(input.attachment);
+            documentDraft = EvidenceJsonBuilder.withAttachment(input, publishedAttachment);
+        }
+        else {
+            documentDraft = EvidenceJsonBuilder.build(input);
+        }
+        const selfHash = EvidenceHasher.hashEvidenceDocumentWithoutSelfHash(documentDraft);
+        const documentWithSelfHash = EvidenceJsonBuilder.withSelfHash(documentDraft, selfHash);
+        const publishedDocument = await this.options.documentStore.putEvidenceDocument(documentWithSelfHash);
+        const baseResult = {
+            selfHash,
+            documentJson: documentWithSelfHash,
+            ...(publishedAttachment ? { attachment: publishedAttachment } : {}),
+            document: publishedDocument,
+        };
+        const remotePinning = await this.runRemotePinning(publishedDocument, publishedAttachment);
+        return {
+            ...baseResult,
+            ...(remotePinning !== undefined ? { remotePinning } : {}),
+        };
+    }
+    async uploadAttachment(input) {
+        if (!this.options.attachmentStore) {
+            throw new Error('attachmentStore is required to upload attachments');
+        }
+        return this.options.attachmentStore.putAttachment(input);
+    }
+    async pinCid(input) {
+        if (!this.options.pinByCidClient) {
+            throw new Error('pinByCidClient is required to pin CIDs');
+        }
+        // No per-request auth override — the client uses its own configured auth.
+        const result = await this.options.pinByCidClient.pinByCid({ cid: input.cid });
+        return {
+            cid: result.cid ?? input.cid,
+            ...(result.cid ? { uri: `ipfs://${result.cid}` } : {}),
+        };
+    }
+    /**
+     * Release underlying resources (e.g. stop the Helia node).
+     * Always call this when the publisher is no longer needed.
+     */
+    async close() {
+        await this.options.onClose?.();
+    }
+    // ── Remote pinning pipeline ──────────────────────────────────────────────
+    /**
+     * Runs the remote pinning step if configured.
+     * Failures are caught and surfaced via {@link RemotePinOutcome.error} so the
+     * publish result is never hidden by a persistence failure.
+     */
+    async runRemotePinning(document, attachment) {
+        const config = this.options.remotePinning;
+        if (!config || config.enabled === false) {
+            return undefined;
+        }
+        const client = new HttpPinByCidClient({
+            providerUrl: config.endpoint,
+            auth: config.auth,
+            requestPath: config.requestPath,
+            headers: config.headers,
+        });
+        try {
+            const docPinResponse = await client.pinByCid({ cid: document.cid });
+            const documentPin = {
+                cid: docPinResponse.cid ?? document.cid,
+                ...(docPinResponse.cid ? { uri: `ipfs://${docPinResponse.cid}` } : {}),
+                ...(docPinResponse.pinId ? { metadata: { pinId: docPinResponse.pinId } } : {}),
+            };
+            let attachmentPin;
+            if (attachment) {
+                const attPinResponse = await client.pinByCid({ cid: attachment.cid });
+                attachmentPin = {
+                    cid: attPinResponse.cid ?? attachment.cid,
+                    ...(attPinResponse.cid ? { uri: `ipfs://${attPinResponse.cid}` } : {}),
+                    ...(attPinResponse.pinId ? { metadata: { pinId: attPinResponse.pinId } } : {}),
+                };
+            }
+            return {
+                documentPin,
+                ...(attachmentPin ? { attachmentPin } : {}),
+            };
+        }
+        catch (err) {
+            return {
+                error: err instanceof Error ? err : new Error(String(err)),
+            };
+        }
+    }
+}

package/dist/src/EvidencePublisherFactory.d.ts

@@ -0,0 +1,83 @@
+import { type StorageConfig, type StorageConfigReadOptions } from './config.js';
+import { EvidencePublisher } from './EvidencePublisher.js';
+import { MetaEvidencePublisher } from './MetaEvidencePublisher.js';
+import type { AttachmentStore, EvidenceStore, MetaEvidenceStore } from './storage-types.js';
+import type { RemotePinningConfig, RequestAuth, RequestFields, UploadRequest } from './types.js';
+export interface EvidencePublisherFactoryOptions extends StorageConfigReadOptions {
+    /**
+     * Explicit config supplied by code. When present, file reads are bypassed.
+     */
+    config?: StorageConfig;
+    /** Optional YAML file path used only when `config` is not supplied. */
+    configFilePath?: string;
+    gatewayBaseUrls?: string[];
+    attachmentStore?: AttachmentStore;
+    documentStore?: EvidenceStore;
+}
+export declare function createEvidencePublisher(options?: EvidencePublisherFactoryOptions): Promise<EvidencePublisher>;
+/**
+ * Simple, synchronous configuration for publishers that store evidence via an
+ * HTTP multipart upload endpoint (Kubo, Pinata v3, or any compatible service).
+ */
+export interface EvidencePublisherConfig {
+    /** Base URL of the upload endpoint (e.g. https://uploads.pinata.cloud/v3). */
+    endpoint: string;
+    /** Authentication strategy. */
+    auth: RequestAuth;
+    /** Extra request headers applied to every upload. */
+    headers?: Record<string, string>;
+    /** Path relative to endpoint for uploads. Defaults to /files. */
+    requestPath?: string;
+    /** Multipart field name for the file blob. Defaults to "file". */
+    fileFieldName?: string;
+    /** Provider-specific extra fields sent with every upload request. */
+    fields?: RequestFields;
+    /** IPFS gateway base URLs used to build gateway links in results. */
+    gatewayBaseUrls?: string[];
+    /** Override the serialization of the upload request. */
+    serializeRequest?: (request: UploadRequest) => BodyInit;
+    /** Override CID extraction from the upload response. */
+    parseResponse?: (responseBody: unknown) => string | undefined;
+    /**
+     * Base URL for pin-by-CID requests. When set, enables {@link EvidencePublisher.pinCid}.
+     * For Pinata v3 this is https://api.pinata.cloud/v3 (path defaults to /files/public/pin_by_cid).
+     */
+    pinByCidEndpoint?: string;
+    /** Request path for pin-by-CID relative to pinByCidEndpoint. Defaults to /files/public/pin_by_cid. */
+    pinByCidRequestPath?: string;
+    /**
+     * Optional remote pinning step applied automatically after every publish.
+     * Works across all upload backends — the produced CID is forwarded to the
+     * configured remote pinning service.
+     */
+    remotePinning?: RemotePinningConfig;
+}
+/**
+ * Create an {@link EvidencePublisher} backed by an HTTP multipart upload endpoint.
+ * No file reads or async setup required — suitable for browser or edge environments.
+ */
+export declare function createHttpEvidencePublisher(config: EvidencePublisherConfig): EvidencePublisher;
+export interface MetaEvidencePublisherFactoryOptions extends StorageConfigReadOptions {
+    /** Explicit config supplied by code. When present, file reads are bypassed. */
+    config?: StorageConfig;
+    /** Optional YAML file path used only when `config` is not supplied. */
+    configFilePath?: string;
+    gatewayBaseUrls?: string[];
+    attachmentStore?: AttachmentStore;
+    documentStore?: MetaEvidenceStore;
+}
+/**
+ * Create a {@link MetaEvidencePublisher} using the same config-file / Helia
+ * resolution rules as {@link createEvidencePublisher}.
+ */
+export declare function createMetaEvidencePublisher(options?: MetaEvidencePublisherFactoryOptions): Promise<MetaEvidencePublisher>;
+/**
+ * Create a {@link MetaEvidencePublisher} backed by an HTTP multipart upload
+ * endpoint. No file reads or async setup required — suitable for browser or
+ * edge environments.
+ *
+ * Accepts the same {@link EvidencePublisherConfig} as
+ * {@link createHttpEvidencePublisher} so callers can share a single config
+ * object for both document types.
+ */
+export declare function createHttpMetaEvidencePublisher(config: EvidencePublisherConfig): MetaEvidencePublisher;

package/dist/src/EvidencePublisherFactory.js

@@ -0,0 +1,251 @@
+import { join } from 'node:path';
+import { readStorageConfigFile } from './config.js';
+import { EvidenceHasher } from './EvidenceHasher.js';
+import { EvidencePublisher } from './EvidencePublisher.js';
+import { MetaEvidencePublisher } from './MetaEvidencePublisher.js';
+import { HeliaAttachmentStore } from './helia/HeliaAttachmentStore.js';
+import { HeliaEvidenceStore } from './helia/HeliaEvidenceStore.js';
+import { HeliaIpfsClient } from './helia/HeliaIpfsClient.js';
+import { HttpMultipartUploadClient } from './http/HttpMultipartUploadClient.js';
+import { HttpPinByCidClient } from './http/HttpPinByCidClient.js';
+export async function createEvidencePublisher(options = {}) {
+    const { config, configFilePath, gatewayBaseUrls, attachmentStore, documentStore, ...readOptions } = options;
+    const resolvedConfig = await resolveConfig(config, configFilePath, readOptions);
+    // ── content addressing: auto-dispatch on whether a provider URL is present ──
+    if (resolvedConfig.addressing === 'content') {
+        if (!resolvedConfig.provider.url) {
+            // No URL → in-process Helia node
+            const heliaClient = new HeliaIpfsClient({
+                provider: resolvedConfig.provider,
+                gatewayBaseUrls,
+            });
+            return new EvidencePublisher({
+                attachmentStore: attachmentStore ?? new HeliaAttachmentStore(heliaClient),
+                documentStore: documentStore ?? new HeliaEvidenceStore(heliaClient),
+                onClose: () => heliaClient.stop(),
+                ...(resolvedConfig.remotePinning ? { remotePinning: resolvedConfig.remotePinning } : {}),
+            });
+        }
+        // URL present → HTTP multipart upload (Pinata, Kubo, or any compatible provider)
+        const uploadClient = new HttpMultipartUploadClient({
+            providerUrl: resolvedConfig.provider.url,
+            auth: resolvedConfig.provider.auth,
+            ...(resolvedConfig.provider.headers ? { headers: resolvedConfig.provider.headers } : {}),
+            ...(resolvedConfig.provider.fields ? { fields: resolvedConfig.provider.fields } : {}),
+            ...(resolvedConfig.provider.fileFieldName ? { fileFieldName: resolvedConfig.provider.fileFieldName } : {}),
+            gatewayBaseUrls,
+        });
+        return new EvidencePublisher({
+            attachmentStore: attachmentStore ?? new MultipartAttachmentStore(uploadClient),
+            documentStore: documentStore ?? new MultipartEvidenceStore(uploadClient),
+            ...(resolvedConfig.remotePinning ? { remotePinning: resolvedConfig.remotePinning } : {}),
+        });
+    }
+    // ── location addressing: requires caller-supplied stores ──────────────────
+    if (!documentStore) {
+        throw new Error('location addressing requires a custom documentStore to be supplied');
+    }
+    return new EvidencePublisher({
+        ...(attachmentStore ? { attachmentStore } : {}),
+        documentStore,
+        ...(resolvedConfig.remotePinning ? { remotePinning: resolvedConfig.remotePinning } : {}),
+    });
+}
+async function resolveConfig(config, configFilePath, readOptions) {
+    const envFilePath = readOptions.envFilePath ?? join(process.cwd(), '.env');
+    if (config) {
+        return config;
+    }
+    if (!configFilePath) {
+        return readStorageConfigFile(join(process.cwd(), 'evidence.storage.yml'), {
+            env: readOptions.env,
+            envFilePath,
+        });
+    }
+    return readStorageConfigFile(configFilePath, {
+        env: readOptions.env,
+        envFilePath,
+    });
+}
+/**
+ * Create an {@link EvidencePublisher} backed by an HTTP multipart upload endpoint.
+ * No file reads or async setup required — suitable for browser or edge environments.
+ */
+export function createHttpEvidencePublisher(config) {
+    const uploadClient = new HttpMultipartUploadClient({
+        providerUrl: config.endpoint,
+        auth: config.auth,
+        headers: config.headers,
+        requestPath: config.requestPath,
+        fileFieldName: config.fileFieldName,
+        fields: config.fields,
+        gatewayBaseUrls: config.gatewayBaseUrls,
+        ...(config.serializeRequest ? { serializeRequestModel: config.serializeRequest } : {}),
+        ...(config.parseResponse ? { parseResponse: config.parseResponse } : {}),
+    });
+    const pinByCidClient = config.pinByCidEndpoint
+        ? new HttpPinByCidClient({
+            providerUrl: config.pinByCidEndpoint,
+            auth: config.auth,
+            headers: config.headers,
+            requestPath: config.pinByCidRequestPath,
+        })
+        : undefined;
+    return new EvidencePublisher({
+        attachmentStore: new MultipartAttachmentStore(uploadClient),
+        documentStore: new MultipartEvidenceStore(uploadClient),
+        ...(pinByCidClient ? { pinByCidClient } : {}),
+        ...(config.remotePinning ? { remotePinning: config.remotePinning } : {}),
+    });
+}
+/**
+ * Create a {@link MetaEvidencePublisher} using the same config-file / Helia
+ * resolution rules as {@link createEvidencePublisher}.
+ */
+export async function createMetaEvidencePublisher(options = {}) {
+    const { config, configFilePath, gatewayBaseUrls, attachmentStore, documentStore, ...readOptions } = options;
+    const resolvedConfig = await resolveConfig(config, configFilePath, readOptions);
+    if (resolvedConfig.addressing === 'content') {
+        if (!resolvedConfig.provider.url) {
+            const heliaClient = new HeliaIpfsClient({
+                provider: resolvedConfig.provider,
+                gatewayBaseUrls,
+            });
+            return new MetaEvidencePublisher({
+                attachmentStore: attachmentStore ?? new HeliaAttachmentStore(heliaClient),
+                documentStore: documentStore ?? new HeliaMetaEvidenceStore(heliaClient),
+                onClose: () => heliaClient.stop(),
+                ...(resolvedConfig.remotePinning ? { remotePinning: resolvedConfig.remotePinning } : {}),
+            });
+        }
+        const uploadClient = new HttpMultipartUploadClient({
+            providerUrl: resolvedConfig.provider.url,
+            auth: resolvedConfig.provider.auth,
+            ...(resolvedConfig.provider.headers ? { headers: resolvedConfig.provider.headers } : {}),
+            ...(resolvedConfig.provider.fields ? { fields: resolvedConfig.provider.fields } : {}),
+            ...(resolvedConfig.provider.fileFieldName ? { fileFieldName: resolvedConfig.provider.fileFieldName } : {}),
+            gatewayBaseUrls,
+        });
+        return new MetaEvidencePublisher({
+            attachmentStore: attachmentStore ?? new MultipartAttachmentStore(uploadClient),
+            documentStore: documentStore ?? new MultipartMetaEvidenceStore(uploadClient),
+            ...(resolvedConfig.remotePinning ? { remotePinning: resolvedConfig.remotePinning } : {}),
+        });
+    }
+    if (!documentStore) {
+        throw new Error('location addressing requires a custom documentStore to be supplied');
+    }
+    return new MetaEvidencePublisher({
+        ...(attachmentStore ? { attachmentStore } : {}),
+        documentStore,
+        ...(resolvedConfig.remotePinning ? { remotePinning: resolvedConfig.remotePinning } : {}),
+    });
+}
+/**
+ * Create a {@link MetaEvidencePublisher} backed by an HTTP multipart upload
+ * endpoint. No file reads or async setup required — suitable for browser or
+ * edge environments.
+ *
+ * Accepts the same {@link EvidencePublisherConfig} as
+ * {@link createHttpEvidencePublisher} so callers can share a single config
+ * object for both document types.
+ */
+export function createHttpMetaEvidencePublisher(config) {
+    const uploadClient = new HttpMultipartUploadClient({
+        providerUrl: config.endpoint,
+        auth: config.auth,
+        headers: config.headers,
+        requestPath: config.requestPath,
+        fileFieldName: config.fileFieldName,
+        fields: config.fields,
+        gatewayBaseUrls: config.gatewayBaseUrls,
+        ...(config.serializeRequest ? { serializeRequestModel: config.serializeRequest } : {}),
+        ...(config.parseResponse ? { parseResponse: config.parseResponse } : {}),
+    });
+    const pinByCidClient = config.pinByCidEndpoint
+        ? new HttpPinByCidClient({
+            providerUrl: config.pinByCidEndpoint,
+            auth: config.auth,
+            headers: config.headers,
+            requestPath: config.pinByCidRequestPath,
+        })
+        : undefined;
+    return new MetaEvidencePublisher({
+        attachmentStore: new MultipartAttachmentStore(uploadClient),
+        documentStore: new MultipartMetaEvidenceStore(uploadClient),
+        ...(pinByCidClient ? { pinByCidClient } : {}),
+        ...(config.remotePinning ? { remotePinning: config.remotePinning } : {}),
+    });
+}
+// ─── Internal store adapters ─────────────────────────────────────────────────
+class MultipartAttachmentStore {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async putAttachment(input) {
+        const added = await this.client.addBytes(input.bytes, {
+            fileName: input.fileName,
+            mediaType: input.mediaType,
+        });
+        return {
+            cid: added.cid,
+            uri: added.uri,
+            fileHash: EvidenceHasher.hashBytes(input.bytes),
+            fileTypeExtension: input.fileTypeExtension,
+            mediaType: input.mediaType,
+            sizeBytes: input.bytes.length,
+            gatewayUrls: added.gatewayUrls,
+        };
+    }
+}
+class MultipartEvidenceStore {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async putEvidenceDocument(document) {
+        const added = await this.client.addBytes(EvidenceHasher.serialize(document), {
+            fileName: 'evidence.json',
+            mediaType: 'application/json',
+        });
+        return {
+            cid: added.cid,
+            uri: added.uri,
+            gatewayUrls: added.gatewayUrls,
+        };
+    }
+}
+class MultipartMetaEvidenceStore {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async putMetaEvidenceDocument(document) {
+        const bytes = new TextEncoder().encode(JSON.stringify(document));
+        const added = await this.client.addBytes(bytes, {
+            fileName: 'metaEvidence.json',
+            mediaType: 'application/json',
+        });
+        return {
+            cid: added.cid,
+            uri: added.uri,
+            gatewayUrls: added.gatewayUrls,
+        };
+    }
+}
+class HeliaMetaEvidenceStore {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async putMetaEvidenceDocument(document) {
+        const bytes = new TextEncoder().encode(JSON.stringify(document));
+        const added = await this.client.addBytes(bytes);
+        return {
+            cid: added.cid,
+            uri: added.uri,
+            gatewayUrls: added.gatewayUrls,
+        };
+    }
+}

package/dist/src/MetaEvidenceJsonBuilder.d.ts

@@ -0,0 +1,25 @@
+import type { MetaEvidence, MetaEvidenceDraft, PublishedAttachment } from './types.js';
+/**
+ * Builds the canonical {@link MetaEvidence} JSON object from a caller-supplied
+ * draft.  Enforces required fields and normalizes optional ones.
+ *
+ * Business-specific defaults (escrow roles, dispute categories, ruling labels)
+ * are intentionally **not** provided here.  Defaults belong in consuming SDKs
+ * or applications, not in the shared evidence SDK.
+ */
+export declare class MetaEvidenceJsonBuilder {
+    /**
+     * Build a MetaEvidence document from a draft.
+     * Required fields (`category`, `title`, `description`, `question`,
+     * `rulingOptions`) are validated.  Optional fields are included only when
+     * non-blank (strings) or truthy (numbers / objects).
+     */
+    static build(draft: MetaEvidenceDraft): MetaEvidence;
+    /**
+     * Build a MetaEvidence document for the assisted publish path.
+     * Attachment-derived metadata (`fileURI`, `fileHash`, `fileTypeExtension`)
+     * is injected from the published attachment, overriding any values that
+     * may have been supplied on the draft.
+     */
+    static withAttachment(draft: MetaEvidenceDraft, attachment: PublishedAttachment): MetaEvidence;
+}

package/dist/src/MetaEvidenceJsonBuilder.js

@@ -0,0 +1,104 @@
+/**
+ * Builds the canonical {@link MetaEvidence} JSON object from a caller-supplied
+ * draft.  Enforces required fields and normalizes optional ones.
+ *
+ * Business-specific defaults (escrow roles, dispute categories, ruling labels)
+ * are intentionally **not** provided here.  Defaults belong in consuming SDKs
+ * or applications, not in the shared evidence SDK.
+ */
+export class MetaEvidenceJsonBuilder {
+    /**
+     * Build a MetaEvidence document from a draft.
+     * Required fields (`category`, `title`, `description`, `question`,
+     * `rulingOptions`) are validated.  Optional fields are included only when
+     * non-blank (strings) or truthy (numbers / objects).
+     */
+    static build(draft) {
+        const category = requireNonBlank(draft.category, 'category');
+        const title = requireNonBlank(draft.title, 'title');
+        const description = requireNonBlank(draft.description, 'description');
+        const question = requireNonBlank(draft.question, 'question');
+        if (!draft.rulingOptions) {
+            throw new Error('rulingOptions must be provided');
+        }
+        const fileURI = normalizeString(draft.fileURI);
+        const fileHash = normalizeString(draft.fileHash);
+        const fileTypeExtension = normalizeString(draft.fileTypeExtension);
+        if (!fileURI && (fileHash || fileTypeExtension)) {
+            throw new Error('fileHash and fileTypeExtension require fileURI');
+        }
+        // Build the document with stable key ordering that matches the Kleros
+        // Court expected shape (category first, then title/description, etc.)
+        const doc = {
+            category,
+            title,
+            description,
+            question,
+            rulingOptions: draft.rulingOptions,
+        };
+        if (draft.aliases && Object.keys(draft.aliases).length > 0) {
+            doc.aliases = draft.aliases;
+        }
+        if (fileURI) {
+            doc.fileURI = fileURI;
+            if (fileHash)
+                doc.fileHash = fileHash;
+            if (fileTypeExtension)
+                doc.fileTypeExtension = fileTypeExtension;
+        }
+        const evidenceDisplayInterfaceURI = normalizeString(draft.evidenceDisplayInterfaceURI);
+        if (evidenceDisplayInterfaceURI) {
+            doc.evidenceDisplayInterfaceURI = evidenceDisplayInterfaceURI;
+            const evidenceDisplayInterfaceHash = normalizeString(draft.evidenceDisplayInterfaceHash);
+            if (evidenceDisplayInterfaceHash)
+                doc.evidenceDisplayInterfaceHash = evidenceDisplayInterfaceHash;
+        }
+        const dynamicScriptURI = normalizeString(draft.dynamicScriptURI);
+        if (dynamicScriptURI) {
+            doc.dynamicScriptURI = dynamicScriptURI;
+            const dynamicScriptHash = normalizeString(draft.dynamicScriptHash);
+            if (dynamicScriptHash)
+                doc.dynamicScriptHash = dynamicScriptHash;
+        }
+        const arbitrableInterfaceURI = normalizeString(draft.arbitrableInterfaceURI);
+        if (arbitrableInterfaceURI)
+            doc.arbitrableInterfaceURI = arbitrableInterfaceURI;
+        if (draft.arbitrableChainID != null)
+            doc.arbitrableChainID = draft.arbitrableChainID;
+        if (draft.arbitratorChainID != null)
+            doc.arbitratorChainID = draft.arbitratorChainID;
+        const arbitrableJsonRpcUrl = normalizeString(draft.arbitrableJsonRpcUrl);
+        if (arbitrableJsonRpcUrl)
+            doc.arbitrableJsonRpcUrl = arbitrableJsonRpcUrl;
+        const arbitratorJsonRpcUrl = normalizeString(draft.arbitratorJsonRpcUrl);
+        if (arbitratorJsonRpcUrl)
+            doc.arbitratorJsonRpcUrl = arbitratorJsonRpcUrl;
+        if (draft._v != null)
+            doc._v = draft._v;
+        return doc;
+    }
+    /**
+     * Build a MetaEvidence document for the assisted publish path.
+     * Attachment-derived metadata (`fileURI`, `fileHash`, `fileTypeExtension`)
+     * is injected from the published attachment, overriding any values that
+     * may have been supplied on the draft.
+     */
+    static withAttachment(draft, attachment) {
+        return this.build({
+            ...draft,
+            fileURI: attachment.uri,
+            fileHash: attachment.fileHash,
+            fileTypeExtension: attachment.fileTypeExtension,
+        });
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function requireNonBlank(value, name) {
+    if (!value?.trim()) {
+        throw new Error(`${name} must not be blank`);
+    }
+    return value.trim();
+}
+function normalizeString(value) {
+    return value?.trim() ? value.trim() : undefined;
+}

package/dist/src/MetaEvidencePublisher.d.ts

@@ -0,0 +1,39 @@
+import { HttpPinByCidClient } from './http/HttpPinByCidClient.js';
+import type { AttachmentStore, MetaEvidenceStore } from './storage-types.js';
+import type { Attachment, CidInput, MetaEvidencePublishRequest, MetaEvidencePublishResult, PinResult, PublishedAttachment, RemotePinningConfig } from './types.js';
+export interface MetaEvidencePublisherOptions {
+    attachmentStore?: AttachmentStore;
+    documentStore: MetaEvidenceStore;
+    /** Optional client for explicit CID pinning via {@link MetaEvidencePublisher.pinCid}. */
+    pinByCidClient?: HttpPinByCidClient;
+    /**
+     * Optional remote pinning configuration.
+     * When set (and not disabled), every produced CID is forwarded to the
+     * configured pinning service as a post-publish durability step.
+     */
+    remotePinning?: RemotePinningConfig;
+    /** Called by {@link MetaEvidencePublisher.close} to release underlying resources. */
+    onClose?: () => Promise<void>;
+}
+export declare class MetaEvidencePublisher {
+    private readonly options;
+    constructor(options: MetaEvidencePublisherOptions);
+    /**
+     * Publish a MetaEvidence document.
+     *
+     * - **Manual path**: supply the full draft (file fields optional).
+     * - **Assisted path**: include `attachment` on the request; the SDK uploads
+     *   the attachment first and wires its URI / hash into the MetaEvidence JSON.
+     *   Attachment-derived file metadata takes precedence over any file fields
+     *   provided on the draft.
+     */
+    publish(input: MetaEvidencePublishRequest): Promise<MetaEvidencePublishResult>;
+    uploadAttachment(input: Attachment): Promise<PublishedAttachment>;
+    pinCid(input: CidInput): Promise<PinResult>;
+    /**
+     * Release underlying resources (e.g. stop the Helia node).
+     * Always call this when the publisher is no longer needed.
+     */
+    close(): Promise<void>;
+    private runRemotePinning;
+}