Review: docs fixes

raycast · Jan 10, 2024 · c414a4e · c414a4e
1 parent d32f113
commit c414a4e
Show file tree

Hide file tree

Showing 4 changed files with 55 additions and 82 deletions.
diff --git a/docs/utils-reference/oauth/OAuthService.md b/docs/utils-reference/oauth/OAuthService.md
@@ -50,25 +50,19 @@ const accessToken = await oauthService.authorize();
 
 ### Built-in Services
 
-Some 3rd-party providers are exposed by default to make it easy to authenticate with them. Here's the full list:
+Some services are exposed by default to make it easy to authenticate with them. Here's the full list:
 
-- Asana
-- GitHub
-- Google
-- Jira
-- Linear
-- Slack
-- Zoom
+- [Asana](#asana)
+- [GitHub](#github)
+- [Google](#google)
+- [Jira](#jira)
+- [Linear](#linear)
+- [Slack](#slack)
+- [Zoom](#zoom)
 
-#### Asana
-
-##### Signature
+These services are all instances of `OAuthService` with the default options being set. However, you're free to configure your own client ID, and URLs for a specific service.
 
-```ts
-const asana: OAuthService
-```
-
-##### Example
+#### Asana
 
 ```tsx
 const asana = OAuthService.asana({
@@ -80,14 +74,6 @@ const asana = OAuthService.asana({
 
 #### GitHub
 
-##### Signature
-
-```ts
-const github: OAuthService
-```
-
-##### Example
-
 ```tsx
 const github = OAuthService.github({
   clientId: 'custom-client-id', // Optional: If omitted, defaults to a pre-configured client ID
@@ -98,14 +84,6 @@ const github = OAuthService.github({
 
 #### Google
 
-##### Signature
-
-```ts
-const google: OAuthService
-```
-
-##### Example
-
 ```tsx
 const google = OAuthService.google({
   clientId: 'custom-client-id', // Optional: If omitted, defaults to a pre-configured client ID
@@ -116,14 +94,6 @@ const google = OAuthService.google({
 
 #### Jira
 
-##### Signature
-
-```ts
-const jira: OAuthService
-```
-
-##### Example
-
 ```tsx
 const jira = OAuthService.jira({
   clientId: 'custom-client-id', // Optional: If omitted, defaults to a pre-configured client ID
@@ -134,14 +104,6 @@ const jira = OAuthService.jira({
 
 #### Linear
 
-##### Signature
-
-```ts
-const linear: OAuthService
-```
-
-##### Example
-
 ```tsx
 const linear = OAuthService.linear({
   clientId: 'custom-client-id', // Optional: If omitted, defaults to a pre-configured client ID
@@ -152,14 +114,6 @@ const linear = OAuthService.linear({
 
 #### Slack
 
-##### Signature
-
-```ts
-const slack: OAuthService
-```
-
-##### Example
-
 ```tsx
 const slack = OAuthService.slack({
   clientId: 'custom-client-id', // Optional: If omitted, defaults to a pre-configured client ID
@@ -170,14 +124,6 @@ const slack = OAuthService.slack({
 
 #### Zoom
 
-##### Signature
-
-```ts
-const zoom: OAuthService
-```
-
-##### Example
-
 ```tsx
 const zoom = OAuthService.zoom({
   clientId: 'custom-client-id', // Optional: If omitted, defaults to a pre-configured client ID
@@ -222,12 +168,12 @@ Here's an updated markdown table with a "Type" column:
 
 | Property Name | Description | Type |
 |---------------|-------------|------|
-| `client` | The PKCE Client defined using `OAuth.PKCEClient` from `@raycast/api` | `OAuth.PKCEClient` |
-| `clientId` | The app's client ID | `string` |
-| `scope` | The scope of the access requested from the provider | `string` |
-| `authorizeUrl` | The URL to start the OAuth flow | `string` |
-| `tokenUrl` | The URL to exchange the authorization code for an access token | `string` |
-| `refreshTokenUrl` | (Optional) The URL to refresh the access token if applicable | `string` |
-| `personalAccessToken` |  (Optional) A personal token if the provider supports it | `string` |
-| `extraParameters` | (Optional) The extra parameters you may need for the authorization request | `Record<string, string>` |
-| `bodyEncoding` | (Optional) Specifies the format for sending the body of the request. | `json` \| `url-encoded`  |
+| client<mark style="color:red;">*</mark> | The PKCE Client defined using `OAuth.PKCEClient` from `@raycast/api` | `OAuth.PKCEClient` |
+| clientId<mark style="color:red;">*</mark> | The app's client ID | `string` |
+| scope<mark style="color:red;">*</mark> | The scope of the access requested from the provider | `string` |
+| authorizeUrl<mark style="color:red;">*</mark> | The URL to start the OAuth flow | `string` |
+| tokenUrl<mark style="color:red;">*</mark> | The URL to exchange the authorization code for an access token | `string` |
+| refreshTokenUrl | The URL to refresh the access token if applicable | `string` |
+| personalAccessToken | A personal token if the provider supports it | `string` |
+| extraParameters | The extra parameters you may need for the authorization request | `Record<string, string>` |
+| bodyEncoding | Specifies the format for sending the body of the request. | `json` \| `url-encoded`  |
diff --git a/docs/utils-reference/oauth/withAccessToken.md b/docs/utils-reference/oauth/withAccessToken.md
@@ -15,10 +15,10 @@ function withAccessToken<T>(
 ### Arguments
 
 `options` is an object containing:
-- `options.authorize` is a promise that initiates the OAuth token retrieval process and resolves to a token string.
+- `options.authorize` is a function that initiates the OAuth token retrieval process. It returns a promise that resolves to an access token.
 - `options.personalAccessToken` is an optional string that represents an already obtained personal access token. When `options.personalAccessToken` is provided, it uses that token. Otherwise, it calls `options.authorize` to fetch an OAuth token asynchronously.
-- `options.client` is an optional instance of a PKCE Client that you can create using Raycast API.
-- `options.onAuthorize` is an optional callback function that is called once the user has been properly logged in through OAuth. This function is called with the `token`, its type (whether it comes from an OAuth flow or if it's a personal access token) and an `idToken` if `options.client` is provided.
+- `options.client` is an optional instance of a PKCE Client that you can create using Raycast API. This client is used to return the `idToken` as part of the `onAuthorize` callback below.
+- `options.onAuthorize` is an optional callback function that is called once the user has been properly logged in through OAuth. This function is called with the `token`, its type (whether it comes from an OAuth flow or if it's a personal access token) and an `idToken` if `options.client` is provided and if it's returned in the initial token set.
 
 ### Return
 
@@ -30,6 +30,10 @@ Note that the access token isn't injected into the wrapped component props. Inst
 
 ## Example
 
+
+{% tabs %}
+{% tab title="view.tsx" %}
+
 ```tsx
 import { Detail } from "@raycast/api";
 import { withAccessToken } from "@raycast/utils";
@@ -42,7 +46,9 @@ function AuthorizedComponent(props) {
 export default withAccessToken({ authorize })(AuthorizedComponent);
 ```
 
-Note that it also works for `no-view` commands as stated above:
+{% endtab %}
+
+{% tab title="no-view.tsx" %}
 
 ```tsx
 import { Detail } from "@raycast/api";
@@ -56,6 +62,9 @@ async function AuthorizedCommand() {
 export default withAccessToken({ authorize })(AuthorizedCommand);
 ```
 
+{% endtab %}
+{% endtabs %}
+
 ## Types
 
 ### WithAccessTokenParameters

diff --git a/src/oauth/OAuthService.ts b/src/oauth/OAuthService.ts
@@ -15,12 +15,12 @@ export interface OAuthServiceOptions {
   client: OAuth.PKCEClient;
   clientId: string;
   scope: string;
-  personalAccessToken?: string;
-  bodyEncoding?: "json" | "url-encoded";
-  extraParameters?: Record<string, string>;
   authorizeUrl: string;
   tokenUrl: string;
   refreshTokenUrl?: string;
+  personalAccessToken?: string;
+  bodyEncoding?: "json" | "url-encoded";
+  extraParameters?: Record<string, string>;
   onAuthorize?: (params: OnAuthorizeParams) => void;
 }
 

diff --git a/src/oauth/withAccessToken.tsx b/src/oauth/withAccessToken.tsx
@@ -14,9 +14,27 @@ let type: OAuthType | null = null;
 let authorize: { read(): string } | null = null;
 
 type WithAccessTokenParameters = {
+  /**
+   * An optional instance of a PKCE Client that you can create using Raycast API.
+   * This client is used to return the `idToken` as part of the `onAuthorize` callback.
+   */
   client?: OAuth.PKCEClient;
+  /**
+   * A function that initiates the OAuth token retrieval process
+   * @returns a promise that resolves to an access token.
+   */
   authorize: () => Promise<string>;
+  /**
+   * An optional string that represents an already obtained personal access token
+   */
   personalAccessToken?: string;
+  /**
+   * An optional callback function that is called once the user has been properly logged in through OAuth.
+   * @param {object} params - Parameters of the callback
+   * @param {string} options.token - The retrieved access token
+   * @param {string} options.type - The access token's type (either `oauth` or `personal`)
+   * @param {string} options.idToken - The optional id token. The `idToken` is returned if `options.client` is provided and if it's returned in the initial token set.
+   */
   onAuthorize?: (params: OnAuthorizeParams) => void;
 };
 
@@ -42,9 +60,9 @@ type WithAccessTokenParameters = {
  * export default withAccessToken(github)(AuthorizedComponent);
  * ```
  *
- * @param {object} options - Configuration options for the token acquisition.
+ * @param {object} options - Configuration options for the token retrieval.
  * @param {() => Promise<string>} options.authorize - A function to retrieve an OAuth token.
- * @param {string} [options.personalAccessToken] - An optional personal access token.
+ * @param {string} options.personalAccessToken - An optional personal access token.
  * @returns {React.ComponentType<T>} The wrapped component.
  */
 export function withAccessToken<T>(