@dreamlake/dreamlake-cli 0.89.0 → 0.90.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,83 @@
1
+ import type { Transport } from './client.js';
2
+ import { readNoteEvents, type Participant } from './note-events.js';
3
+ export interface NoteLingerOptions {
4
+ signal: AbortSignal;
5
+ format?: 'diff' | 'inline-dff';
6
+ debounce?: string;
7
+ throttle?: string;
8
+ ifMatch?: string;
9
+ intent?: string;
10
+ }
11
+ export type NoteLingerEvent = ({
12
+ type: 'snapshot';
13
+ observedAt: number;
14
+ selectionHash: string;
15
+ participants: Participant[];
16
+ } & LingerRead) | {
17
+ type: 'update';
18
+ observedAt: number;
19
+ content?: LingerRead;
20
+ joined: Participant[];
21
+ left: Participant[];
22
+ activities: Activity[];
23
+ selections: (Participant & {
24
+ hash: string;
25
+ })[];
26
+ };
27
+ export declare const LINGER_BATCH_MS = 2000;
28
+ /** Durations are bounded to avoid accidental busy loops or effectively silent sessions. */
29
+ export declare function lingerDuration(value: string | undefined, option: string): number;
30
+ export interface Activity {
31
+ id: string;
32
+ agent: {
33
+ id: string;
34
+ name: string;
35
+ owner: string;
36
+ };
37
+ kind: "read" | "insert";
38
+ scope: string;
39
+ hash: string;
40
+ ranges: {
41
+ start: number;
42
+ end: number;
43
+ }[];
44
+ at: number;
45
+ expiresAt: number;
46
+ }
47
+ export interface LingerRead {
48
+ note: string;
49
+ hash: string;
50
+ revision: string;
51
+ content?: string;
52
+ base?: string;
53
+ patch?: string;
54
+ format?: string;
55
+ }
56
+ interface Observation {
57
+ body: LingerRead;
58
+ participants: Participant[];
59
+ activities: Activity[];
60
+ }
61
+ export interface LingerRuntime {
62
+ signal?: AbortSignal;
63
+ events?: typeof readNoteEvents;
64
+ now(): number;
65
+ wait(ms: number, signal: AbortSignal): Promise<void>;
66
+ }
67
+ /** Stable activity fingerprints suppress renewed read/typing observations each poll. */
68
+ export declare class LingerBatch {
69
+ private readonly self;
70
+ private participants;
71
+ private activity;
72
+ private selections;
73
+ constructor(initial: Observation, self: string);
74
+ others(rows: Participant[]): Participant[];
75
+ diff(next: Observation): {
76
+ joined: Participant[];
77
+ left: Participant[];
78
+ activities: Activity[];
79
+ selections: Participant[];
80
+ };
81
+ }
82
+ export declare function watchNote(t: Transport, path: string, id: string, opts: NoteLingerOptions, receive: (event: NoteLingerEvent) => void | Promise<void>, clock?: LingerRuntime): Promise<void>;
83
+ export {};
@@ -0,0 +1,270 @@
1
+ /** Shared event-driven Note collaboration engine. Owns a bounded presence lease; never writes Note content. */
2
+ import { createHash } from 'node:crypto';
3
+ import { setTimeout as delay } from 'node:timers/promises';
4
+ import { readNoteEvents } from './note-events.js';
5
+ import { notePresenceIntent as presenceIntent } from './note-presence.js';
6
+ export const LINGER_BATCH_MS = 2000;
7
+ /** Durations are bounded to avoid accidental busy loops or effectively silent sessions. */
8
+ export function lingerDuration(value, option) {
9
+ if (value === undefined)
10
+ return LINGER_BATCH_MS;
11
+ const match = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(value);
12
+ const ms = match ? Number(match[1]) * ({ ms: 1, s: 1000, m: 60000 }[match[2]] ?? 0) : NaN;
13
+ if (!Number.isFinite(ms) || ms < 250 || ms > 300000)
14
+ throw new Error(`${option} requires a duration from 250ms to 5m (for example 500ms or 2s)`);
15
+ return ms;
16
+ }
17
+ const HEARTBEAT_MS = 20_000;
18
+ const runtime = {
19
+ now: Date.now,
20
+ wait: async (ms, signal) => { await delay(ms, undefined, { signal }); },
21
+ };
22
+ /** Stable activity fingerprints suppress renewed read/typing observations each poll. */
23
+ export class LingerBatch {
24
+ self;
25
+ participants = new Map();
26
+ activity = new Map();
27
+ selections = new Map();
28
+ constructor(initial, self) {
29
+ this.self = self;
30
+ this.diff(initial);
31
+ }
32
+ others(rows) { return rows.filter(p => p.user.id !== this.self); }
33
+ diff(next) {
34
+ const current = new Map(this.others(next.participants).map(p => [p.client, p]));
35
+ const joined = [...current].filter(([id]) => !this.participants.has(id)).map(([, p]) => p);
36
+ const left = [...this.participants].filter(([id]) => !current.has(id)).map(([, p]) => p);
37
+ const selections = [...current.values()].flatMap(p => {
38
+ const fingerprint = JSON.stringify(p.selection ?? null);
39
+ const changed = this.selections.get(p.client) !== fingerprint;
40
+ this.selections.set(p.client, fingerprint);
41
+ return changed && (p.selection || this.participants.has(p.client)) ? [p] : [];
42
+ });
43
+ for (const p of left) {
44
+ this.selections.delete(p.client);
45
+ selections.push({ ...p, selection: null });
46
+ }
47
+ this.participants = current;
48
+ const seen = new Map();
49
+ const activities = next.activities.filter(a => {
50
+ if (`agent:${a.agent.owner}:${a.agent.id}` === this.self)
51
+ return false;
52
+ const key = `${a.agent.owner}:${a.agent.id}:${a.kind}`;
53
+ const fingerprint = JSON.stringify([a.hash, a.scope, a.ranges]);
54
+ seen.set(key, fingerprint);
55
+ return this.activity.get(key) !== fingerprint;
56
+ });
57
+ this.activity = seen;
58
+ return { joined, left, activities, selections };
59
+ }
60
+ }
61
+ export async function watchNote(t, path, id, opts, receive, clock = { ...runtime, signal: opts.signal }) {
62
+ const format = opts.format ?? 'diff';
63
+ if (!['diff', 'inline-dff'].includes(format))
64
+ throw new Error('--format must be diff or inline-dff');
65
+ if (opts.ifMatch !== undefined && (!opts.ifMatch.trim() || opts.ifMatch === '*' || /[\r\n]/.test(opts.ifMatch)))
66
+ throw new Error('--if-match requires an exact saved revision');
67
+ let debounce, throttle, intent;
68
+ try {
69
+ debounce = lingerDuration(opts.debounce, '--debounce');
70
+ throttle = lingerDuration(opts.throttle, '--throttle');
71
+ intent = presenceIntent(opts.intent);
72
+ }
73
+ catch (error) {
74
+ throw error;
75
+ }
76
+ const abort = new AbortController();
77
+ const stop = () => abort.abort();
78
+ clock.signal?.addEventListener('abort', stop, { once: true });
79
+ if (clock.signal?.aborted)
80
+ stop();
81
+ let leave;
82
+ let streaming;
83
+ let failure;
84
+ try {
85
+ if (abort.signal.aborted)
86
+ return;
87
+ const request = (suffix, extra = {}) => {
88
+ const { method, ...options } = extra;
89
+ return t.request(method ?? 'GET', path + suffix, {
90
+ signal: abort.signal, timeoutMs: 30000, redirect: 'error', ...options,
91
+ });
92
+ };
93
+ // Install cleanup before join: a lost join response may still have created a lease.
94
+ leave = () => t.request('POST', path + '/presence', {
95
+ json: { action: 'leave' }, timeoutMs: 5000, redirect: 'error',
96
+ });
97
+ // Intent rides the join only; heartbeats omit the field, which preserves it.
98
+ const joined = await request('/presence', { method: 'POST', json: { action: 'join', ...(intent ? { intent } : {}) } });
99
+ if (typeof joined?.state?.user?.id !== 'string')
100
+ throw new Error('server did not return an agent presence session');
101
+ const self = joined.state.user.id;
102
+ let heartbeat = clock.now();
103
+ let latest, sequence = 0, handled = -1, streamError;
104
+ let wake = new AbortController();
105
+ const wait = async (ms) => {
106
+ wake = new AbortController();
107
+ try {
108
+ await clock.wait(ms, AbortSignal.any([abort.signal, wake.signal]));
109
+ }
110
+ catch (error) {
111
+ if (!wake.signal.aborted && !abort.signal.aborted)
112
+ throw error;
113
+ }
114
+ };
115
+ streaming = (clock.events ?? readNoteEvents)(path + '/events', '', id, abort.signal, event => {
116
+ latest = event;
117
+ sequence++;
118
+ wake.abort();
119
+ }, async (_url, options) => {
120
+ if (!t.raw)
121
+ throw new Error('transport_does_not_support_streaming');
122
+ return t.raw('GET', path + '/events', { headers: options?.headers, signal: options?.signal, timeoutMs: null, redirect: 'error' });
123
+ }).then(() => {
124
+ if (!abort.signal.aborted)
125
+ streamError = new Error('Notes event stream disconnected');
126
+ wake.abort();
127
+ }, error => { streamError = error; wake.abort(); });
128
+ while (!latest && !streamError && !abort.signal.aborted)
129
+ await wait(45000);
130
+ if (abort.signal.aborted)
131
+ return;
132
+ if (streamError)
133
+ throw streamError;
134
+ const readBody = async (previous) => {
135
+ const query = new URLSearchParams({ contract: 'v2' });
136
+ if (previous) {
137
+ query.set('since', previous.hash);
138
+ query.set('format', format);
139
+ }
140
+ const body = await request('/body?' + query, { headers: !previous && opts.ifMatch ? { 'If-Match': opts.ifMatch } : {} });
141
+ if (body.note !== id || !/^sha256:[a-f0-9]{64}$/.test(body.hash ?? '') || typeof body.revision !== 'string' || !body.revision || /[\r\n]/.test(body.revision))
142
+ throw new Error('invalid Notes v2 snapshot');
143
+ if (!previous) {
144
+ if (typeof body.content !== 'string' || 'sha256:' + createHash('sha256').update(body.content).digest('hex') !== body.hash)
145
+ throw new Error('source does not match the returned hash');
146
+ if (opts.ifMatch && body.revision !== opts.ifMatch)
147
+ throw new Error('note changed since the acknowledged revision');
148
+ }
149
+ else if (body.base !== previous.hash || body.format !== format || typeof body.patch !== 'string') {
150
+ throw new Error('invalid incremental Notes v2 response');
151
+ }
152
+ return body;
153
+ };
154
+ const readActivities = async () => {
155
+ const feed = await request('/agent-activity');
156
+ if (!Array.isArray(feed?.activities))
157
+ throw new Error('server does not support activity reads');
158
+ return feed.activities;
159
+ };
160
+ const initialEvent = latest;
161
+ handled = sequence;
162
+ let initial = { body: await readBody(), participants: initialEvent.participants, activities: await readActivities() };
163
+ if (abort.signal.aborted)
164
+ return;
165
+ if (streamError)
166
+ throw streamError;
167
+ let previous = initial.body;
168
+ let observedActivities = initial.activities;
169
+ const batches = new LingerBatch(initial, self);
170
+ await receive({ type: 'snapshot', observedAt: clock.now(), ...initial.body, selectionHash: initialEvent.hash, participants: batches.others(initial.participants) });
171
+ // Release the full initial source rather than holding it through the entire session.
172
+ previous = { note: previous.note, hash: previous.hash, revision: previous.revision };
173
+ initial = undefined;
174
+ let observedHash = initialEvent.hash;
175
+ let activityVersion = initialEvent.activityVersion;
176
+ let lastEditAt = clock.now(), lastOutputAt = clock.now();
177
+ let dirtyContent = initialEvent.hash !== previous.hash;
178
+ const arrivals = new Map(), departures = new Map();
179
+ const activity = new Map();
180
+ const selections = new Map();
181
+ while (!abort.signal.aborted) {
182
+ if (streamError)
183
+ throw streamError;
184
+ if (sequence !== handled) {
185
+ handled = sequence;
186
+ const event = latest;
187
+ if (event.hash !== observedHash) {
188
+ observedHash = event.hash;
189
+ lastEditAt = clock.now();
190
+ dirtyContent = true;
191
+ }
192
+ if (event.activityVersion !== activityVersion)
193
+ observedActivities = await readActivities();
194
+ const delta = batches.diff({ body: previous, participants: event.participants, activities: observedActivities });
195
+ activityVersion = event.activityVersion;
196
+ for (const p of delta.joined) {
197
+ if (!departures.delete(p.client))
198
+ arrivals.set(p.client, p);
199
+ }
200
+ for (const p of delta.left) {
201
+ if (!arrivals.delete(p.client))
202
+ departures.set(p.client, p);
203
+ }
204
+ for (const p of delta.selections)
205
+ selections.set(p.client, p);
206
+ for (const a of delta.activities)
207
+ activity.set(`${a.agent.owner}:${a.agent.id}:${a.kind}`, a);
208
+ }
209
+ if (clock.now() - heartbeat >= HEARTBEAT_MS) {
210
+ await request('/presence', { method: 'POST', json: { action: 'heartbeat' } });
211
+ heartbeat = clock.now();
212
+ }
213
+ const now = clock.now();
214
+ const deliverContent = dirtyContent && now - lastEditAt >= debounce;
215
+ if (now - lastOutputAt >= throttle && (deliverContent || arrivals.size || departures.size || activity.size || selections.size)) {
216
+ const nextBody = deliverContent ? await readBody(previous) : undefined;
217
+ if (abort.signal.aborted)
218
+ break;
219
+ if (streamError)
220
+ throw streamError;
221
+ // A source event arriving during the read needs its own quiet period.
222
+ if (sequence !== handled && latest.hash !== observedHash)
223
+ continue;
224
+ const events = { joined: [...arrivals.values()], left: [...departures.values()], activities: [...activity.values()],
225
+ selections: [...selections.values()].map(p => ({ ...p, hash: observedHash })) };
226
+ await receive({ type: 'update', observedAt: clock.now(), ...(nextBody ? { content: nextBody } : {}), ...events });
227
+ lastOutputAt = clock.now();
228
+ arrivals.clear();
229
+ departures.clear();
230
+ activity.clear();
231
+ selections.clear();
232
+ if (nextBody) {
233
+ previous = { note: nextBody.note, hash: nextBody.hash, revision: nextBody.revision };
234
+ dirtyContent = false;
235
+ }
236
+ }
237
+ if (sequence !== handled)
238
+ continue;
239
+ const deadlines = [heartbeat + HEARTBEAT_MS];
240
+ if (arrivals.size || departures.size || activity.size || selections.size)
241
+ deadlines.push(lastOutputAt + throttle);
242
+ if (dirtyContent)
243
+ deadlines.push(Math.max(lastEditAt + debounce, lastOutputAt + throttle));
244
+ await wait(Math.max(1, Math.min(...deadlines) - clock.now()));
245
+ }
246
+ }
247
+ catch (error) {
248
+ if (!abort.signal.aborted) {
249
+ failure = error;
250
+ throw error;
251
+ }
252
+ }
253
+ finally {
254
+ abort.abort();
255
+ await streaming;
256
+ try {
257
+ if (leave)
258
+ await leave();
259
+ }
260
+ catch (error) {
261
+ if (failure instanceof Error)
262
+ Object.assign(failure, { cleanupError: error });
263
+ else
264
+ throw error;
265
+ }
266
+ finally {
267
+ clock.signal?.removeEventListener('abort', stop);
268
+ }
269
+ }
270
+ }
@@ -0,0 +1,82 @@
1
+ /** The CLI's Note roster, visit and hash-bound selection contracts. No implicit login or process state. */
2
+ import { type Transport, type RequestOptions } from './client.js';
3
+ import { type NoteEvent, type Participant } from './note-events.js';
4
+ export interface NoteRange {
5
+ start: number;
6
+ end: number;
7
+ }
8
+ export interface NotePresenceRoster {
9
+ participants: Participant[];
10
+ observedAt: number;
11
+ }
12
+ export interface NotePresenceReceipt {
13
+ state?: {
14
+ user?: Participant['user'];
15
+ expiresAt: number;
16
+ activity?: {
17
+ kind: string;
18
+ hash: string;
19
+ ranges: NoteRange[];
20
+ expiresAt: number;
21
+ };
22
+ };
23
+ [key: string]: unknown;
24
+ }
25
+ export interface NoteActivity {
26
+ id: string;
27
+ agent: {
28
+ id: string;
29
+ name: string;
30
+ owner: string;
31
+ };
32
+ kind: 'read' | 'insert';
33
+ scope: string;
34
+ hash: string;
35
+ ranges: NoteRange[];
36
+ at: number;
37
+ expiresAt: number;
38
+ }
39
+ export interface NoteSelectionOptions {
40
+ text: string;
41
+ section?: string;
42
+ occurrence?: number;
43
+ hash?: string;
44
+ }
45
+ export interface NoteSelectionReceipt {
46
+ note: string;
47
+ hash: string;
48
+ text: string;
49
+ scope: {
50
+ kind: 'note';
51
+ } | {
52
+ kind: 'section';
53
+ anchor: string;
54
+ };
55
+ range: NoteRange;
56
+ occurrence: number;
57
+ matches: number;
58
+ published: true;
59
+ selectionExpiresAt: number;
60
+ presenceExpiresAt: number;
61
+ }
62
+ export declare function notePresenceIntent(value: string | undefined): {
63
+ summary: string;
64
+ } | undefined;
65
+ export declare function notePresenceApi(t: Transport, base: string): {
66
+ /** No join or heartbeat. The optional input retains the former POST API for compatibility. */
67
+ presence: {
68
+ (id: string): Promise<NotePresenceRoster>;
69
+ /** @deprecated Use visit or updatePresence for explicit mutations. */
70
+ (id: string, input: Record<string, unknown>): Promise<NotePresenceReceipt>;
71
+ };
72
+ presenceText: (id: string) => Promise<string>;
73
+ updatePresence: (id: string, input: Record<string, unknown>, options?: RequestOptions) => Promise<NotePresenceReceipt>;
74
+ visit: (id: string, options?: {
75
+ intent?: string;
76
+ }) => Promise<NotePresenceReceipt>;
77
+ activity: (id: string, options?: RequestOptions) => Promise<{
78
+ activities: NoteActivity[];
79
+ }>;
80
+ events: (id: string, signal: AbortSignal, receive: (event: NoteEvent) => void) => Promise<void>;
81
+ selectText: (id: string, options: NoteSelectionOptions) => Promise<NoteSelectionReceipt>;
82
+ };
@@ -0,0 +1,72 @@
1
+ /** The CLI's Note roster, visit and hash-bound selection contracts. No implicit login or process state. */
2
+ import { ApiError, seg } from './client.js';
3
+ import { find } from './note-editing.js';
4
+ import { readNoteEvents } from './note-events.js';
5
+ export function notePresenceIntent(value) {
6
+ if (value === undefined)
7
+ return undefined;
8
+ const summary = value.trim();
9
+ if (!summary || Array.from(summary).length > 280)
10
+ throw new Error('--intent requires 1–280 characters of plain text (one short sentence of purpose)');
11
+ return { summary };
12
+ }
13
+ export function notePresenceApi(t, base) {
14
+ const path = (id) => `${base}/${seg(id)}`;
15
+ const updatePresence = (id, input, options = {}) => t.request('POST', path(id) + '/presence', { ...options, json: input });
16
+ const presence = (id, input) => input === undefined
17
+ ? t.request('GET', path(id) + '/presence', { query: { format: 'json' } })
18
+ : updatePresence(id, input);
19
+ return {
20
+ /** No join or heartbeat. The optional input retains the former POST API for compatibility. */
21
+ presence: presence,
22
+ presenceText: async (id) => {
23
+ if (!t.raw)
24
+ throw new Error('transport_does_not_support_streaming');
25
+ return (await t.raw('GET', path(id) + '/presence', { query: { format: 'text' }, redirect: 'error' })).text();
26
+ },
27
+ updatePresence,
28
+ visit: (id, options = {}) => {
29
+ const intent = notePresenceIntent(options.intent);
30
+ return updatePresence(id, { action: 'join', ...(intent ? { intent } : {}) });
31
+ },
32
+ activity: (id, options = {}) => t.request('GET', path(id) + '/agent-activity', options),
33
+ events: (id, signal, receive) => {
34
+ if (!t.raw)
35
+ throw new Error('transport_does_not_support_streaming');
36
+ return readNoteEvents(path(id) + '/events', '', id, signal, receive, async (_url, options) => t.raw('GET', path(id) + '/events', { headers: options?.headers, signal: options?.signal, timeoutMs: null, redirect: 'error' }));
37
+ },
38
+ selectText: async (id, options) => {
39
+ if (!options.text || options.section === '')
40
+ throw new Error('give nonempty text and an optional nonempty section anchor');
41
+ if (options.occurrence !== undefined && (!Number.isSafeInteger(options.occurrence) || options.occurrence === 0))
42
+ throw new Error('--occurrence (-o) must be a nonzero integer: 1 is first, -1 is last');
43
+ if (options.hash !== undefined && !/^sha256:[a-f0-9]{64}$/.test(options.hash))
44
+ throw new Error('--hash must be sha256: followed by 64 lowercase hex digits');
45
+ const snapshot = await t.request('GET', options.section !== undefined ? path(id) + '/sections/' + seg(options.section) : path(id) + '/body', { query: options.section === undefined ? { contract: 'v2' } : undefined, headers: { 'X-DreamLake-Agent-Id': '' } });
46
+ const source = options.section !== undefined ? snapshot.text : snapshot.content;
47
+ const offset = options.section !== undefined ? snapshot.range?.start : 0;
48
+ if (typeof source !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(snapshot.hash ?? '') || !Number.isSafeInteger(offset) || offset < 0 ||
49
+ (options.section !== undefined && snapshot.range?.end !== offset + Array.from(source).length))
50
+ throw new Error('server did not provide canonical source/hash and code-point range; section selection requires the updated Notes server');
51
+ if (options.hash !== undefined && options.hash !== snapshot.hash)
52
+ throw new ApiError(409, 'stale_range', { note: id });
53
+ const matches = find(source, options.text), requested = options.occurrence ?? 1;
54
+ const nth = requested < 0 ? matches.length + requested + 1 : requested;
55
+ if (!matches.length || nth < 1 || nth > matches.length)
56
+ throw new ApiError(422, 'note_selection_no_match', { matches: matches.length, occurrence: requested });
57
+ if (matches.length > 1 && options.occurrence === undefined)
58
+ throw new ApiError(422, 'note_selection_ambiguous', { matches: matches.length });
59
+ const match = matches[nth - 1], range = { start: offset + match.ind[0], end: offset + match.ind[1] };
60
+ const result = await updatePresence(id, { action: 'seek', hash: snapshot.hash, ranges: [range] });
61
+ const activity = result.state?.activity;
62
+ if (activity?.kind !== 'seeking' || activity.hash !== snapshot.hash || activity.ranges?.length !== 1 ||
63
+ activity.ranges[0].start !== range.start || activity.ranges[0].end !== range.end ||
64
+ !Number.isFinite(activity.expiresAt) || !Number.isFinite(result.state?.expiresAt))
65
+ throw new ApiError(503, 'note_selection_unconfirmed', { note: id, hash: snapshot.hash, range });
66
+ return { note: id, hash: snapshot.hash, text: match.text,
67
+ scope: options.section === undefined ? { kind: 'note' } : { kind: 'section', anchor: options.section },
68
+ range, occurrence: nth, matches: matches.length, published: true,
69
+ selectionExpiresAt: activity.expiresAt, presenceExpiresAt: result.state.expiresAt };
70
+ },
71
+ };
72
+ }
@@ -1,5 +1,6 @@
1
1
  import * as editing from "./note-editing.js";
