@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.
- package/CHANGELOG.md +12 -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 -9442
- package/dist/index.js +6 -14
- 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 +61 -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 +39 -55
- 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 +42 -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,249 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Jewels operations: shadowing overview, pair ledger, approval queue, training.
|
|
3
|
+
*
|
|
4
|
+
* Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
|
|
5
|
+
* AdminTimeoutError. No printing, no process coupling — the CLI skin in
|
|
6
|
+
* commands/jewels.ts and the importable client both call these.
|
|
7
|
+
*
|
|
8
|
+
* Long-running ops (resolve --approve, dryrun, train, grade) hold the request
|
|
9
|
+
* for a full agent/model run; they pass their own timeout bound to `call`.
|
|
10
|
+
* The constant is exported so the CLI skin can pass the same value to
|
|
11
|
+
* cliStream.rawToStdout for the `jewels export --file` passthrough.
|
|
12
|
+
*/
|
|
13
|
+
import type { AdminContext } from '../ctx.js';
|
|
14
|
+
import type { JewelsDryrunResult, JewelsExportResult, JewelsGradeResult, JewelsOverviewResult, JewelsPairResult, JewelsPairsResult, JewelsQueueResult, JewelsResolveResult, JewelsRunResult, JewelsRunsResult, JewelsTimeseriesResult, JewelsTrainResult } from '../types/jewels.js';
|
|
15
|
+
/**
|
|
16
|
+
* Jewel runs are full agent loops: resolve --approve applies the method as
|
|
17
|
+
* the reviewer, and dryrun executes the live jewel end to end — both can
|
|
18
|
+
* legitimately take minutes, so they get their own request bound.
|
|
19
|
+
* @internal Consumed by the CLI skin; not part of the documented surface.
|
|
20
|
+
*/
|
|
21
|
+
export declare const JEWEL_RUN_TIMEOUT_MS = 600000;
|
|
22
|
+
export interface WindowParams {
|
|
23
|
+
/** ISO date string for the start of the query window (default: 30 days before `end`). */
|
|
24
|
+
start?: string;
|
|
25
|
+
/** ISO date string for the end of the query window (default: now). */
|
|
26
|
+
end?: string;
|
|
27
|
+
}
|
|
28
|
+
export interface JewelsPairsParams extends WindowParams {
|
|
29
|
+
/** Filter to a specific method id. */
|
|
30
|
+
methodId?: string;
|
|
31
|
+
/** Filter by verdict: `agree`, `disagree`, `skip`, or `expired`. */
|
|
32
|
+
verdict?: string;
|
|
33
|
+
/** Filter by shadow mode: `shadow`, `arrival`, `auto`, or `approve`. */
|
|
34
|
+
mode?: string;
|
|
35
|
+
/** Page size (default 50). */
|
|
36
|
+
limit?: number;
|
|
37
|
+
/** Keyset cursor from a previous response's `nextCursor`. */
|
|
38
|
+
cursor?: string;
|
|
39
|
+
}
|
|
40
|
+
export interface JewelsQueueParams {
|
|
41
|
+
/** Filter to a specific method id. */
|
|
42
|
+
methodId?: string;
|
|
43
|
+
/** Max items to return (default 50). */
|
|
44
|
+
limit?: number;
|
|
45
|
+
}
|
|
46
|
+
export interface JewelsTimeseriesParams extends WindowParams {
|
|
47
|
+
/** Filter to a specific method id. */
|
|
48
|
+
methodId?: string;
|
|
49
|
+
/** Number of time buckets (default 24). */
|
|
50
|
+
buckets?: number;
|
|
51
|
+
}
|
|
52
|
+
export interface JewelsResolveParams {
|
|
53
|
+
/** The queue item's id (from `queue` results). */
|
|
54
|
+
itemId: string;
|
|
55
|
+
/**
|
|
56
|
+
* `approve` runs the method for real as the calling user (the reviewer),
|
|
57
|
+
* grades the proposed-vs-final pair, and closes the item. `dismiss` closes
|
|
58
|
+
* the item without acting — no method run, no pair recorded.
|
|
59
|
+
*/
|
|
60
|
+
action: 'approve' | 'dismiss';
|
|
61
|
+
/**
|
|
62
|
+
* Override the proposed input before applying (approve only). When set the
|
|
63
|
+
* resolution is recorded as `edited`; omit to apply the proposal as-is.
|
|
64
|
+
*/
|
|
65
|
+
input?: Record<string, unknown>;
|
|
66
|
+
}
|
|
67
|
+
export interface JewelsDryrunParams {
|
|
68
|
+
/** The method id whose jewel should run against `subject`. */
|
|
69
|
+
methodId: string;
|
|
70
|
+
/** The triggering subject object to pass to the jewel. */
|
|
71
|
+
subject: Record<string, unknown>;
|
|
72
|
+
}
|
|
73
|
+
export interface JewelsExportParams extends WindowParams {
|
|
74
|
+
/** The method id to export pairs for. */
|
|
75
|
+
methodId: string;
|
|
76
|
+
}
|
|
77
|
+
export interface JewelsTrainParams {
|
|
78
|
+
/** The method id to train a fine-tuning run for. */
|
|
79
|
+
methodId: string;
|
|
80
|
+
}
|
|
81
|
+
export interface JewelsRunsParams {
|
|
82
|
+
/** Filter to a specific method id. */
|
|
83
|
+
methodId?: string;
|
|
84
|
+
/** Max runs to return (default 20). */
|
|
85
|
+
limit?: number;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Per-method shadowing overview: autonomy, sample rate, pair counts by verdict,
|
|
89
|
+
* agreement rate, human-invocation coverage, and queue depth.
|
|
90
|
+
*
|
|
91
|
+
* Time window defaults to the last 30 days when `start`/`end` are omitted.
|
|
92
|
+
* Training summary (active run, last run, latest model) is always all-time
|
|
93
|
+
* regardless of the window — it reflects current model state, not the pair
|
|
94
|
+
* stats window.
|
|
95
|
+
*
|
|
96
|
+
* @example
|
|
97
|
+
* const { methods, totals } = await admin.jewels.overview();
|
|
98
|
+
* const shadowed = methods.filter((m) => m.hasJewel);
|
|
99
|
+
*/
|
|
100
|
+
export declare function overview(ctx: AdminContext, params?: WindowParams): Promise<JewelsOverviewResult>;
|
|
101
|
+
/**
|
|
102
|
+
* Verdict counts (agree / disagree / skip / expired) over time, bucketed.
|
|
103
|
+
*
|
|
104
|
+
* One bucket array per method; use `methodId` to narrow to a single series.
|
|
105
|
+
* Time window defaults to the last 30 days.
|
|
106
|
+
*
|
|
107
|
+
* @example
|
|
108
|
+
* const { methods } = await admin.jewels.timeseries({ methodId: 'triage-issue', buckets: 48 });
|
|
109
|
+
*/
|
|
110
|
+
export declare function timeseries(ctx: AdminContext, params?: JewelsTimeseriesParams): Promise<JewelsTimeseriesResult>;
|
|
111
|
+
/**
|
|
112
|
+
* Paginated list of slim pair rows (excludes the full JSONB pair payload).
|
|
113
|
+
*
|
|
114
|
+
* Use `pair(pairId)` to fetch the full record with hydrated traces.
|
|
115
|
+
* Time window defaults to the last 30 days.
|
|
116
|
+
*
|
|
117
|
+
* @example
|
|
118
|
+
* const { pairs, nextCursor } = await admin.jewels.pairs({ verdict: 'disagree' });
|
|
119
|
+
*/
|
|
120
|
+
export declare function pairs(ctx: AdminContext, params?: JewelsPairsParams): Promise<JewelsPairsResult>;
|
|
121
|
+
/**
|
|
122
|
+
* Full pair record: proposed vs actual output, reasoning, grade notes, and
|
|
123
|
+
* hydrated model transcripts (propose + grade phases) when the jewel attached
|
|
124
|
+
* traces. Objects that could not be fetched degrade to `{ id, phase, missing: true }`
|
|
125
|
+
* rather than a 500.
|
|
126
|
+
*
|
|
127
|
+
* @param pairId The pair id (from `pairs` results or the overview).
|
|
128
|
+
* @throws AdminApiError `pair_not_found` (404) — no pair with this id in this app.
|
|
129
|
+
* @example
|
|
130
|
+
* const { pair, traces } = await admin.jewels.pair('6f1e...');
|
|
131
|
+
*/
|
|
132
|
+
export declare function pair(ctx: AdminContext, pairId: string): Promise<JewelsPairResult>;
|
|
133
|
+
/**
|
|
134
|
+
* Pending approve-mode proposals awaiting review.
|
|
135
|
+
*
|
|
136
|
+
* Only items for methods with `autonomy: 'approve'` appear here. Use
|
|
137
|
+
* `resolve` to approve or dismiss an item.
|
|
138
|
+
*
|
|
139
|
+
* @example
|
|
140
|
+
* const { items } = await admin.jewels.queue({ methodId: 'triage-issue' });
|
|
141
|
+
*/
|
|
142
|
+
export declare function queue(ctx: AdminContext, params?: JewelsQueueParams): Promise<JewelsQueueResult>;
|
|
143
|
+
/**
|
|
144
|
+
* Approve or dismiss one approval-queue item.
|
|
145
|
+
*
|
|
146
|
+
* **Approve** applies the method as the calling user (the reviewer): the
|
|
147
|
+
* proposal's input runs for real, the platform grades proposed-vs-final, and
|
|
148
|
+
* the item closes. Pass `input` to apply an edited version (resolution
|
|
149
|
+
* recorded as `edited`). **Dismiss** closes the item without acting — no
|
|
150
|
+
* method run, no pair recorded.
|
|
151
|
+
*
|
|
152
|
+
* The request holds for a full jewel/method run — allow minutes (up to
|
|
153
|
+
* `JEWEL_RUN_TIMEOUT_MS`).
|
|
154
|
+
*
|
|
155
|
+
* @example
|
|
156
|
+
* const { resolution, output } = await admin.jewels.resolve({ itemId: '6f1e...', action: 'approve' });
|
|
157
|
+
*/
|
|
158
|
+
export declare function resolve(ctx: AdminContext, params: JewelsResolveParams): Promise<JewelsResolveResult>;
|
|
159
|
+
/**
|
|
160
|
+
* Run the live jewel against a subject without recording or committing
|
|
161
|
+
* anything.
|
|
162
|
+
*
|
|
163
|
+
* Executes inside a disposable database mirror — guaranteed side-effect-free
|
|
164
|
+
* on the app database. The prod twin of the dev `testJewel` tool (which runs
|
|
165
|
+
* draft code against the dev DB); this one answers for the deployed release
|
|
166
|
+
* against the real world. Allow minutes for the full jewel run.
|
|
167
|
+
*
|
|
168
|
+
* @throws AdminApiError `invalid_subject` (400) — `subject` is not an object;
|
|
169
|
+
* `invalid_app_method` (400) — unknown method id; `no_jewel` (400) — the
|
|
170
|
+
* method has no compiled jewel in the live release.
|
|
171
|
+
* @example
|
|
172
|
+
* const { record } = await admin.jewels.dryrun({ methodId: 'triage-issue', subject: { issueId: 'abc' } });
|
|
173
|
+
*/
|
|
174
|
+
export declare function dryrun(ctx: AdminContext, params: JewelsDryrunParams): Promise<JewelsDryrunResult>;
|
|
175
|
+
/**
|
|
176
|
+
* Dataset report (no `--file`): per-file row counts, every exclusion bucket
|
|
177
|
+
* named (skip, expired, ungraded, auto, traceless, traceMissing,
|
|
178
|
+
* preferenceUnrenderable), and trace coverage.
|
|
179
|
+
*
|
|
180
|
+
* The streaming JSONL variant (`--file`) is handled entirely by the CLI skin
|
|
181
|
+
* via `cliStream.rawToStdout` — it is not an op.
|
|
182
|
+
*
|
|
183
|
+
* @throws AdminApiError `missing_method_id` (400) — `methodId` is required;
|
|
184
|
+
* `invalid_file` (400) — `file` is not one of the allowed dataset file types.
|
|
185
|
+
* @example
|
|
186
|
+
* const { summary } = await admin.jewels.exportSummary({ methodId: 'triage-issue' });
|
|
187
|
+
*/
|
|
188
|
+
export declare function exportSummary(ctx: AdminContext, params: JewelsExportParams): Promise<JewelsExportResult>;
|
|
189
|
+
/**
|
|
190
|
+
* Kick off a LoRA fine-tuning run on the method's graded pairs.
|
|
191
|
+
*
|
|
192
|
+
* Returns **immediately** with a run id and dataset report (per-file row
|
|
193
|
+
* counts, exclusion buckets); the GPU trainer runs asynchronously. Poll
|
|
194
|
+
* with `getRun(run.id)` for live progress — the run's `log` carries a
|
|
195
|
+
* narrated status timeline and loss-curve points. One run per method at
|
|
196
|
+
* a time.
|
|
197
|
+
*
|
|
198
|
+
* The tuning dial comes from the method's manifest in the live release.
|
|
199
|
+
* The report's agreement is scored against the held-out ledger split —
|
|
200
|
+
* real decisions the model never saw.
|
|
201
|
+
*
|
|
202
|
+
* @throws AdminApiError `missing_method_id` (400) — `methodId` is required;
|
|
203
|
+
* `invalid_app_method` (400) — unknown method id; `no_jewel` (400) — the
|
|
204
|
+
* method has no compiled jewel in the live release.
|
|
205
|
+
* @example
|
|
206
|
+
* const { run, summary } = await admin.jewels.train({ methodId: 'triage-issue' });
|
|
207
|
+
* // poll for completion:
|
|
208
|
+
* const { run: status } = await admin.jewels.getRun(run.id);
|
|
209
|
+
*/
|
|
210
|
+
export declare function train(ctx: AdminContext, params: JewelsTrainParams): Promise<JewelsTrainResult>;
|
|
211
|
+
/**
|
|
212
|
+
* List training runs newest-first.
|
|
213
|
+
*
|
|
214
|
+
* The `log` field is serialized as `[]` in list responses; fetch a single
|
|
215
|
+
* run with `getRun` to read the full event log.
|
|
216
|
+
*
|
|
217
|
+
* @example
|
|
218
|
+
* const { runs } = await admin.jewels.runs({ methodId: 'triage-issue' });
|
|
219
|
+
*/
|
|
220
|
+
export declare function runs(ctx: AdminContext, params?: JewelsRunsParams): Promise<JewelsRunsResult>;
|
|
221
|
+
/**
|
|
222
|
+
* Get one training run with its full event log and report.
|
|
223
|
+
*
|
|
224
|
+
* The run's `log` is an append-only array of `status` (narration) and `loss`
|
|
225
|
+
* (training curve) entries — the primary polling target for `train --wait`.
|
|
226
|
+
* Status `complete` or `failed` is the terminal signal.
|
|
227
|
+
*
|
|
228
|
+
* @param runId The run id returned by `train` or `runs`.
|
|
229
|
+
* @throws AdminApiError `run_not_found` (404) — no run with this id in this app.
|
|
230
|
+
* @example
|
|
231
|
+
* const { run } = await admin.jewels.getRun(runId);
|
|
232
|
+
* if (run.status === 'complete') console.log(run.report?.grading);
|
|
233
|
+
*/
|
|
234
|
+
export declare function getRun(ctx: AdminContext, runId: string): Promise<JewelsRunResult>;
|
|
235
|
+
/**
|
|
236
|
+
* Re-grade a completed run's held-out predictions with the jewel's own grade
|
|
237
|
+
* function (the same grader as the pairs dashboard).
|
|
238
|
+
*
|
|
239
|
+
* Writes `report.grading`. Runs automatically on completion — use this as
|
|
240
|
+
* the manual retry or backfill for runs that predate the grading feature or
|
|
241
|
+
* whose fire-and-forget trigger was lost. Idempotent.
|
|
242
|
+
*
|
|
243
|
+
* @param runId The run id to grade.
|
|
244
|
+
* @throws AdminApiError `run_not_found` (404) — no run with this id in this app.
|
|
245
|
+
* @example
|
|
246
|
+
* const { grading } = await admin.jewels.grade(runId);
|
|
247
|
+
* console.log(`agreement: ${grading.agreement}`);
|
|
248
|
+
*/
|
|
249
|
+
export declare function grade(ctx: AdminContext, runId: string): Promise<JewelsGradeResult>;
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Methods operations: list (via dashboard) and invoke.
|
|
3
|
+
*
|
|
4
|
+
* Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
|
|
5
|
+
* AdminTimeoutError. No printing, no process coupling — the CLI skin in
|
|
6
|
+
* commands/methods.ts owns streaming (--stream → cliStream.streamToStdout)
|
|
7
|
+
* and user-facing error messages.
|
|
8
|
+
*/
|
|
9
|
+
import type { AdminContext } from '../ctx.js';
|
|
10
|
+
import type { DashboardReleaseMethod } from '../types/releases.js';
|
|
11
|
+
import type { MethodsInvokeResult } from '../types/methods.js';
|
|
12
|
+
/**
|
|
13
|
+
* How long an invoke waits for the method's answer: as long as the API's load
|
|
14
|
+
* balancer holds an idle connection (600 s), since a method can run for many
|
|
15
|
+
* minutes and a request can't outwait that. A method still running past it
|
|
16
|
+
* carries on; `requests list --method <id>` shows how it ended.
|
|
17
|
+
* @internal Consumed by the CLI skin; not part of the documented surface.
|
|
18
|
+
*/
|
|
19
|
+
export declare const METHOD_RUN_TIMEOUT_MS = 600000;
|
|
20
|
+
export interface MethodsInvokeParams {
|
|
21
|
+
/** The method's compiled id (e.g. `mth_abc123`), as shown by `methods.list`. */
|
|
22
|
+
methodId: string;
|
|
23
|
+
/** Input payload forwarded to the method as its first argument. */
|
|
24
|
+
input: Record<string, unknown>;
|
|
25
|
+
/** Present when --roles or --user-id is set; routes through /invoke-as. */
|
|
26
|
+
impersonate?: {
|
|
27
|
+
roles?: string[];
|
|
28
|
+
userId?: string;
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* List methods available on the live release.
|
|
33
|
+
*
|
|
34
|
+
* Fetches the dashboard endpoint and unwraps `liveRelease.methods`. Throws a
|
|
35
|
+
* plain `Error` (not AdminApiError) when the app has no live release —
|
|
36
|
+
* message: `"No live release — publish first."`.
|
|
37
|
+
*
|
|
38
|
+
* @example
|
|
39
|
+
* const methods = await admin.methods.list();
|
|
40
|
+
* const target = methods.find((m) => m.id === 'mth_abc123');
|
|
41
|
+
*/
|
|
42
|
+
export declare function list(ctx: AdminContext): Promise<DashboardReleaseMethod[]>;
|
|
43
|
+
/**
|
|
44
|
+
* Invoke a method and return its output (non-streaming).
|
|
45
|
+
*
|
|
46
|
+
* Routes to `/invoke-as` when `impersonate` is set (either `roles` or
|
|
47
|
+
* `userId` provided), allowing role-gated methods to be tested without
|
|
48
|
+
* spec edits. The streaming path in the CLI skin calls
|
|
49
|
+
* `cliStream.streamToStdout` with the same path/body construction.
|
|
50
|
+
*
|
|
51
|
+
* @throws AdminApiError `missing_impersonation` (400) — `impersonate` object
|
|
52
|
+
* is malformed; `invalid_impersonation` (400) — `impersonate.userId` or
|
|
53
|
+
* `impersonate.roles` has a bad type, or neither field is populated.
|
|
54
|
+
* @example
|
|
55
|
+
* const { output } = await admin.methods.invoke({
|
|
56
|
+
* methodId: 'mth_abc123',
|
|
57
|
+
* input: { query: 'hello' },
|
|
58
|
+
* });
|
|
59
|
+
*/
|
|
60
|
+
export declare function invoke(ctx: AdminContext, params: MethodsInvokeParams): Promise<MethodsInvokeResult>;
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Prerender operations: snapshot listing, stored-HTML view, cache invalidation.
|
|
3
|
+
*
|
|
4
|
+
* Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
|
|
5
|
+
* AdminTimeoutError. No printing, no process coupling — the CLI skin in
|
|
6
|
+
* commands/prerender.ts owns the `prerender get` crawler fetch (a public-URL
|
|
7
|
+
* bot-UA fetch that is NOT an authed API call).
|
|
8
|
+
*/
|
|
9
|
+
import type { AdminContext } from '../ctx.js';
|
|
10
|
+
import type { PrerenderInvalidateResult, PrerenderPagesResult, PrerenderViewResult } from '../types/prerender.js';
|
|
11
|
+
export interface PrerenderPagesParams {
|
|
12
|
+
/** Opaque cursor from a previous `pages` response; omit to start from the first page. */
|
|
13
|
+
cursor?: string;
|
|
14
|
+
}
|
|
15
|
+
export interface PrerenderViewParams {
|
|
16
|
+
/** App path to look up (e.g. `/u/abc123`). Must be non-empty. */
|
|
17
|
+
path: string;
|
|
18
|
+
/**
|
|
19
|
+
* The host whose copy to show, for an app serving several sites (as `pages`
|
|
20
|
+
* lists it). Omit for the copy on the app's address.
|
|
21
|
+
*/
|
|
22
|
+
host?: string;
|
|
23
|
+
}
|
|
24
|
+
export interface PrerenderInvalidateParams {
|
|
25
|
+
/**
|
|
26
|
+
* Pages to purge: paths (`/u/abc`), purged on every host the app is served
|
|
27
|
+
* on, or full URLs (`https://site-a.com/u/abc`), purged on that host only.
|
|
28
|
+
* Omit (or pass undefined) to purge every snapshot (the `--all` flag). An
|
|
29
|
+
* explicit empty array is the same as --all.
|
|
30
|
+
*/
|
|
31
|
+
paths?: string[];
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* List stored prerendered snapshots for the live release.
|
|
35
|
+
*
|
|
36
|
+
* Paginated — pass `nextCursor` from the previous response as `cursor` on
|
|
37
|
+
* the next call. Returns `{ releaseId: null, pages: [] }` (not an error)
|
|
38
|
+
* when the app has no live release.
|
|
39
|
+
*
|
|
40
|
+
* @example
|
|
41
|
+
* const { pages } = await admin.prerender.pages();
|
|
42
|
+
* console.log(`${pages.length} snapshots cached`);
|
|
43
|
+
*/
|
|
44
|
+
export declare function pages(ctx: AdminContext, params?: PrerenderPagesParams): Promise<PrerenderPagesResult>;
|
|
45
|
+
/**
|
|
46
|
+
* Retrieve the stored snapshot HTML for a single path, on one host, with the
|
|
47
|
+
* status crawlers get it with (a page that declared a 4xx is stored as one).
|
|
48
|
+
*
|
|
49
|
+
* Returns JSON (not text/html) so the snapshot cannot execute in the API
|
|
50
|
+
* origin; render the `html` field in a sandboxed iframe if displaying it.
|
|
51
|
+
*
|
|
52
|
+
* @throws AdminApiError `snapshot_not_found` (404) — no snapshot exists for
|
|
53
|
+
* that path on that host (the path is cold; trigger a render via
|
|
54
|
+
* `prerender get`); `missing_path` (400) — `path` is empty.
|
|
55
|
+
* @example
|
|
56
|
+
* const { html } = await admin.prerender.view({ path: '/u/abc123' });
|
|
57
|
+
*/
|
|
58
|
+
export declare function view(ctx: AdminContext, params: PrerenderViewParams): Promise<PrerenderViewResult>;
|
|
59
|
+
/**
|
|
60
|
+
* Purge one or more prerendered snapshots for the live release.
|
|
61
|
+
*
|
|
62
|
+
* Omit `paths` (or pass `undefined`) to purge every snapshot for the app.
|
|
63
|
+
* An empty array behaves the same as omitting. The next crawler visit to any
|
|
64
|
+
* invalidated path will trigger a fresh render.
|
|
65
|
+
*
|
|
66
|
+
* @example
|
|
67
|
+
* // Purge a specific path, on every host:
|
|
68
|
+
* await admin.prerender.invalidate({ paths: ['/u/abc123'] });
|
|
69
|
+
* // Purge it on one site only:
|
|
70
|
+
* await admin.prerender.invalidate({ paths: ['https://site-a.com/u/abc123'] });
|
|
71
|
+
* // Purge all snapshots:
|
|
72
|
+
* await admin.prerender.invalidate();
|
|
73
|
+
*/
|
|
74
|
+
export declare function invalidate(ctx: AdminContext, params?: PrerenderInvalidateParams): Promise<PrerenderInvalidateResult>;
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Branch preview share-link operations.
|
|
3
|
+
*
|
|
4
|
+
* Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
|
|
5
|
+
* AdminTimeoutError. No printing, no process coupling — the CLI skin in
|
|
6
|
+
* commands/previews.ts and the importable client both call these.
|
|
7
|
+
*/
|
|
8
|
+
import type { AdminContext } from '../ctx.js';
|
|
9
|
+
import type { PreviewShareListResult, PreviewShareResult, PreviewShareRevokeResult } from '../types/previews.js';
|
|
10
|
+
export interface PreviewShareParams {
|
|
11
|
+
/** The branch whose preview the link opens. It must have a preview build. */
|
|
12
|
+
branch: string;
|
|
13
|
+
/** Days until the link expires (default 14, max 30). */
|
|
14
|
+
days?: number;
|
|
15
|
+
/** Who the link is for, shown in the dashboard's list of the branch's links. */
|
|
16
|
+
label?: string;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Make a share link to a branch's preview.
|
|
20
|
+
*
|
|
21
|
+
* A person opens `url`. A client with no cookie jar (curl, git, CI, a test
|
|
22
|
+
* run) sends `token` as the `X-Remy-Preview` header on requests to
|
|
23
|
+
* `previewUrl`, beside the app's own `Authorization` where the app needs one.
|
|
24
|
+
* The link follows the branch, so it shows each new preview as it's pushed.
|
|
25
|
+
* `url` and `token` are returned once and can't be recovered; revoking the
|
|
26
|
+
* link shuts out both at once.
|
|
27
|
+
*
|
|
28
|
+
* @throws AdminApiError `missing_branch` (400); `no_preview_for_branch` (404) —
|
|
29
|
+
* the branch has no preview build yet.
|
|
30
|
+
* @example
|
|
31
|
+
* const { previewUrl, token } = await admin.previews.share({ branch: 'feature-x' });
|
|
32
|
+
* await fetch(`${previewUrl}/_/api/health`, { headers: { 'X-Remy-Preview': token } });
|
|
33
|
+
*/
|
|
34
|
+
export declare function share(ctx: AdminContext, params: PreviewShareParams): Promise<PreviewShareResult>;
|
|
35
|
+
/**
|
|
36
|
+
* A branch's share links, revoked and expired ones included. Never their
|
|
37
|
+
* tokens, which aren't kept.
|
|
38
|
+
*
|
|
39
|
+
* @throws AdminApiError `missing_branch` (400).
|
|
40
|
+
* @example
|
|
41
|
+
* const { links } = await admin.previews.list('feature-x');
|
|
42
|
+
*/
|
|
43
|
+
export declare function list(ctx: AdminContext, branch: string): Promise<PreviewShareListResult>;
|
|
44
|
+
/**
|
|
45
|
+
* Revoke a share link: its cookie and its token stop opening the preview at
|
|
46
|
+
* once. Revoking one already revoked keeps its first revocation.
|
|
47
|
+
*
|
|
48
|
+
* @throws AdminApiError `share_link_not_found` (404).
|
|
49
|
+
* @example
|
|
50
|
+
* await admin.previews.revoke(link.id);
|
|
51
|
+
*/
|
|
52
|
+
export declare function revoke(ctx: AdminContext, shareId: string): Promise<PreviewShareRevokeResult>;
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Browser-QA replay recordings: list what the QA agent recorded, and render a
|
|
3
|
+
* replay to an mp4.
|
|
4
|
+
*
|
|
5
|
+
* `ls` is a grouped view over `files.ls` — a replay chunk is an ordinary
|
|
6
|
+
* private file in the app's `qa-recordings` store and needs no endpoint of its
|
|
7
|
+
* own.
|
|
8
|
+
*
|
|
9
|
+
* `export` is the one operation in this SDK that does NOT go through the
|
|
10
|
+
* management API. A replay names the app's own files as the dev box that
|
|
11
|
+
* recorded it served them, signed in, so that box is what packages it for the
|
|
12
|
+
* platform to render: it has the proxy those files come from and the browser
|
|
13
|
+
* session they need. So this talks to the sandbox's local sidecar, and says so
|
|
14
|
+
* plainly when there isn't one. (CLI-only paths are established here —
|
|
15
|
+
* `methods invoke --stream`, `jewels export --file` — but this is the first
|
|
16
|
+
* that needs the local box rather than local disk.)
|
|
17
|
+
*/
|
|
18
|
+
import type { AdminContext } from '../ctx.js';
|
|
19
|
+
import type { QaRecordingsExportResult, QaRecordingsLsResult } from '../types/qaRecordings.js';
|
|
20
|
+
/** The app store QA replay chunks are written to (private). */
|
|
21
|
+
export declare const RECORDING_STORE = "qa-recordings";
|
|
22
|
+
export interface QaRecordingsLsParams {
|
|
23
|
+
/** Only this session. Omitted → every session in the store. */
|
|
24
|
+
sessionId?: string;
|
|
25
|
+
cursor?: string;
|
|
26
|
+
/** Chunk objects to scan, not sessions returned. */
|
|
27
|
+
limit?: number;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Recording sessions in this app, grouped from the chunk keys.
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* const { sessions } = await admin.qaRecordings.ls({});
|
|
34
|
+
* // → [{ sessionId, chunks, bytes, runs: [{ runId, keys }] }]
|
|
35
|
+
*/
|
|
36
|
+
export declare function ls(ctx: AdminContext, params?: QaRecordingsLsParams): Promise<QaRecordingsLsResult>;
|
|
37
|
+
export interface QaRecordingsExportParams {
|
|
38
|
+
/** The recording session to render (32 hex characters). */
|
|
39
|
+
sessionId: string;
|
|
40
|
+
/** Window of the session, as epoch milliseconds. Both required: a replay is
|
|
41
|
+
* a slice of a continuous recording, not a file. */
|
|
42
|
+
from: number;
|
|
43
|
+
to: number;
|
|
44
|
+
/** Where the mp4 is written. Defaults to `assets`, public. */
|
|
45
|
+
store?: string;
|
|
46
|
+
access?: 'public' | 'private';
|
|
47
|
+
/** Milliseconds to wait for the render. */
|
|
48
|
+
timeoutMs?: number;
|
|
49
|
+
/**
|
|
50
|
+
* How far the render is, as it runs: a line when it moves to a new phase
|
|
51
|
+
* and every 10% after, e.g. `Rendering the replay… 40%`.
|
|
52
|
+
*/
|
|
53
|
+
onProgress?: (message: string) => void;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Render a window of a recording session to an mp4.
|
|
57
|
+
*
|
|
58
|
+
* Blocks for the whole render — the box packages the replay, the platform
|
|
59
|
+
* renders it, which takes minutes for a long clip — and answers with where
|
|
60
|
+
* the video landed. Runs only on a Remy dev box, since the replay's own files
|
|
61
|
+
* are served by the box that recorded it.
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* const { url } = await admin.qaRecordings.exportVideo({
|
|
65
|
+
* sessionId, from: 1758000000000, to: 1758000042000,
|
|
66
|
+
* });
|
|
67
|
+
*/
|
|
68
|
+
export declare function exportVideo(_ctx: AdminContext, params: QaRecordingsExportParams): Promise<QaRecordingsExportResult>;
|