@madewithremy/admin 0.1.57 → 0.1.59

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client.d.ts +199 -0
  4. package/dist/config.d.ts +8 -0
  5. package/dist/ctx.d.ts +36 -0
  6. package/dist/errors.d.ts +68 -0
  7. package/dist/http.d.ts +68 -0
  8. package/dist/index.d.ts +7 -9442
  9. package/dist/index.js +6 -14
  10. package/dist/index.js.map +7 -1
  11. package/dist/ops/agent.d.ts +44 -0
  12. package/dist/ops/analytics.d.ts +285 -0
  13. package/dist/ops/apps.d.ts +33 -0
  14. package/dist/ops/crashes.d.ts +86 -0
  15. package/dist/ops/cron.d.ts +40 -0
  16. package/dist/ops/data.d.ts +68 -0
  17. package/dist/ops/dataSourceConnectors.d.ts +80 -0
  18. package/dist/ops/dataSourceEvals.d.ts +208 -0
  19. package/dist/ops/dataSourceJobs.d.ts +141 -0
  20. package/dist/ops/dataSourceMappers.d.ts +125 -0
  21. package/dist/ops/dataSources.d.ts +654 -0
  22. package/dist/ops/db.d.ts +81 -0
  23. package/dist/ops/diagnostics.d.ts +42 -0
  24. package/dist/ops/domains.d.ts +250 -0
  25. package/dist/ops/email.d.ts +305 -0
  26. package/dist/ops/events.d.ts +56 -0
  27. package/dist/ops/feedback.d.ts +24 -0
  28. package/dist/ops/files.d.ts +166 -0
  29. package/dist/ops/infra.d.ts +163 -0
  30. package/dist/ops/issues.d.ts +160 -0
  31. package/dist/ops/jewels.d.ts +249 -0
  32. package/dist/ops/methods.d.ts +60 -0
  33. package/dist/ops/prerender.d.ts +74 -0
  34. package/dist/ops/previews.d.ts +52 -0
  35. package/dist/ops/qaRecordings.d.ts +68 -0
  36. package/dist/ops/releases.d.ts +193 -0
  37. package/dist/ops/requests.d.ts +73 -0
  38. package/dist/ops/secrets.d.ts +61 -0
  39. package/dist/ops/settings.d.ts +45 -0
  40. package/dist/ops/tasks.d.ts +47 -0
  41. package/dist/ops/usage.d.ts +40 -0
  42. package/dist/ops/users.d.ts +59 -0
  43. package/dist/ops/voice.d.ts +178 -0
  44. package/dist/output.d.ts +19 -0
  45. package/dist/parseJsonConfig.d.ts +41 -0
  46. package/dist/poll.d.ts +38 -0
  47. package/dist/prod.js +39 -55
  48. package/dist/runningMethod.d.ts +25 -0
  49. package/dist/sleep.d.ts +12 -0
  50. package/dist/types/agent.d.ts +95 -0
  51. package/dist/types/analytics.d.ts +225 -0
  52. package/dist/types/apps.d.ts +39 -0
  53. package/dist/types/crashes.d.ts +81 -0
  54. package/dist/types/cron.d.ts +68 -0
  55. package/dist/types/data.d.ts +38 -0
  56. package/dist/types/dataSourceConnectors.d.ts +59 -0
  57. package/dist/types/dataSourceEvals.d.ts +225 -0
  58. package/dist/types/dataSourceJobs.d.ts +283 -0
  59. package/dist/types/dataSourceMappers.d.ts +204 -0
  60. package/dist/types/dataSourceReaders.d.ts +102 -0
  61. package/dist/types/dataSources.d.ts +627 -0
  62. package/dist/types/db.d.ts +63 -0
  63. package/dist/types/diagnostics.d.ts +96 -0
  64. package/dist/types/domains.d.ts +277 -0
  65. package/dist/types/email.d.ts +400 -0
  66. package/dist/types/events.d.ts +54 -0
  67. package/dist/types/feedback.d.ts +11 -0
  68. package/dist/types/files.d.ts +150 -0
  69. package/dist/types/index.d.ts +37 -0
  70. package/dist/types/infra.d.ts +188 -0
  71. package/dist/types/issues.d.ts +106 -0
  72. package/dist/types/jewels.d.ts +336 -0
  73. package/dist/types/methods.d.ts +34 -0
  74. package/dist/types/prerender.d.ts +59 -0
  75. package/dist/types/previews.d.ts +39 -0
  76. package/dist/types/progress.d.ts +31 -0
  77. package/dist/types/qaRecordings.d.ts +51 -0
  78. package/dist/types/releases.d.ts +233 -0
  79. package/dist/types/requests.d.ts +114 -0
  80. package/dist/types/secrets.d.ts +42 -0
  81. package/dist/types/settings.d.ts +79 -0
  82. package/dist/types/tasks.d.ts +99 -0
  83. package/dist/types/usage.d.ts +29 -0
  84. package/dist/types/users.d.ts +61 -0
  85. package/dist/types/voice.d.ts +197 -0
  86. package/dist/upload.d.ts +11 -0
  87. package/package.json +7 -10
