chore: use zod v3 syntax by himself65 · Pull Request #4851 · better-auth/better-auth

himself65 · 2025-09-23T20:22:11Z

Document: https://zod.dev/metadata?id=describe
Fixes: #4837

Summary by cubic

Migrated all endpoint and plugin schemas to Zod v3 syntax to standardize descriptions and improve consistency. No runtime behavior changes; API inputs and outputs remain the same.

Refactors
- Replaced z.meta(...) with z.describe(...) across auth routes and plugins (sessions, sign-in, account, org, API keys, 2FA, passkey, phone, magic link, SSO/OIDC, etc.).
- Standardized schema patterns (e.g., z.coerce for ids/booleans, defaults and optionals) while preserving existing validations and OpenAPI descriptions.
Migration
- If you have custom schemas using z.meta, update them to .describe.
- No action needed for consumers unless extending schemas; endpoint contracts are unchanged.

vercel · 2025-09-23T20:22:25Z

@himself65 is attempting to deploy a commit to the better-auth Team on Vercel.

A member of the Team first needs to authorize it.

pkg-pr-new · 2025-09-23T20:23:55Z

Open in StackBlitz

better-auth

npm i https://pkg.pr.new/better-auth/better-auth@4851

@better-auth/cli

npm i https://pkg.pr.new/better-auth/better-auth/@better-auth/cli@4851

@better-auth/expo

npm i https://pkg.pr.new/better-auth/better-auth/@better-auth/expo@4851

@better-auth/sso

npm i https://pkg.pr.new/better-auth/better-auth/@better-auth/sso@4851

@better-auth/stripe

npm i https://pkg.pr.new/better-auth/better-auth/@better-auth/stripe@4851

commit: 24fc68c

cubic-dev-ai

13 issues found across 37 files

Prompt for AI agents (all 13 issues)


Understand the root cause of the following 13 issues and fix them.


<file name="packages/better-auth/src/plugins/organization/routes/crud-invites.ts">

<violation number="1" location="packages/better-auth/src/plugins/organization/routes/crud-invites.ts:847">
Rule violated: **Enforce Consistent Naming Conventions**

Use a descriptive parameter name for consistency and clarity; replace generic id with invitationId to align with other endpoints and naming conventions.</violation>
</file>

<file name="packages/better-auth/src/plugins/organization/routes/crud-access-control.ts">

<violation number="1" location="packages/better-auth/src/plugins/organization/routes/crud-access-control.ts:75">
Description text truncated mid-sentence; restore full message for clarity.</violation>

<violation number="2" location="packages/better-auth/src/plugins/organization/routes/crud-access-control.ts:606">
Description text truncated mid-sentence; restore full message for clarity.</violation>

<violation number="3" location="packages/better-auth/src/plugins/organization/routes/crud-access-control.ts:764">
Description text truncated mid-sentence; restore full message for clarity.</violation>
</file>

<file name="packages/better-auth/src/plugins/generic-oauth/index.ts">

<violation number="1" location="packages/better-auth/src/plugins/generic-oauth/index.ts:358">
Incomplete description string: the example is missing after &quot;Eg:&quot;. Provide a concrete example or remove the placeholder.</violation>
</file>

<file name="packages/better-auth/src/plugins/organization/routes/crud-members.ts">

<violation number="1" location="packages/better-auth/src/plugins/organization/routes/crud-members.ts:410">
Incomplete description string; trailing &#39;Eg: [&#39; indicates a truncated example. Clean up or complete the text.</violation>
</file>

<file name="packages/better-auth/src/plugins/organization/routes/crud-team.ts">

<violation number="1" location="packages/better-auth/src/plugins/organization/routes/crud-team.ts:563">
Typo in example: &quot;organziation-id&quot; should be &quot;organization-id&quot;.</violation>
</file>

<file name="packages/better-auth/src/plugins/one-time-token/index.ts">

<violation number="1" location="packages/better-auth/src/plugins/one-time-token/index.ts:132">
Zod describe string is incomplete (ends with &quot;Eg:&quot;), reducing clarity for docs; include an example or remove the &quot;Eg:&quot;.</violation>
</file>

<file name="packages/sso/src/index.ts">

