Merge branch 'main' into docs-guide-rbac

Author: ThangHuuVu

.prettierignore

@@ -1,3 +1,4 @@
+.prettierignore
 .cache-loader
 .DS_Store
 .pnpm-debug.log
@@ -11,6 +12,7 @@ pnpm-lock.yaml
 .github/actions/issue-validator/index.mjs
 *.d.ts
 *.d.ts.map
+**/*.sh
 
 .svelte-kit
 .next

docs/pages/getting-started/adapters/surrealdb.mdx

@@ -13,17 +13,27 @@ import { Code } from "@/components/Code"
 ### Installation
 
 ```bash npm2yarn
-npm install @auth/surrealdb-adapter surrealdb.js
+npm install @auth/surrealdb-adapter surrealdb
 ```
 
 ### Environment Variables
 
+A valid authentication combination must be provided. The following authentication combinations are supported:
+
+- RootAuth
+- NamespaceAuth
+- DatabaseAuth
+- ScopeAuth
+
 ```sh
-AUTH_SURREALDB_CONNECTION
-AUTH_SURREALDB_USERNAME
-AUTH_SURREALDB_PASSWORD
-AUTH_SURREALDB_NS
-AUTH_SURREALDB_DB
+AUTH_SURREAL_URL (required)
+AUTH_SURREAL_NS
+AUTH_SURREAL_DB
+AUTH_SURREAL_USER
+AUTH_SURREAL_PW
+AUTH_SURREAL_SCOPE
+SURREAL_NS (required when using RootAuth or NamespaceAuth)
+SURREAL_DB (required when using RootAuth or NamespaceAuth)
 ```
 
 ### Configuration
@@ -97,84 +107,172 @@ app.use(
 
 The SurrealDB adapter does not handle connections automatically, so you will have to make sure that you pass the Adapter a `SurrealDBClient` that is connected already. Below you can see an example how to do this.
 
+### Utils File
+
+```ts filename="./lib/surrealdb_utils.ts"
+import type { ConnectOptions, AnyAuth } from "surrealdb"
+import { Surreal, ConnectionStatus } from "surrealdb"
+
+/**
+ * Maintains a single instance of surrealdb.
+ * Automatically reconnects unless options.reconnect is set to false manually.
+ */
+export class MySurreal {
+  // A single instantiation of a surreal connection
+  private _surrealdb: Surreal | undefined
+  private _url: string | URL
+  private _opts: ConnectOptions | undefined
+
+  constructor(
+    url: Parameters<InstanceType<typeof Surreal>["connect"]>[0],
+    opts?: ConnectOptions
+  ) {
+    this._url = url
+    if (opts && opts.reconnect === undefined) {
+      opts.reconnect = true
+    }
+    this._opts = opts
+  }
+
+  async surrealdb(): Promise<Surreal> {
+    // Init Surreal
+    if (!this._surrealdb) {
+      this._surrealdb = new Surreal()
+    }
+
+    if (this._surrealdb.status == ConnectionStatus.Connected) {
+      return this._surrealdb
+    } else if (this._surrealdb.status == ConnectionStatus.Disconnected) {
+      try {
+        // Connect as a database user
+        await this._surrealdb.connect(this._url, this._opts)
+        if (process.env.NODE_ENV === "development") {
+          const str = this.toConnectionString(
+            this._surrealdb.status,
+            this._opts
+          )
+          console.info(str)
+        }
+      } catch (error) {
+        if (error instanceof Error) throw error
+        throw new Error(error as unknown as string)
+      }
+    }
+    return this._surrealdb
+  }
+
+  private toConnectionString(status: ConnectionStatus, opts?: ConnectOptions) {
+    let str = `${status}`
+    const auth = opts?.auth
+
+    if (auth && typeof auth !== "string") {
+      if ("username" in auth) {
+        str += ` as ${auth.username}`
+      }
+      if ("database" in auth && "namespace" in auth) {
+        str += ` for ${auth.namespace} ${auth.database}`
+      } else if ("namespace" in auth) {
+        str += ` for ${auth.namespace}`
+      } else if ("database" in auth) {
+        str += ` for ${auth.database}`
+      }
+    }
+    return str
+  }
+}
+
+/**
+ * Converts environment variables to an AnyAuth type
+ * to connect with the database
+ * @param param0 - environment variables
+ * @returns {RootAuth | NamespaceAuth | DatabaseAuth | ScopeAuth}
+ */
+export function toAnyAuth({
+  username,
+  password,
+  namespace,
+  database,
+  scope,
+}: Record<string, string | undefined>) {
+  let auth: AnyAuth
+  if (username && password && namespace && database) {
+    auth = {
+      database,
+      namespace,
+      username,
+      password,
+    }
+  } else if (username && password && namespace) {
+    auth = {
+      namespace,
+      username,
+      password,
+    }
+  } else if (username && password) {
+    auth = {
+      username,
+      password,
+    }
+  } else if (scope) {
+    auth = {
+      namespace,
+      database,
+      username,
+      password,
+      scope,
+    }
+  } else {
+    throw new Error("unsupported any auth configuration")
+  }
+  return auth
+}
+```
+
 ### Authorization
 
-#### Option 1 – Using RPC:
+The clientPromise provides a connection to the database. You could use any connect option you wish. For quick setup, use the DatabaseAuth method. For best security, we recommend creating a Record Access method if you know how to properly setup access table permissions.
 
 ```ts filename="./lib/surrealdb.ts"
