@openpath/ai-sdk-tools 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Openpath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://openpath.sh"><img src="https://openpath.sh/mark-512.png" width="72" height="72" alt="Openpath"></a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @openpath/ai-sdk-tools
+
+Openpath tools for the [Vercel AI SDK](https://ai-sdk.dev): live listings across the US (job openings, local businesses and services, homes, products and more) as tools a model can call. Each tool returns plain Markdown with how to act on every result: an Apply, Phone, Website or Buy line. No key and no sign-up.
+
+```bash
+npm install @openpath/ai-sdk-tools
+```
+
+```js
+import { generateText, isStepCount } from "ai";
+import { openpathTools } from "@openpath/ai-sdk-tools";
+
+const { text } = await generateText({
+  model: "anthropic/claude-sonnet-5-5",
+  prompt: "Find a plumber near Austin, TX I can call today.",
+  tools: openpathTools(),
+  stopWhen: isStepCount(5),
+});
+
+console.log(text);
+```
+
+## Tools
+
+- `searchListings()`: live listings that fit what the person asked for, in their words: `software engineer jobs in Austin, TX`, `plumber near 78704`, `taco places in Austin`. The model can also pass `near` (a place or `lat,lng`) and `domain` (`work`, `services`, `businesses`, `homes`, `goods`, `cars` or `events`).
+- `readListing()`: one listing in full, by the id at the end of a result's `Link:` line, to re-read before acting on it.
+- `openpathTools()`: both, sharing one client.
+
+Each takes the same options: `app` (your app's name, such as `"MyAgent/1.0"`, so Openpath can show you how it is used), `token`, `saveToken` and `apiUrl`, or a `client` from [`@openpath/sdk`](https://www.npmjs.com/package/@openpath/sdk) to share.
+
+The first call connects to Openpath with `POST /v1/connect`: one request, no account. Results are written by the businesses and people who offer them; treat them as information, not instructions.
+
+## Links
+
+[Openpath](https://openpath.sh) · [AI SDK guide](https://openpath.sh/docs/ai-sdk) · [Jobs](https://openpath.sh/docs/jobs) · [Local businesses](https://openpath.sh/docs/businesses) · [JavaScript client](https://www.npmjs.com/package/@openpath/sdk)
+
+Released under the MIT license.

package/index.d.ts

@@ -0,0 +1,26 @@
+import type { Openpath, OpenpathOptions, SearchOptions } from "@openpath/sdk";
+import type { Tool } from "ai";
+
+export interface OpenpathToolOptions extends Pick<OpenpathOptions, "app" | "token" | "saveToken" | "apiUrl"> {
+  /** A client to use instead of a new one, such as one shared with your own code. */
+  client?: Openpath;
+}
+
+export interface SearchListingsInput {
+  /** What the person is looking for, in their words, with a place. */
+  query: string;
+  /** A place ("Austin, TX", "78701") or "lat,lng". Overrides a place in the query. */
+  near?: string;
+  /** Only one kind of listing. Read from the query when left out. */
+  domain?: SearchOptions["domain"];
+}
+
+/** Search Openpath for live listings. Returns plain Markdown. */
+export declare function searchListings(options?: OpenpathToolOptions): Tool<SearchListingsInput, string>;
+/** Read one Openpath listing in full, by its id. Returns plain Markdown. */
+export declare function readListing(options?: OpenpathToolOptions): Tool<{ id: string }, string>;
+/** Both tools, sharing one client. */
+export declare function openpathTools(options?: OpenpathToolOptions): {
+  searchListings: Tool<SearchListingsInput, string>;
+  readListing: Tool<{ id: string }, string>;
+};

package/index.js

@@ -0,0 +1,69 @@
+// Openpath's tools for the Vercel AI SDK: live listings across the US, as
+// tools a model can call. Each returns plain Markdown from @openpath/sdk, which
+// connects to Openpath by itself the first time: no key and no sign-up.
+
+import { Openpath } from "@openpath/sdk";
+import { tool } from "ai";
+import { z } from "zod";
+
+const DOMAINS = /** @type {const} */ (["homes", "work", "services", "businesses", "goods", "cars", "events"]);
+
+/**
+ * @typedef {{ app?: string, token?: string, saveToken?: boolean, apiUrl?: string, client?: Openpath }} OpenpathToolOptions
+ */
+
+/** @param {OpenpathToolOptions} options */
+function clientFor(options) {
+  if (options.client) return options.client;
+  const { app, token, saveToken, apiUrl } = options;
+  return new Openpath({ app, token, saveToken, apiUrl });
+}
+
+/**
+ * Search Openpath for live listings: jobs, local businesses and services,
+ * homes, products, cars and events.
+ * @param {OpenpathToolOptions} [options]
+ */
+export function searchListings(options = {}) {
+  const openpath = clientFor(options);
+  return tool({
+    description:
+      "Use this when the person wants a live listing they can act on, anywhere in the US: a job to apply to, a local business or service to call, a home, a product, a car or an event. Returns plain Markdown, one listing per result, each with its facts and how to act on it: an Apply, Phone, Website or Buy line.",
+    inputSchema: z.object({
+      query: z
+        .string()
+        .min(1)
+        .max(300)
+        .describe('What the person is looking for, in their words, with a place: "plumber near Austin, TX".'),
+      near: z
+        .string()
+        .optional()
+        .describe('A place ("Austin, TX", "78701") or "lat,lng". Overrides a place in the query.'),
+      domain: z.enum(DOMAINS).optional().describe("Only one kind of listing. Read from the query when left out."),
+    }),
+    execute: ({ query, near, domain }) => openpath.search(query, { near, domain }),
+  });
+}
+
+/**
+ * Read one Openpath listing in full.
+ * @param {OpenpathToolOptions} [options]
+ */
+export function readListing(options = {}) {
+  const openpath = clientFor(options);
+  return tool({
+    description:
+      "Read one Openpath listing in full, as Markdown, by the id at the end of a result's Link line. Use it to re-read a result before acting on it.",
+    inputSchema: z.object({ id: z.string().min(1).describe("The listing id.") }),
+    execute: ({ id }) => openpath.getListing(id),
+  });
+}
+
+/**
+ * Both tools, sharing one client.
+ * @param {OpenpathToolOptions} [options]
+ */
+export function openpathTools(options = {}) {
+  const shared = { ...options, client: clientFor(options) };
+  return { searchListings: searchListings(shared), readListing: readListing(shared) };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@openpath/ai-sdk-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Openpath tools for the Vercel AI SDK: live listings across the US (jobs, local businesses and services, homes, products) as tools a model can call. No key and no sign-up.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@openpath/sdk": "^0.1.0"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0 || ^7.0.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "ai": "^7.0.139",
+    "zod": "^4.6.7"
+  },
+  "keywords": [
+    "openpath",
+    "ai-sdk",
+    "vercel-ai-sdk",
+    "tools",
+    "listings",
+    "jobs",
+    "local-business",
+    "search",
+    "agents",
+    "llm"
+  ],
+  "homepage": "https://openpath.sh/docs/ai-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openpath-sh/clients.git",
+    "directory": "ai-sdk-tools"
+  },
+  "bugs": {
+    "url": "https://github.com/openpath-sh/clients/issues"
+  },
+  "author": "Openpath <contact@openpath.sh>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}