package/CHANGELOG.md CHANGED
@@ -4,6 +4,18 @@ What changed in `@madewithremy/admin`, newest first, each version under its own
4
4
 
5
5
  Versions before 0.1.44 aren't recorded here.
6
6
 
7
+ ## 0.1.59
8
+
9
+ ### Changed behavior
10
+
11
+ - Secret values are write-only. `remy-admin secrets get` and `admin.secrets.get` are gone, and so is the api route behind them, so an older version's `get` answers 404. `secrets list` still says which environments have a value, and `secrets set` replaces one. An app's code still reads its secrets as environment variables. Check for: a script or method that read a value back through `get`, which now has to keep its own copy or be given the value another way.
12
+
13
+ ## 0.1.58
14
+
15
+ ### Changed behavior
16
+
17
+ - Built with esbuild and the TypeScript compiler rather than tsup. The client's types are a `.d.ts` file for each source file, behind the same `types` path, in place of one combined file. The CLI and the client behave as before.
18
+
7
19
  ## 0.1.57
8
20
 
9
21
  ### New
package/README.md CHANGED
@@ -86,7 +86,7 @@ Every response is fully typed (the shapes are hand-transcribed from the platform
86
86
  ```bash
87
87
  npm install
88
88
  npm run typecheck
89
- npm run build # tsup → dist/index.js (+ d.ts) and dist/prod.js (bin)
89
+ npm run build # esbuild → dist/index.js (+ d.ts from tsc) and dist/prod.js (bin)
90
90
  node dist/prod.js --help
91
91
  ```
92
92
 
@@ -0,0 +1,199 @@
1
+ /**
2
+ * The importable admin client: every CLI command as a typed method, bound to
3
+ * one app. Namespaces mirror the CLI groups 1:1 — `remy-admin requests list`
4
+ * is `admin.requests.list(...)` — so there is exactly one mental model.
5
+ *
6
+ * The client is a thin binding layer: each namespace is its ops module with
7
+ * the AdminContext applied on every call. Ops throw AdminApiError /
8
+ * AdminTimeoutError; nothing here prints, exits, or streams (the CLI-only
9
+ * streaming passthroughs live in cliStream.ts and are deliberately not
10
+ * exposed).
11
+ *
12
+ * Which context a call runs with is decided per call: an `apiKey` the client
13
+ * was given; otherwise, inside an app's running method, that run's own
14
+ * credential (`runningMethod.ts`); otherwise `MINDSTUDIO_API_KEY` and the
15
+ * workspace's mindstudio.json. Per call, so a client made once at module scope
16
+ * follows each execution of the method rather than keeping the first one's.
17
+ */
18
+ import { type AdminContext } from './ctx.js';
19
+ import * as agent from './ops/agent.js';
20
+ import * as tasks from './ops/tasks.js';
21
+ import * as analytics from './ops/analytics.js';
22
+ import * as apps from './ops/apps.js';
23
+ import * as appEvents from './ops/events.js';
24
+ import * as crashes from './ops/crashes.js';
25
+ import * as cron from './ops/cron.js';
26
+ import * as feedback from './ops/feedback.js';
27
+ import * as data from './ops/data.js';
28
+ import * as dataSources from './ops/dataSources.js';
29
+ import * as dataSourceJobs from './ops/dataSourceJobs.js';
30
+ import * as dataSourceConnectors from './ops/dataSourceConnectors.js';
31
+ import * as dataSourceEvals from './ops/dataSourceEvals.js';
32
+ import * as dataSourceMappers from './ops/dataSourceMappers.js';
33
+ import * as db from './ops/db.js';
34
+ import * as diagnostics from './ops/diagnostics.js';
35
+ import * as domains from './ops/domains.js';
36
+ import * as email from './ops/email.js';
37
+ import * as files from './ops/files.js';
38
+ import * as infra from './ops/infra.js';
39
+ import * as issues from './ops/issues.js';
40
+ import * as jewels from './ops/jewels.js';
41
+ import * as methods from './ops/methods.js';
42
+ import * as prerender from './ops/prerender.js';
43
+ import * as previews from './ops/previews.js';
44
+ import * as qaRecordings from './ops/qaRecordings.js';
45
+ import * as releases from './ops/releases.js';
46
+ import * as requests from './ops/requests.js';
47
+ import * as secrets from './ops/secrets.js';
48
+ import * as settings from './ops/settings.js';
49
+ import * as usage from './ops/usage.js';
50
+ import * as users from './ops/users.js';
51
+ import * as voice from './ops/voice.js';
52
+ export interface AdminClientOptions {
53
+ /**
54
+ * Org-scoped `sk_` API key. Inside an app's method, leave it out: the
55
+ * method's own run is the credential, holding the `adminPermissions` its
56
+ * `mindstudio.json` entry declares. Elsewhere it falls back to
57
+ * MINDSTUDIO_API_KEY.
58
+ */
59
+ apiKey?: string;
60
+ /**
61
+ * The app to manage. Inside a method, the method's own app. Elsewhere it
62
+ * falls back to the workspace's mindstudio.json — pass explicitly anywhere
63
+ * that file doesn't exist.
64
+ */
65
+ appId?: string;
66
+ /**
67
+ * API origin. Inside a method, the api the run calls back on. Elsewhere it
68
+ * falls back to MINDSTUDIO_BASE_URL, then the production default.
69
+ */
70
+ baseUrl?: string;
71
+ }
72
+ /** The context one call runs with. */
73
+ type ContextSource = () => Promise<AdminContext>;
74
+ /** An ops module with the AdminContext applied to every function. */
75
+ type BoundOps<T> = {
76
+ [K in keyof T as T[K] extends (ctx: AdminContext, ...args: never[]) => unknown ? K : never]: T[K] extends (ctx: AdminContext, ...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
77
+ };
78
+ declare function buildClient(source: ContextSource, context: AdminContext | null): {
79
+ /**
80
+ * The context the client uses outside a running method: its options, or
81
+ * the environment. Null when neither names a key, as in a method, where
82
+ * each call takes the run's own.
83
+ */
84
+ context: Readonly<AdminContext> | null;
85
+ /**
86
+ * A sibling client for another app, sharing credentials.
87
+ *
88
+ * The app we came from becomes the origin, so a write through the returned
89
+ * client records which app acted — the same rule the CLI's `--app` follows.
90
+ * Chaining `forApp` twice keeps the FIRST app as the origin, since that is
91
+ * the one whose workspace this code is running in. A method's own
92
+ * credential acts on its own app only, so from a method this needs a key.
93
+ */
94
+ forApp(appId: string): /*elided*/ any;
95
+ agent: BoundOps<typeof agent>;
96
+ tasks: BoundOps<typeof tasks>;
97
+ analytics: BoundOps<typeof analytics>;
98
+ apps: BoundOps<typeof apps>;
99
+ events: BoundOps<typeof appEvents>;
100
+ crashes: BoundOps<typeof crashes>;
101
+ cron: BoundOps<typeof cron>;
102
+ feedback: BoundOps<typeof feedback>;
103
+ data: BoundOps<typeof data>;
104
+ dataSources: BoundOps<typeof dataSources>;
105
+ dataSourceJobs: BoundOps<typeof dataSourceJobs>;
106
+ dataSourceConnectors: BoundOps<typeof dataSourceConnectors>;
107
+ dataSourceEvals: BoundOps<typeof dataSourceEvals>;
108
+ dataSourceMappers: BoundOps<typeof dataSourceMappers>;
109
+ db: BoundOps<typeof db>;
110
+ diagnostics: BoundOps<typeof diagnostics>;
111
+ domains: BoundOps<typeof domains>;
112
+ email: {
113
+ list: (params?: email.EmailListParams | undefined) => Promise<import("./index.js").EmailListResult>;
114
+ get: (messageId: string) => Promise<import("./index.js").V2EmailMessage>;
115
+ stats: (params?: email.EmailWindowParams | undefined) => Promise<import("./index.js").EmailSummary>;
116
+ status: () => Promise<import("./index.js").EmailSendingStatusResult>;
117
+ batches: (params?: email.EmailBatchesParams | undefined) => Promise<import("./index.js").EmailBatchesResult>;
118
+ batch: (batchId: string) => Promise<import("./index.js").EmailBatchSummary>;
119
+ suppressions: (params?: email.EmailSuppressionsParams | undefined) => Promise<import("./index.js").EmailSuppressionsResult>;
120
+ suppress: (email: string) => Promise<import("./index.js").EmailSuppressResult>;
121
+ unsuppress: (email: string) => Promise<import("./index.js").EmailUnsuppressResult>;
122
+ inbox: (params?: email.EmailInboxParams | undefined) => Promise<import("./index.js").EmailInboxResult>;
123
+ listDomains: <D extends email.DomainDirection>(direction: D) => Promise<email.ForDirection<D, import("./index.js").OutboundEmailDomainsListResult, import("./index.js").InboundEmailDomainsListResult>>;
124
+ checkDomain: <D extends email.DomainDirection>(direction: D, domain: string) => Promise<email.ForDirection<D, import("./index.js").OutboundEmailDomainCheckResult, import("./index.js").InboundEmailDomainCheckResult>>;
125
+ addDomain: <D extends email.DomainDirection>(direction: D, domain: string) => Promise<email.ForDirection<D, import("./index.js").OutboundEmailDomainAddResult, import("./index.js").InboundEmailDomainAddResult>>;
126
+ verifyDomain: <D extends email.DomainDirection>(direction: D, domain: string) => Promise<email.ForDirection<D, import("./index.js").OutboundEmailDomainAddResult, import("./index.js").InboundEmailDomainAddResult>>;
127
+ removeDomain: <D extends email.DomainDirection>(direction: D, domain: string) => Promise<email.ForDirection<D, import("./index.js").OutboundEmailDomainDeleteResult, import("./index.js").InboundEmailDomainDeleteResult>>;
128
+ };
129
+ files: BoundOps<typeof files>;
130
+ infra: BoundOps<typeof infra>;
131
+ issues: BoundOps<typeof issues>;
132
+ jewels: BoundOps<typeof jewels>;
133
+ methods: BoundOps<typeof methods>;
134
+ prerender: BoundOps<typeof prerender>;
135
+ previews: BoundOps<typeof previews>;
136
+ qaRecordings: BoundOps<typeof qaRecordings>;
137
+ releases: BoundOps<typeof releases>;
138
+ requests: BoundOps<typeof requests>;
139
+ secrets: BoundOps<typeof secrets>;
140
+ settings: BoundOps<typeof settings>;
141
+ usage: BoundOps<typeof usage>;
142
+ users: BoundOps<typeof users>;
143
+ voice: BoundOps<typeof voice>;
144
+ };
145
+ export type AdminClient = ReturnType<typeof buildClient>;
146
+ /**
147
+ * Create a client bound to one app.
148
+ *
149
+ * Inside an app's method, with no options, it acts on the method's own app as
150
+ * the method's own run: no key in the app's secrets. Each operation needs the
151
+ * admin permission the method declares in `mindstudio.json`
152
+ * (`"adminPermissions": ["analytics.view"]`), and an undeclared one fails with
153
+ * `admin_permission_required:<name>`.
154
+ *
155
+ * The admin permissions, by the client namespaces they open (`.manage`
156
+ * includes its `.view`):
157
+ *
158
+ * | Admin permission | Opens |
159
+ * |---|---|
160
+ * | `analytics.view` | `analytics` |
161
+ * | `usage.view` | `usage` |
162
+ * | `requests.view` | `requests`, `crashes` |
163
+ * | `agent.view` / `tasks.view` | `agent` / `tasks` |
164
+ * | `voice.view` / `voice.manage` | `voice` reads: call log, transcripts, settings, numbers list / buying, releasing and naming numbers, settings writes |
165
+ * | `users.view` / `users.manage` | `users` reads / roles and app-user API keys, live runs only (`admin_permission_live_only:users.manage` from dev or a preview) |
166
+ * | `settings.manage` | `settings` |
167
+ * | `email.view` / `email.manage` | `email` reads: log, batches, status, inbox, domains list / suppressions and the sending and receiving domains |
168
+ * | `domains.manage` | `domains`' custom domains and subdomain (not buying domains, which is the workspace's) |
169
+ * | `issues.view` / `issues.manage` | `issues` on this app, reads / writes as the app |
170
+ * | `datasources.manage` | `dataSources` and its jobs, connectors, evals, mappers and readers |
171
+ * | `cron.view` / `cron.manage` | `cron` overview / run now |
172
+ * | `releases.view` | `releases`, `diagnostics`' release reads |
173
+ *
174
+ * The rules:
175
+ * - Only the method's own app: `forApp()` and another `appId` get
176
+ * `app_credential_wrong_app`. Another app or the workspace needs a key.
177
+ * - Not in a jewel's shadow run or a data source's mapper or reader run
178
+ * (`admin_permission_unavailable`).
179
+ * - Publishing the declaration is the consent, and any visitor who can call
180
+ * the method can make it use what it holds, so gate the method accordingly.
181
+ * - Never an admin permission: secrets (a method has its own in
182
+ * `process.env`) and builder operations (deploys, data lifts, previews,
183
+ * infra, jewel training). What `@mindstudio-ai/agent` already does needs
184
+ * none.
185
+ *
186
+ * ```ts
187
+ * import { createAdminClient } from '@madewithremy/admin';
188
+ *
189
+ * // In a method declaring "adminPermissions": ["analytics.view"]
190
+ * const admin = createAdminClient();
191
+ * const live = await admin.analytics.live();
192
+ *
193
+ * // Anywhere else, with a workspace API key
194
+ * const other = createAdminClient({ apiKey: 'sk_…', appId: 'app_…' });
195
+ * const { releases } = await other.releases.list({ limit: 5 });
196
+ * ```
197
+ */
198
+ export declare function createAdminClient(options?: AdminClientOptions): AdminClient;
199
+ export {};
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Local-environment locations for the commands that touch the box rather than
3
+ * the management API: the workspace (files put/get, datasources add, releases
4
+ * wait's git HEAD sniff) and the sandbox sidecar (qa-recordings export). API
5
+ * credentials and appId resolution live in ctx.ts.
6
+ */
7
+ export declare const WORKSPACE_DIR: string;
8
+ export declare const SIDECAR_URL: string;
package/dist/ctx.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The bound context every operation runs against: which app, as whom, where.
3
+ *
4
+ * Ops in src/ops/ take this as their first argument and are otherwise pure —
5
+ * no env reads, no process coupling — so the same functions serve both the
6
+ * CLI (context from the environment, built once in prod.ts) and the importable
7
+ * client (context from createAdminClient's options).
8
+ */
9
+ export interface AdminContext {
10
+ /** Org-scoped `sk_` API key. */
11
+ apiKey: string;
12
+ /** The app every operation is scoped to. */
13
+ appId: string;
14
+ /**
15
+ * Who is acting, when that is not `appId` itself — set only when the caller
16
+ * has retargeted at another app (`--app`, or `forApp()`), and carrying the
17
+ * app they came FROM.
18
+ *
19
+ * Writes that record authorship attach it, so a cross-app issue says which
20
+ * app filed it without the caller having to remember a second flag. That
21
+ * matters more than it sounds: the information was always available here and
22
+ * being optional at the call site is precisely how it came to be omitted
23
+ * everywhere.
24
+ */
25
+ originAppId?: string;
26
+ /** API origin, no trailing slash. */
27
+ baseUrl: string;
28
+ }
29
+ export declare const DEFAULT_BASE_URL = "https://v1.mindstudio-api.com";
30
+ /**
31
+ * Resolve the appId the way the CLI always has: `mindstudio.json` in the
32
+ * workspace. Throws a plain Error with the CLI's historical message text —
33
+ * prod.ts's catch turns it into `{error}` + exit 10, and the client surfaces
34
+ * it as-is.
35
+ */
36
+ export declare function loadWorkspaceAppId(workspaceDir?: string): string;
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Error + exit-code vocabulary for the remy-admin CLI.
3
+ *
4
+ * Exit codes are a contract remy can branch on without parsing stdout. The
5
+ * 0-4 range belongs to `releases wait` (see HELP_RELEASES) and predates this
6
+ * module; `generic` is deliberately 10 so that a bad API key or an unparseable
7
+ * mindstudio.json can never be mistaken for exit 1 = "build failed".
8
+ */
9
+ export declare const EXIT: {
10
+ /** live (or preview, for a feature branch) */
11
+ readonly ok: 0;
12
+ /** `releases wait` only: the build failed */
13
+ readonly buildFailed: 1;
14
+ /** `releases wait` only: still building when --timeout elapsed */
15
+ readonly timeout: 2;
16
+ /** `releases wait` only: no release ever appeared for the commit */
17
+ readonly notFound: 3;
18
+ /** `releases wait` only: built, but a newer release replaced it */
19
+ readonly superseded: 4;
20
+ /** Any other failure: bad arguments, missing config, API error, timeout. */
21
+ readonly generic: 10;
22
+ };
23
+ /**
24
+ * A failure that should be reported as `{"error": ...}` on stdout.
25
+ *
26
+ * Thrown rather than exiting so that main()'s catch can print the message and
27
+ * set `process.exitCode`, letting node flush stdout naturally. Calling
28
+ * process.exit() here would truncate the message at one pipe buffer (64 KiB) —
29
+ * which is exactly how remy invokes this CLI.
30
+ */
31
+ export declare class CliError extends Error {
32
+ readonly code: number;
33
+ constructor(message: string, code?: number);
34
+ }
35
+ /**
36
+ * A failure caused by bad input. Carries the command's verbatim usage string
37
+ * so the caller sees exactly what it should have typed.
38
+ */
39
+ export declare class UsageError extends CliError {
40
+ constructor(detail: string | null, usage: string);
41
+ }
42
+ /**
43
+ * Report a failure and stop.
44
+ *
45
+ * Throws rather than calling process.exit(): exit() does not drain an async
46
+ * stdout write, so a message larger than one pipe buffer (64 KiB) was truncated
47
+ * mid-JSON — and a pipe is exactly how remy invokes this CLI. The entry point's
48
+ * catch prints and sets process.exitCode, letting node flush on its own. Typed
49
+ * `never`, so callers use it as a terminator.
50
+ */
51
+ export declare function fatal(message: string): never;
52
+ /**
53
+ * A non-2xx API response, thrown by the ops core (src/http.ts) so both skins
54
+ * share one error surface: the CLI's entry-point catch prints `.message`
55
+ * (built to the CLI's historical string) and exits 10; an importing caller
56
+ * gets the structured fields.
57
+ */
58
+ export declare class AdminApiError extends Error {
59
+ readonly method: string;
60
+ readonly path: string;
61
+ readonly status: number;
62
+ readonly body: unknown;
63
+ constructor(method: string, path: string, status: number, body: unknown);
64
+ }
65
+ /** A request that exceeded its time bound before a response arrived. */
66
+ export declare class AdminTimeoutError extends Error {
67
+ constructor(label: string, timeoutMs: number);
68
+ }
package/dist/http.d.ts ADDED
@@ -0,0 +1,68 @@
1
+ /**
2
+ * The authed HTTP core under every operation, context-bound and process-free:
3
+ * it throws typed errors (AdminApiError / AdminTimeoutError) and never prints
4
+ * or exits, so the same functions serve the CLI and the importable client.
5
+ *
6
+ * Two entry points, because ops need two failure shapes: `call` throws on a
7
+ * bad status (most ops), `tryCall` returns the status so a caller can tolerate
8
+ * one (releases waitForCommit polls through 404s). The CLI-only raw/SSE
9
+ * passthroughs live in cliStream.ts — they are output devices, not API calls.
10
+ */
11
+ import type { AdminContext } from './ctx.js';
12
+ /** Bound one request, so a hung API call can't hang the caller indefinitely. */
13
+ export declare const REQUEST_TIMEOUT_MS = 30000;
14
+ /**
15
+ * How long a poll loop keeps retrying through transient failures before it
16
+ * gives up. A `--wait` can run for many minutes over a tunnel; one 502 from a
17
+ * gateway says nothing about the thing being waited on.
18
+ */
19
+ export declare const TRANSIENT_GRACE_MS: number;
20
+ /**
21
+ * A failure worth retrying inside a poll loop: the API answered 5xx (a gateway
22
+ * or tunnel between the CLI and the platform hiccupped), the request timed out,
23
+ * or the socket never connected. A 4xx is a real answer and is not.
24
+ */
25
+ export declare function isTransientError(err: unknown): boolean;
26
+ /** The raw Lighthouse report is a large artifact pulled from object storage. */
27
+ export declare const REPORT_TIMEOUT_MS = 60000;
28
+ /** Percent-encode one URL path segment. */
29
+ export declare function seg(value: string | number): string;
30
+ /**
31
+ * Query string ('' or '?a=1&b=2') from a params object; undefined/null values
32
+ * are skipped. The ops-side counterpart of the CLI's Args.query().
33
+ *
34
+ * Takes `object` rather than a Record so ops can pass their typed params
35
+ * interfaces directly (interfaces lack index signatures, so a Record
36
+ * constraint would force a cast at every call site).
37
+ */
38
+ export declare function qs(params: object): string;
39
+ declare function authHeaders(ctx: AdminContext): Record<string, string>;
40
+ /**
41
+ * Read a response body without assuming it is JSON.
42
+ *
43
+ * A 204 or an empty body is a legitimate success for the DELETE endpoints
44
+ * (`secrets delete`, `users revoke-api-key`). res.json() throws on those, which
45
+ * turned a successful mutation into a reported failure.
46
+ */
47
+ export declare function readBody(res: Response): Promise<any>;
48
+ export declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number, label: string): Promise<Response>;
49
+ /**
50
+ * `T` is the endpoint's response shape, transcribed from the api's route
51
+ * in `src/types/`. Defaults to `unknown` so an unannotated call site that
52
+ * touches the result fails to compile rather than silently going untyped.
53
+ * Note: 204/empty responses surface as `{ ok: true, status }` (see readBody) —
54
+ * delete-style result types reflect that, not the route's (absent) JSON.
55
+ */
56
+ export declare function call<T = unknown>(ctx: AdminContext, method: string, apiPath: string, body?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
57
+ /**
58
+ * Like `call`, but never throws on an HTTP status — returns a structured
59
+ * result so a caller can react to one (e.g. tolerate a 404 while a release
60
+ * row is still being created after a push).
61
+ */
62
+ export declare function tryCall<T = unknown>(ctx: AdminContext, method: string, apiPath: string): Promise<{
63
+ ok: boolean;
64
+ status: number;
65
+ body: T;
66
+ }>;
67
+ /** @internal Exposed for cliStream.ts, which shares the auth header shape. */
68
+ export { authHeaders };