@fabrika/provider-zerops 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -24,6 +24,16 @@
 			"bun": "./src/cli.ts",
 			"types": "./src/cli.ts",
 			"default": "./src/cli.ts"
+		},
+		"./installation": {
+			"bun": "./src/installation/index.ts",
+			"types": "./src/installation/index.ts",
+			"default": "./src/installation/index.ts"
+		},
+		"./installation/topology": {
+			"bun": "./src/installation/topology/index.ts",
+			"types": "./src/installation/topology/index.ts",
+			"default": "./src/installation/topology/index.ts"
 		}
 	},
 	"scripts": {
@@ -32,9 +42,12 @@
 		"gen:schema": "bun scripts/generate-zerops-types.ts"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.2.0",
-		"@fabrika/auth-core": "^0.2.0",
-		"@fabrika/provider-contract": "^0.2.0",
-		"@fabrika/proxy-contract": "^0.2.0"
+		"zod": "^3.25.76",
+		"@fabrika/auth": "^0.3.1",
+		"@fabrika/auth-core": "^0.3.1",
+		"@fabrika/installation-init": "^0.3.1",
+		"@fabrika/provider-contract": "^0.3.1",
+		"@fabrika/proxy-core": "^0.3.1",
+		"yaml": "^2.9.1"
 	}
 }

package/src/api/client.ts

