{"id":15423443,"url":"https://github.com/jmandel/shlinker","last_synced_at":"2025-08-20T07:22:58.780Z","repository":{"id":236401503,"uuid":"792541989","full_name":"jmandel/shlinker","owner":"jmandel","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-18T23:32:42.000Z","size":84,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-20T00:52:57.837Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/jmandel.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":"2024-04-26T22:21:21.000Z","updated_at":"2024-05-18T21:07:20.000Z","dependencies_parsed_at":"2024-04-26T23:26:19.761Z","dependency_job_id":"9e12c422-6792-4d4f-9cdf-36987f9e4cbf","html_url":"https://github.com/jmandel/shlinker","commit_stats":{"total_commits":28,"total_committers":1,"mean_commits":28.0,"dds":0.0,"last_synced_commit":"58b5590e2df4a88f237dcadcf352610618c686e5"},"previous_names":["jmandel/shlinker"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmandel%2Fshlinker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmandel%2Fshlinker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmandel%2Fshlinker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmandel%2Fshlinker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmandel","download_url":"https://codeload.github.com/jmandel/shlinker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245643237,"owners_count":20649003,"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":[],"created_at":"2024-10-01T17:43:08.331Z","updated_at":"2025-03-26T11:27:03.307Z","avatar_url":"https://github.com/jmandel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SHLinker: SMART Health Links Processing Library\n\nSHLinker helps web applications work with SMART Health Links and display them consistently. It provides functions to parse, retrieve, and render SHLinks, making it easy to integrate SHLink functionality into your projects.\n\n## Key Features\n\n- Parse SHLinks and extract relevant information\n- Retrieve files associated with SHLinks\n- Render SHLink widgets with customizable options\n- Decrypt and handle different file types (FHIR, SMART Health Cards)\n- TypeScript support for enhanced developer experience\n\n## Static Example\n\nIf you don't want to use a build process, you can always download or link to our CSS and JavaScript files:\n\n![image](https://github.com/jmandel/shlinker/assets/313089/b7fb7273-d23f-4c39-a292-ec7511c0302d)\n\n```html\n\u003c!doctype html\u003e\n\u003chtml lang=\"en\"\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"UTF-8\" /\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" /\u003e\n    \u003ctitle\u003eSHLinker Test\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv id=\"main\"\u003e\u003c/div\u003e\n    \u003cscript type=\"module\"\u003e\n      import * as shlink from \"https://cdn.jsdelivr.net/npm/shlinker@0.2.1/dist/shlinker.js\";\n      // ^^ Or download and use a local copy\n\n      // pass a shl directly, or let the library parse it from window.location\n      const parsed = await shlink.parse(\"https://joshuamandel.com/cgm/#shlink:/eyJ1cmwiOiJodHRwczovL2pvc2h1YW1hbmRlbC5jb20vY2dtL3NobC8xMjBkYXlfYWdwX2J1bmRsZV91bmd1ZXNzYWJsZV9zaGxfaWQwMDAwMDAwIiwiZmxhZyI6IkxVIiwia2V5IjoiYWdwX29ic191bmd1ZXNzYWJsZV9yYW5kb21fa2V5MDAwMDAwMDAwMDAwMCIsImxhYmVsIjoiSm9zaCdzIENHTSBEYXRhIn0\");\n      const retrieved = await shlink.retrieve(parsed)\n      const main = document.getElementById(\"main\")\n      shlink.render(retrieved, main, { showDetails: true })\n    \u003c/script\u003e\n    \u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/shlinker@0.2.1/dist/shlinker.css\" /\u003e\n    \u003c!-- ^^ Or download and use a local copy --/\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Installation\n\nIf you're using a build process, install the library using npm or its ilk:\n\n```bash\nnpm install shlinker\n```\n\nor\n\n```bash\nbun install shlinker\n```\n\n## Usage\n\nImport the library and use its functions:\n\n```typescript\nimport { parse, retrieve, render } from 'shlinker';\n\n// Parse an SHLink\nconst shlinkData = parse('shlink:/...');\n\n// Retrieve files associated with the SHLink\nconst retrievedData = await retrieve(shlinkData, { recipient: 'John Doe' });\n\n// Render the SHLink widget\nconst container = document.getElementById('shlink-container');\nrender(retrievedData, container, { showDetails: true });\n```\n\n## API Reference\n\n### `parse(shlink?: string): SHLinkData`\n\nParses an SHLink and extracts relevant information.\n\n- `shlink` (optional): The SHLink to parse. If not provided, the current page URL will be used.\n\nReturns an `SHLinkData` object containing the parsed information.\n\n### `retrieve(shlinkData: SHLinkData, options?: RetrieveOptions): Promise\u003cSHLinkData\u003e`\n\nRetrieves files associated with an SHLink.\n\n- `shlinkData`: The parsed SHLink data obtained from `parse()`.\n- `options` (optional): Additional options for file retrieval.\n  - `recipient` (optional): The recipient of the SHLink.\n  - `passcode` (optional): The passcode required to access the SHLink files.\n\nReturns a promise that resolves to an updated `SHLinkData` object with the retrieved files.\n\n### `render(shlinkData: SHLinkData, container: Element, config?: RenderConfig): void`\n\nRenders the SHLink widget using the provided SHLink data.\n\n- `shlinkData`: The parsed SHLink data obtained from `parse()` or `retrieve()`.\n- `container`: The DOM element where the SHLink widget will be rendered.\n- `config` (optional): Configuration options for rendering the SHLink widget.\n  - `showDetails` (optional): Determines whether to show additional details in the widget. Default is `true`.\n  - `showButtons` (optional): Array of buttons to show in the widget. Can include `copy`, `download`, `share`, and `qr`. If not specified, all buttons are shown.\n  - `viewerPrefix` (optional): The prefix to use when generating the SHLink URL for viewing.\n  - `qrStartsOpen` (optional): Set to `true` to display the QR code initially. Default is `false`.\n  - `logoOverride` (optional): URL to override the default SMART logo. Set to `null` to remove the logo.\n  - `logoBottom` (optional): URL to add a logo at the bottom of the widget. Set to `null` to remove the bottom logo.\n\n## Customization\n\nThe `render()` function accepts a `RenderConfig` object that allows you to customize the rendering of the SHLink widget.\n\n- `showDetails` (optional): Set to `true` to display additional details such as label, file count, and total size. Default is `true`.\n- `showButtons` (optional): Array of buttons to show in the widget. Can include `copy`, `download`, `share`, and `qr`. If not specified, all buttons are shown.\n- `viewerPrefix` (optional): Specify a custom prefix to use when rendering the SHLink URL for copy-to-clipboard or QR display. Default is the original prefix from the parsed SHLink. Pass `null` to explicitly strip any prefix from the link.\n- `qrStartsOpen` (optional): Set to `true` to display the QR code initially. Default is `false`.\n- `logoOverride` (optional): URL to override the default SMART logo. Set to `null` to remove the logo.\n- `logoBottom` (optional): URL to add a logo at the bottom of the widget. Set to `null` to remove the bottom logo.\n\nExample:\n\n```typescript\nrender(shlinkData, container, {\n  showDetails: false,\n  viewerPrefix: 'https://example.com/viewer',\n  showButtons: ['copy', 'download'],\n  qrStartsOpen: true,\n  logoOverride: 'https://example.com/custom-logo.png',\n  logoBottom: 'https://example.com/bottom-logo.png',\n});\n```\n\n### CSS\n\nYou can use our supplied CSS to style the widget based on `.class`, or you can customize the styling. Either way, include a `shlinker.css` in your page. See [`src/shlinker.css`](./src/shlinker.css).\n\n### Sizing\n\nIf you render the widget into an explicitly sized div, it will adjust to fit.\n\n## Contributing\n\nContributions to the SMART Health Links Processing Library are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the library's GitHub repository.\n\n## License\n\nThis library is released under the [MIT License](https://opensource.org/licenses/MIT).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmandel%2Fshlinker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmandel%2Fshlinker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmandel%2Fshlinker/lists"}