{"_id":"@carl.fyi/web3","name":"@carl.fyi/web3","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@carl.fyi/web3","version":"0.1.0","description":"Validate Ethereum addresses and turn IPFS content into dependable explorer and gateway links.","type":"module","sideEffects":false,"license":"MIT","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./ethereum":{"types":"./dist/ethereum.d.ts","import":"./dist/ethereum.js"},"./ipfs":{"types":"./dist/ipfs.d.ts","import":"./dist/ipfs.js"}},"gitHead":"8395ae726af204ee2590ca681a8076b73a31a8e7","_id":"@carl.fyi/web3@0.1.0","_nodeVersion":"26.7.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-V2cgmHsgTXDV4CORTxupbTPtLGe/GJylO+/Obt3I753RVogokpVlXZcsvRKMhGwfp3Em+Q+wJ8XhPZyVRLYu7w==","shasum":"17f5c2d922d4ef5c0d694cfbc3496a2483132bf0","tarball":"https://registry.npmjs.org/@carl.fyi/web3/-/web3-0.1.0.tgz","fileCount":15,"unpackedSize":24840,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDAeqHQhkL823tgIbZ2D9+8iT32H94LAaNhWOM+6wGhTQIhAN0+nZat6I4KcZiEUeGjTfU4DIMIsKFOvHJU7WE3k48x"}]},"_npmUser":{"name":"carlfairclough","email":"hi@carlfairclough.me"},"directories":{},"maintainers":[{"name":"carlfairclough","email":"hi@carlfairclough.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/web3_0.1.0_1787903747269_0.15027239437595052"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-28T07:55:46.798Z","0.1.0":"2026-08-28T07:55:47.412Z","modified":"2026-08-28T07:55:47.751Z"},"maintainers":[{"name":"carlfairclough","email":"hi@carlfairclough.me"}],"description":"Validate Ethereum addresses and turn IPFS content into dependable explorer and gateway links.","license":"MIT","readme":"<!-- Generated from package.json and src TSDoc by scripts/generate-tool-documentation.mjs. Do not edit by hand. -->\n\n# @carl.fyi/web3\n\nValidate Ethereum addresses and turn IPFS content into dependable explorer and gateway links.\n\n[Interactive documentation](https://tools.carl.fyi/packages/web3)\n\n## Install\n\n```sh\nnpm install @carl.fyi/web3\n```\n\n## Quick start\n\n```ts\nimport { ethereumAddress, buildBlockExplorerUrl } from \"@carl.fyi/web3\";\n\nconst display = ethereumAddress(\"0x1234567890abcdef1234567890ABCDEF12345678\", {\n  leadingChars: 6,\n  trailingChars: 4,\n});\n\nconst url = buildBlockExplorerUrl(\"https://etherscan.io\", \"address\", \"0x1234\");\n```\n\n## Entry points\n\n| Import                    | Purpose                |\n| ------------------------- | ---------------------- |\n| `@carl.fyi/web3`          | All public exports     |\n| `@carl.fyi/web3/ethereum` | Focused subpath import |\n| `@carl.fyi/web3/ipfs`     | Focused subpath import |\n\nAll entry points are ESM, side-effect-free, and include TypeScript declarations.\n\n## Public API\n\nThis is the complete export inventory. The detailed reference below mirrors the APIs demonstrated on the documentation website; its signatures, descriptions, defaults, errors, and examples are compiled from the package source.\n\n| Export                           | Kind      | Import from               | Description                                                    |\n| -------------------------------- | --------- | ------------------------- | -------------------------------------------------------------- |\n| `BlockExplorerResource`          | type      | `@carl.fyi/web3/ethereum` | Public type exported by this package.                          |\n| `buildBlockExplorerUrl`          | function  | `@carl.fyi/web3/ethereum` | Build an HTTP(S) block-explorer URL for a resource identifier. |\n| `ethereumAddress`                | function  | `@carl.fyi/web3/ethereum` | Validate and truncate an Ethereum address for compact display. |\n| `EthereumAddressOptions`         | interface | `@carl.fyi/web3/ethereum` | Public interface exported by this package.                     |\n| `ethereumAddressStorageKey`      | function  | `@carl.fyi/web3/ethereum` | Public function exported by this package.                      |\n| `isEthereumAddress`              | function  | `@carl.fyi/web3/ethereum` | Public function exported by this package.                      |\n| `truncateEthereumAddress`        | function  | `@carl.fyi/web3/ethereum` | Public function exported by this package.                      |\n| `TruncateEthereumAddressOptions` | type      | `@carl.fyi/web3/ethereum` | Public type exported by this package.                          |\n| `truncateIdentifier`             | function  | `@carl.fyi/web3/ethereum` | Public function exported by this package.                      |\n| `TruncateIdentifierOptions`      | interface | `@carl.fyi/web3/ethereum` | Public interface exported by this package.                     |\n| `IpfsLocation`                   | interface | `@carl.fyi/web3/ipfs`     | Public interface exported by this package.                     |\n| `ipfsToGatewayUrl`               | function  | `@carl.fyi/web3/ipfs`     | Convert a validated IPFS URI or CID into an HTTP gateway URL.  |\n| `parseIpfsUri`                   | function  | `@carl.fyi/web3/ipfs`     | Public function exported by this package.                      |\n\n# API reference\n\n## `@carl.fyi/web3/ethereum`\n\n### `ethereumAddress`\n\n```ts\nethereumAddress(address: string, options?: EthereumAddressOptions): string\n```\n\nValidate and truncate an Ethereum address for compact display.\n\nValidation requires `0x` followed by exactly 40 hexadecimal characters. The original casing is preserved in the display value.\n\n| Parameter                          | Type                     | Description                                                      |\n| ---------------------------------- | ------------------------ | ---------------------------------------------------------------- |\n| `address`                          | `string`                 | Ethereum address to validate and display.                        |\n| `options (optional)`               | `EthereumAddressOptions` | Counts of leading and trailing characters plus separator text.   |\n| `options.leadingChars (optional)`  | `number`                 | Number of leading address characters to preserve. Default: `6`.  |\n| `options.trailingChars (optional)` | `number`                 | Number of trailing address characters to preserve. Default: `4`. |\n| `options.break (optional)`         | `string`                 | Separator inserted between preserved sections. Default: `\"…\"`.   |\n\n**Returns:** The original address when already short enough, otherwise its compact representation.\n\n**Throws**\n\n- A `TypeError` for an invalid address or `RangeError` for invalid character counts.\n\n**Example**\n\n```ts\nimport { ethereumAddress } from \"@carl.fyi/web3\";\n\nconst display = ethereumAddress(\"0x1234567890abcdef1234567890ABCDEF12345678\", {\n  leadingChars: 6,\n  trailingChars: 4,\n});\n```\n\n### `buildBlockExplorerUrl`\n\n```ts\nbuildBlockExplorerUrl(explorerUrl: string, resource: BlockExplorerResource, identifier: string): string\n```\n\nBuild an HTTP(S) block-explorer URL for a resource identifier.\n\nExisting explorer path prefixes are preserved and the identifier is percent-encoded as one path segment.\n\n| Parameter     | Type                    | Description                                            |\n| ------------- | ----------------------- | ------------------------------------------------------ |\n| `explorerUrl` | `string`                | HTTP(S) base URL for the explorer.                     |\n| `resource`    | `BlockExplorerResource` | Explorer resource kind.                                |\n| `identifier`  | `string`                | Address, transaction hash, token, or block identifier. |\n\n**Returns:** A serialised explorer URL.\n\n**Throws**\n\n- A `TypeError` when the explorer URL is not HTTP(S).\n\n**Example**\n\n```ts\nimport { buildBlockExplorerUrl } from \"@carl.fyi/web3\";\n\nconst url = buildBlockExplorerUrl(\"https://etherscan.io\", \"address\", \"0x1234\");\n```\n\n## `@carl.fyi/web3/ipfs`\n\n### `ipfsToGatewayUrl`\n\n```ts\nipfsToGatewayUrl(input: string, options?: { gateway?: string; mode?: \"path\" | \"subdomain\"; }): string\n```\n\nConvert a validated IPFS URI or CID into an HTTP gateway URL.\n\nPaths, query strings, and fragments are preserved. Subdomain mode lowercases the CID for a DNS-safe hostname.\n\n| Parameter                    | Type                                                                                                                                                                                                                  | Description                                                                   |\n| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| `input`                      | `string`                                                                                                                                                                                                              | `ipfs://` URI or bare CID, optionally followed by a path, query, or fragment. |\n| `options (optional)`         | ``{     /** HTTP(S) gateway base URL. @defaultValue `\"https://ipfs.io\"` */     gateway?: string;     /** Place the CID in the URL path or hostname. @defaultValue `\"path\"` */     mode?: \"path\" \\| \"subdomain\";   }`` | Gateway base URL and path-versus-subdomain mode.                              |\n| `options.gateway (optional)` | `string`                                                                                                                                                                                                              | HTTP(S) gateway base URL. Default: `\"https://ipfs.io\"`.                       |\n| `options.mode (optional)`    | `\"path\" \\| \"subdomain\"`                                                                                                                                                                                               | Place the CID in the URL path or hostname. Default: `\"path\"`.                 |\n\n**Returns:** A serialised HTTP(S) gateway URL.\n\n**Throws**\n\n- A `TypeError` for an invalid CID, URI, or non-HTTP gateway.\n\n**Example**\n\n```ts\nimport { ipfsToGatewayUrl } from \"@carl.fyi/web3\";\n\nconst url = ipfsToGatewayUrl(\"ipfs://QmYwAPJzv5CZsnAzt8auVZRnGiRAzrQ1hW8mD9a1B3vL4B/image.png\", {\n  gateway: \"https://ipfs.io\",\n  mode: \"path\",\n});\n```\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md","_rev":"1-f799499a75b538606dd0b01f2fcc2e22"}