{"_id":"@api-hooks/pub","name":"@api-hooks/pub","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@api-hooks/pub","version":"1.0.0","description":"React hooks for the pub.dev REST API, built on @tanstack/react-query","keywords":["react","hooks","pub","pub.dev","dart","flutter","registry","api","react-query","tanstack"],"license":"MIT","homepage":"https://github.com/ElJijuna/api-hooks#readme","repository":{"type":"git","url":"git+https://github.com/ElJijuna/api-hooks.git","directory":"packages/pub"},"bugs":{"url":"https://github.com/ElJijuna/api-hooks/issues"},"publishConfig":{"access":"public"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./types":{"types":"./dist/types.d.ts","import":"./dist/types.js"}},"sideEffects":false,"scripts":{"build":"vite build && tsc --emitDeclarationOnly --declarationMap","dev":"vite build --watch","test":"jest --passWithNoTests","test:coverage":"jest --coverage --passWithNoTests","typecheck":"tsc --noEmit","docs":"typedoc"},"peerDependencies":{"@tanstack/react-query":"^5.0.0","react":">=19.0.0"},"dependencies":{"pub-api-client":"^1.0.0"},"devDependencies":{"@tanstack/react-query":"^5.101.0","@testing-library/react":"^16.3.2","jest":"^30.4.2","jest-environment-jsdom":"^30.4.1","react":"^19.2.7","react-dom":"^19.2.7","typedoc":"^0.28.19","vite":"^8.0.16","vite-magic-tree-shaking":"^1.0.0"},"author":{"name":"pilmee","email":"pilmee@gmail.com","url":"https://github.com/ElJijuna"},"gitHead":"84cccb0247db03a492515479544dae64b4b322d7","_id":"@api-hooks/pub@1.0.0","_nodeVersion":"22.23.1","_npmVersion":"11.18.0","dist":{"integrity":"sha512-i5jf7qjXCOOQ7XG9f6fU900HqXeolv45N3Aq3yzZReOH1v0+O8QFQCAAvufQ/Vg/jMSivFupfS+nCwhkW7M9fQ==","shasum":"f0eaa5b11b40607ff1658bc0a0897390c4d99702","tarball":"https://registry.npmjs.org/@api-hooks/pub/-/pub-1.0.0.tgz","fileCount":47,"unpackedSize":44433,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCFOYpry2GFuxHioZ5cmydqTUZi5B3jrxn4V4nI87VgBQIhAM5s/WSNzFilwCD5XwJZYbE/RLr4lVeYQJ60AAJVINlO"}]},"_npmUser":{"name":"pilmee","email":"pilmee@gmail.com"},"directories":{},"maintainers":[{"name":"pilmee","email":"pilmee@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pub_1.0.0_1783080584174_0.46155817129191035"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T12:09:43.925Z","1.0.0":"2026-07-03T12:09:44.302Z","modified":"2026-07-03T12:09:44.560Z"},"maintainers":[{"name":"pilmee","email":"pilmee@gmail.com"}],"description":"React hooks for the pub.dev REST API, built on @tanstack/react-query","homepage":"https://github.com/ElJijuna/api-hooks#readme","keywords":["react","hooks","pub","pub.dev","dart","flutter","registry","api","react-query","tanstack"],"repository":{"type":"git","url":"git+https://github.com/ElJijuna/api-hooks.git","directory":"packages/pub"},"author":{"name":"pilmee","email":"pilmee@gmail.com","url":"https://github.com/ElJijuna"},"bugs":{"url":"https://github.com/ElJijuna/api-hooks/issues"},"license":"MIT","readme":"# @api-hooks/pub\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/ElJijuna/api-hooks/main/public/assets/api-hooks.png\" alt=\"api-hooks logo\" width=\"240\" />\n</p>\n\nReact hooks for the [pub.dev REST API](https://pub.dev), built on [`pub-api-client`](https://www.npmjs.com/package/pub-api-client) and [`@tanstack/react-query`](https://tanstack.com/query).\n\n[![npm](https://img.shields.io/npm/v/@api-hooks/pub)](https://www.npmjs.com/package/@api-hooks/pub)\n[![npm downloads](https://img.shields.io/npm/dm/@api-hooks/pub)](https://www.npmjs.com/package/@api-hooks/pub)\n[![CI](https://github.com/ElJijuna/api-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/ElJijuna/api-hooks/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n\n## Requirements\n\n| Peer dependency | Version |\n| --------------- | ------- |\n| `react` | `>=19.0.0` |\n| `@tanstack/react-query` | `^5.0.0` |\n\n## Installation\n\n```bash\nnpm install @api-hooks/pub @tanstack/react-query\n```\n\n## Setup\n\nWrap your application with a `QueryClientProvider` and a `PubClientProvider` once at the root:\n\n```tsx\nimport { QueryClient, QueryClientProvider } from '@tanstack/react-query';\nimport { PubClientProvider } from '@api-hooks/pub';\n\nconst queryClient = new QueryClient();\n\nexport default function App() {\n  return (\n    <QueryClientProvider client={queryClient}>\n      <PubClientProvider>\n        <YourApp />\n      </PubClientProvider>\n    </QueryClientProvider>\n  );\n}\n```\n\nBy default, requests go to `pub.dev`. To point at a private/mirrored pub registry, pass `baseUrl` through `PubClientProvider`:\n\n```tsx\n<PubClientProvider options={{ baseUrl: 'https://my-pub-mirror.example.com' }}>\n  <YourApp />\n</PubClientProvider>\n```\n\n`PubClientProvider` is optional — hooks fall back to a default `PubClient` (pointed at `pub.dev`) when no provider is present.\n\n## Hooks\n\nQuery hooks return a [`UseQueryResult`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) — you get the full TanStack Query API: `data`, `isLoading`, `isFetching`, `isError`, `error`, `refetch`, and more. `usePubSearchInfinite` returns a [`UseInfiniteQueryResult`](https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery).\n\n| Hook | Description | Returns |\n| ---- | ----------- | ------- |\n| [`usePubPackageInfo(name, options?)`](#usepubpackageinfoname-options) | Full package info: latest + all versions | `PubPackageInfo` |\n| [`usePubPackageVersions(name, options?)`](#usepubpackageversionsname-options) | All published versions of a package | `PubVersionInfo[]` |\n| [`usePubPackageVersion(name, version, options?)`](#usepubpackageversionname-version-options) | Metadata for a specific version | `PubVersionInfo` |\n| [`usePubPackageLatest(name, options?)`](#usepubpackagelatestname-options) | Metadata for the latest version | `PubVersionInfo` |\n| [`usePubPackageScore(name, options?)`](#usepubpackagescorename-options) | Pub points, likes, popularity score | `PubPackageScore` |\n| [`usePubSearch(params?, options?)`](#usepubsearchparams-options) | Search pub.dev packages | `PubSearchResult` |\n| [`usePubSearchInfinite(options?)`](#usepubsearchinfiniteoptions) | Infinite-scroll variant of `usePubSearch` | `InfiniteData<PubSearchResult>` |\n\n---\n\n## API Reference\n\n### `usePubPackageInfo(name, options?)`\n\nFetches full pub.dev package info, including latest version and all published versions.\n\n```tsx\nimport { usePubPackageInfo } from '@api-hooks/pub';\n\nfunction PackageDetail() {\n  const { data } = usePubPackageInfo('http');\n\n  return <p>Latest: {data?.latest.version}</p>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `usePubPackageVersions(name, options?)`\n\nFetches all published versions of a pub.dev package.\n\n```tsx\nimport { usePubPackageVersions } from '@api-hooks/pub';\n\nfunction VersionList() {\n  const { data } = usePubPackageVersions('http');\n\n  return <ul>{data?.map(v => <li key={v.version}>{v.version}</li>)}</ul>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `usePubPackageVersion(name, version, options?)`\n\nFetches metadata for a specific published version of a pub.dev package.\n\n```tsx\nimport { usePubPackageVersion } from '@api-hooks/pub';\n\nfunction VersionDetail() {\n  const { data } = usePubPackageVersion('http', '1.2.2');\n\n  return <p>Published: {data?.published}</p>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` or `version` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `usePubPackageLatest(name, options?)`\n\nFetches metadata for the latest published version of a pub.dev package.\n\n```tsx\nimport { usePubPackageLatest } from '@api-hooks/pub';\n\nfunction LatestVersion() {\n  const { data } = usePubPackageLatest('http');\n\n  return <p>Latest: {data?.version}</p>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `usePubPackageScore(name, options?)`\n\nFetches pub points, likes, and popularity score for a package.\n\n```tsx\nimport { usePubPackageScore } from '@api-hooks/pub';\n\nfunction ScoreBadge() {\n  const { data } = usePubPackageScore('http');\n\n  return <p>{data?.grantedPoints} / {data?.maxPoints} pub points</p>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `usePubSearch(params?, options?)`\n\nSearches pub.dev packages by text.\n\n```tsx\nimport { usePubSearch } from '@api-hooks/pub';\n\nfunction PackageSearch() {\n  const { data, isLoading } = usePubSearch({ query: 'http client' });\n\n  if (isLoading) return <p>Loading…</p>;\n\n  return <ul>{data?.packages.map(p => <li key={p.package}>{p.package}</li>)}</ul>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `usePubSearchInfinite(options?)`\n\nInfinite-scroll variant of `usePubSearch`. Each page advances the 1-based `page` number; continues while `lastPage.next` is present. Call `fetchNextPage()` to load the next batch — results accumulate in `data.pages`.\n\n```tsx\nimport { usePubSearchInfinite } from '@api-hooks/pub';\n\nfunction PackageSearchInfinite() {\n  const { data, fetchNextPage, hasNextPage } = usePubSearchInfinite({ query: 'json' });\n\n  return (\n    <>\n      {data?.pages.flatMap(page => page.packages).map(p => (\n        <div key={p.package}>{p.package}</div>\n      ))}\n      {hasNextPage && <button onClick={() => fetchNextPage()}>Load more</button>}\n    </>\n  );\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `query` | `string` | `undefined` | Search text |\n| `enabled` | `boolean` | `true` | Disable the query |\n| `queryOptions` | `InfiniteQueryOverrides<TData>` | `undefined` | Override TanStack Query options |\n\n---\n\n## License\n\nMIT © [ElJijuna](https://github.com/ElJijuna)\n","readmeFilename":"README.md","_rev":"1-2a4a5d36bab1f1dd8b23064474b3ba94"}