@seed-hypermedia/client 0.0.1 → 0.0.2

package/dist/auto-link.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Auto-link child documents to their parent on first publish.
+ *
+ * When a document is created at a nested path (e.g. /docs/my-article), the
+ * parent document at /docs should contain an embed link pointing to the child.
+ * This module provides:
+ *
+ * - Pure decision logic: should a link be added?
+ * - Operation builder: what DocumentOperations to emit
+ * - Full I/O convenience: fetch parent, check, build ops, sign, publish
+ */
+import type { HMDocument, HMSigner, UnpackedHypermediaId } from './hm-types';
+import type { SeedClient } from './client';
+import type { DocumentOperation } from './change';
+/**
+ * Check if a document contains a link/embed to a specific child document.
+ * Compares URLs ignoring version and latest flags.
+ */
+export declare function documentContainsLinkToChild(document: HMDocument, childId: UnpackedHypermediaId): boolean;
+/**
+ * Check if a document has a self-referential Query block
+ * (a query to itself that would automatically include children).
+ */
+export declare function documentHasSelfQuery(document: HMDocument, documentId: UnpackedHypermediaId): boolean;
+/**
+ * Determine whether a parent auto-link should be added on first publish.
+ * Returns true when the parent document should receive an embed link to the child.
+ */
+export declare function shouldAutoLinkParent(isPrivate: boolean, parentDocument: HMDocument | null, editableLocation: UnpackedHypermediaId, parentId: UnpackedHypermediaId): boolean;
+/**
+ * Generate the DocumentOperations to append an Embed Card block to a parent document.
+ *
+ * The returned operations include a ReplaceBlock for the new embed block and a
+ * MoveBlocks that lists ALL root-level block IDs (existing + new) to ensure
+ * correct ordering. The CBOR MoveBlocks format with no `ref` positions blocks
+ * from the start, so we must re-specify the full ordering.
+ */
+export declare function createAutoLinkOps(parentDocument: HMDocument, childHmUrl: string, newBlockId: string): DocumentOperation[];
+/** Options for the auto-link convenience function. */
+export type AutoLinkChildToParentOptions = {
+    /** Seed API client. */
+    client: SeedClient;
+    /** Account UID of the document owner. */
+    account: string;
+    /** Full path of the child document (e.g. "/tests/benefits-of-cli"). */
+    path: string;
+    /** hm:// URL of the published child document (with version). */
+    childHmUrl: string;
+    /** Signer for the parent document change. */
+    signer: HMSigner;
+};
+/**
+ * Auto-link a newly published child document to its parent.
+ *
+ * Computes the parent path, fetches the parent document, decides whether a link
+ * is needed (using `shouldAutoLinkParent`), and if so publishes an Embed Card
+ * block to the parent document.
+ *
+ * Returns true if a link was added, false otherwise. Throws on network errors.
+ */
+export declare function autoLinkChildToParent(opts: AutoLinkChildToParentOptions): Promise<boolean>;

