feat(nextjs): Mark keyless onboarding as complete when stored keys match explicit keys

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
       path: basePath,
     });
   }
+
+  public async completeAccountlessApplicationOnboarding() {
+    return this.request<AccountlessApplication>({
+      method: 'POST',
+      path: joinPaths(basePath, 'complete'),
+    });
+  }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
   claimUrl: string;
   copyKeysUrl: string;
-  onDismiss: (() => Promise<unknown>) | undefined;
+  onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
     return null;
   }
 
-  const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+  const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
   /**
    * Notify developers.
    */
-  keylessLogger?.log({
+  clerkDevelopmentCache?.log({
     cacheKey: result.publishableKey,
     msg: createKeylessModeMessage(result),
   });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
     const newOrReadKeys = await import('../../server/keyless-node.js')
       .then(mod => mod.createOrReadKeyless())
       .catch(() => null);
-    const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+    const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
       '../../server/keyless-log-cache.js'
     );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
             publishableKey: newOrReadKeys.publishableKey,
             __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
             __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
-            __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+            // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+            __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
           })}
           nonce={await generateNonce()}
           initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
       );
 
       if (runningWithClaimedKeys) {
+        try {
+          const secretKey = await import('../../server/keyless-node.js').then(
+            mod => mod.safeParseClerkFile()?.secretKey,
+          );
+          if (!secretKey) {
+            // we will ignore it later
+            throw new Error(secretKey);
+          }
+          const client = createClerkClientWithOptions({
+            secretKey,
+          });
+
+          /**
+           * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+           * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+           */
+          await clerkDevelopmentCache?.run(
+            () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+            {
+              cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+              onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+            },
+          );
+        } catch {
+          // ignore
+        }
+
         /**
          * Notify developers.
          */
-        keylessLogger?.log({
+        clerkDevelopmentCache?.log({
           cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
           msg: createConfirmationMessage(),
         });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
         /**
          * Notify developers.
          */
-        keylessLogger?.log({
+        clerkDevelopmentCache?.log({
           cacheKey: newOrReadKeys.publishableKey,
           msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
         });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
   // eslint-disable-next-line no-var
   var __clerk_internal_keyless_logger:
     | {
-        __cache: Map<string, { expiresAt: number }>;
+        __cache: Map<string, { expiresAt: number; data?: unknown }>;
         log: (param: { cacheKey: string; msg: string }) => void;
+        run: (
+          callback: () => Promise<unknown>,
+          {
+            cacheKey,
+            onSuccessStale,
+            onErrorStale,
+          }: {
+            cacheKey: string;
+            onSuccessStale?: number;
+            onErrorStale?: number;
+          },
+        ) => Promise<unknown>;
       }
     | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
   if (!isDevelopmentEnvironment()) {
     return;
   }
 
   if (!global.__clerk_internal_keyless_logger) {
     global.__clerk_internal_keyless_logger = {
-      __cache: new Map<string, { expiresAt: number }>(),
+      __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
-      log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+      log: function ({ cacheKey, msg }) {
         if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
           return;
         }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
           expiresAt: Date.now() + THROTTLE_DURATION_MS,
         });
       },
+      run: async function (
+        callback,
+        { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+      ) {
+        if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+          return this.__cache.get(cacheKey)?.data;
+        }
+
+        try {
+          const result = await callback();
+
+          this.__cache.set(cacheKey, {
+            expiresAt: Date.now() + onSuccessStale,
+            data: result,
+          });
+          return result;
+        } catch (e) {
+          this.__cache.set(cacheKey, {
+            expiresAt: Date.now() + onErrorStale,
+          });
+
+          throw e;
+        }
+      },
     };
   }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
   return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
      * Pass a function that will trigger the unmounting of the Keyless Prompt.
      * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
      */
-    __internal_keyless_dismissPrompt?: () => Promise<void>;
+    __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
   };
 
 export interface NavigateOptions {