@@ -0,0 +1,522 @@
+import { z } from 'zod'
+import type { Sleeper } from '../collaborators'
+import { apiError, isAppVersionNotFoundResponse, ZeropsApiError } from './errors'
+import { waitForProcess } from './polling'
+import {
+	appVersionListSchema,
+	appVersionSchema,
+	importResultSchema,
+	integrationTokenSchema,
+	logAccessSchema,
+	processSchema,
+	projectMatchesSchema,
+	projectSchema,
+	readResponse,
+	serviceEnvSchema,
+	serviceSchema,
+} from './readers'
+import { parseServiceEnvResponse } from './service-env-response'
+import type { ZeropsApi, ZeropsApiOptions, ZeropsAppVersion, ZeropsLogLine } from './types'
+
+/**
+ * `sensitive` on every user-data WRITE, create and update alike. Required by the platform — omitting it answers
+ * `400 invalidUserInput` with `{"sensitive":["field is required"]}` (measured live, 2026-08-18) — and
+ * `true` because most of what fabrika writes is a credential. It costs nothing to read: a sensitive
+ * variable's `content` still comes back verbatim from `GET /service-stack/{id}/env`, also measured, so the
+ * compare-before-write both `platform deploy` and the create-only credential slots depend on still works.
+ */
+const SENSITIVE_USER_DATA = true
+
+/** The RFC3339 stamp the plaintext log window puts first on every line. Anchored so a bare year cannot pass. */
+const LOG_LINE_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+
+const appVersionReservationSchema = z.object({
+	id: z.string().refine((value) => value.trim() !== ''),
+	uploadUrl: z.string().refine((value) => value.trim() !== ''),
+	serviceStackId: z.string().refine((value) => value.trim() !== ''),
+})
+const triggerPipelineSchema = z.object({ process: processSchema.nullish() })
+const deleteAppVersionSchema = z.object({ success: z.literal(true) })
+
+// ── default (real) implementation ───────────────────────────────────────────────
+
+/** Base URL of the Zerops public REST API. */
+export const ZEROPS_API_BASE = 'https://api.app-prg1.zerops.io/api/rest/public'
+
+/** The platform's code for "this service stack already has a variable under that key". */
+const USER_DATA_DUPLICATE_KEY = 'userDataDuplicateKey'
+
+/** The platform's code for a service stack it cannot find — sent with a 400, not a 404. */
+const ZEROPS_SERVICE_STACK_NOT_FOUND = 'serviceStackNotFound'
+
+const timerSleep: Sleeper = (ms, signal) =>
+	new Promise<void>((resolve) => {
+		if (signal.aborted) {
+			resolve()
+			return
+		}
+		const timer = setTimeout(() => {
+			signal.removeEventListener('abort', onAbort)
+			resolve()
+		}, ms)
+		const onAbort = (): void => {
+			clearTimeout(timer)
+			resolve()
+		}
+		signal.addEventListener('abort', onAbort, { once: true })
+	})
+
+/** Build the real client. Every request carries the bearer and the run's signal. */
+export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
+	const base = (options.baseUrl ?? ZEROPS_API_BASE).replace(/\/+$/, '')
+	const doFetch = options.fetchImpl ?? fetch
+	// Its own, rather than `collaborators`' — that module imports this one, so taking the value back would close a cycle.
+	const sleep = options.sleep ?? timerSleep
+	const abortError = (): DOMException => new DOMException('The operation was aborted', 'AbortError')
+	const isAbortError = (error: unknown): boolean => error instanceof Error && error.name === 'AbortError'
+	const SERVICE_ENV_RESPONSE_MAX_BYTES = 8 * 1024 * 1024
+	class ResponseByteBoundError extends Error {}
+
+	const boundedJson = async (response: Response, label: string, maxBytes: number, signal: AbortSignal): Promise<unknown> => {
+		if (signal.aborted) {
+			void response.body?.cancel().catch(() => {})
+			throw abortError()
+		}
+		const contentLength = response.headers.get('content-length')
+		if (contentLength !== null) {
+			const declaredBytes = Number(contentLength)
+			if (Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+				void response.body?.cancel().catch(() => {})
+				throw new ResponseByteBoundError(`zerops: ${label} response exceeded its byte bound`)
+			}
+		}
+		if (response.body === null) return null
+		const reader = response.body.getReader()
+		let abortRead = (): void => {}
+		const aborted = new Promise<never>((_resolve, reject) => {
+			abortRead = (): void => {
+				void reader.cancel().catch(() => {})
+				reject(abortError())
+			}
+			signal.addEventListener('abort', abortRead, { once: true })
+			if (signal.aborted) abortRead()
+		})
+		const chunks: Uint8Array[] = []
+		let receivedBytes = 0
+		try {
+			while (true) {
+				const next = await Promise.race([reader.read(), aborted])
+				if (signal.aborted) throw abortError()
+				if (next.done) break
+				receivedBytes += next.value.byteLength
+				if (receivedBytes > maxBytes) {
+					void reader.cancel().catch(() => {})
+					throw new ResponseByteBoundError(`zerops: ${label} response exceeded its byte bound`)
+				}
+				chunks.push(next.value)
+			}
+		} finally {
+			signal.removeEventListener('abort', abortRead)
+		}
+		const bytes = new Uint8Array(receivedBytes)
+		let offset = 0
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset)
+			offset += chunk.byteLength
+		}
+		return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+	}
+
+	const request = async (
+		label: string,
+		method: string,
+		path: string,
+		/**
+		 * `redactDetail` drops the server's message from the thrown error, keeping only its code. Set it on
+		 * any call whose BODY carries a secret value: a validation error can quote what it rejected, and an
+		 * error that echoes a secret into a deploy log is a leak whichever end wrote it.
+		 * `omitErrorResponseDetails` also drops the code for upload flows whose response may carry a
+		 * credential; nothing from that response body may reach an error.
+		 */
+		init: {
+			body?: unknown
+			signal: AbortSignal
+			redactDetail?: boolean
+			omitErrorResponseDetails?: boolean
+			/** Pretrigger reservation cleanup needs verified absence, never arbitrary response text or codes. */
+			preserveAppVersionNotFound?: boolean
+			responseMaxBytes?: number
+		},
+	): Promise<unknown> => {
+		if (init.signal.aborted) {
+			throw abortError()
+		}
+		const headers: Record<string, string> = { authorization: `Bearer ${options.token}`, accept: 'application/json' }
+		if (init.body !== undefined) {
+			headers['content-type'] = 'application/json'
+		}
+		let response: Response
+		try {
+			response = await doFetch(`${base}${path}`, {
+				method,
+				headers,
+				body: init.body === undefined ? undefined : JSON.stringify(init.body),
+				signal: init.signal,
+			})
+		} catch (error) {
+			if (init.signal.aborted || isAbortError(error)) throw abortError()
+			throw error
+		}
+		let payload: unknown
+		try {
+			payload = init.responseMaxBytes === undefined
+				? await response.json()
+				: await boundedJson(response, label, init.responseMaxBytes, init.signal)
+		} catch (error) {
+			if (init.signal.aborted || isAbortError(error)) throw abortError()
+			if (error instanceof ResponseByteBoundError) throw error
+			payload = null
+		}
+		if (!response.ok) {
+			if (init.omitErrorResponseDetails === true) {
+				if (init.preserveAppVersionNotFound === true && response.status === 400 && isAppVersionNotFoundResponse(payload)) {
+					throw new ZeropsApiError(`zerops: ${label} failed (400) — appVersionNotFound`, 400, 'appVersionNotFound')
+				}
+				throw new ZeropsApiError(`zerops: ${label} failed (${response.status})`, response.status, '')
+			}
+			throw apiError(label, response.status, payload, init.redactDetail === true)
+		}
+		return payload
+	}
+
+	const invalidResponse = (label: string): Error => new Error(`zerops: ${label} returned an invalid response`)
+
+	const PAGE_SIZE = 100
+	const readAllPages = async <Item>(
+		label: string,
+		path: string,
+		signal: AbortSignal,
+		itemSchema: z.ZodType<Item, z.ZodTypeDef, unknown>,
+	): Promise<Item[]> => {
+		const pageSchema = z.object({ list: z.array(itemSchema), total: z.number().int().nonnegative() })
+		const items: Item[] = []
+		let offset = 0
+		while (true) {
+			const separator = path.includes('?') ? '&' : '?'
+			const payload = await request(label, 'GET', `${path}${separator}limit=${PAGE_SIZE}&offset=${offset}`, { signal })
+			const { list: page, total } = readResponse(label, pageSchema, payload)
+			items.push(...page)
+			if (items.length >= total) {
+				return items
+			}
+			if (page.length === 0) {
+				throw new Error(`zerops: ${label} ended before total`)
+			}
+			offset += page.length
+		}
+	}
+
+	/**
+	 * Named so `putServiceEnv` can reach it: the conflict path needs the record id, and the ONE endpoint
+	 * that hands it over on every service is `/env` (`/user-data` answers 400 unconditionally).
+	 */
+	const listServiceEnv: ZeropsApi['listServiceEnv'] = async ({ serviceId, signal }) => {
+		const payload = await request('list service env', 'GET', `/service-stack/${serviceId}/env`, {
+			signal,
+			responseMaxBytes: SERVICE_ENV_RESPONSE_MAX_BYTES,
+		})
+		try {
+			return parseServiceEnvResponse(payload, serviceId)
+		} catch {
+			throw invalidResponse('list service env')
+		}
+	}
+
+	const getProcess: ZeropsApi['getProcess'] = async ({ processId, signal }) =>
+		readResponse('get process', processSchema, await request('get process', 'GET', `/process/${processId}`, { signal }))
+
+	/**
+	 * Wait out the `stack.updateUserData` process every user-data write answers with.
+	 *
+	 * While one runs the platform refuses the NEXT operation on that service with `400
+	 * userDataSyncRunning` — which is how a deploy that wrote an app's environment and then asked for a
+	 * build failed, one second before the sync it had started finished. Measured live: PENDING → RUNNING →
+	 * FINISHED in about three seconds, on a deployed service and on one that has never had code alike.
+	 *
+	 * The response is recognised by `actionName`, not by having an `id`: a user-data RECORD carries an id
+	 * too, and polling `/process/{recordId}` would hang instead of failing. An unrecognised response is
+	 * left alone — nothing then says the write is still settling.
+	 */
+	const awaitUserDataSync = async (payload: unknown, label: string, signal: AbortSignal): Promise<void> => {
+		const started = processSchema.safeParse(payload)
+		if (!started.success || started.data.actionName === undefined || started.data.actionName.trim() === '') {
+			return
+		}
+		await waitForProcess({ api: { getProcess }, processId: started.data.id, sleep, signal, label })
+	}
+
+	return {
+		importServices: async ({ projectId, yaml, signal }) =>
+			readResponse(
+				'service-stack import',
+				importResultSchema,
+				await request('service-stack import', 'POST', `/project/${projectId}/service-stack/import`, { body: { yaml }, signal }),
+			),
+
+		importProject: async ({ clientId, yaml, signal }) =>
+			readResponse(
+				'project import',
+				importResultSchema,
+				await request('project import', 'POST', `/client/${clientId}/project/import`, { body: { yaml }, signal }),
+			),
+
+		triggerPipeline: async ({ serviceId, buildFromGit, zeropsYaml, zeropsSetup, signal }) => {
+			const body: Record<string, unknown> = {}
+			if (buildFromGit !== undefined) {
+				body['buildFromGit'] = buildFromGit
+			}
+			if (zeropsYaml !== undefined) {
+				body['zeropsYaml'] = zeropsYaml
+			}
+			if (zeropsSetup !== undefined) {
+				body['zeropsSetup'] = zeropsSetup
+			}
+			const payload = await request('trigger-pipeline', 'PUT', `/service-stack/${serviceId}/trigger-pipeline`, { body, signal })
+			return readResponse('trigger-pipeline', triggerPipelineSchema, payload).process ?? null
+		},
+
+		createAppVersion: async ({ serviceId, name, signal }) => {
+			const body = name === undefined ? {} : { name }
+			const payload = await request('create app-version', 'POST', `/service-stack/${serviceId}/app-version`, {
+				body,
+				signal,
+				omitErrorResponseDetails: true,
+			})
+			const result = appVersionReservationSchema.safeParse(payload)
+			if (!result.success || result.data.serviceStackId !== serviceId) {
+				throw invalidResponse('create app-version')
+			}
+			return {
+				id: result.data.id,
+				uploadUrl: result.data.uploadUrl,
+			}
+		},
+
+		buildAndDeployAppVersion: async ({ appVersionId, zeropsYaml, zeropsYamlSetup, signal }) => {
+			const body = zeropsYamlSetup === undefined ? { zeropsYaml } : { zeropsYaml, zeropsYamlSetup }
+			// `redactDetail`, not `omitErrorResponseDetails`: this request body is the app's COMMITTED
+			// descriptor and this response carries no upload URL, so there is nothing here to protect by
+			// dropping the code as well — and a bare `(400)` is what made `userDataSyncRunning` cost a day.
+			const payload = await request('build and deploy app-version', 'PUT', `/app-version/${appVersionId}/build-and-deploy`, {
+				body,
+				signal,
+				redactDetail: true,
+			})
+			const process = readResponse('build and deploy app-version', processSchema, payload)
+			if (process.appVersionId !== undefined && process.appVersionId !== appVersionId) {
+				throw invalidResponse('build and deploy app-version')
+			}
+			return { ...process, appVersionId }
+		},
+
+		deleteAppVersion: async ({ appVersionId, signal }) => {
+			const payload = await request('delete app-version', 'DELETE', `/app-version/${appVersionId}`, {
+				signal,
+				omitErrorResponseDetails: true,
+				preserveAppVersionNotFound: true,
+			})
+			readResponse('delete app-version', deleteAppVersionSchema, payload)
+		},
+
+		getAppVersion: async ({ appVersionId, signal }) =>
+			readResponse('get app-version', appVersionSchema, await request('get app-version', 'GET', `/app-version/${appVersionId}`, { signal })),
+
+		latestAppVersion: async ({ serviceId, signal }) => {
+			const payload = await request('list app-versions', 'GET', `/service-stack/${serviceId}/app-version?limit=25`, { signal })
+			const versions = readResponse('list app-versions', appVersionListSchema, payload).list
+			// Highest `sequence` wins — the list's order is not documented, the sequence's meaning is.
+			return versions.reduce<ZeropsAppVersion | null>(
+				(best, version) => (best === null || (version.sequence ?? -1) > (best.sequence ?? -1) ? version : best),
+				null,
+			)
+		},
+
+		cancelBuild: async ({ appVersionId, signal }) => {
+			await request('cancel-build', 'PUT', `/app-version/${appVersionId}/cancel-build`, { signal })
+		},
+
+		getProcess,
+
+		enableSubdomainAccess: async ({ serviceId, signal }) => {
+			// No body: the operation takes none, and sending one would add a content-type the platform did not ask for.
+			await request('enable subdomain access', 'PUT', `/service-stack/${serviceId}/enable-subdomain-access`, { signal })
+		},
+
+		getService: async ({ serviceId, signal }) =>
+			readResponse('get service', serviceSchema, await request('get service', 'GET', `/service-stack/${serviceId}`, { signal })),
+
+		findService: async ({ projectId, hostname, signal }) => {
+			try {
+				return readResponse(
+					'find service',
+					serviceSchema,
+					await request('find service', 'GET', `/service-stack-by-name/${projectId}/${encodeURIComponent(hostname)}`, { signal }),
+				)
+			} catch (error) {
+				// A missing service is an answer, not a failure; anything else propagates. The live platform
+				// says it as 400 `serviceStackNotFound` (docs/reference/zerops-platform.md), not as a 404.
+				if (error instanceof ZeropsApiError && (error.status === 404 || error.code === ZEROPS_SERVICE_STACK_NOT_FOUND)) {
+					return null
+				}
+				throw error
+			}
+		},
+
+		getProject: async ({ projectId, signal }) => {
+			const payload = await request('get project', 'GET', `/project/${projectId}`, { signal })
+			return readResponse('get project', projectSchema, payload)
+		},
+
+		listProjects: async ({ clientId, signal }) => readAllPages('list projects', `/client/${clientId}/project`, signal, projectSchema),
+
+		findProjects: async ({ clientId, name, signal }) => {
+			const payload = await request(
+				'find projects',
+				'GET',
+				`/client/${clientId}/projects-by-name/${encodeURIComponent(name)}`,
+				{ signal },
+			)
+			return readResponse('find projects', projectMatchesSchema, payload).projects
+		},
+
+		listProjectServices: async ({ projectId, signal }) =>
+			readAllPages('list project services', `/project/${projectId}/service-stack`, signal, serviceSchema),
+
+		listServiceEnv,
+
+		createServiceEnv: async ({ serviceId, key, value, signal }) => {
+			let started: unknown
+			try {
+				started = await request('create-only service env', 'POST', `/service-stack/${serviceId}/user-data`, {
+					body: { key, content: value, sensitive: SENSITIVE_USER_DATA },
+					signal,
+					omitErrorResponseDetails: true,
+				})
+			} catch (error) {
+				if (error instanceof Error && error.name === 'AbortError') throw error
+				throw new Error('zerops: create-only service env failed')
+			}
+			await awaitUserDataSync(started, `the user-data sync on service ${serviceId}`, signal)
+		},
+
+		putServiceEnv: async ({ serviceId, key, value, signal }) => {
+			const label = `the user-data sync on service ${serviceId}`
+			// `redactDetail` on both writes: this is the one place a secret VALUE is in the request body.
+			try {
+				const created = await request('create service env', 'POST', `/service-stack/${serviceId}/user-data`, {
+					body: { key, content: value, sensitive: SENSITIVE_USER_DATA },
+					signal,
+					redactDetail: true,
+				})
+				await awaitUserDataSync(created, label, signal)
+				return
+			} catch (error) {
+				if (!(error instanceof ZeropsApiError) || error.code !== USER_DATA_DUPLICATE_KEY) {
+					throw error
+				}
+			}
+			// Only the conflict reads, and only then: the create must work on a service that has never been
+			// deployed, which is the whole of ADR-0004's bring-up order.
+			const existing = (await listServiceEnv({ serviceId, signal })).find((entry) => entry.key === key)
+			if (existing === undefined || existing.id === '') {
+				// The service declares the key in its own `zerops.yaml` (`type: ENV`), which conflicts on create
+				// yet never appears in the env list. Replacing it here would be undone by the next deploy.
+				throw new Error(
+					`zerops: service ${serviceId} already defines \`${key}\` outside the environment API — it cannot be written`,
+				)
+			}
+			const updated = await request('update service env', 'PUT', `/user-data/${existing.id}`, {
+				body: { key, content: value, sensitive: SENSITIVE_USER_DATA },
+				signal,
+				redactDetail: true,
+			})
+			await awaitUserDataSync(updated, label, signal)
+		},
+
+		deleteServiceEnv: async ({ envId, signal }) => {
+			const deleted = await request('delete service env', 'DELETE', `/user-data/${envId}`, { signal })
+			await awaitUserDataSync(deleted, `the user-data sync for record ${envId}`, signal)
+		},
+
+		getProjectEnv: async ({ projectEnvId, signal }) =>
+			readResponse('get project env', serviceEnvSchema, await request('get project env', 'GET', `/project-env/${projectEnvId}`, { signal })),
+
+		createIntegrationToken: async ({ clientId, name, projects, roleCode, canCreateProjects, signal }) =>
+			// `redactDetail`: unlike every other write here the SECRET is in the RESPONSE, not the request, so
+			// this is the one error envelope that could quote a minted token back at us.
+			readResponse(
+				'create integration token',
+				integrationTokenSchema,
+				await request('create integration token', 'POST', `/client/${clientId}/integration-token`, {
+					body: {
+						name,
+						roleCode: roleCode ?? 'NO_ACCESS',
+						// Always sent, like `roleCode`: a security-relevant field that never reaches the wire is a
+						// field nobody can review.
+						canCreateProjects: canCreateProjects ?? false,
+						projects: projects.map((grant) => ({ projectId: grant.projectId, roleCode: grant.roleCode })),
+					},
+					signal,
+					redactDetail: true,
+				}),
+			),
+
+		getLogAccess: async ({ projectId, signal }) => {
+			const payload = await request('get log access', 'GET', `/project/${projectId}/log`, { signal })
+			return readResponse('get log access', logAccessSchema, payload)
+		},
+
+		readBuildLog: async ({ access, serviceId, appVersionId, since, limit, signal }) => {
+			if (access.urlPlain === '') {
+				return []
+			}
+			const separator = access.urlPlain.includes('?') ? '&' : '?'
+			const readWindow = async (terms: string): Promise<{ lines: ZeropsLogLine[]; error: unknown }> => {
+				try {
+					const url = `${access.urlPlain}${separator}${terms}&limit=${limit ?? 200}`
+					const response = await doFetch(url, { headers: { authorization: `Bearer ${access.accessToken}` }, signal })
+					if (!response.ok) {
+						throw new Error(`zerops: read build log failed (${response.status})`)
+					}
+					const text = await response.text()
+					const lines = text.split('\n').filter((line) => line.trim() !== '').map((line) => {
+						const head = line.slice(0, Math.max(line.indexOf(' '), 0))
+						return LOG_LINE_TIMESTAMP.test(head) ? { timestamp: head, message: line } : { message: line }
+					})
+					return { lines, error: undefined }
+				} catch (error) {
+					return { lines: [], error }
+				}
+			}
+			// Selected by tag alone: the build runs on a builder stack, so pairing the tag with the runtime
+			// service id matches nothing (see the interface).
+			const build = appVersionId === undefined ? undefined : await readWindow(`tags=${encodeURIComponent(`zbuilder@${appVersionId}`)}`)
+			const runtime = since === undefined ? undefined : await readWindow(`serviceStackId=${encodeURIComponent(serviceId)}`)
+			const attempted = [build, runtime].filter((result) => result !== undefined)
+			if (attempted.length === 0) {
+				return []
+			}
+			// Independent windows: only a failure of every one attempted is worth raising.
+			const failure = attempted.find((result) => result.error !== undefined)
+			if (failure !== undefined && attempted.every((result) => result.error !== undefined)) {
+				throw failure.error
+			}
+			const boundary = since === undefined ? Number.NaN : Date.parse(since)
+			// The runtime window carries every version that ever ran, so a line the driver cannot date is dropped.
+			const runtimeLines = runtime === undefined || Number.isNaN(boundary)
+				? runtime?.lines ?? []
+				: runtime.lines.filter((line) => line.timestamp !== undefined && Date.parse(line.timestamp) >= boundary)
+			return [...build?.lines ?? [], ...runtimeLines]
+		},
+	}
+}

package/src/api/errors.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod'
+
+const errorDetailShape = {
+	code: z.string().optional().catch(undefined),
+	message: z.string().optional().catch(undefined),
+	// An element that is not an object still counts: `isAppVersionNotFoundResponse` requires exactly one.
+	meta: z.array(z.object({ code: z.string().optional().catch(undefined) }).catch({})).catch([]),
+}
+const errorDetailSchema = z.object(errorDetailShape).catch({ meta: [] })
+const errorEnvelopeSchema = z.object({ ...errorDetailShape, error: errorDetailSchema }).catch({ meta: [], error: { meta: [] } })
+
+export const isAppVersionNotFoundResponse = (value: unknown): boolean => {
+	const { error: inner, ...outer } = errorEnvelopeSchema.parse(value)
+	const metadata = [...outer.meta, ...inner.meta]
+	return inner.code === 'appVersionNotFound' || outer.code === 'appVersionNotFound'
+		|| (metadata.length === 1 && metadata[0]?.code === 'appVersionNotFound')
+}
+
+/**
+ * A non-2xx answer from the Zerops API. `code` is the platform's own error identifier, so a caller can
+ * branch on `userDataDuplicateKey` rather than matching a prose message.
+ */
+export class ZeropsApiError extends Error {
+	constructor(message: string, readonly status: number, readonly code: string) {
+		super(message)
+		this.name = 'ZeropsApiError'
+	}
+}
+
+/**
+ * The platform's code for "this service publishes no HTTP port", the answer `enableSubdomainAccess` gives
+ * before a service's first deploy. Exported so a caller can say what is missing instead of relaying prose.
+ */
+export const ZEROPS_SERVICE_NOT_HTTP = 'serviceStackIsNotHttp'
+
+/**
+ * Turn a non-2xx response into a `ZeropsApiError`. Zerops answers with `{ error: { code, message, meta } }`
+ * (the envelope observed live; the OpenAPI `Error` schema shows the inner `{ code, message }`).
+ *
+ * `redactDetail` drops the server's MESSAGE, which a validation error can fill with the value it
+ * rejected. The CODE is a fixed identifier and is kept either way — without it nothing downstream can
+ * tell a duplicate key from a missing service.
+ */
+export const apiError = (label: string, status: number, body: unknown, redactDetail: boolean): ZeropsApiError => {
+	const { error: inner, ...outer } = errorEnvelopeSchema.parse(body)
+	const code = inner.code ?? outer.code ?? ''
+	const message = redactDetail ? '' : (inner.message ?? outer.message ?? '')
+	const detail = [code, message].filter((part) => part !== '').join(': ')
+	return new ZeropsApiError(`zerops: ${label} failed (${status})${detail === '' ? '' : ` — ${detail.slice(0, 300)}`}`, status, code)
+}

package/src/api/polling.ts

@@ -0,0 +1,59 @@
+import type { Sleeper } from '../collaborators'
+import { ZEROPS_PROCESS_FINISHED, ZEROPS_PROCESS_TERMINAL, type ZeropsApi, type ZeropsProcess } from './types'
+
+// ── waiting on a process ────────────────────────────────────────────────────────
+
+/**
+ * How often `waitForProcess` polls. The two process durations anyone has measured are 0.7 s
+ * (`stack.enableSubdomainAccess`) and 2.6 s (`stack.updateUserData`), so 5 s — the platform DEPLOY's
+ * interval — would spend most of its time asleep on a call that already finished.
+ */
+const PROCESS_POLL_INTERVAL_MS = 2_000
+
+/** ~5 minutes. The slow case is an import that creates managed services, not a build; a build is polled through `/app-version`. */
+const PROCESS_POLL_ATTEMPTS = 150
+
+/**
+ * Poll ONE process to completion.
+ *
+ * The same loop `deployPlatformService` (`installation/deploy.ts`) runs over `/app-version`, run over `/process`
+ * instead: read, decide ONLY on a status this build knows to be terminal, sleep, and give up on a deadline
+ * of our own rather than on a coincidence. Returns the finished process so a caller can read
+ * `actionName`/`appVersionId` off it.
+ *
+ * Anything outside `ZEROPS_PROCESS_TERMINAL` means "keep waiting", including a status this build has never
+ * seen — which is why an unpublished vocabulary (see that constant) can cost a timeout and never a false
+ * success. A non-`FINISHED` terminal status throws, naming the status and nothing else.
+ */
+export const waitForProcess = async (input: {
+	api: Pick<ZeropsApi, 'getProcess'>
+	processId: string
+	sleep: Sleeper
+	signal: AbortSignal
+	/** What to call this process in a failure or timeout message. Defaults to its id. */
+	label?: string
+	intervalMs?: number
+	attempts?: number
+}): Promise<ZeropsProcess> => {
+	const label = input.label ?? input.processId
+	const intervalMs = input.intervalMs ?? PROCESS_POLL_INTERVAL_MS
+	const attempts = input.attempts ?? PROCESS_POLL_ATTEMPTS
+	for (let attempt = 0;; attempt += 1) {
+		// A `Sleeper` resolves early on abort, so without this the loop would spin out its whole budget
+		// against a cancelled run.
+		if (input.signal.aborted) {
+			throw new Error(`zerops: waiting for ${label} was cancelled`)
+		}
+		const process = await input.api.getProcess({ processId: input.processId, signal: input.signal })
+		if (process.status !== undefined && ZEROPS_PROCESS_TERMINAL.has(process.status)) {
+			if (process.status !== ZEROPS_PROCESS_FINISHED) {
+				throw new Error(`zerops: ${label} finished as ${process.status}`)
+			}
+			return process
+		}
+		if (attempt >= attempts) {
+			throw new Error(`zerops: ${label} did not finish in time`)
+		}
+		await input.sleep(intervalMs, input.signal)
+	}
+}