@theholocron/vercel-client 1.32.0 → 1.33.0

package/dist/index.d.mts

@@ -0,0 +1,191 @@
+import "@theholocron/http-client";
+import { ErrorSink, Logger } from "@theholocron/observability/core";
+//#region ../../../../../src/utils.d.ts
+interface VercelClientOptions {
+  /** Vercel API token. */
+  token: string;
+  /** Team ID — appended as `?teamId=` on every request. Omit for personal accounts. */
+  teamId?: string;
+  /** Override base URL for testing. Defaults to https://api.vercel.com. */
+  baseUrl?: string;
+  /** Override fetch for testing. Defaults to globalThis.fetch. */
+  fetch?: typeof fetch;
+  /** Structured logger for request/response diagnostics. Defaults to a no-op. */
+  logger?: Logger;
+  /** Reports transport failures and unexpected 5xx. Defaults to a no-op. */
+  errors?: ErrorSink;
+}
+//#endregion
+//#region ../../../../../src/deployments/deployments.d.ts
+type VercelDeploymentState = "INITIALIZING" | "QUEUED" | "BUILDING" | "READY" | "ERROR" | "CANCELED";
+type VercelDeploymentTarget = "production" | "staging";
+interface VercelDeployment {
+  id: string;
+  url: string;
+  readyState: VercelDeploymentState;
+  target?: VercelDeploymentTarget | null;
+  meta?: {
+    githubCommitRef?: string;
+  };
+}
+interface VercelTriggerDeploymentInput {
+  projectName: string;
+  branch: string;
+  repoId: number;
+  target?: VercelDeploymentTarget;
+}
+/** One file for `deployments.create()` — content is sent inline, base64-encoded. */
+interface VercelDeployFile {
+  /** Path relative to the project root, e.g. "api/webhook.js". */
+  file: string;
+  /** File content, plain text — base64-encoded by `create()` before the request goes out. */
+  content: string;
+}
+interface VercelCreateDeploymentInput {
+  projectName: string;
+  files: VercelDeployFile[];
+  /**
+   * `projectSettings.framework`. `null` (the default) deploys with no
+   * framework preset — the right choice for a bare serverless function,
+   * not an app. Vercel requires this on a project's first deployment;
+   * later deployments inherit it unless overridden here again.
+   */
+  framework?: string | null;
+  target?: VercelDeploymentTarget;
+}
+//#endregion
+//#region ../../../../../src/domains/domains.d.ts
+interface VercelDomain {
+  name: string;
+  apexName: string;
+  verified: boolean;
+}
+interface VercelDomainsResponse {
+  domains: VercelDomain[];
+}
+/**
+ * One DNS verification challenge — complete any one of these (usually
+ * just one is returned) to prove ownership. `type: "CNAME"` means
+ * `domain` needs a CNAME record pointing at `value`; `type: "TXT"`
+ * means a TXT record on `domain` with content `value`. The CNAME
+ * target is generated per-project by Vercel, not a fixed well-known
+ * host — always read it from this response, never hardcode it.
+ */
+interface VercelDomainVerification {
+  type: string;
+  domain: string;
+  value: string;
+  reason: string;
+}
+interface VercelAddDomainResult {
+  name: string;
+  apexName: string;
+  verified: boolean;
+  verification?: VercelDomainVerification[];
+}
+/** One ranked CNAME/IPv4 recommendation — `rank: 1` is the preferred value. */
+interface VercelDomainConfigRecommendation<T> {
+  rank: number;
+  value: T;
+}
+/**
+ * DNS *routing* status for a domain — distinct from ownership (`verified`
+ * on `VercelDomain`/`VercelAddDomainResult`). A domain can be verified
+ * (Vercel trusts you own it) with no record actually pointing traffic at
+ * Vercel yet, e.g. re-adding a domain whose apex is already verified on
+ * this team short-circuits to `verified: true` with no `verification`
+ * challenge (`domains.add` returns 409, not a fresh challenge) — this is
+ * the only source for that domain's CNAME target in that case.
+ */
+interface VercelDomainConfig {
+  /** How Vercel currently sees the domain resolving. `null` = not resolving to Vercel at all. */
+  configuredBy: "A" | "CNAME" | "http" | "dns-01" | null;
+  /** `false` once DNS is correctly configured and a TLS cert can be issued. */
+  misconfigured: boolean;
+  /** Recommended CNAME target(s) for a subdomain, ranked; `[0]` is preferred. Per-project, never a fixed host. */
+  recommendedCNAME: VercelDomainConfigRecommendation<string>[];
+  /** Recommended A-record IPv4(s) for an apex domain, ranked. */
+  recommendedIPv4: VercelDomainConfigRecommendation<string[]>[];
+}
+//#endregion
+//#region ../../../../../src/env/env.d.ts
+type VercelEnvTarget = "production" | "preview" | "development";
+interface VercelEnvVar {
+  id: string;
+  key: string;
+  target: VercelEnvTarget[];
+}
+interface VercelEnvVarsResponse {
+  envs: VercelEnvVar[];
+}
+//#endregion
+//#region ../../../../../src/projects/projects.d.ts
+interface VercelProjectLink {
+  type?: string;
+  repoId?: number;
+  repo?: string;
+  org?: string;
+}
+interface VercelProject {
+  id: string;
+  name: string;
+  framework?: string | null;
+  rootDirectory?: string | null;
+  link?: VercelProjectLink | null;
+}
+interface VercelProjectsResponse {
+  projects: VercelProject[];
+}
+interface VercelCreateProjectInput {
+  name: string;
+  framework?: string;
+  repo?: string;
+  rootDirectory?: string;
+}
+interface VercelUpdateProjectInput {
+  previewDeploymentsDisabled?: boolean;
+  gitProviderOptions?: {
+    createDeployments?: boolean | string;
+  };
+}
+//#endregion
+//#region ../../../../../src/user/user.d.ts
+interface VercelUser {
+  id?: string;
+  username?: string;
+  email?: string;
+  name?: string;
+}
+interface VercelUserResponse {
+  user?: VercelUser;
+}
+//#endregion
+//#region ../../../../../src/index.d.ts
+declare function createVercelClient(opts: VercelClientOptions): {
+  deployments: {
+    trigger: (input: VercelTriggerDeploymentInput) => Promise<VercelDeployment>;
+    create: (input: VercelCreateDeploymentInput) => Promise<VercelDeployment>;
+    get: (deploymentId: string) => Promise<VercelDeployment>;
+  };
+  domains: {
+    list: (projectId: string) => Promise<VercelDomainsResponse>;
+    add: (projectId: string, name: string) => Promise<VercelAddDomainResult>;
+    config: (domain: string, projectIdOrName?: string) => Promise<VercelDomainConfig>;
+  };
+  env: {
+    list: (projectId: string) => Promise<VercelEnvVarsResponse>;
+    set: (projectId: string, target: VercelEnvTarget, name: string, value: string) => Promise<VercelEnvVar>;
+  };
+  projects: {
+    list: () => Promise<VercelProjectsResponse>;
+    get: (nameOrId: string) => Promise<VercelProject>;
+    create: (input: VercelCreateProjectInput) => Promise<VercelProject>;
+    update: (projectId: string, input: VercelUpdateProjectInput) => Promise<VercelProject>;
+  };
+  user: {
+    get: () => Promise<VercelUserResponse>;
+  };
+};
+type VercelClient = ReturnType<typeof createVercelClient>;
+//#endregion
+export { type VercelAddDomainResult, VercelClient, type VercelClientOptions, type VercelCreateDeploymentInput, type VercelCreateProjectInput, type VercelDeployFile, type VercelDeployment, type VercelDeploymentState, type VercelDeploymentTarget, type VercelDomain, type VercelDomainConfig, type VercelDomainConfigRecommendation, type VercelDomainVerification, type VercelDomainsResponse, type VercelEnvTarget, type VercelEnvVar, type VercelEnvVarsResponse, type VercelProject, type VercelProjectLink, type VercelProjectsResponse, type VercelTriggerDeploymentInput, type VercelUpdateProjectInput, type VercelUser, type VercelUserResponse, createVercelClient };