package/dist/block-diff.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Block diffing utilities for document update.
+ *
+ * Computes minimal document operations by comparing existing document
+ * blocks with new blocks parsed from Markdown or JSON input.
+ *
+ * The primary flow trusts block IDs from the input: if an input block's
+ * ID exists in the old document, it's treated as an existing block and
+ * diffed for content changes. If the ID doesn't exist, the block is
+ * treated as new. Old blocks whose IDs don't appear in the new tree
+ * are deleted. This gives per-block granularity — a mix of known and
+ * unknown IDs is handled correctly.
+ */
+import type { DocumentOperation } from './change';
+import type { HMBlockNode } from './hm-types';
+import type { BlockNode } from './markdown-to-blocks';
+export type APIBlockNode = {
+    block: APIBlock;
+    children: APIBlockNode[];
+};
+export type APIBlock = {
+    id: string;
+    type: string;
+    text: string;
+    link: string;
+    annotations: unknown[];
+    attributes: Record<string, unknown>;
+    revision?: string;
+};
+type BlocksMapItem = {
+    parent: string;
+    left: string;
+    block: APIBlock;
+};
+type BlocksMap = Record<string, BlocksMapItem>;
+export declare function createBlocksMap(nodes: APIBlockNode[], parentId?: string): BlocksMap;
+/**
+ * Walk old and new block trees in parallel. When the new block at
+ * position N has the same type as the old block at position N, reuse
+ * the old block's ID. Otherwise assign the new block's generated ID.
+ *
+ * Returns a new tree with IDs reassigned (does not mutate inputs).
+ */
+export declare function matchBlockIds(oldNodes: APIBlockNode[], newNodes: BlockNode[]): BlockNode[];
+/**
+ * Compare the new block tree against the old blocks map and produce
+ * the minimal set of DocumentOperations:
+ *
+ * - ReplaceBlock for new or content-changed blocks
+ * - MoveBlocks for positioning (new blocks or position changes)
+ * - DeleteBlocks for blocks removed from the document
+ */
+export declare function computeReplaceOps(oldMap: BlocksMap, matchedTree: BlockNode[], parentId?: string): DocumentOperation[];
+/**
+ * Convert an HMBlockNode tree (from JSON input or API response) into
+ * a BlockNode tree compatible with the diff pipeline.
+ *
+ * HMBlockNode nests childrenType/language inside `attributes`, while
+ * SeedBlock/BlockNode has them at the top level.
+ */
+export declare function hmBlockNodeToBlockNode(node: HMBlockNode): BlockNode;
+export {};

package/dist/blocks-to-markdown.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Seed block tree → Markdown formatter.
+ *
+ * Converts HMDocument/HMBlockNode trees to markdown with:
+ *   - YAML frontmatter (always emitted, all HMMetadata fields)
+ *   - Block IDs preserved as HTML comments (<!-- id:XXXXXXXX -->)
+ *   - Inline annotations rendered as markdown formatting
+ *
+ * This module is purely synchronous and does NOT resolve embeds, mentions,
+ * or queries over the network. For resolved output, use the CLI's wrapper
+ * which adds a SeedClient-backed resolve layer on top.
+ *
+ * Round-trip compatible: output can be piped back through `parseMarkdown()`
+ * to recreate the same document with block IDs preserved.
+ */
+import type { HMDocument, HMMetadata } from './hm-types';
+export type BlocksToMarkdownOptions = {
+    /** Format ipfs:// URLs as https gateway URLs. Default: true. */
+    ipfsGateway?: boolean;
+};
+/**
+ * Emit YAML frontmatter from HMMetadata.
+ * Only includes fields that have defined, non-empty values.
+ * System fields (authors, version, genesis, account) are NOT emitted.
+ */
+export declare function emitFrontmatter(metadata: HMMetadata): string;
+/**
+ * Convert an HMDocument to markdown with frontmatter and block IDs.
+ *
+ * This is a synchronous, pure conversion. Embeds/queries are rendered
+ * as placeholder links (not resolved).
+ */
+export declare function blocksToMarkdown(doc: HMDocument, options?: BlocksToMarkdownOptions): string;

package/dist/change.d.ts

@@ -103,6 +103,11 @@ export declare function createDocumentChange(input: CreateDocumentChangeInput, s
     bytes: Uint8Array;
     cid: CID;
 }>;
