Feature: Add support for Nango

README.md

@@ -221,6 +221,7 @@ By creating a `.cursorrules` file in your project's root directory, you can leve
 - [Next.js (Type LLM)](./rules/next-type-llm/.cursorrules)
 - [Unity (C#)](./rules/unity-cursor-ai-c-cursorrules-prompt-file/.cursorrules)
 - [Web App Optimization](./rules/web-app-optimization-cursorrules-prompt-file/.cursorrules)
+- [Nango Integration Best Practices](./rules/nango-cursorrules-prompt-file/.cursorrules)
 
 ### Utilities
 

rules/nango-cursorrules-prompt-file/.cursorrules

@@ -0,0 +1,3 @@
+# Persona
+
+You are a top tier integrations engineer. You are methodical, pragmatic and systematic in how you write integration scripts. You follow best practices and look carefully at existing patterns and coding styles in this existing project. You will always attempt to test your work by using the "dryrun" command, and will use a connection if provided to test or will discover a valid connection by using the API to fetch one. You always run the available commands to ensure your work compiles, lints successfully and has a valid nango.yaml.

rules/nango-cursorrules-prompt-file/README.md

@@ -0,0 +1,37 @@
+# Nango integrations .cursorrules prompt file
+
+Author: Ayodeji Adeoti
+
+## What you can build
+
+**Third-Party Integrations**: Build integrations with popular platforms like Salesforce, HubSpot, Notion, or Google Calendar using Nango’s unified APIs and OAuth support. The AI can help scaffold authentication flows, map API responses to unified models, and handle pagination, retries, and webhooks.
+
+**Data Sync**: Create sync scripts that sync data from third-party providers into your application using Nango’s incremental sync and full sync strategies. Automatically manage scheduling, error handling, and data freshness.
+
+**Provider-Specific Connectors**: Develop custom integration logic for providers not yet natively supported by Nango. The prompt can help generate clean, reusable connector code that wraps external APIs into Nango's integration flow.
+
+**Multi-Tenant Integration Flows**: Build integration logic that works across many tenants while preserving isolation and secure token storage, using Nango’s multi-connection handling. The prompt ensures correct handling of auth, error isolation, and scoped data flow.
+
+**Integration Documentation**: Generate clear, user-friendly documentation for setting up, using, and troubleshooting integrations built on Nango. This includes connection instructions, expected data fields, sync frequency, and webhook behavior.
+
+**Integration SDKs**: Build SDKs that wrap Nango’s API for specific use cases or platforms (e.g., Node.js, Python, Ruby), offering developers a seamless developer experience when connecting to Nango.
+
+
+## Benefits
+
+**10x Developer Persona**: The prompt assumes the role of an experienced integration engineer, offering deep insights into structuring scalable, secure, and reliable integrations across multiple platforms using Nango.
+
+**Minimal Code Alteration**: Promotes surgical, efficient changes that maintain clarity and avoid unnecessary complexity, reducing long-term maintenance cost.
+
+**Key Mindsets Focus**: Focuses on correctness, simplicity, observability, and clarity—ensuring that every integration is built with maintainability and robustness in mind.
+
+## Synopsis
+
+This prompt benefits developers building integrations on Nango by accelerating development, promoting best practices, and generating relevant, high-quality documentation alongside the code.
+
+## Overview of .cursorrules prompt
+
+The `.cursorrules` file outlines principles for a senior engineer building third-party integrations with Nango. Key mindsets include clarity, resilience, maintainability, and correctness. Coding practices emphasize OAuth handling, sync lifecycle management, secure token flows, and normalized data structures. The prompt encourages thoughtful use of TODO comments for edge cases, promotes testing early in the integration lifecycle, and pushes for lightweight abstractions. It also recommends generating setup and usage documentation in parallel with code, ensuring the final product is not only functional but easy to understand and deploy.
+
+
+For more details on best practices for custom Nango integrations, refer to the [Nango Best Practices Guide](https://github.com/NangoHQ/integration-templates/tree/main/guides).

rules/nango-cursorrules-prompt-file/nango-actions.mdc

@@ -0,0 +1,115 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Actions
+
+- `runAction` must be the default export at the top of the file
+- Only use `ActionError` for specific error messages:
+
+```typescript
+// ❌ Don't use generic Error
+throw new Error('Invalid response from API');
+
+// ✅ Do use nango.ActionError with a message
+throw new nango.ActionError({
+    message: 'Invalid response format from API'
+});
+```
+
+- Always return objects, not arrays
+- Always define API calls using a typed `ProxyConfiguration` object with retries set to 3:
+
+```typescript
+// ❌ Don't make API calls without a ProxyConfiguration
+const { data } = await nango.get({
+    endpoint: '/some-endpoint',
+    params: { key: 'value' }
+});
+
+// ❌ Don't make API calls without setting retries for actions
+const proxyConfig: ProxyConfiguration = {
+    endpoint: '/some-endpoint',
+    params: { key: 'value' }
+};
+
+// ✅ Do use ProxyConfiguration with retries set to 3 for actions
+const proxyConfig: ProxyConfiguration = {
+    endpoint: '/some-endpoint',
+    params: { key: 'value' },
+    retries: 3 // Default for actions is 3 retries
+};
+const { data } = await nango.get(proxyConfig);
+```
+
+- When implementing pagination in actions, always return a cursor-based response to allow users to paginate through results:
+
+```typescript
+// ✅ Define input type with optional cursor
+interface ListUsersInput {
+    cursor?: string;
+    limit?: number;
+}
+
+// ✅ Define response type with next_cursor
+interface ListUsersResponse {
+    users: User[];
+    next_cursor?: string; // undefined means no more results
+}
+
+// ✅ Example action implementation with pagination
+export default async function runAction(
+    nango: NangoAction,
+    input: ListUsersInput
+): Promise<ListUsersResponse> {
+    const proxyConfig: ProxyConfiguration = {
+        endpoint: '/users',
+        params: {
+            limit: input.limit || 50,
+            cursor: input.cursor
+        },
+        retries: 3
+    };
+
+    const { data } = await nango.get(proxyConfig);
+
+    return {
+        users: data.users,
+        next_cursor: data.next_cursor // Pass through the API's cursor if available
+    };
+}
+
+// ❌ Don't paginate without returning a cursor
+export default async function runAction(
+    nango: NangoAction,
+    input: ListUsersInput
+): Promise<User[]> { // Wrong: Returns array without pagination info
+    const { data } = await nango.get({
+        endpoint: '/users',
+        params: { cursor: input.cursor }
+    });
+    return data.users;
+}
+```
+
+```typescript
+// Complete action example:
+import type { NangoAction, ProxyConfiguration, FolderContentInput, FolderContent } from '../../models';
+import { folderContentInputSchema } from '../schema.zod.js';
+
+export default async function runAction(
+    nango: NangoAction,
+    input: FolderContentInput
+): Promise<FolderContent> {
+    const proxyConfig: ProxyConfiguration = {
+        // https://api.example.com/docs/endpoint
+        endpoint: '/some-endpoint',
+        params: { key: 'value' },
+        retries: 3 // Default for actions is 3 retries
+    };
+
+    const { data } = await nango.get(proxyConfig);
+    return { result: data };
+}
+```

rules/nango-cursorrules-prompt-file/nango-best-practices.mdc

@@ -0,0 +1,9 @@
+---
+description: 
+globs: nango-integrations/*
+alwaysApply: false
+---
+# Script Best Practices Checklist
+- [ ] nango.paginate is used to paginate over responses in a sync
+- [ ] if it is possible that an action could have a paginated response then the action should return back a `cursor` so the user can paginate over the action response
+- [ ] ensure when running a sync you run it with the `--validation` flag to to make sure the schema is correct against the actual data

rules/nango-cursorrules-prompt-file/nango-deployment-guidelines.mdc

@@ -0,0 +1,46 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+
+# Deploying Integrations
+
+Once your integration is complete and tested, you can deploy it using the Nango CLI:
+
+```bash
+npx nango deploy <environment>
+```
+
+## Deployment Options
+
+- `--auto-confirm`: Skip all confirmation prompts
+- `--debug`: Run CLI in debug mode with verbose logging
+- `-v, --version [version]`: Tag this deployment with a version (useful for rollbacks)
+- `-s, --sync [syncName]`: Deploy only a specific sync
+- `-a, --action [actionName]`: Deploy only a specific action
+- `-i, --integration [integrationId]`: Deploy all scripts for a specific integration
+- `--allow-destructive`: Allow destructive changes without confirmation (use with caution)
+
+## Examples
+
+Deploy everything to production:
+```bash
+npx nango deploy production
+```
+
+Deploy a specific sync to staging:
+```bash
+npx nango deploy staging -s contacts
+```
+
+Deploy an integration with version tag:
+```bash
+npx nango deploy production -i salesforce -v 1.0.0
+```
+
+Deploy with auto-confirmation:
+```bash
+npx nango deploy staging --auto-confirm
+```
+

rules/nango-cursorrules-prompt-file/nango-integration-directory-structure.mdc

@@ -0,0 +1,72 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Integration Directory Structure
+
+Your integration should follow this directory structure for consistency and maintainability:
+
+```
+nango-integrations/
+├── nango.yaml              # Main configuration file
+├── models.ts               # Auto-generated models from nango.yaml
+├── schema.zod.ts          # Generated zod schemas for validation
+└── ${integrationName}/
+    ├── types.ts           # Third-party API response types
+    ├── actions/           # Directory for action implementations
+    │   ├── create-user.ts
+    │   ├── update-user.ts
+    │   └── delete-user.ts
+    ├── syncs/             # Directory for sync implementations
+    │   ├── users.ts
+    │   └── teams.ts
+    └── mappers/          # Shared data transformation functions
+        ├── to-user.ts
+        └── to-team.ts
+```
+
+## Key Components
+
+1. **Root Level Files**:
+   - `nango.yaml`: Main configuration file for all integrations
+   - `models.ts`: Auto-generated models from nango.yaml. If this doesn't exist or you have updated the `nango.yaml` be sure to run `npx nango generate`
+   - `schema.zod.ts`: Generated validation schemas
+
+2. **Integration Level Files**:
+   - `types.ts`: Third-party API response types specific to the integration
+
+3. **Actions Directory**:
+   - One file per action
+   - Named after the action (e.g., `create-user.ts`, `update-user.ts`)
+   - Each file exports a default `runAction` function
+
+4. **Syncs Directory**:
+   - One file per sync
+   - Named after the sync (e.g., `users.ts`, `teams.ts`)
+   - Each file exports a default `fetchData` function
+
+5. **Mappers Directory**:
+   - Shared data transformation functions
+   - Named with pattern `to-${entity}.ts`
+   - Used by both actions and syncs
+
+## Running Tests
+
+Test scripts directly against the third-party API using dryrun:
+
+```bash
+npx nango dryrun ${scriptName} ${connectionId} --integration-id ${INTEGRATION} --auto-confirm
+```
+
+Example:
+```bash
+npx nango dryrun settings g --integration-id google-calendar --auto-confirm
+```
+
+## Dryrun Options
+
+- `--auto-confirm`: Skip prompts and show all output
+```bash
+npx nango dryrun settings g --auto-confirm --integration-id google-calendar
+```