package/dist/index.mjs

@@ -0,0 +1,138 @@
+import { createRestClient } from "@theholocron/http-client";
+//#region ../../../../../src/deployments/deployments.ts
+function deployments(rest) {
+	return {
+		trigger: (input) => rest.request("/v13/deployments", {
+			method: "POST",
+			body: {
+				name: input.projectName,
+				gitSource: {
+					type: "github",
+					ref: input.branch,
+					repoId: input.repoId
+				},
+				...input.target ? { target: input.target } : {}
+			}
+		}),
+		/**
+		* Create a deployment directly from source files — no `gitSource`,
+		* no linked repo required. The non-git counterpart to `trigger()`,
+		* for a consumer with no repo to deploy from (a webhook receiver
+		* bundled and shipped as an npm package, for instance).
+		*/
+		create: (input) => rest.request("/v13/deployments", {
+			method: "POST",
+			body: {
+				name: input.projectName,
+				files: input.files.map((f) => ({
+					file: f.file,
+					data: Buffer.from(f.content, "utf8").toString("base64"),
+					encoding: "base64"
+				})),
+				projectSettings: { framework: input.framework ?? null },
+				...input.target ? { target: input.target } : {}
+			}
+		}),
+		get: (deploymentId) => rest.request(`/v13/deployments/${encodeURIComponent(deploymentId)}`)
+	};
+}
+//#endregion
+//#region ../../../../../src/domains/domains.ts
+function domains(rest) {
+	return {
+		list: (projectId) => rest.request(`/v9/projects/${encodeURIComponent(projectId)}/domains`),
+		add: (projectId, name) => rest.request(`/v10/projects/${encodeURIComponent(projectId)}/domains`, {
+			method: "POST",
+			body: { name }
+		}),
+		/**
+		* DNS routing status for `domain` — works regardless of whether the
+		* domain is already attached/verified on a project. `projectIdOrName`
+		* is optional per Vercel's docs ("use this when the domain is not yet
+		* associated with a project") but passed through when known to scope
+		* the recommendation to that project.
+		*/
+		config: (domain, projectIdOrName) => rest.request(`/v6/domains/${encodeURIComponent(domain)}/config`, { query: projectIdOrName ? { projectIdOrName } : void 0 })
+	};
+}
+//#endregion
+//#region ../../../../../src/env/env.ts
+function env(rest) {
+	return {
+		list: (projectId) => rest.request(`/v9/projects/${encodeURIComponent(projectId)}/env`),
+		set: (projectId, target, name, value) => rest.request(`/v10/projects/${encodeURIComponent(projectId)}/env`, {
+			method: "POST",
+			query: { upsert: "true" },
+			body: {
+				key: name,
+				value,
+				target: [target],
+				type: "encrypted"
+			}
+		})
+	};
+}
+//#endregion
+//#region ../../../../../src/projects/projects.ts
+function projects(rest) {
+	return {
+		list: () => rest.request("/v10/projects"),
+		get: (nameOrId) => rest.request(`/v10/projects/${encodeURIComponent(nameOrId)}`),
+		create: (input) => {
+			const body = {
+				name: input.name,
+				...input.framework !== void 0 ? { framework: input.framework } : {},
+				...input.repo ? { gitRepository: {
+					type: "github",
+					repo: input.repo
+				} } : {},
+				...input.rootDirectory ? { rootDirectory: input.rootDirectory } : {}
+			};
+			return rest.request("/v11/projects", {
+				method: "POST",
+				body
+			});
+		},
+		update: (projectId, input) => {
+			const body = {};
+			if (input.previewDeploymentsDisabled !== void 0) body.previewDeploymentsDisabled = input.previewDeploymentsDisabled;
+			if (input.gitProviderOptions !== void 0) body.gitProviderOptions = input.gitProviderOptions;
+			return rest.request(`/v9/projects/${encodeURIComponent(projectId)}`, {
+				method: "PATCH",
+				body
+			});
+		}
+	};
+}
+//#endregion
+//#region ../../../../../src/user/user.ts
+function user(rest) {
+	return { get: () => rest.request("/v2/user") };
+}
+//#endregion
+//#region ../../../../../src/utils.ts
+function createVercelRestClient(opts) {
+	return createRestClient({
+		baseUrl: opts.baseUrl ?? "https://api.vercel.com",
+		token: opts.token,
+		defaultQuery: opts.teamId ? { teamId: opts.teamId } : void 0,
+		vendor: "Vercel",
+		fetch: opts.fetch,
+		logger: opts.logger,
+		errors: opts.errors
+	});
+}
+//#endregion
+//#region ../../../../../src/index.ts
+function createVercelClient(opts) {
+	const rest = createVercelRestClient(opts);
+	return {
+		deployments: deployments(rest),
+		domains: domains(rest),
+		env: env(rest),
+		projects: projects(rest),
+		user: user(rest)
+	};
+}
+//#endregion
+export { createVercelClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/vercel-client",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "A TypeScript client for the Vercel API",
   "keywords": [
     "vercel",
@@ -33,13 +33,13 @@
   ],
   "dependencies": {
     "@theholocron/observability": "^0.3.0",
-    "@theholocron/http-client": "^1.32.0"
+    "@theholocron/http-client": "^1.33.0"
   },
   "devDependencies": {
     "@theholocron/cli": "5.0.0-alpha.79",
     "@theholocron/eslint-config": "^8.4.3",
     "@theholocron/tsconfig": "^8.2.0",
-    "@theholocron/tsdown-config": "^8.5.2",
+    "@theholocron/tsdown-config": "^8.6.1",
     "@theholocron/vitest-config": "^8.2.0",
     "@types/node": "^26.4.1",
     "@vitest/coverage-v8": "^5.0.0",