@hellocoop/better-auth
Version:
Better Auth plugin for Hellō - https://hello.dev
402 lines (401 loc) • 14.3 kB
TypeScript
import * as z from 'zod';
import type { OAuth2Tokens, OAuth2UserInfo, OAuthProvider } from 'better-auth';
import type { GenericEndpointContext, User } from 'better-auth';
export { ContinueButton } from './button';
export { hellocoopClient } from './client';
/**
* Configuration interface for generic OAuth providers.
*/
export interface GenericOAuthConfig {
/** OAuth client ID */
clientId: string;
/** OAuth client secret */
clientSecret?: string;
/**
* Array of OAuth scopes to request.
* @default ["openid", "profile"]
*/
scopes?: string[];
/**
* Custom redirect URI.
* If not provided, a default URI will be constructed.
*/
redirectURI?: string;
/**
* OAuth response type.
* @default "code"
*/
responseType?: string;
/**
* The response mode to use for the authorization code request.
*/
responseMode?: 'query' | 'form_post';
/**
* Prompt parameter for the authorization request.
* Controls the authentication experience for the user.
*/
prompt?: 'login' | 'consent';
/**
* Whether to use PKCE (Proof Key for Code Exchange)
* @default true
*/
pkce?: boolean;
/**
* URL for the authorization endpoint.
*/
authorizationUrl?: string;
/**
* URL for the token endpoint.
*/
tokenUrl?: string;
/**
* URL for the user info endpoint.
*/
userInfoUrl?: string;
/**
* Access type for the authorization request.
* Use "offline" to request a refresh token.
*/
accessType?: string;
/**
* Custom function to fetch user info.
* If provided, this function will be used instead of the default user info fetching logic.
* @param tokens - The OAuth tokens received after successful authentication
* @returns A promise that resolves to a User object or null
*/
getUserInfo?: (tokens: OAuth2Tokens) => Promise<OAuth2UserInfo | null>;
/**
* Custom function to map the user profile to a User object.
*/
mapProfileToUser?: (profile: Record<string, any>) => Partial<Partial<User>> | Promise<Partial<User>>;
/**
* Additional search-params to add to the authorizationUrl.
* Warning: Search-params added here overwrite any default params.
*/
authorizationUrlParams?: Record<string, string> | ((ctx: GenericEndpointContext) => Record<string, string>);
/**
* Additional search-params to add to the tokenUrl.
* Warning: Search-params added here overwrite any default params.
*/
tokenUrlParams?: Record<string, string> | ((ctx: GenericEndpointContext) => Record<string, string>);
/**
* Disable implicit sign up for new users. When set to true for the provider,
* sign-in need to be called with with requestSignUp as true to create new users.
*/
disableImplicitSignUp?: boolean;
/**
* Disable sign up for new users.
*/
disableSignUp?: boolean;
/**
* Authentication method for token requests.
* @default "post"
*/
authentication?: 'basic' | 'post';
/**
* Override user info with the provider info.
*
* This will update the user info with the provider info,
* when the user signs in with the provider.
* @default true (for HelloCoop to ensure claims are updated)
*/
overrideUserInfo?: boolean;
/**
* URL to fetch OAuth 2.0 configuration.
* If provided, the authorization and token endpoints will be fetched from this URL.
*/
discoveryUrl?: string;
/**
* Custom headers to include in the discovery request.
* Useful for providers like Epic that require specific headers (e.g., Epic-Client-ID).
*/
discoveryHeaders?: Record<string, string>;
/**
* Custom headers to include in the authorization request.
* Useful for providers like Qonto that require specific headers (e.g., X-Qonto-Staging-Token for local development).
*/
authorizationHeaders?: Record<string, string>;
/**
* Unique identifier for the OAuth provider
*/
providerId?: string;
/**
* Default callback URL to redirect to after sign in.
* Can be overridden in signInWithHello calls.
* @default "/"
*/
callbackURL?: string;
/**
* Default error callback URL to redirect to if an error occurs.
* Can be overridden in signInWithHello calls.
* @default "/error"
*/
errorCallbackURL?: string;
/**
* Default login hint for which user account to use.
* Can be overridden in signInWithHello calls.
* @see https://www.hello.dev/docs/oidc/request/#openid-connect-parameters
*/
loginHint?: string;
/**
* Default provider hint - space separated list of preferred providers to show new users.
* Can be overridden in signInWithHello calls.
* @default "apple/microsoft" depending on OS and "google email"
* @see https://www.hello.dev/docs/apis/wallet/#provider_hint
*/
providerHint?: string;
/**
* Default domain hint for which domain or type of account to use.
* Can be overridden in signInWithHello calls.
* @see https://www.hello.dev/docs/oidc/request/#hell%C5%8D-parameters
*/
domainHint?: string;
}
interface GenericOAuthOptions {
/**
* OAuth provider configuration for HelloCoop.
*/
config: GenericOAuthConfig;
}
/**
* A generic OAuth plugin that can be used to add OAuth support to any provider
*/
export declare const hellocoop: (options: GenericOAuthOptions) => {
id: "hellocoop";
schema: {
user: {
fields: {
nickname: {
type: string;
required: boolean;
};
ethereum: {
type: string;
required: boolean;
};
phone: {
type: string;
required: boolean;
};
phone_number: {
type: string;
required: boolean;
};
phone_verified: {
type: string;
required: boolean;
};
phone_number_verified: {
type: string;
required: boolean;
};
github: {
type: string;
required: boolean;
};
gitlab: {
type: string;
required: boolean;
};
twitter: {
type: string;
required: boolean;
};
discord: {
type: string;
required: boolean;
};
family_name: {
type: string;
required: boolean;
};
given_name: {
type: string;
required: boolean;
};
tenant: {
type: string;
required: boolean;
};
};
};
};
init: (ctx: import("better-auth").AuthContext) => {
context: {
socialProviders: OAuthProvider<Record<string, any>, Partial<import("better-auth").ProviderOptions<any>>>[];
};
};
endpoints: {
/**
* ### Endpoint
*
* POST `/sign-in/oauth2`
*
* ### API Methods
*
* **server:**
* `auth.api.signInWithOAuth2`
*
* **client:**
* `authClient.signIn.oauth2`
*
* @see [Read our docs to learn more.](https://better-auth.com/docs/plugins/sign-in#api-method-sign-in-oauth2)
*/
hellocoopSignIn: {
<AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
body: {
callbackURL?: string | undefined;
errorCallbackURL?: string | undefined;
newUserCallbackURL?: string | undefined;
disableRedirect?: boolean | undefined;
scopes?: string[] | undefined;
requestSignUp?: boolean | undefined;
prompt?: string | undefined;
providerHint?: string | undefined;
domainHint?: string | undefined;
loginHint?: string | undefined;
};
} & {
method?: "POST" | undefined;
} & {
query?: Record<string, any> | undefined;
} & {
params?: Record<string, any>;
} & {
request?: Request;
} & {
headers?: HeadersInit;
} & {
asResponse?: boolean;
returnHeaders?: boolean;
use?: import("better-call").Middleware[];
path?: string;
} & {
asResponse?: AsResponse | undefined;
returnHeaders?: ReturnHeaders | undefined;
}): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
headers: Headers;
response: {
url: string;
redirect: boolean;
};
} : {
url: string;
redirect: boolean;
}>;
options: {
method: "POST";
body: z.ZodObject<{
callbackURL: z.ZodOptional<z.ZodString>;
errorCallbackURL: z.ZodOptional<z.ZodString>;
newUserCallbackURL: z.ZodOptional<z.ZodString>;
disableRedirect: z.ZodOptional<z.ZodBoolean>;
scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
requestSignUp: z.ZodOptional<z.ZodBoolean>;
prompt: z.ZodOptional<z.ZodString>;
providerHint: z.ZodOptional<z.ZodString>;
domainHint: z.ZodOptional<z.ZodString>;
loginHint: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
metadata: {
openapi: {
description: string;
responses: {
200: {
description: string;
content: {
'application/json': {
schema: {
type: "object";
properties: {
url: {
type: string;
};
redirect: {
type: string;
};
};
};
};
};
};
};
};
};
} & {
use: any[];
};
path: "/hellocoop/sign-in";
};
oAuth2Callback: {
<AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
body?: undefined;
} & {
method?: "GET" | undefined;
} & {
query: {
code?: string | undefined;
error?: string | undefined;
error_description?: string | undefined;
state?: string | undefined;
};
} & {
params?: Record<string, any>;
} & {
request?: Request;
} & {
headers?: HeadersInit;
} & {
asResponse?: boolean;
returnHeaders?: boolean;
use?: import("better-call").Middleware[];
path?: string;
} & {
asResponse?: AsResponse | undefined;
returnHeaders?: ReturnHeaders | undefined;
}): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
headers: Headers;
response: void;
} : void>;
options: {
method: "GET";
query: z.ZodObject<{
code: z.ZodOptional<z.ZodString>;
error: z.ZodOptional<z.ZodString>;
error_description: z.ZodOptional<z.ZodString>;
state: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
metadata: {
client: boolean;
openapi: {
description: string;
responses: {
200: {
description: string;
content: {
'application/json': {
schema: {
type: "object";
properties: {
url: {
type: string;
};
};
};
};
};
};
};
};
};
} & {
use: any[];
};
path: "/hellocoop/callback";
};
};
$ERROR_CODES: {
readonly INVALID_OAUTH_CONFIGURATION: "Invalid OAuth configuration";
};
};
//# sourceMappingURL=index.d.ts.map