@kubb/studio 5.2.7 → 5.3.0

package/dist/index.d.ts

@@ -114,6 +114,38 @@ export declare function waitForJob({ studioUrl, token, id, timeoutMs }: {
    */
   timeoutMs?: number;
 }): Promise<StudioJob>;
+/**
+ * CI agent returned by {@link createAgent}. The token is issued only once, at creation or reuse.
+ */
+type StudioAgent = {
+  /**
+   * Agent id, passed to {@link createJob} as `agentId`.
+   */
+  id: string;
+  /**
+   * Human-readable slug, used to build the readable snapshot URL and the agent's Studio page.
+   */
+  slug: string;
+  /**
+   * Agent display name.
+   */
+  name: string;
+  /**
+   * Bearer token for the WebSocket agent session. Mask it before logging.
+   */
+  token: string;
+};
+/**
+ * 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.
+ */
+export declare function createAgent({ studioUrl, token, name, machineToken }: {
+  studioUrl: string;
+  token: string;
+  name: string;
+  machineToken: string;
+}): Promise<StudioAgent>;
 //#endregion
 //#region src/StudioSession.d.ts
 type StudioSessionOptions = {
@@ -322,6 +354,11 @@ export declare function setStorage(next: Storage): void;
  * survive a restart. Repeated pairings of one machine depend on that secret staying put.
  */
 export declare function createFileStorage(base: string): Storage;
+/**
+ * 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.
+ */
+export declare function machineTokenFrom(secret: string): string;
 //#endregion
 //#region src/runConnection.d.ts
 /**
@@ -480,5 +517,5 @@ type PollOptions = {
  */
 export declare function pollForPairingToken({ studioUrl, session, signal }: PollOptions): Promise<PairingResult>;
 //#endregion
-export { type Client, type ClientOptions, type ConnectionOptions, type StudioConnectedContext, type StudioJob, type StudioJobStatus, type StudioSnapshot, createJobId };
+export { type Client, type ClientOptions, type ConnectionOptions, type StudioAgent, type StudioConnectedContext, type StudioJob, type StudioJobStatus, type StudioSnapshot, createJobId };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,12 +2,12 @@ import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
 import { createJobId, isCommandMessage, isDisconnectMessage, isStudioPingMessage, isStudioReadyMessage } from "./protocol.js";
 import { createRequire } from "node:module";
 import { styleText } from "node:util";
+import process$1 from "node:process";
+import { spawn } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
 import path, { isAbsolute, relative, resolve } from "node:path";
-import { spawn } from "node:child_process";
 import { FetchError, ofetch } from "ofetch";
 import { hash, randomBytes } from "node:crypto";
-import process$1 from "node:process";
 import { createStorage } from "unstorage";
 import fsDriver from "unstorage/drivers/fs";
 import { Diagnostics, Hookable, createKubb, fsStorage, memoryStorage } from "@kubb/core";
@@ -406,14 +406,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 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 (process$1.env.KUBB_AGENT_SECRET) return hash("sha256", process$1.env.KUBB_AGENT_SECRET);
+	if (process$1.env.KUBB_AGENT_SECRET) return machineTokenFrom(process$1.env.KUBB_AGENT_SECRET);
 	fallbackSecretPromise ??= loadOrCreateFallbackSecret();
-	return hash("sha256", await fallbackSecretPromise);
+	return machineTokenFrom(await fallbackSecretPromise);
 }
 //#endregion
 //#region src/api.ts
@@ -612,9 +619,34 @@ async function waitForJob({ studioUrl, token, id, timeoutMs = 6e4 }) {
 		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 ofetch(`${studioUrl}/api/agents`, {
+			method: "POST",
+			headers: { "x-api-key": token },
+			body: {
+				name,
+				machineToken
+			}
+		});
+	} catch (error) {
+		if (error instanceof 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.7";
+var version = "5.3.0";
 //#endregion
 //#region src/hooks.ts
 /**
@@ -2490,6 +2522,6 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 	throw new Error("The pairing code expired, pair again");
 }
 //#endregion
-export { InvalidAgentTokenError, PairingCanceledError, createClient, createFileStorage, createJob, createJobId, defaultStudioUrl, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
+export { InvalidAgentTokenError, PairingCanceledError, createAgent, createClient, createFileStorage, createJob, createJobId, defaultStudioUrl, machineTokenFrom, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
 
 //# sourceMappingURL=index.js.map