5pm 0.1.0

data/lib/five_pm/operations.json

@@ -0,0 +1,354 @@
+{
+  "activity": {
+    "add": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "activity": "nsc:Activity"
+      },
+      "response": {
+        "activity": "nsc:Activity"
+      }
+    },
+    "update": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "activity": "nsc:Activity"
+      },
+      "response": {
+        "activity": "nsc:Activity"
+      }
+    },
+    "remove": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "status": "xsd:boolean"
+      }
+    },
+    "getList": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "filter": "nsc:ActivityListFilter",
+        "offset": "xsd:integer",
+        "count": "xsd:integer",
+        "withFiles": "xsd:boolean",
+        "withNames": "xsd:boolean"
+      },
+      "response": {
+        "list": "nsc:ActivityList"
+      }
+    },
+    "getFilesList": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "filter": "nsc:ActivityListFilter",
+        "offset": "xsd:integer",
+        "count": "xsd:integer"
+      },
+      "response": {
+        "list": "nsc:FileList"
+      }
+    },
+    "getById": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer",
+        "withNames": "xsd:boolean"
+      },
+      "response": {
+        "activity": "nsc:Activity"
+      }
+    },
+    "attachFiles": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "activityId": "xsd:integer",
+        "files": "nsc:FileList"
+      },
+      "response": {
+        "status": "xsd:boolean"
+      }
+    },
+    "removeFile": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "status": "xsd:boolean"
+      }
+    },
+    "downloadFile": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer",
+        "stream": "xsd:boolean"
+      },
+      "response": {
+        "file": "nsc:File"
+      }
+    }
+  },
+  "authentication": {
+    "signIn": {
+      "parameters": {
+        "login": "xsd:string",
+        "password": "xsd:string"
+      },
+      "response": {
+        "auth": "nsc:AuthToken"
+      }
+    },
+    "signOut": {
+      "parameters": {
+        "sessionId": "xsd:string"
+      },
+      "response": {
+        "signOutState": "xsd:boolean"
+      }
+    },
+    "getAuthorizedUser": {
+      "parameters": {
+        "sessionId": "xsd:string"
+      },
+      "response": {
+        "user": "nsc:User"
+      }
+    },
+    "nop": {
+      "parameters": {
+        "sessionId": "xsd:string"
+      },
+      "response": {
+        "nopState": "xsd:boolean"
+      }
+    },
+    "isSsl": {
+      "parameters": {},
+      "response": {
+        "isSsl": "xsd:boolean"
+      }
+    }
+  },
+  "projects": {
+    "add": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "project": "nsc:Project"
+      },
+      "response": {
+        "project": "nsc:Project"
+      }
+    },
+    "update": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "project": "nsc:Project"
+      },
+      "response": {
+        "project": "nsc:Project"
+      }
+    },
+    "remove": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "status": "xsd:boolean"
+      }
+    },
+    "getById": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "project": "nsc:Project"
+      }
+    },
+    "getAll": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "loadTeam": "xsd:boolean"
+      },
+      "response": {
+        "list": "nsc:ProjectList"
+      }
+    },
+    "getList": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "filter": "nsc:ProjectListFilter",
+        "offset": "xsd:integer",
+        "count": "xsd:integer",
+        "loadTeam": "xsd:boolean"
+      },
+      "response": {
+        "list": "nsc:ProjectList"
+      }
+    }
+  },
+  "projectsgroups": {
+    "add": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "group": "nsc:ProjectsGroup"
+      },
+      "response": {
+        "group": "nsc:ProjectsGroup"
+      }
+    },
+    "update": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "group": "nsc:ProjectsGroup"
+      },
+      "response": {
+        "group": "nsc:ProjectsGroup"
+      }
+    },
+    "remove": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "status": "xsd:boolean"
+      }
+    },
+    "getById": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "group": "nsc:ProjectsGroup"
+      }
+    },
+    "getAll": {
+      "parameters": {
+        "sessionId": "xsd:string"
+      },
+      "response": {
+        "list": "nsc:ProjectsGroupList"
+      }
+    }
+  },
+  "tasks": {
+    "add": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "task": "nsc:Task"
+      },
+      "response": {
+        "task": "nsc:Task"
+      }
+    },
+    "update": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "task": "nsc:Task"
+      },
+      "response": {
+        "task": "nsc:Task"
+      }
+    },
+    "remove": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "status": "xsd:boolean"
+      }
+    },
+    "getById": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "task": "nsc:Task"
+      }
+    },
+    "getList": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "filter": "nsc:TaskListFilter",
+        "offset": "xsd:integer",
+        "count": "xsd:integer",
+        "loadTeam": "xsd:boolean"
+      },
+      "response": {
+        "list": "nsc:TaskList"
+      }
+    }
+  },
+  "users": {
+    "add": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "user": "nsc:User"
+      },
+      "response": {
+        "user": "nsc:User"
+      }
+    },
+    "update": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "user": "nsc:User"
+      },
+      "response": {
+        "user": "nsc:User"
+      }
+    },
+    "remove": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "status": "xsd:boolean"
+      }
+    },
+    "getById": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "id": "xsd:integer"
+      },
+      "response": {
+        "user": "nsc:User"
+      }
+    },
+    "getByEmail": {
+      "parameters": {
+        "sessionId": "xsd:string",
+        "email": "xsd:string"
+      },
+      "response": {
+        "user": "nsc:User"
+      }
+    },
+    "getAll": {
+      "parameters": {
+        "sessionId": "xsd:string"
+      },
+      "response": {
+        "sessionId": "xsd:string",
+        "list": "nsc:UserList"
+      }
+    },
+    "getAuthorizedUser": {
+      "parameters": {
+        "sessionId": "xsd:string"
+      },
+      "response": {
+        "user": "nsc:User"
+      }
+    }
+  }
+}

