feat(oauth): allow customizing provider display metadata

[smorin]

What

Add optional providerName and description fields to the shared options for every built-in OAuthService provider.

Each built-in provider passes these values to its internally constructed OAuth.PKCEClient. When an extension omits either field, the provider keeps its existing name and connection description.

Why

PR #80 added providerId so an extension can keep separate token storage for multiple logins to the same OAuth provider. The built-in provider factories still hard-code the name and description shown by Raycast, so users cannot tell which account, workspace, or site they are connecting.

Extensions currently have to construct OAuth.PKCEClient and OAuthService manually to retain that context. That workaround duplicates provider configuration, including URLs, client defaults, and icons, which can drift from @raycast/utils.

Exposing the two display fields completes the multi-login use case without coupling the API to Linear or to a specific account model. For example, a Linear extension can keep tokens isolated with providerId while identifying the workspace in the authorization UI:

OAuthService.linear({
  scope: "read write",
  providerId: "linear-acme",
  providerName: "Linear — Acme",
  description: "Connect to Acme as you@acme.com",
});

How

• Define providerName?: string and description?: string on the shared provider options.
• Pass both fields to all seven built-in OAuth.PKCEClient instances.
• Use nullish fallback so existing callers retain the exact current defaults.
• Test default values, combined overrides, and independent overrides for every built-in provider.
• Document the new fields and the multi-workspace example.

Verification

• npm test — 50 tests passed across 7 test files
• npm run lint — 0 errors
• npm run build — production bundle and declarations built successfully

[smorin]

@0xdhrv Have a new PR here to address the needs of raycast/extensions#24297

[Copilot]

🟡 Changes recommended

The updated OAuthService documentation contains multiple type/signature inaccuracies (e.g., onAuthorize type, provider option scope type, and Linear signature) that should be corrected before release.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR extends the built-in OAuthService.* provider factories to allow extensions to override the OAuth UI display metadata (provider name and connection description) while preserving existing defaults for callers that omit the new fields.

Changes:

• Adds providerName?: string and description?: string to the shared provider options type.
• Threads providerName/description through all seven built-in providers when constructing OAuth.PKCEClient, using nullish fallback to keep existing defaults.
• Expands the built-in-provider test matrix and updates OAuthService documentation with a multi-login example.

File summaries

File	Description
test/OAuthService.test.ts	Extends table tests to assert default and overridden PKCE client display metadata across all built-in providers.
src/oauth/types.ts	Adds providerName and description to the shared provider options type.
src/oauth/OAuthService.ts	Passes providerName/description overrides into each built-in provider’s OAuth.PKCEClient with backward-compatible defaults.
docs/utils-reference/oauth/OAuthService.md	Documents the new fields and provides a multi-workspace Linear example.

Review details

Suppressed comments (2)

docs/utils-reference/oauth/OAuthService.md:239

• ProviderWithDefaultClientOptions scope is documented as string | Array<string>, but the exported ProviderWithDefaultClientOptions type uses BaseProviderOptions.scope: string. The docs should match the actual built-in provider factory option type.

| scope<mark style="color:red;">\*</mark> | The scope of the access requested from the provider                                                                                                                                                                                                  | `string` \| `Array<string>`                  |

docs/utils-reference/oauth/OAuthService.md:249

• In the ProviderWithDefaultClientOptions table, onAuthorize is documented as type string, but in the source types it is a callback: onAuthorize?: (params: OnAuthorizeParams) => void (see src/oauth/types.ts).

| onAuthorize                             | A callback function that is called once the user has been properly logged in through OAuth when used with `withAccessToken`                                                                                                                          | `string`                                     |

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[smorin]

@mathieudutour Have a followup to #80