2
- import type { JsonObject, Query } from "./common.js";
2
+ import { type NoteLingerOptions, type NoteLingerEvent } from "./note-linger.js";
3
+ import type { Query } from "./common.js";
3
4
  import { type NoteSource, type NoteEdit, type NotePatch } from "./note-edits.js";
4
5
  export { noteEdits, type NoteSource, type NoteEdit, type NotePatch, } from "./note-edits.js";
5
6
  import { type Transport } from "./client.js";
@@ -74,8 +75,25 @@ export interface WriteReceipt {
74
75
  sizeBytes: number;
75
76
  sections?: Section[];
76
77
  }
78
+ export interface NoteMediaReceipt {
79
+ url: string;
80
+ contentType: string;
81
+ sizeBytes: number;
82
+ }
77
83
  export declare function notesApi(t: Transport, namespace: string): {
84
+ linger: (noteId: string, options: NoteLingerOptions, receive: (event: NoteLingerEvent) => void | Promise<void>) => Promise<void>;
78
85
  namespace: string;
86
+ /** Resolve the same ID, exact slug or exact title accepted by the CLI in this namespace. */
87
+ resolve: (ref: string) => Promise<string>;
88
+ /** CSS inspection is read-only; selectText publishes a separate agent selection. */
89
+ selectElement: (noteId: string, css: string) => Promise<{
90
+ etag: string;
91
+ tag: string;
92
+ attrs: Record<string, string | null>;
93
+ outer: [number, number];
94
+ inner: [number, number];
95
+ text: string;
96
+ }>;
79
97
  source: (noteId: string, at?: string) => Promise<NoteSource>;
80
98
  patch: (noteId: string, input: NotePatch) => Promise<{
81
99
  note: string;
@@ -151,25 +169,24 @@ export declare function notesApi(t: Transport, namespace: string): {
151
169
  remove: (userId: string) => Promise<unknown>;
152
170
  };
153
171
  files: (noteId: string) => {
154
- download: (id: string, signal?: AbortSignal) => Promise<Response>;
155
- list: (query?: {
156
- prefix?: string;
157
- trash?: boolean;
158
- limit?: number;
159
- offset?: number;
160
- }) => Promise<{
161
- files: import("./note-files.js").NoteFile[];
162
- total: number;
163
- }>;
172
+ list: (query?: import("./note-files.js").NoteFileListOptions) => Promise<import("./note-files.js").NoteFilePage>;
164
173
  get: (id: string) => Promise<import("./note-files.js").NoteFile>;
165
- text: (id: string) => Promise<{
174
+ resolve: (ref: string, includeTrashed?: boolean) => Promise<import("./note-files.js").NoteFile>;
175
+ text: (ref: string) => Promise<{
166
176
  text: string;
167
177
  etag: string;
168
178
  }>;
169
- upload: (path: string, body: NonNullable<import("./client.js").RequestOptions["body"]>, options?: {
179
+ cat: (ref: string) => Promise<{
180
+ text: string;
181
+ etag: string;
182
+ }>;
183
+ download: (ref: string, signal?: AbortSignal) => Promise<Response>;
184
+ upload: (path: string, body: NonNullable<import("./client.js").RequestOptions["body"]> | import("stream").Readable, options?: {
170
185
  contentType?: string;
171
186
  overwrite?: boolean;
172
187
  ifMatch?: string;
188
+ contentLength?: number;
189
+ signal?: AbortSignal;
173
190
  }) => Promise<import("./note-files.js").NoteFile>;
174
191
  write: (input: {
175
192
  path: string;
@@ -179,39 +196,34 @@ export declare function notesApi(t: Transport, namespace: string): {
179
196
  }, options?: {
180
197
  ifMatch?: string;
181
198
  idempotencyKey?: string;
182
- }) => Promise<import("./note-files.js").NoteFile>;
183
- move: (id: string, path: string, options?: {
199
+ }) => Promise<import("./note-files.js").NoteFileWriteReceipt>;
200
+ move: (ref: string, path: string, options?: {
184
201
  overwrite?: boolean;
185
202
  ifMatch?: string;
186
203
  }) => Promise<import("./note-files.js").NoteFile>;
187
- copy: (id: string, path: string, options?: {
204
+ copy: (ref: string, path: string, options?: {
188
205
  overwrite?: boolean;
189
206
  idempotencyKey?: string;
190
- }) => Promise<import("./note-files.js").NoteFile>;
191
- operation: (operationId: string, action?: "status" | "reconcile" | "cancel") => Promise<{
192
- operationId: string;
193
- state: string;
194
- historicalResult: boolean;
195
- file?: import("./note-files.js").NoteFile;
196
- }>;
197
- delete: (id: string, options?: {
207
+ }) => Promise<import("./note-files.js").NoteFileWriteReceipt>;
208
+ operation: (operationId: string, action?: "status" | "reconcile" | "cancel") => Promise<import("./note-files.js").NoteFileOperationReceipt>;
209
+ status: (id: string) => Promise<import("./note-files.js").NoteFileOperationReceipt>;
210
+ reconcile: (id: string) => Promise<import("./note-files.js").NoteFileOperationReceipt>;
211
+ cancel: (id: string) => Promise<import("./note-files.js").NoteFileOperationReceipt>;
212
+ delete: (ref: string, options?: {
198
213
  purge?: boolean;
199
214
  ifMatch?: string;
200
215
  }) => Promise<{
201
216
  id: string;
202
217
  purged: boolean;
203
218
  }>;
204
- restore: (id: string, path?: string) => Promise<import("./note-files.js").NoteFile>;
205
- preview: (id: string, share?: boolean) => Promise<{
206
- [key: string]: unknown;
207
- url: string;
208
- }>;
209
- revokePreview: (id: string) => Promise<{
219
+ restore: (ref: string, path?: string) => Promise<import("./note-files.js").NoteFile>;
220
+ preview: (ref: string, share?: boolean) => Promise<import("./note-files.js").NoteFilePreview>;
221
+ revokePreview: (ref: string) => Promise<{
210
222
  id: string;
211
223
  shared: boolean;
212
224
  }>;
213
225
  };
214
- media: (form: FormData) => Promise<unknown>;
226
+ media: (form: FormData) => Promise<NoteMediaReceipt>;
215
227
  read: (noteId: string, query?: Query) => Promise<NoteReadResult>;
216
228
  html: (noteId: string, options?: {
217
229
  at?: string;
@@ -231,7 +243,6 @@ export declare function notesApi(t: Transport, namespace: string): {
231
243
  since?: string;
232
244
  format?: "diff" | "inline-dff";
233
245
  }) => Promise<unknown>;
234
- presence: (noteId: string, input: JsonObject) => Promise<unknown>;
235
246
  saveVersion: (noteId: string, input: {
236
247
  hash: string;
237
248
  tag?: string;
@@ -300,5 +311,19 @@ export declare function notesApi(t: Transport, namespace: string): {
300
311
  after?: string;
301
312
  }, ifMatch?: string) => Promise<WriteReceipt>;
302
313
  removeSection: (noteId: string, anchor: string, ifMatch?: string) => Promise<WriteReceipt>;
314
+ presence: {
315
+ (id: string): Promise<import("./note-presence.js").NotePresenceRoster>;
316
+ (id: string, input: Record<string, unknown>): Promise<import("./note-presence.js").NotePresenceReceipt>;
317
+ };
318
+ presenceText: (id: string) => Promise<string>;
319
+ updatePresence: (id: string, input: Record<string, unknown>, options?: import("./client.js").RequestOptions) => Promise<import("./note-presence.js").NotePresenceReceipt>;
320
+ visit: (id: string, options?: {
321
+ intent?: string;
322
+ }) => Promise<import("./note-presence.js").NotePresenceReceipt>;
323
+ activity: (id: string, options?: import("./client.js").RequestOptions) => Promise<{
324
+ activities: import("./note-presence.js").NoteActivity[];
325
+ }>;
326
+ events: (id: string, signal: AbortSignal, receive: (event: import("./note-events.js").NoteEvent) => void) => Promise<void>;
327
+ selectText: (id: string, options: import("./note-presence.js").NoteSelectionOptions) => Promise<import("./note-presence.js").NoteSelectionReceipt>;
303
328
  };
304
329
  export type NotesApi = ReturnType<typeof notesApi>;