diff --git a/README.org b/README.org index 14da5f9..a3a2935 100644 --- a/README.org +++ b/README.org @@ -1,6 +1,10 @@ +- [[android/public-receiver.org][Public receiver]] :: For integration with Tasker, Automate, etc. + +*Note:* the pages linked below are unchanged from [[https://github.com/orgzly/documentation][Orgzly's original documentation]], and may be out of date for Orgzly Revived. + - [[miscellaneous.org][A little bit of Everything]] :: Content of [[https://www.orgzly.com/docs]] - [[searching-proposal.org][Search queries syntax (Proposal)]] :: Full specification to be implemented * Android App -- [[android/changelog.org][Change Log]] :: What's New +- [[android/changelog.org][Change Log]] :: What's New - [[android/getting-started.org][Getting Started with Orgzly]] :: Imported Notebook diff --git a/android/public-receiver.org b/android/public-receiver.org new file mode 100644 index 0000000..32f1977 --- /dev/null +++ b/android/public-receiver.org @@ -0,0 +1,355 @@ +#+TITLE: Public Receiver +#+AUTHOR: Orgzly Revived +#+OPTIONS: html-postamble:nil num:nil H:10 + +/For integration with [[https://tasker.joaoapps.com/][Tasker]], [[https://llamalab.com/automate/][Automate]], etc./ + +* Table of Contents +- [[#types][Types]] + - [[#arguments-extras][Arguments (Extras)]] + - [[#json-types][JSON types]] +- [[#actions][Actions]] + - [[#add_note][ ~ADD_NOTE~ ]] + - [[#add_saved_search][ ~ADD_SAVED_SEARCH~ ]] + - [[#delete_note--delete_notes][ ~DELETE_NOTE~ / ~DELETE_NOTES~ ]] + - [[#delete_saved_search][ ~DELETE_SAVED_SEARCH~ ]] + - [[#edit_note][ ~EDIT_NOTE~ ]] + - [[#edit_saved_search][ ~EDIT_SAVED_SEARCH~ ]] + - [[#get_books][ ~GET_BOOKS~ ]] + - [[#get_note][ ~GET_NOTE~ ]] + - [[#get_saved_searches][ ~GET_SAVED_SEARCHES~ ]] + - [[#get_widgets][ ~GET_WIDGETS~ ]] + - [[#move_note--move_notes][ ~MOVE_NOTE~ / ~MOVE_NOTES~ ]] + - [[#move_saved_search][ ~MOVE_SAVED_SEARCH~ ]] + - [[#refile_note--refile_notes][ ~REFILE_NOTE~ / ~REFILE_NOTES~ ]] + - [[#search][ ~SEARCH~ ]] + - [[#set_widget][ ~SET_WIDGET~ ]] + +* Types +** Arguments (Extras) +The "arguments" to an action are supplied via the ~extras~ in the intent. + +| Key | Type | Description | +|-----------------------------------+--------------+------------------------------------------------------------------------------------------------------------------------| +| ~BOOK_ID~, ~PARENT_BOOK_ID~ | long | The internal ID of a notebook | +| ~BOOK_NAME~, ~PARENT_BOOK_NAME~ | string | The name of a notebook | +| ~DIRECTION~ | string | The direction in which to move something | +| ~NOTE_ID~, ~PARENT_NOTE_ID~ | long | The internal ID of a note | +| ~NOTE_IDS~ | long array | A list of internal note IDs | +| ~NOTE_PATH~, ~PARENT_NOTE_PATH~ | string | The path to a note, e.g. "My Book/Parent Note/Target Note" | +| ~NOTE_PATHS~ | string array | A list of note paths | +| ~NOTE_PAYLOAD~ | string | The contents of a new/edited note, in stringified JSON format; see the ~NotePayload~ type | +| ~NOTE_QUERY~, ~PARENT_NOTE_QUERY~ | string | An Orgzly search query to identify a note; errors if the query yields multiple notes | +| ~PLACEMENT~ | string | Where to place a note relative to another; one of ~​"ABOVE"​~, ~​"UNDER"​~, ~​"UNDER_AS_FIRST"​~, ~​"BELOW"​~, ~​"UNSPECIFIED"​~ | +| ~SAVED_SEARCH_ID~ | long | The internal ID of a saved search | +| ~SAVED_SEARCH_NAME~ | string | The name of a saved search | +| ~SAVED_SEARCH_NEW_NAME~ | string | The name for a new/edited saved search | +| ~SAVED_SEARCH_NEW_QUERY~ | string | The search query for a new/edited saved search | +| ~QUERY~ | string | An Orgzly search query | +| ~WIDGET_ID~ | int | The internal ID of a home screen widget | + +** JSON types +These are given in the style of TypeScript types. + +*** Book (Notebook) +#+BEGIN_SRC typescript +type Book = { + id: number, // Notebook ID in Orgzly's internal database + title: string, // Notebook title +} +#+END_SRC + +*** Note +#+BEGIN_SRC typescript +type Note = { + id: number, // Note ID in Orgzly's internal database + title: string, // Note title + content: string | null, // Note content + tags: string[], // Own tags - inherited tags are not included + inheritedTags: string[], // Tags inherited from parent notes + bookName: string, // The containing notebook's name + scheduled: Timestamp | null, // Scheduled timestamp + deadline: Timestamp | null, // Deadline timestamp + closed: Timestamp | null, // Closed timestamp + priority: string | null, // Priority string, e.g. "A", "B", "C" + state: string | null, // To-do state, e.g. "TODO", "DONE" + createdAt: number | null, // UNIX timestamp of the note's creation + properties: Record, // Map of the note's PROPERTIES +} +#+END_SRC + +*** Note payload +#+BEGIN_SRC typescript +type NotePayload = { + NOTE_PAYLOAD: { + title: string, // Note title + content?: string, // Note content + state?: string, // To-do state e.g. "TODO", "DONE" + priority?: string, // Priority string e.g. "A", "B", "C" + scheduled?: string, // Scheduled timestamp (in Org format) + deadline?: string, // Deadline timestamp (in Org format) + closed?: string, // Closed timestamp (in Org format) + tags?: string, // A space-separated list of tags + properties?: Record, // A map of properties + } +} +#+END_SRC + +*** Response +#+BEGIN_SRC typescript +type Response = { + success: true, // Success case + result: Data | null, // Response data; see response types for specific actions +} | { + success: false, // Failure case + result: string, // An error message +} +#+END_SRC + +*** Saved search +#+BEGIN_SRC typescript +type SavedSearch = { + id: number, // Saved search ID in Orgzly's internal database + name: string, // Saved search name + position: number, // Position in the list of saved searches + query: string, // The search's query +} +#+END_SRC + +*** Timestamp +#+BEGIN_SRC typescript +type Timestamp = { + rangeString: string, // Full timestamp string + timeTimestamp: number, // UNIX timestamp of the start of the time range + timeString: string | null, // String of the stamp's start time + timeEndString: string | null, // String of the stamp's end time +} +#+END_SRC + +* Actions +In practice, all actions should be prefixed with ~​"com.orgzly.android."​~ , e.g. ~​"com.orgzly.android.ADD_NOTE"​~ + +** ~ADD_NOTE~ +Adds a new note. + +*Arguments:* +- One of: + - ~PARENT_BOOK_ID~ + - ~PARENT_BOOK_NAME~ + - ~PARENT_NOTE_ID~ and ~PLACEMENT~ + - ~PARENT_NOTE_PATH~ and ~PLACEMENT~ + - ~PARENT_NOTE_QUERY~ and ~PLACEMENT~ +- ~NOTE_PAYLOAD~ + +*Returns:* +The internal ID of the newly-created note. +#+BEGIN_SRC typescript +type AddNoteResponse = Response +#+END_SRC + +** ~ADD_SAVED_SEARCH~ +Adds a new saved search. + +*Arguments:* +- ~SAVED_SEARCH_NEW_NAME~ +- ~SAVED_SEARCH_NEW_QUERY~ + +*Returns:* +The internal ID of the newly-created saved search. +#+BEGIN_SRC typescript +type AddSavedSearchResponse = Response +#+END_SRC + +** ~DELETE_NOTE~ / ~DELETE_NOTES~ +Deletes one or more notes. + +*Arguments:* +- One of: + - ~NOTE_ID~ + - ~NOTE_IDS~ + - ~NOTE_PATH~ + - ~NOTE_PATHS~ + +*Returns:* +Nothing. +#+BEGIN_SRC typescript +type DeleteNoteResponse = Response +#+END_SRC + +** ~DELETE_SAVED_SEARCH~ +Deletes a saved search. + +*Arguments:* +- One of: + - ~SAVED_SEARCH_ID~ + - ~SAVED_SEARCH_NAME~ + +*Returns:* +Nothing. +#+BEGIN_SRC typescript +type DeleteSavedSearchResponse = Response +#+END_SRC + +** ~EDIT_NOTE~ +Edits a note. + +*Arguments:* +- One of: + - ~NOTE_ID~ + - ~NOTE_PATH~ + - ~NOTE_QUERY~ +- ~NOTE_PAYLOAD~ + +*Returns:* +Nothing. +#+BEGIN_SRC typescript +type EditNoteResponse = Response +#+END_SRC + +** ~EDIT_SAVED_SEARCH~ +Edits a saved search. + +*Arguments:* +- One of: + - ~SAVED_SEARCH_ID~ + - ~SAVED_SEARCH_NAME~ +- ~SAVED_SEARCH_NEW_NAME~; optional - left unchanged if absent +- ~SAVED_SEARCH_NEW_QUERY~; optional - left unchanged if absent + +*Returns:* +Nothing. +#+BEGIN_SRC typescript +type EditSavedSearchResponse = Response +#+END_SRC + +** ~GET_BOOKS~ +Retrieves a list of all notebooks. + +*Arguments:* +None. + +*Returns:* +A list of all notebooks. +#+BEGIN_SRC typescript +type GetBooksResponse = Response +#+END_SRC + +** ~GET_NOTE~ +Retrieves a note. + +*Arguments:* +- One of: + - ~NOTE_ID~ + - ~NOTE_PATH~ + - ~NOTE_QUERY~ + +*Returns:* +The specified note. +#+BEGIN_SRC typescript +type GetNoteResponse = Response +#+END_SRC + +** ~GET_SAVED_SEARCHES~ +Retrieves a list of all saved searches. + +*Arguments:* +None. + +*Returns:* +A list of all saved searches. +#+BEGIN_SRC typescript +type GetSavedSearchesResponse = Response +#+END_SRC + +** ~GET_WIDGETS~ +Retrieves a list of all home screen widgets. + +*Arguments:* +None. + +*Returns:* +A map of internal widget IDs to the saved search they're set to +#+BEGIN_SRC typescript +type GetWidgetsResponse = Response> +#+END_SRC + +** ~MOVE_NOTE~ / ~MOVE_NOTES~ +Moves one or more notes in the specified direction. + +*Arguments:* +- One of: + - ~NOTE_ID~ + - ~NOTE_IDS~ + - ~NOTE_PATH~ + - ~NOTE_PATHS~ +- ~DIRECTION~; one of ~​"UP"​~, ~​"DOWN"​~, ~​"LEFT"​~ or ~​"RIGHT"​~ + +*Returns:* +Nothing. +#+BEGIN_SRC typescript +type MoveNoteResponse = Response +#+END_SRC + +** ~MOVE_SAVED_SEARCH~ +Moves a saved search up or down in the list of saved searches. + +*Arguments:* +- One of: + - ~SAVED_SEARCH_ID~ + - ~SAVED_SEARCH_NAME~ +- ~DIRECTION~; either ~​"UP"​~ or ~​"DOWN"​~ + +*Returns:* +Nothing. +#+BEGIN_SRC typescript +type MoveSavedSearchResponse = Response +#+END_SRC + +** ~REFILE_NOTE~ / ~REFILE_NOTES~ +Refiles one or more notes to a specified location. + +*Arguments:* +- One of: + - ~NOTE_ID~ + - ~NOTE_IDS~ + - ~NOTE_PATH~ + - ~NOTE_PATHS~ +- One of: + - ~PARENT_BOOK_ID~ + - ~PARENT_BOOK_NAME~ + - ~PARENT_NOTE_ID~ and ~PLACEMENT~ + - ~PARENT_NOTE_PATH~ and ~PLACEMENT~ + - ~PARENT_NOTE_QUERY~ and ~PLACEMENT~ + +*Returns:* +Nothing. +#+BEGIN_SRC typescript +type RefileNoteResponse = Response +#+END_SRC + +** ~SEARCH~ +Runs a search query, retrieving the results. + +*Arguments:* +- ~QUERY~ + +*Returns:* +A list of notes matching the query. +#+BEGIN_SRC typescript +type SearchResponse = Response +#+END_SRC + +** ~SET_WIDGET~ +Sets the saved search displayed by a home screen widget. + +*Arguments:* +- ~WIDGET_ID~ +- One of: + - ~SAVED_SEARCH_ID~ + - ~SAVED_SEARCH_NAME~ + +*Returns:* +Nothing. +#+BEGIN_SRC typescript +type SetWidgetResponse = Response +#+END_SRC