data/lib/five_pm/pagination.rb

@@ -0,0 +1,51 @@
+module FivePM
+  module Pagination
+    def each_page(filter: nil, offset: 0, count: 100, max_pages: 100, **options)
+      unless block_given?
+        return enum_for(__method__, filter: filter, offset: offset, count: count, max_pages: max_pages,
+                                    **options)
+      end
+
+      unless OPERATIONS.fetch(@name).key?("getList")
+        raise ArgumentError, "this service does not support offset pagination"
+      end
+      raise ArgumentError, "max_pages must be 1..10000" unless max_pages.is_a?(Integer) && (1..10_000).cover?(max_pages)
+
+      Request.operation!(@name, "getList", { "offset" => offset, "count" => count })
+      previous = nil
+      max_pages.times do
+        page = list(filter: filter, offset: offset, count: count, **options)
+        raw = page.is_a?(Response) ? page.to_h : page
+        raw = Envelope.parts(raw, OPERATIONS.fetch(@name).fetch("getList")) if raw.is_a?(Hash)
+        items = raw.dig("list", "items") if raw.is_a?(Hash) && raw["list"].is_a?(Hash)
+        raise ProtocolError, "pagination expected a list.items array" unless items.is_a?(Array)
+
+        received = items.length
+        signature = JSON.generate(items)
+        raise ProtocolError, "pagination received a repeated page" if previous == signature && received.positive?
+        raise ProtocolError, "pagination exceeded the requested page size" if received > count
+
+        yield page
+        return self if received.zero? || received < count
+
+        previous = signature
+        offset += received
+      end
+      raise ProtocolError, "pagination reached max_pages; resume with an explicit offset"
+    end
+
+    def each_item(**options, &block)
+      return enum_for(__method__, **options) unless block_given?
+
+      each_page(**options) do |page|
+        items = if page.is_a?(Response)
+                  page.list.items
+                else
+                  Envelope.parts(page, OPERATIONS.fetch(@name).fetch("getList")).fetch("list").fetch("items")
+                end
+        items.each(&block)
+      end
+      self
+    end
+  end
+end

data/lib/five_pm/request.rb

@@ -0,0 +1,80 @@
+module FivePM
+  module Request
+    module_function
+
+    def validate!(parameters, depth = 0)
+      raise ArgumentError, "request nesting exceeds 32 levels" if depth > 32
+
+      case parameters
+      when Hash
+        parameters.each do |key, value|
+          unless (key.is_a?(String) || key.is_a?(Symbol)) && /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(key.to_s)
+            raise ArgumentError, "invalid request field name"
+          end
+
+          validate!(value, depth + 1)
+        end
+      when Array
+        parameters.each { |value| validate!(value, depth + 1) }
+      when Float
+        raise ArgumentError, "request numbers must be finite" unless parameters.finite?
+      when String, Integer, TrueClass, FalseClass, NilClass
+        # JSON-compatible scalars only; arbitrary objects cannot enter the wire format.
+      else
+        raise ArgumentError, "unsupported request value type"
+      end
+    end
+
+    def operation!(service, operation, parameters)
+      validate!(parameters)
+      required = case operation
+                 when "add", "update"
+                   [Resource::OBJECT_PARAMETERS.fetch(service)]
+                 when "getById", "remove", "removeFile", "downloadFile"
+                   ["id"]
+                 when "getByEmail"
+                   ["email"]
+                 when "attachFiles"
+                   %w[activityId files]
+                 else
+                   []
+                 end
+      if required.any? { |key| !parameters.key?(key) || parameters[key].nil? }
+        raise ArgumentError, "missing required operation parameters"
+      end
+
+      %w[id activityId].each do |key|
+        identifier!(parameters[key]) if parameters.key?(key)
+      end
+      if parameters.key?("email") && !(parameters["email"].is_a?(String) && !parameters["email"].empty?)
+        raise ArgumentError, "email must be a nonempty string"
+      end
+      if parameters.key?("filter") && !parameters["filter"].nil? && !parameters["filter"].is_a?(Hash)
+        raise ArgumentError, "filter must be an object"
+      end
+
+      if %w[add update].include?(operation)
+        record = parameters.fetch(required.first)
+        raise ArgumentError, "resource attributes must be an object" unless record.is_a?(Hash)
+        if operation == "update" && !(record.key?(:id) || record.key?("id"))
+          raise ArgumentError, "update requires an id in the attributes"
+        end
+
+        identifier!(record.key?("id") ? record["id"] : record[:id]) if operation == "update"
+      end
+      %w[offset count].each do |key|
+        next unless parameters.key?(key) && !parameters[key].nil?
+
+        value = parameters[key]
+        minimum = key == "count" ? 1 : 0
+        raise ArgumentError, "invalid pagination parameter" unless value.is_a?(Integer) && value >= minimum
+      end
+    end
+
+    def identifier!(value)
+      return if value.is_a?(Integer) || (value.is_a?(String) && /\A[+-]?\d+\z/.match?(value))
+
+      raise ArgumentError, "identifier must be an integer or decimal integer string"
+    end
+  end
+end

data/lib/five_pm/resource.rb

@@ -0,0 +1,41 @@
+module FivePM
+  # Convenience wrappers retain the complete upstream JSON envelope. Use #call
+  # for less common operations and exact WSDL parameter names.
+  class Resource < Service
+    include Pagination
+
+    OBJECT_PARAMETERS = { "projects" => "project", "projectsgroups" => "group", "tasks" => "task",
+                          "activity" => "activity", "users" => "user" }.freeze
+
+    def create(attributes)
+      attributes = attributes.to_h if attributes.is_a?(Models::Record)
+      call("add", **{ OBJECT_PARAMETERS.fetch(@name) => attributes })
+    end
+
+    def update(attributes)
+      attributes = attributes.to_h if attributes.is_a?(Models::Record)
+      unless attributes.is_a?(Hash) && (attributes.key?(:id) || attributes.key?("id"))
+        raise ArgumentError, "update requires an id in the attributes"
+      end
+
+      call("update", **{ OBJECT_PARAMETERS.fetch(@name) => attributes })
+    end
+
+    def get(id)
+      call("getById", id: id)
+    end
+
+    def delete(id)
+      call("remove", id: id)
+    end
+
+    def list(filter: nil, offset: nil, count: nil, **options)
+      operation = OPERATIONS.fetch(@name).key?("getList") ? "getList" : "getAll"
+      parameters = options.dup
+      { filter: filter, offset: offset, count: count }.each do |key, value|
+        parameters[key] = value unless value.nil?
+      end
+      call(operation, **parameters)
+    end
+  end
+end