@theholocron/vercel-client 1.58.0-alpha.3 → 1.58.0-alpha.4

package/dist/index.d.mts

@@ -1,9 +1,14 @@
 import "@theholocron/http-client";
 import { ErrorSink, Logger } from "@theholocron/observability/core";
+/** Options for `createVercelClient()` and `createVercelRestClient()`. */
 interface VercelClientOptions {
   /** Vercel API token. */
   token: string;
-  /** Team ID — appended as `?teamId=` on every request. Omit for personal accounts. */
+  /**
+   * Team ID — appended as `?teamId=` on every request. Omit for personal accounts.
+   * Required for team-owned resources (projects, deployments, env vars); without it, requests
+   * target personal account resources only. Find it in Vercel dashboard → Team Settings → General.
+   */
   teamId?: string;
   /** Override base URL for testing. Defaults to https://api.vercel.com. */
   baseUrl?: string;
@@ -14,21 +19,35 @@ interface VercelClientOptions {
   /** Reports transport failures and unexpected 5xx. Defaults to a no-op. */
   errors?: ErrorSink;
 }
+/** The lifecycle state of a Vercel deployment; `READY` means it is serving traffic. */
 type VercelDeploymentState = "INITIALIZING" | "QUEUED" | "BUILDING" | "READY" | "ERROR" | "CANCELED";
+/** The environment a deployment is built for. */
 type VercelDeploymentTarget = "production" | "staging";
+/** A Vercel deployment as the API returns it. */
 interface VercelDeployment {
+  /** The deployment id. */
   id: string;
+  /** The deployment's generated hostname, without a scheme. */
   url: string;
+  /** Where the deployment is in its lifecycle. */
   readyState: VercelDeploymentState;
+  /** The environment the deployment was built for; absent or `null` for a preview. */
   target?: VercelDeploymentTarget | null;
+  /** Git metadata Vercel attaches to the deployment. */
   meta?: {
+    /** The branch or ref the deployment was built from. */
     githubCommitRef?: string;
   };
 }
+/** Input for `deployments.trigger()`: deploy a branch of a linked GitHub repository. */
 interface VercelTriggerDeploymentInput {
+  /** The Vercel project to deploy. */
   projectName: string;
+  /** The Git branch (ref) to deploy. */
   branch: string;
+  /** The numeric GitHub repository id. */
   repoId: number;
+  /** The environment to deploy to; omitted, Vercel decides. */
   target?: VercelDeploymentTarget;
 }
 /** One file for `deployments.create()` — content is sent inline, base64-encoded. */
@@ -38,8 +57,11 @@ interface VercelDeployFile {
   /** File content, plain text — base64-encoded by `create()` before the request goes out. */
   content: string;
 }
+/** Input for `deployments.create()`: deploy source files without a Git repository. */
 interface VercelCreateDeploymentInput {
+  /** The Vercel project to deploy to. */
   projectName: string;
+  /** The files that make up the deployment. */
   files: VercelDeployFile[];
   /**
    * `projectSettings.framework`. `null` (the default) deploys with no
@@ -48,14 +70,21 @@ interface VercelCreateDeploymentInput {
    * later deployments inherit it unless overridden here again.
    */
   framework?: string | null;
+  /** The environment to deploy to; omitted, Vercel decides. */
   target?: VercelDeploymentTarget;
 }
+/** A domain attached to a Vercel project. */
 interface VercelDomain {
+  /** The domain name. */
   name: string;
+  /** The domain's apex (registrable) name. */
   apexName: string;
+  /** Whether Vercel has verified ownership of the domain. */
   verified: boolean;
 }
+/** The response of `domains.list()`. */
 interface VercelDomainsResponse {
+  /** The domains attached to the project. */
   domains: VercelDomain[];
 }
 /**
@@ -67,20 +96,31 @@ interface VercelDomainsResponse {
  * host — always read it from this response, never hardcode it.
  */
 interface VercelDomainVerification {
+  /** The record type to create: `CNAME` or `TXT`. */
   type: string;
+  /** The name the record goes on. */
   domain: string;
+  /** The record content. */
   value: string;
+  /** Why Vercel asks for this record. */
   reason: string;
 }
+/** The response of `domains.add()`. */
 interface VercelAddDomainResult {
+  /** The domain name. */
   name: string;
+  /** The domain's apex (registrable) name. */
   apexName: string;
+  /** Whether ownership is already verified; when `false`, `verification` lists what to do. */
   verified: boolean;
+  /** The challenges to complete to verify ownership; absent when already verified. */
   verification?: VercelDomainVerification[];
 }
 /** One ranked CNAME/IPv4 recommendation — `rank: 1` is the preferred value. */
 interface VercelDomainConfigRecommendation<T> {
+  /** The preference order; `1` is the preferred value. */
   rank: number;
+  /** The recommended value. */
   value: T;
 }
 /**
@@ -102,52 +142,89 @@ interface VercelDomainConfig {
   /** Recommended A-record IPv4(s) for an apex domain, ranked. */
   recommendedIPv4: VercelDomainConfigRecommendation<string[]>[];
 }
+/** An environment a variable applies to. */
 type VercelEnvTarget = "production" | "preview" | "development";
