feat!: Make get_secret utility functions use secret references

Author: mrjones2014

README.md

@@ -221,8 +221,12 @@ able to access the session. You also **must** configure `op.nvim` with `biometri
 
 All commands are also available as a Lua API, see [API](#api). Additionally there are two utility methods for grabbing secrets to use in scripting:
 
-- `require('op').get_secret(item_name: string, field_name: string): string|nil, string|nil`
-- `require('op').get_secret_async(item_name: string, field_name: string, callback: fun(secret: string|nil, stderr: string|nil))`
+- `require('op').get_secret(item_reference: string): string|nil, string|nil`
+- `require('op').get_secret_async(item_reference: string, callback: fun(secret: string|nil, stderr: string|nil))`
+
+If the CLI integration is enabled in the 1Password desktop app, the field action menu will have an item to "Copy secret reference".
+You can also go to Settings -> Developer and "Show 1Password Developer experience" to enable the "Copy UUID" actions in the field and item action
+menus and the right click menu on vaults. To get an account UUID, run `op account list` and copy the `USER ID` field.
 
 ## Features
 
@@ -314,8 +318,8 @@ All commands are also available as a Lua API as described below:
 
 Additionally there are two utility methods for grabbing secrets to use in scripting:
 
-- `require('op').get_secret(item_name: string, field_name: string): string|nil, string|nil`
-- `require('op').get_secret_async(item_name: string, field_name: string, callback: fun(secret: string|nil, stderr: string|nil))`
+- `require('op').get_secret(item_reference: string): string|nil, string|nil`
+- `require('op').get_secret_async(item_reference: string, callback: fun(secret: string|nil, stderr: string|nil))`
 
 Additionally, part of `op.nvim`'s design includes complete bindings to the CLI that you can use for scripting with Lua. This API
 is available in the `op.api` module. This module returns a table that matches the hierarchy of the 1Password CLI commands.

doc/op.txt

@@ -1,4 +1,4 @@
-*op.txt*                                            Last change: 2024 March 18
+*op.txt*                                              Last change: 2024 May 28
 
 ==============================================================================
 Table of Contents                                       *op-table-of-contents*
@@ -266,10 +266,16 @@ COMMANDS                                                         *op-commands*
 All commands are also available as a Lua API, see API <#api>. Additionally
 there are two utility methods for grabbing secrets to use in scripting:
 
-- `require('op').get_secret(item_name: string, field_name: string):
-  string|nil, string|nil`
-- `require('op').get_secret_async(item_name: string, field_name: string,
-  callback: fun(secret: string|nil, stderr: string|nil))`
+- `require('op').get_secret(item_reference: string): string|nil, string|nil`
+- `require('op').get_secret_async(item_reference: string, callback:
+  fun(secret: string|nil, stderr: string|nil))`
+If the CLI integration is enabled in the 1Password desktop app, the field
+action menu will have an item to "Copy secret reference". You can also go to
+Settings -> Developer and "Show 1Password Developer experience" to enable the
+"Copy UUID" actions in the field and item action menus and the right click
+menu on vaults. To get an account UUID, run `op account list` and copy the
+`USER ID` field.
+
 
 ------------------------------------------------------------------------------
 FEATURES                                                         *op-features*
@@ -397,10 +403,9 @@ All commands are also available as a Lua API as described below:
 Additionally there are two utility methods for grabbing secrets to use in
 scripting:
 
-- `require('op').get_secret(item_name: string, field_name: string):
-  string|nil, string|nil`
-- `require('op').get_secret_async(item_name: string, field_name: string,
-  callback: fun(secret: string|nil, stderr: string|nil))`
+- `require('op').get_secret(item_reference: string): string|nil, string|nil`
+- `require('op').get_secret_async(item_reference: string, callback:
+  fun(secret: string|nil, stderr: string|nil))`
 Additionally, part of `op.nvim`'s design includes complete bindings to the CLI
 that you can use for scripting with Lua. This API is available in the `op.api`
 module. This module returns a table that matches the hierarchy of the
@@ -433,4 +438,4 @@ See lua/op/types.lua <./lua/op/types.lua> for type annotations describing the
 completions when using `lua-language-server`.
 
 
-vim:tw=78:ts=8:ft=help:norl:
+vim:tw=78:ts=8:ft=help:norl:

lua/op/init.lua

@@ -266,12 +266,10 @@ function M.op_analyze_buffer()
 end
 
 ---Utility method to get a secret in 1 line of code.
----@param item_name string the name of the item in 1Password to get the secret from
----@param field_name string the name of the field on the 1Password item that holds the secret
+---@param item_reference string The `op://` item reference; perfer using UUIDs if you have multiple accounts
 ---@return string|nil secret, string|nil stderr secret if successful, nil and the `STDERR` otherwise
-function M.get_secret(item_name, field_name)
-  local args = { item_name, '--reveal', '--fields', field_name }
-  local stdout, stderr = require('op.api').item.get(args)
+function M.get_secret(item_reference)
+  local stdout, stderr = require('op.api').read({ item_reference })
   if not stdout or #stdout == 0 then
     return nil, table.concat(stderr, '\n')
   end
@@ -280,12 +278,11 @@ function M.get_secret(item_name, field_name)
 end
 
 ---Utility method to asynchronously get a secret in 1 line of code.
----@param item_name string the name of the item in 1Password to get the secret from
----@param field_name string the name of the field on the 1Password item that holds the secret
+---@param item_reference string The `op://` item reference; prefer using UUIDs if you have multiple accounts
 ---@param callback fun(secret:string|nil, stderr:string|nil) callback to call with the secret on success, else `STDERR`
-function M.get_secret_async(item_name, field_name, callback)
-  local args = { async = true, item_name, '--reveal', '--fields', field_name }
-  require('op.api').item.get(args, function(stdout, stderr)
+function M.get_secret_async(item_reference, callback)
+  local args = { async = true, item_reference }
+  require('op.api').read(args, function(stdout, stderr)
     if not stdout or #stdout == 0 then
       callback(nil, table.concat(stderr, '\n'))
     else