{"id":27635816,"url":"https://github.com/windingwind/zotero-types","last_synced_at":"2025-04-23T20:27:41.800Z","repository":{"id":58134389,"uuid":"530170249","full_name":"windingwind/zotero-types","owner":"windingwind","description":"TypeScript definitions for Zotero.","archived":false,"fork":false,"pushed_at":"2025-04-20T13:35:12.000Z","size":2077,"stargazers_count":62,"open_issues_count":1,"forks_count":11,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-20T13:42:07.335Z","etag":null,"topics":["api","npm","npm-package","plugin","types","typescript","typing","zotero"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/zotero-types","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/windingwind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2022-08-29T10:29:49.000Z","updated_at":"2025-04-20T13:35:14.000Z","dependencies_parsed_at":"2023-02-17T02:16:13.978Z","dependency_job_id":"8e606b36-5665-4cdd-b6dc-6a2d4c94a283","html_url":"https://github.com/windingwind/zotero-types","commit_stats":null,"previous_names":[],"tags_count":105,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windingwind%2Fzotero-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windingwind%2Fzotero-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windingwind%2Fzotero-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windingwind%2Fzotero-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/windingwind","download_url":"https://codeload.github.com/windingwind/zotero-types/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250508267,"owners_count":21442182,"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":["api","npm","npm-package","plugin","types","typescript","typing","zotero"],"created_at":"2025-04-23T20:27:41.279Z","updated_at":"2025-04-23T20:27:41.793Z","avatar_url":"https://github.com/windingwind.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zotero Types\n\nThis package contains type definitions for Zotero (\u003chttps://www.zotero.org/\u003e) plugin.\n\nnpm package: \u003chttps://www.npmjs.com/package/zotero-types\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"720\" src=\"https://github.com/user-attachments/assets/01a37569-77a6-4222-8624-a2136c1aa0d8\" /\u003e\n\u003c/p\u003e\n\n## Installation\n\nRun `npm install --save-dev zotero-types`.\n\n## Usage\n\n### Include Type Definitions\n\nYou can include the type definitions in your Zotero plugin project in three ways:\n\n1. Extend the `tsconfig.json` file in your Zotero plugin project. This is the recommended way.\n\n```jsonc\n// tsconfig.json\n{\n  \"extends\": \"zotero-types/entries/sandbox\",\n}\n```\n\nFor the best practices, see \u003chttps://github.com/windingwind/know-ur-zotero\u003e as a reference.\n\nAvailable entries:\n\n| Entry        | Description                                                                                                         | Privileged | Zotero | XUL | DOM | MainWindow | WebWorker |\n| ------------ | ------------------------------------------------------------------------------------------------------------------- | ---------- | ------ | --- | --- | ---------- | --------- |\n| `sandbox`    | The default entry for Zotero plugin development. For Zotero plugin's `bootstrap.js` sandbox environment.            | ✅         | ✅     | ❌  | ❌  | ❌         | ❌        |\n| `xhtml`      | The entry for Zotero's `xhtml` environment.                                                                         | ✅         | ✅     | ✅  | ✅  | ❌         | ❌        |\n| `mainWindow` | Besides definitions from the `xhtml` entry, it also includes main window APIs, such as `ZoteroPane`, `Zotero_Tabs`. | ✅         | ✅     | ✅  | ✅  | ✅         | ❌        |\n| `html`       | Same as normal HTML environment.                                                                                    | ❌         | ❌     | ❌  | ✅  | ❌         | ❌        |\n| `webworker`  | Same as normal web worker environment.                                                                              | ❌         | ❌     | ❌  | ❌  | ❌         | ✅        |\n| `base`       | The base entry. Does not include any extra type definitions.                                                        | ❌         | ❌     | ❌  | ❌  | ❌         | ❌        |\n| `shared`     | The entry for privileged APIs.                                                                                      | ✅         | ✅     | ❌  | ❌  | ❌         | ❌        |\n\n2. Use `compileOptions \u003e types` in your Zotero plugin project's `tsconfig.json` file.\n\n```jsonc\n// tsconfig.json\n{\n  \"compilerOptions\": {\n    \"types\": [\"zotero-types\"],\n  },\n}\n```\n\nThis is equivalent to the combination of `sandbox` and `xhtml` entries.\n\n3. Use triple-slash directive in your Zotero plugin project's `d.ts` file.\n\nSimilar to the `tsconfig.json` file, you can use the `/// \u003creference path=\"...\" /\u003e` directive to include the type definitions.\n\n```ts\n/// \u003creference types=\"zotero-types/entries/sandbox/index.d.ts\" /\u003e\n```\n\n### Use in Code\n\n```ts\n// Example 1: get Zotero.Item by id\nconst item = Zotero.Items.get(1234);\n\n// Example 2: use XUL.Element type with specific properties\nconst exportFiles = document.querySelector(\n  \"#menu_export_files\",\n) as XULMenuItemElement;\nexportFiles.disabled = true;\n\n// Example 3: use platform APIs (OS)\nconst filepath = \"/path/to/file\";\nif (await IOUtils.exists(filepath)) {\n  let contentRaw = await IOUtils.readUTF8(filepath);\n}\n```\n\n## Contributing\n\nThis type definition only contains frequently used typings and is not complete. Please check the source code of Zotero here: [https://github.com/zotero/zotero](https://github.com/zotero/zotero).\n\nThe `d.ts` files of Zotero are set accordingly to their corresponding file in the Zotero repository.\n\nPlanning to merge to \u003chttps://github.com/DefinitelyTyped/DefinitelyTyped/\u003e\n\nTo release this to the npm package, use `npm run release`.\n\n## Disclaimer\n\nUse this code under MIT License. No warranties are provided. Keep the laws of your locality in mind!\n\nIf you want to change the license, please contact me at \u003cwyzlshx@foxmail.com\u003e\n\nPart of the code of this repo refers to other open-source projects within the allowed scope.\n\n- zotero-better-bibtex(`d.ts`)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwindingwind%2Fzotero-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwindingwind%2Fzotero-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwindingwind%2Fzotero-types/lists"}