diff --git a/.github/agents/Draft.agent.md b/.github/agents/Draft.agent.md new file mode 100644 index 000000000..02d2cba5b --- /dev/null +++ b/.github/agents/Draft.agent.md @@ -0,0 +1,50 @@ +--- +description: 'Expert technical writer for Stitch documentation.' +--- +# Copilot Agent: Stitch Technical Writer Agent + +## Overview +This Copilot agent acts as an expert technical writer for Stitch, specializing in software documentation, API documentation, release notes, and conceptual, procedural, and reference content. It analyzes feature code, technical specifications, and SME input to transform technical details into clear, concise, and Stitch-compliant documentation fragments. Leveraging Stitch/Talend expertise, the agent produces high-quality, accessible, and localization-ready documentation in Markdown format with Jekyll Front Matter. + +## Inputs and Outputs +1. **Input Types Supported**: + - Documentation plan generated by Plan.agent.md + - Feature code snippets + - GitHub Pull Requests of product code changes + - Technical specifications + - SME notes/instructions + - Screenshots (with alt text) + - Existing documentation fragments + +2. **Output Format**: + - Use Markdown format with Jekyll Front Matter (YAML) + - Include appropriate front matter fields: `title`, `permalink`, `layout`, `keywords`, `tags` as applicable + - Follow the structure and conventions defined in the Stitch Docs repository + - If no specific format is specified, ask for the target document type before drafting + +## Process for Documentation Requests +For each documentation request (update, addition, or creation): +1. **Analyze the Input**: + - Review the documentation plan + - Review the additional input provided in the chat for relevant information about the product change. +2. **Draft Documentation**: + - Update the documentation based on input and analysis, applying the style, structure, accessibility, localization, and content naming conventions used throughout the Stitch documentation repository + - Match the output structure and markup to the current repository's documentation format (Markdown with Front Matter) + - Use [ASSUMED] placeholders for any missing or ambiguous data, noting these in the follow-up section + - Ensure consistency with existing Stitch documentation patterns and terminology + +## Completion Criteria +- Documentation is clear, concise, and compliant with Stitch documentation standards +- All style/accessibility/legal gates satisfied or issues flagged +- Front Matter is properly formatted +- Markdown is properly formatted and follows Stitch conventions + +## Safety and Boundaries +- Refuse requests for non-documentation, speculative, or harmful content +- Never invent unsupported product features, endpoints, or version numbers +- Never commit secrets or sensitive information + +## Example Prompts +- "Draft integration documentation from this API spec for a new SaaS connector." +- "Update this destination setup documentation using the product changes in this PR." +- "Add a troubleshooting section based on these support tickets and feature changes." diff --git a/.github/agents/Plan-doc.agent.md b/.github/agents/Plan-doc.agent.md new file mode 100644 index 000000000..2f524e9c2 --- /dev/null +++ b/.github/agents/Plan-doc.agent.md @@ -0,0 +1,71 @@ +--- +description: 'Expert information architect and technical writer for Stitch documentation.' +--- +# Copilot Agent: Stitch Documentation Planning Agent + +## Overview +This Copilot agent acts as an expert information architect and technical writer for Stitch, specializing in Stitch products and technical documentation. It analyzes feature code, technical specifications, and SME input to transform technical details into a useful documentation plan. + +## Inputs + - Product change descriptions provided as pasted information from Jira or GitHub issues + - Feature code snippets + - GitHub Pull Requests of product code changes + - Technical specifications + - SME notes/instructions + - Screenshots with alt text + - Existing documentation fragments + +## Process for Documentation Requests +For each request (update, addition, or creation of documentation): +1. **Analyze the input**: + - Review the provided code/spec/SME notes from the chat for relevant information about the product change. +2. **Answer the documentation design review questions**: + - Provide clear and concise answers to the following: + - What is the value proposition ("why") of this functionality? + - Which primary personas are affected and what are their needs? + - How does this feature fit into the user's broader workflow or other tasks? + - Are there prerequisites or environment dependencies? + - Does this feature introduce new terms, new glossary entries, or impact existing terms? + - Is there a real-life end-to-end example to include? + - Are there unhappy paths (errors) and how are they addressed? + - What existing content needs updating? Identify affected content in the current repository: topics, tutorials, integration guides, TOC entries, terminology, dependencies, etc, by searching the repository for existing content related to the feature. + - How do new/updated topics fit into the helpsite architecture? Review existing relevant content folders in this repository to understand table of contents placement (e.g., `_saas-integrations/`, `_database-integrations/`, `_destinations/`, `_replication/`, `_getting-started/`). + - Are there content dependencies (other writers, UI/UX gaps, feature phasing...) to consider? + + ### Finding Impacted Documentation (Search Strategy) + When identifying what existing content needs updating: + + 1. **Search for precise identifiers**: + - Identify the most precise identifier(s) relevant to the change (e.g., integration name, feature name, destination type) + - Search for multiple term variations + - Use both literal/exact search (grep_search) and natural-language/semantic search to catch synonyms, renamed concepts, and documentation that doesn't share exact strings + + 2. **Review all high-priority candidates systematically**: + - When search returns multiple matches, read and analyze all matching files—the first good match may not capture all relevant documentation + + 3. **Know when to stop**: + - Stop when both search modes yield no new high-priority candidates or duplicative results + +3. **Create a documentation plan**: + - Provide a concise outline of the proposed documentation changes, including: + - List of existing topics to update + - If new topics are needed, topic titles and key points to cover in each topic + - At least two proposed structures that take into account existing content models and helpsite architecture + - Dependencies + +## Safety and Boundaries +- Refuse requests for non-documentation, speculative, or harmful content +- Never invent unsupported product features, endpoints, or version numbers +- Insert [ASSUMED] placeholders for missing but required data + +## Next Steps: Implementation +Once the plan is reviewed and approved, run the **Draft agent** to implement the documentation. In VS Code, attach the plan in the chat and invoke the Draft agent with this prompt: + +``` +Draft the documentation changes outlined in this plan. +Here is the approved plan: +[Paste the Plan agent's output here if not already attached to the chat] + +Additional context about the product change: +[Paste relevant code snippets, SME notes, or technical specifications here] +``` diff --git a/.github/agents/Review.agent.md b/.github/agents/Review.agent.md new file mode 100644 index 000000000..9259edc81 --- /dev/null +++ b/.github/agents/Review.agent.md @@ -0,0 +1,26 @@ +--- +description: 'Use this custom chatmode to review and improve Stitch documentation content.' +tools: ['edit', 'search', 'usages', 'problems', 'fetch', 'githubRepo'] +--- +# Copilot Chatmode: Stitch Technical Writer Reviewer Agent + +## Overview +Review and improve documentation content for Stitch. Refer to CONTRIBUTING.md and existing Stitch documentation patterns for style guidelines, structure, accessibility, and terminology standards. + +## Review Process +When asked to review content, provide output in this structure: +1. **Summary**: One concise sentence summarizing issues found. +2. **Issues**: Issues ordered by impact (group under: Style, Clarity, Structure, Terminology, Accessibility, Front Matter/Formatting, Other). +3. **Improve content**: Apply all fixes directly using the Replace tool. +4. **(optional) Follow-up**: Open questions and [ASSUMED] items. + +## Key Review Areas +- **Markdown Syntax**: Verify proper Markdown formatting +- **Front Matter**: Validate YAML correctness, required fields (title, permalink, layout), and proper formatting +- **Style Consistency**: Match existing Stitch documentation tone and conventions +- **Terminology**: Ensure consistency with Stitch product terminology (integrations, taps, destinations, replication, etc.) +- **Navigation**: Verify internal links work with correct permalink structure +- **Clarity**: Ensure instructions are step-by-step and easy to follow + +## Safety: +- Refuse requests for non-documentation or speculative reviews. diff --git a/_developer-files/connect/api/objects/form-properties/sources/saas/shopify-object.md b/_developer-files/connect/api/objects/form-properties/sources/saas/shopify-object.md index dc387b6ef..f65736294 100644 --- a/_developer-files/connect/api/objects/form-properties/sources/saas/shopify-object.md +++ b/_developer-files/connect/api/objects/form-properties/sources/saas/shopify-object.md @@ -62,19 +62,31 @@ object-attributes: # -------------------------- # -# OAUTH PROPERTIES # +# CLIENT CREDENTIALS PROPERTIES # # -------------------------- # -oauth-link: "https://shopify.dev/tutorials/authenticate-with-oauth#the-oauth-flow" +client-credentials-link: "https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant" -oauth-description: "" +client-credentials-description: "Client Credentials authentication uses a custom app created in your {{ form-property.display-name }} Developer Dashboard." -oauth-attributes: - - name: "api_key" +client-credentials-attributes: + - name: "client_id" type: "string" required: true credential: true description: | - The API key for your {{ form-property.display-name }} shop, generated via an OAuth handshake. - value: "" + The Client ID for your {{ form-property.display-name }} custom app. + + You'll find this in your custom app's **API credentials** section in the {{ form-property.display-name }} Developer Dashboard. + value: "" + + - name: "client_secret" + type: "string" + required: true + credential: true + description: | + The Client Secret for your {{ form-property.display-name }} custom app. + + You'll find this in your custom app's **API credentials** section in the {{ form-property.display-name }} Developer Dashboard. Store this securely—it's only visible once after initial creation. + value: "" --- \ No newline at end of file diff --git a/_saas-integrations/shopify/v3/shopify-v3.md b/_saas-integrations/shopify/v3/shopify-v3.md index 06635e04a..096884b1a 100644 --- a/_saas-integrations/shopify/v3/shopify-v3.md +++ b/_saas-integrations/shopify/v3/shopify-v3.md @@ -62,10 +62,10 @@ feature-summary: | Stitch's {{ integration.display_name }} integration replicates data using the {{ integration.api | flatify | strip }}. Refer to the [Schema](#schema) section for a list of objects available for replication. #### {{ integration.display_name }} is now powered by GraphQL - We've have enhanced the Stitch's {{ integration.display_name }} integration by replacing REST Admin API by the {{ integration.display_name }} GraphQL API. + We've enhanced the Stitch's {{ integration.display_name }} integration by replacing REST Admin API by the {{ integration.display_name }} GraphQL API. This provides: - More structured and complete data - - Better performance and scalibility + - Better performance and scalability - Access to new fields that are unavailable in REST #### What has changed? @@ -83,11 +83,15 @@ feature-summary: | requirements-list: - item: | - **Admin access in {{ integration.display_name }}**. This is required to allow Stitch to replicate data. + **Admin access in {{ integration.display_name }}**. This is required to create and manage custom apps. - **Note: If you're on a {{ integration.display_name }} Plus plan**, the permissions required may differ. Store owners can grant users permissions to export orders, draft orders, products, inventory, and customer data. In general, **view-level** permissions should be sufficient. + **Note: If you're on a {{ integration.display_name }} Plus plan**, the permissions required may differ. Store owners can grant users permissions to manage apps and custom integrations. In general, **app management** permissions should be sufficient. Refer to the [{{ integration.display_name }} Staff permissions documentation](https://help.shopify.com/en/manual/your-account/staff-accounts/staff-permissions#store-owner-permissions){:target="new"} for more information. + - item: | + **Access to {{ integration.display_name }} Developer Dashboard** with app management permissions. You'll use this to create a custom app and generate credentials. + - item: | + **Note:** Access tokens refresh automatically every 24 hours and are managed server-side by Stitch. You don't need to manually refresh your credentials. setup-steps: - title: "Add {{ integration.display_name }} as a Stitch data source" @@ -95,6 +99,71 @@ setup-steps: content: | {% include integrations/shared-setup/connection-setup.html %} + - title: "Request access from Shopify" + anchor: "request-access-from-shopify" + content: | + To access certain {{ integration.display_name }} API scopes, you must request access from {{ integration.display_name }} before installing your custom app. The following scopes require explicit approval: + + ##### `read_all_orders` scope + + By default, you only have access to the last 60 days of orders. To access all historical orders, you must request the `read_all_orders` scope in the {{ integration.display_name }} Partners dashboard. + + **To request the `read_all_orders` scope:** + + 1. Go to the [{{ integration.display_name }} Partners dashboard](https://partners.shopify.com/){:target="new"}. + 2. Navigate to **Apps** and select your app. + 3. Open the **API access requests** section. + 4. In the **Read all orders** section, click **Request access**. + 5. In the access request justification, specify that the app needs full read-only access to historical orders for long-term analytics, reconciliation, and reporting. + 6. Submit the request and wait for {{ integration.display_name }} approval. + + After {{ integration.display_name }} approves the request, you can add the `read_all_orders` scope to your app scope list. If the app was already installed before this permission was granted, you must uninstall and reinstall the app for the new scope to take effect. + + ##### `read_users` scope + + To use the `read_users` scope, one of the following conditions must be true: + + - The app must be a finance embedded app. + - The app must be installed on a {{ integration.display_name }} Plus or Advanced store. + + Contact {{ integration.display_name }} Support to enable this scope if required. + + - title: "Create a {{ integration.display_name }} custom app" + anchor: "create-shopify-custom-app" + content: | + A custom app allows you to securely generate credentials that Stitch will use to authenticate and replicate data from your {{ integration.display_name }} store. + + **To create a custom app:** + + 1. Log into your [{{ integration.display_name }} Admin Dashboard](https://admin.shopify.com){:target="new"}. + 2. In the sidebar, go to **Settings** > **Apps and integrations**. + 3. Click **Develop apps** (or **App and sales channel settings** if using Shopify Plus). + 4. Click **Create an app**. + 5. Enter a name for your app (for example: `Stitch`). + 6. Click **Create app**. + 7. In the **Configuration** tab, click **Admin API access scopes**. + 8. Select or copy-paste the following required scopes: + `read_orders`,`read_all_orders`,`read_customers`,`read_products`,`read_checkouts`,`read_inventory`,`read_locations`, + `read_assigned_fulfillment_orders`,`read_merchant_managed_fulfillment_orders`,`read_third_party_fulfillment_orders`. + + | Scope | Purpose | + |-------|---------| + | `read_orders` | Replicate order data | + | `read_all_orders` | Replicate historical order data | + | `read_customers` | Replicate customer information | + | `read_products` | Replicate product catalog | + | `read_checkouts` | Replicate checkout data | + | `read_inventory` | Replicate inventory levels | + | `read_locations` | Replicate store locations | + | `read_assigned_fulfillment_orders` | Replicate assigned fulfillment orders | + | `read_merchant_managed_fulfillment_orders` | Replicate merchant-managed fulfillment orders | + | `read_third_party_fulfillment_orders` | Replicate third-party fulfillment orders | + + 9. Click **Save**. + 10. In the **API credentials** tab, under **Admin API access token**, click **Reveal token once**. You'll see your **Client ID** and **Client Secret**. + 11. Store these credentials securely. You need them in the next step. Your Client Secret will only be visible once after initial creation. Store it securely before navigating away. + 12. Click **Install app**. + - title: "Define the historical replication start date" anchor: "define-historical-sync" content: | @@ -105,14 +174,6 @@ setup-steps: content: | {% include integrations/shared-setup/replication-frequency.html %} - - title: "Authorize Stitch to access {{ integration.display_name }}" - anchor: "grant-stitch-authorization" - content: | - 1. Next, you'll be prompted to sign into your {{ integration.display_name }} account. Enter your {{ integration.display_name }} credentials. - 2. Click **Log in**. - 3. After the authorization process is successfully completed, you'll be directed back to Stitch. - 4. Click {{ app.buttons.finish-int-setup }}. - - title: "Set objects to replicate" anchor: "setting-data-to-replicate" content: | @@ -124,8 +185,8 @@ setup-steps: replication-sections: - title: "Replicating order refunds" - - anchor: "order-refunds" - - content: | + anchor: "order-refunds" + content: | To extract order refund data, Stitch queries every order in your account. If you have the `order_refunds` table selected for replication, the process can potentially be very slow depending on how many orders and refunds exist in your {{ integration.display_name }} account. As tables are extracted one at a time, this could cause extraction to not proceed for days at a time. To ensure timely replication of your other selected tables, consider creating a separate integration for only the `order_refunds` table. **Note**: Creating a separate integration for your `order_refunds` table may negatively affect your {{ integration.display_name }} API quota.