lastpass-api 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1a8aa320296c4a0aeb20e9a04e80c436219f754
-  data.tar.gz: 97e3b16e1ddbae6a8b8b30a57de7f847a92cb93e
+  metadata.gz: f26e4e827da19cccd9805e2100cac712895fc826
+  data.tar.gz: df65a26f0e0f16101129defd81581b846a3a3cf6
 SHA512:
-  metadata.gz: 92c56bd448f617d4302bad7492452412900818be871d2d91f571d03e8802ce549347674f388836fdd8565e144f72218db710de38552e50b0267c9b4ad1ef3641
-  data.tar.gz: 0ce701b1cd9d7698b47a2e52a6a98e9e739b280dcd68ce728846a130ee6c01ea9dd86ebbbd464ed235bba0a0db7e5c4a948dd2ceb0ed02e796e8f393b9a8e1bc
+  metadata.gz: 7d7852b0df17ccd15b70154e6b74336dc9a44f9efad5a2e2f2dcbbfa9d19e6aebe53189594ac0d880185fc061435648dd0658bc471fe534f4cfd429883727b94
+  data.tar.gz: 3e34687404317f013e4fcdc72da1866fee36c899b32658b0b4da6c0d8f73d17075d9759576c6b41cf7dc59f57a468c08b8e865e35f40c1f903f8839029f87f70

data/README.md

@@ -180,6 +180,10 @@ puts groups.first.to_h
 
 #### Update group (rename a group)
 
