docs(source-typeform): improve setup guide, prerequisites, and performance documentation (#75510)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: bot_apk <apk@cognition.ai>

Author: devin-ai-integration[bot]

docs/integrations/sources/typeform.md

@@ -1,23 +1,15 @@
 # Typeform
 
-This page guides you through the process of setting up the Typeform source connector.
+This page contains the setup guide and reference information for the [Typeform](https://www.typeform.com/) source connector.
 
 ## Prerequisites
 
-- [Typeform Account](https://www.typeform.com/)
-- Form IDs (Optional) - If you want to sync data for specific forms, you'll need to have the IDs of those forms. If you want to sync data for all forms in your account you don't need any IDs. Form IDs can be found in the URLs to the forms in Typeform Admin Panel (for example, for URL `https://admin.typeform.com/form/12345/` a `12345` part would your Form ID)
-  <!-- env:cloud -->
-
-  **For Airbyte Cloud:**
-
-- OAuth
+- A [Typeform](https://www.typeform.com/) account
+<!-- env:cloud -->
+- For Airbyte Cloud: OAuth authentication
 <!-- /env:cloud -->
-
 <!-- env:oss -->
-
-**For Airbyte Open Source:**
-
-- Personal Access Token (see [personal access token](https://www.typeform.com/developers/get-started/personal-access-token/))
+- For Airbyte Open Source: A Typeform [personal access token](https://www.typeform.com/developers/get-started/personal-access-token/) with the following read scopes: `forms:read`, `responses:read`, `webhooks:read`, `workspaces:read`, `images:read`, and `themes:read`
 <!-- /env:oss -->
 
 ## Setup guide
@@ -27,21 +19,24 @@ This page guides you through the process of setting up the Typeform source conne
 <!-- env:oss -->
 
 **For Airbyte Open Source:**
-To get the API token for your application, follow these [steps](https://developer.typeform.com/get-started/personal-access-token/):
 
-1. Log in to your account at Typeform.
-2. In the upper-right corner, in the drop-down menu next to your profile photo, click **My Account**.
+To generate a personal access token for your Typeform account:
+
+1. Log in to your [Typeform](https://www.typeform.com/) account.
+2. In the upper-left corner, in the drop-down menu next to your username, click **Account**.
 3. In the left menu, click **Personal tokens**.
 4. Click **Generate a new token**.
 5. In the **Token name** field, type a name for the token to help you identify it.
-6. Choose the scopes you need (API actions this token can perform). See [OAuth 2.0 scopes](https://www.typeform.com/developers/get-started/scopes/) for more details.
+6. Select the following scopes: `forms:read`, `responses:read`, `webhooks:read`, `workspaces:read`, `images:read`, and `themes:read`. See [OAuth scopes](https://www.typeform.com/developers/get-started/scopes/) for details.
 7. Click **Generate token**.
+
 <!-- /env:oss -->
 
 <!-- env:cloud -->
 
 **For Airbyte Cloud:**
-This step is not needed in Airbyte Cloud. Skip to the next step.
+
+Skip this step. Airbyte Cloud uses OAuth to authenticate with Typeform.
 
 <!-- /env:cloud -->
 
@@ -54,11 +49,11 @@ This step is not needed in Airbyte Cloud. Skip to the next step.
 1. [Log into your Airbyte Cloud](https://cloud.airbyte.com/workspaces) account.
 2. In the left navigation bar, click **Sources**. In the top-right corner, click **+ New Source**.
 3. On the source setup page, select **Typeform** from the Source type dropdown and enter a name for this connector.
-4. Click `Authenticate your Typeform account` by selecting Oauth or Personal Access Token for Authentication.
-5. Log in and Authorize to the Typeform account.
-6. **Start date (Optional)** - The date from which to start fetching Responses stream data, in the format `YYYY-MM-DDT00:00:00Z`. If not set, the Responses stream fetches data from one year ago.
-7. **Form IDs (Optional)** - List of Form IDs to sync. If not specified, all forms in your account are synced.
-8. Click **Set up source**.
+4. Click **Authenticate your Typeform account** and complete the OAuth flow.
+5. **Start date** (Optional) - The date from which you want to replicate data for the Responses stream, in the format `YYYY-MM-DDT00:00:00Z`. If not set, the connector fetches response data from one year before the current date.
+6. **Form IDs** (Optional) - IDs of specific forms to sync. If not specified, the connector syncs all forms in your account. You can find form IDs in your form URLs on the **Share** panel. For example, in the URL `https://mysite.typeform.com/to/u6nXL7`, the form ID is `u6nXL7`.
+7. Click **Set up source**.
+
 <!-- /env:cloud -->
 
 <!-- env:oss -->
@@ -67,15 +62,18 @@ This step is not needed in Airbyte Cloud. Skip to the next step.
 
 1. Go to your local Airbyte instance.
 2. In the left navigation bar, click **Sources**. In the top-right corner, click **+ New Source**.
-3. On the Set up the source page, enter a name for the connector and select **Typeform** from the Source type dropdown.
-4. Enter your **API Token** and optionally set a **Start Date**.
-5. Click **Set up source**.
+3. On the source setup page, enter a name for the connector and select **Typeform** from the Source type dropdown.
+4. Enter your personal access token in the **API Token** field.
+5. **Start date** (Optional) - The date from which you want to replicate data for the Responses stream, in the format `YYYY-MM-DDT00:00:00Z`. If not set, the connector fetches response data from one year before the current date.
+6. **Form IDs** (Optional) - IDs of specific forms to sync. If not specified, the connector syncs all forms in your account. You can find form IDs in your form URLs on the **Share** panel. For example, in the URL `https://mysite.typeform.com/to/u6nXL7`, the form ID is `u6nXL7`.
+7. Click **Set up source**.
+
 <!-- /env:oss -->
 
 ## Supported streams and sync modes
 
 | Stream     | Key         | Incremental | API Link                                                                    |
-| :--------- | ----------- | :---------- | --------------------------------------------------------------------------- |
+| :--------- | :---------- | :---------- | :-------------------------------------------------------------------------- |
 | Forms      | id          | No          | https://developer.typeform.com/create/reference/retrieve-form/              |
 | Responses  | response_id | Yes         | https://developer.typeform.com/responses/reference/retrieve-responses       |
 | Webhooks   | id          | No          | https://developer.typeform.com/webhooks/reference/retrieve-webhooks/        |
@@ -85,14 +83,14 @@ This step is not needed in Airbyte Cloud. Skip to the next step.
 
 ## Performance considerations
 
-Typeform API page size limit per source:
+The Typeform API enforces a rate limit of 2 requests per second per account. The connector respects this limit automatically. For more information, see the [Typeform API rate limits documentation](https://developer.typeform.com/get-started/#rate-limits).
 
-- Forms - 200
-- Responses - 1000
+Page size limits per stream:
 
-The connector performs an additional API call to fetch all form IDs in your account using the [retrieve forms endpoint](https://developer.typeform.com/create/reference/retrieve-forms/).
+- Forms: 200
+- Responses: 1000
 
-API rate limits \(2 requests per second\): [https://developer.typeform.com/get-started/\#rate-limits](https://developer.typeform.com/get-started/#rate-limits)
+The connector makes an additional API call per sync to fetch the list of form IDs in your account using the [retrieve forms endpoint](https://developer.typeform.com/create/reference/retrieve-forms/).
 
 ## Changelog