@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.
- package/CHANGELOG.md +6 -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 -6
- package/dist/index.js.map +7 -1
- package/dist/ops/agent.d.ts +44 -0
- package/dist/ops/analytics.d.ts +285 -0
- package/dist/ops/apps.d.ts +33 -0
- package/dist/ops/crashes.d.ts +86 -0
- package/dist/ops/cron.d.ts +40 -0
- package/dist/ops/data.d.ts +68 -0
- package/dist/ops/dataSourceConnectors.d.ts +80 -0
- package/dist/ops/dataSourceEvals.d.ts +208 -0
- package/dist/ops/dataSourceJobs.d.ts +141 -0
- package/dist/ops/dataSourceMappers.d.ts +125 -0
- package/dist/ops/dataSources.d.ts +654 -0
- package/dist/ops/db.d.ts +81 -0
- package/dist/ops/diagnostics.d.ts +42 -0
- package/dist/ops/domains.d.ts +250 -0
- package/dist/ops/email.d.ts +305 -0
- package/dist/ops/events.d.ts +56 -0
- package/dist/ops/feedback.d.ts +24 -0
- package/dist/ops/files.d.ts +166 -0
- package/dist/ops/infra.d.ts +163 -0
- package/dist/ops/issues.d.ts +160 -0
- package/dist/ops/jewels.d.ts +249 -0
- package/dist/ops/methods.d.ts +60 -0
- package/dist/ops/prerender.d.ts +74 -0
- package/dist/ops/previews.d.ts +52 -0
- package/dist/ops/qaRecordings.d.ts +68 -0
- package/dist/ops/releases.d.ts +193 -0
- package/dist/ops/requests.d.ts +73 -0
- package/dist/ops/secrets.d.ts +69 -0
- package/dist/ops/settings.d.ts +45 -0
- package/dist/ops/tasks.d.ts +47 -0
- package/dist/ops/usage.d.ts +40 -0
- package/dist/ops/users.d.ts +59 -0
- package/dist/ops/voice.d.ts +178 -0
- package/dist/output.d.ts +19 -0
- package/dist/parseJsonConfig.d.ts +41 -0
- package/dist/poll.d.ts +38 -0
- package/dist/prod.js +21 -21
- package/dist/runningMethod.d.ts +25 -0
- package/dist/sleep.d.ts +12 -0
- package/dist/types/agent.d.ts +95 -0
- package/dist/types/analytics.d.ts +225 -0
- package/dist/types/apps.d.ts +39 -0
- package/dist/types/crashes.d.ts +81 -0
- package/dist/types/cron.d.ts +68 -0
- package/dist/types/data.d.ts +38 -0
- package/dist/types/dataSourceConnectors.d.ts +59 -0
- package/dist/types/dataSourceEvals.d.ts +225 -0
- package/dist/types/dataSourceJobs.d.ts +283 -0
- package/dist/types/dataSourceMappers.d.ts +204 -0
- package/dist/types/dataSourceReaders.d.ts +102 -0
- package/dist/types/dataSources.d.ts +627 -0
- package/dist/types/db.d.ts +63 -0
- package/dist/types/diagnostics.d.ts +96 -0
- package/dist/types/domains.d.ts +277 -0
- package/dist/types/email.d.ts +400 -0
- package/dist/types/events.d.ts +54 -0
- package/dist/types/feedback.d.ts +11 -0
- package/dist/types/files.d.ts +150 -0
- package/dist/types/index.d.ts +37 -0
- package/dist/types/infra.d.ts +188 -0
- package/dist/types/issues.d.ts +106 -0
- package/dist/types/jewels.d.ts +336 -0
- package/dist/types/methods.d.ts +34 -0
- package/dist/types/prerender.d.ts +59 -0
- package/dist/types/previews.d.ts +39 -0
- package/dist/types/progress.d.ts +31 -0
- package/dist/types/qaRecordings.d.ts +51 -0
- package/dist/types/releases.d.ts +233 -0
- package/dist/types/requests.d.ts +114 -0
- package/dist/types/secrets.d.ts +52 -0
- package/dist/types/settings.d.ts +79 -0
- package/dist/types/tasks.d.ts +99 -0
- package/dist/types/usage.d.ts +29 -0
- package/dist/types/users.d.ts +61 -0
- package/dist/types/voice.d.ts +197 -0
- package/dist/upload.d.ts +11 -0
- package/package.json +7 -10
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,12 @@ 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.58
|
|
8
|
+
|
|
9
|
+
### Changed behavior
|
|
10
|
+
|
|
11
|
+
- 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.
|
|
12
|
+
|
|
7
13
|
## 0.1.57
|
|
8
14
|
|
|
9
15
|
### 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 #
|
|
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
|
|
package/dist/client.d.ts
ADDED
|
@@ -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 {};
|
package/dist/config.d.ts
ADDED
|
@@ -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;
|
package/dist/errors.d.ts
ADDED
|
@@ -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 };
|