<violation number="1" location="packages/sso/src/index.ts:342">
Truncated .describe() texts in oidcConfig.mapping (dangling &#39;(&#39; and missing defaults) degrade API docs clarity.</violation>
</file>

<file name="packages/better-auth/src/plugins/device-authorization/index.ts">

<violation number="1" location="packages/better-auth/src/plugins/device-authorization/index.ts:625">
Error enum for /device missing &quot;expired_token&quot;, which this endpoint returns when the user code is expired.</violation>
</file>

<file name="packages/better-auth/src/plugins/two-factor/otp/index.ts">

<violation number="1" location="packages/better-auth/src/plugins/two-factor/otp/index.ts:137">
Incomplete description string; it ends mid-sentence. Restore the full sentence and example for clarity in generated docs.</violation>
</file>

<file name="packages/better-auth/src/plugins/admin/admin.ts">

<violation number="1" location="packages/better-auth/src/plugins/admin/admin.ts:501">
Invalid Zod record key schema: use a string-like key (e.g., z.string()) instead of z.any() for z.record().</violation>

<violation number="2" location="packages/better-auth/src/plugins/admin/admin.ts:606">
Attach description to the union schema instead of a single branch to document the full (string | number | boolean) type.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

cubic-dev-ai · 2025-09-23T20:30:48Z

packages/better-auth/src/plugins/organization/routes/crud-invites.ts

-				id: z.string().meta({
-					description: "The ID of the invitation to get",
-				}),
+				id: z.string().describe("The ID of the invitation to get"),


Rule violated: Enforce Consistent Naming Conventions

Use a descriptive parameter name for consistency and clarity; replace generic id with invitationId to align with other endpoints and naming conventions.

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/organization/routes/crud-invites.ts at line 847: <comment>Use a descriptive parameter name for consistency and clarity; replace generic id with invitationId to align with other endpoints and naming conventions.</comment> <file context> @@ -869,9 +844,7 @@ export const getInvitation = <O extends OrganizationOptions>(options: O) => - id: z.string().meta({ - description: "The ID of the invitation to get", - }), + id: z.string().describe("The ID of the invitation to get"), }), metadata: { </file context>

cubic-dev-ai · 2025-09-23T20:30:48Z

packages/better-auth/src/plugins/organization/routes/crud-access-control.ts

+					.string()
+					.optional()
+					.describe(
+						"The id of the organization to create the role in. If not provided, the user",


Description text truncated mid-sentence; restore full message for clarity.

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/organization/routes/crud-access-control.ts at line 75: <comment>Description text truncated mid-sentence; restore full message for clarity.</comment> <file context> @@ -68,16 +68,16 @@ export const createOrgRole = <O extends OrganizationOptions>(options: O) => { + .string() + .optional() + .describe( + "The id of the organization to create the role in. If not provided, the user", + ), + role: z.string().describe("The name of the role to create"), </file context>

cubic-dev-ai · 2025-09-23T20:30:49Z

packages/better-auth/src/plugins/organization/routes/crud-access-control.ts

+						.string()
+						.optional()
+						.describe(
+							"The id of the organization to read a role for. If not provided, the user",


Description text truncated mid-sentence; restore full message for clarity.

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/organization/routes/crud-access-control.ts at line 606: <comment>Description text truncated mid-sentence; restore full message for clarity.</comment> <file context> @@ -599,22 +599,20 @@ export const getOrgRole = <O extends OrganizationOptions>(options: O) => { + .string() + .optional() + .describe( + "The id of the organization to read a role for. If not provided, the user", + ), }) </file context>

cubic-dev-ai · 2025-09-23T20:30:49Z

packages/better-auth/src/plugins/organization/routes/crud-access-control.ts

+						.string()
+						.optional()
+						.describe(
+							"The id of the organization to update the role in. If not provided, the user",


Description text truncated mid-sentence; restore full message for clarity.

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/organization/routes/crud-access-control.ts at line 764: <comment>Description text truncated mid-sentence; restore full message for clarity.</comment> <file context> @@ -759,34 +757,31 @@ export const updateOrgRole = <O extends OrganizationOptions>(options: O) => { + .string() + .optional() + .describe( + "The id of the organization to update the role in. If not provided, the user", + ), data: z.object({ </file context>

cubic-dev-ai · 2025-09-23T20:30:49Z

packages/better-auth/src/plugins/generic-oauth/index.ts

-									'The URL to redirect to after login if the user is new. Eg: "/welcome"',
-							})
+							.describe(
+								"The URL to redirect to after login if the user is new. Eg: ",


Incomplete description string: the example is missing after "Eg:". Provide a concrete example or remove the placeholder.

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/generic-oauth/index.ts at line 358: <comment>Incomplete description string: the example is missing after "Eg:". Provide a concrete example or remove the placeholder.</comment> <file context> @@ -341,47 +341,38 @@ export const genericOAuth = (options: GenericOAuthOptions) => { - 'The URL to redirect to after login if the user is new. Eg: "/welcome"', - }) + .describe( + "The URL to redirect to after login if the user is new. Eg: ", + ) .optional(), </file context>

Suggested change

"The URL to redirect to after login if the user is new. Eg: ",

"The URL to redirect to after login if the user is new. Eg: \"/welcome\"",

cubic-dev-ai · 2025-09-23T20:30:50Z

packages/sso/src/index.ts

-												description:
-													"Field mapping for image (defaults to 'picture')",
-											})
+											.describe("Field mapping for image (")


Truncated .describe() texts in oidcConfig.mapping (dangling '(' and missing defaults) degrade API docs clarity.

Prompt for AI agents

Address the following comment on packages/sso/src/index.ts at line 342: <comment>Truncated .describe() texts in oidcConfig.mapping (dangling '(' and missing defaults) degrade API docs clarity.</comment> <file context> @@ -284,95 +284,62 @@ export const sso = (options?: SSOOptions) => { - description: - "Field mapping for image (defaults to 'picture')", - }) + .describe("Field mapping for image (") .optional(), extraFields: z.record(z.string(), z.any()).optional(), </file context>

cubic-dev-ai · 2025-09-23T20:30:50Z

packages/better-auth/src/plugins/device-authorization/index.ts

-						error_description: z.string().meta({
-							description: "Detailed error description",
-						}),
+						error: z.enum(["invalid_request"]).describe("Error code"),


Error enum for /device missing "expired_token", which this endpoint returns when the user code is expired.

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/device-authorization/index.ts at line 625: <comment>Error enum for /device missing "expired_token", which this endpoint returns when the user code is expired.</comment> <file context> @@ -631,17 +619,13 @@ Follow [rfc8628#section-3.4](https://datatracker.ietf.org/doc/html/rfc8628#secti - error_description: z.string().meta({ - description: "Detailed error description", - }), + error: z.enum(["invalid_request"]).describe("Error code"), + error_description: z + .string() </file context>

Suggested change

error: z.enum(["invalid_request"]).describe("Error code"),

error: z.enum(["invalid_request", "expired_token"]).describe("Error code"),

cubic-dev-ai · 2025-09-23T20:30:50Z

packages/better-auth/src/plugins/two-factor/otp/index.ts

+					trustDevice: z
+						.boolean()
+						.optional()
+						.describe("If true, the device will be trusted for 30 days. It"),


Incomplete description string; it ends mid-sentence. Restore the full sentence and example for clarity in generated docs.

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/two-factor/otp/index.ts at line 137: <comment>Incomplete description string; it ends mid-sentence. Restore the full sentence and example for clarity in generated docs.</comment> <file context> @@ -131,10 +131,10 @@ export const otp2fa = (options?: OTPOptions) => { + trustDevice: z + .boolean() + .optional() + .describe("If true, the device will be trusted for 30 days. It"), }) .optional(), </file context>

cubic-dev-ai · 2025-09-23T20:30:50Z

packages/better-auth/src/plugins/admin/admin.ts

-							.meta({
-								description: "The value to filter by",
-							})
+							.describe("The value to filter by")


Attach description to the union schema instead of a single branch to document the full (string | number | boolean) type.

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/admin/admin.ts at line 606: <comment>Attach description to the union schema instead of a single branch to document the full (string | number | boolean) type.</comment> <file context> @@ -584,68 +566,50 @@ export const admin = <O extends AdminOptions>(options?: O) => { - .meta({ - description: "The value to filter by", - }) + .describe("The value to filter by") .or(z.number()) .or(z.boolean()) </file context>

cubic-dev-ai · 2025-09-23T20:30:50Z

packages/better-auth/src/plugins/admin/admin.ts

-						}),
+						userId: z.coerce.string().describe("The user id"),
+						data: z
+							.record(z.any(), z.any())


Invalid Zod record key schema: use a string-like key (e.g., z.string()) instead of z.any() for z.record().

Prompt for AI agents

Address the following comment on packages/better-auth/src/plugins/admin/admin.ts at line 501: <comment>Invalid Zod record key schema: use a string-like key (e.g., z.string()) instead of z.any() for z.record().</comment> <file context> @@ -512,12 +496,10 @@ export const admin = <O extends AdminOptions>(options?: O) => { - }), + userId: z.coerce.string().describe("The user id"), + data: z + .record(z.any(), z.any()) + .describe("The user data to update"), }), </file context>

