@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,193 @@
1
+ /**
2
+ * Release operations: list, get, by-commit, dashboard live-release, and the
3
+ * composite waitForCommit op that owns the two poll loops.
4
+ *
5
+ * Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
6
+ * AdminTimeoutError (or a plain Error for application-level failures such as
7
+ * an unexpected non-404 during commit resolve). No printing, no process
8
+ * coupling — the CLI skin in commands/releases.ts and the importable client
9
+ * both call these.
10
+ */
11
+ import type { AdminContext } from '../ctx.js';
12
+ import type { ReleasesListResult, ReleasesGetResult, ReleasesByCommitResult, DashboardLiveRelease, V2ReleaseStatus } from '../types/releases.js';
13
+ export interface ReleasesListParams {
14
+ /** Max releases to return per page (default 20, clamped 1–100). */
15
+ limit?: number;
16
+ }
17
+ /**
18
+ * Paginated list of releases, newest first (non-dev only).
19
+ *
20
+ * Returns up to `limit` releases. `nextCursor` in the response is non-null
21
+ * when further pages exist; pass it as a raw query parameter to walk all pages.
22
+ *
23
+ * @example
24
+ * const { releases } = await admin.releases.list({ limit: 50 });
25
+ */
26
+ export declare function list(ctx: AdminContext, params?: ReleasesListParams): Promise<ReleasesListResult>;
27
+ /**
28
+ * Full detail for a single release by id.
29
+ *
30
+ * Includes build log, methods, interfaces, databases, a short-lived signed
31
+ * commit-diff URL, a signed Lighthouse diagnostics URL, and the async
32
+ * post-deploy progress state.
33
+ *
34
+ * @throws AdminApiError `release_not_found` (404) — no release with that id exists on this app.
35
+ * @example
36
+ * const release = await admin.releases.get('rel_abc123');
37
+ * console.log(release.status, release.buildDurationMs);
38
+ */
39
+ export declare function get(ctx: AdminContext, releaseId: string): Promise<ReleasesGetResult>;
40
+ /**
41
+ * By-commit lookup. Returns the raw tryCall result so callers can tolerate
42
+ * 404s during the resolve-grace window (used internally by waitForCommit and
43
+ * exposed for programmatic callers that want a one-shot lookup).
44
+ *
45
+ * HTTP errors arrive as `{ ok: false, status, body }` rather than thrown —
46
+ * the API returns `invalid_commit_sha` (400) for non-hex input and
47
+ * `release_not_found` (404) when the commit has no release yet.
48
+ *
49
+ * @example
50
+ * const r = await admin.releases.byCommit('91ca67a');
51
+ * if (r.ok) console.log(r.body.status);
52
+ */
53
+ export declare function byCommit(ctx: AdminContext, commitSha: string): Promise<{
54
+ ok: boolean;
55
+ status: number;
56
+ body: ReleasesByCommitResult;
57
+ }>;
58
+ /**
59
+ * The currently-live release, or null when the app has never been published.
60
+ * Fetched from the dashboard endpoint — same source as `releases current` —
61
+ * with the address it's served on as `primaryUrl` (see `primaryUrl` below).
62
+ *
63
+ * @example
64
+ * const live = await admin.releases.dashboardLive();
65
+ * if (live) console.log(live.commitSha, live.publishedAt, live.primaryUrl);
66
+ */
67
+ export declare function dashboardLive(ctx: AdminContext): Promise<(DashboardLiveRelease & {
68
+ primaryUrl: string;
69
+ }) | null>;
70
+ /**
71
+ * The URL the app is served on, as the platform resolves it: its live custom
72
+ * domain, then its platform subdomain, then its id's own host. Ends in a slash.
73
+ * Fetched from the dashboard endpoint.
74
+ *
75
+ * @example
76
+ * const url = await admin.releases.primaryUrl();
77
+ */
78
+ export declare function primaryUrl(ctx: AdminContext): Promise<string>;
79
+ /**
80
+ * Compact, stable projection of a release for the wait result.
81
+ *
82
+ * `previewUrl` is present for a feature-branch build (status 'preview') and is
83
+ * where that build is actually reachable — gated to anyone who can open the app
84
+ * in Remy. `primaryUrl` is present for a live one: the address the app is
85
+ * served on. Both are reported as data rather than taught as a URL shape, so
86
+ * the caller never has to construct one.
87
+ */
88
+ export interface ReleaseSummary {
89
+ releaseId: string;
90
+ commitSha: string;
91
+ branch: string | null;
92
+ status: V2ReleaseStatus;
93
+ buildDurationMs: number | null;
94
+ publishedAt: string | null;
95
+ previewUrl?: string;
96
+ /**
97
+ * Where the live app is served: its live custom domain, then its platform
98
+ * subdomain, then its id's own host. Only present when status is `live`.
99
+ */
100
+ primaryUrl?: string;
101
+ /** Why it failed; only present when status is `failed`. */
102
+ error?: string;
103
+ /**
104
+ * Only present when status is `failed`. 'interrupted' means a platform
105
+ * restart killed the build and a retry is already running — not a code
106
+ * problem. See ReleaseFailureFields.
107
+ */
108
+ failureKind?: 'build' | 'interrupted' | 'unbuildable';
109
+ /** Build stage that was running when it failed; only when `failed`. */
110
+ failurePhase?: string;
111
+ /**
112
+ * Each data source whose reader this live release brought live, with the
113
+ * documents it hasn't read: what `datasources reread --unread` reads, priced
114
+ * first. Absent when the release declares no reader.
115
+ */
116
+ readers?: {
117
+ slug: string;
118
+ unread: number;
119
+ }[];
120
+ }
121
+ /**
122
+ * Terminal outcome of a `waitForCommit` call.
123
+ *
124
+ * `live` — deployed to the default branch; the app is live.
125
+ * `preview` — feature-branch build finished; `summary.previewUrl` is set.
126
+ * `failed` — build error; `summary.error` carries the reason.
127
+ * `superseded` — a newer commit for this app finished first.
128
+ * `timeout` — timed out before a terminal status; `summary` has the last-known state.
129
+ * `not_found` — no release registered within the 30s resolve grace.
130
+ */
131
+ export type WaitOutcome = 'live' | 'preview' | 'failed' | 'superseded' | 'timeout' | 'not_found';
132
+ export interface WaitForCommitResult {
133
+ /** Terminal outcome; determines which other fields are populated. */
134
+ outcome: WaitOutcome;
135
+ /** Raw release row at the time of resolution; absent for `not_found`. */
136
+ release?: ReleasesByCommitResult;
137
+ /** The summarizeRelease projection; absent for `not_found`. */
138
+ summary?: ReleaseSummary;
139
+ /**
140
+ * Error message string for `not_found` and `timeout` outcomes. The CLI skin
141
+ * incorporates this into the printable output object. For `failed`, the error
142
+ * is already baked into `summary.error` by summarizeRelease.
143
+ */
144
+ error?: string;
145
+ }
146
+ export interface WaitForCommitParams {
147
+ /** Full or abbreviated (7–40 hex char) git commit SHA; the API matches by prefix. */
148
+ commitSha: string;
149
+ /** Defaults to 300 000 ms (5 min), matching the CLI's --timeout 300 default. */
150
+ timeoutMs?: number;
151
+ /**
152
+ * Called with the exact progress strings the CLI prints via progress():
153
+ * `waiting for release to be created for ${shortSha}…`
154
+ * `${status}… (Ns)`
155
+ */
156
+ onProgress?: (message: string) => void;
157
+ }
158
+ /**
159
+ * Wait for the release built from a git commit to reach a terminal state.
160
+ *
161
+ * The "publish and wait until live" primitive. Phase 1 resolves the release
162
+ * row by commit SHA, tolerating 404s for up to 30s — a SHA polled immediately
163
+ * after `git push` will briefly 404 while the receive-pack hook registers it,
164
+ * and that is expected. Phase 2 polls every 3s until the release reaches a
165
+ * terminal status or the timeout expires.
166
+ *
167
+ * Possible outcomes:
168
+ * `live` — default-branch deploy succeeded; the app is live.
169
+ * `preview` — feature-branch build finished; `summary.previewUrl` is the gated URL.
170
+ * `failed` — build failed; `summary.error` carries the last build-log error entry.
171
+ * `superseded` — a newer commit finished first and this build was skipped.
172
+ * `timeout` — `timeoutMs` elapsed before a terminal status; `summary` has the last-known state.
173
+ * `not_found` — no release created within the 30s resolve grace; the push may not have
174
+ * registered yet, or this SHA never produced a build.
175
+ *
176
+ * `onProgress` is called with a human-readable string on each poll cycle —
177
+ * the exact strings the CLI skin passes to `progress()`, so callers can echo
178
+ * them without reformatting.
179
+ *
180
+ * Throws a plain `Error` (not AdminApiError) only when Phase 1 encounters an
181
+ * unexpected non-404 HTTP error (e.g. a 500 from the API).
182
+ *
183
+ * @example
184
+ * const result = await admin.releases.waitForCommit({
185
+ * commitSha: '91ca67a',
186
+ * timeoutMs: 600_000,
187
+ * onProgress: (msg) => console.error(msg),
188
+ * });
189
+ * if (result.outcome !== 'live' && result.outcome !== 'preview') {
190
+ * throw new Error(result.error ?? result.outcome);
191
+ * }
192
+ */
193
+ export declare function waitForCommit(ctx: AdminContext, params: WaitForCommitParams): Promise<WaitForCommitResult>;
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Request log + method metrics 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/requests.ts and the importable client both call these.
7
+ */
8
+ import type { AdminContext } from '../ctx.js';
9
+ import type { RequestsListResult, RequestsGetResult, RequestsStatsSummaryResult, RequestsStatsMethodResult } from '../types/requests.js';
10
+ export interface RequestsListParams {
11
+ /** Filter to a single method id (e.g. `mth_abc123`). */
12
+ methodId?: string;
13
+ /** `'success'` or `'error'` — omit to return all statuses. */
14
+ status?: string;
15
+ /** Maximum rows to return (default 50). */
16
+ limit?: number;
17
+ /** Row offset for pagination (default 0). */
18
+ offset?: number;
19
+ /** Keyset cursor from a previous page's `nextCursor`. */
20
+ cursor?: string;
21
+ }
22
+ export interface MetricsWindowParams {
23
+ /** Window start as an ISO 8601 date string (inclusive). */
24
+ start?: string;
25
+ /** Window end as an ISO 8601 date string (inclusive). */
26
+ end?: string;
27
+ }
28
+ /**
29
+ * Recent request log entries, optionally filtered by method or status.
30
+ *
31
+ * Results are cursor-paginated — check `nextCursor` to page forward. Default
32
+ * `limit` is 50 and `offset` is 0. A run's `id` is also its request-log id,
33
+ * so `requests.get(id)` drills into the full payload for any interface
34
+ * (cron, api, agent, …).
35
+ *
36
+ * @example
37
+ * const { requests } = await admin.requests.list({ status: 'error', limit: 10 });
38
+ */
39
+ export declare function list(ctx: AdminContext, params?: RequestsListParams): Promise<RequestsListResult>;
40
+ /**
41
+ * Full request log entry — input, output, stdout, error, and interface context.
42
+ *
43
+ * @param requestId The request id (e.g. from `list`, or the `requestId`
44
+ * returned by `cron.run`).
45
+ * @throws AdminApiError `not_found` (404) — the request id does not exist or
46
+ * belongs to a different app.
47
+ * @example
48
+ * const entry = await admin.requests.get('req_abc123');
49
+ */
50
+ export declare function get(ctx: AdminContext, requestId: string): Promise<RequestsGetResult>;
51
+ /**
52
+ * Aggregated metrics for the whole app over a time window.
53
+ *
54
+ * Returns per-bucket totals, per-method breakdowns with sparklines,
55
+ * per-error-type counts, and interface distribution. When `start`/`end` are
56
+ * omitted the server applies its own default window.
57
+ *
58
+ * @example
59
+ * const { totals, byMethod } = await admin.requests.statsSummary();
60
+ */
61
+ export declare function statsSummary(ctx: AdminContext, params?: MetricsWindowParams): Promise<RequestsStatsSummaryResult>;
62
+ /**
63
+ * Per-method time-series metrics over a time window.
64
+ *
65
+ * Returns per-bucket counts (including `successCount`, which is absent from
66
+ * the app-summary buckets), overall totals, and an error-type breakdown.
67
+ * When `start`/`end` are omitted the server applies its own default window.
68
+ *
69
+ * @param methodId The method id to scope the query (e.g. `mth_abc123`).
70
+ * @example
71
+ * const { buckets, totals } = await admin.requests.statsForMethod('mth_abc123');
72
+ */
73
+ export declare function statsForMethod(ctx: AdminContext, methodId: string, params?: MetricsWindowParams): Promise<RequestsStatsMethodResult>;
@@ -0,0 +1,69 @@
1
+ /**
2
+ * App secrets operations: list, read, write, and delete encrypted key/value pairs.
3
+ *
4
+ * `SecretsSetParams` allows `null` values to explicitly clear an environment's
5
+ * stored value (mapped from the CLI's `--dev-clear` / `--prod-clear` flags).
6
+ * The key presence check (at least one of devValue/prodValue) stays in the skin.
7
+ *
8
+ * Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
9
+ * AdminTimeoutError. No printing, no process coupling.
10
+ */
11
+ import type { AdminContext } from '../ctx.js';
12
+ import type { SecretsListResult, SecretsGetResult, SecretsSetResult, SecretsDeleteResult } from '../types/secrets.js';
13
+ /**
14
+ * List all secret keys for the app (values are not returned — use `get` to
15
+ * retrieve decrypted values for a specific key).
16
+ *
17
+ * @example
18
+ * const { secrets } = await admin.secrets.list();
19
+ * const withProd = secrets.filter((s) => s.hasProdValue);
20
+ */
21
+ export declare function list(ctx: AdminContext): Promise<SecretsListResult>;
22
+ /**
23
+ * Get the decrypted dev and prod values for a secret key.
24
+ *
25
+ * This call is audited as a `secret.reveal` event on the workspace.
26
+ *
27
+ * @throws AdminApiError `secret_not_found` (404).
28
+ * @example
29
+ * const { devValue, prodValue } = await admin.secrets.get('STRIPE_SECRET_KEY');
30
+ */
31
+ export declare function get(ctx: AdminContext, key: string): Promise<SecretsGetResult>;
32
+ export interface SecretsSetParams {
33
+ /**
34
+ * Value for the dev environment; `null` clears the stored dev value;
35
+ * omitting the field leaves the dev value unchanged.
36
+ */
37
+ devValue?: string | null;
38
+ /**
39
+ * Value for the prod environment; `null` clears the stored prod value;
40
+ * omitting the field leaves the prod value unchanged.
41
+ */
42
+ prodValue?: string | null;
43
+ }
44
+ /**
45
+ * Create or update a secret's value for dev and/or prod (merge semantics —
46
+ * environments you omit are not changed).
47
+ *
48
+ * Active sandboxes are invalidated so they reprovision with the updated values.
49
+ * Key must match `[A-Z][A-Z0-9_]{0,99}` (validated server-side).
50
+ *
51
+ * @throws AdminApiError `invalid_key` (400) — the key does not match
52
+ * `[A-Z][A-Z0-9_]{0,99}`; `missing_value` (400) — neither devValue nor
53
+ * prodValue was provided.
54
+ * @example
55
+ * await admin.secrets.set('STRIPE_SECRET_KEY', { devValue: 'sk_test_…', prodValue: 'sk_live_…' });
56
+ * // Clear just the dev value:
57
+ * await admin.secrets.set('STRIPE_SECRET_KEY', { devValue: null });
58
+ */
59
+ export declare function set(ctx: AdminContext, key: string, params: SecretsSetParams): Promise<SecretsSetResult>;
60
+ /**
61
+ * Delete a secret entirely (removes both dev and prod values).
62
+ *
63
+ * Active sandboxes are invalidated. Silently succeeds if the key does not
64
+ * exist.
65
+ *
66
+ * @example
67
+ * await admin.secrets.del('OLD_KEY');
68
+ */
69
+ export declare function del(ctx: AdminContext, key: string): Promise<SecretsDeleteResult>;
@@ -0,0 +1,45 @@
1
+ /**
2
+ * App settings operations: get and update the app's v2_settings jsonb.
3
+ *
4
+ * Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
5
+ * AdminTimeoutError. No printing, no process coupling — the CLI skin in
6
+ * commands/settings.ts and the importable client both call these.
7
+ */
8
+ import type { AdminContext } from '../ctx.js';
9
+ import type { V2AppSettings } from '../types/settings.js';
10
+ /**
11
+ * Get all V2AppSettings for this app.
12
+ *
13
+ * Returns the current state of every dashboard-controlled toggle: signup
14
+ * allowlist, test accounts, frame-ancestors, disposable-email blocking,
15
+ * telemetry capture, and more. See `V2AppSettings` in `types/settings.ts`
16
+ * for the full field set and per-field semantics.
17
+ *
18
+ * @example
19
+ * const settings = await admin.settings.getSettings();
20
+ * console.log(settings.blockDisposableEmails);
21
+ */
22
+ export declare function getSettings(ctx: AdminContext): Promise<V2AppSettings>;
23
+ /**
24
+ * Apply a partial update to the app's V2AppSettings.
25
+ *
26
+ * The server validates and normalizes security-shaped values before writing:
27
+ * signup-allowlist entries must be `*@domain.com` or `user@domain.com`; test
28
+ * accounts require a valid email or E.164 identifier and a 6-digit code (max
29
+ * 5 entries); frame-ancestor entries must be exact `https://` origins (max
30
+ * 25). Unknown keys in `partial` are silently dropped. Returns the full
31
+ * settings after the update.
32
+ *
33
+ * `partial` is deliberately untyped: the CLI escape-hatch `settings set`
34
+ * forwards arbitrary keys for the route to validate; a strict `V2AppSettings`
35
+ * body would reject that use.
36
+ *
37
+ * @throws AdminApiError `invalid_signup_allowlist` (400) — malformed entry or
38
+ * non-array value; `invalid_test_accounts` (400) — invalid identifier/code,
39
+ * duplicate identifier, or over the 5-entry cap;
40
+ * `invalid_frame_ancestors` (400) — not a valid https origin or over the
41
+ * 25-entry cap.
42
+ * @example
43
+ * const updated = await admin.settings.updateSettings({ blockDisposableEmails: false });
44
+ */
45
+ export declare function updateSettings(ctx: AdminContext, partial: Record<string, unknown>): Promise<V2AppSettings>;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Task log operations: every task agent (`runTask`) the app ran.
3
+ *
4
+ * Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
5
+ * AdminTimeoutError. No printing, no process coupling — the CLI skin in
6
+ * commands/tasks.ts and the importable client both call these.
7
+ */
8
+ import type { AdminContext } from '../ctx.js';
9
+ import type { TasksListResult, TasksGetResult } from '../types/tasks.js';
10
+ export interface TasksListParams {
11
+ /** Max traces per page (default 20, server clamps to 100). */
12
+ limit?: number;
13
+ /** Pagination cursor from a prior page's `nextCursor`. */
14
+ cursor?: string;
15
+ }
16
+ /**
17
+ * Every task the app ran, newest started first, kept for 90 days.
18
+ *
19
+ * Returns cursored pages; pass `nextCursor` from one page as `cursor` for the
20
+ * next. Transcripts are not included — fetch one with `get`.
21
+ *
22
+ * `outcome`, `toolErrorCount` and `hasTurnError` are how you find the runs
23
+ * worth reading, and `devSession` separates your own dev runs from real
24
+ * traffic.
25
+ *
26
+ * @example
27
+ * const { traces } = await admin.tasks.list({ limit: 10 });
28
+ * const broken = traces.filter((t) => t.outcome !== 'answered' || t.toolErrorCount > 0);
29
+ */
30
+ export declare function list(ctx: AdminContext, params?: TasksListParams): Promise<TasksListResult>;
31
+ /**
32
+ * One task with its full transcript: the prompt and tools it was given, its
33
+ * input, each turn's reply and reasoning, and every tool call with what came
34
+ * back.
35
+ *
36
+ * This is the primary tool for iterating on a task agent's prompt and tool
37
+ * descriptions — read what actually happened rather than guessing. A method
38
+ * tool's result carries a `requestId`; pass it to `requests.get()` for that
39
+ * call's input, output, stdout and error. `result.traceId` from `runTask()`
40
+ * is the id.
41
+ *
42
+ * @throws AdminApiError `task_trace_not_found` (404).
43
+ * @example
44
+ * const trace = await admin.tasks.get('0b9e…');
45
+ * console.log(trace.outcome, trace.messages);
46
+ */
47
+ export declare function get(ctx: AdminContext, traceId: string): Promise<TasksGetResult>;
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Usage operations: what the app costs to run.
3
+ *
4
+ * Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
5
+ * AdminTimeoutError. No printing, no process coupling — the CLI skin in
6
+ * commands/usage.ts and the importable client both call these.
7
+ */
8
+ import type { AdminContext } from '../ctx.js';
9
+ import type { UsageGroupBy, UsageSummaryResult } from '../types/usage.js';
10
+ export interface UsageSummaryParams {
11
+ /** Window start, ISO 8601. */
12
+ startTime: string;
13
+ /** Window end, ISO 8601, after `startTime`. */
14
+ endTime: string;
15
+ /**
16
+ * The breakdown (default `method`): `method` is the spend each method
17
+ * drove, `model` the models' share, `step` the whole spend by action,
18
+ * models and everything else.
19
+ */
20
+ groupBy?: UsageGroupBy;
21
+ }
22
+ /**
23
+ * The app's runtime spend over a window, broken down one way, in dollars.
24
+ * Remy's own work on the app isn't counted: building it, testing it in the
25
+ * sandbox, and its security assessments.
26
+ *
27
+ * In a method, needs the `usage.view` admin permission.
28
+ *
29
+ * @throws AdminApiError `invalid_window` (400) — a date that doesn't parse, or
30
+ * an end not after the start; `invalid_group_by` (400);
31
+ * `admin_permission_required:usage.view` (403) — a method that doesn't
32
+ * declare it.
33
+ * @example
34
+ * const { totalCostDollars, groups } = await admin.usage.summary({
35
+ * startTime: '2026-10-01T00:00:00Z',
36
+ * endTime: '2026-11-01T00:00:00Z',
37
+ * groupBy: 'method',
38
+ * });
39
+ */
40
+ export declare function summary(ctx: AdminContext, params: UsageSummaryParams): Promise<UsageSummaryResult>;
@@ -0,0 +1,59 @@
1
+ /**
2
+ * App users operations: list, role management, API key lifecycle.
3
+ *
4
+ * Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
5
+ * AdminTimeoutError. No printing, no process coupling — the CLI skin in
6
+ * commands/users.ts and the importable client both call these.
7
+ */
8
+ import type { AdminContext } from '../ctx.js';
9
+ import type { UsersListResult, UsersSetRoleResult, UsersCreateApiKeyResult, UsersRevokeApiKeyResult } from '../types/users.js';
10
+ export interface UsersListParams {
11
+ /** Max users to return per page (server default 50, clamped to 200). */
12
+ limit?: number;
13
+ /** Zero-based page offset. */
14
+ offset?: number;
15
+ }
16
+ /**
17
+ * All app-managed users with their roles and masked API-key status.
18
+ *
19
+ * @example
20
+ * const { users } = await admin.users.list({ limit: 20 });
21
+ * const admins = users.filter((u) => u.roles.includes('admin'));
22
+ */
23
+ export declare function list(ctx: AdminContext, params?: UsersListParams): Promise<UsersListResult>;
24
+ /**
25
+ * Replace a user's role set with a single role.
26
+ *
27
+ * Sends `roles: [role]` — the array replaces the user's entire prior role
28
+ * list. The updated user record is returned.
29
+ *
30
+ * @throws AdminApiError `user_not_found` (404) — the user does not belong to
31
+ * this app; `invalid_roles` (400) — the roles field was malformed.
32
+ * @example
33
+ * const { user } = await admin.users.setRole('usr_abc123', 'admin');
34
+ */
35
+ export declare function setRole(ctx: AdminContext, userId: string, role: string): Promise<UsersSetRoleResult>;
36
+ /**
37
+ * Generate an API key for a user; the full plaintext `key` is returned exactly
38
+ * once — only the masked form is stored after this call.
39
+ *
40
+ * Requires the app's live release to have the `api-key` auth method enabled.
41
+ *
42
+ * @throws AdminApiError `user_not_found` (404) — the user does not belong to
43
+ * this app; `auth_method_not_enabled` (400) — the `api-key` auth method is
44
+ * not enabled on the app's live release.
45
+ * @example
46
+ * const { key } = await admin.users.createApiKey('usr_abc123');
47
+ * // Store `key` immediately — it cannot be retrieved again.
48
+ */
49
+ export declare function createApiKey(ctx: AdminContext, userId: string): Promise<UsersCreateApiKeyResult>;
50
+ /**
51
+ * Revoke a user's API key; takes effect immediately — in-flight requests using
52
+ * the key will fail.
53
+ *
54
+ * @throws AdminApiError `user_not_found` (404) — the user does not belong to
55
+ * this app.
56
+ * @example
57
+ * await admin.users.revokeApiKey('usr_abc123');
58
+ */
59
+ export declare function revokeApiKey(ctx: AdminContext, userId: string): Promise<UsersRevokeApiKeyResult>;