@theholocron/holocron-plugin-vercel 5.0.0-alpha.278 → 5.0.0-alpha.279

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { AuthError, DeployFunctionConfig, DeployFunctionResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, DnsRecordRequest, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
 import { VercelClient, VercelClient as VercelClient$1, VercelClientOptions, createVercelClient } from "@theholocron/vercel-client";
+/** Resolves the Vercel token from `--token`, `HOLOCRON_VERCEL_TOKEN`, `VERCEL_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
 export declare const resolveToken: import("@theholocron/cli").TokenResolver;
 /** Every token this plugin takes, for `holocron doctor tokens`. */
 export declare const tokens: PluginToken[];
@@ -9,13 +10,17 @@ interface DeploymentOptions {
   /** Custom domain that `holocron repo setup` should attach to this project. */
   domain?: string;
 }
+/** The `deployment` capability for Vercel: projects, environment variables, deployments, functions and custom domains. */
 export declare class VercelDeployment implements Deployment {
   private readonly client;
+  /** The capability key, always `deployment`. */
   readonly key: "deployment";
+  /** The provider name, `vercel`. */
   readonly providerName = "vercel";
   readonly domain?: string;
   private readonly defaultFramework;
   constructor(client: () => VercelClient$1, opts?: DeploymentOptions);
+  /** Lists the projects the token can see, mapped to the provider-neutral shape. */
   listProjects(): Promise<DeploymentProject[]>;
   ensureProject(input: {
     name: string;
@@ -23,14 +28,18 @@ export declare class VercelDeployment implements Deployment {
     repo?: string;
     rootDirectory?: string;
   }): Promise<DeploymentProject>;
+  /** Updates a project's preview-deployment and Git-provider deployment settings and returns the updated project. */
   updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
+  /** Lists the names of the project's environment variables that apply to `target`. */
   listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
+  /** Creates or updates (upsert) an environment variable on the project for `target`. */
   setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
   triggerDeployment(input: {
     projectId: string;
     branch: string;
     target?: DeploymentTrigger;
   }): Promise<DeploymentRecord>;
+  /** Fetches a deployment by id; the record's branch is the deployment's Git commit ref, or `null` when it has none. */
   getDeployment(deploymentId: string): Promise<DeploymentRecord>;
   deployFunction(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
   /**
@@ -59,7 +68,9 @@ interface VerifyTokenOptions {
   baseUrl?: string;
   fetch?: typeof fetch;
 }
+/** Checks a Vercel token by fetching the current user; the success subject is `user @` followed by the email, username, name or id, the failure carries the error message. */
 export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
+/** Options for the Vercel plugin: token resolution, team, defaults for new projects and test overrides. */
 export interface VercelPluginOptions extends ResolveTokenInput {
   /** Vercel team id. Set when working with a team-owned project. */
   teamId?: string;
@@ -72,12 +83,18 @@ export interface VercelPluginOptions extends ResolveTokenInput {
   /** Override `fetch` for tests. */
   fetch?: typeof fetch;
 }
+/** What the plugin's capabilities share: the options and a lazily built client. */
 export interface PluginContext {
+  /** The options the plugin was created with. */
   options: VercelPluginOptions;
+  /** Builds the Vercel client on first call and reuses it; the token is resolved then, not at plugin load. */
   client: () => VercelClient;
 }
+/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
 export declare function createContext(options?: VercelPluginOptions): PluginContext;
+/** Builds the `deployment` capability from a plugin context, passing on `defaultFramework` and `domain` when set. */
 export declare function deployment(ctx: PluginContext): Deployment;
+/** Creates the Vercel plugin: a `connection` probe and the `deployment` capability. */
 export declare function createPlugin(options?: VercelPluginOptions): {
   name: string;
   probes: {

package/dist/index.mjs

@@ -2,6 +2,7 @@ import { AuthError, ProviderApiError, connectionProbe, createResolveToken } from
 import { createVercelClient } from "@theholocron/vercel-client";
 import { errorMessage } from "@theholocron/misc-utils";
 // src/auth.ts
+/** Resolves the Vercel token from `--token`, `HOLOCRON_VERCEL_TOKEN`, `VERCEL_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
 const resolveToken = createResolveToken({
 	envName: "HOLOCRON_VERCEL_TOKEN",
 	vendorEnvName: "VERCEL_TOKEN",
@@ -11,9 +12,12 @@ const resolveToken = createResolveToken({
 /** Every token this plugin takes, for `holocron doctor tokens`. */
 const tokens = [resolveToken.token];
 // src/capabilities/deployment.ts
+/** The `deployment` capability for Vercel: projects, environment variables, deployments, functions and custom domains. */
 var VercelDeployment = class {
 	client;
+	/** The capability key, always `deployment`. */
 	key = "deployment";
+	/** The provider name, `vercel`. */
 	providerName = "vercel";
 	domain;
 	defaultFramework;
@@ -22,6 +26,7 @@ var VercelDeployment = class {
 		this.defaultFramework = opts.defaultFramework ?? "nextjs";
 		this.domain = opts.domain;
 	}
+	/** Lists the projects the token can see, mapped to the provider-neutral shape. */
 	async listProjects() {
 		const { projects } = await this.client().projects.list();
 		return projects.map(mapProject);
@@ -36,16 +41,19 @@ var VercelDeployment = class {
 			rootDirectory: input.rootDirectory
 		}));
 	}
+	/** Updates a project's preview-deployment and Git-provider deployment settings and returns the updated project. */
 	async updateProjectSettings(projectId, settings) {
 		return mapProject(await this.client().projects.update(projectId, {
 			previewDeploymentsDisabled: settings.previewDeploymentsDisabled,
 			gitProviderOptions: settings.gitProviderCreateDeployments !== void 0 ? { createDeployments: settings.gitProviderCreateDeployments } : void 0
 		}));
 	}
+	/** Lists the names of the project's environment variables that apply to `target`. */
 	async listEnvVars(projectId, target) {
 		const { envs } = await this.client().env.list(projectId);
 		return envs.filter((e) => e.target.includes(target)).map((e) => e.key);
 	}
+	/** Creates or updates (upsert) an environment variable on the project for `target`. */
 	async setEnvVar(projectId, target, name, value) {
 		await this.client().env.set(projectId, target, name, value);
 	}
@@ -60,6 +68,7 @@ var VercelDeployment = class {
 			target: input.target
 		}), input.branch);
 	}
+	/** Fetches a deployment by id; the record's branch is the deployment's Git commit ref, or `null` when it has none. */
 	async getDeployment(deploymentId) {
 		const raw = await this.client().deployments.get(deploymentId);
 		return mapDeployment(raw, raw.meta?.githubCommitRef ?? null);
@@ -163,6 +172,7 @@ function normalizeState(s) {
 	}
 }
 // src/verify-token.ts
+/** Checks a Vercel token by fetching the current user; the success subject is `user @` followed by the email, username, name or id, the failure carries the error message. */
 async function verifyToken(token, opts = {}) {
 	const client = createVercelClient({
 		token,
@@ -183,6 +193,7 @@ async function verifyToken(token, opts = {}) {
 	}
 }
 // src/index.ts
+/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
 function createContext(options = {}) {
 	let client;
 	return {
@@ -195,12 +206,14 @@ function createContext(options = {}) {
 		})
 	};
 }
+/** Builds the `deployment` capability from a plugin context, passing on `defaultFramework` and `domain` when set. */
 function deployment(ctx) {
 	const opts = {};
 	if (ctx.options.defaultFramework !== void 0) opts.defaultFramework = ctx.options.defaultFramework;
 	if (ctx.options.domain !== void 0) opts.domain = ctx.options.domain;
 	return new VercelDeployment(ctx.client, opts);
 }
+/** Creates the Vercel plugin: a `connection` probe and the `deployment` capability. */
 function createPlugin(options = {}) {
 	const ctx = createContext(options);
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-vercel",
-  "version": "5.0.0-alpha.278",
+  "version": "5.0.0-alpha.279",
   "description": "Holocron plugin for Vercel. Implements the deployment capability against the Vercel REST API.",
   "keywords": [
     "deployment",
@@ -40,19 +40,19 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/cli": "5.0.0-alpha.278",
-    "@theholocron/http-client": "^1.58.0-alpha.3",
+    "@theholocron/cli": "5.0.0-alpha.279",
     "@theholocron/eslint-config": "^8.9.0-alpha.4",
-    "@theholocron/misc-utils": "^1.16.1-alpha.3",
+    "@theholocron/http-client": "^1.58.0-alpha.3",
     "@theholocron/tsconfig": "^8.9.0-alpha.4",
-    "@theholocron/vercel-client": "^1.58.0-alpha.3",
     "@theholocron/tsdown-config": "^8.9.0-alpha.4",
-    "@theholocron/vitest-config": "^8.9.0-alpha.4"
+    "@theholocron/vercel-client": "^1.58.0-alpha.3",
+    "@theholocron/vitest-config": "^8.9.0-alpha.4",
+    "@theholocron/misc-utils": "^1.16.1-alpha.3"
   },
   "peerDependencies": {
     "@theholocron/misc-utils": "^1.16.0",
     "@theholocron/vercel-client": "^1.43.1",
-    "@theholocron/cli": "5.0.0-alpha.278"
+    "@theholocron/cli": "5.0.0-alpha.279"
   },
   "peerDependenciesMeta": {
     "@theholocron/vercel-client": {}