update submodule docs

LICENSE

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2018-2021, Iain Collins
+Copyright (c) 2022-2023, Balázs Orbán
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

packages/core/src/adapters.ts

@@ -1,8 +1,9 @@
 /**
- * The `@auth/core/adapters` module contains useful helpers that a database adapter
- * can incorporate in order to be compatible with Auth.js.
- * You can think of an adapter as a way to normalize database implementation details to a common interface
- * that Auth.js can use to interact with the database.
+ * This module contains functions and types that a database adapter
+ * can use to be compatible with Auth.js.
+ *
+ * A database adapter provides a common interface for Auth.js so that it can work with
+ * _any_ database/ORM adapter without concerning itself with the implementation details of the database/ORM.
  *
  * Auth.js supports 2 session strtategies to persist the login state of a user.
  * The default is to use a cookie + {@link https://authjs.dev/concepts/session-strategies#jwt JWT}
@@ -11,7 +12,7 @@
  *
  * :::info Note
  * Auth.js _currently_ does **not** implement {@link https://authjs.dev/concepts/session-strategies#federated-logout federated logout}.
- * So even if the session is deleted from the database, the user will still be logged in to the provider.
+ * So even if the session is deleted from the database, the user will still be logged in to the provider (but will be logged out of the app).
  * See [this discussion](https://github.com/nextauthjs/next-auth/discussions/3938) for more information.
  * :::
  *
@@ -21,29 +22,48 @@
  * npm install @auth/core
  * ```
  *
+ * You can then import this submodule from `@auth/core/adapters`.
+ *
  * ## Usage
  *
- * {@link https://authjs.dev/reference/adapters/overview Built-in adapters} already implement this interface, so you likely won't need to
+ * {@link https://authjs.dev/reference/adapters/overview Built-in adapters} already implement this interfac, so you likely won't need to
  * implement it yourself. If you do, you can use the following example as a
  * starting point.
  *
- * ```ts
- * // src/your-adapter.ts
+ * ```ts title=your-adapter.ts
  * import { type Adapter } from "@auth/core/adapters"
  *
- * export function MyAdapter(options: any): Adapter {
+ * export function MyAdapter(config: {}): Adapter {
  *  // implement the adapter methods
  * }
+ * ```
  *
- * // src/index.ts
+ * ```ts title=index.ts
  * import { MyAdapter } from "./your-adapter"
  *
  * const response = Auth({
- *   adapter: MyAdapter({ ...adapter options }),
- *   ... auth options
+ *   adapter: MyAdapter({ /* ...adapter config *\/ }),
+ *   // ... auth config
  * })
  * ```
  *
+ * :::caution Note
+ * Although `@auth/core` is framework/runtime agnostic, an adapter might rely on a client/ORM package,
+ * that is not yet compatible with your runtime
+ * (E.g. it might rely on [Node.js-specific APIs](https://nodejs.org/docs/latest/api)) when you are trying to use it elsewhere.
+ * Related issues should be reported to the corresponding package maintainers.
+ * :::
+ *
+ * ### Testing
+ * :::tip
+ * If you are writing your own adapter, there is a test suite [available](https://github.com/nextauthjs/next-auth/tree/main/packages/adapter-test)
+ * to ensure that your adapter is compatible with Auth.js.
+ * :::
+ *
+ * ## Resources
+ *
+ * - [What is a database session strategy?](https://authjs.dev/concepts/session-strategies#database)
+ *
  * @module adapters
  */
 

packages/core/src/index.ts

@@ -1,9 +1,19 @@
 /**
  *
- * `@auth/core` is the main entry point for the Auth.js library.
+ * This is the main entry point to the Auth.js library.
  *
  * Based on the {@link https://developer.mozilla.org/en-US/docs/Web/API/Request Request}
  * and {@link https://developer.mozilla.org/en-US/docs/Web/API/Response Response} Web standard APIs.
+ * Primarily used to implement [framework](https://authjs.dev/concepts/frameworks)-specific packages,
+ * but it can also be used directly.
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn2pnpm
+ * npm install @auth/core
+ * ```
+ *
+ * ## Usage
  *
  * ```ts
  * import { Auth } from "@auth/core"
@@ -14,14 +24,10 @@
  * console.log(response instanceof Response) // true
  * ```
  *
- * Primarily used to implement [framework](https://authjs.dev/concepts/frameworks)-specific packages,
- * but it can also be used directly.
- *
- * ## Installation
+ * ## Resources
  *
- * ```bash npm2yarn2pnpm
- * npm install @auth/core
- * ```
+ * - [Gettint started](https://authjs.dev/getting-started/introduction)
+ * - [Most common use case guides](https://authjs.dev/guides/overview)
  *
  * @module main
  */

