zentao-api 0.6.2 → 0.6.4

package/dist/utils/doc-helper/shared.js

@@ -0,0 +1,305 @@
+const DEFAULT_MAX_DEPTH = 256;
+const MAX_ALLOWED_DEPTH = 1000;
+const DEFAULT_MAX_BLOCKS = 50_000;
+const MAX_ALLOWED_BLOCKS = 1_000_000;
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function toRecord(value) {
+    return isRecord(value) ? value : {};
+}
+export function toStringValue(value, fallback = '') {
+    return typeof value === 'string' ? value : fallback;
+}
+export function toFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+export function blockChildren(block) {
+    return Array.isArray(block.children)
+        ? block.children.filter(isBlockSnapshot)
+        : [];
+}
+export function isBlockSnapshot(value) {
+    return isRecord(value) && typeof value.flavour === 'string';
+}
+function parseJson(value) {
+    let parsed = value;
+    // The product loader accepts content that was JSON-stringified more than once.
+    for (let depth = 0; depth < 3 && typeof parsed === 'string'; depth += 1) {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new TypeError(`Invalid BlockSuite snapshot JSON: ${message}`);
+        }
+    }
+    return parsed;
+}
+export function normalizeSnapshot(input) {
+    let value = typeof input === 'string' ? parseJson(input) : input;
+    if (isRecord(value) && !isBlockSnapshot(value) && 'snapshot' in value) {
+        value = value.snapshot;
+    }
+    if (Array.isArray(value) && value.every(isBlockSnapshot)) {
+        return {
+            kind: 'slice',
+            blocks: value,
+            documentLike: false,
+        };
+    }
+    if (isRecord(value) && isBlockSnapshot(value.blocks)) {
+        const root = value.blocks;
+        return {
+            kind: 'doc',
+            blocks: [root],
+            root,
+            meta: isRecord(value.meta) ? value.meta : undefined,
+            documentLike: true,
+        };
+    }
+    if (isRecord(value) && Array.isArray(value.content)) {
+        const blocks = value.content.filter(isBlockSnapshot);
+        if (blocks.length !== value.content.length) {
+            throw new TypeError('Invalid BlockSuite slice: content must contain blocks');
+        }
+        return {
+            kind: 'slice',
+            blocks,
+            documentLike: false,
+        };
+    }
+    if (isBlockSnapshot(value)) {
+        return {
+            kind: 'block',
+            blocks: [value],
+            root: value,
+            documentLike: value.flavour === 'affine:page',
+        };
+    }
+    throw new TypeError('Invalid BlockSuite snapshot: expected a DocSnapshot, BlockSnapshot, SliceSnapshot, or JSON string');
+}
+function conversionLimit(value, fallback, maximum, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > maximum) {
+        throw new TypeError(`${name} must be an integer between 1 and ${maximum}`);
+    }
+    return Number(value);
+}
+/**
+ * Validate limits iteratively before recursive rendering. Besides making error
+ * messages deterministic, this prevents deeply nested untrusted JSON from
+ * exhausting the JavaScript call stack.
+ */
+export function validateSnapshotTree(blocks, options) {
+    const maxDepth = conversionLimit(options.maxDepth, DEFAULT_MAX_DEPTH, MAX_ALLOWED_DEPTH, 'maxDepth');
+    const maxBlocks = conversionLimit(options.maxBlocks, DEFAULT_MAX_BLOCKS, MAX_ALLOWED_BLOCKS, 'maxBlocks');
+    const active = new WeakSet();
+    const stack = [];
+    for (let index = blocks.length - 1; index >= 0; index -= 1) {
+        const block = blocks[index];
+        if (block)
+            stack.push({ block, depth: 1 });
+    }
+    let count = 0;
+    while (stack.length) {
+        const frame = stack.pop();
+        if (!frame)
+            continue;
+        if (frame.exit) {
+            active.delete(frame.block);
+            continue;
+        }
+        if (active.has(frame.block)) {
+            throw new TypeError('Invalid BlockSuite snapshot: cyclic block children');
+        }
+        count += 1;
+        if (count > maxBlocks) {
+            throw new RangeError(`BlockSuite snapshot exceeds maxBlocks (${maxBlocks})`);
+        }
+        if (frame.depth > maxDepth) {
+            throw new RangeError(`BlockSuite snapshot exceeds maxDepth (${maxDepth})`);
+        }
+        active.add(frame.block);
+        stack.push({ ...frame, exit: true });
+        const children = blockChildren(frame.block);
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            const child = children[index];
+            if (child)
+                stack.push({ block: child, depth: frame.depth + 1 });
+        }
+    }
+}
+export function deltaFrom(value) {
+    if (Array.isArray(value)) {
+        return value.filter(isRecord);
+    }
+    if (isRecord(value) && Array.isArray(value.delta)) {
+        return value.delta.filter(isRecord);
+    }
+    if (typeof value === 'string') {
+        return [{ insert: value }];
+    }
+    return [];
+}
+export function plainText(value) {
+    return deltaFrom(value)
+        .map(delta => (typeof delta.insert === 'string' ? delta.insert : ''))
+        .join('');
+}
+export function pageTitleDelta(normalized) {
+    const root = normalized.root;
+    if (root?.flavour === 'affine:page') {
+        const rootTitle = deltaFrom(toRecord(root.props).title);
+        if (rootTitle.length > 0)
+            return rootTitle;
+    }
+    const metaTitle = normalized.meta?.title;
+    return typeof metaTitle === 'string' ? [{ insert: metaTitle }] : [];
+}
+export function pageTitleText(normalized) {
+    const metaTitle = normalized.meta?.title;
+    if (typeof metaTitle === 'string')
+        return metaTitle;
+    return plainText(toRecord(normalized.root?.props).title);
+}
+export function escapeHtml(value) {
+    return String(value ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+export function escapeHtmlAttribute(value) {
+    return escapeHtml(value)
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+export function sanitizeUrl(value, kind = 'link') {
+    if (typeof value !== 'string')
+        return '';
+    const url = value.trim().replace(/[\u0000-\u001F\u007F]/g, '');
+    if (!url)
+        return '';
+    if (url.startsWith('/') ||
+        url.startsWith('./') ||
+        url.startsWith('../') ||
+        url.startsWith('#') ||
+        url.startsWith('?')) {
+        return url;
+    }
+    const scheme = /^([a-z][a-z\d+.-]*):/i.exec(url)?.[1]?.toLowerCase();
+    if (!scheme)
+        return url;
+    if (['http', 'https', 'mailto', 'tel', 'blob'].includes(scheme))
+        return url;
+    if (kind === 'image' && scheme === 'data' && /^data:image\//i.test(url)) {
+        return url;
+    }
+    return '';
+}
+export function resolveAssetUrl(options, block, kind) {
+    const props = toRecord(block.props);
+    const sourceId = toStringValue(props.sourceId);
+    if (!sourceId)
+        return '';
+    const resolved = options.resolveAssetUrl?.(sourceId, block, kind);
+    return sanitizeUrl(resolved, kind === 'image' ? 'image' : 'link');
+}
+export function resolveZuiImageUrl(options, block) {
+    const src = toStringValue(toRecord(block.props).src);
+    if (!src)
+        return '';
+    const resolved = options.resolveZuiImageUrl
+        ? options.resolveZuiImageUrl(src, block)
+        : src;
+    return sanitizeUrl(resolved, 'image');
+}
+function appendReferenceParams(url, params) {
+    const search = new URLSearchParams();
+    for (const [key, raw] of Object.entries(params)) {
+        if (raw === undefined || raw === null || raw === '')
+            continue;
+        if (Array.isArray(raw)) {
+            const values = raw.filter((item) => ['string', 'number', 'boolean'].includes(typeof item));
+            if (values.length)
+                search.set(key, values.join(','));
+        }
+        else if (['string', 'number', 'boolean'].includes(typeof raw)) {
+            search.set(key, String(raw));
+        }
+    }
+    const query = search.toString();
+    if (!query)
+        return url;
+    return `${url}${url.includes('?') ? '&' : '?'}${query}`;
+}
+export function resolveDocumentUrl(options, reference, block) {
+    const custom = options.resolveDocLink?.(reference, block);
+    if (custom !== undefined)
+        return sanitizeUrl(custom);
+    const base = options.docLinkBaseUrl?.replace(/\/$/, '');
+    if (!base)
+        return '';
+    return sanitizeUrl(appendReferenceParams(`${base}/${encodeURIComponent(reference.pageId)}`, reference.params));
+}
+export function formatFileSize(value) {
+    const bytes = toFiniteNumber(value) ?? 0;
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'kB', 'MB', 'GB', 'TB'];
+    const index = Math.min(Math.floor(Math.log(Math.abs(bytes)) / Math.log(1024)), units.length - 1);
+    const size = bytes / 1024 ** index;
+    const rounded = size >= 10 || index === 0 ? size.toFixed(0) : size.toFixed(1);
+    return `${rounded} ${units[index]}`;
+}
+export function isEdgelessOnly(block) {
+    return toRecord(block.props).displayMode === 'edgeless';
+}
+export function safeLanguage(value) {
+    return typeof value === 'string'
+        ? value.trim().replace(/[^a-z\d_+#.-]/gi, '').slice(0, 50)
+        : '';
+}
+export function escapeMarkdownMath(value) {
+    return toStringValue(value)
+        .replace(/\$/g, '\\$')
+        .replace(/</g, '\\lt{}')
+        .replace(/>/g, '\\gt{}')
+        .replace(/(\]\(\s*)([^)\s]*)/gi, (match, prefix, target) => {
+        const decoded = target
+            .replace(/&#x([\da-f]+);/gi, (_, hex) => {
+            const code = Number.parseInt(hex, 16);
+            return code <= 0x7f ? String.fromCharCode(code) : '';
+        })
+            .replace(/&#(\d+);/g, (_, decimal) => {
+            const code = Number.parseInt(decimal, 10);
+            return code <= 0x7f ? String.fromCharCode(code) : '';
+        })
+            .replace(/&colon;/gi, ':')
+            .replace(/[\u0000-\u0020\u007f]/g, '')
+            .toLowerCase();
+        if (!/^(?:javascript|vbscript|data):/.test(decoded))
+            return match;
+        return `${prefix}${target.replace(/:|&(?:#0*58|#x0*3a|colon);/i, '%3A')}`;
+    });
+}
+export function safeCssColor(value) {
+    if (typeof value !== 'string')
+        return '';
+    const color = value.trim();
+    if (/^(#[\da-f]{3,8}|(?:rgb|hsl)a?\([\d\s.,%+-]+\)|var\(--[\w-]+\)|[a-z]+)$/i.test(color)) {
+        return color;
+    }
+    return '';
+}
+export function safeFontSize(value) {
+    if (typeof value !== 'string')
+        return '';
+    const size = value.trim();
+    return /^(?:\d+(?:\.\d+)?(?:px|em|rem|%|pt)|var\(--[\w-]+\))$/i.test(size)
+        ? size
+        : '';
+}

package/dist/utils/doc-helper/types.d.ts

@@ -0,0 +1,86 @@
+export type JsonRecord = Record<string, unknown>;
+export interface DeltaInsert {
+    insert?: unknown;
+    attributes?: JsonRecord;
+    retain?: number;
+    delete?: number;
+}
+export interface TextSnapshot {
+    '$blocksuite:internal:text$'?: true;
+    delta: DeltaInsert[];
+}
+export interface BlockSnapshot {
+    type?: 'block' | string;
+    id?: string;
+    flavour: string;
+    version?: number;
+    props?: JsonRecord;
+    children?: BlockSnapshot[];
+}
+export interface DocSnapshotMeta extends JsonRecord {
+    id?: string;
+    title?: string;
+    createDate?: number;
+    tags?: string[];
+}
+export interface DocSnapshot {
+    type?: 'page' | string;
+    meta?: DocSnapshotMeta;
+    blocks: BlockSnapshot;
+}
+export interface SliceSnapshot {
+    type?: 'slice' | string;
+    content: BlockSnapshot[];
+}
+export type Snapshot = DocSnapshot | BlockSnapshot | SliceSnapshot;
+export interface SnapshotEnvelope {
+    snapshot: Snapshot | readonly BlockSnapshot[];
+}
+export type SnapshotInput = Snapshot | readonly BlockSnapshot[] | SnapshotEnvelope | string;
+export type OutputFormat = 'markdown' | 'html';
+export type UnknownBlockStrategy = 'children' | 'omit' | 'throw';
+export interface DocumentReference {
+    pageId: string;
+    params: JsonRecord;
+    title?: string;
+}
+export interface RenderBlockContext {
+    format: OutputFormat;
+    renderChildren(children?: readonly BlockSnapshot[]): string;
+    renderInline(text: unknown): string;
+}
+export type BlockRenderer = (block: BlockSnapshot, context: RenderBlockContext) => string | undefined;
+export interface ConvertOptions {
+    /** Include the page title. Defaults to true. */
+    includeTitle?: boolean;
+    /** Maximum nested block depth. Defaults to 256 and cannot exceed 1000. */
+    maxDepth?: number;
+    /** Maximum number of blocks rendered from one snapshot. Defaults to 50,000. */
+    maxBlocks?: number;
+    /** Used for standard image/attachment sourceId values. */
+    resolveAssetUrl?: (sourceId: string, block: BlockSnapshot, kind: 'image' | 'attachment') => string | undefined;
+    /** Resolve editor-specific affine:zui-image src placeholders. */
+    resolveZuiImageUrl?: (src: string, block: BlockSnapshot) => string | undefined;
+    /** Resolve linked-document references without loading a BlockSuite collection. */
+    resolveDocLink?: (reference: DocumentReference, block?: BlockSnapshot) => string | undefined;
+    /** Resolve the visible label of a linked document. */
+    resolveDocTitle?: (pageId: string) => string | undefined;
+    /** Base URL used when resolveDocLink is not supplied. */
+    docLinkBaseUrl?: string;
+    /** Override built-in rendering. Return undefined to continue normally. */
+    renderBlock?: BlockRenderer;
+    /** Unknown containers recurse by default; unknown leaves produce no output. */
+    unknownBlock?: UnknownBlockStrategy;
+}
+export type MarkdownOptions = ConvertOptions;
+export interface HtmlOptions extends ConvertOptions {
+    /**
+     * Defaults to true for a DocSnapshot/page root and false for block/slice input.
+     */
+    fullDocument?: boolean;
+    /**
+     * Render stored HTML from affine:embed-zui-html or zui-custom as trusted HTML.
+     * Disabled by default.
+     */
+    allowUnsafeHtml?: boolean;
+}

package/dist/utils/doc-helper/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-08-18T08:24:17.240Z";
-const fallbackVersion = "0.6.2";
+const fallbackBuild = "2026-08-19T02:49:40.949Z";
+const fallbackVersion = "0.6.4";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",