@layers/amba 4.1.4 → 4.1.5

package/dist/api-client.d.ts

@@ -295,6 +295,8 @@ export interface FunctionDeploymentRow {
     /** Opt-in public flag (#17). True = X-Api-Key gate skipped for this
      *  function so external webhook senders can reach it. Default false. */
     is_public?: boolean;
+    /** Explicit per-deployment opt-in. Default false. */
+    forward_authorization?: boolean;
 }
 /** Provider-neutral lifecycle for an exact hostname bound to one function. */
 export interface FunctionDomain {
@@ -310,6 +312,9 @@ export interface FunctionDomain {
     dns_note?: string | null;
     cert_status: 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'active' | 'error';
     ownership_status: 'pending' | 'active' | 'error';
+    /** Raw point-in-time upstream states returned by attach/refresh. */
+    provider_status?: string | null;
+    provider_cert_status?: string | null;
     /** True only when certificate/ownership are active and routing reconciliation succeeded. */
     live: boolean;
     created_at: string;
@@ -383,10 +388,23 @@ export declare function deployFunctionViaApi(projectId: string, input: {
      * HMAC inside the handler.
      */
     public?: boolean;
+    /** Forward a verified client Authorization header to customer code. */
+    forward_authorization?: boolean;
 }): Promise<DeployFunctionResult>;
 export declare function listFunctionDeployments(projectId: string, options?: {
     activeOnly?: boolean;
 }): Promise<ApiListResponse<FunctionDeploymentRow>>;
+export interface FunctionDeployStatus {
+    status: 'available' | 'scheduled' | 'paused';
+    available: boolean;
+    paused: boolean;
+    retry_after_seconds: number | null;
+    retry_after_is_poll_interval: boolean;
+    maintenance_start_at: string | null;
+    estimated_resume_at: string | null;
+    reason: string | null;
+}
+export declare function getFunctionDeployStatus(projectId: string): Promise<ApiResponse<FunctionDeployStatus>>;
 /** Attach one exact hostname to one deployed function. */
 export declare function attachFunctionDomainViaApi(projectId: string, functionName: string, hostname: string): Promise<ApiResponse<AttachedFunctionDomain>>;
 /** List provider-neutral ownership/certificate status for a function's hostnames. */
@@ -433,6 +451,17 @@ export declare function scheduleFunction(projectId: string, input: {
 }): Promise<ApiResponse<{
     schedule_id: string;
 }>>;
+export interface FunctionScheduleRow {
+    schedule_id: string;
+    function_name: string;
+    enriched: boolean;
+    cron: string | null;
+    timezone: string | null;
+    next_fire_at: string | null;
+    last_fire_at: string | null;
+    paused: boolean | null;
+}
+export declare function listFunctionSchedules(projectId: string): Promise<ApiResponse<FunctionScheduleRow[]>>;
 export interface FunctionLogEvent {
     /** Sanitized log row — see `r2-log-reader.ts:SanitizedLogEvent`. Field-shape stable. */
     Event?: {
@@ -680,6 +709,9 @@ export interface SiteDomainRow {
     provider_hostname_id: string | null;
     cert_status: 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'active' | 'error';
     ownership_status: 'pending' | 'active' | 'error';
+    /** Raw point-in-time upstream values returned by attach/refresh. */
+    provider_status?: string | null;
+    provider_cert_status?: string | null;
     /** Edge Worker route reconciliation. */
     route_status: 'pending' | 'active' | 'error';
     /** Host-to-site KV reconciliation. */
@@ -740,6 +772,7 @@ export declare function archiveSite(projectId: string, name: string, confirm: st
 export interface DeleteCascadeSummary {
     domains_removed?: number;
     site_runtime_removed?: boolean;
+    function_schedule_removed?: boolean;
     runtime_script_removed?: boolean;
     function_deployments_marked_disabled?: number;
 }

package/dist/commands/functions.d.ts

@@ -42,15 +42,19 @@ export interface DeployOptions {
      * the handler — public skips the credential gate only.
      */
     public?: boolean;
+    /** Opt in to forwarding verified client Authorization to this function. */
+    forwardAuthorization?: boolean;
 }
 export declare function functionsDeployCommand(target: string, options?: DeployOptions): Promise<void>;
 export declare function functionsListCommand(): Promise<void>;
+export declare function functionsDeployStatusCommand(): Promise<void>;
 export declare function functionsDeleteCommand(name: string, options?: {
     confirm?: string;
 }): Promise<void>;
 export declare function functionsScheduleCommand(name: string, cron: string, options?: {
     tz?: string;
 }): Promise<void>;
+export declare function functionsSchedulesCommand(): Promise<void>;
 export interface DevOptions {
     /** Local port. Default 8787 (overridable per project). */
     port?: number;

package/dist/index.js

@@ -1018,7 +1018,8 @@ async function deployFunctionViaApi(projectId, input) {
 	const metadata = {
 		name: input.name,
 		...input.rate_limit !== void 0 ? { rate_limit: input.rate_limit } : {},
-		...input.public === true ? { public: true } : {}
+		...input.public === true ? { public: true } : {},
+		...input.forward_authorization === true ? { forward_authorization: true } : {}
 	};
 	fd.set("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }), "metadata.json");
 	return request("POST", `/projects/${projectId}/functions/deploy`, fd);
@@ -1026,6 +1027,9 @@ async function deployFunctionViaApi(projectId, input) {
 async function listFunctionDeployments(projectId, options = {}) {
 	return request("GET", `/projects/${projectId}/functions/deployments${options.activeOnly ? "?active=1" : ""}`);
 }
+async function getFunctionDeployStatus(projectId) {
+	return request("GET", `/projects/${projectId}/functions/deploy-status`);
+}
 function functionDomainsPath(projectId, functionName) {
 	return `/projects/${encodeURIComponent(projectId)}/functions/${encodeURIComponent(functionName)}/domains`;
 }
@@ -1048,6 +1052,9 @@ async function removeFunctionDomainViaApi(projectId, functionName, hostname) {
 async function scheduleFunction(projectId, input) {
 	return request("POST", `/projects/${projectId}/functions/schedules`, input);
 }
+async function listFunctionSchedules(projectId) {
+	return request("GET", `/projects/${projectId}/functions/schedules`);
+}
 async function getFunctionLogs(projectId, functionName, options = {}) {
 	const params = new URLSearchParams();
 	if (options.since) params.set("since", options.since);
@@ -5784,6 +5791,16 @@ async function functionsDeployCommand(target, options = {}) {
 	console.log(pc.bold(`  amba functions deploy ${pc.cyan(functionName)}`));
 	console.log(pc.dim("  ─────────────────────────────────"));
 	console.log();
+	if (!options.dryRun) {
+		let deployStatus = null;
+		try {
+			deployStatus = (await getFunctionDeployStatus(projectId)).data;
+		} catch (err) {
+			if (!(err instanceof ApiClientError && err.statusCode === 404)) throw err;
+		}
+		if (deployStatus && !deployStatus.available) throw new Error(formatDeployUnavailableMessage(deployStatus));
+		if (deployStatus?.status === "scheduled") console.log(pc.yellow("  !") + ` Maintenance is scheduled for ${deployStatus.maintenance_start_at ?? "a forthcoming window"}.`);
+	}
 	console.log(pc.dim(`  Bundling ${entryPoint}…`));
 	const bundle = await bundleFunction({ entryPoint });
 	printBundleReport(bundle);
@@ -5798,13 +5815,20 @@ async function functionsDeployCommand(target, options = {}) {
 			name: functionName,
 			bundleCode: bundle.code,
 			rate_limit: rateLimit,
-			public: options.public === true ? true : void 0
+			public: options.public === true ? true : void 0,
+			forward_authorization: options.forwardAuthorization === true ? true : void 0
 		});
 	} catch (err) {
 		if (err instanceof ApiClientError && err.statusCode === 503) {
+			try {
+				const status = (await getFunctionDeployStatus(projectId)).data;
+				if (!status.available) throw new Error(formatDeployUnavailableMessage(status));
+			} catch (statusErr) {
+				if (!(statusErr instanceof ApiClientError)) throw statusErr;
+			}
 			const base = err.message.trimEnd();
 			const sep = /[.!?]$/.test(base) ? " " : ". ";
-			throw new Error(`${base}${sep}The function platform is temporarily unavailable; retry in ~30s.`);
+			throw new Error(`${base}${sep}Check \`amba functions deploy-status\` before retrying.`);
 		}
 		throw err;
 	}
@@ -5812,8 +5836,15 @@ async function functionsDeployCommand(target, options = {}) {
 	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`));
 	if (options.public === true) console.log(pc.yellow("  ! Public") + pc.dim(" — no X-Api-Key required. Verify the webhook signature inside your handler."));
+	if (options.forwardAuthorization === true) console.log(pc.yellow("  ! Authorization forwarding enabled") + pc.dim(" — the verified client Bearer is visible to this function; X-Api-Key is never forwarded."));
 	console.log();
 }
+function formatDeployUnavailableMessage(status) {
+	const reason = status.reason ? ` (${status.reason})` : "";
+	if (status.estimated_resume_at) return `Function deployments are paused${reason}. Estimated resume: ${status.estimated_resume_at}.`;
+	if (status.retry_after_seconds !== null) return `Function deployments are paused${reason}. ${status.retry_after_is_poll_interval ? "Poll deploy-status again" : "Retry"} in ${status.retry_after_seconds}s; no end time is known yet.`;
+	return `Function deployments are paused${reason}. Check \`amba functions deploy-status\` before retrying.`;
+}
 async function functionsListCommand() {
 	const res = await listFunctionDeployments((await loadProjectConfig()).projectId, { activeOnly: true });
 	console.log();
@@ -5825,12 +5856,25 @@ async function functionsListCommand() {
 	for (const d of res.data) console.log(`  ${pc.bold(d.name)} ${pc.dim("v" + d.version)}  ` + pc.dim(`sha=${d.bundle_sha.slice(0, 12)}…  ${d.created_at}`));
 	console.log();
 }
+async function functionsDeployStatusCommand() {
+	const res = await getFunctionDeployStatus((await loadProjectConfig()).projectId);
+	if (res.data.available) {
+		console.log(pc.green("  ✓") + " Function deployments are available.");
+		if (res.data.status === "scheduled") {
+			console.log(pc.yellow("  !") + ` Maintenance is scheduled for ${res.data.maintenance_start_at ?? "a forthcoming window"}.`);
+			if (res.data.estimated_resume_at) console.log(pc.dim(`    Estimated resume: ${res.data.estimated_resume_at}.`));
+		}
+		return;
+	}
+	console.log(pc.yellow("  !") + " Function deployments are paused for platform maintenance.");
+	if (res.data.retry_after_seconds !== null) console.log(pc.dim(res.data.retry_after_is_poll_interval ? `    Poll deploy-status again in ${res.data.retry_after_seconds}s; no end time is known yet.` : `    Estimated resume: ${res.data.estimated_resume_at} (Retry-After ${res.data.retry_after_seconds}s).`));
+}
 async function functionsDeleteCommand(name, options = {}) {
 	validateFunctionName$1(name);
 	if (!options.confirm || options.confirm !== name) throw new Error(`Delete is destructive. Pass --confirm ${name} to proceed. Clients calling this function will start 404'ing immediately.`);
 	const cascade = (await deleteFunctionViaApi((await loadProjectConfig()).projectId, name, { confirm: name })).data.cascade;
 	console.log(pc.green("  ✓") + ` Deleted ${pc.bold(name)}.`);
-	console.log(pc.dim(`    Cascade: runtime_script_removed=${cascade.runtime_script_removed ?? false}, function_deployments_marked_disabled=${cascade.function_deployments_marked_disabled ?? 0}`));
+	console.log(pc.dim(`    Cascade: function_schedule_removed=${cascade.function_schedule_removed ?? false}, runtime_script_removed=${cascade.runtime_script_removed ?? false}, function_deployments_marked_disabled=${cascade.function_deployments_marked_disabled ?? 0}`));
 }
 async function functionsScheduleCommand(name, cron, options = {}) {
 	const projectConfig = await loadProjectConfig();
@@ -5846,6 +5890,25 @@ async function functionsScheduleCommand(name, cron, options = {}) {
 	console.log(pc.dim(`    schedule_id: ${res.data.schedule_id}`));
 	console.log();
 }
+async function functionsSchedulesCommand() {
+	const res = await listFunctionSchedules((await loadProjectConfig()).projectId);
+	console.log();
+	if (res.data.length === 0) {
+		console.log(pc.dim("  No function schedules registered."));
+		console.log();
+		return;
+	}
+	for (const schedule of res.data) {
+		if (!schedule.enriched) {
+			console.log(`${pc.bold(schedule.function_name)}  ${pc.yellow("metadata unavailable")}`);
+			continue;
+		}
+		const state = schedule.paused ? pc.yellow("paused") : pc.green("active");
+		console.log(`  ${pc.bold(schedule.function_name)}  ${pc.cyan(schedule.cron ?? "?")}  ${pc.dim(schedule.timezone ?? "UTC")}  ${state}`);
+		console.log(pc.dim(`    last=${schedule.last_fire_at ?? "never"}  next=${schedule.next_fire_at ?? "unknown"}`));
+	}
+	console.log();
+}
 /**
 * `amba functions dev <file>` — run the function locally with file-change
 * hot reload.
@@ -6420,7 +6483,10 @@ function printEvents(events, asJson) {
 			console.log(`${pc.dim(ts)} ${pc.cyan(script)} ${level} ${msg}`);
 		}
 		if (e.Exceptions && e.Exceptions.length > 0) for (const ex of e.Exceptions) console.log(`${pc.dim(ts)} ${pc.cyan(script)} ${pc.red("[exception]")} ${ex.Name ?? "Error"}: ${ex.Message ?? ""}`);
-		if ((!e.Logs || e.Logs.length === 0) && (!e.Exceptions || e.Exceptions.length === 0) && e.Outcome && e.Outcome !== "ok") console.log(`${pc.dim(ts)} ${pc.cyan(script)} ${pc.yellow("[outcome]")} ${e.Outcome}`);
+		if ((!e.Logs || e.Logs.length === 0) && (!e.Exceptions || e.Exceptions.length === 0) && e.Outcome) {
+			const outcome = e.Outcome === "ok" ? pc.green("[outcome]") : pc.yellow("[outcome]");
+			console.log(`${pc.dim(ts)} ${pc.cyan(script)} ${outcome} ${e.Outcome}`);
+		}
 	}
 }
 function renderLevel(level) {
@@ -9695,7 +9761,7 @@ async function diffConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
 //#endregion
 //#region src/index.ts
 const program = new Command();
-program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.1.4");
+program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.1.5");
 program.option("--token <pat>", "Use a Personal Access Token for headless / CI / agent use (overrides ~/.amba/credentials.json + AMBA_PAT env)");
 program.hook("preAction", (thisCommand) => {
 	setBearerOverride(resolveTokenSource({
@@ -9837,18 +9903,24 @@ program.command("schema").description("Schema export commands").command("export"
 	}));
 });
 const functions = program.command("functions").description("Customer serverless functions deployed to the edge");
-functions.command("deploy <target>").description("Bundle a function (a single file OR a directory) and deploy to the dispatch namespace. A directory resolves its entry by convention (index.ts/js/mjs) or via --entry.").option("--name <name>", "Function name (default: file name without extension, or the directory leaf name)").option("--entry <file>", "Entry file when <target> is a directory (relative to it). Default: index.ts/js/mjs.").option("--dry-run", "Bundle and report size without uploading").option("--rate-limit-window <duration>", "Rate-limit window: 60s | 5m | 1h").option("--rate-limit-max <int>", "Rate-limit max requests per window", (v) => Number.parseInt(v, 10)).option("--rate-limit-key <kind>", "Rate-limit bucket key: user_id | ip").option("--public", "Deploy WITHOUT the X-Api-Key gate so external webhook senders can call it. You MUST verify the webhook signature in your handler. Default: private.").action(async (target, opts) => {
+functions.command("deploy <target>").description("Bundle a function (a single file OR a directory) and deploy to the dispatch namespace. A directory resolves its entry by convention (index.ts/js/mjs) or via --entry.").option("--name <name>", "Function name (default: file name without extension, or the directory leaf name)").option("--entry <file>", "Entry file when <target> is a directory (relative to it). Default: index.ts/js/mjs.").option("--dry-run", "Bundle and report size without uploading").option("--rate-limit-window <duration>", "Rate-limit window: 60s | 5m | 1h").option("--rate-limit-max <int>", "Rate-limit max requests per window", (v) => Number.parseInt(v, 10)).option("--rate-limit-key <kind>", "Rate-limit bucket key: user_id | ip").option("--public", "Deploy WITHOUT the X-Api-Key gate so external webhook senders can call it. You MUST verify the webhook signature in your handler. Default: private.").option("--forward-authorization", "Forward a verified client Authorization Bearer to this function. X-Api-Key and internal trigger credentials remain stripped.").action(async (target, opts) => {
 	await runAction(() => functionsDeployCommand(target, opts));
 });
 functions.command("list").description("List active functions for the current project").action(async () => {
 	await runAction(functionsListCommand);
 });
+functions.command("deploy-status").description("Show whether function deployments are available or paused for maintenance").action(async () => {
+	await runAction(functionsDeployStatusCommand);
+});
 functions.command("delete <name>").description("Disable + remove a function from the dispatch namespace (destructive)").option("--confirm <name>", "Pass the function name to confirm deletion").action(async (name, opts) => {
 	await runAction(() => functionsDeleteCommand(name, { confirm: opts.confirm }));
 });
 functions.command("schedule <name> <cron>").description("Register a cron schedule that invokes a deployed function").option("--tz <iana>", "IANA timezone for the schedule (default: UTC)").action(async (name, cron, opts) => {
 	await runAction(() => functionsScheduleCommand(name, cron, opts));
 });
+functions.command("schedules").description("List function schedules with cron, timezone, state, and last/next fire times").action(async () => {
+	await runAction(functionsSchedulesCommand);
+});
 functions.command("dev <file>").description("Run a local dev server for your function with hot reload on file changes").option("--port <n>", "Port to listen on (default 8787)", (v) => parseInt(v, 10)).option("--no-watch", "Disable file-change hot reload").action(async (file, opts) => {
 	await runAction(() => functionsDevCommand(file, {
 		port: opts.port,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "amba — agent-native backend-as-a-service. Functions, collections, storage, AI, email, queues, sites, and `amba ship` to take an Expo app live on the App Store + Google Play. `npx @layers/amba init` to start.",
   "type": "module",
   "bin": {
@@ -49,7 +49,7 @@
     "tsdown": "^0.12.5",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@layers/amba-mcp": "4.0.8",
+    "@layers/amba-mcp": "4.0.9",
     "@layers/amba-shared": "4.0.4"
   },
   "scripts": {