packages/core/src/jwt.ts

@@ -1,13 +1,37 @@
 /**
- * `@authjs/core/jwt` provides functions
+ *
+ *
+ * This module contains functions and types
  * to encode and decode {@link https://authjs.dev/concepts/session-strategies#jwt JWT}s
- * issued and used by Auth.js. It is meant for being used in the app only.
- * If you need JWT authentication for your API, you should rely on your Identity Provider.
+ * issued and used by Auth.js.
  *
- * The JWT created by Auth.js is encrypted using the `A256GCM` algorithm ({@link https://www.rfc-editor.org/rfc/rfc7516 JWE}). by default.
+ * The JWT issued by Auth.js is _encrypted by default_, using the _A256GCM_ algorithm ({@link https://www.rfc-editor.org/rfc/rfc7516 JWE}).
  * It uses the `AUTH_SECRET` environment variable to dervice a sufficient encryption key.
  *
- * @see [RFC7519 - JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519)
+ * :::info Note
+ * Auth.js JWTs are meant to be used by the same app that issued them.
+ * If you need JWT authentication for your third-party API, you should rely on your Identity Provider instead.
+ * :::
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn2pnpm
+ * npm install @auth/core
+ * ```
+ *
+ * You can then import this submodule from `@auth/core/jwt`.
+ *
+ * ## Usage
+ *
+ * :::warning Warning
+ * This module *will* be refactored/changed. We do not recommend relying on it right now.
+ * :::
+ *
+ *
+ * ## Resources
+ *
+ * - [What is a JWT session strategy](https://authjs.dev/concepts/session-strategies#jwt)
+ * - [RFC7519 - JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519)
  *
  * @module jwt
  */

packages/core/src/types.ts

@@ -1,6 +1,56 @@
 /**
  *
- * `@auth/core/types` contains all public types and interfaces of the core package.
+ * This module contains public types and interfaces of the core package.
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn2pnpm
+ * npm install @auth/core
+ * ```
+ *
+ * You can then import this submodule from `@auth/core/type`.
+ *
+ * ## Usage
+ *
+ * Even if you don't use TypeScript, IDEs like VSCode will pick up types to provide you with a better developer experience.
+ * While you are typing, you will get suggestions about what certain objects/functions look like,
+ * and sometimes links to documentation, examples, and other valuable resources.
+ *
+ * Generally, you will not need to import types from this module.
+ * Mostly when using the `Auth` function and optionally the `AuthConfig` interface,
+ * everything inside there will already be typed.
+ *
+ * :::tip
+ * Inside the `Auth` function, you won't need to use a single type from this module.
+ *
+ * @example
+ * ```ts title=index.ts
+ * import { Auth } from "@auth/core"
+ *
+ * const request = new Request("https://example.com")
+ * const response = await Auth(request, {
+ *   callbacks: {
+ *     jwt(): JWT { // <-- This is unnecessary!
+ *       return { foo: "bar" }
+ *     },
+ *     session(
+ *        { session, token }: { session: Session; token: JWT } // <-- This is unnecessary!
+ *     ) {
+ *       return session
+ *     },
+ *   }
+ * })
+ * ```
+ * :::
+ *
+ * :::info
+ * We are advocates of TypeScript, as it will help you catch errors at build-time, before your users do. 😉
+ * :::
+ *
+ * ## Resources
+ *
+ * - [TypeScript - The Basics](https://www.typescriptlang.org/docs/handbook/2/basic-types.html)
+ * - [Extending built-in types](https://authjs.dev/getting-started/typescript#module-augmentation)
  *
  * @module types
  */