{"id":15883216,"url":"https://github.com/cboulanger/zotero-sync-bookends","last_synced_at":"2025-09-04T07:16:53.355Z","repository":{"id":138345211,"uuid":"360460477","full_name":"cboulanger/zotero-sync-bookends","owner":"cboulanger","description":"Bookends Store for https://github.com/retorquere/zotero-sync","archived":false,"fork":false,"pushed_at":"2021-05-25T06:51:48.000Z","size":107,"stargazers_count":9,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-09T16:09:56.549Z","etag":null,"topics":["bookends","sync","synchronization","zotero","zotero-sync"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cboulanger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-22T09:16:43.000Z","updated_at":"2025-03-04T09:42:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"8f2131d3-70e5-4945-9aa8-abbdef31dd73","html_url":"https://github.com/cboulanger/zotero-sync-bookends","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/cboulanger/zotero-sync-bookends","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cboulanger%2Fzotero-sync-bookends","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cboulanger%2Fzotero-sync-bookends/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cboulanger%2Fzotero-sync-bookends/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cboulanger%2Fzotero-sync-bookends/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cboulanger","download_url":"https://codeload.github.com/cboulanger/zotero-sync-bookends/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cboulanger%2Fzotero-sync-bookends/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273570140,"owners_count":25129155,"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","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bookends","sync","synchronization","zotero","zotero-sync"],"created_at":"2024-10-06T04:08:47.909Z","updated_at":"2025-09-04T07:16:53.315Z","avatar_url":"https://github.com/cboulanger.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bookends Store for @retorquere/zotero-sync\n\nThis is a store implementation for https://github.com/retorquere/zotero-sync \nthat enables exporting/backing up Zotero libraries into Bookends, a MacOS reference\nmanager from https://www.sonnysoftware.com. Using Bookend's scripting support via\nJavaScript for Automation (JSX), Zotero data is added to, or updated in a Bookends library.\n\nThis implementation saves all Zotero libraries that are accessible to a given Zotero \nAPI key in a Bookends library, which must be opened during sync. All Zotero library items are\nstored in a separate Bookends \"group\". Zotero collections, notes, and attachments are\nnot synchronized.\n\nThe library allows, among other things, to use Bookends super-fast search to do a \ncross-library lookup of reference items, which is not possible with Zotero currently.\n\n## Issues\n - Access to Bookends via OSA/JXA is slow. The initial synchronization can take a couple of hours for large libraries.\n   After that, especially if you do it often, syncing should go fast since only the data that has changed is \n   synchronized. \n - The current implementation works well enough for my use case but of course isn't perfect. Please\n   let me know if it works for you and open issues / pull requests if it doesn't.\n - Bookends crashes quite a bit - see below how to recover from the crash without having to restart the \n   synchronization from scratch. \n - Make sure not to modify a library on zotero.org during the initial synchronization, since otherwise \n   synchronization will abort with a \"last-modified-version changed ... retry later\" error. \n - The implementation stores sync metadata such as the Zotero library version in the Bookends \n   group names. This isn't a very robust solution but since there is no other place in Bookends \n   for this kind of data, the best one I could come up with. \n   \n## Recovering from a Bookends crash\n\nUnfortunately, especially when syncing large libraries, Bookends sometimes crashes and messes up all the groups. \nYou can restore the state before the crash like so:\n\n   1) Rebuild the library \n   2) If the groups have disappeared, execute \"Flatten Groups List Hierarchy\" from the menu in the bottom left corner of \n      the application window. Now the groups should re-appear.\n   3) The group names (and the metadata stored in them) often need to be manually repaired. Double-click on them.\n      For every library that had been fully synchronized before the crash, set the `lastIndex` value to 0 and the \n      `version` value to the value of `library.version` displayed at `https://api.zotero.org/\u003cprefix\u003e/items/top?key=\u003cyour key\u003e` \n      (the `prefix` is also stored in the group name). You might also need to repair the group name, which is available\n      from the same JSON data as `library.name`\n      \nThen you can restart the synchronization. It will skip and update the previously synchronized libraries. For the others,\nit will \"fast-forward\" (sort of) to the not-yet-synchronized items if the \"lastIndex\" value has been preserved.\n\n## Installation\n\nTo use the library in your projects, simply `npm install @cboulanger/zotero-sync-bookends`. See [the test script](test.ts) \nfor an example on how to use the API.\n\n## Testing\n\nThe test will actually work out-of-the-box to sync your data if you provide the needed environment variables.\n\n```bash\ngit clone https://github.com/cboulanger/zotero-sync-bookends.git\ncd zotero-sync-bookends\ncp .env.dist ./.env\n# edit .env and provide the values needed there\nnpm install\nnpm test\n```\n\n## Creating an executable / MacOS app\n\nYou can create a standalone executable file which can be run on the command line or packaged into \nan application by executing `npm run pkg`. The executable will be written to the `bin` directory.\n\n\u003e Please note that if you have set environment variables in a `.env` file, the package will include \n\u003e include them and will be visible as plain text in the source! Please remove the file if you intend \n\u003e to distribute the built executable. The values will be used as defaults, which is convenient for \n\u003e personal use of the executable. \n\nThe usage of the executable is\n\n```bash\nzotero-sync-bookends \u003cZotero API key\u003e \"Bookends library file name (not the path!)\"\n```\n\n\n## Resources\n- [JXA Release notes](https://developer.apple.com/library/archive/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/Articles/OSX10-10.html#//apple_ref/doc/uid/TP40014508-CH109-SW1)\n- [JXA debugging](https://developer.apple.com/library/archive/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/Articles/OSX10-11.html#//apple_ref/doc/uid/TP40014508-CH110-SW1) \n- [AppleEvents Error Codes](https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptLangGuide/reference/ASLR_error_codes.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcboulanger%2Fzotero-sync-bookends","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcboulanger%2Fzotero-sync-bookends","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcboulanger%2Fzotero-sync-bookends/lists"}