+Note that although this does rename the group, any accounts that were inside the group
+will still remain under the original group name. Any new accounts that are created
+will be placed under the new group name.
+
 ```ruby
 # Update using instance variables
 group = @lastpass.groups.find( 'Group1' )

data/lib/lastpass-api.rb

@@ -17,14 +17,24 @@ require 'lastpass-api/parser'
 module Lastpass
   @@verbose = false
 
+  # Verbose mode flag
   def self.verbose
     @@verbose
   end
 
+  # Set if you want to turn on verbose mode.  Turning on verbose will show much more output.
+  # This is good for debugging.  It will output any commands that are executed with "lpass".
+  #
+  # @return [Boolean]
+  # @example
+  #   Lastpass.verbose = true
   def self.verbose=( verbose )
     @@verbose = verbose
   end
 
+  private
+
+  # Make sure "lpass" is installed with the correct version.
   def self.check_lpass_in_path
     error_message = 'Cannot find the "lpass" executable in the path!'
     begin

data/lib/lastpass-api/account.rb

@@ -1,12 +1,29 @@
 module Lastpass
+
+  # Interact with a Lastpass account
   class Account
-    attr_reader :id, :group # TODO: Make group editable eventually
+    attr_reader :id
+    # @todo Make group editable eventually
+    attr_reader :group
     attr_accessor :name, :username, :password, :url, :notes
 
+    # @param params [Hash]
     def initialize( params )
       params_to_account( params )
     end
 
+    # Update the account details
+    #
+    # @param params [Hash]
+    # @example
+    #   account = @lastpass.accounts.find( 'MyAccount' )
+    #   account.update(
+    #     name: 'MyAccount EDIT',
+    #     username: 'root EDIT',
+    #     password: 'pass EDIT',
+    #     url: 'http://www.exampleEDIT.com',
+    #     notes: 'This is my note. EDIT'
+    #   )
     def update( params )
       deleted! if @deleted
       params.delete( :id ) # Prevent overwriting ID
@@ -15,7 +32,19 @@ module Lastpass
       save
     end
 
-    # TODO: This does not support changing groups yet!
+    # Either create or update an account, depending on what
+    # was changed on the account object before this method was called.
+    #
+    # @todo This does not support changing groups yet!
+    # @example
+    #   # Update using instance variables
+    #   account = @lastpass.accounts.find( 'MyAccount' )
+    #   account.name = 'MyAccount EDIT'
+    #   account.username = 'root EDIT'
+    #   account.password = 'pass EDIT'
+    #   account.url = 'http://www.exampleEDIT.com'
+    #   account.notes = 'This is my notes. EDIT'
+    #   account.save
     def save
       deleted! if @deleted
       # If there is an ID, update that entry
@@ -41,11 +70,22 @@ module Lastpass
       self
     end
 
+    # Delete the account
+    #
+    # @example
+    #   account = @lastpass.accounts.find( 1234 )
+    #   account.delete
     def delete
       Cli.rm( @id )
       @deleted = true
     end
 
+    # Hash representation of the account object
+    #
+    # @return [Hash]
+    # @example
+    #   puts account.to_h
+    #   # => { id: '1234', name: 'MyAccount', username: 'root', password: 'pass', url: 'http://www.example.com', notes: 'This is my note.', group: 'MyGroup' }
     def to_hash
       params = {}
       params[:id]       = @id       if @id
@@ -61,6 +101,8 @@ module Lastpass
     alias_method :to_h, :to_hash
 
     # Hide instance variables and values
+    #
+    # @api private
     def inspect
       original_inspect = super
       original_inspect.split( ' ' ).first << '>'

data/lib/lastpass-api/accounts.rb

@@ -1,6 +1,19 @@
 module Lastpass
+
+  # Interact with Lastpass accounts
   class Accounts < Collection
 
+    # Find a specific account by name or by ID
+    #
+    # @param search_text [String] Account name or ID
+    # @param with_password [Boolean] Fetch the password along with the account details (default: false)
+    # @return [Lastpass::Account, NilClass]
+    # @example
+    #   # Find a specific account by name
+    #   account = @lastpass.accounts.find( 'MyAccount', with_password: true )
+    #
+    #   # Find a specific account by ID
+    #   account = @lastpass.accounts.find( 1234, with_password: true )
     def find( search_text, with_password: false )
       params = super
       if params.is_a?( Hash ) && !params[:name]&.end_with?( '/' )
@@ -8,6 +21,20 @@ module Lastpass
       end
     end
 
+    # Find all accounts by name or by ID
+    #
+    # @note By default, with no params specified, all accounts will be returned.
+    # @param search_text [String] Account name or ID (can pass in regex like '.*')
+    # @param with_passwords [Boolean] Fetch the password along with the account details (default: false)
+    # @return [Array<Lastpass::Account>]
+    # @example
+    #   # Find all accounts that match string (or regex)
+    #   accounts = @lastpass.accounts.find_all( 'MyAcc' )
+    #   puts accounts.count
+    #   puts accounts.first.to_h
+    #
+    #   # Fetch all accounts - same as find_all( '.*' )
+    #   @lastpass.accounts.find_all
     def find_all( search_text = '.*', with_passwords: false )
       accounts = super.select { |params| !params[:name]&.end_with? '/' }
       accounts.map do |params|
@@ -15,12 +42,32 @@ module Lastpass
       end
     end
 
+    # Create a new account
+    #
+    # @param params [Hash]
+    # @return [Lastpass::Account]
+    # @example
+    #   # Create an optional group to place account into
+    #   @lastpass.groups.create( name: 'MyGroup' )
+    #
+    #   # Create account
+    #   account = @lastpass.accounts.create(
+    #     name: 'MyAccount',
+    #     username: 'root',
+    #     password: 'pass',
+    #     url: 'http://www.example.com',
+    #     notes: 'This is my note.',
+    #     group: 'MyGroup'
+    #   )
+    #   puts account.id
     def create( params )
       params.delete( :id ) # Prevent overwriting ID
       Account.new( params ).save
     end
 
     # Hide instance variables and values
+    #
+    # @api private
     def inspect
       original_inspect = super
       original_inspect.split( ' ' ).first << '>'

data/lib/lastpass-api/cli.rb

@@ -3,8 +3,26 @@ require 'timeout'
 module Lastpass
 
   # Low-level interaction with LastPass CLI
+  #
+  # @api private
+  # @example
+  #   Lastpass::Cli.login( username, password:, trust: false, plaintext_key: false, force: false )
+  #   Lastpass::Cli.logout( force: false )
+  #   Lastpass::Cli.show( account, clip: false, expand_multi: false, all: false, basic_regexp: false, id: false )
+  #   Lastpass::Cli.ls( group = nil, long: false, m: false, u: false )
+  #   Lastpass::Cli.add( name, username: nil, password: nil, url: nil, notes: nil, group: nil )
+  #   Lastpass::Cli.add_group( name )
+  #   Lastpass::Cli.edit( id, name: nil, username: nil, password: nil, url: nil, notes: nil, group: nil )
+  #   Lastpass::Cli.edit_group( id, name: )
+  #   Lastpass::Cli.rm( id )
+  #   Lastpass::Cli.status( quiet: false )
+  #   Lastpass::Cli.sync
+  #   Lastpass::Cli.export
+  #   Lastpass::Cli.import( csv_filename )
+  #   Lastpass::Cli.version
   class Cli
-    UPLOAD_QUEUE_PATH = '~/.lpass/upload-queue' # TODO: Make this configurable? Or at least smarter?
+    # @todo Make this configurable? Or at least smarter?
+    UPLOAD_QUEUE_PATH = '~/.lpass/upload-queue'
 
     # Login to LastPass, opening up a global session
     #
@@ -26,11 +44,12 @@ module Lastpass
     end
 
     # @note lpass passwd
+    # @todo Not yet implemented
     def self.passwd
       not_implemented!
     end
 
-    # @note lpass show [--sync=auto|now|no] [--clip, -c] [--expand-multi, -x] [--all|--username|--password|--url|--notes|--field=FIELD|--id|--name|--attach=ATTACHID] [--basic-regexp, -G|--fixed-strings, -F] [--color=auto|never|always] {UNIQUENAME|UNIQUEID}
+    # @note lpass show [--sync=auto|now|no] [--clip, -c] [--expand-multi, -x] [--all|--username|--password|--url|--notes|--field=FIELD|--id|--name|--attach=ATTACHID] [--basic-regexp, -G|--fixed-strings, -F] [--color=auto|never|always] \\{UNIQUENAME|UNIQUEID}
     def self.show( account, clip: false, expand_multi: false, all: false, basic_regexp: false, id: false )
       sync # Ensure everything is synced up before running!
       command = 'lpass show'
@@ -62,12 +81,13 @@ module Lastpass
       response
     end
 
-    # @note lpass mv [--color=auto|never|always] {UNIQUENAME|UNIQUEID} GROUP
+    # @note lpass mv [--color=auto|never|always] \\{UNIQUENAME|UNIQUEID} GROUP
+    # @todo Not yet implemented
     def self.mv
       not_implemented!
     end
 
-    # @note lpass add [--sync=auto|now|no] [--non-interactive] [--color=auto|never|always] {--username|--password|--url|--notes|--field=FIELD|--note-type=NOTETYPE} NAME
+    # @note lpass add [--sync=auto|now|no] [--non-interactive] [--color=auto|never|always] \\{--username|--password|--url|--notes|--field=FIELD|--note-type=NOTETYPE} NAME
     def self.add( name, username: nil, password: nil, url: nil, notes: nil, group: nil )
       data = {}
       data[:Username] = escape( username,   double: true ) if username
@@ -85,14 +105,14 @@ module Lastpass
       response
     end
 
-    # @note lpass add [--sync=auto|now|no] [--non-interactive] [--color=auto|never|always] {--username|--password|--url|--notes|--field=FIELD|--note-type=NOTETYPE} NAME
+    # @note lpass add [--sync=auto|now|no] [--non-interactive] [--color=auto|never|always] \\{--username|--password|--url|--notes|--field=FIELD|--note-type=NOTETYPE} NAME
     def self.add_group( name )
       response = Utils.cmd "printf 'URL: http://group' | lpass add --non-interactive --sync=no '#{escape( name )}/'"
       sync
       response
     end
 
-    # @note lpass edit [--sync=auto|now|no] [--non-interactive] [--color=auto|never|always] {--name|--username|--password|--url|--notes|--field=FIELD} {NAME|UNIQUEID}
+    # @note lpass edit [--sync=auto|now|no] [--non-interactive] [--color=auto|never|always] \\{--name|--username|--password|--url|--notes|--field=FIELD} \\{NAME|UNIQUEID}
     def self.edit( id, name: nil, username: nil, password: nil, url: nil, notes: nil, group: nil )
       data = {}
       name_with_group = ''
@@ -114,7 +134,13 @@ module Lastpass
       response
     end
 
-    # @note lpass edit [--sync=auto|now|no] [--non-interactive] [--color=auto|never|always] {--name|--username|--password|--url|--notes|--field=FIELD} {NAME|UNIQUEID}
+    # @note lpass edit [--sync=auto|now|no] [--non-interactive] [--color=auto|never|always] \\{--name|--username|--password|--url|--notes|--field=FIELD} \\{NAME|UNIQUEID}
+    # @note This does actually rename the project even though it looks like it
+    #   creates a new group in Lastpass. This is because the original creds that
+    #   were under this project have the group name in the name of the creds
+    #   (yay for Lastpass awesomeness). So, after a project rename, newly created
+    #   creds will go under the new group name.  Old creds will rename in the
+    #   old pseudo name.
     def self.edit_group( id, name: )
       command = 'printf "'
       command << "Name: #{escape( name, double: true )}/"
@@ -125,17 +151,19 @@ module Lastpass
       response
     end
 
-    # @note lpass generate [--sync=auto|now|no] [--clip, -c] [--username=USERNAME] [--url=URL] [--no-symbols] {NAME|UNIQUEID} LENGTH
+    # @note lpass generate [--sync=auto|now|no] [--clip, -c] [--username=USERNAME] [--url=URL] [--no-symbols] \\{NAME|UNIQUEID} LENGTH
+    # @todo Not yet implemented
     def self.generate
-      not_implemented! # TODO
+      not_implemented!
     end
 
-    # @note lpass duplicate [--sync=auto|now|no] [--color=auto|never|always] {UNIQUENAME|UNIQUEID}
+    # @note lpass duplicate [--sync=auto|now|no] [--color=auto|never|always] \\{UNIQUENAME|UNIQUEID}
+    # @todo Not yet implemented
     def self.duplicate
       not_implemented!
     end
 
-    # @note lpass rm [--sync=auto|now|no] [--color=auto|never|always] {UNIQUENAME|UNIQUEID}
+    # @note lpass rm [--sync=auto|now|no] [--color=auto|never|always] \\{UNIQUENAME|UNIQUEID}
     def self.rm( id )
       response = Utils.cmd "lpass rm --sync=no #{id}"
       sync
@@ -168,6 +196,7 @@ module Lastpass
     end
 
     # @note lpass share subcommand sharename ...
+    # @todo Not yet implemented
     def self.share
       not_implemented!
     end

data/lib/lastpass-api/client.rb

@@ -1,10 +1,33 @@
 module Lastpass
+
+  # Main class to interact with Lastpass API
   class Client
 
+    # @param verbose [Boolean] Set if you want to turn on verbose mode.  Turning on
+    #   verbose will show much more output. This is good for debugging.  It will
+    #   output any commands that are executed with "lpass". (default: false)
+    # @example Without verbose
+    #   require 'lastpass-api'
+    #   @lastpass = Lastpass::Client.new
+    # @example With verbose mode on
+    #   require 'lastpass-api'
+    #   @lastpass = Lastpass::Client.new( verbose: true )
     def initialize( verbose: false )
       Lastpass.verbose = verbose
     end
 
+    # Login to Lastpass
+    #
+    # @note This is not thread safe. Only one login session can be active at a time.
+    # @note If there is a valid active login session already when this is called, it
+    #   will use that session rather than create a new one.
+    # @param email [String] Lastpass master email
+    # @param password [String] Lastpass master password
+    # @raise [RuntimeError] if login failed
+    # @return [Boolean] if login was successful
+    # @example
+    #   @lastpass.login( email: 'user@example.com', password: 'secret' )
+    #   puts @lastpass.logged_in?
     def login( email:, password: )
       if logged_in?
         Cli.sync
@@ -17,6 +40,12 @@ module Lastpass
       true
     end
 
+    # Logout of Lastpass
+    #
+    # @return [Boolean] if logout was successful
+    # @example
+    #   @lastpass.logout
+    #   puts @lastpass.logged_out?
     def logout
       return true if logged_out?
       Cli.logout
@@ -25,25 +54,39 @@ module Lastpass
       false
     end
 
+    # Check to see if currently logged into Lastpass
+    #
+    # @return [Boolean]
     def logged_in?
       Cli.status.include? 'Logged in'
     rescue
       false
     end
 
+    # Check to see if logged out of Lastpass
+    #
+    # @return [Boolean]
     def logged_out?
       !logged_in?
     end
 
+    # Interface to interacting with Lastpass accounts
+    #
+    # @return [Lastpass::Accounts]
     def accounts
       Accounts.new
     end
 
+    # Interface to interacting with Lastpass groups
+    #
+    # @return [Lastpass::Groups]
     def groups
       Groups.new
     end
 
     # Hide instance variables and values
+    #
+    # @api private
     def inspect
       original_inspect = super
       original_inspect.split( ' ' ).first << '>'

data/lib/lastpass-api/collection.rb

@@ -1,10 +1,25 @@
 module Lastpass
+
+  # Represents a collection of Lastpass objects (whether that be accounts or groups)
+  #
+  # @api private
   class Collection
 
+    # Find a specific object by name or by ID
+    #
+    # @param search_text [String] Object name or ID
+    # @param with_password [Boolean] Fetch the password along with the object details (default: false)
+    # @return [Hash, NilClass]
     def find( search_text, with_password: false )
       show( search_text, with_passwords: with_password )&.first
     end
 
+    # Find all objects by name or by ID
+    #
+    # @note By default, with no params specified, all objects will be returned.
+    # @param search_text [String] Object name or ID (can pass in regex like '.*')
+    # @param with_passwords [Boolean] Fetch the password along with the object details (default: false)
+    # @return [Array<Hash>]
     def find_all( search_text = '.*', with_passwords: false )
       show( search_text, with_passwords: with_passwords, regex: true ) || []
     end

data/lib/lastpass-api/group.rb

@@ -1,13 +1,22 @@
 module Lastpass
+
+  # Interact with a Lastpass group/folder
   class Group
     attr_reader :id
     attr_accessor :name
 
+    # @param params [Hash]
     def initialize( params )
       params[:name].chomp!( '/' ) if params[:name]&.end_with? '/'
       params_to_group( params )
     end
 
+    # Update the group details
+    #
+    # @param params [Hash]
+    # @example
+    #   group = @lastpass.groups.find( 'Group1' )
+    #   group.update( name: 'Group1 EDIT' )
     def update( params )
       deleted! if @deleted
       params.delete( :id ) # Prevent overwriting ID
@@ -15,6 +24,14 @@ module Lastpass
       save
     end
 
+    # Either create or update a group, depending on what
+    # was changed on the group object before this method was called.
+    #
+    # @example
+    #   # Update using instance variables
+    #   group = @lastpass.groups.find( 'Group1' )
+    #   group.name = 'Group1 EDIT'
+    #   group.save
     def save
       deleted! if @deleted
       # If there is an ID, update that entry
@@ -27,11 +44,22 @@ module Lastpass
       self
     end
 
+    # Delete the group
+    #
+    # @example
+    #   group = @lastpass.groups.find( 1234 )
+    #   group.delete
     def delete
       Cli.rm( @id )
       @deleted = true
     end
 
+    # Hash representation of the account object
+    #
+    # @return [Hash]
+    # @example
+    #   puts group.to_h
+    #   # => { id: '1234', name: 'Group1' }
     def to_hash
       params = {}
       params[:id]   = @id   if @id
@@ -42,6 +70,8 @@ module Lastpass
     alias_method :to_h, :to_hash
 
     # Hide instance variables and values
+    #
+    # @api private
     def inspect
       original_inspect = super
       original_inspect.split( ' ' ).first << '>'

data/lib/lastpass-api/groups.rb

@@ -1,6 +1,19 @@
 module Lastpass
+
+  # Interact with Lastpass groups/folders
   class Groups < Collection
 
+    # Find a specific group by name or by ID
+    #
+    # @param search_text [String] Group name or ID
+    # @param with_password [Boolean] Fetch the account passwords along with the group details (default: false)
+    # @return [Lastpass::Group, NilClass]
+    # @example
+    #   # Find a specific group by name
+    #   group = @lastpass.groups.find( 'Group1' )
+    #
+    #   # Find a specific group by ID
+    #   group = @lastpass.groups.find( '1234' )
     def find( search_text, with_password: false )
       search_text.to_s.gsub!( '/', '' )
       search_text << '/' unless is_number?( search_text )
@@ -10,6 +23,20 @@ module Lastpass
       end
     end
 
+    # Find all groups by name or by ID
+    #
+    # @note By default, with no params specified, all groups will be returned.
+    # @param search_text [String] Group name or ID (can pass in regex like '.*')
+    # @param with_passwords [Boolean] Fetch the account passwords along with the group details (default: false)
+    # @return [Array<Lastpass::Group>]
+    # @example
+    #   # Find all groups that match string (or regex)
+    #   groups = @lastpass.groups.find_all( 'Gro' )
+    #   puts groups.count
+    #   puts groups.first.to_h
+    #
+    #   # Fetch all groups - same as find_all( '.*' )
+    #   @lastpass.groups.find_all
     def find_all( search_text = '.*', with_passwords: false )
       groups = super.select { |params| params[:name]&.end_with? '/' }
       groups.map do |params|
@@ -17,12 +44,21 @@ module Lastpass
       end
     end
 
+    # Create a new group
+    #
+    # @param params [Hash]
+    # @return [Lastpass::Group]
+    # @example
+    #   group = @lastpass.groups.create( name: 'Group1' )
+    #   puts group.id
     def create( params )
       params.delete( :id ) # Prevent overwriting ID
       Group.new( params ).save
     end
 
     # Hide instance variables and values
+    #
+    # @api private
     def inspect
       original_inspect = super
       original_inspect.split( ' ' ).first << '>'

data/lib/lastpass-api/parser.rb

@@ -1,16 +1,29 @@
 module Lastpass
+
+  # Internal class for parsing through Lastpass raw output
+  #
+  # @api private
   class Parser
 
+    # Method to interact directly with parser
+    #
+    # @param raw_string [String] Lastpass CLI response string
+    # @param with_passwords [Boolean] Whether or not to return passwords
+    # @return [Array<Hash>]
     def self.parse( raw_string, with_passwords: false )
       new( raw_string, with_passwords: with_passwords ).parse_all
     end
 
+    # @param (see parse)
     def initialize( raw_string, with_passwords: false )
       @raw_string = raw_string
       @with_passwords = with_passwords
       @all = {}
     end
 
+    # Parse through all lines in raw output
+    #
+    # @return [Array<Hash>]
     def parse_all
       @raw_string.split( "\n" ).each do |line|
         parse_line( line )
@@ -19,6 +32,8 @@ module Lastpass
     end
 
     # Hide instance variables and values
+    #
+    # @api private
     def inspect
       original_inspect = super
       original_inspect.split( ' ' ).first << '>'

data/lib/lastpass-api/utils.rb

@@ -2,9 +2,18 @@ require 'colorize'
 require 'open3'
 
 module Lastpass
+
+  # Internal utility class
+  #
+  # @api private
   class Utils
 
     # Run a command
+    #
+    # @param command [String]
+    # @param output [Boolean] Print command output on stdout (default: false)
+    # @raise [StandardError] if execution of command has errors
+    # @return [String] Command output
     def self.cmd( command, output: false )
       puts "RUN COMMAND:  #{command}".green if Lastpass.verbose
       @stdout = ''

data/lib/lastpass-api/version.rb

@@ -1,3 +1,4 @@
 module Lastpass
-  VERSION = '0.2.3'.freeze
+  # Version of this gem
+  VERSION = '0.3.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lastpass-api
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Eric Terry
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-15 00:00:00.000000000 Z
+date: 2017-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize