New Integration: Asana

Description

Add Asana integration to sync tasks, projects, comments, and team activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/linear/ - Similar project management system
• integrations/todoist/ - Task management integration
• integrations/github/ - For webhooks and OAuth reference

Required Files Structure

integrations/asana/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Asana API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Asana API Integration

OAuth Setup

• Use OAuth 2.0 Authorization Code flow
• Authorization URL: https://app.asana.com/-/oauth_authorize
• Token URL: https://app.asana.com/-/oauth_token
• Required scopes (format: <resource>:<action>):
  • tasks:read - Read tasks
  • tasks:write - Create/update tasks
  • projects:read - Read projects
  • projects:write - Create/update projects
  • project_sections:read - Read project sections
  • stories:read - Read comments/stories
  • users:read - Read user info
  • workspaces:read - Read workspaces
  • custom_fields:read - Read custom fields
  • attachments:read - Read attachments
  • webhooks:read - Read webhooks
  • webhooks:write - Create/manage webhooks

Key Endpoints

Base URL: https://app.asana.com/api/1.0

• GET /users/me - Get current user
• GET /users - List users in a workspace
• GET /workspaces - List workspaces
• GET /projects?workspace={workspace_gid} - List projects in a workspace
• GET /projects/{project_gid} - Get project details
• GET /projects/{project_gid}/tasks - List tasks in a project
• GET /projects/{project_gid}/sections - List sections in a project
• GET /tasks/{task_gid} - Get task details
• GET /tasks/{task_gid}/stories - Get comments/stories for a task
• GET /tasks/{task_gid}/subtasks - Get subtasks
• GET /tasks/{task_gid}/attachments - Get task attachments
• POST /webhooks - Create a webhook
• GET /webhooks?workspace={workspace_gid} - List webhooks
• DELETE /webhooks/{webhook_gid} - Delete a webhook
• GET /events?resource={resource_gid} - Get events (polling-based)
• GET /tags?workspace={workspace_gid} - List tags
• GET /custom_fields/{custom_field_gid} - Get custom field details

Events to Track

1. Tasks

   • Task created
   • Task completed / uncompleted
   • Task assigned / reassigned
   • Task due date changed
   • Task moved between sections
   • Subtask added

2. Projects

   • Project created / archived
   • Task added to / removed from project
   • Section created / reordered

3. Comments & Stories

   • Comment added to task
   • Task description updated
   • Attachment added

4. Team Activity

   • Team membership changes
   • User added to / removed from project

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 Authorization Code flow in account-create.ts
• Create Asana API utilities in utils.ts (handle pagination with offset and next_page)
• Implement sync logic in schedule.ts for tasks, projects, and comments
• Convert Asana events to CORE activity format
• Add webhook support for real-time task and project events
• Add error handling and rate limiting (150 requests/minute)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Asana API is RESTful with JSON request/response format
• Base URL: https://app.asana.com/api/1.0
• Pagination uses offset parameter with next_page.offset in response
• Use opt_fields query parameter to request specific fields (reduces payload)
• Webhooks require an initial handshake (X-Hook-Secret header)
• Webhook filters support: action (added, removed, changed, deleted, undeleted), resource_type, resource_subtype
• Events API provides polling-based change detection with sync tokens
• Rate limit: 150 requests per minute per user per app
• OAuth scopes follow <resource>:<action> format; apps without scopes use "Full permissions"
• Rich text fields use HTML format

Resources

• Asana API Reference
• OAuth Documentation
• OAuth Scopes
• Webhooks Guide
• Quick Start Guide
• Authentication Overview

Labels

enhancement, good first issue, integration, new-feature, new-integration

Read integrations/linear/, integrations/todoist/, and integrations/github/src/index.ts first, then use the required integrations/asana/ files as the implementation map. The work is done when OAuth, paginated Asana synchronization, activity conversion, webhook handling, rate limiting, error handling, and the listed integration documentation are complete.