@layers/amba 4.0.2 → 4.0.3

package/dist/api-client.d.ts

@@ -348,11 +348,14 @@ export declare function scheduleFunction(projectId: string, input: {
     schedule_id: string;
 }>>;
 export interface FunctionLogEvent {
-    /** Logpush row — see `r2-log-reader.ts:LogpushTraceEvent`. Field-shape stable. */
+    /** Sanitized log row — see `r2-log-reader.ts:SanitizedLogEvent`. Field-shape stable. */
     Event?: {
         Timestamp?: string;
     };
-    ScriptName?: string;
+    /** The function's name (parsed server-side from the internal script name). */
+    function_name?: string;
+    /** The deploy version this event came from. */
+    version?: number;
     Outcome?: string;
     Logs?: Array<{
         Level?: string;
@@ -417,8 +420,8 @@ export declare function listSecretSyncStatus(projectId: string): Promise<ApiList
 export interface SetSecretResultRow {
     /** Secret name as set by the customer. */
     name: string;
-    /** Function name the secret binds to. */
-    function: string;
+    /** Function the secret binds to, or `null` for a project-wide secret. */
+    function: string | null;
     /** Secret store version number (1, 2, 3, ...). */
     version: number;
     /** Backend version resource path — exposed for ops debugging. */
@@ -432,12 +435,16 @@ export declare function setSecretViaApi(projectId: string, input: {
     name: string;
     /** Plaintext secret value. <=64KiB. */
     value: string;
-    /** Function name the secret binds to. v1 has no project-wide secrets. */
-    function: string;
+    /**
+     * Function the secret binds to. OMIT for a PROJECT-WIDE secret
+     * (applied to every function in the project, including ones deployed
+     * later).
+     */
+    function?: string;
 }): Promise<ApiResponse<SetSecretResultRow>>;
 export interface ListSecretsRow {
-    /** Function name the secret binds to. */
-    function: string;
+    /** Function the secret binds to, or `null` for a project-wide secret. */
+    function: string | null;
     /** Secret name. */
     name: string;
     /** Latest secret-store version number. */
@@ -447,12 +454,14 @@ export interface ListSecretsRow {
     last_error: string | null;
     updated_at: string;
 }
-export declare function listSecretsViaApi(projectId: string): Promise<ApiListResponse<ListSecretsRow>>;
-export declare function deleteSecretViaApi(projectId: string, name: string, options: {
-    function: string;
+export declare function listSecretsViaApi(projectId: string, options?: {
+    function?: string;
+}): Promise<ApiListResponse<ListSecretsRow>>;
+export declare function deleteSecretViaApi(projectId: string, name: string, options?: {
+    function?: string;
 }): Promise<ApiResponse<{
     name: string;
-    function: string;
+    function: string | null;
     deleted: true;
 }>>;
 /** Closed set of column types the server accepts. */
@@ -579,9 +588,23 @@ export interface SiteDomainRow {
     hostname: string;
     provider_hostname_id: string | null;
     cert_status: 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'active' | 'error';
+    ownership_status: 'pending' | 'active' | 'error';
     created_at: string;
     updated_at: string;
 }
+/** A DNS record the customer must publish to validate / prove ownership. */
+export interface DomainValidationRecord {
+    txt_name?: string;
+    txt_value?: string;
+    http_url?: string;
+    http_body?: string;
+}
+/** Hostname-ownership token returned as a DNS TXT record. */
+export interface DomainOwnershipVerification {
+    type?: string;
+    name?: string;
+    value?: string;
+}
 export declare function createSite(projectId: string, input: {
     name: string;
 }): Promise<ApiResponse<SiteRow>>;
@@ -622,7 +645,16 @@ export declare function addSiteDomainViaApi(projectId: string, siteName: string,
     hostname: string;
     provider_hostname_id: string;
     cert_status: SiteDomainRow["cert_status"];
+    ownership_status: SiteDomainRow["ownership_status"];
     dns_target: string;
+    is_apex: boolean;
+    dns_note: string | null;
+    ssl_validation: DomainValidationRecord[];
+    ownership_verification: DomainOwnershipVerification | null;
+    ownership_verification_http: {
+        http_url?: string;
+        http_body?: string;
+    } | null;
     created_at: string;
 }>>;
 /**
@@ -654,6 +686,51 @@ export declare function deleteSiteViaApi(projectId: string, siteName: string, op
     deleted: true;
     cascade: DeleteCascadeSummary;
 }>>;
+/** A candidate domain from a search. */
+export interface DomainSuggestion {
+    domain: string;
+    available: boolean;
+    price_usd: number | null;
+    currency: string;
+    premium: boolean;
+}
+/** Authoritative availability + price for a specific domain. */
+export interface DomainAvailability extends DomainSuggestion {
+    supported: boolean;
+}
+/** Purchase response — either a quote (executed=false) or a result. */
+export interface DomainPurchaseResult {
+    domain: string;
+    site: string;
+    executed: boolean;
+    available?: boolean;
+    price_usd?: number | null;
+    currency?: string;
+    premium?: boolean;
+    confirmation_required?: boolean;
+    gated?: boolean;
+    live?: boolean;
+    registered?: boolean;
+    provisioned?: boolean;
+    cert_status?: string;
+    ownership_status?: string;
+    dns_autoconfigured?: boolean;
+    url?: string;
+    public_url?: string;
+    message?: string;
+}
+export declare function searchDomainsViaApi(projectId: string, query: string, limit?: number): Promise<ApiListResponse<DomainSuggestion>>;
+export declare function checkDomainsViaApi(projectId: string, domains: string[]): Promise<ApiListResponse<DomainAvailability>>;
+export declare function purchaseDomainViaApi(projectId: string, body: {
+    domain: string;
+    site: string;
+    accept_price_usd?: number;
+    confirm?: boolean;
+    auto_renew?: boolean;
+    privacy?: boolean;
+    years?: number;
+}): Promise<ApiResponse<DomainPurchaseResult>>;
+export declare function listPurchasedDomainsViaApi(projectId: string): Promise<ApiListResponse<Record<string, unknown>>>;
 /**
  * Delete a function entirely. Cascade: removes the deployed script
  * (backend 404 treated as success), then marks every historical

package/dist/commands/domains.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `amba domains ...` commands — buy a domain through Amba.
+ *
+ *   amba domains search <query>         find available domains + prices
+ *   amba domains check <domain...>      authoritative availability + price
+ *   amba domains buy <domain> --site s  buy + connect to a site
+ *   amba domains list                   domains this project has purchased
+ *
+ * Search + check are free. `buy` surfaces the cost and requires explicit
+ * confirmation (interactive y/N, or `--yes`) before it submits a purchase —
+ * and the API itself only executes a real, paid registration when the
+ * platform has live purchasing enabled. A registered domain is auto-
+ * connected to the chosen site with no DNS setup by the customer.
+ */
+export declare function domainsSearchCommand(query: string, options?: {
+    limit?: number;
+}): Promise<void>;
+export declare function domainsCheckCommand(domains: string[]): Promise<void>;
+export interface DomainsBuyOptions {
+    site: string;
+    yes?: boolean;
+    noPrivacy?: boolean;
+    noAutoRenew?: boolean;
+    years?: number;
+}
+export declare function domainsBuyCommand(domain: string, options: DomainsBuyOptions): Promise<void>;
+export declare function domainsListCommand(): Promise<void>;

package/dist/commands/functions-logs.d.ts

@@ -9,8 +9,8 @@
  * Output formatting:
  *   - `--json`: NDJSON to stdout (one event per line) so `| jq` works.
  *   - default: human-readable lines:
- *       2026-05-08T12:34:56.789Z scan-letter-v3 [info] "scanning"
- *       2026-05-08T12:34:57.012Z scan-letter-v3 [exception] TypeError: …
+ *       2026-05-08T12:34:56.789Z scan-letter@v3 [info] "scanning"
+ *       2026-05-08T12:34:57.012Z scan-letter@v3 [exception] TypeError: …
  *
  * Server-side scoping is enforced — the API filters by ScriptName
  * prefix so a developer can never read another tenant's logs.

package/dist/commands/functions.d.ts

@@ -55,11 +55,12 @@ export interface DevOptions {
  * — externalization rules, size cap, and source-map handling are
  * identical so dev → prod parity is automatic.
  *
- * Handler shape: `export default async function (req: Request): Promise<Response>`.
+ * Handler shape: `export default { async fetch(req, env, ctx) { ... } }`.
  * `.env.local` values in the customer's working directory are passed
- * through to the child process so the handler can read them via
- * `process.env.MY_KEY`. Existing values in the parent's env take
- * priority (so `MY_KEY=x amba functions dev …` wins).
+ * through to the child process and bridged into the `env` parameter so
+ * the handler reads them the same way as in production (`env.MY_KEY`).
+ * Existing values in the parent's env take priority (so
+ * `MY_KEY=x amba functions dev …` wins).
  */
 export declare function functionsDevCommand(entryPoint: string, options?: DevOptions): Promise<void>;
 /**

package/dist/commands/secrets.d.ts

@@ -1,13 +1,25 @@
 /**
- * `amba secrets ...` — write per-function secrets through the platform
- * API. The CLI sends `{name, value, function}` to the admin endpoint;
- * the server stores the value, validates reserved binding names, and
- * propagates it to the deployed Worker's binding. Sync is eventual —
- * `amba secrets list` shows progress.
+ * `amba secrets ...` — write secrets through the platform API. The CLI
+ * sends `{name, value, function?}` to the admin endpoint; the server
+ * stores the value, validates reserved binding names, and propagates it to
+ * the deployed Worker binding(s). Sync is eventual — `amba secrets list`
+ * shows progress.
+ *
+ * Two scopes:
+ *   - `--function <name>` → the secret binds to that one function.
+ *   - no `--function`     → a PROJECT-WIDE secret, visible to every
+ *     function in the project (and to any function deployed later). Set it
+ *     once instead of repeating the same value per function.
+ *
+ * Secrets may be set BEFORE the function is deployed. The sync drains once
+ * a deployment lands (and `amba functions deploy` re-syncs at the end).
  */
 export interface SecretsSetOptions {
-    /** Function name the secret binds to. Required — there are no project-wide secrets. */
-    function: string;
+    /**
+     * Function the secret binds to. Omit for a PROJECT-WIDE secret (applied
+     * to every function in the project, including ones deployed later).
+     */
+    function?: string;
     /**
      * Environment selector. Currently informational: both `dev` and `prod`
      * write to the same secret namespace per project. Workarounds:
@@ -23,7 +35,15 @@ export interface SecretsSetOptions {
     fromStdin?: boolean;
 }
 export declare function secretsSetCommand(name: string, value: string | undefined, options: SecretsSetOptions): Promise<void>;
-export declare function secretsListCommand(): Promise<void>;
+export interface SecretsListOptions {
+    /**
+     * Filter to secrets for a single function. Without this, all secrets
+     * across all functions in the project are listed — noisy when a
+     * project has 10+ functions.
+     */
+    function?: string;
+}
+export declare function secretsListCommand(options?: SecretsListOptions): Promise<void>;
 export declare function secretsUnsetCommand(name: string, options: {
-    function: string;
+    function?: string;
 }): Promise<void>;

package/dist/index.js

@@ -377,7 +377,7 @@ async function request(method, path, body) {
 		try {
 			const errorBody = await res.json();
 			if (errorBody.error?.message) {
-				errorMessage = errorBody.error.message;
+				errorMessage = `${res.status} — ${errorBody.error.message}`;
 				errorCode = errorBody.error.code;
 			}
 		} catch {}
@@ -498,7 +498,7 @@ async function streamUsersExport(projectId, query = {}) {
 		try {
 			const errorBody = await res.json();
 			if (errorBody.error?.message) {
-				errorMessage = errorBody.error.message;
+				errorMessage = `${res.status} — ${errorBody.error.message}`;
 				errorCode = errorBody.error.code;
 			}
 		} catch {}
@@ -560,12 +560,12 @@ async function deleteQueueBinding(projectId, queueName) {
 async function setSecretViaApi(projectId, input) {
 	return request("POST", `/projects/${projectId}/secrets`, input);
 }
-async function listSecretsViaApi(projectId) {
-	return request("GET", `/projects/${projectId}/secrets`);
+async function listSecretsViaApi(projectId, options = {}) {
+	return request("GET", `/projects/${projectId}/secrets${options.function ? `?${new URLSearchParams({ function: options.function }).toString()}` : ""}`);
 }
-async function deleteSecretViaApi(projectId, name, options) {
-	const qs = new URLSearchParams({ function: options.function });
-	return request("DELETE", `/projects/${projectId}/secrets/${encodeURIComponent(name)}?${qs.toString()}`);
+async function deleteSecretViaApi(projectId, name, options = {}) {
+	const qs = options.function ? `?${new URLSearchParams({ function: options.function }).toString()}` : "";
+	return request("DELETE", `/projects/${projectId}/secrets/${encodeURIComponent(name)}${qs}`);
 }
 async function createCollection(projectId, input) {
 	return request("POST", `/projects/${projectId}/collections`, input);
@@ -645,6 +645,20 @@ async function rollbackSiteViaApi(projectId, siteName, deploymentId) {
 async function deleteSiteViaApi(projectId, siteName, options) {
 	return request("DELETE", `/projects/${projectId}/sites/${encodeURIComponent(siteName)}?confirm=${encodeURIComponent(options.confirm)}`);
 }
+async function searchDomainsViaApi(projectId, query, limit) {
+	const params = new URLSearchParams({ q: query });
+	if (limit !== void 0) params.set("limit", String(limit));
+	return request("GET", `/projects/${projectId}/domains/search?${params.toString()}`);
+}
+async function checkDomainsViaApi(projectId, domains) {
+	return request("POST", `/projects/${projectId}/domains/check`, { domains });
+}
+async function purchaseDomainViaApi(projectId, body) {
+	return request("POST", `/projects/${projectId}/domains/purchase`, body);
+}
+async function listPurchasedDomainsViaApi(projectId) {
+	return request("GET", `/projects/${projectId}/domains`);
+}
 /**
 * Delete a function entirely. Cascade: removes the deployed script
 * (backend 404 treated as success), then marks every historical
@@ -2318,7 +2332,7 @@ All SDKs expose the same surface: \`Amba.configure({ projectId, apiKey })\`, the
 - **challenges** — time-bounded goals. Define with \`amba_challenges_create\`; progress via SDK.
 
 ### Economy
-- **currencies** — virtual currencies (coins, gems). Define with \`amba_currencies_create\`; grant via \`amba_currencies_grant\` or event rules via \`amba_currency_grant_rules_create\`.
+- **currencies** — virtual currencies (coins, gems). Define with \`amba_currencies_create\`; grant via \`amba_currencies_grant\` or event rules via \`amba_currency_grant_rules_create\`; debit via \`amba_currencies_spend\` (atomic, rejects on insufficient funds).
 - **catalog + stores** — purchasable items + storefronts. Chain: \`amba_catalog_items_create\` → \`amba_catalog_items_set_price\` → \`amba_stores_create\` → \`amba_stores_add_listing\`. (Define currency first.)
 - **inventory** — items users own. Read via SDK \`Amba.inventory.*\`; grant with \`amba_inventory_grant_item\`.
 
@@ -2341,7 +2355,7 @@ All SDKs expose the same surface: \`Amba.configure({ projectId, apiKey })\`, the
 - **sites** — static site hosting at \`*.app.amba.host\`. Deploy with \`amba_sites_deploy\`.
 - **media** — file storage + CDN. Upload via \`amba_media_upload\`.
 - **secrets** — env vars for functions. Set via \`amba_secrets_set\`.
-- **configs** — remote config flags. Define with \`amba_configs_create\`.
+- **configs** — remote config flags. Define with \`amba_remote_configs_create\`.
 - **integrations** — third-party webhooks (RevenueCat, Superwall, AppsFlyer, etc.). Configure with \`amba_integrations_configure\`.
 - **ai_prompts** — versioned LLM prompts callable from SDK. Define with \`amba_ai_prompts_create\`; call via \`amba_ai_prompts_invoke\`.
 `;
@@ -4055,7 +4069,7 @@ async function configSetCommand(key, rawValue) {
 }
 //#endregion
 //#region src/commands/projects.ts
-function confirm(question) {
+function confirm$1(question) {
 	const rl = createInterface({
 		input: process.stdin,
 		output: process.stdout
@@ -4216,7 +4230,7 @@ async function projectsDeleteCommand(projectId, opts = {}) {
 	console.log(pc.dim("  ─────────────────────────────────"));
 	console.log();
 	if (!opts.yes) {
-		if (!await confirm(pc.yellow(`  Delete project ${projectId}? This is irreversible. (y/N) `))) {
+		if (!await confirm$1(pc.yellow(`  Delete project ${projectId}? This is irreversible. (y/N) `))) {
 			console.log(pc.dim("  Aborted."));
 			console.log();
 			return;
@@ -5094,11 +5108,21 @@ async function functionsDeployCommand(entryPoint, options = {}) {
 		return;
 	}
 	console.log(pc.dim("  Uploading…"));
-	const result = await deployFunctionViaApi(projectId, {
-		name: functionName,
-		bundleCode: bundle.code,
-		rate_limit: rateLimit
-	});
+	let result;
+	try {
+		result = await deployFunctionViaApi(projectId, {
+			name: functionName,
+			bundleCode: bundle.code,
+			rate_limit: rateLimit
+		});
+	} catch (err) {
+		if (err instanceof ApiClientError && err.statusCode === 503) {
+			const base = err.message.trimEnd();
+			const sep = /[.!?]$/.test(base) ? " " : ". ";
+			throw new Error(`${base}${sep}The function platform is temporarily unavailable; retry in ~30s.`);
+		}
+		throw err;
+	}
 	console.log(pc.green("  ✓") + ` Deployed ${pc.cyan(functionName)} ${pc.dim(`v${result.data.version}`)}`);
 	console.log(pc.green("  ✓") + ` URL: ${pc.underline(result.fn_url)}`);
 	if (rateLimit) console.log(pc.dim(`  Rate limit: ${rateLimit.max} per ${rateLimit.window} (key=${rateLimit.key}) — enforced pre-dispatch`));
@@ -5153,11 +5177,12 @@ async function functionsScheduleCommand(name, cron, options = {}) {
 * — externalization rules, size cap, and source-map handling are
 * identical so dev → prod parity is automatic.
 *
-* Handler shape: `export default async function (req: Request): Promise<Response>`.
+* Handler shape: `export default { async fetch(req, env, ctx) { ... } }`.
 * `.env.local` values in the customer's working directory are passed
-* through to the child process so the handler can read them via
-* `process.env.MY_KEY`. Existing values in the parent's env take
-* priority (so `MY_KEY=x amba functions dev …` wins).
+* through to the child process and bridged into the `env` parameter so
+* the handler reads them the same way as in production (`env.MY_KEY`).
+* Existing values in the parent's env take priority (so
+* `MY_KEY=x amba functions dev …` wins).
 */
 async function functionsDevCommand(entryPoint, options = {}) {
 	const port = validatePort(options.port);
@@ -5432,11 +5457,37 @@ try {
   // \`pathToFileURL\` is a no-op equivalent on POSIX (returns file:///...).
   const bundleUrl = pathToFileURL(bundlePath).href;
   const mod = await import(bundleUrl);
-  if (typeof mod.default !== 'function') {
-    process.stderr.write('  Error: entry file must export default async function (req: Request): Promise<Response>\\n');
+  // Support the canonical modules export shape: export default { async fetch(req, env, ctx) { ... } }
+  // .env.local values are already in process.env (parent passes childEnv to the child process).
+  // Bridge them into the env parameter so dev/prod parity holds — production injects the same
+  // names as env bindings; local dev reads them from .env.local via process.env.
+  if (mod.default && typeof mod.default.fetch === 'function') {
+    const env = Object.assign(Object.create(null), process.env);
+    const fetchFn = mod.default.fetch.bind(mod.default);
+    handler = (req) => {
+      // Fresh ctx per request — production gives each request its own
+      // ExecutionContext; a shared stub would leak per-request state
+      // across concurrent requests in dev but not in prod.
+      const ctx = {
+        waitUntil: (p) => {
+          // Swallow rejections from background promises — prod handles
+          // waitUntil rejections without crashing. Leaving the rejection
+          // unhandled would cause Node 15+ to crash the child process
+          // even though the HTTP response was already sent.
+          Promise.resolve(p).catch(() => {});
+        },
+        passThroughOnException: () => {},
+      };
+      return fetchFn(req, env, ctx);
+    };
+  } else if (typeof mod.default === 'function') {
+    // Legacy plain-function shape — still accepted for backward compat but env
+    // parameter is not available (secrets only reachable via process.env).
+    handler = mod.default;
+  } else {
+    process.stderr.write('  Error: entry file must export default { async fetch(req, env, ctx) { ... } }\\n');
     process.exit(2);
   }
-  handler = mod.default;
 } catch (err) {
   process.stderr.write('  Bundle import failed: ' + (err && err.stack ? err.stack : err) + '\\n');
   process.exit(2);
@@ -5586,8 +5637,8 @@ function parseRateLimitFlags(options) {
 * Output formatting:
 *   - `--json`: NDJSON to stdout (one event per line) so `| jq` works.
 *   - default: human-readable lines:
-*       2026-05-08T12:34:56.789Z scan-letter-v3 [info] "scanning"
-*       2026-05-08T12:34:57.012Z scan-letter-v3 [exception] TypeError: …
+*       2026-05-08T12:34:56.789Z scan-letter@v3 [info] "scanning"
+*       2026-05-08T12:34:57.012Z scan-letter@v3 [exception] TypeError: …
 *
 * Server-side scoping is enforced — the API filters by ScriptName
 * prefix so a developer can never read another tenant's logs.
@@ -5640,7 +5691,7 @@ function printEvents(events, asJson) {
 	}
 	for (const e of ordered) {
 		const ts = e.EventTimestampMs ? new Date(e.EventTimestampMs).toISOString() : "????-??-??T??:??:??Z";
-		const script = e.ScriptName ?? "<unknown-script>";
+		const script = e.function_name ? `${e.function_name}@v${e.version ?? "?"}` : "<unknown-function>";
 		if (e.Logs && e.Logs.length > 0) for (const logLine of e.Logs) {
 			const level = renderLevel(logLine.Level);
 			const msg = renderMessage(logLine.Message);
@@ -5746,11 +5797,20 @@ async function resolveSecretValue(opts) {
 //#endregion
 //#region src/commands/secrets.ts
 /**
-* `amba secrets ...` — write per-function secrets through the platform
-* API. The CLI sends `{name, value, function}` to the admin endpoint;
-* the server stores the value, validates reserved binding names, and
-* propagates it to the deployed Worker's binding. Sync is eventual —
-* `amba secrets list` shows progress.
+* `amba secrets ...` — write secrets through the platform API. The CLI
+* sends `{name, value, function?}` to the admin endpoint; the server
+* stores the value, validates reserved binding names, and propagates it to
+* the deployed Worker binding(s). Sync is eventual — `amba secrets list`
+* shows progress.
+*
+* Two scopes:
+*   - `--function <name>` → the secret binds to that one function.
+*   - no `--function`     → a PROJECT-WIDE secret, visible to every
+*     function in the project (and to any function deployed later). Set it
+*     once instead of repeating the same value per function.
+*
+* Secrets may be set BEFORE the function is deployed. The sync drains once
+* a deployment lands (and `amba functions deploy` re-syncs at the end).
 */
 async function secretsSetCommand(name, value, options) {
 	validateSecretName(name);
@@ -5760,14 +5820,15 @@ async function secretsSetCommand(name, value, options) {
 	});
 	const projectConfig = await loadProjectConfig();
 	if (options.env === "prod") console.log(pc.dim("  Note: --env is informational; prod and dev share one secret namespace per project."));
+	const scopeLabel = options.function ? options.function : "project-wide";
 	console.log();
 	console.log(pc.bold(`  amba secrets set ${pc.cyan(name)}`));
-	console.log(pc.dim(`  function=${options.function}  env=${options.env ?? "dev"}`));
+	console.log(pc.dim(`  scope=${scopeLabel}  env=${options.env ?? "dev"}`));
 	console.log();
 	const res = await setSecretViaApi(projectConfig.projectId, {
 		name,
 		value: resolvedValue,
-		function: options.function
+		...options.function ? { function: options.function } : {}
 	});
 	console.log(pc.green("  ✓") + ` Secret ${pc.cyan(name)} stored ${pc.dim(`v${res.data.version}`)}`);
 	console.log(pc.green("  ✓") + ` Workers Secret sync ${pc.dim(`(status=${res.data.sync_status})`)} queued`);
@@ -5775,17 +5836,22 @@ async function secretsSetCommand(name, value, options) {
 	console.log(pc.dim("  Workers Secret will be live within ~30s. Run `amba secrets list` to check sync status."));
 	console.log();
 }
-async function secretsListCommand() {
-	const res = await listSecretsViaApi((await loadProjectConfig()).projectId);
+async function secretsListCommand(options = {}) {
+	const res = await listSecretsViaApi((await loadProjectConfig()).projectId, { function: options.function });
 	console.log();
+	if (options.function) {
+		console.log(pc.dim(`  Secrets for function ${pc.bold(options.function)}:`));
+		console.log();
+	}
 	if (res.data.length === 0) {
-		console.log(pc.dim("  No secrets configured."));
+		console.log(pc.dim(options.function ? `  No secrets configured for ${options.function}.` : "  No secrets configured."));
 		console.log();
 		return;
 	}
 	for (const row of res.data) {
 		const status = renderStatus(row.sync_status);
-		console.log(`  ${pc.bold(row.name)} ` + pc.dim(`(${row.function})`) + ` v${row.version}  ${status}` + (row.last_error ? pc.dim(`  — ${row.last_error}`) : ""));
+		const scope = row.function ?? "project-wide";
+		console.log(`  ${pc.bold(row.name)} ` + pc.dim(`(${scope})`) + ` v${row.version}  ${status}` + (row.last_error ? pc.dim(`  — ${row.last_error}`) : ""));
 	}
 	console.log();
 }
@@ -6391,13 +6457,21 @@ function makeCodegenHttpClient() {
 * directory (mirrors `wrangler pages deploy ./out` semantics). Dynamic
 * logic belongs in `amba functions deploy`, not in a site directory.
 */
-const SITE_NAME_RE = /^[a-z][a-z0-9_-]{0,49}$/;
-const HOSTNAME_RE = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const SITE_NAME_RE$1 = /^[a-z][a-z0-9_-]{0,49}$/;
+const HOSTNAME_RE$1 = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const MAX_CERT_CN_LENGTH = 64;
+const PLATFORM_DOMAINS = ["amba.host", "amba.dev"];
+function isPlatformDomain(host) {
+	return PLATFORM_DOMAINS.some((d) => host === d || host.endsWith(`.${d}`));
+}
 function validateSiteName(name) {
-	if (!SITE_NAME_RE.test(name)) throw new Error(`Invalid site name '${name}'. Must match /^[a-z][a-z0-9_-]{0,49}$/ (lowercase ASCII, digits, underscore or hyphen; ≤50 chars).`);
+	if (!SITE_NAME_RE$1.test(name)) throw new Error(`Invalid site name '${name}'. Must match /^[a-z][a-z0-9_-]{0,49}$/ (lowercase ASCII, digits, underscore or hyphen; ≤50 chars).`);
 }
 function validateHostname(host) {
-	if (!HOSTNAME_RE.test(host)) throw new Error(`Invalid hostname '${host}'. Must be a DNS-shaped name (e.g. site.example.com).`);
+	const h = host.trim().toLowerCase();
+	if (!HOSTNAME_RE$1.test(h)) throw new Error(`Invalid hostname '${host}'. Must be a DNS-shaped name (e.g. site.example.com).`);
+	if (h.length > MAX_CERT_CN_LENGTH) throw new Error(`Hostname '${host}' is too long for certificate issuance (max ${MAX_CERT_CN_LENGTH} characters). Use a shorter subdomain.`);
+	if (isPlatformDomain(h)) throw new Error(`'${host}' is reserved by the platform. Attach a domain you own, e.g. app.yourdomain.com.`);
 }
 /**
 * Per-deploy size cap. The hosting provider enforces 25 MiB per file +
@@ -6446,7 +6520,7 @@ async function sitesDeployCommand(inputDir, options = {}) {
 	if (domains.data.length > 0) {
 		console.log();
 		console.log(pc.dim("  Domains:"));
-		for (const d of domains.data) console.log(`    ${pc.bold(d.hostname)}  ${formatCertStatus(d.cert_status)}`);
+		for (const d of domains.data) console.log(`    ${pc.bold(d.hostname)}  ${formatDomainStatus(d)}`);
 	}
 	console.log();
 }
@@ -6496,32 +6570,51 @@ async function sitesDomainAddCommand(hostname, options) {
 	console.log();
 	const res = await addSiteDomainViaApi(projectId, options.site, hostname);
 	console.log(pc.green("  ✓") + ` Custom hostname registered`);
+	const validation = res.data.ssl_validation ?? [];
+	const ownership = res.data.ownership_verification;
+	const isApex = res.data.is_apex ?? false;
+	if (validation.length > 0 || ownership) {
+		console.log();
+		console.log(pc.dim("  1. Publish these DNS records to verify ownership:"));
+		for (const rec of validation) if (rec.txt_name && rec.txt_value) console.log(`     ${pc.bold("TXT")} ${rec.txt_name}  →  ${pc.cyan(rec.txt_value)}`);
+		if (ownership?.name && ownership.value) console.log(`     ${pc.bold("TXT")} ${ownership.name}  →  ${pc.cyan(ownership.value)}`);
+		console.log();
+		console.log(pc.dim("  2. Point your hostname at the Amba target:"));
+	} else {
+		console.log();
+		console.log(pc.dim("  Point your hostname at the Amba target:"));
+	}
+	console.log(`     ${pc.bold("CNAME")} ${hostname}  →  ${pc.cyan(res.data.dns_target)}`);
 	console.log();
-	console.log(pc.dim("  Point your DNS at:"));
-	console.log(`    ${pc.bold("CNAME")} ${hostname}  →  ${pc.cyan(res.data.dns_target)}`);
-	console.log();
+	if (isApex) {
+		console.log(pc.dim(`  ${hostname} is a root domain — the CNAME above works only if your DNS provider`));
+		console.log(pc.dim(`  flattens CNAME-at-root. If it doesn't, A-record apex support is coming soon;`));
+		console.log(pc.dim(`  use a subdomain like app.${hostname} in the meantime.`));
+		console.log();
+	}
 	if (options.noWait) {
-		console.log(pc.yellow("  ! --no-wait — skipping cert poll. Run `amba sites describe` later."));
+		console.log(pc.yellow("  ! --no-wait — skipping status poll. Run `amba sites describe` later."));
 		return;
 	}
 	const timeout = (options.timeout ?? 600) * 1e3;
 	const start = Date.now();
-	let lastStatus = "";
+	let lastLine = "";
 	while (Date.now() - start < timeout) {
 		const row = (await listSiteDomains(projectId, options.site)).data.find((d) => d.hostname === hostname);
 		if (!row) throw new Error(`Domain ${hostname} disappeared from listing — check API state.`);
-		if (row.cert_status !== lastStatus) {
-			console.log(pc.dim(`  cert_status: ${formatCertStatus(row.cert_status)}`));
-			lastStatus = row.cert_status;
+		const line = formatDomainStatus(row);
+		if (line !== lastLine) {
+			console.log(pc.dim(`  ${line}`));
+			lastLine = line;
 		}
-		if (row.cert_status === "active") {
-			console.log(pc.green("  ✓") + ` ${hostname} live with valid cert.`);
+		if (row.cert_status === "active" && row.ownership_status === "active") {
+			console.log(pc.green("  ✓") + ` ${hostname} is live with a valid certificate.`);
 			return;
 		}
-		if (row.cert_status === "error") throw new Error(`Cert provisioning failed for ${hostname}. Check that the CNAME points at ${res.data.dns_target}.`);
+		if (row.cert_status === "error" || row.ownership_status === "error") throw new Error(`Domain setup failed for ${hostname}. Confirm the TXT record(s) above are published and the CNAME points at ${res.data.dns_target}.`);
 		await sleep(5e3);
 	}
-	console.log(pc.yellow(`  ! Timed out after ${options.timeout ?? 600}s waiting for cert. Re-run \`amba sites describe ${options.site}\` to check status.`));
+	console.log(pc.yellow(`  ! Timed out after ${options.timeout ?? 600}s. Re-run \`amba sites describe ${options.site}\` to check status.`));
 }
 async function sitesDomainListCommand(siteName) {
 	validateSiteName(siteName);
@@ -6532,7 +6625,7 @@ async function sitesDomainListCommand(siteName) {
 		console.log();
 		return;
 	}
-	for (const d of res.data) console.log(`  ${pc.bold(d.hostname)}  ${formatCertStatus(d.cert_status)}`);
+	for (const d of res.data) console.log(`  ${pc.bold(d.hostname)}  ${formatDomainStatus(d)}`);
 	console.log();
 }
 async function sitesDomainRemoveCommand(hostname, options) {
@@ -6641,10 +6734,157 @@ function formatCertStatus(s) {
 	if (s === "error") return pc.red(s);
 	return pc.yellow(s);
 }
+/**
+* Render BOTH lifecycle states for a domain row. A domain is only live when
+* ownership AND cert are both `active`, so display paths must show both —
+* showing cert alone reads "live" while ownership is still pending.
+*/
+function formatDomainStatus(d) {
+	return `ownership: ${formatCertStatus(d.ownership_status)}  cert: ${formatCertStatus(d.cert_status)}`;
+}
 function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
 }
 //#endregion
+//#region src/commands/domains.ts
+/**
+* `amba domains ...` commands — buy a domain through Amba.
+*
+*   amba domains search <query>         find available domains + prices
+*   amba domains check <domain...>      authoritative availability + price
+*   amba domains buy <domain> --site s  buy + connect to a site
+*   amba domains list                   domains this project has purchased
+*
+* Search + check are free. `buy` surfaces the cost and requires explicit
+* confirmation (interactive y/N, or `--yes`) before it submits a purchase —
+* and the API itself only executes a real, paid registration when the
+* platform has live purchasing enabled. A registered domain is auto-
+* connected to the chosen site with no DNS setup by the customer.
+*/
+const HOSTNAME_RE = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const SITE_NAME_RE = /^[a-z][a-z0-9_-]{0,49}$/;
+function confirm(question) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(/^y(es)?$/i.test(answer.trim()));
+		});
+	});
+}
+function formatPrice(price, currency) {
+	if (price === null) return pc.dim("price unavailable");
+	return pc.bold(`$${price.toFixed(2)} ${currency}/yr`);
+}
+async function domainsSearchCommand(query, options = {}) {
+	const { projectId } = await loadProjectConfig();
+	const res = await searchDomainsViaApi(projectId, query, options.limit);
+	console.log();
+	if (res.data.length === 0) {
+		console.log(pc.dim(`  No suggestions for "${query}".`));
+		console.log();
+		return;
+	}
+	for (const s of res.data) {
+		const tag = s.available ? pc.green("available") : pc.red("taken");
+		const premium = s.premium ? pc.yellow(" premium") : "";
+		console.log(`  ${pc.bold(s.domain)}  ${tag}${premium}  ${formatPrice(s.price_usd, s.currency)}`);
+	}
+	console.log();
+	console.log(pc.dim("  Buy one with:  amba domains buy <domain> --site <site>"));
+	console.log();
+}
+async function domainsCheckCommand(domains) {
+	if (domains.length === 0) throw new Error("Pass at least one domain to check.");
+	if (domains.length > 20) throw new Error("At most 20 domains per check.");
+	const normalised = domains.map((d) => d.toLowerCase());
+	for (const d of normalised) if (!HOSTNAME_RE.test(d)) throw new Error(`Invalid domain '${d}'.`);
+	const { projectId } = await loadProjectConfig();
+	const res = await checkDomainsViaApi(projectId, normalised);
+	console.log();
+	for (const a of res.data) {
+		const tag = a.available ? pc.green("available") : pc.red("taken");
+		const unsupported = a.supported ? "" : pc.yellow(" (extension not supported)");
+		console.log(`  ${pc.bold(a.domain)}  ${tag}${unsupported}  ${formatPrice(a.price_usd, a.currency)}`);
+	}
+	console.log();
+}
+async function domainsBuyCommand(domain, options) {
+	const hostname = domain.toLowerCase();
+	if (!HOSTNAME_RE.test(hostname)) throw new Error(`Invalid domain '${domain}'.`);
+	if (!options.site || !SITE_NAME_RE.test(options.site)) throw new Error("--site <name> is required (the site to connect the domain to).");
+	const { projectId } = await loadProjectConfig();
+	console.log();
+	console.log(pc.bold(`  amba domains buy ${pc.cyan(hostname)}`));
+	console.log(pc.dim(`  → connect to site ${pc.cyan(options.site)}`));
+	console.log();
+	const check = await checkDomainsViaApi(projectId, [hostname]);
+	const availability = check.data.find((d) => d.domain === hostname) ?? check.data[0];
+	if (!availability) throw new Error("Could not determine availability for that domain.");
+	if (!availability.available) throw new Error(`${hostname} is not available to register. Try \`amba domains search\`.`);
+	if (!availability.supported) throw new Error(`${hostname} uses an extension we can't register yet.`);
+	if (availability.price_usd === null) throw new Error(`${hostname} can't be priced right now — try again shortly.`);
+	const price = availability.price_usd;
+	console.log(`  Price: ${formatPrice(price, availability.currency)}` + (availability.premium ? pc.yellow("  (premium)") : ""));
+	console.log(pc.dim(`  Includes: registration${options.noPrivacy ? "" : " + WHOIS privacy"}${options.noAutoRenew ? "" : " + auto-renew"}, auto-connected to ${options.site} (no DNS setup).`));
+	console.log();
+	if (!options.yes) {
+		if (!await confirm(pc.yellow(`  Buy ${hostname} for $${price.toFixed(2)} ${availability.currency}? `) + "(y/N) ")) {
+			console.log(pc.dim("  Cancelled — nothing was purchased."));
+			console.log();
+			return;
+		}
+	}
+	const r = (await purchaseDomainViaApi(projectId, {
+		domain: hostname,
+		site: options.site,
+		accept_price_usd: price,
+		confirm: true,
+		privacy: !options.noPrivacy,
+		auto_renew: !options.noAutoRenew,
+		...options.years ? { years: options.years } : {}
+	})).data;
+	if (!r.executed) {
+		if (r.gated) {
+			console.log(pc.yellow("  ! Domain purchasing is not enabled on this deployment."));
+			console.log(pc.dim("    The domain is available at the price shown; no charge was made."));
+		} else {
+			console.log(pc.yellow("  ! Purchase not completed."));
+			if (r.message) console.log(pc.dim(`    ${r.message}`));
+		}
+		console.log();
+		return;
+	}
+	console.log(pc.green("  ✓") + ` Registered ${pc.bold(hostname)}`);
+	if (r.provisioned) {
+		console.log(pc.green("  ✓") + ` Connected to ${options.site}${r.dns_autoconfigured ? " — no DNS setup needed" : ""}.`);
+		if (r.public_url) console.log(pc.green("  ✓") + ` Live at ${pc.underline(r.public_url)}`);
+		console.log(pc.dim("    The TLS certificate is issuing now (usually a minute or two)."));
+	} else if (r.message) console.log(pc.dim(`    ${r.message}`));
+	console.log();
+}
+async function domainsListCommand() {
+	const { projectId } = await loadProjectConfig();
+	const res = await listPurchasedDomainsViaApi(projectId);
+	console.log();
+	if (res.data.length === 0) {
+		console.log(pc.dim("  No domains purchased through Amba yet."));
+		console.log(pc.dim("  Buy one with: amba domains buy <domain> --site <site>"));
+		console.log();
+		return;
+	}
+	for (const d of res.data) {
+		const domain = String(d.domain ?? "");
+		const status = String(d.status ?? "");
+		const coloured = status === "active" ? pc.green(status) : status === "failed" ? pc.red(status) : pc.yellow(status);
+		console.log(`  ${pc.bold(domain)}  ${coloured}`);
+	}
+	console.log();
+}
+//#endregion
 //#region src/index.ts
 const program = new Command();
 program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("0.1.0");
@@ -6827,17 +7067,17 @@ consumers.command("unbind <queue-name>").description("Remove the binding for a q
 	await runAction(() => functionsConsumersUnbindCommand(queueName));
 });
 const secrets = program.command("secrets").description("Function secrets (GCP canonical, Workers-Secret synced)");
-secrets.command("set <name> [value]").description("Write a secret to GCP Secret Manager and queue Workers Secret sync. Use --from-stdin to keep the value out of shell history.").requiredOption("--function <name>", "Function name the secret binds to. Secrets are scoped per dispatched script — there is no project-wide secret in v1; every secret belongs to exactly one function. Use the same name as the entry passed to 'amba functions deploy'.").option("--env <env>", "'dev' | 'prod' — INFORMATIONAL ONLY. Both share one secret namespace per project. Use distinct secret names (e.g. STRIPE_KEY_DEV / STRIPE_KEY_PROD) or two amba projects for real env isolation.").option("--from-stdin", "Read the secret value from stdin instead of the positional arg. Mutually exclusive with <value>. Pipe in: `echo $KEY | amba secrets set NAME --function fn --from-stdin`.").action(async (name, value, opts) => {
+secrets.command("set <name> [value]").description("Store a secret and queue its sync to your deployed function(s). Omit --function for a project-wide secret. Use --from-stdin to keep the value out of shell history.").option("--function <name>", "Function the secret binds to. OMIT this flag to set a PROJECT-WIDE secret — one value visible to every function in the project (and to any function deployed later). With it, the secret is scoped to just that function. Use the same name as the entry passed to 'amba functions deploy'. Secrets may be set before the function is deployed; the sync drains once you deploy.").option("--env <env>", "'dev' | 'prod' — INFORMATIONAL ONLY. Both share one secret namespace per project. Use distinct secret names (e.g. STRIPE_KEY_DEV / STRIPE_KEY_PROD) or two amba projects for real env isolation.").option("--from-stdin", "Read the secret value from stdin instead of the positional arg. Mutually exclusive with <value>. Pipe in: `echo $KEY | amba secrets set NAME --from-stdin`.").action(async (name, value, opts) => {
 	await runAction(() => secretsSetCommand(name, value, {
 		function: opts.function,
 		env: opts.env ?? "dev",
 		fromStdin: opts.fromStdin
 	}));
 });
-secrets.command("list").description("List secret sync status for the current project").action(async () => {
-	await runAction(secretsListCommand);
+secrets.command("list").description("List secret sync status for the current project").option("--function <name>", "Filter to secrets for a single function (avoids listing all functions at once)").action(async (opts) => {
+	await runAction(() => secretsListCommand({ function: opts.function }));
 });
-secrets.command("unset <name>").description("Remove a secret from GCP Secret Manager (Workers Secret cleared on next deploy)").requiredOption("--function <name>", "Function name the secret binds to").action(async (name, opts) => {
+secrets.command("unset <name>").description("Remove a secret (Worker binding cleared on next deploy)").option("--function <name>", "Function the secret was bound to. Omit to remove the project-wide secret of this name.").action(async (name, opts) => {
 	await runAction(() => secretsUnsetCommand(name, opts));
 });
 const billing = program.command("billing").description("Per-project subscription, headroom, and spend controls");
@@ -6930,6 +7170,25 @@ sitesDomain.command("remove <hostname>").description("Detach a custom hostname (
 		zoneId: opts.zoneId
 	}));
 });
+const domains = program.command("domains").description("Buy a domain through Amba and connect it to a site");
+domains.command("search <query>").description("Search for available domains + prices (free)").option("--limit <n>", "Max suggestions (1-50, default 20)", (v) => parseInt(v, 10)).action(async (query, opts) => {
+	await runAction(() => domainsSearchCommand(query, { limit: opts.limit }));
+});
+domains.command("check <domains...>").description("Authoritative availability + price for specific domains (free)").action(async (domainArgs) => {
+	await runAction(() => domainsCheckCommand(domainArgs));
+});
+domains.command("buy <domain>").description("Buy a domain + connect it to a site (surfaces cost, asks to confirm)").requiredOption("--site <name>", "Site name to connect the domain to").option("--yes", "Skip the interactive cost confirmation prompt").option("--no-privacy", "Disable WHOIS privacy (privacy is on by default)").option("--no-auto-renew", "Disable auto-renew (on by default)").option("--years <n>", "Registration length in years (default 1)", (v) => parseInt(v, 10)).action(async (domain, opts) => {
+	await runAction(() => domainsBuyCommand(domain, {
+		site: opts.site,
+		yes: opts.yes,
+		noPrivacy: opts.privacy === false,
+		noAutoRenew: opts.autoRenew === false,
+		years: opts.years
+	}));
+});
+domains.command("list").description("List domains this project has purchased through Amba").action(async () => {
+	await runAction(domainsListCommand);
+});
 const aiProviders = program.command("ai").description("AI gateway — manage provider keys + prompts").command("providers").description("Per-project provider key registration (Anthropic, OpenAI)");
 aiProviders.command("add <provider>").description("Register an AI provider key. Plaintext stored securely server-side; a preview (first-6+last-4) is printed back. Use --from-stdin to keep the key out of shell history.").option("--key <value>", "Provider API key plaintext (alternative: --from-stdin)").option("--from-stdin", "Read the key from stdin instead of --key").action(async (provider, opts) => {
 	await runAction(() => aiProvidersAddCommand(provider, opts));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "amba — agent-native backend-as-a-service. Functions, collections, storage, AI, email, queues, sites — one CLI to spin up your project and ship to production. `npx @layers/amba init` to start.",
   "type": "module",
   "bin": {