{"id":13583245,"url":"https://github.com/internet4000/find","last_synced_at":"2025-05-07T10:29:48.134Z","repository":{"id":33557698,"uuid":"112372302","full_name":"internet4000/find","owner":"internet4000","description":"URL \u0026 local first client side actions for the browser omnibox","archived":false,"fork":false,"pushed_at":"2024-11-12T07:11:25.000Z","size":841,"stargazers_count":36,"open_issues_count":21,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-02-25T09:04:28.259Z","etag":null,"topics":["bangs","cli","find","find-web","local-first","omnibox","open-search","router","search-actions","serverless","unhosted","url","url-builder","url-first","url-router","web-browser","web-components"],"latest_commit_sha":null,"homepage":"https://internet4000.github.io/find/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/internet4000.png","metadata":{"files":{"readme":"docs/readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-28T18:21:07.000Z","updated_at":"2024-11-12T07:11:29.000Z","dependencies_parsed_at":"2023-10-15T07:12:19.271Z","dependency_job_id":"cdee590c-9d8c-4e5c-8606-37a29ed821f6","html_url":"https://github.com/internet4000/find","commit_stats":{"total_commits":214,"total_committers":10,"mean_commits":21.4,"dds":"0.26635514018691586","last_synced_commit":"f0f5ced3ca83e8fe3313ebab1c43007f4905fac0"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internet4000%2Ffind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internet4000%2Ffind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internet4000%2Ffind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internet4000%2Ffind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/internet4000","download_url":"https://codeload.github.com/internet4000/find/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241826071,"owners_count":20026596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bangs","cli","find","find-web","local-first","omnibox","open-search","router","search-actions","serverless","unhosted","url","url-builder","url-first","url-router","web-browser","web-components"],"created_at":"2024-08-01T15:03:21.147Z","updated_at":"2025-03-04T10:05:03.524Z","avatar_url":"https://github.com/internet4000.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003e Check the other files of this folder for more documentation.\n\n# Find\nWeb browser URL search engine utility to customize the omnibar actions.\n\nIt is built as a single importable file, without dependency, that can\nrun in web browsers and node.js javascript contexts.\n\nIt is distributed as [a\nwebsite](https://internet4000.github.io/find/), [javascript\nclass](https://github.com/internet4000/find/blob/main/src/index.js),\n[npm package](https://www.npmjs.com/package/i4k-find) and [git\nrepository](https://github.com/internet4000/find).\n\nTo install and use a personal/community instance, follow the\ninstallation/deployment guides.\n\n## Browser search engine\n\nTo make Find the default search engine of a web browser:\n\n1. Visit [a find instance homepage](https://internet4000.github.io/find)\n2. Follow this [wiki how\n   guide](https://www.wikihow.com/Change-Your-Browser%27s-Default-Search-Engine)\n   for the specific device and browser\n\nAlternatively, adding manually the search engine could be done with this open search browser config:\n\n```\nSearch engine: `Find`\nKeyword: `f`\nQuery URL: `https://internet4000.github.io/find/#q=%s`\n```\n\n3. Make the new Find search engine the default search engine (optional,\n   recommended).\n4. Now it should be possible to use the functionalities of Find in the URL bar of the web browser\n\n\u003e The mobile installation is not the easiest, but works on Firefox; web-browsers\n\u003e are making their bread and butter on the default search engines, and our\n\u003e queries; so they sometimes make changing it slightly annoying.\n\n## Usage\nAll find \"search queries\" or \"commands\", are to be run in the browser\nomnibox, or a find search input.\n\nA \"find search query\" is a string of text, which \"Finds tries to\ndecode\", to find some syntax it knows, to build (destination) URLs\n(what the user is requesting).\n\nThe user query string, is splitted into a list of strings, for every\nwhite space, and from there, find looks for a \"symbol\", probably the\nfirst character of the first string, for example `!`, or `+`.\n\nIt then looks for an \"engine ID\", for example `m` in the user query\nstarting with `!m`.\n\nThe last part, are the user *arguments* to the the requested\ndestination URL/web-application.\n\nFor example `!m tokyo` in order to *search* (`!`) for \"tokyo\" on the\nmap application (`m`).\n\n### Symbols\n\nIf the query we write in Find starts by one of these **symbols**, Find will try\nto decrypt the user query to see if it can do something with it.\n\nAll available symbols are:\n\n- `!` = search\n- `+` = action\n- `\u0026` = build\n- `#` = command (no custom engines)\n- if there are no symbols, the query is forwarded untouched to the default search engine\n\nSymbols are a way to give semantic meaning to engines. It should help\norganize what the engines do, what parameter and query they can accept.\n\n### Engines by symbols\n\nFor an up-to date list of default engines by symbols, look at the `index.js`\nfile.\n\nAll these symbols can be overwritten by the user, and new ones can be added.\n\n#### ! search\n\nThese engines are stored under this `!` symbol, because they provide\nsearch results, from your query.\n\n- `!c \u003cquery\u003e` - contacts.google.com\n- `!d \u003cquery\u003e` - duckduckgo.com\n- `!dd \u003cquery\u003e` - devdocs.io\n- `!dr \u003cquery\u003e` - drive.google.com\n- `!m \u003cquery\u003e` - maps.google.com\n- `!osm \u003cquery\u003e` - openstreetmap.org\n- `!w \u003cquery\u003e` - en.wikipedia.org\n- `!y \u003cquery\u003e` - youtube.com\n- if unknown keyword - !keyword and queries fallback to default search\n  engine, currently duckduckgo\n- if nokeyword - search goes to default search engine\n\n#### + action\n\nThese engines are stored under this `+` symbol, because they will allow you to\ncomplete an action; add a item to a library, create a drawing, find a random\nimage or text etc.\n\n- `+r4 [url]` - add a new track to a radio4000, from a youtube URL\n- `+draw [title]` - open a new drawing in Google Drive Draw\n- `+doc [title]` - open a new Google Docs document\n- `+sheet` - open a new Google Spreadsheets document\n- `+gmail` - open a new Gmail (Google Mail) email\n- `+wr` - random wikipedia article\n- `+wri` - random wikipedia image media\n- `+r4p` [radio] - play a radio4000 radio\n- `+r4pr` [radio] - play a random track from a radio4000 radio\n\n#### \u0026 build\n\nThese engines are stored under this `\u0026` symbol, because the parameters\ntaken by the engines allows you to build complex URLs.\n\n- `\u0026gh [actor] [repo]` - github/[actor]/[repo]\n- `\u0026gl [actor] [repo]` - gitlab/[actor]/[repo]\n- `\u0026firebase [project]` - firebase/[project]\n- `\u0026netlify [project]` - netlify/[project]\n- `\u0026r4 [radio]` - radio4000/[radio]\n\n#### # command\n\nThis is a special symbol, for command functions within find.\n\n- `#add \u003csymbol\u003e \u003cengine-id\u003e \u003cengine-url\u003e`\n\nadds a custom engine, by its `engine-id`, under a specific `symbol`\n\n```\n#add ! gh https://github.com/search?q=\n```\n\n- `#del \u003csymbol\u003e \u003cengine-id\u003e`\n\ndeletes a custom engine, by its `engine-id`, under a specific `symbol`\n\n```\n#del ! gh\n```\n\n### Update default search engine\n\nIt is possible to customize the default search engine used by find.\n\nWe have to overwrite the engine under the id `d` (`!d`; **d** for _default_).\n\nFor this we can use the following \"find command\", to make Google our default search engine.\n\n```\n#add ! d https://encrypted.google.com/search#q={}\n```\n\nTo use these triggers, for exemple with the search query `foo`:\n\n- Put the cursor in the URL bar of the web-browser\n- Type the website's `!keyword` (the website on which you want to\n  search. ex: `!y` for Youtube), prefixed with a `!`.\n- After the keyword, add a `space` (just normally as in between two\n  words), and type our _search query_, in this exemple we said\n  `foo`\n- At this point the URL bar should have this written in `!y foo` (there\n  is a space in between `!y` and `foo`).\n- Press `enter` (the return key), to validate our search.\n- Now you should be on Youtube, with the search results for our\n  search querry `foo`.\n\nNote: in the exemple above `Find!` is considered to be our default\nsearch engine. If it is not, and you use it as one of Firefox's \"one click\nsearch engine\", or Chrome/Chromium's \"other search engine\", you have\nto follow the same steps as above but as a first step you need to\n_trigger the search `Find!` search engine_ (\"Tab\" key in Firefox /\n\"one space\" in Chrome/ium, after writting the keyword).\n\n### Add custom engines\n\nThe interest of Find is the possibility to add a custom engines,\nand replace the default ones depending on our preferences.\n\nThere are different ways to add engines (works for all symbols, but `#`):\n\n- `#add` command\n- `Find` object in the browser console (Try: `Find.help()`)\n- edit the code and host an instance\n\n### Sync data between devices\n\nto `sync` custom engines between devices, we use a trick with the password manager, and take advantage of the user usual way to synchronise credentials between their devices.\n\n\u003e This operation currently overwrites existing user defined engines, when\n\u003e importing new ones (in does not merge them).\n\n1. save the \"application data\" (user defined engines and symbols), as a JSON string, into a password manager, for this \"find instance\" URL\n2. in the other devices, import by \"login in\" this site (in the \"sync section\"), which will request the credentials for this site (actually the application data we just saved from our device).\n\nThe imported data, is written as the new user defined engines, and saved to local storage for this browser.\n\n### `search` engine urls\n\n1. Go to the website you would like to add and search for `foo` in the\n   search input.\n1. Wait for the search result to appear and copy the URL of the search\n   result page, it should have `foo` in it (usually after a parameter\n   called `q`, or `query`, but it could be a different pattern). Copy\n   everything, from the `scheme://` to `foo` (excluded).\n\n\u003e Note that you can also use the information stored in the `.xml` file\n\u003e possibly used by websites to define their `Open Search\nDescription`. To do that, inspect the HTML code of the site you want\n\u003e to add and search for a HTML link tag with the folloing type:\n\u003e `application/opensearchdescription+xml\"`. The file it points to will\n\u003e have the infortmation you are looking for in the `Url` XML tag.\n\n### API(s)\nFind has different interfaces, some of which can be used\nprogramatically (better than others):\n\n- through its URL: [internet4000.github.io/find/#q=[query]](https://internet4000.github.io/find/#q=[query]) with a Find search query\n- through the `I4kFind` Javascript class exported by the package (and\n  `.find(\"my query\")` public method)\n- through the graphical interface `./src/ui/index.js`, and all\n  exported web-components\n- through the `./service-worker.js` client side OpenSearch suggestions\n  API (experimental; see development notes)\n\n## Host a personal instance\n1. deploy and host the site on a server\n2. edit the file `assets/opensearch.xml` to fit the URL address of the\n   instance\n\n## Privacy\nThis software does not collect any data, there are and should be no\nanalytics functionalities on the user queries and usage.\n\nIt stores in the browsers local storage (could be improved, or\nenhanced), only the user defined customization(s).\n\n### (Privacy warning) Cloudflare analytics\n\nThere is a cloudflare analytics beacon.\n\nIt sends a HTTP get request, to cloudflare, to check if it can. If it\ncan, it warns the user that they should install a \"blocker\" with\ninstructions.\n\nIf the HTTP request succeeds (user has no advert blocker),\n[Cloudflare](https://www.cloudflare.com/analytics/), eventually must\nbe saving the \"request information\", for a certain amount of time.\n\nThe user query is (and should) never be shared with Cloudflare, the\n`#` param where the user request, always stays on the client side of\nthe browser.\n\nIt is used to warn the user:\n- if the request goes through to cloudflare, that they should install\na advert-blocker. The resulting analytics of user who do not have\nadvertising de-activated, are stored in Cloudflare analytics, but will\nnever be used to process user data of any kind. Sometimes an admin\nlooks at the map to see where the request to the site comes from.\n- if the request is rejected, it removes itself from the DOM (see\n@TODO:flag-rm-analytics-beacon)\n\n### About the hash parameter\nWhen making a search to an instance of find, the user query is passed\nto the client side application, and never to the server.\n\nThe query should never leave the user browser (and reach the server\nhosting the site serving the Find webpage and code), [as it is passed\nto the browser as value of the `hash` parameter](\nhttps://en.wikipedia.org/wiki/URI_fragment).\n\nThis should help protect more the privacy of the user, as the value of\nthe `hash` parameter in a URL, does not \"leak the user query\" to the\nserver it is hosted on (or any third party; there are none, except the\nCloudflare beacon, which can be removed; @TODO: add flag to local\nstorage to not even insert; but need to define first user settings,\nmore than just the custom engines).\n\n- Find uses the [hash](https://en.wikipedia.org/wiki/URI_fragment) `#`\n  URL Search Parameter; uses `#q=`\n- versus the [query](https://en.wikipedia.org/wiki/Query_string) `?`\n  URL Search Parameter (do not use; it used to only handle `?q=`, but\n  removed for the reason explained here; @TODO:rm-query-search-param\n  currently left in as fallback for legacy migration; and maybe\n  alternative entry point, somehow if some need)\n\n## Debug this software (live, in the browser)\nThe easieset way to start debugging is from the developer tools of\na web browser. Because Find is unminified javascript code, it is\npossible to look at what read what the code does and where it\nfails. You can for example use a debugger to follow how a query is\ntranslated.\n\nFrom a browser we can look at it like so:\n\n![find-browser-debug](./doc-debug.png \"How to debug Find from the browser\").\n\n## Firefox notes\n\nIn firefox omnibar, we can use the prefixes:\n\n```text\n*  to search for matches in bookmarks\n%  to search for matches in currently open tabs\n^  to search for matches in browsing history\n\u003e  to search for marches in firefox actions\n+  to search for matches in tagged pages\n#  to search for matches in page titles\n$  to search for matches in web addresses (URLs)\n?  to search for matches in suggestions\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finternet4000%2Ffind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finternet4000%2Ffind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finternet4000%2Ffind/lists"}