app/models/agents/evernote_agent.rb
module Agents
class EvernoteAgent < Agent
include EvernoteConcern
description <<~MD
The Evernote Agent connects with a user's Evernote note store.
Visit [Evernote](https://dev.evernote.com/doc/) to set up an Evernote app and receive an api key and secret.
Store these in the Evernote environment variables in the .env file.
You will also need to create a [Sandbox](https://sandbox.evernote.com/Registration.action) account to use during development.
Next, you'll need to authenticate with Evernote in the [Services](/services) section.
Options:
* `mode` - Two possible values:
- `update` Based on events it receives, the agent will create notes
or update notes with the same `title` and `notebook`
- `read` On a schedule, it will generate events containing data for newly
added or updated notes
* `include_xhtml_content` - Set to `true` to include the content in ENML (Evernote Markup Language) of the note
* `note`
- When `mode` is `update` the parameters of `note` are the attributes of the note to be added/edited.
To edit a note, both `title` and `notebook` must be set.
For example, to add the tags 'comic' and 'CS' to a note titled 'xkcd Survey' in the notebook 'xkcd', use:
"notes": {
"title": "xkcd Survey",
"content": "",
"notebook": "xkcd",
"tagNames": "comic, CS"
}
If a note with the above title and notebook did note exist already, one would be created.
- When `mode` is `read` the values are search parameters.
Note: The `content` parameter is not used for searching. Setting `title` only filters
notes whose titles contain `title` as a substring, not as the exact title.
For example, to find all notes with tag 'CS' in the notebook 'xkcd', use:
"notes": {
"title": "",
"content": "",
"notebook": "xkcd",
"tagNames": "CS"
}
MD
event_description <<~MD
When `mode` is `update`, events look like:
{
"title": "...",
"content": "...",
"notebook": "...",
"tags": "...",
"source": "...",
"sourceURL": "..."
}
When `mode` is `read`, events look like:
{
"title": "...",
"content": "...",
"notebook": "...",
"tags": "...",
"source": "...",
"sourceURL": "...",
"resources" : [
{
"url": "resource1_url",
"name": "resource1_name",
"mime_type": "resource1_mime_type"
}
...
]
}
MD
default_schedule "never"
def working?
event_created_within?(interpolated['expected_update_period_in_days']) && !recent_error_logs?
end
def default_options
{
"expected_update_period_in_days" => "2",
"mode" => "update",
"include_xhtml_content" => "false",
"note" => {
"title" => "{{title}}",
"content" => "{{content}}",
"notebook" => "{{notebook}}",
"tagNames" => "{{tag1}}, {{tag2}}"
}
}
end
def validate_options
errors.add(:base, "mode must be 'update' or 'read'") unless %w[read update].include?(options[:mode])
if options[:mode] == "update" && schedule != "never"
errors.add(:base, "when mode is set to 'update', schedule must be 'never'")
end
if options[:mode] == "read" && schedule == "never"
errors.add(:base, "when mode is set to 'read', agent must have a schedule")
end
errors.add(:base,
"expected_update_period_in_days is required") unless options['expected_update_period_in_days'].present?
if options[:mode] == "update" && options[:note].values.all?(&:empty?)
errors.add(:base, "you must specify at least one note parameter to create or update a note")
end
end
def include_xhtml_content?
options[:include_xhtml_content] == "true"
end
def receive(incoming_events)
if options[:mode] == "update"
incoming_events.each do |event|
note = note_store.create_or_update_note(note_params(event))
create_event payload: note.attr(include_content: include_xhtml_content?)
end
end
end
def check
if options[:mode] == "read"
opts = note_params(options)
# convert time to evernote timestamp format:
# https://dev.evernote.com/doc/reference/Types.html#Typedef_Timestamp
opts.merge!(agent_created_at: created_at.to_i * 1000)
opts.merge!(last_checked_at: (memory[:last_checked_at] ||= created_at.to_i * 1000))
if opts[:tagNames]
notes_with_tags =
memory[:notes_with_tags] ||=
NoteStore::Search.new(note_store, { tagNames: opts[:tagNames] }).note_guids
opts.merge!(notes_with_tags:)
end
notes = NoteStore::Search.new(note_store, opts).notes
notes.each do |note|
memory[:notes_with_tags] << note.guid unless memory[:notes_with_tags].include?(note.guid)
create_event payload: note.attr(include_resources: true, include_content: include_xhtml_content?)
end
memory[:last_checked_at] = Time.now.to_i * 1000
end
end
private
def note_params(options)
params = interpolated(options)[:note]
errors.add(:base, "only one notebook allowed") unless params[:notebook].to_s.split(/\s*,\s*/) == 1
params[:tagNames] = params[:tagNames].to_s.split(/\s*,\s*/)
params[:title].strip!
params[:notebook].strip!
params
end
def evernote_note_store
evernote_client.note_store
end
def note_store
@note_store ||= NoteStore.new(evernote_note_store)
end
# wrapper for evernote api NoteStore
# https://dev.evernote.com/doc/reference/
class NoteStore
attr_reader :en_note_store
delegate :createNote, :updateNote, :getNote, :listNotebooks, :listTags, :getNotebook,
:createNotebook, :findNotesMetadata, :getNoteTagNames, to: :en_note_store
def initialize(en_note_store)
@en_note_store = en_note_store
end
def create_or_update_note(params)
search = Search.new(self, { title: params[:title], notebook: params[:notebook] })
# evernote search can only filter notes with titles containing a substring;
# this finds a note with the exact title
note = search.notes.detect { |note| note.title == params[:title] }
if note
# a note with specified title and notebook exists, so update it
update_note(params.merge(guid: note.guid, notebookGuid: note.notebookGuid))
else
# create the notebook unless it already exists
notebook = find_notebook(name: params[:notebook])
notebook_guid =
notebook ? notebook.guid : create_notebook(params[:notebook]).guid
create_note(params.merge(notebookGuid: notebook_guid))
end
end
def create_note(params)
note = Evernote::EDAM::Type::Note.new(with_wrapped_content(params))
en_note = createNote(note)
find_note(en_note.guid)
end
def update_note(params)
# do not empty note properties that have not been set in `params`
params.keys.each { |key| params.delete(key) unless params[key].present? }
params = with_wrapped_content(params)
# append specified tags instead of replacing current tags
# evernote will create any new tags
tags = getNoteTagNames(params[:guid])
tags.each { |tag|
params[:tagNames] << tag unless params[:tagNames].include?(tag)
}
note = Evernote::EDAM::Type::Note.new(params)
updateNote(note)
find_note(params[:guid])
end
def find_note(guid)
# https://dev.evernote.com/doc/reference/NoteStore.html#Fn_NoteStore_getNote
en_note = getNote(guid, true, false, false, false)
build_note(en_note)
end
def build_note(en_note)
notebook = find_notebook(guid: en_note.notebookGuid).try(:name)
tags = en_note.tagNames || find_tags(en_note.tagGuids.to_a).map(&:name)
Note.new(en_note, notebook, tags)
end
def find_tags(guids)
listTags.select { |tag| guids.include?(tag.guid) }
end
def find_notebook(params)
if params[:guid]
listNotebooks.detect { |notebook| notebook.guid == params[:guid] }
elsif params[:name]
listNotebooks.detect { |notebook| notebook.name == params[:name] }
end
end
def create_notebook(name)
notebook = Evernote::EDAM::Type::Notebook.new(name:)
createNotebook(notebook)
end
def with_wrapped_content(params)
params.delete(:notebook)
if params[:content]
params[:content] =
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" \
"<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">" \
"<en-note>#{params[:content].encode(xml: :text)}</en-note>"
end
params
end
class Search
attr_reader :note_store, :opts
def initialize(note_store, opts)
@note_store = note_store
@opts = opts
end
def note_guids
filtered_metadata.map(&:guid)
end
def notes
metadata = filtered_metadata
if opts[:last_checked_at] && opts[:tagNames]
# evernote does note change Note#updated timestamp when a tag is added to a note
# the following selects recently updated notes
# and notes that recently had the specified tags added
metadata.select! do |note_data|
note_data.updated > opts[:last_checked_at] ||
!opts[:notes_with_tags].include?(note_data.guid)
end
elsif opts[:last_checked_at]
metadata.select! { |note_data| note_data.updated > opts[:last_checked_at] }
end
metadata.map! { |note_data| note_store.find_note(note_data.guid) }
metadata
end
def create_filter
filter = Evernote::EDAM::NoteStore::NoteFilter.new
# evernote search grammar:
# https://dev.evernote.com/doc/articles/search_grammar.php#Search_Terms
query_terms = []
query_terms << "notebook:\"#{opts[:notebook]}\"" if opts[:notebook].present?
query_terms << "intitle:\"#{opts[:title]}\"" if opts[:title].present?
query_terms << "updated:day-1" if opts[:last_checked_at].present?
opts[:tagNames].to_a.each { |tag| query_terms << "tag:#{tag}" }
filter.words = query_terms.join(" ")
filter
end
private
def filtered_metadata
filter = create_filter
spec = create_spec
metadata = note_store.findNotesMetadata(filter, 0, 100, spec).notes
end
def create_spec
Evernote::EDAM::NoteStore::NotesMetadataResultSpec.new(
includeTitle: true,
includeAttributes: true,
includeNotebookGuid: true,
includeTagGuids: true,
includeUpdated: true,
includeCreated: true
)
end
end
end
class Note
attr_accessor :en_note
attr_reader :notebook, :tags
delegate :guid, :notebookGuid, :title, :tagGuids, :content, :resources,
:attributes, to: :en_note
def initialize(en_note, notebook, tags)
@en_note = en_note
@notebook = notebook
@tags = tags
end
def attr(opts = {})
return_attr = {
title:,
notebook:,
tags:,
source: attributes.source,
source_url: attributes.sourceURL
}
return_attr[:content] = content if opts[:include_content]
if opts[:include_resources] && resources
return_attr[:resources] = []
resources.each do |resource|
return_attr[:resources] << {
url: resource.attributes.sourceURL,
name: resource.attributes.fileName,
mime_type: resource.mime
}
end
end
return_attr
end
end
end
end