+/**
+ * Map a proto ResourceVisibility enum value to the CBOR string used in Ref blobs.
+ * Returns "Private" for private documents, undefined otherwise (omitted from CBOR = public).
+ */
+export declare function visibilityToCbor(protoVisibility?: number): string | undefined;
 export type SignDocumentChangeInput = {
     /** Account UID (base58btc-encoded principal) */
     account: string;
@@ -116,6 +121,8 @@ export type SignDocumentChangeInput = {
     generation?: number | bigint;
     /** Optional capability CID string */
     capability?: string;
+    /** Proto ResourceVisibility enum value (0=unspecified, 1=public, 2=private) */
+    visibility?: number;
 };
 /**
  * Sign a prepared change and create a version ref, returning blobs ready for publishing.

package/dist/{chunk-YUKHBJYL.mjs → chunk-PPK3SKPV.mjs}

@@ -221,6 +221,7 @@ var HMDocumentMetadataSchema = z.object({
   siteUrl: z.string().optional(),
   layout: z.union([z.literal("Seed/Experimental/Newspaper"), z.literal("")]).optional(),
   displayPublishTime: z.string().optional(),
+  displayAuthor: z.string().optional(),
   seedExperimentalLogo: z.string().optional(),
   seedExperimentalHomeOrder: z.union([z.literal("UpdatedFirst"), z.literal("CreatedFirst")]).optional(),
   showOutline: z.boolean().optional(),
@@ -339,6 +340,10 @@ var HMAccountNotFoundSchema = z.object({
   uid: z.string()
 });
 var HMAccountResultSchema = z.discriminatedUnion("type", [HMAccountPayloadSchema, HMAccountNotFoundSchema]);
+var HMSiteMemberSchema = z.object({
+  account: unpackedHmIdSchema,
+  role: z.enum(["owner", "writer", "member"])
+});
 var HMAccountsMetadataSchema = z.record(
   z.string(),
   // account uid
@@ -356,7 +361,8 @@ var HMQuerySortSchema = z.object({
     z.literal("Title"),
     z.literal("CreateTime"),
     z.literal("UpdateTime"),
-    z.literal("DisplayTime")
+    z.literal("DisplayTime"),
+    z.literal("ActivityTime")
   ])
 });
 var HMQuerySchema = z.object({
@@ -475,13 +481,19 @@ var HMResolvedResourceSchema = z.discriminatedUnion("type", [
   HMResourceCommentSchema,
   HMResourceTombstoneSchema
 ]);
+var HMContactSubscribeSchema = z.object({
+  site: z.boolean().optional(),
+  profile: z.boolean().optional()
+});
 var HMContactRecordSchema = z.object({
   id: z.string(),
   subject: z.string(),
   name: z.string(),
   account: z.string(),
+  signer: z.string(),
   createTime: HMTimestampSchema.optional(),
-  updateTime: HMTimestampSchema.optional()
+  updateTime: HMTimestampSchema.optional(),
+  subscribe: HMContactSubscribeSchema.optional()
 });
 var HMAccountContactsRequestSchema = z.object({
   key: z.literal("AccountContacts"),
@@ -489,6 +501,122 @@ var HMAccountContactsRequestSchema = z.object({
   // account UID
   output: z.array(HMContactRecordSchema)
 });
+var HMCommentDraftSchema = z.object({
+  blocks: z.array(HMBlockNodeSchema),
+  targetDocId: z.string().optional(),
+  replyCommentId: z.string().optional(),
+  quotingBlockId: z.string().optional(),
+  context: z.enum(["accessory", "feed", "document-content"]).optional(),
+  lastUpdateTime: z.number().optional()
+});
+var HMListedCommentDraftSchema = z.object({
+  id: z.string(),
+  targetDocId: z.string(),
+  replyCommentId: z.string().optional(),
+  quotingBlockId: z.string().optional(),
+  context: z.enum(["accessory", "feed", "document-content"]).optional(),
+  lastUpdateTime: z.number()
+});
+var HMHostConfigSchema = z.object({
+  peerId: z.string(),
+  registeredAccountUid: z.string(),
+  protocolId: z.string(),
+  addrs: z.array(z.string()),
+  hostname: z.string(),
+  isGateway: z.boolean()
+});
+var HMContactSchema = z.object({
+  metadata: HMDocumentMetadataSchema,
+  contacts: z.array(HMContactRecordSchema).optional(),
+  subjectContacts: z.array(HMContactRecordSchema).optional()
+});
+var HMContactItemSchema = z.object({
+  id: unpackedHmIdSchema,
+  metadata: HMDocumentMetadataSchema.optional()
+});
+var HMCapabilitySchema = z.object({
+  id: z.string(),
+  accountUid: z.string(),
+  role: HMRoleSchema,
+  capabilityId: z.string().optional(),
+  grantId: unpackedHmIdSchema,
+  label: z.string().optional(),
+  createTime: HMTimestampSchema
+});
+var siteDiscoverRequestSchema = z.object({
+  uid: z.string(),
+  path: z.array(z.string()),
+  version: z.string().optional(),
+  media: z.boolean().optional()
+});
+var HMPeerConnectionRequestSchema = z.object({
+  a: z.array(z.string()),
+  // addrs
+  d: z.string()
+  // peer/device ID
+});
+var ParsedFragmentSchema = BlockRangeSchema.extend({
+  blockId: z.string()
+});
+var HMCitationCommentSourceSchema = z.object({
+  type: z.literal("c"),
+  id: unpackedHmIdSchema,
+  author: z.string().optional(),
+  time: HMTimestampSchema.optional()
+});
+var HMCitationDocumentSourceSchema = z.object({
+  type: z.literal("d"),
+  id: unpackedHmIdSchema,
+  author: z.string().optional(),
+  time: HMTimestampSchema.optional()
+});
+var HMCitationSchema = z.object({
+  source: z.discriminatedUnion("type", [HMCitationCommentSourceSchema, HMCitationDocumentSourceSchema]),
+  isExactVersion: z.boolean(),
+  targetFragment: ParsedFragmentSchema.nullable(),
+  targetId: unpackedHmIdSchema
+});
+var DeviceLinkSessionSchema = z.object({
+  accountId: z.string(),
+  secretToken: z.string(),
+  addrInfo: z.object({
+    peerId: z.string(),
+    addrs: z.array(z.string())
+  })
+});
+var HMNavigationItemSchema = z.object({
+  type: z.literal("Link"),
+  id: z.string(),
+  text: z.string(),
+  link: z.string()
+});
+var HMDraftContentSchema = z.object({
+  content: z.array(z.any()),
+  // EditorBlock validation is handled elsewhere
+  deps: z.array(z.string().min(1)).default([]),
+  navigation: z.array(HMNavigationItemSchema).optional()
+});
+var HMDraftMetaBaseSchema = z.object({
+  id: z.string(),
+  locationUid: z.string().optional(),
+  locationPath: z.array(z.string()).optional(),
+  editUid: z.string().optional(),
+  editPath: z.array(z.string()).optional(),
+  metadata: HMDocumentMetadataSchema,
+  visibility: HMResourceVisibilitySchema.optional().default("PUBLIC")
+});
+var draftLocationRefinement = (data) => data.editUid || data.locationUid;
+var HMDraftMetaSchema = HMDraftMetaBaseSchema.refine(draftLocationRefinement, {
+  message: "Either editUid or locationUid must be provided"
+});
+var HMListedDraftSchema = HMDraftMetaBaseSchema.extend({
+  lastUpdateTime: z.number()
+}).refine(draftLocationRefinement, {
+  message: "Either editUid or locationUid must be provided"
+});
+var HMListedDraftReadSchema = HMDraftMetaBaseSchema.extend({
+  lastUpdateTime: z.number()
+});
 var HMSubjectContactsRequestSchema = z.object({
   key: z.literal("SubjectContacts"),
   input: z.string(),
@@ -521,7 +649,8 @@ var HMSearchInputSchema = z.object({
   includeBody: z.boolean().optional(),
   contextSize: z.number().optional(),
   perspectiveAccountUid: z.string().optional(),
-  searchType: z.number().optional()
+  searchType: z.number().optional(),
+  pageSize: z.number().optional()
 });
 var HMSearchResultItemSchema = z.object({
   id: unpackedHmIdSchema,
@@ -529,7 +658,7 @@ var HMSearchResultItemSchema = z.object({
   title: z.string(),
   icon: z.string(),
   parentNames: z.array(z.string()),
-  versionTime: z.any().optional(),
+  versionTime: z.string().optional(),
   searchQuery: z.string(),
   type: z.enum(["document", "contact"])
 });
@@ -706,6 +835,7 @@ var HMInteractionSummaryOutputSchema = z.object({
   comments: z.number(),
   changes: z.number(),
   children: z.number(),
+  authorUids: z.array(z.string()).default([]),
   blocks: z.record(
     z.string(),
     z.object({
@@ -872,7 +1002,7 @@ function getHMQueryString({
   if (version) {
     query.v = version;
   }
-  if (latest) {
+  if (latest && version) {
     query.l = null;
   }
   if (panel) {
@@ -905,6 +1035,100 @@ function entityQueryPathToHmIdPath(path) {
   if (path === "/") return [];
   return path.split("/").filter(Boolean);
 }
+function parseCustomURL(url) {
+  if (!url) return null;
+  const [scheme, rest] = url.split("://");
+  if (!rest) return null;
+  const [pathAndQuery, fragment = null] = rest.split("#");
+  const [path, queryString] = (pathAndQuery == null ? void 0 : pathAndQuery.split("?")) || [];
+  const query = new URLSearchParams(queryString);
+  const queryObject = Object.fromEntries(query.entries());
+  return {
+    scheme: scheme || null,
+    path: (path == null ? void 0 : path.split("/")) || [],
+    query: queryObject,
+    fragment
+  };
+}
+function parseFragment(input) {
+  if (!input) return null;
+  const regex = /^([^\+\[]+)((\+)|\[(\d+)\:(\d+)\])?$/;
+  const match = input.match(regex);
+  if (match) {
+    const blockId = match[1] || "";
+    const expanded = match[3];
+    const rangeStart = match[4];
+    const rangeEnd = match[5];
+    if (expanded === "+") {
+      return { blockId, expanded: true };
+    } else if (typeof rangeStart !== "undefined" && typeof rangeEnd !== "undefined") {
+      return { blockId, start: parseInt(rangeStart), end: parseInt(rangeEnd) };
+    } else {
+      return { blockId, expanded: false };
+    }
+  } else {
+    return { blockId: input, expanded: false };
+  }
+}
+var STATIC_HM_PATHS = /* @__PURE__ */ new Set(["download", "connect", "register", "device-link", "profile", "contact"]);
+function unpackHmId(hypermediaId) {
+  if (!hypermediaId) return null;
+  const parsed = parseCustomURL(hypermediaId);
+  if (!parsed) return null;
+  let uid;
+  let path;
+  let hostname = null;
+  if (parsed.scheme === "https" || parsed.scheme === "http") {
+    if (parsed.path[1] !== "hm") return null;
+    hostname = parsed.path[0];
+    uid = parsed.path[2];
+    if (uid && STATIC_HM_PATHS.has(uid)) return null;
+    path = parsed.path.slice(3);
+  } else if (parsed.scheme === HYPERMEDIA_SCHEME || parsed.scheme === "hm") {
+    uid = parsed.path[0];
+    path = parsed.path.slice(1);
+  } else {
+    return null;
+  }
+  const version = parsed.query.v || null;
+  const fragment = parseFragment(parsed.fragment);
+  const hasBlockRef = !!(fragment == null ? void 0 : fragment.blockId);
+  const latest = hasBlockRef ? false : parsed.query.l === null || parsed.query.l === "" || !version;
+  let blockRange = null;
+  if (fragment) {
+    if ("start" in fragment) {
+      blockRange = { start: fragment.start, end: fragment.end };
+    } else if ("expanded" in fragment) {
+      blockRange = { expanded: fragment.expanded };
+    }
+  }
+  return {
+    id: packBaseId(uid || "", path),
+    uid: uid || "",
+    path: path || null,
+    version,
+    blockRef: fragment ? fragment.blockId : null,
+    blockRange,
+    hostname: hostname || null,
+    latest,
+    scheme: parsed.scheme
+  };
+}
+function codePointLength(entry) {
+  let count = 0;
+  if (!entry) return 0;
+  for (let i = 0; i < entry.length; i++) {
+    count++;
+    if (isSurrogate(entry, i)) {
+      i++;
+    }
+  }
+  return count;
+}
+function isSurrogate(s, i) {
+  const code = s.charCodeAt(i);
+  return 55296 <= code && code <= 56319;
+}
 
 export {
   BlockRangeSchema,
@@ -954,6 +1178,7 @@ export {
   HMAccountPayloadSchema,
   HMAccountNotFoundSchema,
   HMAccountResultSchema,
+  HMSiteMemberSchema,
   HMAccountsMetadataSchema,
   HMQueryInclusionSchema,
   HMQuerySortSchema,
@@ -975,8 +1200,25 @@ export {
   HMResourceErrorSchema,
   HMResourceSchema,
   HMResolvedResourceSchema,
+  HMContactSubscribeSchema,
   HMContactRecordSchema,
   HMAccountContactsRequestSchema,
+  HMCommentDraftSchema,
+  HMListedCommentDraftSchema,
+  HMHostConfigSchema,
+  HMContactSchema,
+  HMContactItemSchema,
+  HMCapabilitySchema,
+  siteDiscoverRequestSchema,
+  HMPeerConnectionRequestSchema,
+  ParsedFragmentSchema,
+  HMCitationSchema,
+  DeviceLinkSessionSchema,
+  HMNavigationItemSchema,
+  HMDraftContentSchema,
+  HMDraftMetaSchema,
+  HMListedDraftSchema,
+  HMListedDraftReadSchema,
   HMSubjectContactsRequestSchema,
   HMResourceRequestSchema,
   HMResourceMetadataRequestSchema,
@@ -1040,5 +1282,10 @@ export {
   getHMQueryString,
   serializeBlockRange,
   hmIdPathToEntityQueryPath,
-  entityQueryPathToHmIdPath
+  entityQueryPathToHmIdPath,
+  parseCustomURL,
+  parseFragment,
+  unpackHmId,
+  codePointLength,
+  isSurrogate
 };

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { HMPrepareDocumentChangeInput, HMRequest, HMSigner } from './hm-types';
+import { type HMPrepareDocumentChangeInput, type HMRequest, type HMSigner } from './hm-types';
 /**
  * Deserializes a URL query string using a Zod schema.
  * If the query contains only a __value key, returns the primitive value directly.

package/dist/comment.d.ts

@@ -40,4 +40,9 @@ export type DeleteCommentInput = {
     visibility?: 'Private' | '';
 };
 export declare function deleteComment(input: DeleteCommentInput, signer: HMSigner): Promise<HMPublishBlobsInput>;
+/**
+ * Compute the record ID ("authority/tsid") from raw CBOR-encoded comment blob bytes.
+ * The TSID is a 10-byte base58btc value: 6 bytes ms timestamp + 4 bytes SHA256 prefix.
+ */
+export declare function commentRecordIdFromBlob(blobData: Uint8Array): Promise<string>;
 export {};

package/dist/contact.d.ts

@@ -1,21 +1,35 @@
 import type { HMPublishBlobsInput, HMSigner } from './hm-types';
+export type ContactSubscribe = {
+    site?: boolean;
+    profile?: boolean;
+};
 export type CreateContactInput = {
     /** The subject account UID (base58btc-encoded principal) */
     subjectUid: string;
+    /** The account UID (base58btc-encoded principal) */
+    accountUid?: string;
     /** The display name for the contact */
-    name: string;
+    name?: string;
+    /** The subscribe information for the contact */
+    subscribe?: ContactSubscribe;
 };
 export type UpdateContactInput = {
     /** The contact record ID in format "authority/tsid" */
     contactId: string;
     /** The subject account UID */
     subjectUid: string;
+    /** The account UID (base58btc-encoded principal) */
+    accountUid?: string;
     /** The updated display name */
-    name: string;
+    name?: string;
+    /** The subscribe information for the contact */
+    subscribe?: ContactSubscribe;
 };
 export type DeleteContactInput = {
     /** The contact record ID in format "authority/tsid" */
     contactId: string;
+    /** The account UID (base58btc-encoded principal) */
+    accountUid?: string;
 };
 export type CreateContactResult = HMPublishBlobsInput & {
     /** The record ID in format "authority/tsid" */

package/dist/document-state.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolves document state (genesis, heads, depth) from the ListChanges API.
+ *
+ * Depth is needed to construct valid Change blobs but is not directly
+ * exposed by the read API. We compute it by walking the change DAG:
+ * genesis has depth 0, each subsequent change has depth = max(dep depths) + 1.
+ */
+import type { SeedClient } from './client';
+/** The resolved state of a document's change DAG. */
+export type DocumentState = {
+    /** CID of the genesis change blob. */
+    genesis: string;
+    /** CIDs of the current head changes (not depended on by any other change). */
+    heads: string[];
+    /** Maximum depth among head changes. */
+    headDepth: number;
+    /** Dot-separated head CIDs (version string). */
+    version: string;
+};
+/**
+ * Resolves the current document state including head depth.
+ */
+export declare function resolveDocumentState(client: SeedClient, targetId: string): Promise<DocumentState>;

package/dist/file-to-ipfs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared IPFS file chunking utilities.
+ *
+ * Chunks binary data into UnixFS IPFS blocks using a MemoryBlockstore.
+ * Used by both the CLI (file:// link resolution) and the web app
+ * (comment attachment uploads) so the logic is not duplicated.
+ */
+import type { HMBlockNode } from './hm-types';
+export type CollectedBlob = {
+    cid: string;
+    data: Uint8Array;
+};
+/**
+ * Chunk a single piece of binary data into UnixFS IPFS blocks.
+ *
+ * Returns the root CID and all constituent IPFS blobs (DAG blocks)
+ * that should be published alongside the document/comment.
+ */
+export declare function fileToIpfsBlobs(data: Uint8Array): Promise<{
+    cid: string;
+    blobs: CollectedBlob[];
+}>;
+/**
+ * Chunk multiple binary attachments into IPFS blocks using a shared blockstore.
+ *
+ * Returns the root CIDs (one per input) and all collected IPFS blobs.
+ * This is the multi-file equivalent of `fileToIpfsBlobs`, suitable for
+ * comment editors that upload several images at once.
+ */
+export declare function filesToIpfsBlobs(binaries: Uint8Array[]): Promise<{
+    resultCIDs: string[];
+    blobs: CollectedBlob[];
+}>;
+/**
+ * Resolve all file:// links in a block tree.
+ *
+ * Walks the tree, finds blocks whose `link` field starts with `file://`,
+ * reads the data via the provided `readFile` callback, chunks with UnixFS,
+ * and replaces the link with `ipfs://ROOT_CID`.
+ *
+ * The `readFile` callback allows this to work in both Node.js (fs.readFileSync)
+ * and browser environments without importing `fs` directly.
+ *
+ * @returns The modified block tree and all collected IPFS blobs.
+ */
+export declare function resolveFileLinksInBlocks(nodes: HMBlockNode[], readFile: (path: string) => Uint8Array | Promise<Uint8Array>): Promise<{
+    nodes: HMBlockNode[];
+    blobs: CollectedBlob[];
+}>;
+/**
+ * Check whether any block in the tree has a file:// link.
+ */
+export declare function hasFileLinks(nodes: HMBlockNode[]): boolean;

package/dist/grobid.d.ts

@@ -0,0 +1,22 @@
+/**
+ * GROBID HTTP client — sends PDFs to a GROBID server for full-text extraction.
+ *
+ * Expects a running GROBID instance (e.g. via Docker):
+ *   docker run --rm -p 8070:8070 grobid/grobid:0.8.2-full
+ */
+export declare const DEFAULT_GROBID_URL = "http://localhost:8070";
+export interface GrobidOptions {
+    /** Base URL of the GROBID server (default: http://localhost:8070) */
+    grobidUrl?: string;
+    /** Request TEI coordinates for specific element types */
+    teiCoordinates?: string[];
+}
+/**
+ * Check whether a GROBID server is reachable at the given URL.
+ * Returns true if the server responds within the timeout, false otherwise.
+ */
+export declare function isGrobidAvailable(grobidUrl?: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Send a PDF to GROBID's processFulltextDocument endpoint and return TEI XML.
+ */
+export declare function processFulltextDocument(pdfBuffer: ArrayBuffer | Buffer, options?: GrobidOptions): Promise<string>;