tudla_hubstaff 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4618d21ce8eea610d7b0c2b25ca7f4188b4044ddac344ae30a5518e154db21c
+  data.tar.gz: 44c08c47579cd47c0ac320f02c95b3bb58e36b2c5a0d6ebe051941bf3f962c0c
+SHA512:
+  metadata.gz: 91f7745c87bfd703b0384ab62f898c7d5d3f313ec4e65848241bcb90947f9a43702988e5338c954052a22cd709e25fe5d253a17722cecad18357171816b3ddad
+  data.tar.gz: 750b594080e755fc669bf6f9469b0a9ee689eedc1ca7d1162b85a88f388b46cad2988fdc27b8e9aeac18c1097cad86e9acb0a4c5119db84104eb38b823b62e71

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Tibo Mogul
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,270 @@
+# TudlaHubstaff
+
+`TudlaHubstaff` is a Rails 8.1 mountable engine that provides a seamless integration with the **Hubstaff API v2**. It is built with the "Solid trifecta" (Solid Queue, Solid Cache, and Solid Cable) and integrates into the `TudlaContracts` ecosystem.
+
+## Features
+
+- **Hubstaff API v2 Integration**: Fetch daily activities, members, and tasks.
+- **Automated OAuth2**: Handles token refreshing and discovery automatically via `OpenIDConnect`.
+- **Solid Stack Integration**: SQL-backed background jobs, caching, and pub/sub.
+- **TudlaContracts Compatible**: Registers as a `time_sheet` provider.
+- **ViewComponent Architecture**: Modular, testable UI components with slot-based composition.
+- **Unmapped Entity Management**: Built-in views for mapping Users, Tasks, and Projects to Tudla entities.
+- **Customizable Views**: Generator-based ejection pattern for host app customization.
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem "tudla_contracts"
+gem "tudla_hubstaff"
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+### Mounting the Engine
+
+Mount the engine in your application's `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount TudlaHubstaff::Engine => "/tudla_hubstaff"
+end
+```
+
+### Installing Migrations
+
+Copy the engine's migrations to your application:
+
+```bash
+$ bin/rails tudla_hubstaff:install:migrations
+```
+
+Then run the migrations:
+
+```bash
+$ bin/rails db:migrate
+```
+
+### Generating the engine's Tailwind import file
+
+We are using`tailwindcss-rails` experiment support https://github.com/rails/tailwindcss-rails?tab=readme-ov-file#rails-engines-support-experimental
+
+Run the following command to generate the engine's Tailwind import file `app/assets/builds/tailwind/tudla_hubstaff.css`:
+```bash
+$ bin/rails tailwindcss:engines
+```
+
+Edit your `app/assets/tailwind/application.css` to import the engine's Tailwind import file:
+```css
+@import "../builds/tailwind/tudla_hubstaff";
+```
+
+### Importing the engine's JavaScript
+
+Edit your `app/javascript/application.js` to import the engine's JavaScript:
+```javascript
+import "tudla_hubstaff/controllers/index"
+```
+
+### Database Setup
+
+This engine uses the Solid trifecta. Ensure your host application is configured with the necessary databases (primary, queue, cache, cable) as described in the [Solid Rails documentation](https://github.com/rails/solid_queue).
+
+## Configuration
+
+The engine registers itself automatically with `TudlaContracts`. You typically interact with it via the `TudlaHubstaff::Provider`.
+
+To initialize a connection, you need a Hubstaff Personal Access Token (used as the initial refresh token):
+
+```ruby
+config = TudlaHubstaff::Config.new
+config.tudla_organization = Organization.first
+config.personal_access_token = ENV["HUBSTAFF_PAT"]
+config.organization_id = ENV["HUBSTAFF_VALUEPRO_ID"].to_i
+config.save
+
+# provider = TudlaHubstaff::Provider.new(config)
+```
+
+### Host Interface Configuration
+
+The engine requires a host interface class to provide available Tudla entities for mapping. Configure this in an initializer:
+
+```ruby
+# config/initializers/tudla_hubstaff.rb
+TudlaHubstaff.host_interface_class = "::HubstaffHostInterface"
+```
+
+Your class must inherit from `TudlaContracts::Integrations::HostInterface` and implement:
+
+```ruby
+class YourApp::HubstaffHostInterface < TudlaContracts::Integrations::HostInterface
+  def available_users_for_user(current_user)
+    # Return array of objects with :id, :name, :email
+  end
+
+  def available_tasks_for_user(current_user)
+    # Return array of objects with :id, :name, :project_name
+  end
+
+  def available_projects_for_user(current_user)
+    # Return array of objects with :id, :name
+  end
+end
+```
+
+### Layout Configuration
+
+By default, the engine uses its own layout. To use your application's layout:
+
+```ruby
+# config/initializers/tudla_hubstaff.rb
+TudlaHubstaff::Engine.config.tudla_hubstaff.layout = "application"
+```
+
+## Usage
+
+### Fetching Activities
+
+```ruby
+activities = provider.daily_activities
+```
+
+### Advanced API Access
+
+For more granular control, use the `ApiClient`:
+
+```ruby
+connection = TudlaHubstaff::ApiConnection.new("your_pat")
+client = TudlaHubstaff::ApiClient.new("your_org_id", connection)
+
+# Fetch members
+members = client.members
+
+# Fetch tasks
+tasks = client.tasks(status: "active")
+```
+
+## Scheduling Background Jobs
+
+The engine includes a `FetchUpdatedActivitiesJob` that syncs activity updates from Hubstaff. **The host application must schedule this job to run periodically.**
+
+### Using Solid Queue (Recommended)
+
+Add a recurring job in your host application's `config/recurring.yml`:
+
+```yaml
+production:
+  fetch_hubstaff_activities:
+    class: TudlaHubstaff::FetchUpdatedActivitiesJob
+    schedule: every 15 minutes
+```
+
+### Using Cron or Other Schedulers
+
+If you prefer cron or another scheduler, enqueue the job periodically:
+
+```ruby
+TudlaHubstaff::FetchUpdatedActivitiesJob.perform_later
+```
+
+**Note:** Before the job can process an organization, you must create an `OrganizationUpdate` record with a `last_updated_at` timestamp. Records with `nil` timestamps are skipped.
+
+## Architecture
+
+- **`TudlaHubstaff::Provider`**: The main entry point for the `TudlaContracts` interface.
+- **`TudlaHubstaff::ApiClient`**: Handles Hubstaff v2 API endpoints.
+- **`TudlaHubstaff::ApiConnection`**: Manages Faraday connections and OAuth2 token lifecycle.
+- **Caching**: Access tokens and refresh tokens are stored in `Rails.cache` (backed by `SolidCache`).
+
+### ViewComponent Architecture
+
+The engine uses [ViewComponent](https://viewcomponent.org/) for modular, testable UI components:
+
+- **`TudlaHubstaff::BaseComponent`**: Base class with engine route helpers
+- **`TudlaHubstaff::UI::ModalComponent`**: Reusable modal with slots (header, body, footer)
+- **`TudlaHubstaff::UI::TableComponent`**: Table with header and rows slots
+- **`TudlaHubstaff::UI::PaginationComponent`**: Pagination with configurable path helper
+- **`TudlaHubstaff::UI::StatusBadgeComponent`**: Status badges with color coding
+- **`TudlaHubstaff::UI::MappingModalComponent`**: Specialized modal for entity mapping
+- **`TudlaHubstaff::UI::MapButtonComponent`**: Button to trigger mapping modal
+
+## Customizing Views
+
+The engine provides generators to copy views and components to your application for customization.
+
+### Copy All Views
+
+```bash
+rails g tudla_hubstaff:views
+```
+
+### Copy Scoped Views
+
+```bash
+# Copy only user views
+rails g tudla_hubstaff:views users
+
+# Copy only task views
+rails g tudla_hubstaff:views tasks
+
+# Copy only project views
+rails g tudla_hubstaff:views projects
+```
+
+### Copy Components
+
+```bash
+# Copy all components (Ruby classes and templates)
+rails g tudla_hubstaff:components
+
+# Copy only component templates (recommended for customization)
+rails g tudla_hubstaff:components --templates_only
+
+# Copy specific component scope
+rails g tudla_hubstaff:components ui
+```
+
+**Note:** When copying only templates, the engine retains control over the component logic while you customize the presentation.
+
+## Testing
+
+The engine uses RSpec for testing. A dummy Rails application is located in `spec/dummy`.
+
+### Database Setup for Tests
+
+**Important:** Rails 8 with the Solid trifecta uses multiple databases (primary, queue, cache, cable). When resetting the test database, you must load each schema separately.
+
+```bash
+# One-time setup or when you need a complete refresh
+RAILS_ENV=test bundle exec rails db:reset
+
+# Load Solid gem schemas (required after db:reset)
+RAILS_ENV=test bundle exec rails app:db:schema:load:cache
+RAILS_ENV=test bundle exec rails app:db:schema:load:queue
+RAILS_ENV=test bundle exec rails app:db:schema:load:cable
+
+# Run the specs
+bundle exec rspec
+```
+
+**Quick workflow for ongoing development:**
+
+```bash
+# When adding new migrations
+RAILS_ENV=test bundle exec rails db:migrate
+
+# Run tests
+bundle exec rspec
+```
+
+**Note:** `db:reset` only loads the primary database schema. The Solid gem databases (cache, queue, cable) have separate schema files that must be loaded explicitly.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/tudla_hubstaff/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/assets/tailwind/tudla_hubstaff/engine.css

@@ -0,0 +1,32 @@
+/* Engine CSS */
+@import "tailwindcss";
+
+/* 
+   @source Directive:
+   Explicitly tells the CLI where to look for class usage within the engine.
+   Relative path resolution is key here. 
+   Assuming the file is in app/assets/tailwind/my_engine/engine.css:
+  .. -> my_engine
+  .. -> tailwind
+  .. -> assets
+  .. -> app
+  ../views -> Target Directory
+*/
+@source "../../../views";
+@source "../../../components"; 
+
+/* 
+   @plugin Directive:
+   If the engine relies on specific plugins (e.g., typography, forms),
+   they must be declared here if not inheriting from the host.
+*/
+/*
+@plugin "@tailwindcss/typography";
+*/
+
+/* Custom Theme Variables specific to the engine */
+/*
+@theme {
+  --color-engine-brand: oklch(0.65 0.2 30);
+}
+*/

data/app/components/tudla_hubstaff/activity_row_component.html.erb

@@ -0,0 +1,46 @@
+<tr id="<%= dom_id %>" class="tudla_hubstaff-activity-row">
+  <td class="px-6 py-4 whitespace-nowrap">
+    <div class="text-sm text-gray-900"><%= format_date(activity.date) %></div>
+  </td>
+  <td class="px-6 py-4 whitespace-nowrap">
+    <div class="text-sm font-medium text-gray-900"><%= task_name %></div>
+    <% if mapped? %>
+      <div class="text-xs text-green-600">Mapped</div>
+    <% elsif hubstaff_task.present? %>
+      <div class="text-xs text-gray-500">Hubstaff Task</div>
+    <% end %>
+  </td>
+  <td class="px-6 py-4 whitespace-nowrap">
+    <div class="text-sm text-gray-900"><%= format_duration(activity.tracked) %></div>
+    <% if activity.billable.to_i > 0 %>
+      <div class="text-xs text-green-600">Billable: <%= format_duration(activity.billable) %></div>
+    <% end %>
+  </td>
+  <td class="px-6 py-4 whitespace-nowrap">
+    <div class="flex items-center space-x-2">
+      <div class="text-sm text-gray-500">
+        <span title="Overall activity"><%= activity.overall %>%</span>
+      </div>
+      <div class="w-16 bg-gray-200 rounded-full h-2">
+        <div class="bg-indigo-600 h-2 rounded-full" style="width: <%= [activity.overall.to_i, 100].min %>%"></div>
+      </div>
+    </div>
+  </td>
+  <td class="px-6 py-4 whitespace-nowrap text-sm font-medium">
+    <% if show_map_button? %>
+      <button type="button"
+              class="text-indigo-600 hover:text-indigo-900"
+              data-action="click->activity-task-mapping-modal#open"
+              data-activity-id="<%= activity.id %>"
+              data-hubstaff-task-id="<%= hubstaff_task.id %>"
+              data-task-name="<%= hubstaff_task.summary %>"
+              data-map-url="<%= map_url %>">
+        Map
+      </button>
+    <% elsif mapped? %>
+      <span class="text-green-600">✓</span>
+    <% else %>
+      <span class="text-gray-400">-</span>
+    <% end %>
+  </td>
+</tr>

data/app/components/tudla_hubstaff/activity_row_component.rb

@@ -0,0 +1,67 @@
+module TudlaHubstaff
+  class ActivityRowComponent < TudlaHubstaff::BaseComponent
+    def initialize(activity:)
+      @activity = activity
+    end
+
+    attr_reader :activity
+
+    def dom_id
+      "activity_#{activity.id}"
+    end
+
+    def hubstaff_task
+      @hubstaff_task ||= TudlaHubstaff::Task.find_by(task_id: activity.task_id) if activity.task_id.present?
+    end
+
+    def tudla_task_id
+      hubstaff_task&.tudla_task_id
+    end
+
+    def mapped?
+      tudla_task_id.present?
+    end
+
+    def task_name
+      if mapped?
+        tudla_task&.name || "Task ##{tudla_task_id}"
+      elsif hubstaff_task.present?
+        hubstaff_task.summary
+      else
+        "No task"
+      end
+    end
+
+    def tudla_task
+      @tudla_task ||= TudlaHubstaff.host_interface.find_task(tudla_task_id) if tudla_task_id.present?
+    end
+
+    def show_map_button?
+      hubstaff_task.present? && !mapped?
+    end
+
+    def map_url
+      map_activity_task_activity_path(activity) if hubstaff_task.present?
+    end
+
+    def format_duration(seconds)
+      return "0m" if seconds.nil? || seconds.zero?
+
+      hours = seconds / 3600
+      minutes = (seconds % 3600) / 60
+
+      if hours > 0
+        "#{hours}h #{minutes}m"
+      else
+        "#{minutes}m"
+      end
+    end
+
+    def format_date(date_string)
+      return "" if date_string.blank?
+      Date.parse(date_string).strftime("%b %d, %Y")
+    rescue ArgumentError
+      date_string
+    end
+  end
+end

data/app/components/tudla_hubstaff/base_component.rb

@@ -0,0 +1,10 @@
+module TudlaHubstaff
+  class BaseComponent < ViewComponent::Base
+    include TudlaHubstaff::Engine.routes.url_helpers
+    include Turbo::FramesHelper
+
+    def default_url_options
+      { only_path: true }
+    end
+  end
+end

data/app/components/tudla_hubstaff/project_row_component.html.erb

@@ -0,0 +1,22 @@
+<tr id="<%= dom_id %>" class="tudla_hubstaff-project-row">
+  <td class="px-6 py-4 whitespace-nowrap">
+    <div class="text-sm font-medium text-gray-900"><%= project.name %></div>
+    <div class="text-sm text-gray-500"><%= truncated_description %></div>
+  </td>
+  <td class="px-6 py-4 whitespace-nowrap">
+    <div class="text-sm text-gray-900"><%= formatted_project_type %></div>
+  </td>
+  <td class="px-6 py-4 whitespace-nowrap">
+    <%= render TudlaHubstaff::UI::StatusBadgeComponent.new(status: project.status) %>
+  </td>
+  <td class="px-6 py-4 whitespace-nowrap text-sm font-medium">
+    <button type="button"
+            class="text-indigo-600 hover:text-indigo-900"
+            data-action="click->project-mapping-modal#open"
+            data-project-id="<%= project.id %>"
+            data-project-name="<%= project.name %>"
+            data-map-url="<%= map_tudla_project_project_path(project) %>">
+      Map to Tudla Project
+    </button>
+  </td>
+</tr>

data/app/components/tudla_hubstaff/project_row_component.rb

@@ -0,0 +1,21 @@
+module TudlaHubstaff
+  class ProjectRowComponent < TudlaHubstaff::BaseComponent
+    def initialize(project:)
+      @project = project
+    end
+
+    attr_reader :project
+
+    def dom_id
+      "tudla_hubstaff_project_#{project.id}"
+    end
+
+    def truncated_description
+      project.description.to_s.truncate(50)
+    end
+
+    def formatted_project_type
+      project.project_type.titleize
+    end
+  end
+end

data/app/components/tudla_hubstaff/task_activities_component.html.erb

@@ -0,0 +1,82 @@
+<div class="tudla_hubstaff-task-activities">
+  <% if activities.any? %>
+    <div class="bg-white shadow rounded-lg overflow-hidden">
+      <table class="min-w-full divide-y divide-gray-200">
+        <thead class="bg-gray-50">
+          <tr>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Date</th>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">User</th>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Tracked</th>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Activity</th>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Last Updated</th>
+          </tr>
+        </thead>
+        <tbody class="bg-white divide-y divide-gray-200">
+          <% activities.each do |activity| %>
+            <tr class="tudla_hubstaff-activity-row">
+              <td class="px-6 py-4 whitespace-nowrap">
+                <div class="text-sm text-gray-900"><%= format_date(activity.date) %></div>
+              </td>
+              <td class="px-6 py-4 whitespace-nowrap">
+                <div class="text-sm text-gray-900"><%= activity.user_id %></div>
+              </td>
+              <td class="px-6 py-4 whitespace-nowrap">
+                <div class="text-sm text-gray-900"><%= format_duration(activity.tracked) %></div>
+                <% if activity.billable.to_i > 0 %>
+                  <div class="text-xs text-green-600">Billable: <%= format_duration(activity.billable) %></div>
+                <% end %>
+              </td>
+              <td class="px-6 py-4 whitespace-nowrap">
+                <div class="flex items-center space-x-2">
+                  <div class="text-sm text-gray-500">
+                    <span title="Overall activity"><%= activity.overall %>%</span>
+                  </div>
+                  <div class="w-16 bg-gray-200 rounded-full h-2">
+                    <div class="bg-indigo-600 h-2 rounded-full" style="width: <%= [activity.overall.to_i, 100].min %>%"></div>
+                  </div>
+                </div>
+              </td>
+              <td class="px-6 py-4 whitespace-nowrap">
+                <div class="text-sm text-gray-500">
+                  <% if activity.last_updated_at.present? %>
+                    <%= activity.last_updated_at.strftime("%b %d, %Y %H:%M") %>
+                  <% else %>
+                    -
+                  <% end %>
+                </div>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+
+    <% if total_pages > 1 %>
+      <div class="tudla_hubstaff-pagination flex items-center justify-between mt-4 px-4 py-3 bg-white border border-gray-200 rounded-lg sm:px-6">
+        <div class="text-sm text-gray-700">
+          Showing <span class="font-medium"><%= start_item %></span> to <span class="font-medium"><%= end_item %></span> of <span class="font-medium"><%= total_count %></span> activities
+        </div>
+        <div class="flex space-x-2">
+          <% if show_previous? %>
+            <span class="text-indigo-600 hover:text-indigo-900 cursor-pointer" data-page="<%= previous_page %>">
+              Previous
+            </span>
+          <% else %>
+            <span class="text-gray-400 cursor-not-allowed">Previous</span>
+          <% end %>
+          <% if show_next? %>
+            <span class="text-indigo-600 hover:text-indigo-900 cursor-pointer" data-page="<%= next_page %>">
+              Next
+            </span>
+          <% else %>
+            <span class="text-gray-400 cursor-not-allowed">Next</span>
+          <% end %>
+        </div>
+      </div>
+    <% end %>
+  <% else %>
+    <div class="text-center py-12 bg-white rounded-lg border border-gray-200">
+      <p class="text-gray-500">No activities found for this task.</p>
+    </div>
+  <% end %>
+</div>