@madewithremy/admin 0.1.56 → 0.1.58
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.
- package/CHANGELOG.md +16 -0
- package/README.md +1 -1
- package/dist/client.d.ts +199 -0
- package/dist/config.d.ts +8 -0
- package/dist/ctx.d.ts +36 -0
- package/dist/errors.d.ts +68 -0
- package/dist/http.d.ts +68 -0
- package/dist/index.d.ts +7 -9434
- package/dist/index.js +6 -6
- package/dist/index.js.map +7 -1
- package/dist/ops/agent.d.ts +44 -0
- package/dist/ops/analytics.d.ts +285 -0
- package/dist/ops/apps.d.ts +33 -0
- package/dist/ops/crashes.d.ts +86 -0
- package/dist/ops/cron.d.ts +40 -0
- package/dist/ops/data.d.ts +68 -0
- package/dist/ops/dataSourceConnectors.d.ts +80 -0
- package/dist/ops/dataSourceEvals.d.ts +208 -0
- package/dist/ops/dataSourceJobs.d.ts +141 -0
- package/dist/ops/dataSourceMappers.d.ts +125 -0
- package/dist/ops/dataSources.d.ts +654 -0
- package/dist/ops/db.d.ts +81 -0
- package/dist/ops/diagnostics.d.ts +42 -0
- package/dist/ops/domains.d.ts +250 -0
- package/dist/ops/email.d.ts +305 -0
- package/dist/ops/events.d.ts +56 -0
- package/dist/ops/feedback.d.ts +24 -0
- package/dist/ops/files.d.ts +166 -0
- package/dist/ops/infra.d.ts +163 -0
- package/dist/ops/issues.d.ts +160 -0
- package/dist/ops/jewels.d.ts +249 -0
- package/dist/ops/methods.d.ts +60 -0
- package/dist/ops/prerender.d.ts +74 -0
- package/dist/ops/previews.d.ts +52 -0
- package/dist/ops/qaRecordings.d.ts +68 -0
- package/dist/ops/releases.d.ts +193 -0
- package/dist/ops/requests.d.ts +73 -0
- package/dist/ops/secrets.d.ts +69 -0
- package/dist/ops/settings.d.ts +45 -0
- package/dist/ops/tasks.d.ts +47 -0
- package/dist/ops/usage.d.ts +40 -0
- package/dist/ops/users.d.ts +59 -0
- package/dist/ops/voice.d.ts +178 -0
- package/dist/output.d.ts +19 -0
- package/dist/parseJsonConfig.d.ts +41 -0
- package/dist/poll.d.ts +38 -0
- package/dist/prod.js +24 -21
- package/dist/runningMethod.d.ts +25 -0
- package/dist/sleep.d.ts +12 -0
- package/dist/types/agent.d.ts +95 -0
- package/dist/types/analytics.d.ts +225 -0
- package/dist/types/apps.d.ts +39 -0
- package/dist/types/crashes.d.ts +81 -0
- package/dist/types/cron.d.ts +68 -0
- package/dist/types/data.d.ts +38 -0
- package/dist/types/dataSourceConnectors.d.ts +59 -0
- package/dist/types/dataSourceEvals.d.ts +225 -0
- package/dist/types/dataSourceJobs.d.ts +283 -0
- package/dist/types/dataSourceMappers.d.ts +204 -0
- package/dist/types/dataSourceReaders.d.ts +102 -0
- package/dist/types/dataSources.d.ts +627 -0
- package/dist/types/db.d.ts +63 -0
- package/dist/types/diagnostics.d.ts +96 -0
- package/dist/types/domains.d.ts +277 -0
- package/dist/types/email.d.ts +400 -0
- package/dist/types/events.d.ts +54 -0
- package/dist/types/feedback.d.ts +11 -0
- package/dist/types/files.d.ts +150 -0
- package/dist/types/index.d.ts +37 -0
- package/dist/types/infra.d.ts +188 -0
- package/dist/types/issues.d.ts +106 -0
- package/dist/types/jewels.d.ts +336 -0
- package/dist/types/methods.d.ts +34 -0
- package/dist/types/prerender.d.ts +59 -0
- package/dist/types/previews.d.ts +39 -0
- package/dist/types/progress.d.ts +31 -0
- package/dist/types/qaRecordings.d.ts +51 -0
- package/dist/types/releases.d.ts +233 -0
- package/dist/types/requests.d.ts +114 -0
- package/dist/types/secrets.d.ts +52 -0
- package/dist/types/settings.d.ts +79 -0
- package/dist/types/tasks.d.ts +99 -0
- package/dist/types/usage.d.ts +29 -0
- package/dist/types/users.d.ts +61 -0
- package/dist/types/voice.d.ts +197 -0
- package/dist/upload.d.ts +11 -0
- package/package.json +7 -10
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Warming an index, sampling a source, and retrieval evals: query sets, runs,
|
|
3
|
+
* comparisons. Ops are pure (ctx, params) → typed result; the CLI skin in
|
|
4
|
+
* commands/dataSourceEvals.ts owns flags, progress printing and exit codes.
|
|
5
|
+
*/
|
|
6
|
+
import type { AdminContext } from '../ctx.js';
|
|
7
|
+
import type { DataSourcesListEntry } from '../types/dataSources.js';
|
|
8
|
+
import type { DataSourcesHydrateResult, DataSourcesSampleResult, EvalCompareResult, EvalQueriesAddResult, EvalQueriesListResult, EvalQueryStyle, EvalRetrieval, EvalRun, EvalRunResult, EvalRunsListResult, EvalSet, EvalSetGetResult, EvalSetResult, EvalSetsListResult } from '../types/dataSourceEvals.js';
|
|
9
|
+
/** @internal Consumed by the CLI skin. */
|
|
10
|
+
export declare const DEFAULT_WAIT_TIMEOUT_MS: number;
|
|
11
|
+
/**
|
|
12
|
+
* Warm a source's index if it is cold. A search on a large cold index answers
|
|
13
|
+
* `index_warming` until the reload lands; call this before a demo, or after an
|
|
14
|
+
* eviction you know about. Answers `resident: true` when nothing was needed.
|
|
15
|
+
*/
|
|
16
|
+
export declare function hydrate(ctx: AdminContext, params: {
|
|
17
|
+
slug: string;
|
|
18
|
+
}): Promise<DataSourcesHydrateResult>;
|
|
19
|
+
/**
|
|
20
|
+
* Recreate a dedicated source's collection with the platform's current shape
|
|
21
|
+
* and refill it from the stored vectors. Nothing is re-embedded. Dedicated
|
|
22
|
+
* capacity only; refused while a job, move, hydration or candidate version is
|
|
23
|
+
* in flight, and with `collection_shared` when another source shares the
|
|
24
|
+
* collection on that capacity. Same response as `hydrate`: follow it with
|
|
25
|
+
* `waitForHydration`.
|
|
26
|
+
*
|
|
27
|
+
* @throws AdminApiError `reindex_requires_dedicated` (422), `data_source_busy`
|
|
28
|
+
* (422), `collection_shared` (422).
|
|
29
|
+
*/
|
|
30
|
+
export declare function reindex(ctx: AdminContext, params: {
|
|
31
|
+
slug: string;
|
|
32
|
+
}): Promise<DataSourcesHydrateResult>;
|
|
33
|
+
export interface WaitForHydrationParams {
|
|
34
|
+
slug: string;
|
|
35
|
+
/** How long without movement before giving up. Defaults to DEFAULT_WAIT_TIMEOUT_MS (30 min). */
|
|
36
|
+
timeoutMs?: number;
|
|
37
|
+
/** Receives `copying… X/Y documents · N/min · about M min left (Ns)`. */
|
|
38
|
+
onProgress?: (message: string) => void;
|
|
39
|
+
}
|
|
40
|
+
export type WaitForHydrationResult = {
|
|
41
|
+
status: 'done';
|
|
42
|
+
source: DataSourcesListEntry;
|
|
43
|
+
} | {
|
|
44
|
+
status: 'failed';
|
|
45
|
+
source: DataSourcesListEntry;
|
|
46
|
+
error: string;
|
|
47
|
+
} | {
|
|
48
|
+
status: 'timeout';
|
|
49
|
+
source: DataSourcesListEntry;
|
|
50
|
+
error: string;
|
|
51
|
+
};
|
|
52
|
+
/** Poll the source list until its `hydration` clears, fails, or the timeout elapses. */
|
|
53
|
+
export declare function waitForHydration(ctx: AdminContext, params: WaitForHydrationParams): Promise<WaitForHydrationResult>;
|
|
54
|
+
export interface SampleParams {
|
|
55
|
+
/** The source to draw from. */
|
|
56
|
+
slug: string;
|
|
57
|
+
/** Documents to draw (at most 2,000). */
|
|
58
|
+
size: number;
|
|
59
|
+
/** Slug for the sample; default `<slug>-sample`. */
|
|
60
|
+
as?: string;
|
|
61
|
+
/** Scope the draw: metadata equality, or the full document selector. */
|
|
62
|
+
filter?: Record<string, unknown>;
|
|
63
|
+
/** Metadata key to stratify on, proportional per value. */
|
|
64
|
+
stratify?: string;
|
|
65
|
+
placement?: {
|
|
66
|
+
resourceId: string;
|
|
67
|
+
} | 'shared';
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Draw a sample of a source into a new source with the same pinned config.
|
|
71
|
+
* The copy is a job (auto-approved; extraction is reused by content hash, so
|
|
72
|
+
* the plan is chunk + embed only). Documents keep their content hashes, which
|
|
73
|
+
* is what lets an eval set built on the sample score the parent too.
|
|
74
|
+
*
|
|
75
|
+
* @throws AdminApiError `invalid_size` (400), `slug_in_use` (422),
|
|
76
|
+
* `data_source_limit` (422), `data_source_busy` (422).
|
|
77
|
+
*/
|
|
78
|
+
export declare function sample(ctx: AdminContext, params: SampleParams): Promise<DataSourcesSampleResult>;
|
|
79
|
+
export interface CreateSetParams {
|
|
80
|
+
slug: string;
|
|
81
|
+
/** Lowercase [a-z0-9_-], unique per source. */
|
|
82
|
+
name: string;
|
|
83
|
+
description?: string;
|
|
84
|
+
/** Queries to generate from the corpus; 0 (default) makes an empty set to add to. */
|
|
85
|
+
size?: number;
|
|
86
|
+
/** `cloze` (default, free) or `question` (a chat model writes them). */
|
|
87
|
+
style?: EvalQueryStyle;
|
|
88
|
+
/** Chat model for `question`; default the source's contextual model or the platform's. */
|
|
89
|
+
modelId?: string;
|
|
90
|
+
tags?: string[];
|
|
91
|
+
/** Makes generation reproducible; default the current time. */
|
|
92
|
+
seed?: number;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Create a query set, generating queries from the corpus when `size` is set.
|
|
96
|
+
* Generation runs in the background; the set is `generating` until it is
|
|
97
|
+
* `ready` (see `waitForSet`).
|
|
98
|
+
*
|
|
99
|
+
* @throws AdminApiError `eval_set_exists` (422), `invalid_name` (400).
|
|
100
|
+
*/
|
|
101
|
+
export declare function createSet(ctx: AdminContext, params: CreateSetParams): Promise<EvalSetResult>;
|
|
102
|
+
export declare function listSets(ctx: AdminContext, params?: {
|
|
103
|
+
slug?: string;
|
|
104
|
+
}): Promise<EvalSetsListResult>;
|
|
105
|
+
export declare function getSet(ctx: AdminContext, params: {
|
|
106
|
+
id: string;
|
|
107
|
+
queries?: boolean;
|
|
108
|
+
}): Promise<EvalSetGetResult>;
|
|
109
|
+
export declare function deleteSet(ctx: AdminContext, params: {
|
|
110
|
+
id: string;
|
|
111
|
+
}): Promise<{
|
|
112
|
+
deleted: true;
|
|
113
|
+
set: EvalSet;
|
|
114
|
+
}>;
|
|
115
|
+
export interface QueryInput {
|
|
116
|
+
query: string;
|
|
117
|
+
/** Which documents should come back; each reference must exist on the set's source. */
|
|
118
|
+
expect: {
|
|
119
|
+
documentIds?: string[];
|
|
120
|
+
filenames?: string[];
|
|
121
|
+
externalIds?: string[];
|
|
122
|
+
contentHashes?: string[];
|
|
123
|
+
};
|
|
124
|
+
passage?: string;
|
|
125
|
+
tags?: string[];
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Add hand-written queries (≤ 500 per call). Every reference is resolved
|
|
129
|
+
* before anything is written; an unknown filename refuses the whole call by
|
|
130
|
+
* name (`expected_document_not_found`).
|
|
131
|
+
*/
|
|
132
|
+
export declare function addQueries(ctx: AdminContext, params: {
|
|
133
|
+
id: string;
|
|
134
|
+
queries: QueryInput[];
|
|
135
|
+
}): Promise<EvalQueriesAddResult>;
|
|
136
|
+
export declare function listQueries(ctx: AdminContext, params: {
|
|
137
|
+
id: string;
|
|
138
|
+
}): Promise<EvalQueriesListResult>;
|
|
139
|
+
export declare function deleteQuery(ctx: AdminContext, params: {
|
|
140
|
+
id: string;
|
|
141
|
+
queryId: string;
|
|
142
|
+
}): Promise<{
|
|
143
|
+
deleted: string;
|
|
144
|
+
queryCount: number;
|
|
145
|
+
}>;
|
|
146
|
+
export interface RunParams {
|
|
147
|
+
setId: string;
|
|
148
|
+
/** Target source; default the set's own. Expectations resolve by content hash. */
|
|
149
|
+
slug?: string;
|
|
150
|
+
/** Evaluate the target's candidate version instead of the active one. */
|
|
151
|
+
candidate?: boolean;
|
|
152
|
+
label?: string;
|
|
153
|
+
retrieval?: EvalRetrieval;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Score a set against a target. Runs in the background; block with
|
|
157
|
+
* `waitForRun`. Each query is a real search (embedding + rerank spend).
|
|
158
|
+
*
|
|
159
|
+
* @throws AdminApiError `eval_set_not_ready` (422), `eval_set_empty` (422),
|
|
160
|
+
* `no_candidate_pipeline` (404), `invalid_retrieval` (400).
|
|
161
|
+
*/
|
|
162
|
+
export declare function run(ctx: AdminContext, params: RunParams): Promise<EvalRunResult>;
|
|
163
|
+
export declare function listRuns(ctx: AdminContext, params?: {
|
|
164
|
+
setId?: string;
|
|
165
|
+
slug?: string;
|
|
166
|
+
}): Promise<EvalRunsListResult>;
|
|
167
|
+
export declare function getRun(ctx: AdminContext, params: {
|
|
168
|
+
id: string;
|
|
169
|
+
queries?: boolean;
|
|
170
|
+
worst?: number;
|
|
171
|
+
}): Promise<EvalRunResult>;
|
|
172
|
+
/** Two runs side by side: aggregate deltas, and per-query wins/losses when they share a set. */
|
|
173
|
+
export declare function compare(ctx: AdminContext, params: {
|
|
174
|
+
a: string;
|
|
175
|
+
b: string;
|
|
176
|
+
}): Promise<EvalCompareResult>;
|
|
177
|
+
export interface WaitParams {
|
|
178
|
+
id: string;
|
|
179
|
+
timeoutMs?: number;
|
|
180
|
+
onProgress?: (message: string) => void;
|
|
181
|
+
}
|
|
182
|
+
export type WaitForRunResult = {
|
|
183
|
+
status: 'done';
|
|
184
|
+
run: EvalRun;
|
|
185
|
+
} | {
|
|
186
|
+
status: 'failed';
|
|
187
|
+
run: EvalRun;
|
|
188
|
+
error: string;
|
|
189
|
+
} | {
|
|
190
|
+
status: 'timeout';
|
|
191
|
+
run: EvalRun;
|
|
192
|
+
error: string;
|
|
193
|
+
};
|
|
194
|
+
export declare function waitForRun(ctx: AdminContext, params: WaitParams): Promise<WaitForRunResult>;
|
|
195
|
+
export type WaitForSetResult = {
|
|
196
|
+
status: 'done';
|
|
197
|
+
set: EvalSet;
|
|
198
|
+
} | {
|
|
199
|
+
status: 'failed';
|
|
200
|
+
set: EvalSet;
|
|
201
|
+
error: string;
|
|
202
|
+
} | {
|
|
203
|
+
status: 'timeout';
|
|
204
|
+
set: EvalSet;
|
|
205
|
+
error: string;
|
|
206
|
+
};
|
|
207
|
+
/** Poll until generation lands (`ready`) or fails; a set waits `queued` for a worker first. */
|
|
208
|
+
export declare function waitForSet(ctx: AdminContext, params: WaitParams): Promise<WaitForSetResult>;
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Bulk ingestion jobs: load a corpus into a data source from a file-store
|
|
3
|
+
* prefix or a manifest of URLs, with a plan (cost, size, duration) shown
|
|
4
|
+
* before anything is spent.
|
|
5
|
+
*
|
|
6
|
+
* Ops are pure (ctx, params) → typed result. The CLI skin in
|
|
7
|
+
* commands/dataSourceJobs.ts owns flags, progress printing and exit codes.
|
|
8
|
+
*/
|
|
9
|
+
import type { AdminContext } from '../ctx.js';
|
|
10
|
+
import type { DataSourceJob, DataSourceJobGetResult, DataSourceJobResult, DataSourceJobsListResult, DataSourceJobSource } from '../types/dataSourceJobs.js';
|
|
11
|
+
/** @internal Consumed by the CLI skin. */
|
|
12
|
+
export declare const DEFAULT_WAIT_TIMEOUT_MS: number;
|
|
13
|
+
export interface StartParams {
|
|
14
|
+
/** Data source slug. Created on first use, like `add`. */
|
|
15
|
+
slug: string;
|
|
16
|
+
source: DataSourceJobSource;
|
|
17
|
+
/** Run as soon as the plan passes the gates, without a separate approve. */
|
|
18
|
+
approve?: boolean;
|
|
19
|
+
/** Stop when estimated spend reaches this; default 1.5× the projection. */
|
|
20
|
+
budgetDollars?: number;
|
|
21
|
+
/** Batches in flight at once (default 64, max 128). */
|
|
22
|
+
concurrency?: number;
|
|
23
|
+
/**
|
|
24
|
+
* Embed at the provider's priority tier: calls are admitted ahead of the
|
|
25
|
+
* provider's queue at 1.5x the embedding price. Off by default.
|
|
26
|
+
*/
|
|
27
|
+
priority?: boolean;
|
|
28
|
+
/** Process only the first N objects — a sample of the corpus. */
|
|
29
|
+
limit?: number;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Start a job. The platform enumerates the source, reads a sample, and writes
|
|
33
|
+
* a plan; the job then waits in `planned` for `approve` unless `approve` was
|
|
34
|
+
* set. Nothing is embedded until it runs.
|
|
35
|
+
*
|
|
36
|
+
* @throws AdminApiError `data_source_busy` (422) — a move, a candidate
|
|
37
|
+
* version or another job is in flight; `invalid_source` (400).
|
|
38
|
+
* @example
|
|
39
|
+
* const { job } = await admin.dataSourceJobs.start({
|
|
40
|
+
* slug: 'archive',
|
|
41
|
+
* source: { type: 'store', store: 'raw', access: 'private', prefix: '2024/' },
|
|
42
|
+
* });
|
|
43
|
+
*/
|
|
44
|
+
export declare function start(ctx: AdminContext, params: StartParams): Promise<DataSourceJobResult>;
|
|
45
|
+
export interface UploadManifestParams {
|
|
46
|
+
slug: string;
|
|
47
|
+
/** JSONL: one `{ url, filename?, externalId?, metadata? }` per line. */
|
|
48
|
+
content: Buffer;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Upload a manifest for `start` with a `manifest` source. Returns the key to
|
|
52
|
+
* pass as `source.key`.
|
|
53
|
+
*/
|
|
54
|
+
export declare function uploadManifest(ctx: AdminContext, params: UploadManifestParams): Promise<{
|
|
55
|
+
key: string;
|
|
56
|
+
}>;
|
|
57
|
+
export interface ListParams {
|
|
58
|
+
/** Only this source's jobs; omit for every job on the app. */
|
|
59
|
+
slug?: string;
|
|
60
|
+
}
|
|
61
|
+
export declare function list(ctx: AdminContext, params?: ListParams): Promise<DataSourceJobsListResult>;
|
|
62
|
+
export interface JobIdParams {
|
|
63
|
+
id: string;
|
|
64
|
+
}
|
|
65
|
+
/** @throws AdminApiError `job_not_found` (404). */
|
|
66
|
+
export declare function get(ctx: AdminContext, params: JobIdParams): Promise<DataSourceJobGetResult>;
|
|
67
|
+
/**
|
|
68
|
+
* Approve a planned job: the yes to the plan's spend. Refused when the
|
|
69
|
+
* projection does not fit the source's placement or the workspace cannot
|
|
70
|
+
* cover it.
|
|
71
|
+
*
|
|
72
|
+
* @throws AdminApiError `job_not_found` (404), `invalid_transition` (422),
|
|
73
|
+
* `plan_requires_dedicated` (422), `plan_exceeds_capacity` (422),
|
|
74
|
+
* `insufficient_credits/*` (402).
|
|
75
|
+
*/
|
|
76
|
+
export declare function approve(ctx: AdminContext, params: JobIdParams & {
|
|
77
|
+
/** Batches in flight from here on (max 128); the plan was made at the job's current value. */
|
|
78
|
+
concurrency?: number;
|
|
79
|
+
/** Embed at the provider's priority tier from here on (1.5x the embedding price). */
|
|
80
|
+
priority?: boolean;
|
|
81
|
+
}): Promise<DataSourceJobResult>;
|
|
82
|
+
/** Stop dispatching batches; the ones in flight finish. */
|
|
83
|
+
export declare function pause(ctx: AdminContext, params: JobIdParams): Promise<DataSourceJobResult>;
|
|
84
|
+
/** Continue from the checkpoint; failed batches with attempts left are retried. */
|
|
85
|
+
export declare function resume(ctx: AdminContext, params: JobIdParams & {
|
|
86
|
+
/** Batches in flight from here on (max 128). */
|
|
87
|
+
concurrency?: number;
|
|
88
|
+
/** Embed at the provider's priority tier from here on (1.5x the embedding price). */
|
|
89
|
+
priority?: boolean;
|
|
90
|
+
}): Promise<DataSourceJobResult>;
|
|
91
|
+
/**
|
|
92
|
+
* Run a finished job's failed batches again, after fixing what failed them.
|
|
93
|
+
* The job goes back to `running`; `nothing_to_retry` when none failed.
|
|
94
|
+
*/
|
|
95
|
+
export declare function retry(ctx: AdminContext, params: JobIdParams): Promise<DataSourceJobResult>;
|
|
96
|
+
/** End the job. Documents already indexed stay. */
|
|
97
|
+
export declare function cancel(ctx: AdminContext, params: JobIdParams): Promise<DataSourceJobResult>;
|
|
98
|
+
export interface WaitParams {
|
|
99
|
+
id: string;
|
|
100
|
+
/** How long without movement before giving up. Default one hour. */
|
|
101
|
+
timeoutMs?: number;
|
|
102
|
+
onProgress?: (message: string) => void;
|
|
103
|
+
}
|
|
104
|
+
export type WaitResult = {
|
|
105
|
+
status: 'done';
|
|
106
|
+
job: DataSourceJob;
|
|
107
|
+
}
|
|
108
|
+
/** The plan is ready but the job will not run on its own: a gate refused, or it waits for approval. */
|
|
109
|
+
| {
|
|
110
|
+
status: 'planned';
|
|
111
|
+
job: DataSourceJob;
|
|
112
|
+
error: string;
|
|
113
|
+
} | {
|
|
114
|
+
status: 'failed';
|
|
115
|
+
job: DataSourceJob;
|
|
116
|
+
error: string;
|
|
117
|
+
} | {
|
|
118
|
+
status: 'timeout';
|
|
119
|
+
job: DataSourceJob;
|
|
120
|
+
error: string;
|
|
121
|
+
};
|
|
122
|
+
/**
|
|
123
|
+
* Poll until the job leaves `planning`: the plan is ready (`done`), or a gate
|
|
124
|
+
* refused it (`planned` with the job's error), or it could not be planned.
|
|
125
|
+
*/
|
|
126
|
+
export declare function waitForPlan(ctx: AdminContext, params: WaitParams): Promise<WaitResult>;
|
|
127
|
+
/**
|
|
128
|
+
* Poll until the job reaches a terminal state, pauses for the owner, or
|
|
129
|
+
* settles in `planned` with nothing about to move it: a gate refused an
|
|
130
|
+
* auto-approved plan, or the plan waits for an approval nobody asked this wait
|
|
131
|
+
* to give. A pause for errors that will resume itself (`autoResumeAt` set) is
|
|
132
|
+
* ridden through; a pause that waits for the owner is reported as `failed`
|
|
133
|
+
* with the pause reason, since nothing more will happen without them.
|
|
134
|
+
*/
|
|
135
|
+
export declare function waitForJob(ctx: AdminContext, params: WaitParams): Promise<WaitResult>;
|
|
136
|
+
/**
|
|
137
|
+
* One line of progress in the job's own terms: the platform's phase, count,
|
|
138
|
+
* rate and ETA, with the spend so far beside them. A planning walk that has
|
|
139
|
+
* finished listing says so, since its count has stopped moving on purpose.
|
|
140
|
+
*/
|
|
141
|
+
export declare function describeProgress(job: DataSourceJob, start: number): string;
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Data-source mappers: the loop around customer code that turns raw objects
|
|
3
|
+
* into documents — inspect the objects, test the mapper, make a build's mapper
|
|
4
|
+
* the source's active one, remap after a fix, read and replay what a job
|
|
5
|
+
* quarantined.
|
|
6
|
+
*
|
|
7
|
+
* Ops are pure (ctx, params) → typed result. The CLI skin in
|
|
8
|
+
* commands/dataSourceMappers.ts owns flags, progress and exit codes.
|
|
9
|
+
*/
|
|
10
|
+
import type { AdminContext } from '../ctx.js';
|
|
11
|
+
import type { DataSourceInspectResult, DataSourceMapDeployResult, DataSourceMapTestResult, DataSourceQuarantineResult, DataSourceRemapResult } from '../types/dataSourceMappers.js';
|
|
12
|
+
/** Which objects to look at: a prefix of an app file store, or the connected bucket. */
|
|
13
|
+
export type ObjectSelection = {
|
|
14
|
+
store: string;
|
|
15
|
+
access?: 'private' | 'public';
|
|
16
|
+
prefix?: string;
|
|
17
|
+
} | {
|
|
18
|
+
connector: true;
|
|
19
|
+
};
|
|
20
|
+
export interface InspectParams {
|
|
21
|
+
/** Required for a connector selection; optional for a store. */
|
|
22
|
+
slug?: string;
|
|
23
|
+
selection: ObjectSelection;
|
|
24
|
+
/** Only these keys. */
|
|
25
|
+
keys?: string[];
|
|
26
|
+
/** Objects to list (default 5,000, max 50,000). */
|
|
27
|
+
limit?: number;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Profile raw objects before writing a mapper: counts and bytes by extension
|
|
31
|
+
* and by key shape, size buckets, and ten sampled heads with their JSON key
|
|
32
|
+
* signatures. Read-only.
|
|
33
|
+
*
|
|
34
|
+
* @throws AdminApiError `invalid_source` (400), `connector_not_found` (422).
|
|
35
|
+
*/
|
|
36
|
+
export declare function inspect(ctx: AdminContext, params: InspectParams): Promise<DataSourceInspectResult>;
|
|
37
|
+
export interface MapTestParams {
|
|
38
|
+
slug: string;
|
|
39
|
+
selection: ObjectSelection;
|
|
40
|
+
keys?: string[];
|
|
41
|
+
/** Objects to map (default 20, max 200). */
|
|
42
|
+
limit?: number;
|
|
43
|
+
/** Run the LOCAL mapper through the app's dev session instead of the live bundle. */
|
|
44
|
+
dev?: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* With `dev`, which of your dev sessions: its dev release id. Default your
|
|
47
|
+
* newest. Only ever your own.
|
|
48
|
+
*/
|
|
49
|
+
releaseId?: string;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Run the source's mapper over real objects and return the outcomes — nothing
|
|
53
|
+
* is ingested. With `dev` the mapper runs from local source through the
|
|
54
|
+
* running dev session, which is how a mapper is checked before a deploy.
|
|
55
|
+
*
|
|
56
|
+
* @throws AdminApiError `no_mapper` (422), `no_dev_session` (422),
|
|
57
|
+
* `invalid_source` (400).
|
|
58
|
+
*/
|
|
59
|
+
export declare function mapTest(ctx: AdminContext, params: MapTestParams): Promise<DataSourceMapTestResult>;
|
|
60
|
+
export interface RemapParams {
|
|
61
|
+
slug: string;
|
|
62
|
+
/** Pause when estimated spend reaches this; default the plan's headroom. */
|
|
63
|
+
budgetDollars?: number;
|
|
64
|
+
/** Only the first N raw objects. */
|
|
65
|
+
limit?: number;
|
|
66
|
+
}
|
|
67
|
+
export interface MapDeployParams {
|
|
68
|
+
slug: string;
|
|
69
|
+
/**
|
|
70
|
+
* The release to take the mapper from. Default: the newest built release —
|
|
71
|
+
* live or the head of any branch — that carries a compiled mapper for the
|
|
72
|
+
* slug.
|
|
73
|
+
*/
|
|
74
|
+
releaseId?: string;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Make a built release's compiled mapper the source's active mapper — what
|
|
78
|
+
* jobs, syncs and `add()` run from now on. A branch build is enough: the app
|
|
79
|
+
* need never have been published. Publishing to main also activates the
|
|
80
|
+
* mapper main declares. Idempotent (`changed: false` when already active).
|
|
81
|
+
*
|
|
82
|
+
* @throws AdminApiError `no_built_mapper` (422) when no build carries a
|
|
83
|
+
* compiled mapper for the slug, `release_not_found` (404).
|
|
84
|
+
*/
|
|
85
|
+
export declare function mapDeploy(ctx: AdminContext, params: MapDeployParams): Promise<DataSourceMapDeployResult>;
|
|
86
|
+
/**
|
|
87
|
+
* Run the active mapper over every raw object the source holds a copy of.
|
|
88
|
+
* Auto-approved: unchanged markdown is skipped by hash, so a remap after a
|
|
89
|
+
* metadata tweak costs frames and little else. Block on the job with
|
|
90
|
+
* `dataSourceJobs.waitForJob`.
|
|
91
|
+
*
|
|
92
|
+
* @throws AdminApiError `no_mapper` (422), `nothing_to_remap` (422),
|
|
93
|
+
* `data_source_busy` (422).
|
|
94
|
+
*/
|
|
95
|
+
export declare function remap(ctx: AdminContext, params: RemapParams): Promise<DataSourceRemapResult>;
|
|
96
|
+
export interface QuarantineParams {
|
|
97
|
+
id: string;
|
|
98
|
+
kind?: 'skip' | 'error';
|
|
99
|
+
/** Only the mapper's (`map`) or only the reader's (`read`). */
|
|
100
|
+
stage?: 'map' | 'read';
|
|
101
|
+
/** Only objects quarantined with exactly this reason. */
|
|
102
|
+
reason?: string;
|
|
103
|
+
cursor?: string;
|
|
104
|
+
/** Page size (default 100, max 1,000). */
|
|
105
|
+
limit?: number;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* What a job's mapper skipped or failed on, and what its reader failed on:
|
|
109
|
+
* counts, reasons by frequency, and a page of objects.
|
|
110
|
+
*
|
|
111
|
+
* @throws AdminApiError `job_not_found` (404).
|
|
112
|
+
*/
|
|
113
|
+
export declare function quarantine(ctx: AdminContext, params: QuarantineParams): Promise<DataSourceQuarantineResult>;
|
|
114
|
+
export interface ReplayParams {
|
|
115
|
+
id: string;
|
|
116
|
+
kind?: 'skip' | 'error';
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Run a job's quarantined objects through the current mapper, from their raw
|
|
120
|
+
* copies. Starts a job; block on it with `dataSourceJobs.waitForJob`.
|
|
121
|
+
*
|
|
122
|
+
* @throws AdminApiError `nothing_to_replay` (422), `no_mapper` (422),
|
|
123
|
+
* `data_source_busy` (422).
|
|
124
|
+
*/
|
|
125
|
+
export declare function replay(ctx: AdminContext, params: ReplayParams): Promise<DataSourceRemapResult>;
|