+/** An environment variable on a project, as the API lists it. */
 interface VercelEnvVar {
+  /** The variable's id. */
   id: string;
+  /** The variable's name. */
   key: string;
+  /** The environments the variable applies to. */
   target: VercelEnvTarget[];
 }
+/** The response of `env.list()`. */
 interface VercelEnvVarsResponse {
+  /** The project's environment variables. */
   envs: VercelEnvVar[];
 }
+/** The Git repository a project is linked to. */
 interface VercelProjectLink {
+  /** The Git provider, e.g. `github`. */
   type?: string;
+  /** The provider's numeric repository id. */
   repoId?: number;
+  /** The repository name. */
   repo?: string;
+  /** The organization or user that owns the repository. */
   org?: string;
 }
+/** A Vercel project as the API returns it. */
 interface VercelProject {
+  /** The project id. */
   id: string;
+  /** The project name. */
   name: string;
+  /** The framework preset, or `null` for none. */
   framework?: string | null;
+  /** The directory in the repository the project builds from, or `null` for the root. */
   rootDirectory?: string | null;
+  /** The linked Git repository, or `null` when there is none. */
   link?: VercelProjectLink | null;
 }
+/** The response of `projects.list()`. */
 interface VercelProjectsResponse {
+  /** The projects the token can see. */
   projects: VercelProject[];
 }
+/** Input for `projects.create()`. */
 interface VercelCreateProjectInput {
+  /** The project name. */
   name: string;
+  /** The framework preset; omitted, none is sent. */
   framework?: string;
+  /** A GitHub repository (`owner/name`) to link the project to. */
   repo?: string;
+  /** The directory in the repository the project builds from. */
   rootDirectory?: string;
 }
+/** Input for `projects.update()`; only the fields given are sent. */
 interface VercelUpdateProjectInput {
+  /** Turn preview deployments off (`true`) or on (`false`). */
   previewDeploymentsDisabled?: boolean;
+  /** Git integration settings for the project. */
   gitProviderOptions?: {
+    /** Whether (or when) Vercel creates deployments for pushes to the linked repository. */
     createDeployments?: boolean | string;
   };
 }
+/** The authenticated Vercel user. */
 interface VercelUser {
+  /** The user id. */
   id?: string;
+  /** The user's username. */
   username?: string;
+  /** The user's email address. */
   email?: string;
+  /** The user's display name. */
   name?: string;
 }
+/** The response of `user.get()`. */
 interface VercelUserResponse {
+  /** The authenticated user. */
   user?: VercelUser;
 }
+/** Create a Vercel client with `deployments`, `domains`, `env`, `projects` and `user` groups, all sharing one REST client built from `opts`. */
 export declare function createVercelClient(opts: VercelClientOptions): {
   deployments: {
     trigger: (input: VercelTriggerDeploymentInput) => Promise<VercelDeployment>;
@@ -173,5 +250,6 @@ export declare function createVercelClient(opts: VercelClientOptions): {
     get: () => Promise<VercelUserResponse>;
   };
 };
+/** The client `createVercelClient()` returns. */
 export type VercelClient = ReturnType<typeof createVercelClient>;
 export type { VercelAddDomainResult, VercelClientOptions, VercelCreateDeploymentInput, VercelCreateProjectInput, VercelDeployFile, VercelDeployment, VercelDeploymentState, VercelDeploymentTarget, VercelDomain, VercelDomainConfig, VercelDomainConfigRecommendation, VercelDomainVerification, VercelDomainsResponse, VercelEnvTarget, VercelEnvVar, VercelEnvVarsResponse, VercelProject, VercelProjectLink, VercelProjectsResponse, VercelTriggerDeploymentInput, VercelUpdateProjectInput, VercelUser, VercelUserResponse };

package/dist/index.mjs

@@ -118,6 +118,7 @@ function createVercelRestClient(opts) {
 	});
 }
 // src/index.ts
+/** Create a Vercel client with `deployments`, `domains`, `env`, `projects` and `user` groups, all sharing one REST client built from `opts`. */
 function createVercelClient(opts) {
 	const rest = createVercelRestClient(opts);
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/vercel-client",
-  "version": "1.58.0-alpha.3",
+  "version": "1.58.0-alpha.4",
   "description": "A TypeScript client for the Vercel API",
   "keywords": [
     "vercel",
@@ -32,7 +32,7 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/http-client": "^1.58.0-alpha.3",
+    "@theholocron/http-client": "^1.58.0-alpha.4",
     "@theholocron/observability": "^0.6.1-alpha.1"
   },
   "devDependencies": {
@@ -45,10 +45,10 @@
     "tsdown": "^0.23.3",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/eslint-config": "^8.9.0-alpha.3",
-    "@theholocron/vitest-config": "^8.9.0-alpha.3",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
-    "@theholocron/tsconfig": "^8.9.0-alpha.3"
+    "@theholocron/eslint-config": "^8.9.0-alpha.5",
+    "@theholocron/tsconfig": "^8.9.0-alpha.5",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.5",
+    "@theholocron/vitest-config": "^8.9.0-alpha.5"
   },
   "engines": {
     "node": ">=22.0.0"