{"_id":"@datum_story/qr","name":"@datum_story/qr","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@datum_story/qr","version":"0.2.0","description":"Small TypeScript QR generator for Node.js applications","license":"MIT","type":"module","engines":{"node":">=22"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","test":"pnpm build && node --test test/*.test.mjs","prepack":"pnpm test","example":"pnpm build && node examples/generate.mjs"},"dependencies":{"pngjs":"^7.0.0","qrcode":"^1.5.4"},"devDependencies":{"@types/node":"^22.0.0","@types/pngjs":"^6.0.5","@types/qrcode":"^1.5.5","jsqr":"^1.4.0","typescript":"^5.9.3"},"_id":"@datum_story/qr@0.2.0","_nodeVersion":"22.14.0","_npmVersion":"11.12.0","dist":{"integrity":"sha512-VgCUoYpLI/TwwzAzZt/Disb5GUskZbkWyPqdnwTGLSCtvb1iA34gM4nCXHhApZTvlGhJsax5ZpSvhrx6OYJlsA==","shasum":"9cb224d3063b00ea49e61c2730e4b4141e3b6098","tarball":"https://registry.npmjs.org/@datum_story/qr/-/qr-0.2.0.tgz","fileCount":5,"unpackedSize":14267,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICx2Bat1UkcsQ+89RL3h77/QI74uoAlyRHRwHiqAuwyVAiAcCL1GnAC21IYQX7XCQbATNCicKQBGIMu8FvGAlXxzbQ=="}]},"_npmUser":{"name":"datum_story","email":"datumstory@gmail.com"},"directories":{},"maintainers":[{"name":"datum_story","email":"datumstory@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qr_0.2.0_1788964309045_0.3775451336318527"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-09T14:31:48.822Z","0.2.0":"2026-09-09T14:31:49.175Z","modified":"2026-09-09T14:31:49.488Z"},"maintainers":[{"name":"datum_story","email":"datumstory@gmail.com"}],"description":"Small TypeScript QR generator for Node.js applications","license":"MIT","readme":"# Mini QR — first npm package\n\nA small TypeScript wrapper around [qrcode](https://github.com/soldair/node-qrcode), reusable in WhenWines, SpotRep and future projects. Nothing has been published. The package is named `@datum_story/qr` (version 0.2.0).\n\n## Start here\n\nUse Node.js 22+ and pnpm. Extract this project, open its directory, then run:\n\n```sh\npnpm install\npnpm test\npnpm example\n```\n\nThe example creates `example.svg` and `example.png` with a generic sample icon. To use your own icon, run `pnpm example /absolute/path/to/icon.png`. Try scanning the PNG with your phone. Tests also decode generated PNGs back to their exact original content, including Greek text.\n\n## What you are learning\n\n1. `src/index.ts` defines the public function and TypeScript types.\n2. `pnpm build` compiles these to JavaScript and `.d.ts` declarations in `dist`.\n3. `exports` tells consumers where the compiled module and types live.\n4. `files` limits the release to `dist`, plus npm's automatically included metadata and README.\n5. `pnpm pack` creates the actual installable `.tgz` package.\n6. Publishing uploads that package to npm. Consumer applications execute it locally.\n\nThis release supports ESM imports in Node.js. Use it in Next.js server code with the Node.js runtime; browser components, Edge runtimes and CommonJS `require` are outside this starter's supported API.\n\n## API\n\n```ts\nimport { generateQr } from '@datum_story/qr';\n\nconst svg = await generateQr({\n  content: 'https://whenwines.com/visit',\n  color: '#1d2a22',\n}); // string\n\nconst png = await generateQr({\n  content: 'https://example.com/report/123',\n  format: 'png',\n}); // Uint8Array\n```\n\n| Option | Default | Behaviour |\n| --- | --- | --- |\n| content | Required | Non-empty URL or text, preserved exactly |\n| format | svg | svg returns a string; png returns bytes |\n| color | #000000 | Six-digit opaque hex |\n| background | #ffffff | Six-digit opaque hex |\n| margin | 4 | Quiet zone in modules; integer 4–32 |\n| scale | 8 | PNG pixels per module; integer 1–16 |\n| errorCorrectionLevel | M | L, M, Q or H; forced to H when a logo is supplied |\n| logo | Omitted | PNG bytes; max 2 MiB and 1024 × 1024 pixels |\n\nThe wrapper caps input at 2,953 UTF-8 bytes as a conservative resource limit; actual encodable capacity depends on content and error correction. The underlying encoder rejects content it cannot fit. Empty content, invalid options and identical colours also reject the promise. Choose dark foregrounds on light backgrounds; arbitrary different colours are not a scan guarantee. Check printed codes at their intended size.\n\nGeneration does not fetch URLs, create permanent redirects, track scans or save images. Your application handles destination permissions and any storage. An optional PNG logo is embedded in both output formats. Your app supplies the bytes; no website icon is fetched automatically.\n\n## Test installation before publishing\n\nIn this package directory:\n\n```sh\npnpm pack\n```\n\nThe `prepack` script builds and tests automatically. Use the exact `.tgz` path printed by the command in a separate project:\n\n```sh\npnpm add /absolute/path/to/the-generated-package.tgz\n```\n\nYou can then import `@datum_story/qr`. This exercises the release contents rather than a direct source import.\n\n## Your first npm release\n\nFollow the [official scoped-package publishing guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/). Do this locally with your own npm account.\n\n1. The name is already `@datum_story/qr`. Confirm you are logged in as `datum_story`.\n2. Decide whether the source will be public or restricted. Choose a licence deliberately; `UNLICENSED` is currently a placeholder withholding a licence grant. For an open-source release, add your chosen licence file and update `license`.\n3. Remove `\"private\": true` when ready to publish. This field currently prevents registry publication; it does not select a restricted npm package.\n4. Authenticate and review the release:\n\n```sh\nnpm login\nnpm whoami\nnpm pack --dry-run\n```\n\nInspect the listed files. npm may require additional authentication for publishing; follow its prompts.\n\n5. For a deliberately public release, run:\n\n```sh\nnpm publish --access public\n```\n\nThis makes the package downloadable by anyone. For restricted distribution, follow npm's [private-package guide](https://docs.npmjs.com/creating-and-publishing-private-packages/) instead and confirm account eligibility.\n\n6. In a consuming project:\n\n```sh\npnpm add @datum_story/qr\n```\n\nFor subsequent fixes, bump the version, run the tests and package review, then publish again. npm does not let you reuse a published name/version pair. Update consumers with `pnpm update @datum_story/qr` when ready. During 0.x development, explicitly document breaking changes and update consumers together.\n\n## Suggested first integration\n\nStart with a single server-side QR download in either project. Supply an existing destination URL and return the generated image with `image/svg+xml` or `image/png`. Keep its existing authentication rules. Once that works, reuse exactly the same import in the second project.\n\nReference: [qrcode options and API](https://github.com/soldair/node-qrcode). This package adds shared defaults and input validation; the dependency performs QR encoding.\n\n## Adding your site icon\n\n```ts\nimport { readFile } from 'node:fs/promises';\nimport { generateQr } from '@datum_story/qr';\n\nconst png = await generateQr({\n  content: 'https://whenwines.com/visit',\n  format: 'png',\n  logo: await readFile('public/icon.png'),\n});\n```\n\nThe path is relative to the application's working directory. Supply PNG bytes from whatever asset-loading mechanism your deployment uses. Export SVG or ICO favicons to PNG first; a transparent square PNG of 128–256 pixels is a practical starting point. The icon stays proportional inside a centred padded badge. SVG output retains vector QR modules and embeds the raster logo, so it is self-contained. PNG output uses nearest-neighbour logo resizing.\n\nThe badge covers approximately 18% of the symbol width, including padding. High error correction helps compensate for obscured data, but does not guarantee that every logo/payload/print combination will scan. This version tests short, URL, Greek and longer payloads; check your actual icon and printed output before distributing it.\n\nChanges in 0.2.0: optional logo, PNG validation and composition, self-contained SVG embedding, branded scan tests, and package name updated to @datum_story/qr. The publication guard and licence placeholder remain for the final release preparation.\n","readmeFilename":"README.md","_rev":"1-6a6a22e289b6df89a993ed9d3dbee1eb"}