@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,81 @@
1
+ /**
2
+ * Database query operations.
3
+ *
4
+ * Ops are pure (ctx, sql) → typed result; the CLI skin in commands/db.ts
5
+ * owns SQL assembly (the raw-spec mode, the tables introspection query) and
6
+ * all output.
7
+ */
8
+ import type { AdminContext } from '../ctx.js';
9
+ import type { DbHistoryResult, DbQueryResult } from '../types/db.js';
10
+ /**
11
+ * Execute one SQL statement against the app's live-release database.
12
+ *
13
+ * The statement is passed verbatim — no parsing or rewriting. Both read
14
+ * (`SELECT`) and write (`INSERT`, `UPDATE`, `DELETE`) statements are
15
+ * accepted. The `results` array always has exactly one element for a single
16
+ * statement; `changes` is 0 for SELECT.
17
+ *
18
+ * A statement the database refuses (a syntax error, a constraint, a result
19
+ * too large) throws with `errorString: 'sql_error'`, and the body's
20
+ * `errorMessage` is the database's own message.
21
+ *
22
+ * @param sql The SQL statement to execute.
23
+ * @throws AdminApiError `no_live_release` (404) — the app has not been
24
+ * deployed; `no_database` (404) — the live release has no database;
25
+ * `invalid_request` (400) — `queries[]` missing or malformed;
26
+ * `sql_error` (400) — the database refused the statement.
27
+ * @example
28
+ * const { results } = await admin.db.query('SELECT * FROM users LIMIT 10');
29
+ */
30
+ export declare function query(ctx: AdminContext, sql: string): Promise<DbQueryResult>;
31
+ export interface DbHistoryParams {
32
+ /** Max releases to return per page (default 20, clamped 1–100). */
33
+ limit?: number;
34
+ /** `nextCursor` from the previous page. */
35
+ cursor?: string;
36
+ }
37
+ /**
38
+ * The app's releases that were ever live, newest first, each with the window
39
+ * it was live for and its databases.
40
+ *
41
+ * A deploy copies live into the new release and keeps the release it
42
+ * replaces, database and all, as it stood at that moment. So each entry's
43
+ * database is live as of its `liveUntil`; the release live now heads the list
44
+ * with `current: true`. Nothing between two deploys is kept.
45
+ *
46
+ * @throws AdminApiError `invalid_request` (400) — `limit` isn't an integer.
47
+ * @example
48
+ * const { copies } = await admin.db.history({ limit: 10 });
49
+ */
50
+ export declare function history(ctx: AdminContext, params?: DbHistoryParams): Promise<DbHistoryResult>;
51
+ /**
52
+ * Run one SQL statement, read-only, against a past release's database (the
53
+ * one named as live's default), as it stood when that release was replaced.
54
+ * Nothing can change it: a write is refused with `sql_error`.
55
+ *
56
+ * @param releaseId A release from `history()` that isn't `current`.
57
+ * @throws AdminApiError `release_not_found` (404) — no release of this app
58
+ * that was ever live has that id; `release_is_live` (400) — it's the live
59
+ * release, so use `query`; `no_database` (404) — that release has no
60
+ * database of live's name; `no_live_release` (404) — the app isn't
61
+ * deployed; `sql_error` (400) — the database refused the statement,
62
+ * a write included.
63
+ * @example
64
+ * const { results } = await admin.db.historyQuery(releaseId, 'SELECT count(*) AS n FROM orders');
65
+ */
66
+ export declare function historyQuery(ctx: AdminContext, releaseId: string, sql: string): Promise<DbQueryResult>;
67
+ /**
68
+ * Run one SQL statement against live with a past release's database attached
69
+ * as the schema `history`: `history.<table>` is the past table, and an
70
+ * unqualified name is live's. Writes to live are real, as with `query`, and
71
+ * run in one transaction; the attached copy is private to the call, so
72
+ * nothing written into it lasts.
73
+ *
74
+ * @param releaseId A release from `history()` that isn't `current`.
75
+ * @throws AdminApiError the same as `historyQuery`; a `sql_error` is the
76
+ * database refusing the statement, and nothing in it was applied.
77
+ * @example
78
+ * await admin.db.historyAttach(releaseId,
79
+ * 'UPDATE orders SET note = h.note FROM history.orders h WHERE h.id = orders.id AND orders.note IS NULL');
80
+ */
81
+ export declare function historyAttach(ctx: AdminContext, releaseId: string, sql: string): Promise<DbQueryResult>;
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Diagnostics operations: live-release id resolution (delegates to
3
+ * ops/releases.ts to avoid duplicating the dashboard call), release diagnostics
4
+ * fetch, and raw Lighthouse report download.
5
+ *
6
+ * Ops are pure: (ctx, params) → typed result. No printing, no process coupling.
7
+ */
8
+ import type { AdminContext } from '../ctx.js';
9
+ import type { DiagnosticsReleaseResult } from '../types/diagnostics.js';
10
+ /**
11
+ * Resolve the id of the currently-live release, or null if the app has not
12
+ * been published. Delegates to the releases dashboardLive op to avoid
13
+ * duplicating the dashboard endpoint call.
14
+ *
15
+ * @example
16
+ * const releaseId = await admin.diagnostics.getLiveReleaseId();
17
+ */
18
+ export declare function getLiveReleaseId(ctx: AdminContext): Promise<string | null>;
19
+ /**
20
+ * Fetch a release by id, including its Lighthouse diagnostics payload.
21
+ *
22
+ * `diagnostics` is null when the audit has not yet landed (~30–60s after
23
+ * go-live). The `lighthouseJsonUrl` inside `diagnostics` is a short-lived
24
+ * signed GET URL re-minted on each call — do not cache the URL.
25
+ *
26
+ * @param releaseId The release id to fetch (e.g. from `getLiveReleaseId`).
27
+ * @throws AdminApiError `release_not_found` (404) — the release id does not
28
+ * exist or belongs to a different app.
29
+ * @example
30
+ * const { diagnostics } = await admin.diagnostics.getRelease('rel_abc123');
31
+ */
32
+ export declare function getRelease(ctx: AdminContext, releaseId: string): Promise<DiagnosticsReleaseResult>;
33
+ /**
34
+ * Fetch the raw Lighthouse JSON report from its signed URL. Uses
35
+ * REPORT_TIMEOUT_MS since the report is a large artifact pulled from object
36
+ * storage.
37
+ *
38
+ * @param url The short-lived signed URL from `diagnostics.lighthouseJsonUrl`.
39
+ * @example
40
+ * const report = await admin.diagnostics.fetchReport(url);
41
+ */
42
+ export declare function fetchReport(url: string): Promise<unknown>;
@@ -0,0 +1,250 @@
1
+ /**
2
+ * App domain operations: platform subdomain, custom hostnames, and the
3
+ * domains the workspace buys through Remy.
4
+ *
5
+ * `findHostname` resolves a user-supplied hostname to its row id and full
6
+ * entry (list → match → id). It throws a plain Error with the exact
7
+ * "not found" message the CLI historically surfaced — the entry-point catch
8
+ * prints `.message` identically whether it came from `fatal()` or here.
9
+ *
10
+ * Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
11
+ * AdminTimeoutError. No printing, no process coupling.
12
+ */
13
+ import type { AdminContext } from '../ctx.js';
14
+ import type { DomainsCustomHostnameView, DomainsCustomListResult, DomainsCustomAddResult, DomainsCustomCheckResult, DomainsCustomRemoveResult, DomainsCustomRetryResult, DomainsGetResult, DomainsSetResult, DomainsCheckResult, RegisteredDomainRecordType, RegisteredDomainView, RegisteredDomainsBuyResult, RegisteredDomainsContactResult, RegisteredDomainsContactSetResult, RegisteredDomainsListResult, RegisteredDomainsQuoteResult, RegisteredDomainsRecordDeleteResult, RegisteredDomainsRecordResult, RegisteredDomainsSearchResult, RegisteredDomainsZoneResult, RegistrantContact } from '../types/domains.js';
15
+ /**
16
+ * Get the app's current platform subdomain (e.g. `my-app.madewithremy.com`).
17
+ *
18
+ * Returns `{ subdomain: null }` when none is set.
19
+ *
20
+ * @example
21
+ * const { subdomain } = await admin.domains.get();
22
+ */
23
+ export declare function get(ctx: AdminContext): Promise<DomainsGetResult>;
24
+ /**
25
+ * Set the app's platform subdomain.
26
+ *
27
+ * @param subdomain The desired subdomain (hyphenated, no suffix).
28
+ * @example
29
+ * await admin.domains.set('my-app');
30
+ */
31
+ export declare function set(ctx: AdminContext, subdomain: string): Promise<DomainsSetResult>;
32
+ /**
33
+ * Check whether a platform subdomain is available before calling `set`.
34
+ *
35
+ * @example
36
+ * const { isAvailable } = await admin.domains.check('my-app');
37
+ */
38
+ export declare function check(ctx: AdminContext, subdomain: string): Promise<DomainsCheckResult>;
39
+ /**
40
+ * List all custom hostnames registered on the app.
41
+ *
42
+ * Results come from a Cloudflare-synced cache that can be up to ~5 minutes
43
+ * stale. Use `customRetry` to force a synchronous re-check after the customer
44
+ * adds DNS records. `uiStatus` values: `waiting_for_dns | issuing_ssl | live |
45
+ * action_needed | reconnecting`.
46
+ *
47
+ * @example
48
+ * const { hostnames } = await admin.domains.customList();
49
+ * const live = hostnames.filter((h) => h.uiStatus === 'live');
50
+ */
51
+ export declare function customList(ctx: AdminContext): Promise<DomainsCustomListResult>;
52
+ /**
53
+ * Register a custom hostname on the app.
54
+ *
55
+ * Apex input (e.g. `acme.com`) auto-creates the `www.acme.com` pair and
56
+ * returns both entries. `dnsInstructions` on each returned entry contains
57
+ * the DNS records the customer must add to their provider, except on a domain
58
+ * the workspace bought through Remy, where `registeredDomain` says which
59
+ * records the platform wrote itself and any it couldn't.
60
+ *
61
+ * @throws AdminApiError `invalid_hostname` (400) — the hostname failed format
62
+ * validation; `hostname_in_use` (400) — the hostname (or its auto-paired
63
+ * www) is already registered on any app.
64
+ * @example
65
+ * const { hostnames } = await admin.domains.customAdd('acme.com');
66
+ * // hostnames[0] = apex row, hostnames[1] = www pair
67
+ */
68
+ export declare function customAdd(ctx: AdminContext, hostname: string): Promise<DomainsCustomAddResult>;
69
+ /**
70
+ * Preflight a hostname before registering: validates format, checks
71
+ * availability, and signals whether an apex would auto-pair www.
72
+ *
73
+ * Never throws — invalid input returns `{ valid: false, errorMessage }`.
74
+ *
75
+ * @example
76
+ * const { valid, willAutoPairWww } = await admin.domains.customCheck('acme.com');
77
+ */
78
+ export declare function customCheck(ctx: AdminContext, hostname: string): Promise<DomainsCustomCheckResult>;
79
+ /**
80
+ * Resolve a hostname entry by name: lists all hostnames and matches on the
81
+ * canonical lowercase hostname, returning the row id and full entry.
82
+ *
83
+ * @throws Error `No custom domain "${hostname}" found on this app` when the
84
+ * hostname is not registered.
85
+ * @example
86
+ * const { id, entry } = await admin.domains.findHostname('app.acme.com');
87
+ */
88
+ export declare function findHostname(ctx: AdminContext, hostname: string): Promise<{
89
+ id: string;
90
+ entry: DomainsCustomHostnameView;
91
+ }>;
92
+ /**
93
+ * Remove a custom hostname from the app.
94
+ *
95
+ * Apex hostnames also remove their paired `www.` entry. The hostname is
96
+ * resolved internally via `findHostname` before the delete call.
97
+ *
98
+ * @throws Error `No custom domain "${hostname}" found on this app` when not
99
+ * registered; AdminApiError `not_found` (404) if the resolved id has gone
100
+ * stale.
101
+ * @example
102
+ * await admin.domains.customRemove('acme.com');
103
+ */
104
+ export declare function customRemove(ctx: AdminContext, hostname: string): Promise<DomainsCustomRemoveResult>;
105
+ /**
106
+ * Re-trigger Cloudflare validation for a hostname, typically after the
107
+ * customer has updated their DNS records.
108
+ *
109
+ * @throws Error `No custom domain "${hostname}" found on this app` when not
110
+ * registered; AdminApiError `not_found` (404) if the resolved id has gone
111
+ * stale; `no_cf_id` (400) — the hostname was never registered with
112
+ * Cloudflare and cannot be retried.
113
+ * @example
114
+ * const { hostname: updated } = await admin.domains.customRetry('app.acme.com');
115
+ */
116
+ export declare function customRetry(ctx: AdminContext, hostname: string): Promise<DomainsCustomRetryResult>;
117
+ /**
118
+ * Suggest domains for a keyword or a whole name, each with its price and
119
+ * renewal price. Only `sellable` ones can be bought; the others say why.
120
+ *
121
+ * @throws AdminApiError `invalid_query` (400); `namecom_not_configured` (400)
122
+ * — this deployment doesn't sell domains.
123
+ * @example
124
+ * const { offers } = await admin.domains.search('acme bakery');
125
+ */
126
+ export declare function search(ctx: AdminContext, query: string): Promise<RegisteredDomainsSearchResult>;
127
+ /**
128
+ * The definitive answer for one name: whether it can be bought, its term,
129
+ * its price and its renewal price. The price is what `buy` must be given.
130
+ *
131
+ * @throws AdminApiError `invalid_domain` (400) — not a whole registrable
132
+ * domain; `namecom_not_configured` (400).
133
+ * @example
134
+ * const { quote } = await admin.domains.quote('acmebakery.com');
135
+ */
136
+ export declare function quote(ctx: AdminContext, name: string): Promise<RegisteredDomainsQuoteResult>;
137
+ export interface BuyParams {
138
+ /** The whole domain, like `acmebakery.com`. */
139
+ name: string;
140
+ /** The price the user confirmed: `quote`'s. A price that has moved is refused. */
141
+ price: number;
142
+ }
143
+ /**
144
+ * Buy a domain for the workspace, registered to its registrant contact, at
145
+ * the confirmed price, which is charged at once and isn't refundable. It
146
+ * renews yearly at its renewal price while auto-renew is on. Only call this
147
+ * after the user has explicitly confirmed the name, the price and the renewal
148
+ * price. The domain is usually `active` on return; a `pending` one settles
149
+ * within minutes (poll `owned`). It connects to nothing by itself.
150
+ *
151
+ * @throws AdminApiError `registrant_contact_required` (400) — set the contact
152
+ * first; `price_changed` (409) — the message has the new price, to confirm
153
+ * again; `insufficient_credits/*` (402);
154
+ * `entitlement_required:remy_build` (422) — the workspace doesn't build in
155
+ * Remy, with what would unlock it in `details`; `domain_limit_reached`
156
+ * (422) — it holds as many domains as it may (20 unless support raised
157
+ * it); `domain_registration_rate` (429);
158
+ * `domain_unavailable`, `tld_not_supported`, `trademark_claim` (400);
159
+ * `registrar_busy` (429); `registrar_payment` — temporarily unavailable;
160
+ * `namecom_not_configured` (400).
161
+ * @example
162
+ * const { domain } = await admin.domains.buy({ name: 'acmebakery.com', price: 11.99 });
163
+ */
164
+ export declare function buy(ctx: AdminContext, params: BuyParams): Promise<RegisteredDomainsBuyResult>;
165
+ /**
166
+ * The workspace's bought domains, newest first: status, expiry, auto-renew,
167
+ * whether ICANN's verification is owed, and the apps connected to each.
168
+ * Empty where the deployment doesn't sell domains.
169
+ *
170
+ * @example
171
+ * const { domains } = await admin.domains.owned();
172
+ */
173
+ export declare function owned(ctx: AdminContext): Promise<RegisteredDomainsListResult>;
174
+ /**
175
+ * Resolve one of the workspace's domains by name (lists and matches).
176
+ *
177
+ * @throws Error `No domain "${name}" in this workspace` when it holds none by
178
+ * that name.
179
+ * @internal
180
+ */
181
+ export declare function findOwned(ctx: AdminContext, name: string): Promise<RegisteredDomainView>;
182
+ /**
183
+ * The workspace's registrant contact, which every domain it buys is
184
+ * registered to, or null before the first purchase.
185
+ *
186
+ * @example
187
+ * const { contact } = await admin.domains.contactGet();
188
+ */
189
+ export declare function contactGet(ctx: AdminContext): Promise<RegisteredDomainsContactResult>;
190
+ /**
191
+ * Set the registrant contact: the legal owner of the workspace's domains
192
+ * (the organization when `companyName` is set, the person otherwise), whom
193
+ * ICANN emails to verify. It's put on every domain the workspace holds;
194
+ * `notUpdated` lists any Name.com wouldn't take it on.
195
+ *
196
+ * @throws AdminApiError `invalid_contact` (400) — the message names what's
197
+ * missing or malformed; `namecom_not_configured` (400).
198
+ * @example
199
+ * await admin.domains.contactSet({
200
+ * firstName: 'Ada', lastName: 'Lovelace', address1: '1 Main St', city: 'Austin',
201
+ * state: 'TX', zip: '78701', country: 'US', email: 'ada@acme.com', phone: '+15125550123',
202
+ * });
203
+ */
204
+ export declare function contactSet(ctx: AdminContext, contact: RegistrantContact): Promise<RegisteredDomainsContactSetResult>;
205
+ export interface ZoneRecordParams {
206
+ /** Relative to the zone: `www`, `_dmarc`, or `` for the apex. */
207
+ host: string;
208
+ type: RegisteredDomainRecordType;
209
+ answer: string;
210
+ /** Seconds, at least 300. */
211
+ ttl?: number;
212
+ /** MX and SRV only. */
213
+ priority?: number;
214
+ }
215
+ /**
216
+ * Every DNS record on a bought domain's zone. The ones the platform wrote for
217
+ * a connection carry `managed` (what they're for) and can't be changed here;
218
+ * the rest are the owner's.
219
+ *
220
+ * @throws Error `No domain "${name}" in this workspace`; AdminApiError
221
+ * `domain_not_found` (404) — not active.
222
+ * @example
223
+ * const { records } = await admin.domains.zone('acmebakery.com');
224
+ */
225
+ export declare function zone(ctx: AdminContext, name: string): Promise<RegisteredDomainsZoneResult>;
226
+ /**
227
+ * Add a record to a bought domain's zone, like a site verification TXT.
228
+ *
229
+ * @throws AdminApiError `invalid_record` (400); `domain_not_found` (404).
230
+ * @example
231
+ * await admin.domains.zoneAdd('acmebakery.com', { host: '', type: 'TXT', answer: 'google-site-verification=abc' });
232
+ */
233
+ export declare function zoneAdd(ctx: AdminContext, name: string, record: ZoneRecordParams): Promise<RegisteredDomainsRecordResult>;
234
+ /**
235
+ * Replace one of the owner's records (by the id `zone` lists).
236
+ *
237
+ * @throws AdminApiError `record_managed` (409) — the platform wrote it for a
238
+ * connection; `invalid_record` (400); `domain_not_found` (404).
239
+ * @example
240
+ * await admin.domains.zoneUpdate('acmebakery.com', 123, { host: 'www', type: 'CNAME', answer: 'acme.example.net' });
241
+ */
242
+ export declare function zoneUpdate(ctx: AdminContext, name: string, recordId: number, record: ZoneRecordParams): Promise<RegisteredDomainsRecordResult>;
243
+ /**
244
+ * Delete one of the owner's records.
245
+ *
246
+ * @throws AdminApiError `record_managed` (409); `domain_not_found` (404).
247
+ * @example
248
+ * await admin.domains.zoneDelete('acmebakery.com', 123);
249
+ */
250
+ export declare function zoneDelete(ctx: AdminContext, name: string, recordId: number): Promise<RegisteredDomainsRecordDeleteResult>;
@@ -0,0 +1,305 @@
1
+ /**
2
+ * Email operations: outbound delivery log, blast stats, suppression list,
3
+ * inbound inbox, and custom domain management (both directions).
4
+ *
5
+ * Ops are pure: (ctx, params) → typed result, throwing AdminApiError /
6
+ * AdminTimeoutError. No printing, no process coupling — the CLI skin in
7
+ * commands/email.ts and the importable client both call these.
8
+ */
9
+ import type { AdminContext } from '../ctx.js';
10
+ import type { EmailBatchesResult, EmailInboxResult, EmailListResult, EmailSendingStatusResult, EmailSuppressResult, EmailSuppressionsResult, EmailUnsuppressResult, InboundEmailDomainAddResult, InboundEmailDomainCheckResult, InboundEmailDomainDeleteResult, InboundEmailDomainVerifyResult, InboundEmailDomainsListResult, OutboundEmailDomainAddResult, OutboundEmailDomainCheckResult, OutboundEmailDomainDeleteResult, OutboundEmailDomainVerifyResult, OutboundEmailDomainsListResult } from '../types/email.js';
11
+ export interface EmailListParams {
12
+ /**
13
+ * Comma-separated statuses to include. Values: `suppressed`, `failed`,
14
+ * `sent`, `delivered`, `blocked`, `bounced`, `complained`, `delayed`,
15
+ * `rejected`. Default: all statuses. `blocked` means an SES suppression list
16
+ * dropped the message before delivery — usually this app's OWN tenant list
17
+ * (a prior hard bounce or spam report from that address), occasionally the
18
+ * shared account-wide list. `unsuppress` reports which.
19
+ */
20
+ status?: string;
21
+ /** Origin to filter by: `method` (app-sent) or `auth` (sign-in codes). Default: all. */
22
+ kind?: string;
23
+ /**
24
+ * Exact-match recipient address (index-backed, fast). Use `search` for
25
+ * partial or substring matches instead.
26
+ */
27
+ recipient?: string;
28
+ /** Show only messages belonging to this blast / campaign batch id. */
29
+ batchId?: string;
30
+ /**
31
+ * Substring search across subject and recipient address. Bounded; results
32
+ * are not cursor-paginated.
33
+ */
34
+ search?: string;
35
+ /** ISO date range start (inclusive). */
36
+ start?: string;
37
+ /** ISO date range end (inclusive). */
38
+ end?: string;
39
+ limit?: number;
40
+ offset?: number;
41
+ }
42
+ export interface EmailWindowParams {
43
+ /** ISO date range start (inclusive). */
44
+ start?: string;
45
+ /** ISO date range end (inclusive). */
46
+ end?: string;
47
+ }
48
+ export interface EmailBatchesParams {
49
+ /** ISO date range start (inclusive). */
50
+ start?: string;
51
+ /** ISO date range end (inclusive). */
52
+ end?: string;
53
+ limit?: number;
54
+ offset?: number;
55
+ }
56
+ export interface EmailSuppressionsParams {
57
+ limit?: number;
58
+ offset?: number;
59
+ }
60
+ export interface EmailInboxParams {
61
+ /** Filter by processing status: `success` or `error`. Default: all. */
62
+ status?: string;
63
+ /** Substring search across sender address and subject. */
64
+ search?: string;
65
+ /** ISO date range start (inclusive). */
66
+ start?: string;
67
+ /** ISO date range end (inclusive). */
68
+ end?: string;
69
+ /** Cursor from a previous response for pagination. */
70
+ cursor?: string;
71
+ limit?: number;
72
+ }
73
+ /** Direction of mail flow: `sending` = outbound (a domain at the email provider); `inbound` = receiving (MX). */
74
+ export type DomainDirection = 'sending' | 'inbound';
75
+ /**
76
+ * Sent messages for this app, including messages that never reached SES.
77
+ *
78
+ * The log covers every send attempt — suppressed, over-cap,
79
+ * sender-not-allowed — because most real failures never touch the provider.
80
+ * Status values: `suppressed` (app-level unsubscribe), `failed`, `sent`,
81
+ * `delivered`, `blocked` (dropped by an SES suppression list — usually this
82
+ * app's own tenant list after an earlier bounce or spam report from that
83
+ * address), `bounced`, `complained`, `delayed`, `rejected`. Paginated via
84
+ * cursor in the result or by offset.
85
+ *
86
+ * @example
87
+ * const { messages } = await admin.email.list({ status: 'bounced,blocked', limit: 50 });
88
+ */
89
+ export declare function list(ctx: AdminContext, params?: EmailListParams): Promise<EmailListResult>;
90
+ /**
91
+ * Full detail for one outbound message, including bounce diagnostics.
92
+ *
93
+ * @throws AdminApiError `not_found` (404) — no message with that id on this app.
94
+ * @example
95
+ * const msg = await admin.email.get('msg_abc123');
96
+ * console.log(msg.status, msg.diagnostic);
97
+ */
98
+ export declare function get(ctx: AdminContext, messageId: string): Promise<import("../index.js").V2EmailMessage>;
99
+ /**
100
+ * Aggregate counts and delivery rates over a time window.
101
+ *
102
+ * `accepted` is the denominator for all rates (messages SES received);
103
+ * `counts` includes pre-SES failures. `series` is a per-bucket time-series
104
+ * for charting.
105
+ *
106
+ * @example
107
+ * const { counts, rates } = await admin.email.stats({ start: '2026-01-01T00:00:00Z' });
108
+ */
109
+ export declare function stats(ctx: AdminContext, params?: EmailWindowParams): Promise<import("../index.js").EmailSummary>;
110
+ /**
111
+ * Whether this app can send email right now, and up to what — the first thing
112
+ * to check when "it's not sending emails".
113
+ *
114
+ * Reports four independent things: `sending` (the gate the send path itself
115
+ * uses, so this and a `409 sending_paused` can never disagree), `enforcement`
116
+ * (the platform's own throttle/pause and WHO applied it), `ses` (Amazon's view
117
+ * of the app's tenant), and `quota` (the daily recipient limit, usage, and
118
+ * where the limit came from).
119
+ *
120
+ * How to read a pause: `sending.source === 'ses'` means Amazon paused the
121
+ * tenant on its own findings — nothing the app owner does lifts it directly;
122
+ * it clears when the finding clears. `source === 'platform'` with
123
+ * `enforcement.origin === 'platform'` is the automatic bounce/complaint sweep
124
+ * and steps down on its own as rates recover; `origin === 'operator'` is a
125
+ * human hold and will not. A throttle shows up as `enforcement.level:
126
+ * 'throttled'` with the reduced `quota.limit` and its `expiresAt`.
127
+ *
128
+ * @example
129
+ * const s = await admin.email.status();
130
+ * if (!s.sending.allowed) console.log(s.sending.source, s.sending.reason);
131
+ * console.log(`${s.quota.used}/${s.quota.limit ?? '∞'} recipients today`);
132
+ */
133
+ export declare function status(ctx: AdminContext): Promise<EmailSendingStatusResult>;
134
+ /**
135
+ * One row per blast/campaign with per-status counts and, for queued sends,
136
+ * the in-flight lifecycle.
137
+ *
138
+ * A marketing send delivers one message per recipient; many rows share a
139
+ * `batchId` (set by the caller via `sendEmail`). `recipients` is the total
140
+ * fan-out count including pre-SES failures; `accepted` is the SES-received
141
+ * denominator used for rate calculations.
142
+ *
143
+ * Large or marketing sends are accepted immediately and delivered in chunks —
144
+ * `status` (`accepted`/`sending`/`completed`/`partial`/`failed`), `chunksDone`/
145
+ * `chunksTotal` and `pending` report the progress. `status: null` is a normal,
146
+ * finished send delivered inline (or predating the queue), not an error.
147
+ *
148
+ * @example
149
+ * const { batches } = await admin.email.batches({ limit: 20 });
150
+ * const inFlight = batches.filter((b) => b.status === 'sending');
151
+ */
152
+ export declare function batches(ctx: AdminContext, params?: EmailBatchesParams): Promise<EmailBatchesResult>;
153
+ /**
154
+ * Stats for a single blast identified by its batch id, including the queued
155
+ * lifecycle (`status`, chunk progress, `pending`) when the send was queued.
156
+ * A reused batch id reports its NEWEST run's lifecycle.
157
+ *
158
+ * @throws AdminApiError `not_found` (404) — no batch with that id on this app.
159
+ * @example
160
+ * const blast = await admin.email.batch('batch_xyz');
161
+ * console.log(blast.status, blast.pending, blast.counts);
162
+ */
163
+ export declare function batch(ctx: AdminContext, batchId: string): Promise<import("../index.js").EmailBatchSummary>;
164
+ /**
165
+ * App-level suppression list (addresses that have opted out of this app's mail).
166
+ *
167
+ * @example
168
+ * const { suppressions } = await admin.email.suppressions({ limit: 100 });
169
+ */
170
+ export declare function suppressions(ctx: AdminContext, params?: EmailSuppressionsParams): Promise<EmailSuppressionsResult>;
171
+ /**
172
+ * Add an address to this app's suppression list.
173
+ *
174
+ * @throws AdminApiError `invalid_email` (400) — the address is not a valid email.
175
+ * @example
176
+ * await admin.email.suppress('user@example.com');
177
+ */
178
+ export declare function suppress(ctx: AdminContext, email: string): Promise<EmailSuppressResult>;
179
+ /**
180
+ * Remove an address from this app's suppression lists — the app-level
181
+ * unsubscribe row AND the app's SES tenant suppression entry (a prior hard
182
+ * bounce or spam report against this app), which is the one that actually
183
+ * unblocks delivery.
184
+ *
185
+ * No `confirm` parameter here — the op is the deliberate act. The CLI skin
186
+ * keeps the `--confirm` gate before calling this.
187
+ *
188
+ * Read the result, not just `ok`: `tenantEntryRemoved` true means a
189
+ * provider-side bounce record was cleared and mail will be attempted again
190
+ * (another bounce re-suppresses automatically); `platformSuppression` non-null
191
+ * means the address is on SES's ACCOUNT-wide list — never cleared, shared by
192
+ * every app — and this removal changed nothing about deliverability. The CLI
193
+ * skin surfaces both advisories on stderr.
194
+ *
195
+ * @throws AdminApiError `invalid_email` (400) — the address is not a valid email.
196
+ * @example
197
+ * const result = await admin.email.unsuppress('user@example.com');
198
+ * if (result.platformSuppression) console.warn('Still blocked account-wide.');
199
+ */
200
+ export declare function unsuppress(ctx: AdminContext, email: string): Promise<EmailUnsuppressResult>;
201
+ /**
202
+ * Inbound messages received by this app (sender/subject previews).
203
+ *
204
+ * An inbox row's `id` is its request-log id — open the full detail (parsed
205
+ * message, method run, errors) with `requests.get(id)`. Cursor-paginated;
206
+ * the next page token is in `EmailInboxResult.nextCursor`.
207
+ *
208
+ * @example
209
+ * const { emails } = await admin.email.inbox({ status: 'error', limit: 20 });
210
+ */
211
+ export declare function inbox(ctx: AdminContext, params?: EmailInboxParams): Promise<EmailInboxResult>;
212
+ /**
213
+ * Direction-conditional result selector: maps a literal `DomainDirection` to
214
+ * its concrete result type, or the union when the direction is a runtime variable.
215
+ */
216
+ export type ForDirection<D extends DomainDirection, Sending, Inbound> = [
217
+ D
218
+ ] extends ['sending'] ? Sending : [D] extends ['inbound'] ? Inbound : Sending | Inbound;
219
+ /**
220
+ * All registered custom domains for a direction.
221
+ *
222
+ * Sending domains (`'sending'`) include `effectiveSender` — the address the
223
+ * app currently sends from and its fallback tier (`app_domain` > `org_domain`
224
+ * > `subdomain` > `default`). Inbound domains (`'inbound'`) list custom
225
+ * receiving domains; apps already receive at `*@<slug>.madewithremy.com` with
226
+ * no setup.
227
+ *
228
+ * @example
229
+ * const { domains, effectiveSender } = await admin.email.listDomains('sending');
230
+ */
231
+ export declare function listDomains<D extends DomainDirection>(ctx: AdminContext, direction: D): Promise<ForDirection<D, OutboundEmailDomainsListResult, InboundEmailDomainsListResult>>;
232
+ /**
233
+ * Pre-flight check: validate a domain name and confirm it is not already registered.
234
+ *
235
+ * For inbound domains, also returns `dnsInstructions` (the MX record) when
236
+ * `valid` is true — the record is known before registration and can be given
237
+ * to the user up front. Sending domain DKIM CNAMEs are only available after
238
+ * `addDomain`. Returns `{ valid: false, errorMessage }` inline rather than
239
+ * throwing for validation failures.
240
+ *
241
+ * @example
242
+ * const { valid, dnsInstructions } = await admin.email.checkDomain('inbound', 'acme.com');
243
+ */
244
+ export declare function checkDomain<D extends DomainDirection>(ctx: AdminContext, direction: D, domain: string): Promise<ForDirection<D, OutboundEmailDomainCheckResult, InboundEmailDomainCheckResult>>;
245
+ /**
246
+ * Register a new custom domain in the given direction.
247
+ *
248
+ * **Sending (`'sending'`):** creates the domain at the email provider and
249
+ * returns `dnsInstructions.records`, the DNS records to publish, each marked
250
+ * required or not (on the cloud, three DKIM CNAMEs, then a recommended MX and
251
+ * SPF TXT for the bounce domain). Hand these to the user to create at their
252
+ * DNS host, then call `verifyDomain` to re-check. Verification can take
253
+ * minutes after the records resolve; `uiStatus` will be `pending` until then,
254
+ * and `returnPathStatus` says where the bounce domain stands.
255
+ *
256
+ * **Inbound (`'inbound'`):** creates the domain row and returns
257
+ * `dnsInstructions` with the MX record to add, plus an `ownershipTxt` record
258
+ * when the domain was already aimed at the platform or held by another app
259
+ * (it verifies only once both are published). Apps already receive at
260
+ * `*@<slug>.madewithremy.com`; a custom inbound domain is optional.
261
+ *
262
+ * @throws AdminApiError `invalid_domain` (400) — not a valid registrable domain
263
+ * name; `domain_in_use` (400) — already registered on any app;
264
+ * `sending_domain_create_failed` (502, sending only) — the provider
265
+ * couldn't create the domain; `sending_domains_unavailable` (400, sending
266
+ * only) — the deployment sends from one address and takes no domains.
267
+ * @example
268
+ * const { domain } = await admin.email.addDomain('sending', 'mail.acme.com');
269
+ * console.log(domain.dnsInstructions.records);
270
+ */
271
+ export declare function addDomain<D extends DomainDirection>(ctx: AdminContext, direction: D, domain: string): Promise<ForDirection<D, OutboundEmailDomainAddResult, InboundEmailDomainAddResult>>;
272
+ /**
273
+ * Force an immediate DNS check on a registered domain.
274
+ *
275
+ * Resolves the domain name to its row id via an extra GET, then calls the
276
+ * `retry` endpoint. Use after adding DNS records to check earlier than the
277
+ * background poller. `uiStatus` transitions from `pending` → `verified`, or
278
+ * stays `action_needed` (check `verificationErrors`). Sending verification
279
+ * that was never started expires after ~72h; fix the records and call
280
+ * `verifyDomain` again. On a sending domain this also starts over a bounce
281
+ * domain whose MX was never found (`returnPathStatus: 'failed'`), which only
282
+ * a check asked for does.
283
+ *
284
+ * @throws Error if no domain matching `domain` is registered on this app
285
+ * (thrown before the API call, not an AdminApiError).
286
+ * @throws AdminApiError `not_found` (404) — the row was deleted between list and verify.
287
+ * @example
288
+ * const { domain } = await admin.email.verifyDomain('sending', 'mail.acme.com');
289
+ * console.log(domain.uiStatus, domain.verificationErrors);
290
+ */
291
+ export declare function verifyDomain<D extends DomainDirection>(ctx: AdminContext, direction: D, domain: string): Promise<ForDirection<D, OutboundEmailDomainVerifyResult, InboundEmailDomainVerifyResult>>;
292
+ /**
293
+ * Remove a registered domain.
294
+ *
295
+ * For sending domains, also removes the domain at the email provider
296
+ * (best-effort; a failure there still removes the row). Resolves the domain name to its row
297
+ * id via an extra GET before deletion.
298
+ *
299
+ * @throws Error if no domain matching `domain` is registered on this app
300
+ * (thrown before the API call, not an AdminApiError).
301
+ * @throws AdminApiError `not_found` (404) — the row was deleted between list and delete.
302
+ * @example
303
+ * await admin.email.removeDomain('sending', 'mail.acme.com');
304
+ */
305
+ export declare function removeDomain<D extends DomainDirection>(ctx: AdminContext, direction: D, domain: string): Promise<ForDirection<D, OutboundEmailDomainDeleteResult, InboundEmailDomainDeleteResult>>;