.changeset/big-queens-tap.md (1)

6-6: Expand the changeset body to enumerate the experimental API surface

Consider listing the new experimental APIs to aid consumers and reviewers:

• SignUpFuture.verifications: sendEmailCode(), verifyEmailCode({ code })
• SignUpFuture.unverifiedFields getter
• SignUpFuture.password({ emailAddress, password })
• SignUpFuture.finalize({ navigate })

This helps changelog readers assess potential usage and migration paths.

packages/types/src/signUp.ts (1)

122-131: Document and lock down the new SignUpFuture surface (readonly + JSDoc)

These are public types; add minimal JSDoc and mark readonly where appropriate to prevent external mutation.

Apply this diff:

 export interface SignUpFutureResource {
-  status: SignUpStatus | null;
-  unverifiedFields: SignUpIdentificationField[];
-  verifications: {
+  /** @experimental Mirrors SignUp.status */
+  readonly status: SignUpStatus | null;
+  /** @experimental Mirrors SignUp.unverifiedFields */
+  readonly unverifiedFields: SignUpIdentificationField[];
+  /** @experimental Verification helpers for email-code flows */
+  readonly verifications: {
     sendEmailCode: () => Promise<{ error: unknown }>;
     verifyEmailCode: (params: { code: string }) => Promise<{ error: unknown }>;
   };
-  password: (params: { emailAddress: string; password: string }) => Promise<{ error: unknown }>;
-  finalize: (params: { navigate?: SetActiveNavigate }) => Promise<{ error: unknown }>;
+  /** @experimental Starts email/password sign-up creation */
+  password: (params: { emailAddress: string; password: string }) => Promise<{ error: unknown }>;
+  /** @experimental Finalizes sign-up by activating created session */
+  finalize: (params: { navigate?: SetActiveNavigate }) => Promise<{ error: unknown }>;
 }

Optionally, consider exporting a shared async result type (e.g., type ResourceTaskResult<T = void> = { result?: T; error: unknown }) to align these signatures with runAsyncResourceTask.

packages/clerk-js/src/core/resources/SignUp.ts (4)

499-506: Prefer reusing existing helpers for email code preparation

Reusing the typed helper improves maintainability and keeps behavior aligned.

Apply this diff:

-  async sendEmailCode(): Promise<{ error: unknown }> {
-    return runAsyncResourceTask(this.resource, async () => {
-      await this.resource.__internal_basePost({
-        body: { strategy: 'email_code' },
-        action: 'prepare_verification',
-      });
-    });
-  }
+  async sendEmailCode(): Promise<{ error: unknown }> {
+    return runAsyncResourceTask(this.resource, async () => {
+      await this.resource.prepareEmailAddressVerification();
+    });
+  }

---

508-515: Prefer reusing existing helpers for email code attempt

Same reasoning as above; keeps this thin wrapper aligned with the SignUp resource API.

Apply this diff:

-  async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
-    return runAsyncResourceTask(this.resource, async () => {
-      await this.resource.__internal_basePost({
-        body: { strategy: 'email_code', code },
-        action: 'attempt_verification',
-      });
-    });
-  }
+  async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+    return runAsyncResourceTask(this.resource, async () => {
+      await this.resource.attemptEmailAddressVerification({ code });
+    });
+  }

---

517-525: Throw a typed error when finalizing without a session

Prefer domain-specific errors to a generic Error for consistency and better diagnostics.

Apply this diff:

-  async finalize({ navigate }: { navigate?: SetActiveNavigate }): Promise<{ error: unknown }> {
+  async finalize({ navigate }: { navigate?: SetActiveNavigate }): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
       if (!this.resource.createdSessionId) {
-        throw new Error('Cannot finalize sign-up without a created session.');
+        throw new ClerkRuntimeError('Cannot finalize sign-up without a created session.', {
+          code: 'created_session_missing',
+        });
       }
 
       await SignUp.clerk.setActive({ session: this.resource.createdSessionId, navigate });
     });
   }

Additionally, consider guarding on this.resource.status === 'complete' before activating the session to avoid premature finalization.

---

474-526: Add tests for the new Signal SignUpFuture APIs

Please add unit/integration tests covering:

• password(): calls create under the hood, respects captcha flow, updates resource state.
• sendEmailCode(): triggers prepareEmailAddressVerification and updates verifications state.
• verifyEmailCode(): attempts verification and transitions status appropriately.
• finalize(): throws the typed error when createdSessionId is missing; calls setActive with optional navigate when present.
• Ensure eventBus emissions via runAsyncResourceTask for success and error paths.

