n8n-nodes-hubstaff1

---

🚀 Features

✨ Complete Hubstaff API v2 Support

• 🔐 Secure Authentication: Automatic token refresh with intelligent caching
• 👥 User Management: Get current user info and retrieve users by ID
• 📁 Project Management: List, create, and manage projects
• ✅ Task Management: Create, update, and retrieve tasks across projects
• 👤 Member Management: Get all organization members with email addresses
• ⏱️ Time Tracking: Create, update, and retrieve time entries

🎯 Key Advantages

• ✅ Token Caching: Smart caching system reduces API calls and improves performance
• ✅ OpenID Connect: Uses industry-standard OAuth2 with automatic token refresh
• ✅ Error Handling: Comprehensive error messages for better debugging
• ✅ Pagination Support: Built-in pagination for large datasets
• ✅ Type Safety: Full TypeScript support with proper type definitions

📦 Installation

Via n8n UI (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Search for n8n-nodes-hubstaff1
4. Click Install

Via npm

npm install n8n-nodes-hubstaff1

🎬 Quick Start

1. Get Your Hubstaff Credentials

1. Visit Hubstaff Developer Portal
2. Create a Personal Access Token (Refresh Token)
3. Get your Organization ID from your Hubstaff account settings

2. Configure Credentials in n8n

1. In your n8n workflow, add the Hubstaff 1 node
2. Click Create New Credential
3. Enter:
   • Personal Access Token (Refresh Token): Your refresh token from Hubstaff
   • Organization ID: Your organization ID (optional but required for some operations)

3. Use the Node

Select your resource and operation:

• User: Get current user or get user by ID
• Project: Get all projects or get specific project
• Task: Get all tasks, create, or update tasks
• Member: Get all organization members (includes emails!)
• Time Entry: Get, create, or update time entries

📚 Documentation

Available Resources

👤 User

• Get current user (me): Returns authenticated user information
• Get User: Retrieve user details by User ID (includes email)

📁 Project

• Get All Projects: List all projects in your organization
• Get Project: Retrieve specific project by ID

✅ Task

• Get All Tasks: List tasks (optionally filtered by project)
• Create Task: Create a new task in a project
• Update Task: Update existing task details

👥 Member

• Get All Members: List all organization members with:
  • Email addresses
  • Membership roles
  • Project memberships
  • Profile information

⏱️ Time Entry

• Get Time Entries: Retrieve time entries (with date filters)
• Create Time Entry: Log new time entry
• Update Time Entry: Modify existing time entry

Authentication

This node uses Hubstaff's Personal Access Token (Refresh Token) system with automatic token exchange. The refresh token is securely cached and automatically exchanged for short-lived access tokens, ensuring reliable authentication without manual token management.

Token Features:

• ✅ Automatic refresh token exchange
• ✅ Intelligent caching (tokens cached until expiration)
• ✅ OpenID Connect discovery endpoint support
• ✅ Secure token storage

🔧 Configuration

Required Fields

• Personal Access Token (Refresh Token): Required for all operations
• Organization ID: Required for:
  • Project operations
  • Task operations (when not using Project ID)
  • Member operations

Optional Fields

• Organization ID: Can be left empty if you only use user-specific operations

📖 Example Workflows

Get All Members with Emails

1. Add Hubstaff 1 node
2. Select Resource: Member
3. Select Operation: Get All Members
4. Enable "Return All" to get complete list
5. Output includes user.email for each member

Output Example:

{
  "json": {
    "user_id": 12345,
    "user": {
      "id": 12345,
      "name": "John Doe",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "membership_role": "user",
    "effective_role": "project_user"
  }
}

Create a Task

1. Add Hubstaff 1 node
2. Select Resource: Task
3. Select Operation: Create Task
4. Enter:
   - Project ID: Your project ID
   - Name: Task name
5. Task is created and returned

Get User by ID

1. Add Hubstaff 1 node
2. Select Resource: User
3. Select Operation: Get User
4. Enter User ID
5. Returns user details including email

🆚 Why Choose This Package?

Feature	n8n-nodes-hubstaff1	Other Packages
Token Caching	✅ Intelligent caching	❌ No caching
OpenID Connect	✅ Full OAuth2 support	❌ Basic auth
Member Emails	✅ Full access	⚠️ Limited
Error Messages	✅ Detailed & helpful	⚠️ Basic
TypeScript	✅ Full support	⚠️ Partial
Active Maintenance	✅ Regularly updated	⚠️ Varies
API Coverage	✅ Complete v2 API	⚠️ Partial
Performance	✅ Optimized	⚠️ Standard

🐛 Troubleshooting

401 Invalid Token Error

• Solution: Ensure your Personal Access Token (Refresh Token) is valid and not expired
• The node automatically handles token refresh, but the refresh token itself must be valid

404 Not Found Error

• Solution: Make sure Organization ID is configured in credentials for:
  • Project operations
  • Task operations (when Project ID is not provided)
  • Member operations

Missing Email in Member Response

• Note: Email addresses are only visible to organization owners and managers
• Ensure your account has appropriate permissions

📊 API Coverage

This package provides comprehensive coverage of the Hubstaff API v2:

• ✅ Users: Current user info, user lookup by ID
• ✅ Projects: List, retrieve, create projects
• ✅ Tasks: Full CRUD operations
• ✅ Members: Complete member management with profile data
• ✅ Time Entries: Create, read, update time tracking data

📝 License

MIT License - feel free to use in your projects!

🙏 Acknowledgments

Built with ❤️ for the n8n community. Special thanks to Hubstaff for providing a robust API.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Links

• Hubstaff API Documentation
• Hubstaff Developer Portal
• n8n Documentation
• n8n Community Nodes Guide
• Report Issues

📋 Requirements

• n8n version 0.150.0 or higher
• Hubstaff account with API access
• Personal Access Token (Refresh Token) from Hubstaff

🔄 Changelog

v0.2.0

• ✨ Added professional icon
• 📚 Enhanced README with comprehensive documentation
• 🎨 Improved marketing and discoverability
• 🔧 Better package metadata

v0.1.8

• ✅ Added Get User by ID operation
• 🔧 Fixed user operations to match API v2

v0.1.7

• 👥 Added Member resource with Get All Members operation
• 📧 Member responses include email addresses

v0.1.6

• 🔐 Implemented token caching for better performance
• 🌐 Added OpenID Connect discovery support
• 🐛 Fixed 404 errors with proper endpoint structure

⭐ Support

If you find this package useful, please consider giving it a star on GitHub!

💡 Tips

• Organization ID: You can find your Organization ID by using the Organization → Get All operation (if available) or in your Hubstaff account settings
• Token Refresh: The node automatically handles token refresh - no manual intervention needed
• Pagination: Use "Return All" for complete datasets, or set a limit for faster responses
• Member Emails: Email addresses are only visible to organization owners and managers

---