{"_id":"@1001-digital/natspec","_rev":"2-8058517378df9ac43965468e6a55da81","name":"@1001-digital/natspec","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@1001-digital/natspec","version":"0.0.1","license":"MIT","_id":"@1001-digital/natspec@0.0.1","maintainers":[{"name":"jwahdatehagh","email":"jalil@1001.digital"}],"homepage":"https://github.com/1001-digital/natspec#readme","bugs":{"url":"https://github.com/1001-digital/natspec/issues"},"dist":{"shasum":"c10b5580c8032dbfcd909c27dc81a460136a6a3f","tarball":"https://registry.npmjs.org/@1001-digital/natspec/-/natspec-0.0.1.tgz","fileCount":11,"integrity":"sha512-4rXB8iefhPIjonLSgV/BMyT2bFjX9GDPR08GIqDevSr+W2jML5RVW5LGlhaVkd5LRrcXjiwhhQptf3Qa42FIVg==","signatures":[{"sig":"MEYCIQCLP/CVetVslC4YIRXJJfHJfIDMma/Aj8HlGeS2i1QPAAIhAPu1idx8SwielOfuTN/h/CbvZOuhbyXZL+0+D3PSBcSB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30556},"main":"./dist/index.js","type":"module","_from":"file:1001-digital-natspec-0.0.1.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"vite build","changeset":"changeset","test:watch":"vitest"},"_npmUser":{"name":"jwahdatehagh","email":"jalil@1001.digital"},"_resolved":"/tmp/ad66396794d2feeddc23933eae285ea2/1001-digital-natspec-0.0.1.tgz","_integrity":"sha512-4rXB8iefhPIjonLSgV/BMyT2bFjX9GDPR08GIqDevSr+W2jML5RVW5LGlhaVkd5LRrcXjiwhhQptf3Qa42FIVg==","repository":{"url":"git+https://github.com/1001-digital/natspec.git","type":"git"},"_npmVersion":"11.11.0","description":"Fetch and normalize NatSpec (userdoc/devdoc) documentation from [Sourcify](https://sourcify.dev) for any verified smart contract.","directories":{},"_nodeVersion":"24.14.1","_hasShrinkwrap":false,"devDependencies":{"vite":"^6.0.0","vitest":"^3.0.0","@changesets/cli":"^2.30.0","vite-plugin-dts":"^4.0.0","@changesets/changelog-github":"^0.6.0"},"_npmOperationalInternal":{"tmp":"tmp/natspec_0.0.1_1775642849916_0.1536725972070514","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@1001-digital/natspec","version":"0.1.0","license":"MIT","repository":{"type":"git","url":"git+https://github.com/1001-digital/natspec.git"},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"main":"./dist/index.js","types":"./dist/index.d.ts","devDependencies":{"@changesets/changelog-github":"^0.6.0","@changesets/cli":"^2.30.0","vite":"^6.0.0","vite-plugin-dts":"^4.0.0","vitest":"^3.0.0"},"scripts":{"build":"vite build","test":"vitest run","test:watch":"vitest","changeset":"changeset"},"_id":"@1001-digital/natspec@0.1.0","description":"Fetch and normalize NatSpec (userdoc/devdoc) documentation from [Sourcify](https://sourcify.dev) for any verified smart contract.","bugs":{"url":"https://github.com/1001-digital/natspec/issues"},"homepage":"https://github.com/1001-digital/natspec#readme","_integrity":"sha512-ryf+rjlmPPGoOMNktj4vrIvKmE3DNd7Un/0M9yKgtyB3oPC4vYhRoYhowX4uXep5iyBlB6zpOm73zSBsNX+PKg==","_resolved":"/tmp/7d9ba230a1a8425847617eadbc7dadb9/1001-digital-natspec-0.1.0.tgz","_from":"file:1001-digital-natspec-0.1.0.tgz","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-ryf+rjlmPPGoOMNktj4vrIvKmE3DNd7Un/0M9yKgtyB3oPC4vYhRoYhowX4uXep5iyBlB6zpOm73zSBsNX+PKg==","shasum":"dff278270773af0a58bec4a55d375ddd6aa140d2","tarball":"https://registry.npmjs.org/@1001-digital/natspec/-/natspec-0.1.0.tgz","fileCount":11,"unpackedSize":31803,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDNkJIm9/hMh8JQtarF1W75+1mX/2sK8OPlKjvuLDB96QIhAP6JUFXjrC30taeX91iVv985ii7bQcvlXYUpZT5PcEmr"}]},"_npmUser":{"name":"jwahdatehagh","email":"jalil@1001.digital"},"directories":{},"maintainers":[{"name":"jwahdatehagh","email":"jalil@1001.digital"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/natspec_0.1.0_1775665143586_0.36315163230684955"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-08T10:07:29.783Z","modified":"2026-04-08T16:19:03.863Z","0.0.1":"2026-04-08T10:07:30.054Z","0.1.0":"2026-04-08T16:19:03.745Z"},"bugs":{"url":"https://github.com/1001-digital/natspec/issues"},"license":"MIT","homepage":"https://github.com/1001-digital/natspec#readme","repository":{"type":"git","url":"git+https://github.com/1001-digital/natspec.git"},"description":"Fetch and normalize NatSpec (userdoc/devdoc) documentation from [Sourcify](https://sourcify.dev) for any verified smart contract.","maintainers":[{"name":"jwahdatehagh","email":"jalil@1001.digital"}],"readme":"# @1001-digital/natspec\n\nFetch and normalize NatSpec (userdoc/devdoc) documentation from [Sourcify](https://sourcify.dev) for any verified smart contract.\n\n## Install\n\n```bash\npnpm add @1001-digital/natspec\n```\n\n## Usage\n\n### Fetch NatSpec from Sourcify\n\n```ts\nimport { createNatSpec } from '@1001-digital/natspec'\n\nconst natspec = createNatSpec()\n\n// Fetch + parse in one step\nconst result = await natspec.fetch(1, '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2')\n\nconsole.log(result.functions.deposit)\n// {\n//   signature: 'deposit()',\n//   name: 'deposit',\n//   notice: 'Deposit ETH and receive WETH',\n// }\n```\n\n### Parse raw userdoc/devdoc\n\nIf you already have the userdoc and devdoc (e.g. from compiler output), use `parse` directly:\n\n```ts\nimport { parse } from '@1001-digital/natspec'\n\nconst result = parse(userdoc, devdoc)\n```\n\n### Convert to contract-metadata format\n\nConvert parsed NatSpec to a shape compatible with the [contract-metadata](https://github.com/1001-digital/contract-metadata) standard:\n\n```ts\nimport { createNatSpec } from '@1001-digital/natspec'\n\nconst natspec = createNatSpec()\nconst result = await natspec.fetch(1, '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2')\nconst metadata = natspec.toMetadata(result)\n\nconsole.log(metadata.functions?.deposit)\n// {\n//   description: 'Deposit ETH and receive WETH',\n// }\n```\n\n## API\n\n### `createNatSpec(config?)`\n\nCreates a NatSpec client.\n\n**Config options:**\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `baseUrl` | `string` | `'https://sourcify.dev/server'` | Sourcify API base URL |\n| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch function |\n\n**Returns** a `NatSpecClient` with:\n\n- **`fetch(chainId, address)`** — Fetches userdoc + devdoc from Sourcify and returns normalized `NatSpec`\n- **`parse(userdoc, devdoc)`** — Pure function. Merges raw userdoc/devdoc into normalized `NatSpec`\n- **`toMetadata(natspec)`** — Pure function. Converts `NatSpec` to `NatSpecMetadata` (contract-metadata compatible)\n\n### `parse(userdoc, devdoc)`\n\nAlso exported directly for standalone use without the factory.\n\n### `toMetadata(natspec)`\n\nAlso exported directly for standalone use.\n\n## Output shapes\n\n### `NatSpec` (normalized intermediate)\n\n```ts\n{\n  contract?: { title?, author?, notice?, details? }\n  functions: Record<string, {\n    signature: string      // e.g. 'transfer(address,uint256)'\n    name: string           // e.g. 'transfer'\n    notice?: string        // from @notice (user-facing)\n    details?: string       // from @dev (developer-facing)\n    params?: Record<string, string>\n    returns?: Record<string, string>\n  }>\n  events: Record<string, { ... }>   // same shape minus returns\n  errors: Record<string, { ... }>   // same shape minus returns\n}\n```\n\n### `NatSpecMetadata` (contract-metadata compatible)\n\n```ts\n{\n  functions?: Record<string, {\n    description?: string\n    params?: Record<string, { description: string }>\n    returns?: Record<string, { description: string }>\n  }>\n  events?: Record<string, { ... }>\n  errors?: Record<string, { ... }>\n}\n```\n\n### Overloaded functions\n\nFunctions with the same name but different parameters use the full Solidity signature as key:\n\n```ts\nresult.functions['safeTransferFrom(address,address,uint256)']\nresult.functions['safeTransferFrom(address,address,uint256,bytes)']\n```\n\nNon-overloaded functions use the bare name:\n\n```ts\nresult.functions['transfer']\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}