@madewithremy/admin 0.1.57 → 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.
Files changed (87) hide show
  1. package/CHANGELOG.md +6 -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 -6
  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 +69 -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 +21 -21
  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 +52 -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,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>;