@kubb/studio 5.2.6 → 5.2.8

package/README.md

@@ -96,6 +96,38 @@ nothing can read it back.
 member can approve. A host that pairs a shared or tier-limited agent passes `clientId: 'kubb-agent'`
 and an `agentKind`, whose codes only an admin can approve.
 
+## Asynchronous jobs
+
+CI and automation queue work with `createJob` and poll with `waitForJob`. Both send the
+organization CI API key as `x-api-key`. They do not open a WebSocket.
+
+| Step   | Call                 | What it does                                                          |
+| ------ | -------------------- | --------------------------------------------------------------------- |
+| Queue  | `POST /api/jobs`     | Accepts a `generation` or `snapshot` job and returns `202` with an id |
+| Status | `GET /api/jobs/{id}` | Returns the job until `success` or `failed`                           |
+
+```typescript
+import { createJob, waitForJob } from '@kubb/studio'
+
+const job = await createJob({
+  studioUrl: 'https://kubb.studio',
+  token: process.env.KUBB_TOKEN!,
+  type: 'snapshot',
+  agentId: agent.id,
+  name: '@scope/package',
+  version: '1.0.0',
+})
+
+const finished = await waitForJob({
+  studioUrl: 'https://kubb.studio',
+  token: process.env.KUBB_TOKEN!,
+  id: job.id,
+})
+
+if (finished.status === 'failed') throw new Error(finished.error)
+const snapshot = finished.snapshot
+```
+
 ## Protocol
 
 `@kubb/studio/protocol` holds the WebSocket message types shared by both ends, so the agent and

package/dist/index.cjs

@@ -411,14 +411,21 @@ async function loadOrCreateFallbackSecret() {
 	return secret;
 }
 /**
+* Hashes a stable secret into the machine token Studio expects, so a host can derive one from its
+* own identity without duplicating `getMachineToken`'s SHA-256 step.
+*/
+function machineTokenFrom(secret) {
+	return (0, node_crypto.hash)("sha256", secret);
+}
+/**
 * Returns the machine token derived from the `KUBB_AGENT_SECRET` environment variable.
 * Falls back to a generated secret persisted in the runtime storage if the env var is not set.
 * The token is hashed with SHA-256.
 */
 async function getMachineToken() {
-	if (node_process.default.env.KUBB_AGENT_SECRET) return (0, node_crypto.hash)("sha256", node_process.default.env.KUBB_AGENT_SECRET);
+	if (node_process.default.env.KUBB_AGENT_SECRET) return machineTokenFrom(node_process.default.env.KUBB_AGENT_SECRET);
 	fallbackSecretPromise ??= loadOrCreateFallbackSecret();
-	return (0, node_crypto.hash)("sha256", await fallbackSecretPromise);
+	return machineTokenFrom(await fallbackSecretPromise);
 }
 //#endregion
 //#region src/api.ts
@@ -569,9 +576,82 @@ async function disconnect({ sessionId, token, studioUrl, slug }) {
 		console.warn((0, node_util.styleText)("yellow", `[${tag}] Failed to notify Studio of disconnection: ${getErrorMessage(error)}`));
 	}
 }
+/**
+* Queues a generation or snapshot job on Studio (`POST /api/jobs`).
+*
+* Returns as soon as Studio accepts the job (`202`). Poll with {@link waitForJob} until it finishes.
+* Authenticates with the organization CI API key via `x-api-key`.
+*
+* @example Snapshot job
+* ```ts
+* const job = await createJob({
+*   studioUrl: 'https://kubb.studio',
+*   token: process.env.KUBB_TOKEN!,
+*   type: 'snapshot',
+*   agentId: agent.id,
+*   name: '@kubb/demo',
+*   version: '1.0.0',
+* })
+* const finished = await waitForJob({ studioUrl, token, id: job.id })
+* ```
+*/
+async function createJob({ studioUrl, token, type, agentId, name, version, config }) {
+	const { job } = await (0, ofetch.ofetch)(`${studioUrl}/api/jobs`, {
+		method: "POST",
+		headers: { "x-api-key": token },
+		body: {
+			type,
+			agentId,
+			name,
+			version,
+			config
+		}
+	});
+	return job;
+}
+/**
+* Polls `GET /api/jobs/{id}` until the job reaches `success` or `failed`.
+*
+* A `failed` job resolves normally. Check `job.status` and `job.error`. Throws only when the
+* deadline passes before Studio finishes.
+*/
+async function waitForJob({ studioUrl, token, id, timeoutMs = 6e4 }) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		const { job } = await (0, ofetch.ofetch)(`${studioUrl}/api/jobs/${id}`, { headers: { "x-api-key": token } });
+		if (job.status === "success" || job.status === "failed") return job;
+		if (Date.now() >= deadline) throw new Error("Timed out waiting for the Studio job");
+		await new Promise((resolve) => setTimeout(resolve, 1e3));
+	}
+}
+/**
+* Creates or reuses a CI agent (`POST /api/agents`), keyed by `(organization, machineToken)`.
+* Authenticates via `x-api-key`. Reusing the same `machineToken` reuses the same agent instead of
+* consuming a new one from the organization's agent limit.
+*/
+async function createAgent({ studioUrl, token, name, machineToken }) {
+	try {
+		return await (0, ofetch.ofetch)(`${studioUrl}/api/agents`, {
+			method: "POST",
+			headers: { "x-api-key": token },
+			body: {
+				name,
+				machineToken
+			}
+		});
+	} catch (error) {
+		if (error instanceof ofetch.FetchError) {
+			const upgradeUrl = error.data?.data?.upgradeUrl;
+			const detail = responseMessage(error.data) ?? getErrorMessage(error);
+			const hint = upgradeUrl ? ` Agent limit reached; upgrade at ${upgradeUrl}.` : "";
+			throw new Error(`Failed to create a Kubb Studio agent: ${detail}${hint}`, { cause: error });
+		}
+		throw error;
+	}
+}
 //#endregion
 //#region package.json
-var version = "5.2.6";
+var version = "5.2.8";
 //#endregion
 //#region src/hooks.ts
 /**
@@ -2449,13 +2529,17 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 //#endregion
 exports.InvalidAgentTokenError = InvalidAgentTokenError;
 exports.PairingCanceledError = PairingCanceledError;
+exports.createAgent = createAgent;
 exports.createClient = createClient;
 exports.createFileStorage = createFileStorage;
+exports.createJob = createJob;
 exports.createJobId = require_protocol.createJobId;
 exports.defaultStudioUrl = defaultStudioUrl;
+exports.machineTokenFrom = machineTokenFrom;
 exports.pollForPairingToken = pollForPairingToken;
 exports.runConnection = runConnection;
 exports.setStorage = setStorage;
 exports.startPairing = startPairing;
+exports.waitForJob = waitForJob;
 
 //# sourceMappingURL=index.cjs.map