@madewithremy/admin 0.1.57 → 0.1.59

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.
Files changed (87) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client.d.ts +199 -0
  4. package/dist/config.d.ts +8 -0
  5. package/dist/ctx.d.ts +36 -0
  6. package/dist/errors.d.ts +68 -0
  7. package/dist/http.d.ts +68 -0
  8. package/dist/index.d.ts +7 -9442
  9. package/dist/index.js +6 -14
  10. package/dist/index.js.map +7 -1
  11. package/dist/ops/agent.d.ts +44 -0
  12. package/dist/ops/analytics.d.ts +285 -0
  13. package/dist/ops/apps.d.ts +33 -0
  14. package/dist/ops/crashes.d.ts +86 -0
  15. package/dist/ops/cron.d.ts +40 -0
  16. package/dist/ops/data.d.ts +68 -0
  17. package/dist/ops/dataSourceConnectors.d.ts +80 -0
  18. package/dist/ops/dataSourceEvals.d.ts +208 -0
  19. package/dist/ops/dataSourceJobs.d.ts +141 -0
  20. package/dist/ops/dataSourceMappers.d.ts +125 -0
  21. package/dist/ops/dataSources.d.ts +654 -0
  22. package/dist/ops/db.d.ts +81 -0
  23. package/dist/ops/diagnostics.d.ts +42 -0
  24. package/dist/ops/domains.d.ts +250 -0
  25. package/dist/ops/email.d.ts +305 -0
  26. package/dist/ops/events.d.ts +56 -0
  27. package/dist/ops/feedback.d.ts +24 -0
  28. package/dist/ops/files.d.ts +166 -0
  29. package/dist/ops/infra.d.ts +163 -0
  30. package/dist/ops/issues.d.ts +160 -0
  31. package/dist/ops/jewels.d.ts +249 -0
  32. package/dist/ops/methods.d.ts +60 -0
  33. package/dist/ops/prerender.d.ts +74 -0
  34. package/dist/ops/previews.d.ts +52 -0
  35. package/dist/ops/qaRecordings.d.ts +68 -0
  36. package/dist/ops/releases.d.ts +193 -0
  37. package/dist/ops/requests.d.ts +73 -0
  38. package/dist/ops/secrets.d.ts +61 -0
  39. package/dist/ops/settings.d.ts +45 -0
  40. package/dist/ops/tasks.d.ts +47 -0
  41. package/dist/ops/usage.d.ts +40 -0
  42. package/dist/ops/users.d.ts +59 -0
  43. package/dist/ops/voice.d.ts +178 -0
  44. package/dist/output.d.ts +19 -0
  45. package/dist/parseJsonConfig.d.ts +41 -0
  46. package/dist/poll.d.ts +38 -0
  47. package/dist/prod.js +39 -55
  48. package/dist/runningMethod.d.ts +25 -0
  49. package/dist/sleep.d.ts +12 -0
  50. package/dist/types/agent.d.ts +95 -0
  51. package/dist/types/analytics.d.ts +225 -0
  52. package/dist/types/apps.d.ts +39 -0
  53. package/dist/types/crashes.d.ts +81 -0
  54. package/dist/types/cron.d.ts +68 -0
  55. package/dist/types/data.d.ts +38 -0
  56. package/dist/types/dataSourceConnectors.d.ts +59 -0
  57. package/dist/types/dataSourceEvals.d.ts +225 -0
  58. package/dist/types/dataSourceJobs.d.ts +283 -0
  59. package/dist/types/dataSourceMappers.d.ts +204 -0
  60. package/dist/types/dataSourceReaders.d.ts +102 -0
  61. package/dist/types/dataSources.d.ts +627 -0
  62. package/dist/types/db.d.ts +63 -0
  63. package/dist/types/diagnostics.d.ts +96 -0
  64. package/dist/types/domains.d.ts +277 -0
  65. package/dist/types/email.d.ts +400 -0
  66. package/dist/types/events.d.ts +54 -0
  67. package/dist/types/feedback.d.ts +11 -0
  68. package/dist/types/files.d.ts +150 -0
  69. package/dist/types/index.d.ts +37 -0
  70. package/dist/types/infra.d.ts +188 -0
  71. package/dist/types/issues.d.ts +106 -0
  72. package/dist/types/jewels.d.ts +336 -0
  73. package/dist/types/methods.d.ts +34 -0
  74. package/dist/types/prerender.d.ts +59 -0
  75. package/dist/types/previews.d.ts +39 -0
  76. package/dist/types/progress.d.ts +31 -0
  77. package/dist/types/qaRecordings.d.ts +51 -0
  78. package/dist/types/releases.d.ts +233 -0
  79. package/dist/types/requests.d.ts +114 -0
  80. package/dist/types/secrets.d.ts +42 -0
  81. package/dist/types/settings.d.ts +79 -0
  82. package/dist/types/tasks.d.ts +99 -0
  83. package/dist/types/usage.d.ts +29 -0
  84. package/dist/types/users.d.ts +61 -0
  85. package/dist/types/voice.d.ts +197 -0
  86. package/dist/upload.d.ts +11 -0
  87. package/package.json +7 -10
