tsdoc providers

openauthjs · Jan 7, 2025 · fb7b367 · fb7b367
1 parent 61d9c6b
commit fb7b367
Show file tree

Hide file tree

Showing 34 changed files with 3,135 additions and 122 deletions.
diff --git a/packages/openauth/src/provider/apple.ts b/packages/openauth/src/provider/apple.ts
@@ -1,28 +1,33 @@
 /**
- * This is the Apple provider.
- *
- * Use this provider to authenticate with Apple.
+ * Use this provider to authenticate with Apple. Supports both OAuth2 and OIDC.
  *
  * #### Using OAuth
  *
- * ```ts
- * import { AppleProvider } from "@openauthjs/openauth/provider/apple";
+ * ```ts {5-8}
+ * import { AppleProvider } from "@openauthjs/openauth/provider/apple"
  *
- * AppleProvider({
- *   clientId: "1234567890",
- *   clientSecret: "0987654321",
- * });
+ * export default issuer({
+ *   providers: {
+ *     apple: AppleProvider({
+ *       clientId: "1234567890",
+ *       clientSecret: "0987654321"
+ *     })
+ *   }
+ * })
  * ```
  *
  * #### Using OIDC
  *
- * ```ts
- * import { AppleOidcProvider } from "@openauthjs/openauth/provider/apple";
+ * ```ts {5-7}
+ * import { AppleOidcProvider } from "@openauthjs/openauth/provider/apple"
  *
- * AppleOidcProvider({
- *   clientId: "1234567890",
- *   clientSecret: "0987654321",
- * });
+ * export default issuer({
+ *   providers: {
+ *     apple: AppleOidcProvider({
+ *       clientId: "1234567890"
+ *     })
+ *   }
+ * })
  * ```
  *
  * @packageDocumentation
@@ -31,18 +36,19 @@
 import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js"
 import { OidcProvider, OidcWrappedConfig } from "./oidc.js"
 
-export interface AppleConfig extends Oauth2WrappedConfig {}
-export interface AppleOidcConfig extends OidcWrappedConfig {}
+export interface AppleConfig extends Oauth2WrappedConfig { }
+export interface AppleOidcConfig extends OidcWrappedConfig { }
 
 /**
- * This function creates an Apple OAuth2 provider.
- * @param config - The configuration for the provider.
+ * Create an Apple OAuth2 provider.
+ *
+ * @param config - The config for the provider.
  * @example
  * ```ts
  * AppleProvider({
  *   clientId: "1234567890",
- *   clientSecret: "0987654321",
- * });
+ *   clientSecret: "0987654321"
+ * })
  * ```
  */
 export function AppleProvider(config: AppleConfig) {
@@ -57,13 +63,16 @@ export function AppleProvider(config: AppleConfig) {
 }
 
 /**
- * This function creates an Apple OIDC provider.
+ * Create an Apple OIDC provider.
+ *
+ * This is useful if you just want to verify the user's email address.
+ *
+ * @param config - The config for the provider.
  * @example
  * ```ts
  * AppleOidcProvider({
- *   clientId: "1234567890",
- *   clientSecret: "0987654321",
- * });
+ *   clientId: "1234567890"
+ * })
  * ```
  */
 export function AppleOidcProvider(config: AppleOidcConfig) {

diff --git a/packages/openauth/src/provider/cognito.ts b/packages/openauth/src/provider/cognito.ts
@@ -1,10 +1,65 @@
+/**
+ * Use this provider to authenticate with a Cognito OAuth endpoint.
+ *
+ * ```ts {5-10}
+ * import { CognitoProvider } from "@openauthjs/openauth/provider/cognito"
+ *
+ * export default issuer({
+ *   providers: {
+ *     cognito: CognitoProvider({
+ *       domain: "your-domain.auth.us-east-1.amazoncognito.com",
+ *       region: "us-east-1",
+ *       clientId: "1234567890",
+ *       clientSecret: "0987654321"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js"
 
 export interface CognitoConfig extends Oauth2WrappedConfig {
+  /**
+   * The domain of the Cognito User Pool.
+   *
+   * @example
+   * ```ts
+   * {
+   *   domain: "your-domain.auth.us-east-1.amazoncognito.com"
+   * }
+   * ```
+   */
   domain: string
+  /**
+   * The region the Cognito User Pool is in.
+   *
+   * @example
+   * ```ts
+   * {
+   *   region: "us-east-1"
+   * }
+   * ```
+   */
   region: string
 }
 
+/**
+ * Create a Cognito OAuth2 provider.
+ *
+ * @param config - The config for the provider.
+ * @example
+ * ```ts
+ * CognitoProvider({
+ *   domain: "your-domain.auth.us-east-1.amazoncognito.com",
+ *   region: "us-east-1",
+ *   clientId: "1234567890",
+ *   clientSecret: "0987654321"
+ * })
+ * ```
+ */
 export function CognitoProvider(config: CognitoConfig) {
   const domain = `${config.domain}.auth.${config.region}.amazoncognito.com`
 

diff --git a/packages/openauth/src/provider/discord.ts b/packages/openauth/src/provider/discord.ts
@@ -1,6 +1,39 @@
+/**
+ * Use this provider to authenticate with Discord.
+ *
+ * ```ts {5-8}
+ * import { DiscordProvider } from "@openauthjs/openauth/provider/discord"
+ *
+ * export default issuer({
+ *   providers: {
+ *     discord: DiscordProvider({
+ *       clientId: "1234567890",
+ *       clientSecret: "0987654321"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js"
 
-export function DiscordProvider(config: Oauth2WrappedConfig) {
+export interface DiscordConfig extends Oauth2WrappedConfig { }
+
+/**
+ * Create a Discord OAuth2 provider.
+ *
+ * @param config - The config for the provider.
+ * @example
+ * ```ts
+ * DiscordProvider({
+ *   clientId: "1234567890",
+ *   clientSecret: "0987654321"
+ * })
+ * ```
+ */
+export function DiscordProvider(config: DiscordConfig) {
   return Oauth2Provider({
     type: "discord",
     ...config,

diff --git a/packages/openauth/src/provider/facebook.ts b/packages/openauth/src/provider/facebook.ts
@@ -1,7 +1,57 @@
+/**
+ * Use this provider to authenticate with Facebook. Supports both OAuth2 and OIDC.
+ *
+ * #### Using OAuth
+ *
+ * ```ts {5-8}
+ * import { FacebookProvider } from "@openauthjs/openauth/provider/facebook"
+ *
+ * export default issuer({
+ *   providers: {
+ *     facebook: FacebookProvider({
+ *       clientId: "1234567890",
+ *       clientSecret: "0987654321"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * #### Using OIDC
+ *
+ * ```ts {5-7}
+ * import { FacebookOidcProvider } from "@openauthjs/openauth/provider/facebook"
+ *
+ * export default issuer({
+ *   providers: {
+ *     facebook: FacebookOidcProvider({
+ *       clientId: "1234567890"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js"
 import { OidcProvider, OidcWrappedConfig } from "./oidc.js"
 
-export function FacebookProvider(config: Oauth2WrappedConfig) {
+export interface FacebookConfig extends Oauth2WrappedConfig { }
+export interface FacebookOidcConfig extends OidcWrappedConfig { }
+
+/**
+ * Create a Facebook OAuth2 provider.
+ *
+ * @param config - The config for the provider.
+ * @example
+ * ```ts
+ * FacebookProvider({
+ *   clientId: "1234567890",
+ *   clientSecret: "0987654321"
+ * })
+ * ```
+ */
+export function FacebookProvider(config: FacebookConfig) {
   return Oauth2Provider({
     ...config,
     type: "facebook",
@@ -12,7 +62,20 @@ export function FacebookProvider(config: Oauth2WrappedConfig) {
   })
 }
 
-export function FacebookOidcProvider(config: OidcWrappedConfig) {
+/**
+ * Create a Facebook OIDC provider.
+ *
+ * This is useful if you just want to verify the user's email address.
+ *
+ * @param config - The config for the provider.
+ * @example
+ * ```ts
+ * FacebookOidcProvider({
+ *   clientId: "1234567890"
+ * })
+ * ```
+ */
+export function FacebookOidcProvider(config: FacebookOidcConfig) {
   return OidcProvider({
     ...config,
     type: "facebook",

diff --git a/packages/openauth/src/provider/github.ts b/packages/openauth/src/provider/github.ts
@@ -1,6 +1,39 @@
+/**
+ * Use this provider to authenticate with Github.
+ *
+ * ```ts {5-8}
+ * import { GithubProvider } from "@openauthjs/openauth/provider/github"
+ *
+ * export default issuer({
+ *   providers: {
+ *     github: GithubProvider({
+ *       clientId: "1234567890",
+ *       clientSecret: "0987654321"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js"
 
-export function GithubProvider(config: Oauth2WrappedConfig) {
+export interface GithubConfig extends Oauth2WrappedConfig { }
+
+/**
+ * Create a Github OAuth2 provider.
+ *
+ * @param config - The config for the provider.
+ * @example
+ * ```ts
+ * GithubProvider({
+ *   clientId: "1234567890",
+ *   clientSecret: "0987654321"
+ * })
+ * ```
+ */
+export function GithubProvider(config: GithubConfig) {
   return Oauth2Provider({
     ...config,
     type: "github",