{"_id":"@api-hooks/swiftpm","name":"@api-hooks/swiftpm","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@api-hooks/swiftpm","version":"1.0.0","description":"React hooks for the Swift Package Registry and Swift Package Index APIs, built on @tanstack/react-query","keywords":["react","hooks","swiftpm","swift","swift-package-index","swift-package-registry","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/swiftpm"},"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":{"swiftpm-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":"ea4344660aeca384218d881c61572c9feb3e9289","_id":"@api-hooks/swiftpm@1.0.0","_nodeVersion":"22.23.1","_npmVersion":"11.18.0","dist":{"integrity":"sha512-m4xLepAzX7sLT4DLr6KFW8jtUpUHc0Jkf1k/yEa4BkxXxiYjOZrwA0z7HiY9aWpcFBZ0jj78xQBzS0USnNi8sA==","shasum":"12a360d59a2cd929634bb6f3b2863e64ba6f48d1","tarball":"https://registry.npmjs.org/@api-hooks/swiftpm/-/swiftpm-1.0.0.tgz","fileCount":47,"unpackedSize":50150,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICCdh7OX+9gad1D++W07YXamw16r5xIz8TexedryJINfAiEAtkycS5sLsaZ6YAs1lpQrcLH3ygIR4xvmSFdqhuAgkrc="}]},"_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/swiftpm_1.0.0_1783080887221_0.2193339322465897"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T12:14:47.002Z","1.0.0":"2026-07-03T12:14:47.399Z","modified":"2026-07-03T12:14:47.616Z"},"maintainers":[{"name":"pilmee","email":"pilmee@gmail.com"}],"description":"React hooks for the Swift Package Registry and Swift Package Index APIs, built on @tanstack/react-query","homepage":"https://github.com/ElJijuna/api-hooks#readme","keywords":["react","hooks","swiftpm","swift","swift-package-index","swift-package-registry","registry","api","react-query","tanstack"],"repository":{"type":"git","url":"git+https://github.com/ElJijuna/api-hooks.git","directory":"packages/swiftpm"},"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/swiftpm\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 [Swift Package Registry](https://github.com/apple/swift-package-manager/blob/main/Documentation/PackageRegistry/Registry.md) (SE-0292) and [Swift Package Index](https://swiftpackageindex.com) APIs, built on [`swiftpm-api-client`](https://www.npmjs.com/package/swiftpm-api-client) and [`@tanstack/react-query`](https://tanstack.com/query).\n\n[![npm](https://img.shields.io/npm/v/@api-hooks/swiftpm)](https://www.npmjs.com/package/@api-hooks/swiftpm)\n[![npm downloads](https://img.shields.io/npm/dm/@api-hooks/swiftpm)](https://www.npmjs.com/package/@api-hooks/swiftpm)\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/swiftpm @tanstack/react-query\n```\n\n## Setup\n\nWrap your application with a `QueryClientProvider` and a `SwiftPMClientProvider` once at the root:\n\n```tsx\nimport { QueryClient, QueryClientProvider } from '@tanstack/react-query';\nimport { SwiftPMClientProvider } from '@api-hooks/swiftpm';\n\nconst queryClient = new QueryClient();\n\nexport default function App() {\n  return (\n    <QueryClientProvider client={queryClient}>\n      <SwiftPMClientProvider>\n        <YourApp />\n      </SwiftPMClientProvider>\n    </QueryClientProvider>\n  );\n}\n```\n\n`useSwiftPMSearch`/`useSwiftPMSearchInfinite` call the Swift Package Index API, which requires a bearer token. Pass `indexToken` (and optionally `registryUrl`/`indexUrl` for a private registry or self-hosted index) through `SwiftPMClientProvider`:\n\n```tsx\n<SwiftPMClientProvider options={{ indexToken: 'my-spi-token' }}>\n  <YourApp />\n</SwiftPMClientProvider>\n```\n\n`SwiftPMClientProvider` is optional — hooks fall back to a default `SwiftPMClient` when no provider is present, but search will fail without a token.\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. `useSwiftPMSearchInfinite` returns a [`UseInfiniteQueryResult`](https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery).\n\n| Hook | Description | Returns |\n| ---- | ----------- | ------- |\n| [`useSwiftPMPackageReleases(scope, name, options?)`](#useswiftpmpackagereleasesscope-name-options) | All published releases for a package | `SwiftReleasesIndex` |\n| [`useSwiftPMPackageRelease(scope, name, version, options?)`](#useswiftpmpackagereleasescope-name-version-options) | Metadata for a specific release version | `SwiftRelease` |\n| [`useSwiftPMPackageLatest(scope, name, options?)`](#useswiftpmpackagelatestscope-name-options) | Metadata for the latest release | `SwiftRelease` |\n| [`useSwiftPMPackageManifest(scope, name, version, options?)`](#useswiftpmpackagemanifestscope-name-version-options) | Raw `Package.swift` manifest contents | `string` |\n| [`useSwiftPMSearch(params, options?)`](#useswiftpmsearchparams-options) | Search packages via Swift Package Index | `SwiftSearchResult` |\n| [`useSwiftPMSearchInfinite(query, options?)`](#useswiftpmsearchinfinitequery-options) | Infinite-scroll variant of `useSwiftPMSearch` | `InfiniteData<SwiftSearchResult>` |\n| [`useSwiftPMLookupIdentifiers(repositoryURL, options?)`](#useswiftpmlookupidentifiersrepositoryurl-options) | Package identifiers for a repository URL | `SwiftIdentifiersResult` |\n\n---\n\n## API Reference\n\n### `useSwiftPMPackageReleases(scope, name, options?)`\n\nLists all published releases for a Swift package.\n\n```tsx\nimport { useSwiftPMPackageReleases } from '@api-hooks/swiftpm';\n\nfunction ReleaseList() {\n  const { data } = useSwiftPMPackageReleases('apple', 'swift-argument-parser');\n\n  return <ul>{data && Object.keys(data.releases).map(v => <li key={v}>{v}</li>)}</ul>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `scope` or `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useSwiftPMPackageRelease(scope, name, version, options?)`\n\nFetches metadata for a specific release version.\n\n```tsx\nimport { useSwiftPMPackageRelease } from '@api-hooks/swiftpm';\n\nfunction ReleaseDetail() {\n  const { data } = useSwiftPMPackageRelease('apple', 'swift-argument-parser', '1.1.0');\n\n  return <p>{data?.metadata.description}</p>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `scope`, `name`, or `version` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useSwiftPMPackageLatest(scope, name, options?)`\n\nFetches metadata for the latest (highest semver) release of a package.\n\n```tsx\nimport { useSwiftPMPackageLatest } from '@api-hooks/swiftpm';\n\nfunction LatestRelease() {\n  const { data } = useSwiftPMPackageLatest('apple', 'swift-argument-parser');\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 `scope` or `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useSwiftPMPackageManifest(scope, name, version, options?)`\n\nFetches the raw `Package.swift` manifest for a specific release version.\n\n```tsx\nimport { useSwiftPMPackageManifest } from '@api-hooks/swiftpm';\n\nfunction ManifestViewer() {\n  const { data } = useSwiftPMPackageManifest('apple', 'swift-argument-parser', '1.1.0');\n\n  return <pre>{data}</pre>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `scope`, `name`, or `version` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useSwiftPMSearch(params, options?)`\n\nSearches Swift packages using the Swift Package Index API. Requires `indexToken` to be configured via `SwiftPMClientProvider`.\n\n```tsx\nimport { useSwiftPMSearch } from '@api-hooks/swiftpm';\n\nfunction PackageSearch() {\n  const { data, isLoading } = useSwiftPMSearch({ query: 'vapor' });\n\n  if (isLoading) return <p>Loading…</p>;\n\n  return <ul>{data?.results.map(p => <li key={p.packageId}>{p.packageName}</li>)}</ul>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `query` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useSwiftPMSearchInfinite(query, options?)`\n\nInfinite-scroll variant of `useSwiftPMSearch`. Each page advances the 1-based `page` number; continues while `lastPage.hasMoreResults` is `true`. Call `fetchNextPage()` to load the next batch — results accumulate in `data.pages`.\n\n```tsx\nimport { useSwiftPMSearchInfinite } from '@api-hooks/swiftpm';\n\nfunction PackageSearchInfinite() {\n  const { data, fetchNextPage, hasNextPage } = useSwiftPMSearchInfinite('vapor');\n\n  return (\n    <>\n      {data?.pages.flatMap(page => page.results).map(p => (\n        <div key={p.packageId}>{p.packageName}</div>\n      ))}\n      {hasNextPage && <button onClick={() => fetchNextPage()}>Load more</button>}\n    </>\n  );\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `pageSize` | `number` | `undefined` | Results per page |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `query` is empty) |\n| `queryOptions` | `InfiniteQueryOverrides<TData>` | `undefined` | Override TanStack Query options |\n\n---\n\n### `useSwiftPMLookupIdentifiers(repositoryURL, options?)`\n\nLooks up package identifiers by source repository URL.\n\n```tsx\nimport { useSwiftPMLookupIdentifiers } from '@api-hooks/swiftpm';\n\nfunction IdentifierLookup({ url }: { url: string }) {\n  const { data } = useSwiftPMLookupIdentifiers(url);\n\n  return <ul>{data?.identifiers.map(id => <li key={id}>{id}</li>)}</ul>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `repositoryURL` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n## License\n\nMIT © [ElJijuna](https://github.com/ElJijuna)\n","readmeFilename":"README.md","_rev":"1-ff7041693224a7af71afb41010925845"}