diff --git a/README.md b/README.md index 710f6e8..4a25fad 100644 --- a/README.md +++ b/README.md @@ -226,6 +226,112 @@ const config: CapacitorConfig = { export default config; ``` +## API + + + +* [`initialize(...)`](#initialize) +* [`signIn()`](#signin) +* [`refresh()`](#refresh) +* [`signOut()`](#signout) +* [Interfaces](#interfaces) + + + + + +### initialize(...) + +```typescript +initialize(options?: InitOptions) => void +``` + +Initializes the GoogleAuthPlugin, loading the gapi library and setting up the plugin. + +| Param | Type | Description | +| ------------- | --------------------------------------------------- | ---------------------------------- | +| **`options`** | InitOptions | - Optional initialization options. | + +**Since:** 3.1.0 + +-------------------- + + +### signIn() + +```typescript +signIn() => Promise +``` + +Initiates the sign-in process and returns a Promise that resolves with the user information. + +**Returns:** Promise<User> + +-------------------- + + +### refresh() + +```typescript +refresh() => Promise +``` + +Refreshes the authentication token and returns a Promise that resolves with the updated authentication details. + +**Returns:** Promise<Authentication> + +-------------------- + + +### signOut() + +```typescript +signOut() => Promise +``` + +Signs out the user and returns a Promise. + +**Returns:** Promise<any> + +-------------------- + + +### Interfaces + + +#### InitOptions + +| Prop | Type | Description | Default | Since | +| ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ----- | +| **`clientId`** | string | The app's client ID, found and created in the Google Developers Console. Common for Android or iOS. The default is defined in the configuration. | | 3.1.0 | +| **`scopes`** | string[] | Specifies the scopes required for accessing Google APIs The default is defined in the configuration. | | | +| **`grantOfflineAccess`** | boolean | Set if your application needs to refresh access tokens when the user is not present at the browser. In response use `serverAuthCode` key | false | 3.1.0 | + + +#### User + +| Prop | Type | Description | +| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------- | +| **`id`** | string | The unique identifier for the user. | +| **`email`** | string | The email address associated with the user. | +| **`name`** | string | The user's full name. | +| **`familyName`** | string | The family name (last name) of the user. | +| **`givenName`** | string | The given name (first name) of the user. | +| **`imageUrl`** | string | The URL of the user's profile picture. | +| **`serverAuthCode`** | string | The server authentication code. | +| **`authentication`** | Authentication | The authentication details including access, refresh and ID tokens. | + + +#### Authentication + +| Prop | Type | Description | +| ------------------ | ------------------- | ------------------------------------------------ | +| **`accessToken`** | string | The access token obtained during authentication. | +| **`idToken`** | string | The ID token obtained during authentication. | +| **`refreshToken`** | string | The refresh token. | + + + ## Migration guide #### Migrate from 3.2.x to 3.3.x diff --git a/package-lock.json b/package-lock.json index bbc952f..5bc80c5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,6 +12,7 @@ "@capacitor/android": "^5.0.4", "@capacitor/cli": "^5.0.4", "@capacitor/core": "^5.0.4", + "@capacitor/docgen": "^0.2.1", "@capacitor/ios": "^5.0.4", "@ionic/prettier-config": "^2.0.0", "@types/gapi": "0.0.42", @@ -73,6 +74,44 @@ "tslib": "^2.1.0" } }, + "node_modules/@capacitor/docgen": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/@capacitor/docgen/-/docgen-0.2.1.tgz", + "integrity": "sha512-COS5teC6n+EOSaBS7voHnIeIKH7owALnVoI1AhVArIWtBrc1JxSgkUuvLHpti4VGZdXdsrtp4yBPUwGm8WOZKA==", + "dev": true, + "dependencies": { + "@types/node": "^14.18.0", + "colorette": "^2.0.16", + "github-slugger": "^1.4.0", + "minimist": "^1.2.5", + "typescript": "~4.2.4" + }, + "bin": { + "docgen": "bin/docgen" + }, + "engines": { + "node": ">=14.5.0" + } + }, + "node_modules/@capacitor/docgen/node_modules/@types/node": { + "version": "14.18.63", + "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.63.tgz", + "integrity": "sha512-fAtCfv4jJg+ExtXhvCkCqUKZ+4ok/JQk01qDKhL5BDDoS3AxKXhV5/MAVUZyQnSEd2GT92fkgZl0pz0Q0AzcIQ==", + "dev": true + }, + "node_modules/@capacitor/docgen/node_modules/typescript": { + "version": "4.2.4", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.2.4.tgz", + "integrity": "sha512-V+evlYHZnQkaz8TRBuxTA92yZBPotr5H+WhQ7bD3hZUndx5tGOa1fuCgeSjxAzM1RiN5IzvadIXTVefuuwZCRg==", + "dev": true, + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=4.2.0" + } + }, "node_modules/@capacitor/ios": { "version": "5.0.4", "resolved": "https://registry.npmjs.org/@capacitor/ios/-/ios-5.0.4.tgz", @@ -360,6 +399,12 @@ "dev": true, "license": "MIT" }, + "node_modules/colorette": { + "version": "2.0.20", + "resolved": "https://registry.npmjs.org/colorette/-/colorette-2.0.20.tgz", + "integrity": "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==", + "dev": true + }, "node_modules/commander": { "version": "9.4.0", "dev": true, @@ -468,6 +513,12 @@ "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==", "dev": true }, + "node_modules/github-slugger": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-1.5.0.tgz", + "integrity": "sha512-wIh+gKBI9Nshz2o46B0B3f5k/W+WI9ZAv6y5Dn5WJ5SK1t0TnDimB4WE5rmTD05ZAIn8HALCZVmCsvj0w0v0lw==", + "dev": true + }, "node_modules/glob": { "version": "9.3.5", "resolved": "https://registry.npmjs.org/glob/-/glob-9.3.5.tgz", @@ -597,6 +648,15 @@ "url": "https://github.com/sponsors/isaacs" } }, + "node_modules/minimist": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz", + "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==", + "dev": true, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, "node_modules/minipass": { "version": "3.3.4", "dev": true, diff --git a/package.json b/package.json index 61ebe0d..149d4d1 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,8 @@ "watch": "tsc --watch", "prepublishOnly": "npm run build", "prepare": "tsc", - "test": "echo \"no test specified\"" + "test": "echo \"no test specified\"", + "docgen": "docgen --api GoogleAuthPlugin --output-readme README.md" }, "author": "CodetrixStudio", "license": "MIT", @@ -18,6 +19,7 @@ "@capacitor/android": "^5.0.4", "@capacitor/cli": "^5.0.4", "@capacitor/core": "^5.0.4", + "@capacitor/docgen": "^0.2.1", "@capacitor/ios": "^5.0.4", "@ionic/prettier-config": "^2.0.0", "@types/gapi": "0.0.42", @@ -64,4 +66,4 @@ "url": "https://github.com/CodetrixStudio/CapacitorGoogleAuth/issues" }, "prettier": "@ionic/prettier-config" -} +} \ No newline at end of file diff --git a/src/definitions.ts b/src/definitions.ts index 7ddfe61..517ed11 100644 --- a/src/definitions.ts +++ b/src/definitions.ts @@ -7,34 +7,68 @@ declare module '@capacitor/cli' { } export interface User { + /** + * The unique identifier for the user. + */ id: string; + + /** + * The email address associated with the user. + */ email: string; + /** - * @deprecated use `name` instead + * The user's full name. */ - displayName: string name: string; + + /** + * The family name (last name) of the user. + */ familyName: string; + + /** + * The given name (first name) of the user. + */ givenName: string; + + /** + * The URL of the user's profile picture. + */ imageUrl: string; + /** + * The server authentication code. + */ serverAuthCode: string; + + /** + * The authentication details including access, refresh and ID tokens. + */ authentication: Authentication; } export interface Authentication { + /** + * The access token obtained during authentication. + */ accessToken: string; + + /** + * The ID token obtained during authentication. + */ idToken: string; /** - * refreshToken only for iOS and Android + * The refresh token. + * @warning This property is applicable only for mobile platforms (iOS and Android). */ refreshToken?: string; } export interface GoogleAuthPluginOptions { /** - * The app's client ID, found and created in the Google Developers Console. + * The default app's client ID, found and created in the Google Developers Console. * common for Android or iOS * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com * @since 3.1.0 @@ -54,10 +88,10 @@ export interface GoogleAuthPluginOptions { androidClientId?: string; /** - * Scopes that you might need to request to access Google APIs + * Specifies the default scopes required for accessing Google APIs. * @example ["profile", "email"] - * @default [] - * @see @link https://developers.google.com/identity/protocols/oauth2/scopes + * @default ["email", "profile", "openid"] + * @see [Google OAuth2 Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) */ scopes?: string[]; @@ -75,7 +109,24 @@ export interface GoogleAuthPluginOptions { forceCodeForRefreshToken?: boolean; } -export interface InitOptions extends Pick { +export interface InitOptions { + /** + * The app's client ID, found and created in the Google Developers Console. + * Common for Android or iOS. + * The default is defined in the configuration. + * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com + * @since 3.1.0 + */ + clientId?: string; + + /** + * Specifies the scopes required for accessing Google APIs + * The default is defined in the configuration. + * @example ["profile", "email"] + * @see [Google OAuth2 Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) + */ + scopes?: string[]; + /** * Set if your application needs to refresh access tokens when the user is not present at the browser. * In response use `serverAuthCode` key @@ -83,17 +134,29 @@ export interface InitOptions extends Pick; + + /** + * Refreshes the authentication token and returns a Promise that resolves with the updated authentication details. + */ refresh(): Promise; - signOut(): Promise; /** - * Init hook for load gapi and init plugin - * @since 3.1.0 - * */ - initialize(options?: Partial): void; + * Signs out the user and returns a Promise. + */ + signOut(): Promise; }