-import { Surreal } from "surrealdb.js"
-
-const connectionString = process.env.AUTH_SURREALDB_CONNECTION
-const username = process.env.AUTH_SURREALDB_USERNAME
-const password = process.env.AUTH_SURREALDB_PASSWORD
-const namespace = process.env.AUTH_SURREALDB_NAMESPACE
-const database = process.env.AUTH_SURREALDB_DATABASE
-if (!connectionString || !username || !password || !namespace || !database) {
-  throw new Error(
-    "SurrealDB connection string, username, password, namespace, and database are required"
-  )
-}
+import { type Surreal } from "surrealdb"
+import { handleDisconnect, MySurreal, toAnyAuth } from "./lib/surrealdb_utils"
 
 const clientPromise = new Promise<Surreal>(async (resolve, reject) => {
-  const db = new Surreal()
   try {
-    await db.connect(`${connectionString}/rpc`, {
+    const {
+      AUTH_SURREAL_URL: auth_url,
+      AUTH_SURREAL_NS: auth_ns,
+      AUTH_SURREAL_DB: auth_db,
+      AUTH_SURREAL_USER: auth_user,
+      AUTH_SURREAL_PW: auth_pw,
+      AUTH_SURREAL_SCOPE: auth_scope,
+      SURREAL_NS: namespace,
+      SURREAL_DB: database,
+    } = process.env
+    if (!auth_url) throw new Error("required auth_url")
+    const auth = toAnyAuth({
+      namespace: auth_ns,
+      database: auth_db,
+      username: auth_user,
+      password: auth_pw,
+      scope: auth_scope,
+    })
+    const surreal = new MySurreal(auth_url, {
       namespace,
       database,
-      auth: {
-        username,
-        password,
-      },
+      auth,
     })
+    const db = await surreal.surrealdb()
     resolve(db)
   } catch (e) {
     reject(e)
   }
 })
-
-// Export a module-scoped Promise<Surreal>. By doing this in a
-// separate module, the client can be shared across functions.
-export default clientPromise
 ```
 
-#### Option 2 – Using HTTP:
+#### HTTP ENGINE
 
-Useful in serverless environments like Vercel.
+With this configuration, we can use the database's http endpoint. Thus, the `AUTH_SURREAL_URL` should begin with `http` or `https`.
 
-```ts filename="./lib/surrealdb.ts"
-import { ExperimentalSurrealHTTP } from "surrealdb.js"
-
-const connectionString = process.env.AUTH_SURREALDB_CONNECTION
-const username = process.env.AUTH_SURREALDB_USERNAME
-const password = process.env.AUTH_SURREALDB_PASSWORD
-const namespace = process.env.AUTH_SURREALDB_NAMESPACE
-const database = process.env.AUTH_SURREALDB_DATABASE
-if (!connectionString || !username || !password || !namespace || !database) {
-  throw new Error(
-    "SurrealDB connection string, username, password, namespace, and database are required"
-  )
-}
+#### Websocket ENGINE
 
-const clientPromise = new Promise<ExperimentalSurrealHTTP<typeof fetch>>(
-  async (resolve, reject) => {
-    try {
-      const db = new ExperimentalSurrealHTTP(connectionString, {
-        fetch,
-        namespace,
-        database,
-        auth: {
-          username,
-          password,
-        },
-      })
-      resolve(db)
-    } catch (e) {
-      reject(e)
-    }
-  }
-)
-
-// Export a module-scoped Promise<Surreal>. By doing this in a
-// separate module, the client can be shared across functions.
-export default clientPromise
-```
+With this configuration, we can use the database's websocket endpoint. Thus, the `AUTH_SURREAL_URL` should begin with `ws` or `wss`.

docs/pages/getting-started/providers/mailgun.mdx

@@ -41,6 +41,8 @@ AUTH_MAILGUN_KEY=abc
 
 If you name your environment variable `AUTH_MAILGUN_KEY`, the provider will pick it up automatically and your Auth.js configuration object can be simpler. If you'd like to rename it to something else, however, you'll have to manually pass it into the provider in your Auth.js configuration.
 
+3. If you are using the EU Mailgun server, you will need to include `region: "EU"` in the provider options. If you are using the US Mailgun server you can remove this option.
+
 <Code>
 <Code.Next>
 
@@ -53,8 +55,9 @@ export const { handlers, auth, signIn, signOut } = NextAuth({
   providers: [
     Mailgun({
       // If your environment variable is named differently than default
-      apiKey: import.meta.env.AUTH_MAILGUN_KEY,
-      from: "[email protected]"
+      apiKey: process.env.AUTH_MAILGUN_KEY,
+      from: "[email protected]",
+      region: "EU",  // Optional
     }),
   ],
 })
@@ -74,6 +77,7 @@ export const { onRequest, useSession, useSignIn, useSignOut } = QwikAuth$(
         // If your environment variable is named differently than default
         apiKey: import.meta.env.AUTH_MAILGUN_KEY,
         from: "[email protected]",
+        region: "EU", // Optional
       }),
     ],
   })
@@ -95,6 +99,7 @@ export const { handle, signIn, signOut } = SvelteKitAuth({
       // If your environment variable is named differently than default
       apiKey: env.AUTH_MAILGUN_KEY,
       from: "[email protected]",
+      region: "EU",  // Optional
     }),
   ],
 })

docs/pages/guides/extending-the-session.mdx

@@ -34,7 +34,7 @@ To have access to the user id, add the following to your Auth.js configuration:
 ```
 
 During sign-in, the `jwt` callback exposes the user's profile information coming from the provider.
-You can leverage this to add the user's id to the JWT token. Then, on subsequent calls of this API will have access to the user's id via `token.id`.
+You can leverage this to add the user's id to the JWT token. Then, on subsequent calls of this API you will have access to the user's id via `token.id`.
 Then, to expose the user's id in the actual session, you can access `token.id` in the `session` callback and save it on `session.user.id`.
 
 Calls to `auth()` or `useSession()` will now have access to the user's id.

packages/adapter-prisma/src/index.ts

@@ -15,7 +15,7 @@
  *
  * @module @auth/prisma-adapter
  */
-import { Prisma, type PrismaClient } from "@prisma/client"
+import type { PrismaClient } from "@prisma/client"
 import type {
   Adapter,
   AdapterAccount,
@@ -89,7 +89,9 @@ export function PrismaAdapter(
         // If token already used/deleted, just return null
         // https://www.prisma.io/docs/reference/api-reference/error-reference#p2025
         if (
-          error instanceof Prisma.PrismaClientKnownRequestError &&
+          error &&
+          typeof error === "object" &&
+          "code" in error &&
           error.code === "P2025"
         )
           return null

packages/adapter-surrealdb/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@auth/surrealdb-adapter",
-  "version": "1.9.1",
+  "version": "2.0.0",
   "description": "SurrealDB adapter for next-auth.",
   "homepage": "https://authjs.dev",
   "repository": "https://github.com/nextauthjs/next-auth",
   "bugs": {
     "url": "https://github.com/nextauthjs/next-auth/issues"
   },
-  "author": "Martin Schaer <martin@schaerweb.com>",
+  "author": "Dylan Vanmali <https://github.com/dvanmali>",
   "contributors": [
+    "Martin Schaer <[email protected]>",
     "Thang Huu Vu <[email protected]>"
   ],
   "type": "module",
@@ -29,7 +30,7 @@
     "next-auth",
     "next.js",
     "oauth",
-    "mongodb",
+    "surrealdb",
     "adapter"
   ],
   "private": false,
@@ -45,6 +46,6 @@
     "@auth/core": "workspace:*"
   },
   "peerDependencies": {
-    "surrealdb.js": "^0.11.0"
+    "surrealdb": "^1.3.0"
   }
 }