Suggested change

.record(z.any(), z.any())

.record(z.string(), z.any())

This reverts commit 7fa0c2d.

chore: use zod v3 syntax

24fc68c

himself65 requested a review from Bekacru as a code owner September 23, 2025 20:22

himself65 enabled auto-merge September 23, 2025 20:27

himself65 added this pull request to the merge queue Sep 23, 2025

cubic-dev-ai bot reviewed Sep 23, 2025

View reviewed changes

Merged via the queue into better-auth:canary with commit 7fa0c2d Sep 23, 2025
8 of 10 checks passed

himself65 added a commit to himself65/better-auth that referenced this pull request Sep 23, 2025

chore: use zod v3 syntax (better-auth#4851)

202f55d

himself65 added a commit that referenced this pull request Sep 23, 2025

chore: use zod v3 syntax (#4851)

53becd2

dosubot bot mentioned this pull request Sep 23, 2025

1.3.10 and later does not work on zod 3 projects (part 2) #4856

Closed

1 task

himself65 added a commit to himself65/better-auth that referenced this pull request Sep 25, 2025

Revert "chore: use zod v3 syntax (better-auth#4851)"

de2df06

This reverts commit 7fa0c2d.

himself65 added a commit that referenced this pull request Sep 25, 2025

Revert "chore: use zod v3 syntax (#4851)"

faea100

This reverts commit 7fa0c2d.

himself65 added a commit that referenced this pull request Sep 25, 2025

Revert "chore: use zod v3 syntax (#4851)"

38b18f2

This reverts commit 7fa0c2d.

himself65 added a commit that referenced this pull request Sep 25, 2025

Revert "chore: use zod v3 syntax (#4851)"

58bbf0f

This reverts commit 7fa0c2d.

himself65 added a commit that referenced this pull request Sep 25, 2025

Revert "chore: use zod v3 syntax (#4851)"

8757cfe

This reverts commit 7fa0c2d.

rae-fcm pushed a commit to FullCodeMedical/better-auth that referenced this pull request Mar 9, 2026

chore: use zod v3 syntax (better-auth#4851)

b479a92

rae-fcm pushed a commit to FullCodeMedical/better-auth that referenced this pull request Mar 9, 2026

Revert "chore: use zod v3 syntax (better-auth#4851)"

57f22d8

This reverts commit 7fa0c2d.

better-auth locked as resolved and limited conversation to collaborators Apr 1, 2026

bytaesu added the locked Locked conversations after being closed for 7 days label Apr 1, 2026

	"The URL to redirect to after login if the user is new. Eg: ",
	"The URL to redirect to after login if the user is new. Eg: \"/welcome\"",

	error: z.enum(["invalid_request"]).describe("Error code"),
	error: z.enum(["invalid_request", "expired_token"]).describe("Error code"),

Uh oh!

Conversation

himself65 commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by cubic

Uh oh!

vercel bot commented Sep 23, 2025

Uh oh!

pkg-pr-new bot commented Sep 23, 2025

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

himself65 commented Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading

cubic-dev-ai bot Sep 23, 2025 •

edited

Loading