@kubb/studio 5.2.6 → 5.2.8

package/dist/index.d.ts

@@ -11,6 +11,141 @@ import { Config, Hookable, KubbHooks } from "@kubb/core";
 export declare class InvalidAgentTokenError extends Error {
   constructor(studioUrl: string, options?: ErrorOptions);
 }
+/**
+ * Status values returned by Studio's jobs API.
+ */
+type StudioJobStatus = 'queued' | 'running' | 'success' | 'failed';
+/**
+ * Package view returned on a successful snapshot job from Studio.
+ */
+type StudioSnapshot = {
+  /**
+   * Immutable snapshot id.
+   */
+  id: string;
+  /**
+   * npm package name, or `null` when Studio stored none.
+   */
+  name: string | null;
+  /**
+   * npm package version, or `null` when Studio stored none.
+   */
+  version: string | null;
+  /**
+   * Subresource integrity hash for the tarball, or `null` when unavailable.
+   */
+  integrity: string | null;
+  /**
+   * Preferable download path, often the readable `/packages/{agentSlug}/{name}.tgz` form.
+   */
+  url: string;
+  /**
+   * Stable download path keyed by snapshot id.
+   */
+  snapshotIdUrl: string;
+  /**
+   * ISO timestamp after which Studio may delete the tarball.
+   */
+  expiresAt: string;
+};
+/**
+ * Job record from `POST /api/jobs` and `GET /api/jobs/{id}`.
+ */
+type StudioJob = {
+  /**
+   * Job id returned by Studio when the job was queued.
+   */
+  id: string;
+  /**
+   * Current status. Poll until `success` or `failed`.
+   */
+  status: StudioJobStatus;
+  /**
+   * Failure message when `status` is `failed`.
+   */
+  error?: string;
+  /**
+   * Package view when a snapshot job finished successfully.
+   */
+  snapshot?: StudioSnapshot;
+};
+/**
+ * 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 })
+ * ```
+ */
+export declare function createJob({ studioUrl, token, type, agentId, name, version, config }: {
+  studioUrl: string;
+  token: string;
+  type: 'generation' | 'snapshot';
+  agentId: string;
+  name?: string;
+  version?: string;
+  config?: Record<string, unknown>;
+}): Promise<StudioJob>;
+/**
+ * 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.
+ */
+export declare function waitForJob({ studioUrl, token, id, timeoutMs }: {
+  studioUrl: string;
+  token: string;
+  id: string;
+  /**
+   * How long to keep polling before throwing, in milliseconds.
+   *
+   * @default 60000
+   */
+  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 = {
@@ -219,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
 /**
@@ -377,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, 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

@@ -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
@@ -564,9 +571,82 @@ async function disconnect({ sessionId, token, studioUrl, slug }) {
 		console.warn(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 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 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 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.6";
+var version = "5.2.8";
 //#endregion
 //#region src/hooks.ts
 /**
@@ -2442,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, createJobId, defaultStudioUrl, pollForPairingToken, runConnection, setStorage, startPairing };
+export { InvalidAgentTokenError, PairingCanceledError, createAgent, createClient, createFileStorage, createJob, createJobId, defaultStudioUrl, machineTokenFrom, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
 
 //# sourceMappingURL=index.js.map