feat: add AI SDK package tool

README.md

@@ -30,6 +30,12 @@ regxa fills that gap. One `fetchPackage` call, same response shape, regardless o
 pnpm add regxa
 ```
 
+For the AI SDK tool (`regxa/ai` subpath), also install `ai` and `zod`:
+
+```bash
+pnpm add ai zod
+```
+
 ## Quick start
 
 ### API
@@ -69,6 +75,31 @@ regxa deps alpm/aur/paru
 
 Add `--json` for machine-readable output, `--no-cache` to skip the cache.
 
+### AI SDK tool
+
+`regxa/ai` exports a ready-made tool for AI SDK apps:
+
+```ts
+import { generateText } from 'ai'
+import { packageTool } from 'regxa/ai'
+
+const { text } = await generateText({
+  model: yourModel,
+  tools: { packageRegistry: packageTool },
+  prompt: 'Show me the latest metadata for pkg:npm/lodash and then list its maintainers.',
+})
+```
+
+The tool supports these operations through one input schema:
+
+```ts
+// { operation: 'package', purl: 'pkg:npm/lodash' }
+// { operation: 'versions', purl: 'pkg:cargo/serde' }
+// { operation: 'dependencies', purl: 'pkg:pypi/flask@3.1.1' }
+// { operation: 'maintainers', purl: 'pkg:gem/rails' }
+// { operation: 'bulk-packages', purls: ['pkg:npm/lodash', 'pkg:cargo/serde'], concurrency?: number }
+```
+
 ## Registries
 
 | Ecosystem | PURL type | Registry |

build.config.ts

@@ -6,6 +6,7 @@ export default defineBuildConfig({
       type: 'bundle',
       input: [
         './src/index.ts',
+        './src/ai.ts',
         './src/types.ts',
         './src/core/index.ts',
         './src/registries/index.ts',

package.json

@@ -17,6 +17,10 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
     },
+    "./ai": {
+      "types": "./dist/ai.d.mts",
+      "import": "./dist/ai.mjs"
+    },
     "./registries": {
       "types": "./dist/registries/index.d.mts",
       "import": "./dist/registries/index.mjs"
@@ -60,15 +64,29 @@
   ],
   "devDependencies": {
     "@types/node": "^25.3.0",
+    "ai": "^6.0.116",
     "changelogen": "^0.6.2",
     "obuild": "^0.4.31",
     "typescript": "^5.8.3",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "zod": "^4.3.6"
   },
   "dependencies": {
     "citty": "^0.2.1",
     "consola": "^3.4.2",
     "ofetch": "^1.5.1",
     "unstorage": "^1.17.4"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.116",
+    "zod": "^4.3.6"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   }
 }

src/ai.ts

@@ -0,0 +1,56 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+import {
+  bulkFetchPackages,
+  fetchDependenciesFromPURL,
+  fetchMaintainersFromPURL,
+  fetchPackageFromPURL,
+  fetchVersionsFromPURL,
+} from './helpers.ts'
+import './registries/index.ts'
+
+export const packageTool = tool({
+  description: 'Query package metadata from npm, PyPI, crates.io, RubyGems, Packagist, and Arch Linux using PURLs. Supports package info, versions, dependencies, maintainers, and bulk package metadata lookups.',
+  inputSchema: z.discriminatedUnion('operation', [
+    z.object({
+      operation: z.literal('package'),
+      purl: z.string().describe('Package PURL, for example pkg:npm/lodash or pkg:cargo/serde'),
+    }),
+    z.object({
+      operation: z.literal('versions'),
+      purl: z.string().describe('Package PURL, for example pkg:npm/lodash or pkg:cargo/serde'),
+    }),
+    z.object({
+      operation: z.literal('dependencies'),
+      purl: z.string().describe('Package PURL including a version, for example pkg:pypi/flask@3.1.1'),
+    }),
+    z.object({
+      operation: z.literal('maintainers'),
+      purl: z.string().describe('Package PURL, for example pkg:gem/rails or pkg:composer/laravel/framework'),
+    }),
+    z.object({
+      operation: z.literal('bulk-packages'),
+      purls: z.array(z.string()).min(1).max(50).describe('List of package PURLs to fetch in bulk.'),
+      concurrency: z.number().int().min(1).max(50).optional().describe('Maximum concurrent lookups. Defaults to 15.'),
+    }),
+  ]),
+  execute: async (input, { abortSignal }) => {
+    switch (input.operation) {
+      case 'package':
+        return fetchPackageFromPURL(input.purl, abortSignal)
+      case 'versions':
+        return fetchVersionsFromPURL(input.purl, abortSignal)
+      case 'dependencies':
+        return fetchDependenciesFromPURL(input.purl, abortSignal)
+      case 'maintainers':
+        return fetchMaintainersFromPURL(input.purl, abortSignal)
+      case 'bulk-packages': {
+        const results = await bulkFetchPackages(input.purls, {
+          concurrency: input.concurrency,
+          signal: abortSignal,
+        })
+        return Object.fromEntries(results)
+      }
+    }
+  },
+})