From 175c46926913f0eaf775ccd8b12f41ccd0f85ffe Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 15:16:06 -1000 Subject: [PATCH 1/5] Prepare 0.4.0 for @diffbot/typescript 0.6.0. DQL stays on the SDK helper. A missing crawl job is reported instead of stringifying undefined, and chat roles match the narrowed SDK type. The lockfile still resolves the published 0.3.0 tarball until npm update @diffbot/typescript after 0.6.0 is on npm. Co-authored-by: Cursor --- README.md | 2 +- extensions/index.ts | 32 +++++++++++++++++++++++++++--- package-lock.json | 6 +++--- package.json | 4 ++-- skills/diffbot-web-search/SKILL.md | 2 +- 5 files changed, 36 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 01a34ea..7f382f3 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ pi -e . pi install . ``` -Depends on [`@diffbot/typescript`](https://www.npmjs.com/package/@diffbot/typescript) from npm. +0.4.0 depends on [`@diffbot/typescript`](https://www.npmjs.com/package/@diffbot/typescript) ^0.6.0. DQL goes through the SDK `dql()` helper, which posts a JSON body; the token stays a query parameter. `package-lock.json` still records the published 0.3.0 tarball — run `npm update @diffbot/typescript` once 0.6.0 is on npm. A missing crawl job from `crawlGetJob()` is `undefined`. ## Package layout diff --git a/extensions/index.ts b/extensions/index.ts index 44a630a..227b833 100644 --- a/extensions/index.ts +++ b/extensions/index.ts @@ -14,6 +14,8 @@ import { entities, extract, webSearch, + type ChatMessage, + type ExportFormat, type JsonObject, } from "@diffbot/typescript"; import { FileOntologyStore, resolveToken } from "@diffbot/typescript/node"; @@ -65,6 +67,23 @@ function fail( }; } +const EXPORT_FORMATS = ["json", "csv", "xls", "xlsx", "jsonl"] as const; + +function asExportFormat(value: string | undefined): ExportFormat { + if (value === undefined || value === "json") return "json"; + if ((EXPORT_FORMATS as readonly string[]).includes(value)) return value as ExportFormat; + throw new Error(`Unsupported format "${value}". Use json, csv, xls, xlsx, or jsonl.`); +} + +function toChatMessages(messages: Array<{ role: string; content: string }>): ChatMessage[] { + return messages.map((message) => { + if (message.role !== "system" && message.role !== "user" && message.role !== "assistant") { + throw new Error(`Message role must be system, user, or assistant (got "${message.role}")`); + } + return { role: message.role, content: message.content }; + }); +} + function asObject(value: unknown): JsonObject { return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonObject) @@ -159,7 +178,7 @@ export default function (pi: ExtensionAPI) { async execute(_toolCallId, params, _signal, _onUpdate, _ctx) { try { const db = getClient(); - const format = params.format ?? "json"; + const format = asExportFormat(params.format); // The API rejects `;`-joined bare field paths (422). If the filter is // not JsonPath (no `$`), convert `;`-separated field names into the // space-separated dot-notation form the API expects. @@ -448,15 +467,16 @@ export default function (pi: ExtensionAPI) { }), async execute(_toolCallId, params, signal, _onUpdate, _ctx) { try { - const messages = + const drafted = params.messages && params.messages.length > 0 ? params.messages : params.prompt ? [{ role: "user", content: params.prompt }] : null; - if (!messages) { + if (!drafted) { throw new Error("Provide prompt or messages"); } + const messages = toChatMessages(drafted); const db = getClient(); if (params.schema) { const answer = await askJson(db, messages, params.schema as JsonObject); @@ -574,6 +594,12 @@ export default function (pi: ExtensionAPI) { ? await crawlGetJob(db, params.jobName) : await crawlListJobs(db); await db.close(); + if (params.jobName && data === undefined) { + return fail( + "diffbot_crawl_jobs", + new Error(`No crawl job named "${params.jobName}"`), + ); + } return ok(formatJson(data)); } catch (err) { return fail("diffbot_crawl_jobs", err); diff --git a/package-lock.json b/package-lock.json index 72ba87e..729f898 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,15 +1,15 @@ { "name": "@diffbot/pi", - "version": "0.3.0", + "version": "0.4.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@diffbot/pi", - "version": "0.3.0", + "version": "0.4.0", "license": "MIT", "dependencies": { - "@diffbot/typescript": "^0.3.0" + "@diffbot/typescript": "^0.6.0" }, "devDependencies": { "@earendil-works/pi-coding-agent": "^0.80.10", diff --git a/package.json b/package.json index 6a49c9e..9fc72f3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@diffbot/pi", - "version": "0.3.0", + "version": "0.4.0", "description": "Pi package for Diffbot — structured web knowledge tools for the Pi coding agent", "type": "module", "license": "MIT", @@ -39,7 +39,7 @@ "typecheck": "tsc --noEmit" }, "dependencies": { - "@diffbot/typescript": "^0.3.0" + "@diffbot/typescript": "^0.6.0" }, "peerDependencies": { "@earendil-works/pi-coding-agent": "*", diff --git a/skills/diffbot-web-search/SKILL.md b/skills/diffbot-web-search/SKILL.md index a91df08..de15fc9 100644 --- a/skills/diffbot-web-search/SKILL.md +++ b/skills/diffbot-web-search/SKILL.md @@ -90,7 +90,7 @@ current state matters. | `maxTokens` | none | Caps total response tokens — trims from the bottom of the ranking | | `snippetLength` | `long` | `short`, `medium`, `long` or `full`: how much of each page's matching content comes back in `content`. **Always pass `"short"` for searches** — ~1–1.5 KB per result instead of 2.5–6 KB, and the matching sentence is still in the chunk. **Pass `"full"` for a `url:` read** of one whole page; it disables reranking, so query terms are ignored | -Requires `@diffbot/typescript` >= 0.3.0 (`snippetLength` was added in 0.3.0). +Requires `@diffbot/typescript` ^0.6.0 (`snippetLength` was added in 0.3.0). ## Workflow From d1e97e9044aac4dee7fbab375cd9a21856bf06a7 Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 16:43:08 -1000 Subject: [PATCH 2/5] Add trusted-publishing Release workflow and release docs Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/release.yml | 94 +++++++++++++++++++++++++++++++++++ README.md | 12 +++++ 2 files changed, 106 insertions(+) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..1264048 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,94 @@ +name: Release + +# Publishes @diffbot/pi to npm via trusted publishing (OIDC; no NPM_TOKEN). +# Triggered by pushing a version tag (e.g. v0.4.0). workflow_dispatch runs the +# gates and `npm publish --dry-run` only; the publish job runs for tag pushes. +on: + push: + tags: ["v*"] + workflow_dispatch: + +# Never cancel an in-flight run: cancelling a publish midway could leave npm +# and the GitHub Release out of sync. Runs for the same ref queue instead. +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + verify: + name: Verify and dry-run + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + steps: + - uses: actions/checkout@v5 + + - uses: actions/setup-node@v5 + with: + node-version: 22 + cache: npm + + # The tag must match package.json so the GitHub Release can never + # disagree with the version published to npm. (No VERSION constant in + # this repo's sources.) + - name: Check tag matches package version + if: startsWith(github.ref, 'refs/tags/') + run: | + pkg=$(node -p "require('./package.json').version") + tag="${GITHUB_REF_NAME#v}" + if [ "$pkg" != "$tag" ]; then + echo "::error::Tag ${GITHUB_REF_NAME} does not match package.json version ${pkg}. Bump package.json and re-tag." + exit 1 + fi + echo "Tag and package version agree: ${pkg}" + + # Same gates as ci.yml (typecheck is the only one; the repo has no + # lint or test scripts and no live tests). + - run: npm ci + - run: npm run typecheck + + # The package ships TypeScript sources (extensions/, skills/), so there + # is no build step. + - name: Publish dry run + run: npm publish --dry-run --access public + + publish: + name: Publish to npm and GitHub + needs: verify + if: startsWith(github.ref, 'refs/tags/') + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write + # Required for npm trusted publishing and provenance attestation. + id-token: write + steps: + - uses: actions/checkout@v5 + + - uses: actions/setup-node@v5 + with: + node-version: 22 + registry-url: "https://registry.npmjs.org" + + # Trusted publishing needs npm >= 11.5.1; Node 22 ships older. + - name: Update npm + run: | + npm install -g npm@latest + npm --version + + # No token: npm authenticates via the trusted publisher configured on + # npmjs.com (org diffbot, repo diffbot-pi, workflow release.yml). + - name: Publish to npm + run: npm publish --access public --provenance + + - name: Create GitHub Release + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then + echo "Release $GITHUB_REF_NAME already exists; skipping." + else + gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --generate-notes --verify-tag + fi diff --git a/README.md b/README.md index 7f382f3..1dc8ab6 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,18 @@ pi install . 0.4.0 depends on [`@diffbot/typescript`](https://www.npmjs.com/package/@diffbot/typescript) ^0.6.0. DQL goes through the SDK `dql()` helper, which posts a JSON body; the token stays a query parameter. `package-lock.json` still records the published 0.3.0 tarball — run `npm update @diffbot/typescript` once 0.6.0 is on npm. A missing crawl job from `crawlGetJob()` is `undefined`. +## Release + +Publishing uses npm trusted publishing from `.github/workflows/release.yml` (no npm token). + +1. Bump `version` in `package.json` (and update `package-lock.json`) on a branch. +2. Merge to `main`. +3. Tag the merge commit and push the tag: `git tag vX.Y.Z && git push origin vX.Y.Z`. + +The workflow checks the tag matches `package.json`, runs `npm ci` and `npm run typecheck`, then runs `npm publish --access public --provenance` and creates the GitHub Release with generated notes. Running the workflow manually (`workflow_dispatch`) only does the checks and `npm publish --dry-run`. + +One-time npm setup (package settings → Trusted publisher): org `diffbot`, repo `diffbot-pi`, workflow `release.yml`, no environment. + ## Package layout Follows the [Pi package](https://pi.dev/docs/latest/packages#creating-a-pi-package) conventions: From c5a35548d3f81c29cfbd638623531545942c627e Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 17:59:07 -1000 Subject: [PATCH 3/5] Add the 0.4.0 changelog for the TypeScript SDK 0.6.0 release. --- CHANGELOG.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d480003 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +## 0.4.0 - 2026-11-17 + +### Changed + +- Depends on `@diffbot/typescript` `^0.6.0` (cumulative 0.4.0–0.6.0). DQL goes through the SDK `dql()` helper, which POSTs a JSON body; the token stays the query parameter. +- `dql()` format is the SDK `ExportFormat`. Chat messages are checked against `system`, `user`, and `assistant`. +- A missing crawl job (`crawlGetJob()` returning `undefined`) is reported as an error. + +`package-lock.json` still records the published 0.3.0 tarball. Run `npm update @diffbot/typescript` once 0.6.0 is on npm, then tag `v0.4.0`. Publishing is npm trusted publishing from `.github/workflows/release.yml` (no token, no GitHub environment). From 2912b9f302996370019a7539cbc990cce0d86692 Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 18:38:26 -1000 Subject: [PATCH 4/5] Point @diffbot/typescript at 0.6.0-rc.0 for CI verification. --- package-lock.json | 8 ++++---- package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/package-lock.json b/package-lock.json index 729f898..34b5d85 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "0.4.0", "license": "MIT", "dependencies": { - "@diffbot/typescript": "^0.6.0" + "@diffbot/typescript": "^0.6.0-rc.0" }, "devDependencies": { "@earendil-works/pi-coding-agent": "^0.80.10", @@ -26,9 +26,9 @@ } }, "node_modules/@diffbot/typescript": { - "version": "0.3.0", - "resolved": "https://registry.npmjs.org/@diffbot/typescript/-/typescript-0.3.0.tgz", - "integrity": "sha512-VkHiLohAbhUzTNbLL8gwNXAIoTrSfyenAIam5sVLhUGysSkkxuVbNX78BVoU4AlM5pwF3FNEA6Z/5RBRl+TLbQ==", + "version": "0.6.0-rc.0", + "resolved": "https://registry.npmjs.org/@diffbot/typescript/-/typescript-0.6.0-rc.0.tgz", + "integrity": "sha512-04XHLNRhi/4JoQ2a2d4RChBGS1ZParIWeDqfjL+mcdkhUanlVJiLwvSBbQO3ttKd1gsPUA7WdcQ0+HaaH6z5Ng==", "license": "MIT", "engines": { "node": ">=18" diff --git a/package.json b/package.json index 9fc72f3..53b1147 100644 --- a/package.json +++ b/package.json @@ -39,7 +39,7 @@ "typecheck": "tsc --noEmit" }, "dependencies": { - "@diffbot/typescript": "^0.6.0" + "@diffbot/typescript": "^0.6.0-rc.0" }, "peerDependencies": { "@earendil-works/pi-coding-agent": "*", From 58edd814e9806a17599768dec14b2502f0eec82f Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Wed, 18 Nov 2026 11:57:00 -1000 Subject: [PATCH 5/5] Pin @diffbot/typescript ^0.6.0 (stable) and relock from npm. Co-Authored-By: Claude Opus 5.5 --- package-lock.json | 8 ++++---- package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/package-lock.json b/package-lock.json index 34b5d85..9d9e5c4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "0.4.0", "license": "MIT", "dependencies": { - "@diffbot/typescript": "^0.6.0-rc.0" + "@diffbot/typescript": "^0.6.0" }, "devDependencies": { "@earendil-works/pi-coding-agent": "^0.80.10", @@ -26,9 +26,9 @@ } }, "node_modules/@diffbot/typescript": { - "version": "0.6.0-rc.0", - "resolved": "https://registry.npmjs.org/@diffbot/typescript/-/typescript-0.6.0-rc.0.tgz", - "integrity": "sha512-04XHLNRhi/4JoQ2a2d4RChBGS1ZParIWeDqfjL+mcdkhUanlVJiLwvSBbQO3ttKd1gsPUA7WdcQ0+HaaH6z5Ng==", + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/@diffbot/typescript/-/typescript-0.6.0.tgz", + "integrity": "sha512-Sdrnk3+4QHo9BzP/hheAweI4L067EKEHXOrK26Lc6F0gLY/RMsifFiJVeolEAnKdI8HfDrUb7K/qBMQkU6DfiA==", "license": "MIT", "engines": { "node": ">=18" diff --git a/package.json b/package.json index 53b1147..9fc72f3 100644 --- a/package.json +++ b/package.json @@ -39,7 +39,7 @@ "typecheck": "tsc --noEmit" }, "dependencies": { - "@diffbot/typescript": "^0.6.0-rc.0" + "@diffbot/typescript": "^0.6.0" }, "peerDependencies": { "@earendil-works/pi-coding-agent": "*",