@im-nobsidian/core 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -1578,6 +1578,11 @@ interface NotionClientOptions {
     readonly notifications?: NotificationMode;
     readonly fetch?: typeof globalThis.fetch;
 }
+/** 덧붙일 자리 — 블록 뒤(`after`) · 맨 앞(`atStart`). 없으면 맨 끝. */
+interface AppendPosition {
+    readonly after?: string;
+    readonly atStart?: boolean;
+}
 declare class NotionClient {
     private readonly client;
     private readonly sema;
@@ -1880,31 +1885,31 @@ declare class NotionClient {
      */
     getBlockTree(blockId: string): Promise<BlockTreeNode[]>;
     /**
-     * 자식 블록을 덧붙인다. `options.after` 를 주면 그 블록 **바로 뒤**에 삽입한다
+     * 자식 블록을 덧붙인다. `options.after` 를 주면 그 블록 **바로 뒤**에, `options.atStart` 면 맨 앞에 삽입한다
      * (기본은 맨 끝). 자리표시자를 실제 미디어 블록으로 제자리 교체할 때 필요하다.
      *
      * 실측(2025-09-03): position 삽입 응답의 `results` 는 방금 넣은 블록뿐 아니라
      * 삽입 지점 이후의 형제까지 함께 돌려준다. 앞에서부터 batch 길이만큼이 새 블록이므로
      * 배치를 이어 붙일 때는 그 마지막 id 를 다음 기준점으로 삼는다.
      */
-    appendChildren(blockId: string, children: unknown[], options?: {
-        readonly after?: string;
-    }): Promise<string[]>;
+    appendChildren(blockId: string, children: unknown[], options?: AppendPosition): Promise<string[]>;
     /**
      * {@link appendChildren} 과 같되 새로 만든 블록을 통째로 돌려준다. 파일을 붙인 미디어 블록은
      * 응답에 Notion 이 저장한 파일의 URL 이 실려 온다 — 다시 조회하지 않고 그 파일을 알아 둔다(S-05).
      */
-    appendChildBlocks(blockId: string, children: unknown[], options?: {
-        readonly after?: string;
-    }): Promise<(BlockObjectResponse | PartialBlockObjectResponse)[]>;
+    appendChildBlocks(blockId: string, children: unknown[], options?: AppendPosition): Promise<(BlockObjectResponse | PartialBlockObjectResponse)[]>;
     /**
      * 깊이 제한 없는 블록 트리를 맨 끝에 덧붙인다 — 요청 한도(깊이 두 단계 · 100 개 · 1000 블록)를 넘는
      * 자식은 부모를 만든 뒤 그 아래에 마저 붙인다({@link shapeAppendRequests}). 더 깊은 블록의 id 는
      * 응답에 없어 부모의 자식 목록을 읽어 찾는다.
      *
+     * `options.atStart` 면 맨 위 블록을 맨 앞에 넣는다 — 본문 뒤에 둘 블록(폴더 첨부)을 남기고 본문만 바꿀 때.
+     *
      * 중간에 실패하면 그때까지 만든 블록은 남는다 — 호출측이 실패로 알린다.
      */
-    appendBlockTree(parentId: string, blocks: readonly BlockRequest[]): Promise<void>;
+    appendBlockTree(parentId: string, blocks: readonly BlockRequest[], options?: {
+        readonly atStart?: boolean;
+    }): Promise<void>;
     deleteBlock(blockId: string): Promise<void>;
     /**
      * 코드 블록의 글을 바꾼다 — Markdown API 로 보낼 수 없는 코드(코드 속 ``` 줄, S-22)를 블록으로
@@ -3335,6 +3340,11 @@ interface FileHandlerOptions {
      * 파일을. 기본 false.
      */
     readonly deleteSync?: boolean;
+    /**
+     * 볼트 맨 위 파일을 싣는 페이지({@link rootFilesPageOf}) — 페이지 모드의 루트. 없으면(DB 모드) 볼트 맨 위 파일은 경고로 남는다.
+     * 루트는 사용자의 페이지라 노트 페이지처럼 적어 둔 폴더 첨부만 제 것으로 본다.
+     */
+    readonly rootPageId?: string | null;
 }
 /**
  * 노트의 페이지에 폴더 첨부 블록을 붙이거나 지울 때(ADR-056) — 그 쓰기로 노트 페이지의 수정 시각 · 본문이 바뀐다. 알리지 않으면
@@ -3372,6 +3382,7 @@ declare class FileHandler {
     private readonly itemTimeoutMs;
     private readonly attachmentsFolder;
     private readonly deleteSync;
+    private readonly rootPageId;
     constructor(vaultFs: VaultFS, notionClient: NotionClient, stateDb: IStateDB, concurrency?: number, options?: FileHandlerOptions);
     private get fetchFn();
     pushFilesForFolder(folderPageId: string, folderPath: string): Promise<FileUploadResult[]>;
@@ -3402,11 +3413,14 @@ declare class FileHandler {
     private inAttachmentsFolder;
     /**
      * 폴더 첨부를 둘 Notion 페이지 — 그 폴더의 Notion 자리({@link folderContainer} 와 같은 차례). 폴더 노트(`X/X.md`)나 노트
-     * 이름의 폴더(`X.md` 옆 `X/`)면 그 노트의 페이지 끝(ADR-056), 아니면 push 가 만든 폴더 페이지. 맨 위는 루트 기록이 있을 때만.
-     * 행 · DB 폴더는 둘 곳이 없다 — 행의 본문은 행의 것이다.
+     * 이름의 폴더(`X.md` 옆 `X/`)면 그 노트의 페이지 끝(ADR-056), 아니면 push 가 만든 폴더 페이지. 맨 위는 루트 페이지 끝.
+     * 행 이름의 폴더(`DB/행/`)는 그 행의 페이지 끝. DB 폴더는 둘 곳이 없다 — Notion 의 DB 는 본문이 없다.
      */
     private folderPageOf;
-    /** 이 폴더를 품은 노트의 페이지 — 폴더 노트 · 노트 이름의 폴더. 없거나 행이면 null. */
+    /**
+     * 이 폴더를 품은 노트의 페이지 — 폴더 노트 · 노트(행 포함) 이름의 폴더 · 볼트 맨 위는 루트 페이지. 본문이 이 도구의 것이
+     * 아니거나(루트) 노트의 것이라, 적어 둔 폴더 첨부만 제 것으로 본다. 없으면 null.
+     */
     private notePageOf;
     private folderRecordPageOf;
     /**
@@ -3729,6 +3743,11 @@ interface RowProgress {
     planned(count: number): void;
     done(item: ProgressItem): void;
 }
+/** 행 페이지 끝에서 뗀 폴더 첨부 — `complete` 면 빠진 파일을 Notion 에서 지운 것으로 본다. */
+interface RowFolderFiles {
+    readonly files: readonly FolderFileRef[];
+    readonly complete: boolean;
+}
 declare class DatabaseSyncer {
     private readonly config;
     private readonly stateDb;
@@ -3746,6 +3765,8 @@ declare class DatabaseSyncer {
      * 채운다({@link RemoteDetector.noteBodyChildren}).
      */
     private readonly noteRowBody;
+    /** 행 이름의 폴더에 그 행 페이지의 폴더 첨부를 받는다(ADR-056) — `PagePuller.receiveFolderFiles`. */
+    private readonly receiveRowFiles;
     private readonly propertyMapper;
     private decorationsCache?;
     /**
@@ -3805,7 +3826,9 @@ declare class DatabaseSyncer {
      * 받은 행 본문(Notion 원문)을 알린다 — 감지가 행의 하위 페이지를 빠뜨렸을 때 그 본문의 자식 태그로
      * 채운다({@link RemoteDetector.noteBodyChildren}).
      */
-    noteRowBody?: (pageId: string, rawMarkdown: string) => void);
+    noteRowBody?: (pageId: string, rawMarkdown: string) => void, 
+    /** 행 이름의 폴더에 그 행 페이지의 폴더 첨부를 받는다(ADR-056) — `PagePuller.receiveFolderFiles`. */
+    receiveRowFiles?: (folder: string, pageId: string, files: readonly FolderFileRef[], complete: boolean) => Promise<void>);
     pullAll(opts?: {
         readonly paths?: readonly string[];
         readonly progress?: RowProgress;
@@ -4067,6 +4090,8 @@ declare class DatabaseSyncer {
         bodyFingerprint: string;
         /** 원격 본문에 페이지 시절의 속성 블록이 있었나 — 받으며 걷어 냈다. */
         propertiesBlock: boolean;
+        /** 행 끝에서 뗀 폴더 첨부(ADR-056 · 행 이름의 폴더) — 받는 것은 호출측이 정한다. */
+        folderFiles: RowFolderFiles;
     }>;
     /**
      * 행의 본문 밖이 지난 동기화 사본 그대로인가(N-05) — 제목과 보낼 수 있는 속성, 아이콘 · 커버.
@@ -4153,6 +4178,11 @@ declare class DatabaseSyncer {
      * 든다. 추적하는 노트가 없으면 null.
      */
     private adoptedChildrenOf;
+    /**
+     * 이 노트 · 행 옆의 폴더(`from`)가 그것의 것인가 — 하위 페이지가 있거나, 그 페이지에 올린 폴더 첨부(ADR-056)가 든 폴더.
+     * 예전에는 하위 페이지만 보아 행의 이름을 따라 옮길 때 폴더 첨부만 든 폴더가 옛 이름에 남았다.
+     */
+    private holdsChildren;
     /**
      * Notion 에서 바꾼 제목으로 행 이름을 바꿀 자리(`sync.renameOnTitleChange`) — 바꿀 것이 없으면 null.
      * 받기 · pull dry-run · status 가 같은 판정을 쓴다. 행의 하위 페이지 폴더(`행/`)도 새 이름으로 옮기며, 옮길 수
@@ -4164,7 +4194,12 @@ declare class DatabaseSyncer {
     } | {
         reason: string;
     } | null>;
+    /**
+     * 행 하나를 받고 그 행 페이지의 폴더 첨부를 행 이름의 폴더에 받는다(ADR-056) — 노트가 충돌로 남거나 로컬을 지켜도 파일은
+     * 제 규칙대로 받는다(페이지와 같다). 행을 옮겼으면 옮긴 자리로.
+     */
     private pullDatabasePage;
+    private pullDatabaseRow;
 }
 
 declare class FrontmatterExtractor implements Processor {