@@ -0,0 +1,654 @@
1
+ /**
2
+ * Data-sources operations: document ingestion, corpus search, pipeline
3
+ * configuration, and version management.
4
+ *
5
+ * Ops are pure (ctx, params) → typed result; no printing, no process coupling.
6
+ * The CLI skin in commands/dataSources.ts owns everything flag-shaped (path
7
+ * resolution, parseKeyValuePairs, configFromFlags, out/progress calls,
8
+ * process.exit for wait-path exit codes).
9
+ */
10
+ import type { AdminContext } from '../ctx.js';
11
+ import type { DataSourcesBuildProgress, DataSourcesConfigResult, DataSourcesConfigUpdateResult, DataSourcesCreateResult, DataSourcesDeleteResult, DataSourcesDocument, DataSourcesDocumentDeleteManyResult, DataSourcesDocumentDeleteResult, DataSourcesDocumentSelector, DataSourcesDocumentsResult, DataSourcesDocumentStatus, DataSourcesDropResult, DataSourcesIngestUpdate, DataSourcesListEntry, DataSourcesListResult, DataSourcesMoveResult, DataSourcesPromoteResult, DataSourcesRetrievalUpdate, DataSourcesRevectorizeResult, DataSourcesSearchResult, DataSourcesCountResult, DataSourcesDictionaryPushResult, DataSourcesDictionaryStatus, DataSourcesLinkResult, DataSourcesEntitiesResult, DataSourcesPassagesResult } from '../types/dataSources.js';
12
+ import type { DataSourceJob } from '../types/dataSourceJobs.js';
13
+ /** @internal Consumed by the CLI skin; waitForIngest documents the default. */
14
+ export declare const DEFAULT_WAIT_TIMEOUT_MS: number;
15
+ /**
16
+ * The per-document summary projection used by waitForIngest, status, and the
17
+ * revectorize watch loop in the skin. Exported so the skin can reuse it for
18
+ * the revectorize path without re-implementing it.
19
+ * @internal Presentation helper for the CLI skin, not client surface.
20
+ */
21
+ export declare const summarize: (d: DataSourcesDocumentStatus) => {
22
+ id: string;
23
+ filename: string | null;
24
+ status: string;
25
+ chunks: number | null;
26
+ pages: number | null;
27
+ error?: string | undefined;
28
+ };
29
+ export interface AddDocumentParams {
30
+ /** Data source slug. Created on first use. */
31
+ slug: string;
32
+ /** Original filename — used as the key and for MIME-type inference. */
33
+ filename: string;
34
+ /** File bytes to upload. */
35
+ content: Buffer;
36
+ /**
37
+ * Scalar tags filterable at search time (≤ 16 keys,
38
+ * `string | number | boolean` values).
39
+ */
40
+ metadata?: Record<string, string | number | boolean>;
41
+ /**
42
+ * What the document is about, as the app's own ids (≤ 256, printable ASCII,
43
+ * no whitespace or commas). Every passage carries them; `[]` clears them.
44
+ */
45
+ entities?: string[];
46
+ /**
47
+ * The budget in dollars of the job that takes the rest of a file mapping
48
+ * to more than a thousand documents (`AddDocumentResult.job`).
49
+ */
50
+ budgetDollars?: number;
51
+ /**
52
+ * Receives the exact progress strings the CLI prints today:
53
+ * - `${filename}: unchanged, skipped`
54
+ * - `${filename}: uploading N MB…`
55
+ */
56
+ onProgress?: (message: string) => void;
57
+ }
58
+ export interface AddDocumentResult {
59
+ filename: string;
60
+ skipped: boolean;
61
+ queued?: boolean;
62
+ /**
63
+ * The document, or the first of them on a mapped source. Null only when the
64
+ * source's mapper answered `deletes` for the file.
65
+ */
66
+ document: DataSourcesDocument | null;
67
+ /**
68
+ * Every document the file became — one on an unmapped source — or the
69
+ * first thousand of a file that maps to more.
70
+ */
71
+ documents: DataSourcesDocument[];
72
+ /** How many documents the file maps to in all. */
73
+ documentCount: number;
74
+ /** How the source took the file; absent when it was already current. */
75
+ outcome?: 'unmapped' | 'documents' | 'passthrough' | 'deletes';
76
+ /** Documents the mapper produced that failed validation and were not registered. */
77
+ invalid?: {
78
+ count: number;
79
+ examples: {
80
+ document: number;
81
+ reason: string;
82
+ }[];
83
+ } | null;
84
+ /**
85
+ * The job registering and building the rest of a file that maps to more
86
+ * than a thousand documents; it plans and starts on its own.
87
+ */
88
+ job?: DataSourceJob | null;
89
+ }
90
+ /**
91
+ * Add one document to a data source.
92
+ *
93
+ * Three-step flow: hash → token → (skip-if-current) → upload → confirm.
94
+ * Re-adding an unchanged file short-circuits at the token step and moves no
95
+ * bytes. Re-adding with different `metadata` updates the tags in-place, also
96
+ * without a re-upload. The data source is created on first use.
97
+ *
98
+ * @throws AdminApiError `invalid_content_hash` (400) — malformed hash
99
+ * (internal; `addDocument` computes this from `content`).
100
+ * @throws AdminApiError `document_limit_reached` (422) — the source holds the
101
+ * app's limit of documents (`documentLimit` in `list`); support raises it.
102
+ * @example
103
+ * const result = await admin.dataSources.addDocument({
104
+ * slug: 'policies',
105
+ * filename: 'contract.pdf',
106
+ * content: pdfBuffer,
107
+ * metadata: { department: 'legal', year: 2026 },
108
+ * });
109
+ */
110
+ export declare function addDocument(ctx: AdminContext, params: AddDocumentParams): Promise<AddDocumentResult>;
111
+ export interface WaitForIngestParams {
112
+ slug: string;
113
+ documentIds: string[];
114
+ /** How long without movement before giving up. Defaults to DEFAULT_WAIT_TIMEOUT_MS (15 min). */
115
+ timeoutMs?: number;
116
+ /**
117
+ * Receives the exact progress strings the CLI prints today:
118
+ * `ingesting… X/Y done (Ns)`
119
+ */
120
+ onProgress?: (message: string) => void;
121
+ }
122
+ export type SummarizedDocument = ReturnType<typeof summarize>;
123
+ export interface WaitForIngestResult {
124
+ status: 'up-to-date' | 'done' | 'error' | 'timeout';
125
+ documents: SummarizedDocument[];
126
+ /** Present only on status === 'timeout'. */
127
+ error?: string;
128
+ }
129
+ /**
130
+ * Poll until every queued document reaches a terminal state.
131
+ *
132
+ * Terminal states: `done` (all succeeded), `error` (at least one failed),
133
+ * `timeout` (still processing after `timeoutMs`, default 15 minutes). Polls
134
+ * every 3 seconds. Returns a typed result so the caller can branch on
135
+ * `status` without parsing strings.
136
+ *
137
+ * The `dataSource: slug` envelope and exit-code handling stay in the CLI skin
138
+ * so the printed JSON is byte-identical to the pre-refactor CLI.
139
+ *
140
+ * @example
141
+ * const result = await admin.dataSources.waitForIngest({
142
+ * slug: 'policies',
143
+ * documentIds: [doc.id],
144
+ * onProgress: console.error,
145
+ * });
146
+ * if (result.status === 'error') { ... }
147
+ */
148
+ export declare function waitForIngest(ctx: AdminContext, params: WaitForIngestParams): Promise<WaitForIngestResult>;
149
+ export interface WaitForCandidateParams {
150
+ slug: string;
151
+ /** How long without movement before giving up. Defaults to DEFAULT_WAIT_TIMEOUT_MS (15 min). */
152
+ timeoutMs?: number;
153
+ /** Receives `rebuilding… X/Y done (Ns)`. */
154
+ onProgress?: (message: string) => void;
155
+ }
156
+ export interface WaitForCandidateResult {
157
+ status: 'ready' | 'error' | 'timeout';
158
+ /** The candidate's build counts when the wait ended; null when it had no candidate. */
159
+ counts: DataSourcesBuildProgress | null;
160
+ /** The failed documents, first page, when any failed. */
161
+ documents: SummarizedDocument[];
162
+ /** Present only on status === 'timeout'. */
163
+ error?: string;
164
+ }
165
+ /** Failed documents fetched for a status or a candidate wait. */
166
+ export declare const FAILURES_PAGE = 50;
167
+ /**
168
+ * Poll a candidate version (`revectorize`) until every document has built.
169
+ * Reads the candidate's counts from the source list — one row, whatever the
170
+ * corpus holds — and fetches the failures only at the end. `error` means at
171
+ * least one failed; `promote` with `force` accepts that.
172
+ */
173
+ export declare function waitForCandidate(ctx: AdminContext, params: WaitForCandidateParams): Promise<WaitForCandidateResult>;
174
+ export interface DocumentsParams {
175
+ /** Data source slug. */
176
+ slug: string;
177
+ /** true → watch a candidate pipeline (revectorize in progress). */
178
+ candidate?: boolean;
179
+ /** Only these documents (at most DOCUMENTS_IDS_MAX per request). */
180
+ ids?: string[];
181
+ /** Page size, 1..1000 (server default 500). */
182
+ limit?: number;
183
+ /** `nextCursor` from the previous page. */
184
+ cursor?: string;
185
+ /** By the time the document was added; oldest first unless said otherwise. */
186
+ order?: 'oldest' | 'newest';
187
+ /** The failed builds only, newest failure first. */
188
+ status?: 'error';
189
+ /** Filenames starting with this. */
190
+ filename?: string;
191
+ }
192
+ /** The server's cap on `ids` per request; `allDocuments` chunks to it. */
193
+ export declare const DOCUMENTS_IDS_MAX = 200;
194
+ /**
195
+ * Fetch one page of per-document ingest state for one pipeline, oldest first
196
+ * unless `order` says otherwise; `status: 'error'` narrows to the failures and
197
+ * `filename` to a name prefix.
198
+ *
199
+ * Returns an empty document list when the data source does not exist yet.
200
+ * Pass `candidate: true` to watch a revectorization in progress. Follow
201
+ * `nextCursor` for the next page, or use `allDocuments` to walk them all.
202
+ *
203
+ * @example
204
+ * const { documents, nextCursor } = await admin.dataSources.documents({ slug: 'policies' });
205
+ * const failed = await admin.dataSources.documents({ slug: 'policies', status: 'error' });
206
+ */
207
+ export declare function documents(ctx: AdminContext, params: DocumentsParams): Promise<DataSourcesDocumentsResult>;
208
+ /**
209
+ * Every document (or every one of `ids`), following pages to the end.
210
+ *
211
+ * With `ids`, requests are chunked to the server's per-request cap, so a wait
212
+ * over hundreds of just-added files stays a handful of small calls rather than
213
+ * a walk of the whole source.
214
+ *
215
+ * @example
216
+ * const docs = await admin.dataSources.allDocuments({ slug: 'policies' });
217
+ */
218
+ export declare function allDocuments(ctx: AdminContext, params: Omit<DocumentsParams, 'cursor' | 'limit'>): Promise<DataSourcesDocumentStatus[]>;
219
+ /**
220
+ * List all data sources with document counts, the most documents each may
221
+ * hold (`documentLimit`, null when unlimited), build progress, and active
222
+ * version metadata.
223
+ *
224
+ * @example
225
+ * const { dataSources } = await admin.dataSources.list();
226
+ */
227
+ export declare function list(ctx: AdminContext): Promise<DataSourcesListResult>;
228
+ export interface SearchParams {
229
+ /** Data source slug. */
230
+ slug: string;
231
+ /** Natural-language or keyword query. */
232
+ query: string;
233
+ /** Results to return (default 5, max 50). */
234
+ topK?: number;
235
+ /** 'hybrid' (default) | 'semantic' | 'lexical'. */
236
+ mode?: string;
237
+ /** Metadata equality filter or the full filter grammar as a plain object. */
238
+ filter?: Record<string, unknown>;
239
+ /** Cap hits per document; backfills from others. */
240
+ maxPerDocument?: number;
241
+ /** Return query-term offsets per hit. */
242
+ highlight?: boolean;
243
+ /** Search the candidate version instead of the live one. */
244
+ candidate?: boolean;
245
+ /** Assembled from triState(a, 'rerank'/'hybrid') in the skin. */
246
+ retrieval?: Record<string, boolean>;
247
+ }
248
+ /**
249
+ * Query a data source and return ranked passages with citations.
250
+ *
251
+ * `mode` in the response reports what actually ran (e.g. `reranked: false`
252
+ * after an adaptive skip) rather than what was requested, so measurements
253
+ * attribute numbers to the right path. Pass `candidate: true` to evaluate a
254
+ * candidate pipeline before promoting it.
255
+ *
256
+ * @throws AdminApiError `no_candidate_pipeline` (404) — `candidate: true` but
257
+ * no revectorization is in flight; `invalid_query` (400); `invalid_mode`
258
+ * (400).
259
+ * @example
260
+ * const { results } = await admin.dataSources.search({
261
+ * slug: 'policies',
262
+ * query: 'what are the payment terms?',
263
+ * });
264
+ */
265
+ export declare function search(ctx: AdminContext, params: SearchParams): Promise<DataSourcesSearchResult>;
266
+ export interface CountParams {
267
+ /** Data source slug. */
268
+ slug: string;
269
+ /** Same grammar as search's filter; absent counts the whole corpus. */
270
+ filter?: Record<string, unknown>;
271
+ /** Count the candidate version instead of the live one. */
272
+ candidate?: boolean;
273
+ }
274
+ /**
275
+ * How many chunks match a filter — exact, over the whole corpus.
276
+ *
277
+ * `count({ slug, filter: { contains: query } })` is how many passages contain
278
+ * all the query's words: the honest figure to show beside a search's hits.
279
+ * Not a relevance count (none exists) and not the set `search` returns.
280
+ *
281
+ * @throws AdminApiError `invalid_filter` (400); `no_candidate_pipeline` (404)
282
+ * with `candidate: true` and no revectorization in flight; `index_warming` /
283
+ * `index_building` (503) while the corpus is loading or building.
284
+ * @example
285
+ * const { chunks } = await admin.dataSources.count({ slug: 'policies', filter: { contains: 'notice period' } });
286
+ */
287
+ export declare function count(ctx: AdminContext, params: CountParams): Promise<DataSourcesCountResult>;
288
+ export interface EntitiesParams {
289
+ /** Data source slug. */
290
+ slug: string;
291
+ /** Same grammar as search's filter; absent covers the whole corpus. */
292
+ filter?: Record<string, unknown>;
293
+ /** Entities to return, most first (default 20, at most 1,000). */
294
+ limit?: number;
295
+ /** Read the candidate version instead of the live one. */
296
+ candidate?: boolean;
297
+ }
298
+ /**
299
+ * Which entities the passages matching a filter are about, most first.
300
+ *
301
+ * Filtered on one entity, it answers what appears beside it: a co-mention
302
+ * graph. `chunks` counts passages carrying each id, not documents, and is
303
+ * approximate.
304
+ *
305
+ * @throws AdminApiError `invalid_filter` (400); `no_candidate_pipeline` (404)
306
+ * with `candidate: true` and no revectorization in flight; `index_warming` /
307
+ * `index_building` (503) while the corpus is loading or building.
308
+ * @example
309
+ * const { entities } = await admin.dataSources.entities({ slug: 'manuals', filter: { entities: ['P-101A'] } });
310
+ */
311
+ export declare function entities(ctx: AdminContext, params: EntitiesParams): Promise<DataSourcesEntitiesResult>;
312
+ export interface PassagesParams {
313
+ /** Data source slug. */
314
+ slug: string;
315
+ /** Same grammar as search's filter; absent lists the whole corpus. */
316
+ filter?: Record<string, unknown>;
317
+ /** The previous page's `nextCursor`. */
318
+ cursor?: string;
319
+ /** Passages per page (default 50, at most 200). */
320
+ limit?: number;
321
+ /** Read the candidate version instead of the live one. */
322
+ candidate?: boolean;
323
+ }
324
+ /**
325
+ * One page of every passage matching a filter, unranked: all the pages that
326
+ * mention an entity, rather than search's best few. Passages come document by
327
+ * document, each document's in order.
328
+ *
329
+ * @throws AdminApiError `invalid_filter` (400); `invalid_cursor` (400);
330
+ * `no_candidate_pipeline` (404); `index_warming` / `index_building` (503).
331
+ * @example
332
+ * const { passages, nextCursor } = await admin.dataSources.passages({ slug: 'manuals', filter: { entities: ['P-1004A'] } });
333
+ */
334
+ export declare function passages(ctx: AdminContext, params: PassagesParams): Promise<DataSourcesPassagesResult>;
335
+ /**
336
+ * Read the full pipeline configuration for one data source.
337
+ *
338
+ * Returns `ingest` (pinned — requires a revectorize to change) and
339
+ * `retrieval` (live — takes effect on the next query, no rebuild needed).
340
+ *
341
+ * @throws AdminApiError `data_source_not_found` (404).
342
+ * @example
343
+ * const { ingest, retrieval } = await admin.dataSources.configGet('policies');
344
+ */
345
+ export declare function configGet(ctx: AdminContext, slug: string): Promise<DataSourcesConfigResult>;
346
+ export interface ConfigSetParams {
347
+ /** Data source slug. */
348
+ slug: string;
349
+ /**
350
+ * Ingest settings (pinned). Changes are rejected on a populated source —
351
+ * use `revectorize` instead to rebuild alongside the live one.
352
+ */
353
+ ingest?: DataSourcesIngestUpdate;
354
+ /**
355
+ * Retrieval settings (live). Take effect on the next query; no rebuild
356
+ * required.
357
+ */
358
+ retrieval?: DataSourcesRetrievalUpdate;
359
+ /**
360
+ * Where the corpus lives: a dedicated resource (see `admin.infra`) or the
361
+ * shared pool. An empty source moves on the spot; a populated one starts a
362
+ * background move (see `move`) and the response carries its `migration`.
363
+ */
364
+ placement?: {
365
+ resourceId: string;
366
+ } | 'shared';
367
+ }
368
+ /**
369
+ * Update pipeline configuration.
370
+ *
371
+ * `retrieval` changes take effect on the next query at no cost. `ingest`
372
+ * changes are rejected once the source has documents — use `revectorize`
373
+ * instead, which builds a new version alongside the live one so search never
374
+ * degrades.
375
+ *
376
+ * @throws AdminApiError `data_source_not_found` (404),
377
+ * `data_source_migrating` (422) while a move is in flight.
378
+ * @example
379
+ * await admin.dataSources.configSet({
380
+ * slug: 'policies',
381
+ * retrieval: { rerank: { enabled: true } },
382
+ * });
383
+ */
384
+ export declare function configSet(ctx: AdminContext, params: ConfigSetParams): Promise<DataSourcesConfigUpdateResult>;
385
+ export interface CreateParams {
386
+ /** Data source slug: lowercase [a-z0-9_-], up to 64 characters. */
387
+ slug: string;
388
+ /** Display name. */
389
+ name?: string;
390
+ /** Pinned ingest settings for the new pipeline; platform defaults otherwise. */
391
+ ingest?: DataSourcesIngestUpdate;
392
+ /**
393
+ * Where the corpus lives from the start: a dedicated resource (see
394
+ * `admin.infra`) or the shared pool (the default).
395
+ */
396
+ placement?: {
397
+ resourceId: string;
398
+ } | 'shared';
399
+ }
400
+ /**
401
+ * Create an empty data source, optionally on dedicated capacity.
402
+ *
403
+ * The one-step way to start a corpus on a resource. `add` also creates a
404
+ * source on first use, but on the shared pool. Calling this for a source that
405
+ * already exists returns it; a placement given then follows `configSet`'s
406
+ * rule — an empty source moves on the spot, a populated one starts a move.
407
+ *
408
+ * @throws AdminApiError `invalid_data_source` (400), `data_source_limit` (422),
409
+ * `resource_not_found` (404), `resource_destroyed` (422),
410
+ * `data_source_migrating` (422), `capacity_exceeded` (422).
411
+ * @example
412
+ * await admin.dataSources.create({ slug: 'archive', placement: { resourceId } });
413
+ */
414
+ export declare function create(ctx: AdminContext, params: CreateParams): Promise<DataSourcesCreateResult>;
415
+ export interface MoveParams {
416
+ /** Data source slug. */
417
+ slug: string;
418
+ /** A dedicated resource (see `admin.infra`) or the shared pool. */
419
+ placement: {
420
+ resourceId: string;
421
+ } | 'shared';
422
+ /**
423
+ * Start the copy over instead of resuming a move already under way to the
424
+ * same target: fresh chains cut at the target's current count, progress so
425
+ * far discarded (points already copied are written again, harmlessly).
426
+ */
427
+ restart?: boolean;
428
+ /**
429
+ * Parallel chains to copy with, instead of the target size's default (XL 32,
430
+ * Large 16, Medium 8, Small 4; max 128). The platform runs four chains per
431
+ * worker, so this is the worker count times four. Takes effect when the
432
+ * copy's windows are cut: with a move already under way, pair it with
433
+ * `restart`.
434
+ */
435
+ chains?: number;
436
+ }
437
+ /**
438
+ * Halt a move under way. Its chains stop at their next checkpoint and the
439
+ * record reads `error: "Stopped by operator."`; a plain `move` to the same
440
+ * target resumes from the chains' cursors.
441
+ *
442
+ * @throws AdminApiError `data_source_not_found` (404), `no_move_in_flight`
443
+ * (422) when nothing is being moved.
444
+ * @example
445
+ * await admin.dataSources.stopMove({ slug: 'archive' });
446
+ */
447
+ export declare function stopMove(ctx: AdminContext, params: {
448
+ slug: string;
449
+ }): Promise<DataSourcesMoveResult>;
450
+ /**
451
+ * Move a data source between placements: shared → dedicated, dedicated →
452
+ * shared, or one resource to another.
453
+ *
454
+ * A populated source is copied onto the target in the background from its
455
+ * stored vectors — nothing is re-extracted or re-embedded — and flips when the
456
+ * copy lands. Search keeps serving from the old placement meanwhile. Adding,
457
+ * removing or reconfiguring documents is refused with `data_source_migrating`
458
+ * until it finishes; `waitForMove` blocks on that. Moving to `'shared'` is how
459
+ * a source leaves a resource that is about to be destroyed.
460
+ *
461
+ * @throws AdminApiError `data_source_not_found` (404), `same_placement` (400),
462
+ * `data_source_busy` (422) while documents are still building or a
463
+ * candidate version exists, `data_source_migrating` (422), `capacity_<phase>`
464
+ * (422) when the target resource is not active, `capacity_exceeded` (422)
465
+ * when the target is too small, `resource_not_found` (404).
466
+ * @example
467
+ * await admin.dataSources.move({ slug: 'archive', placement: { resourceId } });
468
+ * const result = await admin.dataSources.waitForMove({ slug: 'archive' });
469
+ */
470
+ export declare function move(ctx: AdminContext, params: MoveParams): Promise<DataSourcesMoveResult>;
471
+ export interface WaitForMoveParams {
472
+ slug: string;
473
+ /** How long without movement before giving up. Defaults to DEFAULT_WAIT_TIMEOUT_MS (15 min). */
474
+ timeoutMs?: number;
475
+ /** Receives `copying… X/Y documents · N/min · about M min left (Ns)`. */
476
+ onProgress?: (message: string) => void;
477
+ }
478
+ export type WaitForMoveResult = {
479
+ status: 'done';
480
+ source: DataSourcesListEntry;
481
+ } | {
482
+ status: 'failed';
483
+ source: DataSourcesListEntry;
484
+ error: string;
485
+ } | {
486
+ status: 'timeout';
487
+ source: DataSourcesListEntry;
488
+ error: string;
489
+ };
490
+ /**
491
+ * Poll until a source's move has landed, failed, or the timeout elapses.
492
+ *
493
+ * Reads the source from `list` each poll; done when no move is in flight. A
494
+ * failed move returns immediately with the platform's error.
495
+ *
496
+ * @throws AdminApiError `data_source_not_found` (404).
497
+ */
498
+ export declare function waitForMove(ctx: AdminContext, params: WaitForMoveParams): Promise<WaitForMoveResult>;
499
+ export interface RevectorizeParams {
500
+ /** Data source slug. */
501
+ slug: string;
502
+ /** Ingest settings for the new version. Omit to adopt platform defaults. */
503
+ ingest?: DataSourcesIngestUpdate;
504
+ }
505
+ /**
506
+ * Start a new candidate pipeline alongside the live one.
507
+ *
508
+ * Builds a new version with the supplied settings, or platform defaults when
509
+ * none are given (the upgrade path for a source pinned to an older chunker).
510
+ * Search keeps serving the active version throughout. Reuses stored
511
+ * extractions, so changing chunking never re-runs document extraction — only
512
+ * re-chunking and re-embedding. Call `promote` to cut over.
513
+ *
514
+ * @throws AdminApiError `data_source_not_found` (404).
515
+ * @example
516
+ * const { candidateVersion } = await admin.dataSources.revectorize({
517
+ * slug: 'policies',
518
+ * ingest: { chunking: { maxChars: 900 } },
519
+ * });
520
+ */
521
+ export declare function revectorize(ctx: AdminContext, params: RevectorizeParams): Promise<DataSourcesRevectorizeResult>;
522
+ export interface PromoteParams {
523
+ /** Data source slug. */
524
+ slug: string;
525
+ /** Promote even if some candidate documents failed. */
526
+ force?: boolean;
527
+ }
528
+ /**
529
+ * Make the candidate pipeline version live.
530
+ *
531
+ * Atomically swaps the candidate for the active version and retires the old
532
+ * one. Without `force`, promotion is blocked when any candidate document
533
+ * failed. The retired version is kept; discard it with `drop` once rollback
534
+ * is no longer wanted.
535
+ *
536
+ * @throws AdminApiError `data_source_not_found` (404).
537
+ * @example
538
+ * const { activeVersion } = await admin.dataSources.promote({ slug: 'policies' });
539
+ */
540
+ export declare function promote(ctx: AdminContext, params: PromoteParams): Promise<DataSourcesPromoteResult>;
541
+ export interface DropParams {
542
+ /** Data source slug. */
543
+ slug: string;
544
+ /** Version number to drop. Omitted → the candidate is dropped. */
545
+ version?: number;
546
+ }
547
+ /**
548
+ * Discard a candidate or retired pipeline version.
549
+ *
550
+ * Never touches the active version. Omit `version` to drop the candidate;
551
+ * pass a specific number to drop a retired version once rollback is no longer
552
+ * wanted.
553
+ *
554
+ * @throws AdminApiError `data_source_not_found` (404); `pipeline_not_found`
555
+ * (404) — no candidate exists, or the version number is unknown.
556
+ * @example
557
+ * await admin.dataSources.drop({ slug: 'policies' }); // drops the candidate
558
+ */
559
+ export declare function drop(ctx: AdminContext, params: DropParams): Promise<DataSourcesDropResult>;
560
+ export interface RmParams {
561
+ /** Data source slug. */
562
+ slug: string;
563
+ /** UUID of the document to remove. */
564
+ documentId: string;
565
+ }
566
+ /**
567
+ * Remove one document and its vectors from a data source.
568
+ *
569
+ * Deletes across every pipeline version, not just the active one — a document
570
+ * deleted mid-migration is gone from the candidate too.
571
+ *
572
+ * @throws AdminApiError `data_source_not_found` (404); `document_not_found`
573
+ * (404).
574
+ * @example
575
+ * await admin.dataSources.rm({ slug: 'policies', documentId });
576
+ */
577
+ export declare function rm(ctx: AdminContext, params: RmParams): Promise<DataSourcesDocumentDeleteResult>;
578
+ export interface RmWhereParams {
579
+ /** Data source slug. */
580
+ slug: string;
581
+ filter: DataSourcesDocumentSelector;
582
+ }
583
+ /**
584
+ * Remove one page (up to 1,000) of the documents matching a selector, across
585
+ * every pipeline version, and report how many still match. Loop while
586
+ * `remaining > 0`; `rmWhereAll` does that.
587
+ *
588
+ * @throws AdminApiError `data_source_not_found` (404), `invalid_filter` (400),
589
+ * `data_source_busy` (422) while a job is in flight, `data_source_migrating`
590
+ * (422) during a move.
591
+ * @example
592
+ * await admin.dataSources.rmWhere({ slug: 'archive', filter: { metadata: { year: 2019 } } });
593
+ */
594
+ export declare function rmWhere(ctx: AdminContext, params: RmWhereParams): Promise<DataSourcesDocumentDeleteManyResult>;
595
+ /** `rmWhere` until nothing matches. Reports each page through `onProgress`. */
596
+ export declare function rmWhereAll(ctx: AdminContext, params: RmWhereParams & {
597
+ onProgress?: (message: string) => void;
598
+ }): Promise<{
599
+ deleted: number;
600
+ }>;
601
+ /**
602
+ * Delete a whole data source — every version, every document, and every byte.
603
+ *
604
+ * Extraction caches survive (shared across sources by content hash), so
605
+ * re-ingesting the same files into a new source costs no re-extraction.
606
+ * Manage-plane only: running app code has no equivalent.
607
+ *
608
+ * @throws AdminApiError `data_source_not_found` (404).
609
+ * @example
610
+ * const { documents, versions } = await admin.dataSources.deleteSource('policies');
611
+ */
612
+ export declare function deleteSource(ctx: AdminContext, slug: string): Promise<DataSourcesDeleteResult>;
613
+ /** One dictionary entry: the app's id for a thing and the names it goes by. */
614
+ export interface DictionaryEntryInput {
615
+ id: string;
616
+ names: string[];
617
+ }
618
+ /**
619
+ * Push a source's dictionary, replacing the one it had: a stage, its pages
620
+ * (each retried alone), and the commit. A new version re-tags the source's
621
+ * passages in the background; an unchanged one commits nothing.
622
+ *
623
+ * @throws AdminApiError `invalid_dictionary` / `dictionary_name_too_short` (400)
624
+ * on a page, naming the entry; `dictionary_too_large` (400) at the commit.
625
+ * @example
626
+ * await admin.dataSources.pushDictionary({ slug: 'manuals', entries: [{ id: 'P-101A', names: ['P-101A', 'Main Feed Pump'] }] });
627
+ */
628
+ export declare function pushDictionary(ctx: AdminContext, params: {
629
+ slug: string;
630
+ entries: DictionaryEntryInput[];
631
+ linkerVersion?: number;
632
+ onProgress?: (sent: number, total: number) => void;
633
+ }): Promise<DataSourcesDictionaryPushResult>;
634
+ /**
635
+ * A source's current dictionary, and the relinks re-tagging its versions
636
+ * while they run.
637
+ *
638
+ * @throws AdminApiError `data_source_not_found` (404).
639
+ */
640
+ export declare function dictionary(ctx: AdminContext, params: {
641
+ slug: string;
642
+ }): Promise<DataSourcesDictionaryStatus>;
643
+ /**
644
+ * What the source's current dictionary finds in a piece of text: each
645
+ * mention, in order, with the ids it tags.
646
+ *
647
+ * @throws AdminApiError `data_source_not_found` (404).
648
+ * @example
649
+ * const { mentions } = await admin.dataSources.link({ slug: 'manuals', text: 'Replaced the seal on P101A.' });
650
+ */
651
+ export declare function link(ctx: AdminContext, params: {
652
+ slug: string;
653
+ text: string;
654
+ }): Promise<DataSourcesLinkResult>;