@getnote/mcp 1.7.2 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,122 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.noteSelectors = void 0;
4
+ exports.normalizeLookup = normalizeLookup;
5
+ exports.discoveryContract = discoveryContract;
6
+ exports.verifyDiscovery = verifyDiscovery;
7
+ const zod_1 = require("zod");
8
+ const text = zod_1.z.string().trim().min(1);
9
+ const integer = zod_1.z.number().int().positive();
10
+ const times = ["created_from", "created_to", "edited_from", "edited_to", "record_updated_from", "record_updated_to"];
11
+ exports.noteSelectors = {
12
+ source: text.optional(), note_type: text.optional(),
13
+ reference_resource_type: text.optional(), reference_resource_id: text.optional(),
14
+ reference_article_url: zod_1.z.string().url().refine(v => /^https?:\/\//.test(v)).optional(),
15
+ topic_id: text.optional(), page_size: integer.max(100).optional(),
16
+ created_from: text.optional(), created_to: text.optional(), edited_from: text.optional(), edited_to: text.optional(),
17
+ record_updated_from: text.optional(), record_updated_to: text.optional(),
18
+ };
19
+ function noteSchema() { return zod_1.z.object({ ...exports.noteSelectors, page: integer.optional(), cursor: zod_1.z.string().min(1).optional() }).strict(); }
20
+ const lookupSchema = zod_1.z.object({ page: integer.optional(), scope: zod_1.z.enum(["DEFAULT", "CUSTOMER", "BOOKSPACE", "TEAMSPACE"]).optional(), query: text.optional(), author: text.optional(), book_id: text.optional(), page_size: integer.max(100).optional() }).strict();
21
+ function normalizeLookup(value) {
22
+ value = value.normalize("NFKC").trim();
23
+ for (const [left, right] of [["《", "》"], ["“", "”"], ['"', '"'], ["'", "'"]]) {
24
+ if (value.startsWith(left) && value.endsWith(right) && value.length >= left.length + right.length) {
25
+ value = value.slice(left.length, -right.length).trim();
26
+ break;
27
+ }
28
+ }
29
+ return value.toLowerCase();
30
+ }
31
+ // Keep nanoseconds: Date alone would round distinct reference/time boundaries.
32
+ function timestamp(value) {
33
+ zod_1.z.string().datetime({ offset: true }).parse(value);
34
+ const m = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/.exec(value);
35
+ if (!m)
36
+ throw new Error("time filters require RFC3339 with timezone");
37
+ const ms = Date.parse(m[1] + m[3]);
38
+ if (!Number.isFinite(ms))
39
+ throw new Error("invalid time filter");
40
+ const fraction = (m[2] || "").replace(/0+$/, "");
41
+ return { text: new Date(ms).toISOString().slice(0, 19) + (fraction ? "." + fraction : "") + "Z", epoch: BigInt(ms) * 1000000n + BigInt((m[2] || "").padEnd(9, "0")) };
42
+ }
43
+ function discoveryContract(kind, input) {
44
+ const values = Object.fromEntries(Object.entries(input).filter(([, v]) => v !== undefined));
45
+ const legacy = kind === "topics" ? ["page", "scope"] : kind === "detail" ? ["id", "image_quality"] : kind === "topicNotes" ? ["topic_id", "page"] : ["cursor"];
46
+ if (!Object.keys(values).some(k => !legacy.includes(k)))
47
+ return undefined;
48
+ let params;
49
+ const filters = {};
50
+ if (kind === "detail") {
51
+ params = zod_1.z.object({ id: zod_1.z.union([text, zod_1.z.number().int().safe()]), image_quality: zod_1.z.enum(["original"]).optional() }).strict().parse(values);
52
+ return { params, filters, capabilities: ["note.reference.v1"], kind };
53
+ }
54
+ if (kind === "topics") {
55
+ params = { scope: "DEFAULT", page: 1, page_size: 20, ...lookupSchema.parse(values) };
56
+ if (params.scope !== "BOOKSPACE" && (params.author || params.book_id))
57
+ throw new Error("author and book_id require BOOKSPACE");
58
+ for (const key of ["query", "author"])
59
+ if (typeof params[key] === "string")
60
+ params[key] = normalizeLookup(params[key]);
61
+ }
62
+ else {
63
+ params = { page_size: 20, ...(kind === "topicNotes" ? { page: 1 } : {}), ...noteSchema().parse(values) };
64
+ if (kind === "topicNotes" && !params.topic_id)
65
+ throw new Error("topic_id is required");
66
+ if (params.page && (!params.topic_id || params.cursor))
67
+ throw new Error("page requires topic_id and cannot be combined with cursor");
68
+ if (params.reference_resource_id) {
69
+ if (!params.source || !params.reference_resource_type)
70
+ throw new Error("reference ID requires source and resource type");
71
+ const id = String(params.reference_resource_id);
72
+ if (!/^\d+$/.test(id) || BigInt(id) <= 0n || BigInt(id) > 9223372036854775807n)
73
+ throw new Error("invalid reference ID");
74
+ }
75
+ const epochs = {};
76
+ for (const key of times)
77
+ if (typeof params[key] === "string") {
78
+ const t = timestamp(params[key]);
79
+ params[key] = t.text;
80
+ epochs[key] = t.epoch;
81
+ }
82
+ for (const prefix of ["created", "edited", "record_updated"])
83
+ if (epochs[prefix + "_from"] !== undefined && epochs[prefix + "_to"] !== undefined && epochs[prefix + "_from"] >= epochs[prefix + "_to"])
84
+ throw new Error("time interval must have from < to");
85
+ }
86
+ for (const [key, value] of Object.entries(params))
87
+ if (!["cursor", "page", "page_size"].includes(key))
88
+ filters[key] = String(value);
89
+ const capabilities = ["pagination.v1"];
90
+ if (kind === "topics")
91
+ capabilities.push("knowledge.lookup.v1");
92
+ else if (Object.keys(filters).length)
93
+ capabilities.push("note.filters.v1");
94
+ if (kind !== "topics")
95
+ capabilities.push("note.reference.v1");
96
+ return { params, filters, capabilities, kind };
97
+ }
98
+ function verifyDiscovery(body, contract) {
99
+ const envelope = zod_1.z.object({ meta: zod_1.z.object({ capabilities: zod_1.z.array(zod_1.z.string()) }), data: zod_1.z.record(zod_1.z.unknown()) }).safeParse(body);
100
+ if (!envelope.success)
101
+ throw new Error("server does not declare discovery capabilities; upgrade the server (unfiltered results not accepted)");
102
+ for (const cap of contract.capabilities)
103
+ if (!envelope.data.meta.capabilities.includes(cap))
104
+ throw new Error(`server does not support ${cap}; unfiltered results not accepted`);
105
+ if (contract.kind === "detail")
106
+ return;
107
+ const data = envelope.data.data;
108
+ const applied = zod_1.z.record(zod_1.z.string()).safeParse(data.applied_filters);
109
+ if (!applied.success)
110
+ throw new Error("server did not return applied_filters");
111
+ for (const [key, value] of Object.entries(contract.filters))
112
+ if (applied.data[key] !== value)
113
+ throw new Error(`server did not apply ${key}`);
114
+ const p = zod_1.z.object({ mode: zod_1.z.enum(["page", "cursor"]), page: integer.nullable(), page_size: integer.max(100), returned_count: zod_1.z.number().int().nonnegative(), total_count: zod_1.z.number().int().nonnegative().nullable(), has_more: zod_1.z.boolean(), next_page: integer.nullable(), next_cursor: zod_1.z.string().min(1).nullable() }).parse(data.pagination);
115
+ const items = data[contract.kind === "topics" ? "topics" : "notes"];
116
+ const page = contract.params.page;
117
+ if (!Array.isArray(items) || p.mode !== (page ? "page" : "cursor") || p.page_size !== contract.params.page_size || p.returned_count !== items.length || items.length > p.page_size || (p.total_count !== null && p.total_count < items.length) || (page && p.page !== page))
118
+ throw new Error("invalid discovery pagination response");
119
+ if (p.has_more ? (page ? p.next_page !== Number(page) + 1 || p.next_cursor !== null : !p.next_cursor || p.next_page !== null) : p.next_page !== null || p.next_cursor !== null)
120
+ throw new Error("invalid discovery continuation");
121
+ }
122
+ //# sourceMappingURL=discovery.js.map
package/dist/index.js CHANGED
@@ -44,6 +44,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
44
44
  const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
45
45
  const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
46
46
  const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
47
+ const zod_1 = require("zod");
47
48
  const client_js_1 = require("./client.js");
48
49
  const membership_js_1 = require("./membership.js");
49
50
  const node_fs_1 = require("node:fs");
@@ -130,14 +131,32 @@ function snowflakeID(value, field) {
130
131
  throw new Error(`${field} must be a decimal string; only legacy integers within JavaScript's safe range are accepted`);
131
132
  }
132
133
  // ─── Tool Definitions ────────────────────────────────────────────────────────
134
+ const noteDiscoveryProperties = {
135
+ page: { type: "integer", minimum: 1, description: "知识库内可用页码;与 cursor 互斥" },
136
+ source: { type: "string", description: "来源平台精确筛选,如 dedao" },
137
+ note_type: { type: "string", description: "笔记真实类型精确筛选,如 ref" },
138
+ reference_resource_type: { type: "string", description: "引用资源类型,如 ebook、course_article、audio_book" },
139
+ reference_resource_id: { type: "string", description: "引用资源 ID,必须字符串;同时传 source 和 reference_resource_type" },
140
+ reference_article_url: { type: "string", description: "文章 URL 精确筛选,保留 query 和 fragment" },
141
+ topic_id: { type: "string", description: "知识库 ID,限定授权范围" },
142
+ page_size: { type: "integer", minimum: 1, maximum: 100, description: "每页 1–100 条,默认 20" },
143
+ ...Object.fromEntries(["created_from", "created_to", "edited_from", "edited_to", "record_updated_from", "record_updated_to"].map(key => [key, { type: "string", description: "RFC3339 带时区,from 包含、to 不包含;三种时间轴独立" }])),
144
+ };
145
+ const knowledgeLookupProperties = {
146
+ query: { type: "string", description: "按知识库名/书名定位;多候选须核对书名、作者和 book_id" },
147
+ author: { type: "string", description: "书籍作者,限 BOOKSPACE" },
148
+ book_id: { type: "string", description: "书籍 ID 字符串,限 BOOKSPACE" },
149
+ page_size: noteDiscoveryProperties.page_size,
150
+ };
133
151
  const TOOLS = [
134
152
  // ── Notes ──
135
153
  {
136
154
  name: "list_notes",
137
- description: "获取笔记列表(每次固定返回 20 条,服务端不支持 limit 参数)。用游标翻页:首次请求不传 cursor;后续把上一次响应返回的 cursor 字段原样传入,直到 has_more 为 false。响应里的 total 是全库笔记总数,不是本页条数。",
155
+ description: "按来源、引用资源或知识库查找笔记。列表只返回定位信息;需要正文和完整元数据时调用 get_note。新查询须核对 meta.capabilities、applied_filters,按 pagination.next_cursor 翻页到 has_more=false 才能说全量完成。total_count=null 表示未知,不能用本页条数代替全库总数。",
138
156
  inputSchema: {
139
157
  type: "object",
140
158
  properties: {
159
+ ...noteDiscoveryProperties,
141
160
  cursor: {
142
161
  type: "string",
143
162
  description: "翻页游标。首次不传;后续将上一次响应的 cursor 字段原样传入即可,无需任何转换。",
@@ -148,7 +167,7 @@ const TOOLS = [
148
167
  },
149
168
  {
150
169
  name: "get_note",
151
- description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio 等):转写原文 = `note.audio.original`,AI 总结 = `note.content`\n\n用户要求'读原文'时,先看 `note.note_type`,再按上述对应关系取字段。",
170
+ description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 引用笔记(ref):原文 = `note.ref_content`,`note.content` 是个人评论\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio):转写原文 = `note.audio.original`,AI 总结 = `note.content`\n\n用户要求'读原文'时,先看 `note.note_type`,再按上述对应关系取字段。",
152
171
  inputSchema: {
153
172
  type: "object",
154
173
  properties: {
@@ -167,7 +186,7 @@ const TOOLS = [
167
186
  },
168
187
  {
169
188
  name: "get_note_original",
170
- description: "直接读取笔记原文。链接笔记返回网页原文,录音笔记返回转写原文,文字笔记返回正文;不要把 AI 摘要冒充原文。",
189
+ description: "直接读取笔记原文。引用笔记返回 ref_content,链接笔记返回网页原文,录音笔记返回转写原文,文字笔记返回正文;无原文或不支持的类型会报错。",
171
190
  inputSchema: { type: "object", properties: { id: { type: ["string", "number"], description: "笔记 ID,推荐十进制字符串" } }, required: ["id"] },
172
191
  },
173
192
  {
@@ -185,6 +204,11 @@ const TOOLS = [
185
204
  description: "直接读取录音或会议笔记的结构化时间线和原文资源;没有时间线时明确返回不可用。",
186
205
  inputSchema: { type: "object", properties: { id: { type: ["string", "number"], description: "笔记 ID,推荐十进制字符串" } }, required: ["id"] },
187
206
  },
207
+ {
208
+ name: "get_note_chapters",
209
+ description: "读取总结中的独立章节时间线 chapter_timeline;start_ms 为毫秒,保留 source。与录音 moments 和标记分别读取,不能相互替代。",
210
+ inputSchema: { type: "object", properties: { id: { type: "string", description: "笔记 ID" } }, required: ["id"] },
211
+ },
188
212
  {
189
213
  name: "get_note_quick_note",
190
214
  description: "直接读取录音笔记的快捷笔记;没有快捷笔记时明确返回不可用。",
@@ -345,6 +369,7 @@ const TOOLS = [
345
369
  inputSchema: {
346
370
  type: "object",
347
371
  properties: {
372
+ ...knowledgeLookupProperties,
348
373
  page: {
349
374
  type: "number",
350
375
  description: "页码,从 1 开始(默认 1)",
@@ -384,10 +409,11 @@ const TOOLS = [
384
409
  },
385
410
  {
386
411
  name: "list_topic_notes",
387
- description: "获取指定知识库内的笔记列表(每页 20 条)。\n\n**AI Agent 提示**:列表返回的 `content` 字段可能较长且通常为 AI 总结。如需先获取标题和类型再按需读详情,可用此接口获取 `note_id` 列表,再对感兴趣的条目逐一调用 `get_note`。",
412
+ description: "列出知识库内可访问的笔记,支持来源、引用资源、时间筛选。列表只返回定位信息;需要正文和完整元数据时调用 get_note。按 pagination.next_page 翻页;去重 ID,重复游标/页码、无进展或中途失败不能声称全量完成。",
388
413
  inputSchema: {
389
414
  type: "object",
390
415
  properties: {
416
+ ...noteDiscoveryProperties,
391
417
  topic_id: {
392
418
  type: "string",
393
419
  description: "知识库 ID",
@@ -473,6 +499,36 @@ const TOOLS = [
473
499
  required: ["topic_id", "note_ids"],
474
500
  },
475
501
  },
502
+ {
503
+ name: "get_note_marks",
504
+ description: "读取笔记标记(包含文字标记、照片等),与 Timeline 独立,不用时间线替代标记。",
505
+ inputSchema: { type: "object", properties: { note_id: { type: "string" } }, required: ["note_id"] },
506
+ },
507
+ {
508
+ name: "list_sprouts",
509
+ description: "按月份读取当前用户发芽报告;发芽不是标记数据。",
510
+ inputSchema: { type: "object", properties: { month: { type: "string", description: "YYYY-MM" }, since_id: { type: "string", description: "上一页返回的游标,原样传递" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, required: ["month"] },
511
+ },
512
+ {
513
+ name: "get_sprout",
514
+ description: "读取已授权用户发芽报告原文,id 来自 list_sprouts。",
515
+ inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
516
+ },
517
+ {
518
+ name: "get_knowledge_file_capabilities",
519
+ description: "上传前查询当前配置允许的文件扩展名、MIME、大小、页数和独立日限额;不缓存为固定格式列表。",
520
+ inputSchema: { type: "object", properties: {} },
521
+ },
522
+ {
523
+ name: "get_knowledge_file_upload_token",
524
+ description: "获取一次 OSS 文件上传临时凭据。通过本地 getnote upload --token-file <file> --max-size-bytes <能力上限> 直接 PUT 到 OSS,无需再次 CLI 登录。凭据通过受控文件或 stdin 传入,不写命令参数或聊天;不要把文件字节传给云 MCP。",
525
+ inputSchema: { type: "object", properties: { mime_type: { type: "string", description: "能力接口返回的扩展名,如 HTML" } }, required: ["mime_type"] },
526
+ },
527
+ {
528
+ name: "upload_knowledge_file",
529
+ description: "OSS 直传成功后将原文件加入知识库,只接收元数据,不接收本地路径或 base64。返回处理中的资源不等于入库成功;用 list_topic_directories 查询同一 ID,直到 SUCCESS 或 FAIL。",
530
+ inputSchema: { type: "object", additionalProperties: false, properties: { topic_id: { type: "string" }, directory_id: { type: "string" }, file_name: { type: "string" }, file_type: { type: "string" }, md5: { type: "string" }, url: { type: "string" } }, required: ["topic_id", "directory_id", "file_name", "file_type", "md5", "url"] },
531
+ },
476
532
  // ── Image ──
477
533
  {
478
534
  name: "get_upload_config",
@@ -674,6 +730,7 @@ const TOOLS = [
674
730
  inputSchema: {
675
731
  type: "object",
676
732
  properties: {
733
+ ...knowledgeLookupProperties,
677
734
  page: {
678
735
  type: "number",
679
736
  description: "页码,从 1 开始,默认 1",
@@ -747,7 +804,7 @@ async function handleTool(name, input, client) {
747
804
  // ── Notes ──
748
805
  case "list_notes": {
749
806
  const cursor = input.cursor;
750
- return client.listNotes({ cursor: cursor === "0" ? undefined : cursor });
807
+ return client.listNotes({ ...input, cursor: cursor === "0" ? undefined : cursor });
751
808
  }
752
809
  case "get_note": {
753
810
  return client.getNote(snowflakeID(input.id, "id"), input.image_quality);
@@ -755,10 +812,31 @@ async function handleTool(name, input, client) {
755
812
  case "get_note_original": {
756
813
  const result = await client.getNote(snowflakeID(input.id, "id"));
757
814
  const note = result.note;
758
- const original = note.web_page?.content || note.audio?.original || note.content;
815
+ let original;
816
+ let original_source;
817
+ switch (note.note_type) {
818
+ case "ref":
819
+ original = note.ref_content;
820
+ original_source = "ref_content";
821
+ break;
822
+ case "plain_text":
823
+ original = note.content;
824
+ original_source = "content";
825
+ break;
826
+ case "link":
827
+ original = note.web_page?.content;
828
+ original_source = "web_page.content";
829
+ break;
830
+ case "audio":
831
+ case "local_audio":
832
+ original = note.audio?.original;
833
+ original_source = "audio.original";
834
+ break;
835
+ default: throw new Error(`Unsupported note type for original content: ${note.note_type}`);
836
+ }
759
837
  if (!original)
760
838
  throw new Error("Original content is not available for this note");
761
- return { id: note.id, note_type: note.note_type, title: note.title, original };
839
+ return { id: note.id, note_type: note.note_type, title: note.title, original, original_source };
762
840
  }
763
841
  case "get_note_transcript": {
764
842
  const result = await client.getNote(snowflakeID(input.id, "id"));
@@ -783,6 +861,12 @@ async function handleTool(name, input, client) {
783
861
  throw new Error("Quick note is not available for this note");
784
862
  return { id: result.note.id, title: result.note.title, quick_note: result.note.quick_note };
785
863
  }
864
+ case "get_note_chapters": {
865
+ const result = await client.getNote(snowflakeID(input.id, "id"));
866
+ if (!result.note.chapter_timeline)
867
+ throw new Error("Chapter timeline is not available for this note");
868
+ return { id: result.note.id, title: result.note.title, chapter_timeline: result.note.chapter_timeline };
869
+ }
786
870
  case "get_note_todos": {
787
871
  const result = await client.getNote(snowflakeID(input.id, "id"));
788
872
  return {
@@ -841,6 +925,7 @@ async function handleTool(name, input, client) {
841
925
  // ── Knowledge ──
842
926
  case "list_topics": {
843
927
  return client.listTopics({
928
+ ...input,
844
929
  page: input.page,
845
930
  scope: input.scope,
846
931
  });
@@ -854,6 +939,7 @@ async function handleTool(name, input, client) {
854
939
  }
855
940
  case "list_topic_notes": {
856
941
  return client.listTopicNotes({
942
+ ...input,
857
943
  topic_id: input.topic_id,
858
944
  page: input.page,
859
945
  });
@@ -884,6 +970,12 @@ async function handleTool(name, input, client) {
884
970
  });
885
971
  }
886
972
  // ── Image ──
973
+ case "get_note_marks": return client.getNoteMarks(String(snowflakeID(input.note_id, "note_id")));
974
+ case "list_sprouts": return client.listSprouts(zod_1.z.string().regex(/^\d{4}-\d{2}$/).parse(input.month), zod_1.z.string().optional().parse(input.since_id), zod_1.z.number().int().min(1).max(20).optional().parse(input.limit));
975
+ case "get_sprout": return client.getSprout(zod_1.z.string().min(1).parse(input.id));
976
+ case "get_knowledge_file_capabilities": return client.getKnowledgeFileCapabilities();
977
+ case "get_knowledge_file_upload_token": return client.getKnowledgeFileUploadToken(zod_1.z.string().min(1).parse(input.mime_type));
978
+ case "upload_knowledge_file": return client.uploadKnowledgeFile(zod_1.z.object({ topic_id: zod_1.z.string().min(1), directory_id: zod_1.z.string().regex(/^\d+$/), file_name: zod_1.z.string().min(1), file_type: zod_1.z.string().min(1), md5: zod_1.z.string().regex(/^[a-fA-F0-9]{32}$/), url: zod_1.z.string().url() }).strict().parse(input));
887
979
  case "get_upload_config": {
888
980
  return client.getUploadConfig();
889
981
  }
@@ -969,6 +1061,7 @@ async function handleTool(name, input, client) {
969
1061
  // ── Knowledge / Subscribe ──
970
1062
  case "list_subscribe_topics": {
971
1063
  return client.listSubscribeTopics({
1064
+ ...input,
972
1065
  page: input.page,
973
1066
  scope: input.scope,
974
1067
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getnote/mcp",
3
- "version": "1.7.2",
3
+ "version": "1.9.0",
4
4
  "description": "MCP server for 得到大脑(Get笔记) — manage notes and knowledge bases from AI assistants",
5
5
  "main": "dist/index.js",
6
6
  "bin": {
package/src/client.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import axios, { AxiosInstance, AxiosError } from "axios";
2
+ import { discoveryContract, verifyDiscovery, NoteDiscoveryOptions, LookupOptions, DiscoveryKind } from "./discovery";
2
3
 
3
4
  const DEFAULT_BASE_URL = "https://openapi.biji.com/open/api/v1";
4
5
 
@@ -21,12 +22,11 @@ function normalizeBaseURL(value?: string): string {
21
22
  */
22
23
  export function parseJsonPreservingLargeIntegerStrings(data: unknown) {
23
24
  if (typeof data !== "string" || data.trim() === "") return data;
25
+ // Match complete JSON strings first so numeric text inside note bodies is
26
+ // never rewritten. Consume full number tokens to preserve decimals/exponents.
24
27
  const safe = data.replace(
25
- /"(note_id|next_cursor|cursor|id|parent_id|topic_id|since_id|share_id|follow_id|live_id)"\s*:\s*(\d{16,})/g,
26
- '"$1":"$2"'
27
- ).replace(
28
- /([:[,]\s*)(-?\d{16,})(?=\s*[,}\]])/g,
29
- '$1"$2"'
28
+ /"(?:\\[\s\S]|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g,
29
+ token => /^-?\d{16,}$/.test(token) ? JSON.stringify(token) : token
30
30
  );
31
31
  return JSON.parse(safe);
32
32
  }
@@ -48,6 +48,24 @@ export class GetNoteAPIError extends Error {
48
48
  }
49
49
 
50
50
  export class GetNoteClient {
51
+ async getNoteMarks(note_id: string) {
52
+ return this.request<unknown>("GET", "/resource/note/marks", { note_id });
53
+ }
54
+ async listSprouts(month: string, since_id?: string, limit?: number) {
55
+ return this.request<unknown>("GET", "/resource/note/sprouts", { month, since_id, limit });
56
+ }
57
+ async getSprout(id: string) {
58
+ return this.request<unknown>("GET", "/resource/note/sprout", { id });
59
+ }
60
+ async getKnowledgeFileCapabilities() {
61
+ return this.request<unknown>("GET", "/resource/knowledge/file/capabilities");
62
+ }
63
+ async getKnowledgeFileUploadToken(mime_type: string) {
64
+ return this.request<unknown>("GET", "/resource/knowledge/file/upload_token", { mime_type });
65
+ }
66
+ async uploadKnowledgeFile(data: { topic_id: string; directory_id: string; file_name: string; file_type: string; md5: string; url: string }) {
67
+ return this.request<unknown>("POST", "/resource/knowledge/file/upload", undefined, data);
68
+ }
51
69
  private http: AxiosInstance;
52
70
 
53
71
  constructor(apiKey: string, clientId: string, baseURL?: string) {
@@ -76,10 +94,14 @@ export class GetNoteClient {
76
94
  params?: Record<string, unknown>,
77
95
  data?: unknown
78
96
  ): Promise<T> {
97
+ const kinds: Record<string, DiscoveryKind> = { "/resource/note/list": "notes", "/resource/note/detail": "detail", "/resource/knowledge/notes": "topicNotes", "/resource/knowledge/list": "topics", "/resource/knowledge/subscribe/list": "topics" };
98
+ const contract = method === "GET" && kinds[path] ? discoveryContract(kinds[path], params || {}) : undefined;
99
+ if (contract) params = contract.params;
79
100
  try {
80
101
  const res = await this.http.request<{
81
102
  success: boolean;
82
103
  data: T;
104
+ meta?: { capabilities?: string[]; [key: string]: unknown };
83
105
  error?: APIErrorBody;
84
106
  request_id?: string;
85
107
  }>({
@@ -104,6 +126,11 @@ export class GetNoteClient {
104
126
  );
105
127
  }
106
128
 
129
+ if (contract) verifyDiscovery(body, contract);
130
+ // Keep the verified envelope capabilities visible to the Agent.
131
+ if (body.meta?.capabilities && typeof body.data === "object" && body.data !== null && !Array.isArray(body.data)) {
132
+ return { ...body.data, meta: body.meta };
133
+ }
107
134
  return body.data;
108
135
  } catch (err) {
109
136
  if (err instanceof GetNoteAPIError) throw err;
@@ -135,10 +162,8 @@ export class GetNoteClient {
135
162
 
136
163
  // ─── Notes ───────────────────────────────────────────────────────────────
137
164
 
138
- async listNotes(params: { cursor?: string }) {
139
- return this.request<ListNotesResp>("GET", "/resource/note/list", {
140
- ...(params.cursor ? { cursor: params.cursor } : {}),
141
- });
165
+ async listNotes(params: NoteDiscoveryOptions) {
166
+ return this.request<ListNotesResp>("GET", "/resource/note/list", { ...params });
142
167
  }
143
168
 
144
169
  async getNote(id: string | number, image_quality?: string) {
@@ -271,9 +296,9 @@ export class GetNoteClient {
271
296
 
272
297
  // ─── Knowledge / Topics ─────────────────────────────────────────────────
273
298
 
274
- async listTopics(params?: { page?: number; scope?: KnowledgeScope }) {
299
+ async listTopics(params?: LookupOptions) {
275
300
  return this.request<ListTopicsResp>("GET", "/resource/knowledge/list", {
276
- page: params?.page,
301
+ ...params,
277
302
  scope: params?.scope ?? "DEFAULT",
278
303
  });
279
304
  }
@@ -287,11 +312,11 @@ export class GetNoteClient {
287
312
  );
288
313
  }
289
314
 
290
- async listTopicNotes(params: { topic_id: string; page?: number }) {
315
+ async listTopicNotes(params: NoteDiscoveryOptions & { topic_id: string }) {
291
316
  return this.request<ListTopicNotesResp>(
292
317
  "GET",
293
318
  "/resource/knowledge/notes",
294
- { topic_id: params.topic_id, page: params.page }
319
+ { ...params }
295
320
  );
296
321
  }
297
322
 
@@ -404,11 +429,11 @@ export class GetNoteClient {
404
429
  );
405
430
  }
406
431
 
407
- async listSubscribeTopics(params: { page?: number; scope?: KnowledgeScope }) {
432
+ async listSubscribeTopics(params: LookupOptions) {
408
433
  return this.request<ListSubscribeTopicsResp>(
409
434
  "GET",
410
435
  "/resource/knowledge/subscribe/list",
411
- { page: params.page, scope: params.scope ?? "DEFAULT" }
436
+ { ...params, scope: params.scope ?? "DEFAULT" }
412
437
  );
413
438
  }
414
439
 
@@ -437,21 +462,44 @@ export interface TagInfo {
437
462
  type: "ai" | "manual" | "system";
438
463
  }
439
464
 
440
- export interface NoteItem {
465
+ export interface NoteReference {
466
+ source: string; resource_type: string; ptype: number; resource_id?: string;
467
+ title?: string; author?: string; url?: string; original_note_id?: string;
468
+ is_source_private: boolean; book_id?: string;
469
+ article?: { title?: string; url?: string };
470
+ location?: { chapter_id?: string; chapter_name?: string; page?: number; start_offset?: number; end_offset?: number };
471
+ }
472
+ export interface BookInfo { book_id: string; title: string; author: string; platform?: string; source?: string; isbn?: string }
473
+ export interface DiscoveryMetadata {
474
+ display_title?: string;
475
+ reference?: NoteReference;
476
+ timestamps?: { created_at?: string; edited_at?: string; record_updated_at?: string };
477
+ preview?: { text: string; source: string; truncated: boolean };
478
+ content_state?: { content: string; ref_content: string };
479
+ metadata_state?: { reference: string; topics: string };
480
+ }
481
+ export interface DiscoveryResponse {
482
+ meta?: { capabilities: string[]; timestamp?: number };
483
+ pagination?: { mode: "page" | "cursor"; page: number | null; page_size: number; returned_count: number; total_count: number | null; has_more: boolean; next_page: number | null; next_cursor: string | null };
484
+ applied_filters?: Record<string, string>;
485
+ warnings?: unknown[];
486
+ }
487
+
488
+ export interface NoteItem extends DiscoveryMetadata {
441
489
  /**
442
490
  * Note ID. Returned as string because the actual values exceed
443
491
  * Number.MAX_SAFE_INTEGER. See parseJsonPreservingLargeIntegerStrings.
444
492
  */
445
493
  id: string;
446
494
  title: string;
447
- content: string;
495
+ content?: string;
448
496
  ref_content?: string;
449
497
  note_type: string;
450
498
  source: string;
451
499
  tags: TagInfo[];
452
500
  parent_id?: string;
453
501
  children_count?: number;
454
- topics?: { id: string; name: string }[];
502
+ topics?: { id: string; name: string; scope?: string; book_info?: BookInfo }[];
455
503
  is_child_note?: boolean;
456
504
  created_at: string;
457
505
  updated_at: string;
@@ -480,9 +528,14 @@ export interface NoteDetail extends NoteItem {
480
528
  content?: string;
481
529
  };
482
530
  quick_note?: string;
531
+ chapter_timeline?: {
532
+ source: string;
533
+ items: { start_ms: number; title: string }[];
534
+ };
483
535
  timeline?: {
484
536
  version: number;
485
- moments: { start_ms: number; end_ms: number; text: string }[];
537
+ schema_version?: number;
538
+ moments: { id?: string; type?: string; action_time?: number; content?: string; summary?: string; files?: { id: string; ext: string; name: string; url: string; size: number }[]; start_ms: number; end_ms: number; text: string }[];
486
539
  resources: { type: string; url: string; action_time: number }[];
487
540
  };
488
541
  meeting_todos?: {
@@ -493,7 +546,7 @@ export interface NoteDetail extends NoteItem {
493
546
  version?: number;
494
547
  }
495
548
 
496
- export interface ListNotesResp {
549
+ export interface ListNotesResp extends DiscoveryResponse {
497
550
  notes: NoteItem[];
498
551
  has_more: boolean;
499
552
  /**
@@ -506,7 +559,7 @@ export interface ListNotesResp {
506
559
  total: number;
507
560
  }
508
561
 
509
- export interface GetNoteResp {
562
+ export interface GetNoteResp extends DiscoveryResponse {
510
563
  note: NoteDetail;
511
564
  }
512
565
 
@@ -621,9 +674,11 @@ export interface KnowledgeTopic {
621
674
  stats?: KnowledgeTopicStats;
622
675
  created_at?: string;
623
676
  updated_at?: string;
677
+ topic_id?: string;
678
+ book_info?: BookInfo;
624
679
  }
625
680
 
626
- export interface ListTopicsResp {
681
+ export interface ListTopicsResp extends DiscoveryResponse {
627
682
  topics: KnowledgeTopic[];
628
683
  has_more: boolean;
629
684
  total: number;
@@ -637,10 +692,12 @@ export interface CreateTopicResp {
637
692
  scope?: string;
638
693
  }
639
694
 
640
- export interface TopicNoteItem {
695
+ export interface TopicNoteItem extends DiscoveryMetadata {
641
696
  note_id: string;
642
697
  title: string;
643
- content: string;
698
+ content?: string;
699
+ ref_content?: string;
700
+ note_url?: string;
644
701
  note_type: string;
645
702
  tags: string[];
646
703
  is_ai_generated?: boolean;
@@ -648,7 +705,7 @@ export interface TopicNoteItem {
648
705
  edit_time: string;
649
706
  }
650
707
 
651
- export interface ListTopicNotesResp {
708
+ export interface ListTopicNotesResp extends DiscoveryResponse {
652
709
  notes: TopicNoteItem[];
653
710
  has_more: boolean;
654
711
  total: number;
@@ -807,7 +864,7 @@ export interface ShareNoteResp {
807
864
 
808
865
  // ─── List Subscribe Topics Types ──────────────────────────────────────────────
809
866
 
810
- export interface ListSubscribeTopicsResp {
867
+ export interface ListSubscribeTopicsResp extends DiscoveryResponse {
811
868
  topics: KnowledgeTopic[];
812
869
  has_more: boolean;
813
870
  total: number;
@@ -841,14 +898,26 @@ export interface UpdateNoteResp {
841
898
  // ─── Recall / Search Types ───────────────────────────────────────────────────
842
899
 
843
900
  export interface RecallResultItem {
844
- note_id: string;
901
+ note_id?: string;
902
+ resource_id?: string;
845
903
  note_type: "NOTE" | "FILE" | "BLOGGER" | "LIVE" | "URL" | "DEDAO";
846
904
  title: string;
847
905
  content: string;
848
906
  created_at: string;
849
907
  page_no?: number;
908
+ resource_type?: string;
909
+ note?: NoteItem;
910
+ note_url?: string;
911
+ snippet?: string;
912
+ snippet_source?: string;
913
+ score?: number | null;
850
914
  }
851
915
 
852
- export interface RecallResp {
916
+ export interface RecallResp extends DiscoveryResponse {
853
917
  results: RecallResultItem[];
918
+ result_mode?: string;
919
+ is_exhaustive?: boolean;
920
+ returned_count?: number;
921
+ distinct_note_count?: number;
922
+ partial?: boolean;
854
923
  }