moco-ruby 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7527d151ba5f10b9406932d5f6e488d73897fab49ef9ab9a89341166adde7d42
-  data.tar.gz: ce1efd8024e78ab0541229172735ac27c8ec4595eeaf86d3183bc09d72b59504
+  metadata.gz: a32219e92cf0b5cc11f885486ec9a0afce63d39d2a2de95f3d5225b5521020e5
+  data.tar.gz: fa20563a9ff63d9b412540b99beecdab249ee7dca31608d23a47a82926062f27
 SHA512:
-  metadata.gz: ecad34b5401422a64351c4814c262ad9328bde6cdfa096f2295ae58b5aa56aa015dbd2c06905a6c212a6efa3b13236c45df12dd8534c15861d61dbb5071630bd
-  data.tar.gz: fe46f175939e575b1b63459a10b2ababb5137e4fae30230e59ea45185c996f6e52e9b56ecc11184a2a8fc8a7c28deda74d134594a0940cc3358d7100b4cd735b
+  metadata.gz: 63995cff5c2e36f43619a43e04208460d8aa3a899f06a8b4e0acc673655af550ac40f472519096a8da21d73d850705a4d4a10d788287eb6cac1a461d614c4139
+  data.tar.gz: 7be74a0104d6bfffd3d3bb93f6658db539ec1727e108795f69a63c1b38447d0876eb21187c0557936fa0b70d7457a4150bccd9eed3ba04e8df6f3d32c59179ef

data/.rubocop.yml

@@ -16,6 +16,7 @@ Naming/MethodParameterName:
   - a
   - b
   - id
+  - to
 
 Layout/LineLength:
   Max: 130

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-05-23
+
+### Added
+- New entities to cover remaining MOCO API v1 resources: `LetterPaper`
+  (read-only letterhead listing), `InvoiceAttachment`, `OfferAttachment`,
+  and `Session` (API key exchange/verification).
+- `MOCO::Session.create(subdomain:, email:, password:)` exchanges credentials
+  for an API key without requiring an existing `Client`.
+- `moco.session.verify` confirms the configured API key and returns the user
+  identity.
+
+### Changed
+- `Invoice#attachments` and `Offer#attachments` now return a
+  `NestedCollectionProxy` of typed `InvoiceAttachment` / `OfferAttachment`
+  entities, replacing the previous raw `add_attachment` / `delete_attachment`
+  helpers. Use `invoice.attachments.create(attachment: { filename:, base64: })`
+  and `invoice.attachments.find(id).destroy` instead.
+- Documentation URLs updated from `hundertzehn.github.io/mocoapp-api-docs`
+  (legacy) to `docs.mocoapp.com/api/docs/v1` (current OpenAPI reference).
+
 ## [1.2.0] - 2026-01-14
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    moco-ruby (1.2.0)
+    moco-ruby (1.3.0)
       activesupport (>= 7.0)
       faraday (>= 2.0)
       fuzzy_match (~> 2.1.0)
@@ -9,7 +9,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.1.2)
+    activesupport (8.1.3)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
@@ -22,11 +22,11 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    addressable (2.8.8)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
-    bigdecimal (4.0.1)
+    bigdecimal (4.1.2)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     crack (1.0.1)
@@ -34,21 +34,22 @@ GEM
       rexml
     dotenv (2.8.1)
     drb (2.2.3)
-    faraday (2.14.0)
+    faraday (2.14.2)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.2)
+    faraday-net_http (3.4.3)
       net-http (~> 0.5)
     fuzzy_match (2.1.0)
     hashdiff (1.2.1)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.18.0)
+    json (2.19.5)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (6.0.1)
+    minitest (6.0.6)
+      drb (~> 2.0)
       prism (~> 1.5)
     net-http (0.9.1)
       uri (>= 0.11.1)
@@ -57,8 +58,8 @@ GEM
       ast (~> 2.4.1)
       racc
     power_assert (3.0.1)