I can help scaffold these tests if useful.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/clerk-js/src/core/resources/SignUp.ts (1)

490-497: Do not bypass create flow—this skips captcha gating, normalization, retries

Directly calling __internal_basePost bypasses SignUp.create(), which handles captcha challenges, environment reloads, parameter normalization, and any retry logic. This can cause security and consistency regressions relative to other sign-up flows.

Apply this diff to reuse the existing flow:

   async password({ emailAddress, password }: { emailAddress: string; password: string }): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
-      await this.resource.__internal_basePost({
-        path: this.resource.pathRoot,
-        body: { emailAddress, password },
-      });
+      await this.resource.create({ emailAddress, password });
     });
   }

packages/clerk-js/src/core/resources/SignUp.ts (6)

475-479: Nit: Mark verifications as readonly

This object shouldn’t be reassigned after construction. Marking it readonly communicates intent and prevents accidental mutation.

-class SignUpFuture implements SignUpFutureResource {
-  verifications = {
+class SignUpFuture implements SignUpFutureResource {
+  readonly verifications = {
     sendEmailCode: this.sendEmailCode.bind(this),
     verifyEmailCode: this.verifyEmailCode.bind(this),
   };

---

499-506: Prefer existing prepareEmailAddressVerification() over raw basePost

Use the higher-level API to avoid duplication and to stay aligned with any future changes to verification flows.

   async sendEmailCode(): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
-      await this.resource.__internal_basePost({
-        body: { strategy: 'email_code' },
-        action: 'prepare_verification',
-      });
+      await this.resource.prepareEmailAddressVerification();
     });
   }

---

508-515: Prefer existing attemptEmailAddressVerification() over raw basePost

This keeps behavior consistent with the rest of the codebase and reduces surface area for divergence.

   async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
-      await this.resource.__internal_basePost({
-        body: { strategy: 'email_code', code },
-        action: 'attempt_verification',
-      });
+      await this.resource.attemptEmailAddressVerification({ code });
     });
   }

---

517-525: Use ClerkRuntimeError with actionable guidance when session is missing

Throwing a generic Error makes downstream handling harder and loses error context. Use ClerkRuntimeError with a code and a message suggesting next steps.

   async finalize({ navigate }: { navigate?: SetActiveNavigate }): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
       if (!this.resource.createdSessionId) {
-        throw new Error('Cannot finalize sign-up without a created session.');
+        throw new ClerkRuntimeError(
+          'Cannot finalize sign-up without a created session. Complete verification (e.g. send/verify email code) and ensure create() has produced a createdSessionId before calling finalize().',
+          { code: 'session_missing' },
+        );
       }
 
       await SignUp.clerk.setActive({ session: this.resource.createdSessionId, navigate });
     });
   }

---

474-526: Add JSDoc for the experimental SignUpFuture API

Public/experimental surface should be documented for discoverability and to guide integrators. Briefly describe each method, parameters, and return shape.

Example:

/**
 * @experimental Signal-style future API for orchestrating SignUp flows.
 * Not intended for public use yet; surface is subject to change.
 */
class SignUpFuture implements SignUpFutureResource {
  /**
   * Triggers (or continues) a password-based sign-up using the default instance configuration.
   * Returns an object with `error` set when the operation fails; `result` is unused.
   */
  async password(params: { emailAddress: string; password: string }): Promise<{ error: unknown }>;

  /**
   * Initiates email verification via code for the current sign-up attempt.
   */
  async sendEmailCode(): Promise<{ error: unknown }>;

  /**
   * Attempts to verify the email using the provided code.
   */
  async verifyEmailCode(params: { code: string }): Promise<{ error: unknown }>;

  /**
   * Finalizes the sign-up by activating the created session.
   * Provide `navigate` to customize navigation after activation.
   */
  async finalize(params: { navigate?: SetActiveNavigate }): Promise<{ error: unknown }>;
}

I can open a follow-up PR adding these JSDoc blocks if helpful.

---

474-526: Add targeted tests for the new Signal SignUp APIs

There are no tests shown for this new surface. Add coverage for:

• password(): delegates to SignUp.create with email/password and emits fetch/error events via eventBus
• sendEmailCode(): calls prepareEmailAddressVerification()
• verifyEmailCode(): calls attemptEmailAddressVerification({ code })
• finalize(): throws when createdSessionId is missing; calls Clerk.setActive with navigate when present

Mock the underlying SignUp methods and verify they are invoked correctly, plus ensure runAsyncResourceTask behavior on success/error.

Do you want me to scaffold these tests (e.g., using vitest/jest with spies on resource methods and eventBus)?

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.