-    prism (1.7.0)
-    public_suffix (7.0.2)
+    prism (1.9.0)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/moco-ruby.svg)](https://badge.fury.io/rb/moco-ruby)
 
-A Ruby Gem to interact with the [MOCO API](https://hundertzehn.github.io/mocoapp-api-docs/). This gem provides a modern, Ruby-esque interface (`MOCO::Client`) for interacting with the MOCO API.
+A Ruby Gem to interact with the [MOCO API](https://docs.mocoapp.com/api/docs/v1). This gem provides a modern, Ruby-esque interface (`MOCO::Client`) for interacting with the MOCO API.
 
 ## Installation
 
@@ -176,6 +176,47 @@ profile = moco.profile
 puts "Logged in as: #{profile.firstname} #{profile.lastname}"
 ```
 
+### Sessions
+
+Exchange email/password for an API key, or verify an existing key:
+
+```ruby
+# Exchange credentials for an API key (no Client needed)
+session = MOCO::Session.create(
+  subdomain: "your-subdomain",
+  email: "you@example.com",
+  password: "secret"
+)
+api_key = session["api_key"]
+
+# Verify the configured API key for an existing client
+identity = moco.session.verify
+puts "Authenticated as user #{identity['id']} (#{identity['uuid']})"
+```
+
+### Invoice / Offer Attachments
+
+Attachments are nested under the parent document and use base64-encoded uploads:
+
+```ruby
+require "base64"
+
+invoice = moco.invoices.find(123)
+invoice.attachments.all
+invoice.attachments.create(
+  attachment: {
+    filename: "appendix.pdf",
+    base64: Base64.strict_encode64(File.read("appendix.pdf"))
+  }
+)
+invoice.attachments.find(42).destroy
+
+# Offer attachments work the same way:
+moco.offers.find(123).attachments.create(
+  attachment: { filename: "quote-details.pdf", base64: ... }
+)
+```
+
 ### Reports
 
 Access read-only report endpoints:
@@ -212,9 +253,12 @@ The gem supports all MOCO API entities with a Ruby-esque interface:
 `InvoiceBookkeepingExport`, `PurchaseBookkeepingExport`
 
 **Nested Resources:**
-`Employment`, `WorkTimeAdjustment`, `ProjectContract`, `PaymentSchedule`, `RecurringExpense`, `InvoicePayment`, `InvoiceReminder`, `OfferApproval`
+`Employment`, `WorkTimeAdjustment`, `ProjectContract`, `PaymentSchedule`, `RecurringExpense`, `InvoicePayment`, `InvoiceReminder`, `OfferApproval`, `InvoiceAttachment`, `OfferAttachment`
+
+**Misc:**
+`LetterPaper` (read-only), `Session` (for API key exchange/verification)
 
-Access them via the client using their plural, snake_case names (e.g., `moco.planning_entries`, `moco.vat_code_sales`).
+Access them via the client using their plural, snake_case names (e.g., `moco.planning_entries`, `moco.vat_code_sales`, `moco.letter_papers`). Attachments are accessed via the parent: `invoice.attachments`, `offer.attachments`.
 
 ## Utilities
 

data/lib/moco/client.rb

@@ -42,6 +42,13 @@ module MOCO
       Profile.new(self, get("profile"))
     end
 
+    # Session helper for verifying the configured API key.
+    # Use MOCO::Session.create(subdomain:, email:, password:) to exchange
+    # credentials for an API key without a Client.
+    def session
+      @session ||= Session.new(self)
+    end
+
     # Reports namespace for read-only report endpoints
     def reports
       @reports ||= ReportsProxy.new(self)

data/lib/moco/entities/invoice.rb

@@ -90,21 +90,10 @@ module MOCO
       self
     end
 
-    # Get attachments for this invoice
+    # Fetches attachments for this invoice as a NestedCollectionProxy.
+    # Supports .all, .find(id), .create(attachment: { filename:, base64: }), and .destroy.
     def attachments
-      client.get("invoices/#{id}/attachments")
-    end
-
-    # Add an attachment to the invoice
-    def add_attachment(file_data)
-      client.post("invoices/#{id}/attachments", file_data)
-      self
-    end
-
-    # Delete an attachment from the invoice
-    def delete_attachment(attachment_id)
-      client.delete("invoices/#{id}/attachments/#{attachment_id}")
-      self
+      MOCO::NestedCollectionProxy.new(client, self, :attachments, "InvoiceAttachment")
     end
 
     # Fetches payments for this invoice

data/lib/moco/entities/invoice_attachment.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents an attachment on a MOCO invoice
+  #
+  # == Required attributes for create:
+  #   attachment - Hash with the following keys:
+  #     filename - String, file name including extension (e.g., "appendix.pdf")
+  #     base64   - String, base64-encoded file content
+  #
+  # == Read-only attributes:
+  #   id, title, created_at, updated_at
+  #
+  # == Usage:
+  #   invoice = moco.invoices.find(123)
+  #   invoice.attachments.all
+  #   invoice.attachments.create(
+  #     attachment: {
+  #       filename: "appendix.pdf",
+  #       base64: Base64.strict_encode64(File.read("appendix.pdf"))
+  #     }
+  #   )
+  #   invoice.attachments.find(42).destroy
+  #
+  # == Note:
+  #   The API only supports list (GET), create (POST), and delete (DELETE).
+  #   Update is not available - delete and re-upload to replace.
+  #
+  class InvoiceAttachment < BaseEntity
+    def to_s
+      title.to_s
+    end
+  end
+end

data/lib/moco/entities/letter_paper.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents a MOCO letter paper (letterhead template used on invoices/offers PDFs)
+  # Read-only listing of letterheads configured in the MOCO account.
+  #
+  # == Read-only attributes:
+  #   id, name, active, template, file, created_at, updated_at
+  #
+  # == Usage:
+  #   moco.letter_papers.all
+  #
+  # == Note:
+  #   The API only exposes a list endpoint (GET /letter_papers).
+  #   Use a letter paper's `id` as `letter_paper_id` when fetching
+  #   invoice/offer PDFs (e.g. GET /invoices/{id}.pdf?letter_paper_id=...).
+  #
+  class LetterPaper < BaseEntity
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/moco/entities/offer.rb

@@ -85,21 +85,10 @@ module MOCO
       reload
     end
 
-    # Get attachments for this offer
+    # Fetches attachments for this offer as a NestedCollectionProxy.
+    # Supports .all, .find(id), .create(attachment: { filename:, base64: }), and .destroy.
     def attachments
-      client.get("offers/#{id}/attachments")
-    end
-
-    # Add an attachment to the offer
-    def add_attachment(file_data)
-      client.post("offers/#{id}/attachments", file_data)
-      self
-    end
-
-    # Delete an attachment from the offer
-    def delete_attachment(attachment_id)
-      client.delete("offers/#{id}/attachments/#{attachment_id}")
-      self
+      MOCO::NestedCollectionProxy.new(client, self, :attachments, "OfferAttachment")
     end
 
     # Associations

data/lib/moco/entities/offer_attachment.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MOCO
+  # Represents an attachment on a MOCO offer
+  #
+  # == Required attributes for create:
+  #   attachment - Hash with the following keys:
+  #     filename - String, file name including extension (e.g., "appendix.pdf")
+  #     base64   - String, base64-encoded file content
+  #
+  # == Read-only attributes:
+  #   id, title, created_at, updated_at
+  #
+  # == Usage:
+  #   offer = moco.offers.find(123)
+  #   offer.attachments.all
+  #   offer.attachments.create(
+  #     attachment: {
+  #       filename: "appendix.pdf",
+  #       base64: Base64.strict_encode64(File.read("appendix.pdf"))
+  #     }
+  #   )
+  #   offer.attachments.find(42).destroy
+  #
+  # == Note:
+  #   The API only supports list (GET), create (POST), and delete (DELETE).
+  #   Update is not available - delete and re-upload to replace.
+  #
+  class OfferAttachment < BaseEntity
+    def to_s
+      title.to_s
+    end
+  end
+end

data/lib/moco/entities/project.rb

@@ -82,15 +82,24 @@ module MOCO
       MOCO::NestedCollectionProxy.new(client, self, :expenses, "Expense")
     end
 
-    # Fetches tasks associated with this project.
-    # Always returns a NestedCollectionProxy for consistent interface.
-    # Data is fetched lazily when accessed (e.g., .all, .first, .each).
-    # Note: Embedded tasks from projects.assigned are available via attributes[:tasks]
-    # but may have incomplete fields compared to the dedicated endpoint.
+    # Fetches tasks associated with this project via the API.
+    # Returns a NestedCollectionProxy for lazy loading and CRUD operations.
     def tasks
       MOCO::NestedCollectionProxy.new(client, self, :tasks, "Task")
     end
 
+    # Returns embedded tasks from the projects/assigned response, or nil.
+    # These have fewer fields than the full API response but avoid an
+    # extra API call, useful for limited-permission accounts.
+    def embedded_tasks
+      embedded = attributes[:tasks]
+      if embedded.is_a?(Array) && embedded.all? { |t| t.is_a?(MOCO::Task) }
+        embedded
+      else
+        []
+      end
+    end
+
     # Fetches contracts associated with this project.
     def contracts
       MOCO::NestedCollectionProxy.new(client, self, :contracts, "ProjectContract")

data/lib/moco/entities/session.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module MOCO
+  # Represents a MOCO API session for authentication.
+  #
+  # The `/session` endpoint exchanges email/password credentials for an
+  # API key, and can verify an existing key.
+  #
+  # == Creating an API key (POST /session):
+  #   result = MOCO::Session.create(
+  #     subdomain: "your-account",
+  #     email: "you@example.com",
+  #     password: "secret"
+  #   )
+  #   result["api_key"] # => "6f95f9a0..."
+  #   result["user_id"] # => 933590696
+  #
+  # == Verifying an existing key (GET /session):
+  #   identity = moco.session.verify
+  #   identity["id"]   # => 933590696
+  #   identity["uuid"] # => "7a60719d-..."
+  #
+  # == Note:
+  #   `create` does not require an existing Client - it uses a temporary
+  #   unauthenticated connection. `verify` uses the Client's configured
+  #   API key.
+  #
+  class Session
+    class << self
+      # Exchange email/password for an API key. Does not require a Client.
+      # Returns a Hash: { "api_key" => "...", "user_id" => ... }
+      def create(subdomain:, email:, password:)
+        conn = Faraday.new(url: "https://#{subdomain}.mocoapp.com/api/v1") do |f|
+          f.request :json
+          f.response :json
+        end
+        response = conn.post("session", { email:, password: })
+        raise MOCO::Error, "Authentication failed: #{response.status}" unless response.success?
+
+        response.body
+      end
+    end
+
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Verify the configured API key. Returns the identity Hash or raises on 401.
+    def verify
+      client.get("session")
+    end
+  end
+end

data/lib/moco/entities.rb

@@ -44,7 +44,7 @@ module MOCO
     end
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/projects.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/projects.html
   # @deprecated Use MOCO::Project from entities/project.rb instead
   class Project < BaseEntity
     attr_accessor :id, :active, :name, :customer, :tasks
@@ -54,7 +54,7 @@ module MOCO
     end
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/project_tasks.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/project_tasks.html
   # @deprecated Use MOCO::Task from entities/task.rb instead
   class Task < BaseEntity
     attr_accessor :id, :active, :name, :project_id, :billable
@@ -64,7 +64,7 @@ module MOCO
     end
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/activities.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/activities.html
   # @deprecated Use MOCO::Activity from entities/activity.rb instead
   class Activity < BaseEntity
     attr_accessor :id, :active, :date, :description, :project, :task, :seconds, :hours, :billable, :billed, :user,
@@ -79,13 +79,13 @@ module MOCO
     end
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/companies.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/companies.html
   # @deprecated Use MOCO::Company from entities/company.rb instead
   class Customer < BaseEntity
     attr_accessor :id, :name
   end
 
-  # https://hundertzehn.github.io/mocoapp-api-docs/sections/users.html
+  # https://docs.mocoapp.com/api/docs/v1#tag/users.html
   # @deprecated Use MOCO::User from entities/user.rb instead
   class User < BaseEntity
     attr_accessor :id, :firstname, :lastname

data/lib/moco/sync.rb

@@ -364,7 +364,7 @@ module MOCO
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
 
     def fetch_assigned_projects
-      # Use .projects.assigned for the source, standard .projects for the target
+      # Use .projects.assigned for both source and target to get embedded tasks
       source_filters = @filters.fetch(:source, {}).merge(active: "true")
       # Get the proxy, then fetch all results into the instance variable
       @source_projects = @source.projects.assigned.where(source_filters).all
@@ -372,19 +372,19 @@ module MOCO
       @source_projects.each do |project|
         debug_log "  Source Project: #{project.id} - #{project.name} (#{project.identifier})"
         debug_log "    Tasks:"
-        project.tasks.each do |task|
+        project.embedded_tasks.each do |task|
           debug_log "      Task: #{task.id} - #{task.name}"
         end
       end
 
       target_filters = @filters.fetch(:target, {}).merge(active: "true")
       # Get the proxy, then fetch all results into the instance variable
-      @target_projects = @target.projects.where(target_filters).all
+      @target_projects = @target.projects.assigned.where(target_filters).all
       debug_log "Found #{@target_projects.size} target projects:"
       @target_projects.each do |project|
         debug_log "  Target Project: #{project.id} - #{project.name} (#{project.identifier})"
         debug_log "    Tasks:"
-        project.tasks.each do |task|
+        project.embedded_tasks.each do |task|
           debug_log "      Task: #{task.id} - #{task.name}"
         end
       end
@@ -401,7 +401,7 @@ module MOCO
         @project_mapping[source_project.id] = target_project
         debug_log "Mapped source project #{source_project.id} (#{source_project.name}) to target project #{target_project.id} (#{target_project.name})"
 
-        target_project.tasks.each do |target_task|
+        target_project.embedded_tasks.each do |target_task|
           source_task = match_task(target_task, source_project)
           if source_task
             @task_mapping[source_task.id] = target_task
@@ -520,7 +520,7 @@ module MOCO
       return @default_task_cache[target_project.id] if @default_task_cache.key?(target_project.id)
 
       # Search for the default task in the target project
-      default_task = target_project.tasks.find { |task| task.name == @default_task_name }
+      default_task = target_project.embedded_tasks.find { |task| task.name == @default_task_name }
 
       # Cache the result (even if nil)
       @default_task_cache[target_project.id] = default_task
@@ -545,7 +545,7 @@ module MOCO
 
     def match_task(target_task, source_project)
       # Get tasks from the source project (embedded in projects.assigned response)
-      tasks = source_project.tasks
+      tasks = source_project.embedded_tasks
 
       # Only proceed if we have tasks to match against
       return nil if tasks.empty?

data/lib/moco/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MOCO
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/moco.rb

@@ -63,7 +63,11 @@ require_relative "moco/entities/recurring_expense"
 require_relative "moco/entities/invoice_payment"
 require_relative "moco/entities/invoice_reminder"
 require_relative "moco/entities/invoice_bookkeeping_export"
+require_relative "moco/entities/invoice_attachment"
 require_relative "moco/entities/offer_approval"
+require_relative "moco/entities/offer_attachment"
+require_relative "moco/entities/letter_paper"
+require_relative "moco/entities/session"
 require_relative "moco/entities/purchase_category"
 require_relative "moco/entities/purchase_draft"
 require_relative "moco/entities/purchase_payment"

data/sync_activity.rb

@@ -94,7 +94,7 @@ syncer = MOCO::Sync.new(
 syncer.source_projects.each do |project|
   if syncer.project_mapping[project.id]
     puts "✅ Project #{project} --> #{syncer.project_mapping[project.id]}"
-    project.tasks.each do |task|
+    project.embedded_tasks.each do |task|
       if syncer.task_mapping[task.id]
         puts "  ✅ Task #{task} --> #{syncer.task_mapping[task.id]}"
       else

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moco-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Teal Bauer
@@ -95,11 +95,14 @@ files:
 - lib/moco/entities/hourly_rate.rb
 - lib/moco/entities/internal_hourly_rate.rb
 - lib/moco/entities/invoice.rb
+- lib/moco/entities/invoice_attachment.rb
 - lib/moco/entities/invoice_bookkeeping_export.rb
 - lib/moco/entities/invoice_payment.rb
 - lib/moco/entities/invoice_reminder.rb
+- lib/moco/entities/letter_paper.rb
 - lib/moco/entities/offer.rb
 - lib/moco/entities/offer_approval.rb
+- lib/moco/entities/offer_attachment.rb
 - lib/moco/entities/payment_schedule.rb
 - lib/moco/entities/planning_entry.rb
 - lib/moco/entities/presence.rb
@@ -120,6 +123,7 @@ files:
 - lib/moco/entities/reports/finance.rb
 - lib/moco/entities/reports/utilization.rb
 - lib/moco/entities/schedule.rb
+- lib/moco/entities/session.rb
 - lib/moco/entities/tag.rb
 - lib/moco/entities/tagging.rb
 - lib/moco/entities/task.rb
@@ -161,7 +165,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A Ruby Gem to interact with the MOCO API.
 test_files: []