From b4e04248e73f2f8f5db328c54b1e6708d5e95799 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 19:20:45 +0000 Subject: [PATCH 1/3] chore: update SDK settings --- .github/workflows/publish-npm.yml | 2 +- .github/workflows/release-doctor.yml | 2 ++ .gitignore | 1 - .stats.yml | 2 +- bin/check-release-environment | 4 ++++ bin/publish-npm | 12 ++---------- 6 files changed, 10 insertions(+), 13 deletions(-) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 910fb786..21b3524e 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -18,7 +18,6 @@ jobs: runs-on: ubuntu-latest permissions: contents: write - id-token: write steps: - uses: actions/checkout@v6 @@ -45,6 +44,7 @@ jobs: pnpm tsn scripts/publish-packages.ts "{ \"paths_released\": \"$PATHS_RELEASED\" }" env: INPUT_PATH: ${{ github.event.inputs.path }} + NPM_TOKEN: ${{ secrets.HYPERSPELL_NPM_TOKEN || secrets.NPM_TOKEN }} - name: Upload MCP Server DXT GitHub release asset run: | diff --git a/.github/workflows/release-doctor.yml b/.github/workflows/release-doctor.yml index 16f6b559..f9ea8493 100644 --- a/.github/workflows/release-doctor.yml +++ b/.github/workflows/release-doctor.yml @@ -17,4 +17,6 @@ jobs: - name: Check release environment run: | bash ./bin/check-release-environment + env: + NPM_TOKEN: ${{ secrets.HYPERSPELL_NPM_TOKEN || secrets.NPM_TOKEN }} diff --git a/.gitignore b/.gitignore index ae4aa20e..b7d4f6b9 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,3 @@ dist-deno .eslintcache dist-bundle *.mcpb -oidc diff --git a/.stats.yml b/.stats.yml index 19377f47..b925885d 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 30 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-a4bf4f3aaf1509541db646bc9ff7ec58e78cb4d42cf6bf83881b02739ad77b87.yml openapi_spec_hash: 89cd02b2290061877e6badcddb7c8eb8 -config_hash: bd8505e17db740d82e578d0edaa9bfe0 +config_hash: 2ac853a71ed8b421da86d06bd90cf23f diff --git a/bin/check-release-environment b/bin/check-release-environment index 6b43775a..e4b6d58e 100644 --- a/bin/check-release-environment +++ b/bin/check-release-environment @@ -2,6 +2,10 @@ errors=() +if [ -z "${NPM_TOKEN}" ]; then + errors+=("The NPM_TOKEN secret has not been set. Please set it in either this repository's secrets or your organization secrets") +fi + lenErrors=${#errors[@]} if [[ lenErrors -gt 0 ]]; then diff --git a/bin/publish-npm b/bin/publish-npm index 4e094d72..a6099896 100644 --- a/bin/publish-npm +++ b/bin/publish-npm @@ -2,12 +2,7 @@ set -eux -if [[ ${NPM_TOKEN:-} ]]; then - npm config set '//registry.npmjs.org/:_authToken' "$NPM_TOKEN" -elif [[ ! ${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-} ]]; then - echo "ERROR: NPM_TOKEN must be set if not running in a Github Action with id-token permission" - exit 1 -fi +npm config set '//registry.npmjs.org/:_authToken' "$NPM_TOKEN" pnpm build cd dist @@ -62,8 +57,5 @@ else TAG="latest" fi -# Install OIDC compatible npm version -npm install --prefix ../oidc/ npm@11.6.2 - # Publish with the appropriate tag -pnpm publish --npm-path "$(cd ../ && pwd)/oidc/node_modules/.bin/npm" --no-git-checks --tag "$TAG" +pnpm publish --no-git-checks --tag "$TAG" From 597e2c01ec271e6f7054a03b475968ce5e19af31 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 19:26:45 +0000 Subject: [PATCH 2/3] chore: update SDK settings --- .github/workflows/publish-npm.yml | 2 +- .stats.yml | 2 +- CONTRIBUTING.md | 4 +- MIGRATION.md | 58 ++++----- README.md | 24 ++-- bin/cli | 4 +- bin/migration-config.json | 2 +- eslint.config.mjs | 2 +- jest.config.ts | 4 +- package.json | 4 +- packages/mcp-server/Dockerfile | 4 +- packages/mcp-server/README.md | 4 +- packages/mcp-server/build | 8 +- packages/mcp-server/package.json | 2 +- .../mcp-server/scripts/copy-bundle-files.cjs | 2 +- .../scripts/postprocess-dist-package-json.cjs | 2 +- packages/mcp-server/src/auth.ts | 2 +- packages/mcp-server/src/code-tool-types.ts | 2 +- packages/mcp-server/src/code-tool-worker.ts | 4 +- packages/mcp-server/src/code-tool.ts | 4 +- packages/mcp-server/src/http.ts | 2 +- packages/mcp-server/src/local-docs-search.ts | 122 +++++++++--------- packages/mcp-server/src/server.ts | 6 +- packages/mcp-server/src/types.ts | 2 +- pnpm-lock.yaml | 6 +- pnpm-workspace.yaml | 2 +- scripts/build | 6 +- tests/api-resources/actions.test.ts | 2 +- tests/api-resources/auth.test.ts | 2 +- tests/api-resources/connections.test.ts | 2 +- tests/api-resources/evaluate.test.ts | 2 +- tests/api-resources/folders.test.ts | 2 +- .../integrations/google-calendar.test.ts | 2 +- .../integrations/integrations.test.ts | 2 +- .../api-resources/integrations/slack.test.ts | 2 +- .../integrations/web-crawler.test.ts | 2 +- tests/api-resources/memories.test.ts | 2 +- tests/api-resources/sessions.test.ts | 2 +- tests/api-resources/vaults.test.ts | 2 +- tests/base64.test.ts | 2 +- tests/buildHeaders.test.ts | 6 +- tests/form.test.ts | 4 +- tests/index.test.ts | 6 +- tests/path.test.ts | 2 +- tests/qs/stringify.test.ts | 6 +- tests/qs/utils.test.ts | 2 +- tests/stringifyQuery.test.ts | 2 +- tests/uploads.test.ts | 6 +- tsconfig.build.json | 4 +- tsconfig.json | 4 +- 50 files changed, 179 insertions(+), 175 deletions(-) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 21b3524e..5c5b2649 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -49,6 +49,6 @@ jobs: - name: Upload MCP Server DXT GitHub release asset run: | gh release upload ${{ github.event.release.tag_name }} \ - packages/mcp-server/hyperspell_api.mcpb + packages/mcp-server/hyperspell_hyperspell_api.mcpb env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.stats.yml b/.stats.yml index b925885d..390cd289 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 30 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-a4bf4f3aaf1509541db646bc9ff7ec58e78cb4d42cf6bf83881b02739ad77b87.yml openapi_spec_hash: 89cd02b2290061877e6badcddb7c8eb8 -config_hash: 2ac853a71ed8b421da86d06bd90cf23f +config_hash: f779e7db9263cd21efe5e9469bc1d012 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b6dc765..e74d5a45 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,12 +55,12 @@ $ cd node-sdk # With yarn $ yarn link $ cd ../my-package -$ yarn link hyperspell +$ yarn link @hyperspell/hyperspell # With pnpm $ pnpm link --global $ cd ../my-package -$ pnpm link --global hyperspell +$ pnpm link --global @hyperspell/hyperspell ``` ## Running tests diff --git a/MIGRATION.md b/MIGRATION.md index 2b6ab1a1..ec32e12f 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -7,7 +7,7 @@ The main changes are that the SDK now relies on the [builtin Web fetch API](http ## Migration CLI Most programs will only need minimal changes, but to assist there is a migration tool that will automatically update your code for the new version. -To use it, upgrade the `hyperspell` package, then run `./node_modules/.bin/hyperspell migrate ./your/src/folders` to update your code. +To use it, upgrade the `@hyperspell/hyperspell` package, then run `./node_modules/.bin/hyperspell-hyperspell migrate ./your/src/folders` to update your code. To preview the changes without writing them to disk, run the tool with `--dry`. ## Environment requirements @@ -104,7 +104,7 @@ If you were using `httpAgent` for proxy support, check out the [new proxy docume Before: ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; import http from 'http'; import { HttpsProxyAgent } from 'https-proxy-agent'; @@ -117,7 +117,7 @@ const client = new Hyperspell({ After: ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; import * as undici from 'undici'; const proxyAgent = new undici.ProxyAgent(process.env.PROXY_URL); @@ -130,27 +130,27 @@ const client = new Hyperspell({ ### Changed exports -#### Refactor of `hyperspell/core`, `error`, `pagination`, `resource` and `uploads` +#### Refactor of `@hyperspell/hyperspell/core`, `error`, `pagination`, `resource` and `uploads` -Much of the `hyperspell/core` file was intended to be internal-only but it was publicly accessible, as such it has been refactored and split up into internal and public files, with public-facing code moved to a new `core` folder and internal code moving to the private `internal` folder. +Much of the `@hyperspell/hyperspell/core` file was intended to be internal-only but it was publicly accessible, as such it has been refactored and split up into internal and public files, with public-facing code moved to a new `core` folder and internal code moving to the private `internal` folder. At the same time, we moved some public-facing files which were previously at the top level into `core` to make the file structure cleaner and more clear: ```typescript // Before -import 'hyperspell/error'; -import 'hyperspell/pagination'; -import 'hyperspell/resource'; -import 'hyperspell/uploads'; +import '@hyperspell/hyperspell/error'; +import '@hyperspell/hyperspell/pagination'; +import '@hyperspell/hyperspell/resource'; +import '@hyperspell/hyperspell/uploads'; // After -import 'hyperspell/core/error'; -import 'hyperspell/core/pagination'; -import 'hyperspell/core/resource'; -import 'hyperspell/core/uploads'; +import '@hyperspell/hyperspell/core/error'; +import '@hyperspell/hyperspell/core/pagination'; +import '@hyperspell/hyperspell/core/resource'; +import '@hyperspell/hyperspell/core/uploads'; ``` -If you were relying on anything that was only exported from `hyperspell/core` and is also not accessible anywhere else, please open an issue and we'll consider adding it to the public API. +If you were relying on anything that was only exported from `@hyperspell/hyperspell/core` and is also not accessible anywhere else, please open an issue and we'll consider adding it to the public API. #### Resource classes @@ -159,16 +159,16 @@ Now you must always either reference them as static class properties or import t ```typescript // Before -const { Connections } = require('hyperspell'); +const { Connections } = require('@hyperspell/hyperspell'); // After -const { Hyperspell } = require('hyperspell'); -Hyperspell.Connections; // or import directly from hyperspell/resources/connections +const { Hyperspell } = require('@hyperspell/hyperspell'); +Hyperspell.Connections; // or import directly from @hyperspell/hyperspell/resources/connections ``` #### Cleaned up `uploads` exports -As part of the `core` refactor, `hyperspell/uploads` was moved to `hyperspell/core/uploads` +As part of the `core` refactor, `@hyperspell/hyperspell/uploads` was moved to `@hyperspell/hyperspell/core/uploads` and the following exports were removed, as they were not intended to be a part of the public API: - `fileFromPath` @@ -188,7 +188,7 @@ and the following exports were removed, as they were not intended to be a part o Note that `Uploadable` & `toFile` **are** still exported: ```typescript -import { type Uploadable, toFile } from 'hyperspell/core/uploads'; +import { type Uploadable, toFile } from '@hyperspell/hyperspell/core/uploads'; ``` #### `APIClient` @@ -197,10 +197,10 @@ The `APIClient` base client class has been removed as it is no longer needed. If ```typescript // Before -import { APIClient } from 'hyperspell/core'; +import { APIClient } from '@hyperspell/hyperspell/core'; // After -import { Hyperspell } from 'hyperspell'; +import { Hyperspell } from '@hyperspell/hyperspell'; ``` ### File handling @@ -224,11 +224,11 @@ Previously you could configure the types that the SDK used like this: ```ts // Tell TypeScript and the package to use the global Web fetch instead of node-fetch. -import 'hyperspell/shims/web'; -import Hyperspell from 'hyperspell'; +import '@hyperspell/hyperspell/shims/web'; +import Hyperspell from '@hyperspell/hyperspell'; ``` -The `hyperspell/shims` imports have been removed. Your global types must now be [correctly configured](#minimum-types-requirements). +The `@hyperspell/hyperspell/shims` imports have been removed. Your global types must now be [correctly configured](#minimum-types-requirements). ### Pagination changes @@ -267,19 +267,19 @@ export type ResourcesCursorPage = CursorPage; If you were importing these classes at runtime, you'll need to switch to importing the base class or only import them at the type-level. -### `hyperspell/src` directory removed +### `@hyperspell/hyperspell/src` directory removed -Previously IDEs may have auto-completed imports from the `hyperspell/src` directory, however this +Previously IDEs may have auto-completed imports from the `@hyperspell/hyperspell/src` directory, however this directory was only included for an improved go-to-definition experience and should not have been used at runtime. -If you have any `hyperspell/src/*` imports, you will need to replace them with `hyperspell/*`. +If you have any `@hyperspell/hyperspell/src/*` imports, you will need to replace them with `@hyperspell/hyperspell/*`. ```ts // Before -import Hyperspell from 'hyperspell/src'; +import Hyperspell from '@hyperspell/hyperspell/src'; // After -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; ``` ## TypeScript troubleshooting diff --git a/README.md b/README.md index 8a4d7e63..889fdf76 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Hyperspell TypeScript API Library -[![NPM version]()](https://npmjs.org/package/hyperspell) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/hyperspell) +[![NPM version]()](https://npmjs.org/package/@hyperspell/hyperspell) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@hyperspell/hyperspell) This library provides convenient access to the Hyperspell REST API from server-side TypeScript or JavaScript. @@ -20,7 +20,7 @@ Use the Hyperspell MCP Server to enable AI assistants to interact with this API, ## Installation ```sh -npm install hyperspell +npm install @hyperspell/hyperspell ``` ## Usage @@ -29,7 +29,7 @@ The full API of this library can be found in [api.md](api.md). ```js -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted @@ -46,7 +46,7 @@ This library includes TypeScript definitions for all request params and response ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted @@ -69,7 +69,7 @@ Request parameters that correspond to file uploads can be passed in many differe ```ts import fs from 'fs'; -import Hyperspell, { toFile } from 'hyperspell'; +import Hyperspell, { toFile } from '@hyperspell/hyperspell'; const client = new Hyperspell(); @@ -231,7 +231,7 @@ The log level can be configured in two ways: 2. Using the `logLevel` client option (overrides the environment variable if set) ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ logLevel: 'debug', // Show all log messages @@ -259,7 +259,7 @@ When providing a custom logger, the `logLevel` option still controls which messa below the configured level will not be sent to your logger. ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; import pino from 'pino'; const logger = pino(); @@ -328,7 +328,7 @@ globalThis.fetch = fetch; Or pass it to the client: ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; import fetch from 'my-fetch'; const client = new Hyperspell({ fetch }); @@ -339,7 +339,7 @@ const client = new Hyperspell({ fetch }); If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.) ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ fetchOptions: { @@ -356,7 +356,7 @@ options to requests: **Node** [[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)] ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; import * as undici from 'undici'; const proxyAgent = new undici.ProxyAgent('http://localhost:8888'); @@ -370,7 +370,7 @@ const client = new Hyperspell({ **Bun** [[docs](https://bun.sh/guides/http/proxy)] ```ts -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ fetchOptions: { @@ -382,7 +382,7 @@ const client = new Hyperspell({ **Deno** [[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)] ```ts -import Hyperspell from 'npm:hyperspell'; +import Hyperspell from 'npm:@hyperspell/hyperspell'; const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } }); const client = new Hyperspell({ diff --git a/bin/cli b/bin/cli index 4263af67..f50cb23b 100755 --- a/bin/cli +++ b/bin/cli @@ -4,7 +4,7 @@ const { spawnSync } = require('child_process'); const commands = { migrate: { - description: 'Run migrations to update your code using hyperspell@0.22.1 to be compatible with hyperspell@0.24.0', + description: 'Run migrations to update your code using @hyperspell/hyperspell@0.22.1 to be compatible with @hyperspell/hyperspell@0.24.0', fn: () => { const result = spawnSync( 'npx', @@ -19,7 +19,7 @@ const commands = { } function exitWithHelp() { - console.log(`Usage: hyperspell `); + console.log(`Usage: hyperspell-hyperspell `); console.log(); console.log('Subcommands:'); diff --git a/bin/migration-config.json b/bin/migration-config.json index aeeac6a4..ed08d549 100644 --- a/bin/migration-config.json +++ b/bin/migration-config.json @@ -1,5 +1,5 @@ { - "pkg": "hyperspell", + "pkg": "@hyperspell/hyperspell", "githubRepo": "https://github.com/hyperspell/node-sdk", "clientClass": "Hyperspell", "methods": [ diff --git a/eslint.config.mjs b/eslint.config.mjs index f7a241fb..1752cf14 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -25,7 +25,7 @@ export default tseslint.config( { patterns: [ { - regex: '^hyperspell(/.*)?', + regex: '^@hyperspell/hyperspell(/.*)?', message: 'Use a relative import, not a package import.', }, ], diff --git a/jest.config.ts b/jest.config.ts index 65cfaf88..850da5b9 100644 --- a/jest.config.ts +++ b/jest.config.ts @@ -7,8 +7,8 @@ const config: JestConfigWithTsJest = { '^.+\\.(t|j)sx?$': ['@swc/jest', { sourceMaps: 'inline' }], }, moduleNameMapper: { - '^hyperspell$': '/src/index.ts', - '^hyperspell/(.*)$': '/src/$1', + '^@hyperspell/hyperspell$': '/src/index.ts', + '^@hyperspell/hyperspell/(.*)$': '/src/$1', }, modulePathIgnorePatterns: [ '/ecosystem-tests/', diff --git a/package.json b/package.json index d5368de3..125d1286 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "hyperspell", + "name": "@hyperspell/hyperspell", "version": "0.36.0", "description": "The official TypeScript library for the Hyperspell API", "author": "Hyperspell ", @@ -51,7 +51,7 @@ "typescript-eslint": "8.31.1" }, "bin": { - "hyperspell": "bin/cli" + "hyperspell-hyperspell": "bin/cli" }, "overrides": { "minimatch": "^9.0.5" diff --git a/packages/mcp-server/Dockerfile b/packages/mcp-server/Dockerfile index b2ca6ee9..5e5abe01 100644 --- a/packages/mcp-server/Dockerfile +++ b/packages/mcp-server/Dockerfile @@ -59,8 +59,8 @@ WORKDIR /app # Copy the build results, preserving directory structure COPY --from=builder /build . -# Copy the built hyperspell into node_modules -COPY --from=builder /build/dist ./node_modules/hyperspell +# Copy the built @hyperspell/hyperspell into node_modules +COPY --from=builder /build/dist ./node_modules/@hyperspell/hyperspell # Change ownership to nodejs user RUN chown -R nodejs:nodejs /app diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md index 656c6b69..f84aa924 100644 --- a/packages/mcp-server/README.md +++ b/packages/mcp-server/README.md @@ -24,7 +24,7 @@ For clients with a configuration JSON, it might look something like this: ```json { "mcpServers": { - "hyperspell_api": { + "hyperspell_hyperspell_api": { "command": "npx", "args": ["-y", "hyperspell-mcp"], "env": { @@ -93,7 +93,7 @@ A configuration JSON for this server might look like this, assuming the server i ```json { "mcpServers": { - "hyperspell_api": { + "hyperspell_hyperspell_api": { "url": "http://localhost:3000", "headers": { "Authorization": "Bearer " diff --git a/packages/mcp-server/build b/packages/mcp-server/build index 4923a363..edacf387 100644 --- a/packages/mcp-server/build +++ b/packages/mcp-server/build @@ -19,7 +19,7 @@ done # and does a few other minor things PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist/package.json -# updates the `hyperspell` dependency to point to NPM +# updates the `@hyperspell/hyperspell` dependency to point to NPM node scripts/postprocess-dist-package-json.cjs # build to .js/.mjs/.d.ts files @@ -32,7 +32,7 @@ chmod +x dist/index.js DIST_PATH=./dist PKG_IMPORT_PATH=hyperspell-mcp/ node ../../scripts/utils/postprocess-files.cjs # mcp bundle -rm -rf dist-bundle hyperspell_api.mcpb; mkdir dist-bundle +rm -rf dist-bundle hyperspell_hyperspell_api.mcpb; mkdir dist-bundle # copy package.json PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist-bundle/package.json @@ -48,9 +48,9 @@ cd .. # pack bundle cp manifest.json dist-bundle -npx mcpb pack dist-bundle hyperspell_api.mcpb +npx mcpb pack dist-bundle hyperspell_hyperspell_api.mcpb -npx mcpb sign hyperspell_api.mcpb --self-signed +npx mcpb sign hyperspell_hyperspell_api.mcpb --self-signed # clean up rm -rf dist-bundle diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json index 8a0ccc3c..8fdd201a 100644 --- a/packages/mcp-server/package.json +++ b/packages/mcp-server/package.json @@ -29,7 +29,7 @@ "fix": "eslint --fix ." }, "dependencies": { - "hyperspell": "workspace:*", + "@hyperspell/hyperspell": "workspace:*", "ajv": "^8.18.0", "@cloudflare/cabidela": "^0.2.4", "@hono/node-server": "^1.19.10", diff --git a/packages/mcp-server/scripts/copy-bundle-files.cjs b/packages/mcp-server/scripts/copy-bundle-files.cjs index 013a91c4..0545a7eb 100644 --- a/packages/mcp-server/scripts/copy-bundle-files.cjs +++ b/packages/mcp-server/scripts/copy-bundle-files.cjs @@ -25,7 +25,7 @@ async function copyFiles() { // replace package.json reference with local reference for (const dep in pkgJson.dependencies) { - if (dep === 'hyperspell') { + if (dep === '@hyperspell/hyperspell') { pkgJson.dependencies[dep] = 'file:../../../dist/'; } } diff --git a/packages/mcp-server/scripts/postprocess-dist-package-json.cjs b/packages/mcp-server/scripts/postprocess-dist-package-json.cjs index 5826d4fc..a0881d4c 100644 --- a/packages/mcp-server/scripts/postprocess-dist-package-json.cjs +++ b/packages/mcp-server/scripts/postprocess-dist-package-json.cjs @@ -4,7 +4,7 @@ const parentPkgJson = require('../../../package.json'); for (const dep in pkgJson.dependencies) { // ensure we point to NPM instead of a local directory - if (dep === 'hyperspell') { + if (dep === '@hyperspell/hyperspell') { pkgJson.dependencies[dep] = '^' + parentPkgJson.version; } } diff --git a/packages/mcp-server/src/auth.ts b/packages/mcp-server/src/auth.ts index 9181fb09..7f1be6b2 100644 --- a/packages/mcp-server/src/auth.ts +++ b/packages/mcp-server/src/auth.ts @@ -1,7 +1,7 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. import { IncomingMessage } from 'node:http'; -import { ClientOptions } from 'hyperspell'; +import { ClientOptions } from '@hyperspell/hyperspell'; import { McpOptions } from './options'; export const parseClientAuthHeaders = (req: IncomingMessage, required?: boolean): Partial => { diff --git a/packages/mcp-server/src/code-tool-types.ts b/packages/mcp-server/src/code-tool-types.ts index 4c069221..d5873775 100644 --- a/packages/mcp-server/src/code-tool-types.ts +++ b/packages/mcp-server/src/code-tool-types.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import { ClientOptions } from 'hyperspell'; +import { ClientOptions } from '@hyperspell/hyperspell'; export type WorkerInput = { project_name: string; diff --git a/packages/mcp-server/src/code-tool-worker.ts b/packages/mcp-server/src/code-tool-worker.ts index de828856..c557f78f 100644 --- a/packages/mcp-server/src/code-tool-worker.ts +++ b/packages/mcp-server/src/code-tool-worker.ts @@ -5,7 +5,7 @@ import util from 'node:util'; import Fuse from 'fuse.js'; import ts from 'typescript'; import { WorkerOutput } from './code-tool-types'; -import { Hyperspell, ClientOptions } from 'hyperspell'; +import { Hyperspell, ClientOptions } from '@hyperspell/hyperspell'; async function tseval(code: string) { return import('data:application/typescript;charset=utf-8;base64,' + Buffer.from(code).toString('base64')); @@ -57,7 +57,7 @@ function getRunFunctionSource(code: string): { function getTSDiagnostics(code: string): string[] { const functionSource = getRunFunctionSource(code)!; const codeWithImport = [ - 'import { Hyperspell } from "hyperspell";', + 'import { Hyperspell } from "@hyperspell/hyperspell";', functionSource.type === 'declaration' ? `async function run(${functionSource.client}: Hyperspell)` : `const run: (${functionSource.client}: Hyperspell) => Promise =`, diff --git a/packages/mcp-server/src/code-tool.ts b/packages/mcp-server/src/code-tool.ts index 7f429012..0bfa9557 100644 --- a/packages/mcp-server/src/code-tool.ts +++ b/packages/mcp-server/src/code-tool.ts @@ -15,7 +15,7 @@ import { WorkerInput, WorkerOutput } from './code-tool-types'; import { getLogger } from './logger'; import { SdkMethod } from './methods'; import { McpCodeExecutionMode } from './options'; -import { ClientOptions } from 'hyperspell'; +import { ClientOptions } from '@hyperspell/hyperspell'; const prompt = `Runs JavaScript code to interact with the Hyperspell API. @@ -246,7 +246,7 @@ const localDenoHandler = async ({ // Follow symlinks in node_modules to allow read access to workspace-linked packages try { - const sdkPkgName = 'hyperspell'; + const sdkPkgName = '@hyperspell/hyperspell'; const sdkDir = path.resolve(packageNodeModulesPath, sdkPkgName); const realSdkDir = fs.realpathSync(sdkDir); if (realSdkDir !== sdkDir) { diff --git a/packages/mcp-server/src/http.ts b/packages/mcp-server/src/http.ts index c7d9e181..fa893308 100644 --- a/packages/mcp-server/src/http.ts +++ b/packages/mcp-server/src/http.ts @@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; -import { ClientOptions } from 'hyperspell'; +import { ClientOptions } from '@hyperspell/hyperspell'; import express from 'express'; import pino from 'pino'; import pinoHttp from 'pino-http'; diff --git a/packages/mcp-server/src/local-docs-search.ts b/packages/mcp-server/src/local-docs-search.ts index 36348054..8dd51aae 100644 --- a/packages/mcp-server/src/local-docs-search.ts +++ b/packages/mcp-server/src/local-docs-search.ts @@ -62,7 +62,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ params: ['connection_id: string;'], response: '{ message: string; success: boolean; }', markdown: - "## revoke\n\n`client.connections.revoke(connection_id: string): { message: string; success: boolean; }`\n\n**delete** `/connections/{connection_id}/revoke`\n\nRevokes Hyperspell's access the given provider and deletes all stored credentials and indexed data.\n\n### Parameters\n\n- `connection_id: string`\n\n### Returns\n\n- `{ message: string; success: boolean; }`\n\n - `message: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.connections.revoke('connection_id');\n\nconsole.log(response);\n```", + "## revoke\n\n`client.connections.revoke(connection_id: string): { message: string; success: boolean; }`\n\n**delete** `/connections/{connection_id}/revoke`\n\nRevokes Hyperspell's access the given provider and deletes all stored credentials and indexed data.\n\n### Parameters\n\n- `connection_id: string`\n\n### Returns\n\n- `{ message: string; success: boolean; }`\n\n - `message: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.connections.revoke('connection_id');\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'connections revoke', @@ -86,7 +86,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.connections.revoke', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.connections.revoke('connection_id');\n\nconsole.log(response.message);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.connections.revoke('connection_id');\n\nconsole.log(response.message);", }, }, }, @@ -100,7 +100,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ qualified: 'client.connections.list', response: '{ connections: { id: string; integration_id: string; label: string; provider: string; }[]; }', markdown: - "## list\n\n`client.connections.list(): { connections: object[]; }`\n\n**get** `/connections/list`\n\nList all connections for the user.\n\n### Returns\n\n- `{ connections: { id: string; integration_id: string; label: string; provider: string; }[]; }`\n\n - `connections: { id: string; integration_id: string; label: string; provider: string; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst connections = await client.connections.list();\n\nconsole.log(connections);\n```", + "## list\n\n`client.connections.list(): { connections: object[]; }`\n\n**get** `/connections/list`\n\nList all connections for the user.\n\n### Returns\n\n- `{ connections: { id: string; integration_id: string; label: string; provider: string; }[]; }`\n\n - `connections: { id: string; integration_id: string; label: string; provider: string; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst connections = await client.connections.list();\n\nconsole.log(connections);\n```", perLanguage: { cli: { method: 'connections list', @@ -123,7 +123,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.connections.list', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst connections = await client.connections.list();\n\nconsole.log(connections.connections);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst connections = await client.connections.list();\n\nconsole.log(connections.connections);", }, }, }, @@ -140,7 +140,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ folders: { has_children: boolean; name: string; provider_folder_id: string; parent_folder_id?: string; policy?: { id: string; sync_mode: 'sync' | 'skip' | 'manual'; }; }[]; }", markdown: - "## list\n\n`client.folders.list(connection_id: string, parent_id?: string): { folders: object[]; }`\n\n**get** `/connections/{connection_id}/folders`\n\nList one level of folders from the user's connected source.\n\nReturns folders decorated with their explicit folder policy (if any).\nUse parent_id to drill into subfolders.\n\n### Parameters\n\n- `connection_id: string`\n\n- `parent_id?: string`\n Parent folder ID. Omit for root-level folders.\n\n### Returns\n\n- `{ folders: { has_children: boolean; name: string; provider_folder_id: string; parent_folder_id?: string; policy?: { id: string; sync_mode: 'sync' | 'skip' | 'manual'; }; }[]; }`\n\n - `folders: { has_children: boolean; name: string; provider_folder_id: string; parent_folder_id?: string; policy?: { id: string; sync_mode: 'sync' | 'skip' | 'manual'; }; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst folders = await client.folders.list('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(folders);\n```", + "## list\n\n`client.folders.list(connection_id: string, parent_id?: string): { folders: object[]; }`\n\n**get** `/connections/{connection_id}/folders`\n\nList one level of folders from the user's connected source.\n\nReturns folders decorated with their explicit folder policy (if any).\nUse parent_id to drill into subfolders.\n\n### Parameters\n\n- `connection_id: string`\n\n- `parent_id?: string`\n Parent folder ID. Omit for root-level folders.\n\n### Returns\n\n- `{ folders: { has_children: boolean; name: string; provider_folder_id: string; parent_folder_id?: string; policy?: { id: string; sync_mode: 'sync' | 'skip' | 'manual'; }; }[]; }`\n\n - `folders: { has_children: boolean; name: string; provider_folder_id: string; parent_folder_id?: string; policy?: { id: string; sync_mode: 'sync' | 'skip' | 'manual'; }; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst folders = await client.folders.list('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(folders);\n```", perLanguage: { cli: { method: 'folders list', @@ -164,7 +164,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.folders.list', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst folders = await client.folders.list('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(folders.folders);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst folders = await client.folders.list('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(folders.folders);", }, }, }, @@ -180,7 +180,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ policies: { id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }[]; }", markdown: - "## list_policies\n\n`client.folders.listPolicies(connection_id: string): { policies: object[]; }`\n\n**get** `/connections/{connection_id}/folder-policies`\n\nList all folder policies for a specific connection.\n\n### Parameters\n\n- `connection_id: string`\n\n### Returns\n\n- `{ policies: { id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }[]; }`\n\n - `policies: { id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.folders.listPolicies('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response);\n```", + "## list_policies\n\n`client.folders.listPolicies(connection_id: string): { policies: object[]; }`\n\n**get** `/connections/{connection_id}/folder-policies`\n\nList all folder policies for a specific connection.\n\n### Parameters\n\n- `connection_id: string`\n\n### Returns\n\n- `{ policies: { id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }[]; }`\n\n - `policies: { id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.folders.listPolicies('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'folders list_policies', @@ -204,7 +204,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.folders.listPolicies', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.folders.listPolicies('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.policies);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.folders.listPolicies('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.policies);", }, }, }, @@ -227,7 +227,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }", markdown: - "## set_policies\n\n`client.folders.setPolicies(connection_id: string, provider_folder_id: string, sync_mode: 'sync' | 'skip' | 'manual', folder_name?: string, folder_path?: string, parent_folder_id?: string): { id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }`\n\n**post** `/connections/{connection_id}/folder-policies`\n\nCreate or update a folder policy for a specific connection.\n\n### Parameters\n\n- `connection_id: string`\n\n- `provider_folder_id: string`\n Folder ID from the source provider\n\n- `sync_mode: 'sync' | 'skip' | 'manual'`\n Sync mode for this folder\n\n- `folder_name?: string`\n Display name of the folder\n\n- `folder_path?: string`\n Display path of the folder\n\n- `parent_folder_id?: string`\n Parent folder's provider ID for inheritance resolution\n\n### Returns\n\n- `{ id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }`\n\n - `id: string`\n - `provider_folder_id: string`\n - `sync_mode: 'sync' | 'skip' | 'manual'`\n - `connection_id?: string`\n - `folder_name?: string`\n - `folder_path?: string`\n - `parent_folder_id?: string`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.folders.setPolicies('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { provider_folder_id: 'provider_folder_id', sync_mode: 'sync' });\n\nconsole.log(response);\n```", + "## set_policies\n\n`client.folders.setPolicies(connection_id: string, provider_folder_id: string, sync_mode: 'sync' | 'skip' | 'manual', folder_name?: string, folder_path?: string, parent_folder_id?: string): { id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }`\n\n**post** `/connections/{connection_id}/folder-policies`\n\nCreate or update a folder policy for a specific connection.\n\n### Parameters\n\n- `connection_id: string`\n\n- `provider_folder_id: string`\n Folder ID from the source provider\n\n- `sync_mode: 'sync' | 'skip' | 'manual'`\n Sync mode for this folder\n\n- `folder_name?: string`\n Display name of the folder\n\n- `folder_path?: string`\n Display path of the folder\n\n- `parent_folder_id?: string`\n Parent folder's provider ID for inheritance resolution\n\n### Returns\n\n- `{ id: string; provider_folder_id: string; sync_mode: 'sync' | 'skip' | 'manual'; connection_id?: string; folder_name?: string; folder_path?: string; parent_folder_id?: string; }`\n\n - `id: string`\n - `provider_folder_id: string`\n - `sync_mode: 'sync' | 'skip' | 'manual'`\n - `connection_id?: string`\n - `folder_name?: string`\n - `folder_path?: string`\n - `parent_folder_id?: string`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.folders.setPolicies('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { provider_folder_id: 'provider_folder_id', sync_mode: 'sync' });\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'folders set_policies', @@ -251,7 +251,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.folders.setPolicies', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.folders.setPolicies('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n provider_folder_id: 'provider_folder_id',\n sync_mode: 'sync',\n});\n\nconsole.log(response.id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.folders.setPolicies('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n provider_folder_id: 'provider_folder_id',\n sync_mode: 'sync',\n});\n\nconsole.log(response.id);", }, }, }, @@ -266,7 +266,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ params: ['connection_id: string;', 'policy_id: string;'], response: '{ success: boolean; }', markdown: - "## delete_policy\n\n`client.folders.deletePolicy(connection_id: string, policy_id: string): { success: boolean; }`\n\n**delete** `/connections/{connection_id}/folder-policies/{policy_id}`\n\nDelete a folder policy for a specific connection.\n\n### Parameters\n\n- `connection_id: string`\n\n- `policy_id: string`\n\n### Returns\n\n- `{ success: boolean; }`\n\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.folders.deletePolicy('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { connection_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' });\n\nconsole.log(response);\n```", + "## delete_policy\n\n`client.folders.deletePolicy(connection_id: string, policy_id: string): { success: boolean; }`\n\n**delete** `/connections/{connection_id}/folder-policies/{policy_id}`\n\nDelete a folder policy for a specific connection.\n\n### Parameters\n\n- `connection_id: string`\n\n- `policy_id: string`\n\n### Returns\n\n- `{ success: boolean; }`\n\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.folders.deletePolicy('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { connection_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' });\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'folders delete_policy', @@ -290,7 +290,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.folders.deletePolicy', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.folders.deletePolicy('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n connection_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n});\n\nconsole.log(response.success);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.folders.deletePolicy('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n connection_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n});\n\nconsole.log(response.success);", }, }, }, @@ -305,7 +305,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ integrations: { id: string; allow_multiple_connections: boolean; auth_provider: 'nango' | 'unified' | 'whitelabel'; icon: string; name: string; provider: string; actions_only?: boolean; }[]; }", markdown: - "## list\n\n`client.integrations.list(): { integrations: object[]; }`\n\n**get** `/integrations/list`\n\nList all integrations for the user.\n\n### Returns\n\n- `{ integrations: { id: string; allow_multiple_connections: boolean; auth_provider: 'nango' | 'unified' | 'whitelabel'; icon: string; name: string; provider: string; actions_only?: boolean; }[]; }`\n\n - `integrations: { id: string; allow_multiple_connections: boolean; auth_provider: 'nango' | 'unified' | 'whitelabel'; icon: string; name: string; provider: string; actions_only?: boolean; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst integrations = await client.integrations.list();\n\nconsole.log(integrations);\n```", + "## list\n\n`client.integrations.list(): { integrations: object[]; }`\n\n**get** `/integrations/list`\n\nList all integrations for the user.\n\n### Returns\n\n- `{ integrations: { id: string; allow_multiple_connections: boolean; auth_provider: 'nango' | 'unified' | 'whitelabel'; icon: string; name: string; provider: string; actions_only?: boolean; }[]; }`\n\n - `integrations: { id: string; allow_multiple_connections: boolean; auth_provider: 'nango' | 'unified' | 'whitelabel'; icon: string; name: string; provider: string; actions_only?: boolean; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst integrations = await client.integrations.list();\n\nconsole.log(integrations);\n```", perLanguage: { cli: { method: 'integrations list', @@ -328,7 +328,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.integrations.list', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst integrations = await client.integrations.list();\n\nconsole.log(integrations.integrations);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst integrations = await client.integrations.list();\n\nconsole.log(integrations.integrations);", }, }, }, @@ -343,7 +343,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ params: ['integration_id: string;', 'redirect_url?: string;'], response: '{ expires_at: string; url: string; }', markdown: - "## connect\n\n`client.integrations.connect(integration_id: string, redirect_url?: string): { expires_at: string; url: string; }`\n\n**get** `/integrations/{integration_id}/connect`\n\nRedirects to the connect URL to link an integration.\n\n### Parameters\n\n- `integration_id: string`\n\n- `redirect_url?: string`\n\n### Returns\n\n- `{ expires_at: string; url: string; }`\n\n - `expires_at: string`\n - `url: string`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.integrations.connect('integration_id');\n\nconsole.log(response);\n```", + "## connect\n\n`client.integrations.connect(integration_id: string, redirect_url?: string): { expires_at: string; url: string; }`\n\n**get** `/integrations/{integration_id}/connect`\n\nRedirects to the connect URL to link an integration.\n\n### Parameters\n\n- `integration_id: string`\n\n- `redirect_url?: string`\n\n### Returns\n\n- `{ expires_at: string; url: string; }`\n\n - `expires_at: string`\n - `url: string`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.integrations.connect('integration_id');\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'integrations connect', @@ -367,7 +367,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.integrations.connect', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.integrations.connect('integration_id');\n\nconsole.log(response.expires_at);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.integrations.connect('integration_id');\n\nconsole.log(response.expires_at);", }, }, }, @@ -382,7 +382,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ qualified: 'client.integrations.googleCalendar.list', response: '{ items: { id: string; name: string; primary: boolean; timezone: string; }[]; }', markdown: - "## list\n\n`client.integrations.googleCalendar.list(): { items: object[]; }`\n\n**get** `/integrations/google_calendar/list`\n\nList available calendars for a user. This can be used to ie. populate a dropdown for the user to select a calendar.\n\n### Returns\n\n- `{ items: { id: string; name: string; primary: boolean; timezone: string; }[]; }`\n\n - `items: { id: string; name: string; primary: boolean; timezone: string; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst calendar = await client.integrations.googleCalendar.list();\n\nconsole.log(calendar);\n```", + "## list\n\n`client.integrations.googleCalendar.list(): { items: object[]; }`\n\n**get** `/integrations/google_calendar/list`\n\nList available calendars for a user. This can be used to ie. populate a dropdown for the user to select a calendar.\n\n### Returns\n\n- `{ items: { id: string; name: string; primary: boolean; timezone: string; }[]; }`\n\n - `items: { id: string; name: string; primary: boolean; timezone: string; }[]`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst calendar = await client.integrations.googleCalendar.list();\n\nconsole.log(calendar);\n```", perLanguage: { cli: { method: 'google_calendar list', @@ -405,7 +405,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.integrations.googleCalendar.list', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst calendar = await client.integrations.googleCalendar.list();\n\nconsole.log(calendar.items);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst calendar = await client.integrations.googleCalendar.list();\n\nconsole.log(calendar.items);", }, }, }, @@ -421,7 +421,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }", markdown: - "## index\n\n`client.integrations.webCrawler.index(url: string, limit?: number, max_depth?: number): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**get** `/integrations/web_crawler/index`\n\nRecursively crawl a website to make it available for indexed search.\n\n### Parameters\n\n- `url: string`\n The base URL of the website to crawl\n\n- `limit?: number`\n Maximum number of pages to crawl in total\n\n- `max_depth?: number`\n Maximum depth of links to follow during crawling\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.integrations.webCrawler.index({ url: 'url' });\n\nconsole.log(response);\n```", + "## index\n\n`client.integrations.webCrawler.index(url: string, limit?: number, max_depth?: number): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**get** `/integrations/web_crawler/index`\n\nRecursively crawl a website to make it available for indexed search.\n\n### Parameters\n\n- `url: string`\n The base URL of the website to crawl\n\n- `limit?: number`\n Maximum number of pages to crawl in total\n\n- `max_depth?: number`\n Maximum depth of links to follow during crawling\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.integrations.webCrawler.index({ url: 'url' });\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'web_crawler index', @@ -444,7 +444,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.integrations.webCrawler.index', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.integrations.webCrawler.index({ url: 'url' });\n\nconsole.log(response.resource_id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.integrations.webCrawler.index({ url: 'url' });\n\nconsole.log(response.resource_id);", }, }, }, @@ -466,7 +466,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ ], response: 'object', markdown: - "## list\n\n`client.integrations.slack.list(channels?: string[], exclude_archived?: boolean, include_dms?: boolean, include_group_dms?: boolean, include_private?: boolean): object`\n\n**get** `/integrations/slack/list`\n\nList Slack conversations accessible to the user via the live Nango connection.\n\nReturns minimal channel metadata suitable for selection UIs. If required\nscopes are missing, Slack's error is propagated with details.\n\nSupports filtering by channels, including/excluding private channels, DMs,\ngroup DMs, and archived channels based on the provided search options.\n\n### Parameters\n\n- `channels?: string[]`\n List of Slack channels to include (by id, name, or #name).\n\n- `exclude_archived?: boolean`\n If set, pass 'exclude_archived' to Slack. If None, omit the param.\n\n- `include_dms?: boolean`\n Include direct messages (im) when listing conversations.\n\n- `include_group_dms?: boolean`\n Include group DMs (mpim) when listing conversations.\n\n- `include_private?: boolean`\n Include private channels when constructing Slack 'types'.\n\n### Returns\n\n- `object`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst slacks = await client.integrations.slack.list();\n\nconsole.log(slacks);\n```", + "## list\n\n`client.integrations.slack.list(channels?: string[], exclude_archived?: boolean, include_dms?: boolean, include_group_dms?: boolean, include_private?: boolean): object`\n\n**get** `/integrations/slack/list`\n\nList Slack conversations accessible to the user via the live Nango connection.\n\nReturns minimal channel metadata suitable for selection UIs. If required\nscopes are missing, Slack's error is propagated with details.\n\nSupports filtering by channels, including/excluding private channels, DMs,\ngroup DMs, and archived channels based on the provided search options.\n\n### Parameters\n\n- `channels?: string[]`\n List of Slack channels to include (by id, name, or #name).\n\n- `exclude_archived?: boolean`\n If set, pass 'exclude_archived' to Slack. If None, omit the param.\n\n- `include_dms?: boolean`\n Include direct messages (im) when listing conversations.\n\n- `include_group_dms?: boolean`\n Include group DMs (mpim) when listing conversations.\n\n- `include_private?: boolean`\n Include private channels when constructing Slack 'types'.\n\n### Returns\n\n- `object`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst slacks = await client.integrations.slack.list();\n\nconsole.log(slacks);\n```", perLanguage: { cli: { method: 'slack list', @@ -489,7 +489,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.integrations.slack.list', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst slacks = await client.integrations.slack.list();\n\nconsole.log(slacks);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst slacks = await client.integrations.slack.list();\n\nconsole.log(slacks);", }, }, }, @@ -513,7 +513,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }", markdown: - "## add\n\n`client.memories.add(text: string, collection?: string, date?: string, metadata?: object, resource_id?: string, title?: string): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**post** `/memories/add`\n\nAdds an arbitrary document to the index. This can be any text, email,\ncall transcript, etc. The document will be processed and made available for\nquerying once the processing is complete.\n\n### Parameters\n\n- `text: string`\n Full text of the document.\n\n- `collection?: string`\n The collection to add the document to — deprecated, set the collection using metadata instead.\n\n- `date?: string`\n Date of the document. Depending on the document, this could be the creation date or date the document was last updated (eg. for a chat transcript, this would be the date of the last message). This helps the ranking algorithm and allows you to filter by date range.\n\n- `metadata?: object`\n Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars. Values must be string, number, boolean, or null.\n\n- `resource_id?: string`\n The resource ID to add the document to. If not provided, a new resource ID will be generated. If provided, the document will be updated if it already exists.\n\n- `title?: string`\n Title of the document.\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst memoryStatus = await client.memories.add({ text: '...' });\n\nconsole.log(memoryStatus);\n```", + "## add\n\n`client.memories.add(text: string, collection?: string, date?: string, metadata?: object, resource_id?: string, title?: string): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**post** `/memories/add`\n\nAdds an arbitrary document to the index. This can be any text, email,\ncall transcript, etc. The document will be processed and made available for\nquerying once the processing is complete.\n\n### Parameters\n\n- `text: string`\n Full text of the document.\n\n- `collection?: string`\n The collection to add the document to — deprecated, set the collection using metadata instead.\n\n- `date?: string`\n Date of the document. Depending on the document, this could be the creation date or date the document was last updated (eg. for a chat transcript, this would be the date of the last message). This helps the ranking algorithm and allows you to filter by date range.\n\n- `metadata?: object`\n Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars. Values must be string, number, boolean, or null.\n\n- `resource_id?: string`\n The resource ID to add the document to. If not provided, a new resource ID will be generated. If provided, the document will be updated if it already exists.\n\n- `title?: string`\n Title of the document.\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst memoryStatus = await client.memories.add({ text: '...' });\n\nconsole.log(memoryStatus);\n```", perLanguage: { cli: { method: 'memories add', @@ -536,7 +536,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.add', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.memories.add({ text: '...' });\n\nconsole.log(memoryStatus.resource_id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.memories.add({ text: '...' });\n\nconsole.log(memoryStatus.resource_id);", }, }, }, @@ -555,7 +555,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ count: number; items: { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }[]; success?: boolean; }", markdown: - "## add_bulk\n\n`client.memories.addBulk(items: { text: string; collection?: string; date?: string; metadata?: object; resource_id?: string; title?: string; }[]): { count: number; items: memory_status[]; success?: boolean; }`\n\n**post** `/memories/add/bulk`\n\nAdds multiple documents to the index in a single request.\n\nAll items are validated before any database operations occur. If any item\nfails validation, the entire batch is rejected with a 422 error detailing\nwhich items failed and why.\n\nMaximum 100 items per request. Each item follows the same schema as the\nsingle-item /memories/add endpoint.\n\n### Parameters\n\n- `items: { text: string; collection?: string; date?: string; metadata?: object; resource_id?: string; title?: string; }[]`\n List of memories to ingest. Maximum 100 items.\n\n### Returns\n\n- `{ count: number; items: { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }[]; success?: boolean; }`\n Response schema for successful bulk ingestion.\n\n - `count: number`\n - `items: { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }[]`\n - `success?: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.memories.addBulk({ items: [{ text: '...' }] });\n\nconsole.log(response);\n```", + "## add_bulk\n\n`client.memories.addBulk(items: { text: string; collection?: string; date?: string; metadata?: object; resource_id?: string; title?: string; }[]): { count: number; items: memory_status[]; success?: boolean; }`\n\n**post** `/memories/add/bulk`\n\nAdds multiple documents to the index in a single request.\n\nAll items are validated before any database operations occur. If any item\nfails validation, the entire batch is rejected with a 422 error detailing\nwhich items failed and why.\n\nMaximum 100 items per request. Each item follows the same schema as the\nsingle-item /memories/add endpoint.\n\n### Parameters\n\n- `items: { text: string; collection?: string; date?: string; metadata?: object; resource_id?: string; title?: string; }[]`\n List of memories to ingest. Maximum 100 items.\n\n### Returns\n\n- `{ count: number; items: { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }[]; success?: boolean; }`\n Response schema for successful bulk ingestion.\n\n - `count: number`\n - `items: { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }[]`\n - `success?: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.memories.addBulk({ items: [{ text: '...' }] });\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'memories add_bulk', @@ -578,7 +578,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.addBulk', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.memories.addBulk({ items: [{ text: '...' }] });\n\nconsole.log(response.count);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.memories.addBulk({ items: [{ text: '...' }] });\n\nconsole.log(response.count);", }, }, }, @@ -595,7 +595,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }", markdown: - "## upload\n\n`client.memories.upload(file: string, collection?: string, metadata?: string): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**post** `/memories/upload`\n\nThis endpoint will upload a file to the index and return a resource_id.\nThe file will be processed in the background and the memory will be available for querying once the processing is complete.\nYou can use the `resource_id` to query the memory later, and check the status of the memory.\n\n### Parameters\n\n- `file: string`\n The file to ingest.\n\n- `collection?: string`\n The collection to add the document to — deprecated, set the collection using metadata instead.\n\n- `metadata?: string`\n Custom metadata as JSON string for filtering. Keys must be alphanumeric with underscores, max 64 chars. Values must be string, number, or boolean.\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst memoryStatus = await client.memories.upload({ file: fs.createReadStream('path/to/file') });\n\nconsole.log(memoryStatus);\n```", + "## upload\n\n`client.memories.upload(file: string, collection?: string, metadata?: string): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**post** `/memories/upload`\n\nThis endpoint will upload a file to the index and return a resource_id.\nThe file will be processed in the background and the memory will be available for querying once the processing is complete.\nYou can use the `resource_id` to query the memory later, and check the status of the memory.\n\n### Parameters\n\n- `file: string`\n The file to ingest.\n\n- `collection?: string`\n The collection to add the document to — deprecated, set the collection using metadata instead.\n\n- `metadata?: string`\n Custom metadata as JSON string for filtering. Keys must be alphanumeric with underscores, max 64 chars. Values must be string, number, or boolean.\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst memoryStatus = await client.memories.upload({ file: fs.createReadStream('path/to/file') });\n\nconsole.log(memoryStatus);\n```", perLanguage: { cli: { method: 'memories upload', @@ -618,7 +618,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.upload', example: - "import fs from 'fs';\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.memories.upload({ file: fs.createReadStream('path/to/file') });\n\nconsole.log(memoryStatus.resource_id);", + "import fs from 'fs';\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.memories.upload({ file: fs.createReadStream('path/to/file') });\n\nconsole.log(memoryStatus.resource_id);", }, }, }, @@ -643,7 +643,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }", markdown: - "## update\n\n`client.memories.update(source: string, resource_id: string, collection?: string | object, date?: string | object, metadata?: object | object, text?: string | object, title?: string | object): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**post** `/memories/update/{source}/{resource_id}`\n\nUpdates an existing document in the index. You can update the text, collection,\ntitle, and metadata. The document must already exist or a 404 will be returned.\nThis works for documents from any source (vault, slack, gmail, etc.).\n\nTo remove a collection, set it to null explicitly.\n\n### Parameters\n\n- `source: string`\n\n- `resource_id: string`\n\n- `collection?: string | object`\n The collection to move the document to — deprecated, set the collection using metadata instead.\n\n- `date?: string | object`\n Date of the document for ranking and filtering.\n\n- `metadata?: object | object`\n Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars. Values must be string, number, boolean, or null. Will be merged with existing metadata.\n\n- `text?: string | object`\n Full text of the document. If provided, the document will be re-indexed.\n\n- `title?: string | object`\n Title of the document.\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst memoryStatus = await client.memories.update('resource_id', { source: 'reddit' });\n\nconsole.log(memoryStatus);\n```", + "## update\n\n`client.memories.update(source: string, resource_id: string, collection?: string | object, date?: string | object, metadata?: object | object, text?: string | object, title?: string | object): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**post** `/memories/update/{source}/{resource_id}`\n\nUpdates an existing document in the index. You can update the text, collection,\ntitle, and metadata. The document must already exist or a 404 will be returned.\nThis works for documents from any source (vault, slack, gmail, etc.).\n\nTo remove a collection, set it to null explicitly.\n\n### Parameters\n\n- `source: string`\n\n- `resource_id: string`\n\n- `collection?: string | object`\n The collection to move the document to — deprecated, set the collection using metadata instead.\n\n- `date?: string | object`\n Date of the document for ranking and filtering.\n\n- `metadata?: object | object`\n Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars. Values must be string, number, boolean, or null. Will be merged with existing metadata.\n\n- `text?: string | object`\n Full text of the document. If provided, the document will be re-indexed.\n\n- `title?: string | object`\n Title of the document.\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst memoryStatus = await client.memories.update('resource_id', { source: 'reddit' });\n\nconsole.log(memoryStatus);\n```", perLanguage: { cli: { method: 'memories update', @@ -667,7 +667,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.update', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.memories.update('resource_id', { source: 'reddit' });\n\nconsole.log(memoryStatus.resource_id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.memories.update('resource_id', { source: 'reddit' });\n\nconsole.log(memoryStatus.resource_id);", }, }, }, @@ -691,7 +691,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ resource_id: string; source: string; folder_id?: string; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; parent_folder_id?: string; score?: number; title?: string; }", markdown: - "## list\n\n`client.memories.list(collection?: string, cursor?: string, filter?: string, size?: number, source?: string, status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'): { resource_id: string; source: string; folder_id?: string; metadata?: metadata; parent_folder_id?: string; score?: number; title?: string; }`\n\n**get** `/memories/list`\n\nThis endpoint allows you to paginate through all documents in the index.\nYou can filter the documents by title, date, metadata, etc.\n\n### Parameters\n\n- `collection?: string`\n Filter documents by collection.\n\n- `cursor?: string`\n\n- `filter?: string`\n Filter documents by metadata using MongoDB-style operators. Example: {\"department\": \"engineering\", \"priority\": {\"$gt\": 3}}\n\n- `size?: number`\n\n- `source?: string`\n Filter documents by source.\n\n- `status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n Filter documents by status.\n\n### Returns\n\n- `{ resource_id: string; source: string; folder_id?: string; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; parent_folder_id?: string; score?: number; title?: string; }`\n\n - `resource_id: string`\n - `source: string`\n - `folder_id?: string`\n - `metadata?: { created_at?: string; events?: { message: string; type: 'error' | 'warning' | 'info' | 'success'; time?: string; }[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }`\n - `parent_folder_id?: string`\n - `score?: number`\n - `title?: string`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\n// Automatically fetches more pages as needed.\nfor await (const resource of client.memories.list()) {\n console.log(resource);\n}\n```", + "## list\n\n`client.memories.list(collection?: string, cursor?: string, filter?: string, size?: number, source?: string, status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'): { resource_id: string; source: string; folder_id?: string; metadata?: metadata; parent_folder_id?: string; score?: number; title?: string; }`\n\n**get** `/memories/list`\n\nThis endpoint allows you to paginate through all documents in the index.\nYou can filter the documents by title, date, metadata, etc.\n\n### Parameters\n\n- `collection?: string`\n Filter documents by collection.\n\n- `cursor?: string`\n\n- `filter?: string`\n Filter documents by metadata using MongoDB-style operators. Example: {\"department\": \"engineering\", \"priority\": {\"$gt\": 3}}\n\n- `size?: number`\n\n- `source?: string`\n Filter documents by source.\n\n- `status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n Filter documents by status.\n\n### Returns\n\n- `{ resource_id: string; source: string; folder_id?: string; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; parent_folder_id?: string; score?: number; title?: string; }`\n\n - `resource_id: string`\n - `source: string`\n - `folder_id?: string`\n - `metadata?: { created_at?: string; events?: { message: string; type: 'error' | 'warning' | 'info' | 'success'; time?: string; }[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }`\n - `parent_folder_id?: string`\n - `score?: number`\n - `title?: string`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\n// Automatically fetches more pages as needed.\nfor await (const resource of client.memories.list()) {\n console.log(resource);\n}\n```", perLanguage: { cli: { method: 'memories list', @@ -714,7 +714,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.list', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const resource of client.memories.list()) {\n console.log(resource.resource_id);\n}", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const resource of client.memories.list()) {\n console.log(resource.resource_id);\n}", }, }, }, @@ -728,7 +728,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ qualified: 'client.memories.status', response: '{ providers: object; total: object; }', markdown: - "## status\n\n`client.memories.status(): { providers: object; total: object; }`\n\n**get** `/memories/status`\n\nThis endpoint shows the indexing progress of documents, both by provider and total.\n\n### Returns\n\n- `{ providers: object; total: object; }`\n\n - `providers: object`\n - `total: object`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.memories.status();\n\nconsole.log(response);\n```", + "## status\n\n`client.memories.status(): { providers: object; total: object; }`\n\n**get** `/memories/status`\n\nThis endpoint shows the indexing progress of documents, both by provider and total.\n\n### Returns\n\n- `{ providers: object; total: object; }`\n\n - `providers: object`\n - `total: object`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.memories.status();\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'memories status', @@ -751,7 +751,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.status', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.memories.status();\n\nconsole.log(response.providers);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.memories.status();\n\nconsole.log(response.providers);", }, }, }, @@ -767,7 +767,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ resource_id: string; source: string; type: string; data?: object[]; memories?: string[]; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; title?: string; }", markdown: - "## get\n\n`client.memories.get(source: string, resource_id: string): { resource_id: string; source: string; type: string; data?: object[]; memories?: string[]; metadata?: metadata; title?: string; }`\n\n**get** `/memories/get/{source}/{resource_id}`\n\nRetrieves a document by provider and resource_id.\n\n### Parameters\n\n- `source: string`\n\n- `resource_id: string`\n\n### Returns\n\n- `{ resource_id: string; source: string; type: string; data?: object[]; memories?: string[]; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; title?: string; }`\n Response model for the GET /memories/get endpoint.\n\n - `resource_id: string`\n - `source: string`\n - `type: string`\n - `data?: object[]`\n - `memories?: string[]`\n - `metadata?: { created_at?: string; events?: { message: string; type: 'error' | 'warning' | 'info' | 'success'; time?: string; }[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }`\n - `title?: string`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst memory = await client.memories.get('resource_id', { source: 'reddit' });\n\nconsole.log(memory);\n```", + "## get\n\n`client.memories.get(source: string, resource_id: string): { resource_id: string; source: string; type: string; data?: object[]; memories?: string[]; metadata?: metadata; title?: string; }`\n\n**get** `/memories/get/{source}/{resource_id}`\n\nRetrieves a document by provider and resource_id.\n\n### Parameters\n\n- `source: string`\n\n- `resource_id: string`\n\n### Returns\n\n- `{ resource_id: string; source: string; type: string; data?: object[]; memories?: string[]; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; title?: string; }`\n Response model for the GET /memories/get endpoint.\n\n - `resource_id: string`\n - `source: string`\n - `type: string`\n - `data?: object[]`\n - `memories?: string[]`\n - `metadata?: { created_at?: string; events?: { message: string; type: 'error' | 'warning' | 'info' | 'success'; time?: string; }[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }`\n - `title?: string`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst memory = await client.memories.get('resource_id', { source: 'reddit' });\n\nconsole.log(memory);\n```", perLanguage: { cli: { method: 'memories get', @@ -791,7 +791,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.get', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memory = await client.memories.get('resource_id', { source: 'reddit' });\n\nconsole.log(memory.resource_id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memory = await client.memories.get('resource_id', { source: 'reddit' });\n\nconsole.log(memory.resource_id);", }, }, }, @@ -814,7 +814,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: '{ documents: { resource_id: string; source: string; folder_id?: string; metadata?: metadata; parent_folder_id?: string; score?: number; title?: string; }[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }', markdown: - "## search\n\n`client.memories.search(query: string, answer?: boolean, effort?: number, max_results?: number, options?: { after?: string; answer_model?: string; before?: string; box?: { weight?: number; }; filter?: object; google_calendar?: { calendar_id?: string; weight?: number; }; google_drive?: { weight?: number; }; google_mail?: { label_ids?: string[]; weight?: number; }; max_results?: number; memory_types?: 'procedure' | 'memory' | 'mood'[]; notion?: { notion_page_ids?: string[]; weight?: number; }; reddit?: { period?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'all'; sort?: 'relevance' | 'new' | 'hot' | 'top' | 'comments'; subreddit?: string; weight?: number; }; resource_ids?: string[]; slack?: { channels?: string[]; exclude_archived?: boolean; include_dms?: boolean; include_group_dms?: boolean; include_private?: boolean; weight?: number; }; vault?: { weight?: number; }; web_crawler?: { max_depth?: number; url?: string; weight?: number; }; }, sources?: string[]): { documents: resource[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }`\n\n**post** `/memories/query`\n\nRetrieves documents matching the query.\n\n### Parameters\n\n- `query: string`\n Query to run.\n\n- `answer?: boolean`\n If true, the query will be answered along with matching source documents.\n\n- `effort?: number`\n Effort level. 0 = pass query through verbatim. 1 = LLM rewrites the query for better retrieval and extracts date filters.\n\n- `max_results?: number`\n Maximum number of results to return.\n\n- `options?: { after?: string; answer_model?: string; before?: string; box?: { weight?: number; }; filter?: object; google_calendar?: { calendar_id?: string; weight?: number; }; google_drive?: { weight?: number; }; google_mail?: { label_ids?: string[]; weight?: number; }; max_results?: number; memory_types?: 'procedure' | 'memory' | 'mood'[]; notion?: { notion_page_ids?: string[]; weight?: number; }; reddit?: { period?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'all'; sort?: 'relevance' | 'new' | 'hot' | 'top' | 'comments'; subreddit?: string; weight?: number; }; resource_ids?: string[]; slack?: { channels?: string[]; exclude_archived?: boolean; include_dms?: boolean; include_group_dms?: boolean; include_private?: boolean; weight?: number; }; vault?: { weight?: number; }; web_crawler?: { max_depth?: number; url?: string; weight?: number; }; }`\n Search options for the query.\n - `after?: string`\n Only query documents created on or after this date.\n - `answer_model?: string`\n Model to use for answer generation when answer=True\n - `before?: string`\n Only query documents created before this date.\n - `box?: { weight?: number; }`\n Search options for Box\n - `filter?: object`\n Metadata filters using MongoDB-style operators. Example: {'status': 'published', 'priority': {'$gt': 3}}\n - `google_calendar?: { calendar_id?: string; weight?: number; }`\n Search options for Google Calendar\n - `google_drive?: { weight?: number; }`\n Search options for Google Drive\n - `google_mail?: { label_ids?: string[]; weight?: number; }`\n Search options for Gmail\n - `max_results?: number`\n Maximum number of results to return.\n - `memory_types?: 'procedure' | 'memory' | 'mood'[]`\n Filter by memory type. Defaults to generic memories only. Pass multiple types to include procedures, etc.\n - `notion?: { notion_page_ids?: string[]; weight?: number; }`\n Search options for Notion\n - `reddit?: { period?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'all'; sort?: 'relevance' | 'new' | 'hot' | 'top' | 'comments'; subreddit?: string; weight?: number; }`\n Search options for Reddit\n - `resource_ids?: string[]`\n Only return results from these specific resource IDs. Useful for scoping searches to specific documents (e.g., a specific email thread or uploaded file).\n - `slack?: { channels?: string[]; exclude_archived?: boolean; include_dms?: boolean; include_group_dms?: boolean; include_private?: boolean; weight?: number; }`\n Search options for Slack\n - `vault?: { weight?: number; }`\n Search options for vault\n - `web_crawler?: { max_depth?: number; url?: string; weight?: number; }`\n Search options for Web Crawler\n\n- `sources?: string[]`\n Only query documents from these sources.\n\n### Returns\n\n- `{ documents: { resource_id: string; source: string; folder_id?: string; metadata?: metadata; parent_folder_id?: string; score?: number; title?: string; }[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }`\n\n - `documents: { resource_id: string; source: string; folder_id?: string; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; parent_folder_id?: string; score?: number; title?: string; }[]`\n - `answer?: string`\n - `errors?: object[]`\n - `query_id?: string`\n - `score?: number`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst queryResult = await client.memories.search({ query: 'What does Hyperspell do?' });\n\nconsole.log(queryResult);\n```", + "## search\n\n`client.memories.search(query: string, answer?: boolean, effort?: number, max_results?: number, options?: { after?: string; answer_model?: string; before?: string; box?: { weight?: number; }; filter?: object; google_calendar?: { calendar_id?: string; weight?: number; }; google_drive?: { weight?: number; }; google_mail?: { label_ids?: string[]; weight?: number; }; max_results?: number; memory_types?: 'procedure' | 'memory' | 'mood'[]; notion?: { notion_page_ids?: string[]; weight?: number; }; reddit?: { period?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'all'; sort?: 'relevance' | 'new' | 'hot' | 'top' | 'comments'; subreddit?: string; weight?: number; }; resource_ids?: string[]; slack?: { channels?: string[]; exclude_archived?: boolean; include_dms?: boolean; include_group_dms?: boolean; include_private?: boolean; weight?: number; }; vault?: { weight?: number; }; web_crawler?: { max_depth?: number; url?: string; weight?: number; }; }, sources?: string[]): { documents: resource[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }`\n\n**post** `/memories/query`\n\nRetrieves documents matching the query.\n\n### Parameters\n\n- `query: string`\n Query to run.\n\n- `answer?: boolean`\n If true, the query will be answered along with matching source documents.\n\n- `effort?: number`\n Effort level. 0 = pass query through verbatim. 1 = LLM rewrites the query for better retrieval and extracts date filters.\n\n- `max_results?: number`\n Maximum number of results to return.\n\n- `options?: { after?: string; answer_model?: string; before?: string; box?: { weight?: number; }; filter?: object; google_calendar?: { calendar_id?: string; weight?: number; }; google_drive?: { weight?: number; }; google_mail?: { label_ids?: string[]; weight?: number; }; max_results?: number; memory_types?: 'procedure' | 'memory' | 'mood'[]; notion?: { notion_page_ids?: string[]; weight?: number; }; reddit?: { period?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'all'; sort?: 'relevance' | 'new' | 'hot' | 'top' | 'comments'; subreddit?: string; weight?: number; }; resource_ids?: string[]; slack?: { channels?: string[]; exclude_archived?: boolean; include_dms?: boolean; include_group_dms?: boolean; include_private?: boolean; weight?: number; }; vault?: { weight?: number; }; web_crawler?: { max_depth?: number; url?: string; weight?: number; }; }`\n Search options for the query.\n - `after?: string`\n Only query documents created on or after this date.\n - `answer_model?: string`\n Model to use for answer generation when answer=True\n - `before?: string`\n Only query documents created before this date.\n - `box?: { weight?: number; }`\n Search options for Box\n - `filter?: object`\n Metadata filters using MongoDB-style operators. Example: {'status': 'published', 'priority': {'$gt': 3}}\n - `google_calendar?: { calendar_id?: string; weight?: number; }`\n Search options for Google Calendar\n - `google_drive?: { weight?: number; }`\n Search options for Google Drive\n - `google_mail?: { label_ids?: string[]; weight?: number; }`\n Search options for Gmail\n - `max_results?: number`\n Maximum number of results to return.\n - `memory_types?: 'procedure' | 'memory' | 'mood'[]`\n Filter by memory type. Defaults to generic memories only. Pass multiple types to include procedures, etc.\n - `notion?: { notion_page_ids?: string[]; weight?: number; }`\n Search options for Notion\n - `reddit?: { period?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'all'; sort?: 'relevance' | 'new' | 'hot' | 'top' | 'comments'; subreddit?: string; weight?: number; }`\n Search options for Reddit\n - `resource_ids?: string[]`\n Only return results from these specific resource IDs. Useful for scoping searches to specific documents (e.g., a specific email thread or uploaded file).\n - `slack?: { channels?: string[]; exclude_archived?: boolean; include_dms?: boolean; include_group_dms?: boolean; include_private?: boolean; weight?: number; }`\n Search options for Slack\n - `vault?: { weight?: number; }`\n Search options for vault\n - `web_crawler?: { max_depth?: number; url?: string; weight?: number; }`\n Search options for Web Crawler\n\n- `sources?: string[]`\n Only query documents from these sources.\n\n### Returns\n\n- `{ documents: { resource_id: string; source: string; folder_id?: string; metadata?: metadata; parent_folder_id?: string; score?: number; title?: string; }[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }`\n\n - `documents: { resource_id: string; source: string; folder_id?: string; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; parent_folder_id?: string; score?: number; title?: string; }[]`\n - `answer?: string`\n - `errors?: object[]`\n - `query_id?: string`\n - `score?: number`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst queryResult = await client.memories.search({ query: 'What does Hyperspell do?' });\n\nconsole.log(queryResult);\n```", perLanguage: { cli: { method: 'memories search', @@ -838,7 +838,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.search', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst queryResult = await client.memories.search({ query: 'What does Hyperspell do?' });\n\nconsole.log(queryResult.query_id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst queryResult = await client.memories.search({ query: 'What does Hyperspell do?' });\n\nconsole.log(queryResult.query_id);", }, }, }, @@ -855,7 +855,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: '{ chunks_deleted: number; message: string; resource_id: string; source: string; success: boolean; }', markdown: - "## delete\n\n`client.memories.delete(source: string, resource_id: string): { chunks_deleted: number; message: string; resource_id: string; source: string; success: boolean; }`\n\n**delete** `/memories/delete/{source}/{resource_id}`\n\nDelete a memory and its associated chunks from the index.\n\nThis removes the memory completely from the vector index and database.\nThe operation deletes:\n1. All chunks associated with the resource (including embeddings)\n2. The resource record itself\n\nArgs:\n source: The document provider (e.g., gmail, notion, vault)\n resource_id: The unique identifier of the resource to delete\n api_token: Authentication token\n\nReturns:\n MemoryDeletionResponse with deletion details\n\nRaises:\n DocumentNotFound: If the resource doesn't exist or user doesn't have access\n\n### Parameters\n\n- `source: string`\n\n- `resource_id: string`\n\n### Returns\n\n- `{ chunks_deleted: number; message: string; resource_id: string; source: string; success: boolean; }`\n\n - `chunks_deleted: number`\n - `message: string`\n - `resource_id: string`\n - `source: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst memory = await client.memories.delete('resource_id', { source: 'reddit' });\n\nconsole.log(memory);\n```", + "## delete\n\n`client.memories.delete(source: string, resource_id: string): { chunks_deleted: number; message: string; resource_id: string; source: string; success: boolean; }`\n\n**delete** `/memories/delete/{source}/{resource_id}`\n\nDelete a memory and its associated chunks from the index.\n\nThis removes the memory completely from the vector index and database.\nThe operation deletes:\n1. All chunks associated with the resource (including embeddings)\n2. The resource record itself\n\nArgs:\n source: The document provider (e.g., gmail, notion, vault)\n resource_id: The unique identifier of the resource to delete\n api_token: Authentication token\n\nReturns:\n MemoryDeletionResponse with deletion details\n\nRaises:\n DocumentNotFound: If the resource doesn't exist or user doesn't have access\n\n### Parameters\n\n- `source: string`\n\n- `resource_id: string`\n\n### Returns\n\n- `{ chunks_deleted: number; message: string; resource_id: string; source: string; success: boolean; }`\n\n - `chunks_deleted: number`\n - `message: string`\n - `resource_id: string`\n - `source: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst memory = await client.memories.delete('resource_id', { source: 'reddit' });\n\nconsole.log(memory);\n```", perLanguage: { cli: { method: 'memories delete', @@ -879,7 +879,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.memories.delete', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memory = await client.memories.delete('resource_id', { source: 'reddit' });\n\nconsole.log(memory.resource_id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memory = await client.memories.delete('resource_id', { source: 'reddit' });\n\nconsole.log(memory.resource_id);", }, }, }, @@ -895,7 +895,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: '{ documents: { resource_id: string; source: string; folder_id?: string; metadata?: metadata; parent_folder_id?: string; score?: number; title?: string; }[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }', markdown: - "## get_query\n\n`client.evaluate.getQuery(query_id: string): { documents: resource[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }`\n\n**get** `/evaluate/query/{query_id}`\n\nRetrieve the result of a previous query.\n\n### Parameters\n\n- `query_id: string`\n\n### Returns\n\n- `{ documents: { resource_id: string; source: string; folder_id?: string; metadata?: metadata; parent_folder_id?: string; score?: number; title?: string; }[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }`\n\n - `documents: { resource_id: string; source: string; folder_id?: string; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; parent_folder_id?: string; score?: number; title?: string; }[]`\n - `answer?: string`\n - `errors?: object[]`\n - `query_id?: string`\n - `score?: number`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst queryResult = await client.evaluate.getQuery('query_id');\n\nconsole.log(queryResult);\n```", + "## get_query\n\n`client.evaluate.getQuery(query_id: string): { documents: resource[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }`\n\n**get** `/evaluate/query/{query_id}`\n\nRetrieve the result of a previous query.\n\n### Parameters\n\n- `query_id: string`\n\n### Returns\n\n- `{ documents: { resource_id: string; source: string; folder_id?: string; metadata?: metadata; parent_folder_id?: string; score?: number; title?: string; }[]; answer?: string; errors?: object[]; query_id?: string; score?: number; }`\n\n - `documents: { resource_id: string; source: string; folder_id?: string; metadata?: { created_at?: string; events?: notification[]; indexed_at?: string; last_modified?: string; status?: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; url?: string; }; parent_folder_id?: string; score?: number; title?: string; }[]`\n - `answer?: string`\n - `errors?: object[]`\n - `query_id?: string`\n - `score?: number`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst queryResult = await client.evaluate.getQuery('query_id');\n\nconsole.log(queryResult);\n```", perLanguage: { cli: { method: 'evaluate get_query', @@ -918,7 +918,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.evaluate.getQuery', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst queryResult = await client.evaluate.getQuery('query_id');\n\nconsole.log(queryResult.query_id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst queryResult = await client.evaluate.getQuery('query_id');\n\nconsole.log(queryResult.query_id);", }, }, }, @@ -933,7 +933,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ params: ['query_id: string;', 'score?: number;'], response: '{ message: string; success: boolean; }', markdown: - "## score_query\n\n`client.evaluate.scoreQuery(query_id: string, score?: number): { message: string; success: boolean; }`\n\n**post** `/evaluate/query/{query_id}`\n\nScore the result of a query.\n\n### Parameters\n\n- `query_id: string`\n\n- `score?: number`\n Rating of the query result from -1 (bad) to +1 (good).\n\n### Returns\n\n- `{ message: string; success: boolean; }`\n\n - `message: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.evaluate.scoreQuery('query_id');\n\nconsole.log(response);\n```", + "## score_query\n\n`client.evaluate.scoreQuery(query_id: string, score?: number): { message: string; success: boolean; }`\n\n**post** `/evaluate/query/{query_id}`\n\nScore the result of a query.\n\n### Parameters\n\n- `query_id: string`\n\n- `score?: number`\n Rating of the query result from -1 (bad) to +1 (good).\n\n### Returns\n\n- `{ message: string; success: boolean; }`\n\n - `message: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.evaluate.scoreQuery('query_id');\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'evaluate score_query', @@ -956,7 +956,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.evaluate.scoreQuery', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.evaluate.scoreQuery('query_id');\n\nconsole.log(response.message);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.evaluate.scoreQuery('query_id');\n\nconsole.log(response.message);", }, }, }, @@ -971,7 +971,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ params: ['highlight_id: string;', 'comment?: string;', 'score?: number;'], response: '{ message: string; success: boolean; }', markdown: - "## score_highlight\n\n`client.evaluate.scoreHighlight(highlight_id: string, comment?: string, score?: number): { message: string; success: boolean; }`\n\n**post** `/evaluate/highlight/{highlight_id}`\n\nScore an individual highlight.\n\n### Parameters\n\n- `highlight_id: string`\n\n- `comment?: string`\n Comment on the chunk\n\n- `score?: number`\n Rating of the chunk from -1 (bad) to +1 (good).\n\n### Returns\n\n- `{ message: string; success: boolean; }`\n\n - `message: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.evaluate.scoreHighlight('highlight_id');\n\nconsole.log(response);\n```", + "## score_highlight\n\n`client.evaluate.scoreHighlight(highlight_id: string, comment?: string, score?: number): { message: string; success: boolean; }`\n\n**post** `/evaluate/highlight/{highlight_id}`\n\nScore an individual highlight.\n\n### Parameters\n\n- `highlight_id: string`\n\n- `comment?: string`\n Comment on the chunk\n\n- `score?: number`\n Rating of the chunk from -1 (bad) to +1 (good).\n\n### Returns\n\n- `{ message: string; success: boolean; }`\n\n - `message: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.evaluate.scoreHighlight('highlight_id');\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'evaluate score_highlight', @@ -995,7 +995,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.evaluate.scoreHighlight', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.evaluate.scoreHighlight('highlight_id');\n\nconsole.log(response.message);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.evaluate.scoreHighlight('highlight_id');\n\nconsole.log(response.message);", }, }, }, @@ -1016,7 +1016,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ ], response: '{ success: boolean; error?: string; provider_response?: object; }', markdown: - "## send_message\n\n`client.actions.sendMessage(provider: string, text: string, channel?: string, connection?: string, parent?: string): { success: boolean; error?: string; provider_response?: object; }`\n\n**post** `/actions/send_message`\n\nSend a message to a channel or conversation on a connected integration.\n\n### Parameters\n\n- `provider: string`\n Integration provider (e.g., slack)\n\n- `text: string`\n Message text\n\n- `channel?: string`\n Channel ID (required for Slack)\n\n- `connection?: string`\n Connection ID. If omitted, auto-resolved from provider + user.\n\n- `parent?: string`\n Parent message ID for threading (thread_ts for Slack)\n\n### Returns\n\n- `{ success: boolean; error?: string; provider_response?: object; }`\n Result from executing an integration action.\n\n - `success: boolean`\n - `error?: string`\n - `provider_response?: object`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.actions.sendMessage({ provider: 'reddit', text: 'text' });\n\nconsole.log(response);\n```", + "## send_message\n\n`client.actions.sendMessage(provider: string, text: string, channel?: string, connection?: string, parent?: string): { success: boolean; error?: string; provider_response?: object; }`\n\n**post** `/actions/send_message`\n\nSend a message to a channel or conversation on a connected integration.\n\n### Parameters\n\n- `provider: string`\n Integration provider (e.g., slack)\n\n- `text: string`\n Message text\n\n- `channel?: string`\n Channel ID (required for Slack)\n\n- `connection?: string`\n Connection ID. If omitted, auto-resolved from provider + user.\n\n- `parent?: string`\n Parent message ID for threading (thread_ts for Slack)\n\n### Returns\n\n- `{ success: boolean; error?: string; provider_response?: object; }`\n Result from executing an integration action.\n\n - `success: boolean`\n - `error?: string`\n - `provider_response?: object`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.actions.sendMessage({ provider: 'reddit', text: 'text' });\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'actions send_message', @@ -1040,7 +1040,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.actions.sendMessage', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.actions.sendMessage({ provider: 'reddit', text: 'text' });\n\nconsole.log(response.provider_response);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.actions.sendMessage({ provider: 'reddit', text: 'text' });\n\nconsole.log(response.provider_response);", }, }, }, @@ -1061,7 +1061,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ ], response: '{ success: boolean; error?: string; provider_response?: object; }', markdown: - "## add_reaction\n\n`client.actions.addReaction(channel: string, name: string, provider: string, timestamp: string, connection?: string): { success: boolean; error?: string; provider_response?: object; }`\n\n**post** `/actions/add_reaction`\n\nAdd an emoji reaction to a message on a connected integration.\n\n### Parameters\n\n- `channel: string`\n Channel ID containing the message\n\n- `name: string`\n Emoji name without colons (e.g., thumbsup)\n\n- `provider: string`\n Integration provider (e.g., slack)\n\n- `timestamp: string`\n Message timestamp to react to\n\n- `connection?: string`\n Connection ID. If omitted, auto-resolved from provider + user.\n\n### Returns\n\n- `{ success: boolean; error?: string; provider_response?: object; }`\n Result from executing an integration action.\n\n - `success: boolean`\n - `error?: string`\n - `provider_response?: object`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.actions.addReaction({\n channel: 'channel',\n name: 'name',\n provider: 'reddit',\n timestamp: 'timestamp',\n});\n\nconsole.log(response);\n```", + "## add_reaction\n\n`client.actions.addReaction(channel: string, name: string, provider: string, timestamp: string, connection?: string): { success: boolean; error?: string; provider_response?: object; }`\n\n**post** `/actions/add_reaction`\n\nAdd an emoji reaction to a message on a connected integration.\n\n### Parameters\n\n- `channel: string`\n Channel ID containing the message\n\n- `name: string`\n Emoji name without colons (e.g., thumbsup)\n\n- `provider: string`\n Integration provider (e.g., slack)\n\n- `timestamp: string`\n Message timestamp to react to\n\n- `connection?: string`\n Connection ID. If omitted, auto-resolved from provider + user.\n\n### Returns\n\n- `{ success: boolean; error?: string; provider_response?: object; }`\n Result from executing an integration action.\n\n - `success: boolean`\n - `error?: string`\n - `provider_response?: object`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.actions.addReaction({\n channel: 'channel',\n name: 'name',\n provider: 'reddit',\n timestamp: 'timestamp',\n});\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'actions add_reaction', @@ -1085,7 +1085,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.actions.addReaction', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.actions.addReaction({\n channel: 'channel',\n name: 'name',\n provider: 'reddit',\n timestamp: 'timestamp',\n});\n\nconsole.log(response.provider_response);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.actions.addReaction({\n channel: 'channel',\n name: 'name',\n provider: 'reddit',\n timestamp: 'timestamp',\n});\n\nconsole.log(response.provider_response);", }, }, }, @@ -1110,7 +1110,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }", markdown: - "## add\n\n`client.sessions.add(history: string, date?: string, extract?: 'procedure' | 'memory' | 'mood'[], format?: 'vercel' | 'hyperdoc' | 'openclaw', metadata?: object, session_id?: string, title?: string): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**post** `/trace/add`\n\nAdd an agent trace/transcript to the index.\n\nAccepts traces as a string in Hyperdoc format (native), Vercel AI SDK format,\nor OpenClaw JSONL format. The format is auto-detected if not specified.\n\n**Hyperdoc format** (JSON array, snake_case with type discriminators):\n```json\n{\"history\": \"[{\\\"type\\\": \\\"trace_message\\\", \\\"role\\\": \\\"user\\\", \\\"text\\\": \\\"Hello\\\"}]\"}\n```\n\n**Vercel AI SDK format** (JSON array, camelCase):\n```json\n{\"history\": \"[{\\\"role\\\": \\\"user\\\", \\\"content\\\": \\\"Hello\\\"}]\"}\n```\n\n**OpenClaw JSONL format** (newline-delimited JSON):\n```json\n{\"history\": \"{\\\"type\\\":\\\"session\\\",\\\"id\\\":\\\"abc\\\"}\\n{\\\"type\\\":\\\"message\\\",\\\"message\\\":{\\\"role\\\":\\\"user\\\",...}}\"}\n```\n\n### Parameters\n\n- `history: string`\n The trace history as a string. Can be a JSON array of Hyperdoc steps, a JSON array of Vercel AI SDK steps, or OpenClaw JSONL.\n\n- `date?: string`\n Date of the trace\n\n- `extract?: 'procedure' | 'memory' | 'mood'[]`\n What kind of memories to extract from the trace\n\n- `format?: 'vercel' | 'hyperdoc' | 'openclaw'`\n Trace format: 'vercel', 'hyperdoc', or 'openclaw'. Auto-detected if not set.\n\n- `metadata?: object`\n Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars.\n\n- `session_id?: string`\n Resource identifier for the trace.\n\n- `title?: string`\n Title of the trace\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst memoryStatus = await client.sessions.add({ history: 'history' });\n\nconsole.log(memoryStatus);\n```", + "## add\n\n`client.sessions.add(history: string, date?: string, extract?: 'procedure' | 'memory' | 'mood'[], format?: 'vercel' | 'hyperdoc' | 'openclaw', metadata?: object, session_id?: string, title?: string): { resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n**post** `/trace/add`\n\nAdd an agent trace/transcript to the index.\n\nAccepts traces as a string in Hyperdoc format (native), Vercel AI SDK format,\nor OpenClaw JSONL format. The format is auto-detected if not specified.\n\n**Hyperdoc format** (JSON array, snake_case with type discriminators):\n```json\n{\"history\": \"[{\\\"type\\\": \\\"trace_message\\\", \\\"role\\\": \\\"user\\\", \\\"text\\\": \\\"Hello\\\"}]\"}\n```\n\n**Vercel AI SDK format** (JSON array, camelCase):\n```json\n{\"history\": \"[{\\\"role\\\": \\\"user\\\", \\\"content\\\": \\\"Hello\\\"}]\"}\n```\n\n**OpenClaw JSONL format** (newline-delimited JSON):\n```json\n{\"history\": \"{\\\"type\\\":\\\"session\\\",\\\"id\\\":\\\"abc\\\"}\\n{\\\"type\\\":\\\"message\\\",\\\"message\\\":{\\\"role\\\":\\\"user\\\",...}}\"}\n```\n\n### Parameters\n\n- `history: string`\n The trace history as a string. Can be a JSON array of Hyperdoc steps, a JSON array of Vercel AI SDK steps, or OpenClaw JSONL.\n\n- `date?: string`\n Date of the trace\n\n- `extract?: 'procedure' | 'memory' | 'mood'[]`\n What kind of memories to extract from the trace\n\n- `format?: 'vercel' | 'hyperdoc' | 'openclaw'`\n Trace format: 'vercel', 'hyperdoc', or 'openclaw'. Auto-detected if not set.\n\n- `metadata?: object`\n Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars.\n\n- `session_id?: string`\n Resource identifier for the trace.\n\n- `title?: string`\n Title of the trace\n\n### Returns\n\n- `{ resource_id: string; source: string; status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'; }`\n\n - `resource_id: string`\n - `source: string`\n - `status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst memoryStatus = await client.sessions.add({ history: 'history' });\n\nconsole.log(memoryStatus);\n```", perLanguage: { cli: { method: 'sessions add', @@ -1133,7 +1133,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.sessions.add', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.sessions.add({ history: 'history' });\n\nconsole.log(memoryStatus.resource_id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.sessions.add({ history: 'history' });\n\nconsole.log(memoryStatus.resource_id);", }, }, }, @@ -1149,7 +1149,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ params: ['cursor?: string;', 'size?: number;'], response: '{ collection: string; document_count: number; }', markdown: - "## list\n\n`client.vaults.list(cursor?: string, size?: number): { collection: string; document_count: number; }`\n\n**get** `/vault/list`\n\nThis endpoint lists all collections, and how many documents are in each collection.\nAll documents that do not have a collection assigned are in the `null` collection.\n\n### Parameters\n\n- `cursor?: string`\n\n- `size?: number`\n\n### Returns\n\n- `{ collection: string; document_count: number; }`\n\n - `collection: string`\n - `document_count: number`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\n// Automatically fetches more pages as needed.\nfor await (const vaultListResponse of client.vaults.list()) {\n console.log(vaultListResponse);\n}\n```", + "## list\n\n`client.vaults.list(cursor?: string, size?: number): { collection: string; document_count: number; }`\n\n**get** `/vault/list`\n\nThis endpoint lists all collections, and how many documents are in each collection.\nAll documents that do not have a collection assigned are in the `null` collection.\n\n### Parameters\n\n- `cursor?: string`\n\n- `size?: number`\n\n### Returns\n\n- `{ collection: string; document_count: number; }`\n\n - `collection: string`\n - `document_count: number`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\n// Automatically fetches more pages as needed.\nfor await (const vaultListResponse of client.vaults.list()) {\n console.log(vaultListResponse);\n}\n```", perLanguage: { cli: { method: 'vaults list', @@ -1172,7 +1172,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.vaults.list', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const vaultListResponse of client.vaults.list()) {\n console.log(vaultListResponse.collection);\n}", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const vaultListResponse of client.vaults.list()) {\n console.log(vaultListResponse.collection);\n}", }, }, }, @@ -1188,7 +1188,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ params: ['user_id: string;', 'expires_in?: string;', 'origin?: string;'], response: '{ token: string; expires_at: string; }', markdown: - "## user_token\n\n`client.auth.userToken(user_id: string, expires_in?: string, origin?: string): { token: string; expires_at: string; }`\n\n**post** `/auth/user_token`\n\nUse this endpoint to create a user token for a specific user.\nThis token can be safely passed to your user-facing front-end.\n\n### Parameters\n\n- `user_id: string`\n\n- `expires_in?: string`\n Token lifetime, e.g., '30m', '2h', '1d'. Defaults to 24 hours if not provided.\n\n- `origin?: string`\n Origin of the request, used for CSRF protection. If set, the token will only be valid for requests originating from this origin.\n\n### Returns\n\n- `{ token: string; expires_at: string; }`\n\n - `token: string`\n - `expires_at: string`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst token = await client.auth.userToken({ user_id: 'user_id' });\n\nconsole.log(token);\n```", + "## user_token\n\n`client.auth.userToken(user_id: string, expires_in?: string, origin?: string): { token: string; expires_at: string; }`\n\n**post** `/auth/user_token`\n\nUse this endpoint to create a user token for a specific user.\nThis token can be safely passed to your user-facing front-end.\n\n### Parameters\n\n- `user_id: string`\n\n- `expires_in?: string`\n Token lifetime, e.g., '30m', '2h', '1d'. Defaults to 24 hours if not provided.\n\n- `origin?: string`\n Origin of the request, used for CSRF protection. If set, the token will only be valid for requests originating from this origin.\n\n### Returns\n\n- `{ token: string; expires_at: string; }`\n\n - `token: string`\n - `expires_at: string`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst token = await client.auth.userToken({ user_id: 'user_id' });\n\nconsole.log(token);\n```", perLanguage: { cli: { method: 'auth user_token', @@ -1211,7 +1211,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.auth.userToken', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst token = await client.auth.userToken({ user_id: 'user_id' });\n\nconsole.log(token.token);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst token = await client.auth.userToken({ user_id: 'user_id' });\n\nconsole.log(token.token);", }, }, }, @@ -1226,7 +1226,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: '{ id: string; app: { id: string; icon_url: string; name: string; redirect_url: string; }; available_integrations: string[]; installed_integrations: string[]; token_expiration: string; }', markdown: - "## me\n\n`client.auth.me(): { id: string; app: object; available_integrations: string[]; installed_integrations: string[]; token_expiration: string; }`\n\n**get** `/auth/me`\n\nEndpoint to get basic user data.\n\n### Returns\n\n- `{ id: string; app: { id: string; icon_url: string; name: string; redirect_url: string; }; available_integrations: string[]; installed_integrations: string[]; token_expiration: string; }`\n\n - `id: string`\n - `app: { id: string; icon_url: string; name: string; redirect_url: string; }`\n - `available_integrations: string[]`\n - `installed_integrations: string[]`\n - `token_expiration: string`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.auth.me();\n\nconsole.log(response);\n```", + "## me\n\n`client.auth.me(): { id: string; app: object; available_integrations: string[]; installed_integrations: string[]; token_expiration: string; }`\n\n**get** `/auth/me`\n\nEndpoint to get basic user data.\n\n### Returns\n\n- `{ id: string; app: { id: string; icon_url: string; name: string; redirect_url: string; }; available_integrations: string[]; installed_integrations: string[]; token_expiration: string; }`\n\n - `id: string`\n - `app: { id: string; icon_url: string; name: string; redirect_url: string; }`\n - `available_integrations: string[]`\n - `installed_integrations: string[]`\n - `token_expiration: string`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.auth.me();\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'auth me', @@ -1249,7 +1249,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.auth.me', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.auth.me();\n\nconsole.log(response.id);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.auth.me();\n\nconsole.log(response.id);", }, }, }, @@ -1263,7 +1263,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ qualified: 'client.auth.deleteUser', response: '{ message: string; success: boolean; }', markdown: - "## delete_user\n\n`client.auth.deleteUser(): { message: string; success: boolean; }`\n\n**delete** `/auth/delete`\n\nEndpoint to delete user.\n\n### Returns\n\n- `{ message: string; success: boolean; }`\n\n - `message: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.auth.deleteUser();\n\nconsole.log(response);\n```", + "## delete_user\n\n`client.auth.deleteUser(): { message: string; success: boolean; }`\n\n**delete** `/auth/delete`\n\nEndpoint to delete user.\n\n### Returns\n\n- `{ message: string; success: boolean; }`\n\n - `message: string`\n - `success: boolean`\n\n### Example\n\n```typescript\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\nconst response = await client.auth.deleteUser();\n\nconsole.log(response);\n```", perLanguage: { cli: { method: 'auth delete_user', @@ -1286,7 +1286,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ typescript: { method: 'client.auth.deleteUser', example: - "import Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.auth.deleteUser();\n\nconsole.log(response.message);", + "import Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.auth.deleteUser();\n\nconsole.log(response.message);", }, }, }, @@ -1306,7 +1306,7 @@ const EMBEDDED_READMES: { language: string; content: string }[] = [ { language: 'typescript', content: - "# Hyperspell TypeScript API Library\n\n[![NPM version](https://img.shields.io/npm/v/hyperspell.svg?label=npm%20(stable))](https://npmjs.org/package/hyperspell) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/hyperspell)\n\nThis library provides convenient access to the Hyperspell REST API from server-side TypeScript or JavaScript.\n\n\n\nThe REST API documentation can be found on [docs.hyperspell.com](https://docs.hyperspell.com/). The full API of this library can be found in [api.md](api.md).\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Hyperspell MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=hyperspell-mcp&config=eyJuYW1lIjoiaHlwZXJzcGVsbC1tY3AiLCJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9oeXBlcnNwZWxsLnN0bG1jcC5jb20iLCJoZWFkZXJzIjp7IngtaHlwZXJzcGVsbC1hcGkta2V5IjoiTXkgQVBJIEtleSIsIlgtQXMtVXNlciI6Ik15IFVzZXIgSUQifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22hyperspell-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fhyperspell.stlmcp.com%22%2C%22headers%22%3A%7B%22x-hyperspell-api-key%22%3A%22My%20API%20Key%22%2C%22X-As-User%22%3A%22My%20User%20ID%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Installation\n\n```sh\nnpm install hyperspell\n```\n\n\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n\n```js\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.memories.add({ text: '...' });\n\nconsole.log(memoryStatus.resource_id);\n```\n\n\n\n### Request & Response types\n\nThis library includes TypeScript definitions for all request params and response fields. You may import and use them like so:\n\n\n```ts\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst params: Hyperspell.MemoryAddParams = { text: '...' };\nconst memoryStatus: Hyperspell.MemoryStatus = await client.memories.add(params);\n```\n\nDocumentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.\n\n## File uploads\n\nRequest parameters that correspond to file uploads can be passed in many different forms:\n- `File` (or an object with the same structure)\n- a `fetch` `Response` (or an object with the same structure)\n- an `fs.ReadStream`\n- the return value of our `toFile` helper\n\n```ts\nimport fs from 'fs';\nimport Hyperspell, { toFile } from 'hyperspell';\n\nconst client = new Hyperspell();\n\n// If you have access to Node `fs` we recommend using `fs.createReadStream()`:\nawait client.memories.upload({ file: fs.createReadStream('/path/to/file') });\n\n// Or if you have the web `File` API you can pass a `File` instance:\nawait client.memories.upload({ file: new File(['my bytes'], 'file') });\n\n// You can also pass a `fetch` `Response`:\nawait client.memories.upload({ file: await fetch('https://somesite/file') });\n\n// Finally, if none of the above are convenient, you can use our `toFile` helper:\nawait client.memories.upload({ file: await toFile(Buffer.from('my bytes'), 'file') });\nawait client.memories.upload({ file: await toFile(new Uint8Array([0, 1, 2]), 'file') });\n```\n\n\n\n## Handling errors\n\nWhen the library is unable to connect to the API,\nor if the API returns a non-success status code (i.e., 4xx or 5xx response),\na subclass of `APIError` will be thrown:\n\n\n```ts\nconst memoryStatus = await client.memories.add({ text: '...' }).catch(async (err) => {\n if (err instanceof Hyperspell.APIError) {\n console.log(err.status); // 400\n console.log(err.name); // BadRequestError\n console.log(err.headers); // {server: 'nginx', ...}\n } else {\n throw err;\n }\n});\n```\n\nError codes are as follows:\n\n| Status Code | Error Type |\n| ----------- | -------------------------- |\n| 400 | `BadRequestError` |\n| 401 | `AuthenticationError` |\n| 403 | `PermissionDeniedError` |\n| 404 | `NotFoundError` |\n| 422 | `UnprocessableEntityError` |\n| 429 | `RateLimitError` |\n| >=500 | `InternalServerError` |\n| N/A | `APIConnectionError` |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,\n429 Rate Limit, and >=500 Internal errors will all be retried by default.\n\nYou can use the `maxRetries` option to configure or disable this:\n\n\n```js\n// Configure the default for all requests:\nconst client = new Hyperspell({\n maxRetries: 0, // default is 2\n});\n\n// Or, configure per-request:\nawait client.memories.add({ text: '...' }, {\n maxRetries: 5,\n});\n```\n\n### Timeouts\n\nRequests time out after 1 minute by default. You can configure this with a `timeout` option:\n\n\n```ts\n// Configure the default for all requests:\nconst client = new Hyperspell({\n timeout: 20 * 1000, // 20 seconds (default is 1 minute)\n});\n\n// Override per-request:\nawait client.memories.add({ text: '...' }, {\n timeout: 5 * 1000,\n});\n```\n\nOn timeout, an `APIConnectionTimeoutError` is thrown.\n\nNote that requests which time out will be [retried twice by default](#retries).\n\n## Auto-pagination\n\nList methods in the Hyperspell API are paginated.\nYou can use the `for await … of` syntax to iterate through items across all pages:\n\n```ts\nasync function fetchAllResources(params) {\n const allResources = [];\n // Automatically fetches more pages as needed.\n for await (const resource of client.memories.list()) {\n allResources.push(resource);\n }\n return allResources;\n}\n```\n\nAlternatively, you can request a single page at a time:\n\n```ts\nlet page = await client.memories.list();\nfor (const resource of page.items) {\n console.log(resource);\n}\n\n// Convenience methods are provided for manually paginating:\nwhile (page.hasNextPage()) {\n page = await page.getNextPage();\n // ...\n}\n```\n\n\n\n## Advanced Usage\n\n### Accessing raw Response data (e.g., headers)\n\nThe \"raw\" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.\nThis method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.\n\nYou can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.\nUnlike `.asResponse()` this method consumes the body, returning once it is parsed.\n\n\n```ts\nconst client = new Hyperspell();\n\nconst response = await client.memories.add({ text: '...' }).asResponse();\nconsole.log(response.headers.get('X-My-Header'));\nconsole.log(response.statusText); // access the underlying Response object\n\nconst { data: memoryStatus, response: raw } = await client.memories\n .add({ text: '...' })\n .withResponse();\nconsole.log(raw.headers.get('X-My-Header'));\nconsole.log(memoryStatus.resource_id);\n```\n\n### Logging\n\n> [!IMPORTANT]\n> All log messages are intended for debugging only. The format and content of log messages\n> may change between releases.\n\n#### Log levels\n\nThe log level can be configured in two ways:\n\n1. Via the `HYPERSPELL_LOG` environment variable\n2. Using the `logLevel` client option (overrides the environment variable if set)\n\n```ts\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n logLevel: 'debug', // Show all log messages\n});\n```\n\nAvailable log levels, from most to least verbose:\n\n- `'debug'` - Show debug messages, info, warnings, and errors\n- `'info'` - Show info messages, warnings, and errors\n- `'warn'` - Show warnings and errors (default)\n- `'error'` - Show only errors\n- `'off'` - Disable all logging\n\nAt the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.\nSome authentication-related headers are redacted, but sensitive data in request and response bodies\nmay still be visible.\n\n#### Custom logger\n\nBy default, this library logs to `globalThis.console`. You can also provide a custom logger.\nMost logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.\n\nWhen providing a custom logger, the `logLevel` option still controls which messages are emitted, messages\nbelow the configured level will not be sent to your logger.\n\n```ts\nimport Hyperspell from 'hyperspell';\nimport pino from 'pino';\n\nconst logger = pino();\n\nconst client = new Hyperspell({\n logger: logger.child({ name: 'Hyperspell' }),\n logLevel: 'debug', // Send all messages to pino, allowing it to filter\n});\n```\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API. If you need to access undocumented\nendpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.\nOptions on the client, such as retries, will be respected when making these requests.\n\n```ts\nawait client.post('/some/path', {\n body: { some_prop: 'foo' },\n query: { some_query_arg: 'bar' },\n});\n```\n\n#### Undocumented request params\n\nTo make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented\nparameter. This library doesn't validate at runtime that the request matches the type, so any extra values you\nsend will be sent as-is.\n\n```ts\nclient.memories.add({\n // ...\n // @ts-expect-error baz is not yet public\n baz: 'undocumented option',\n});\n```\n\nFor requests with the `GET` verb, any extra params will be in the query, all other requests will send the\nextra param in the body.\n\nIf you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request\noptions.\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you may access the response object with `// @ts-expect-error` on\nthe response object, or cast the response object to the requisite type. Like the request params, we do not\nvalidate or strip extra properties from the response from the API.\n\n### Customizing the fetch client\n\nBy default, this library expects a global `fetch` function is defined.\n\nIf you want to use a different `fetch` function, you can either polyfill the global:\n\n```ts\nimport fetch from 'my-fetch';\n\nglobalThis.fetch = fetch;\n```\n\nOr pass it to the client:\n\n```ts\nimport Hyperspell from 'hyperspell';\nimport fetch from 'my-fetch';\n\nconst client = new Hyperspell({ fetch });\n```\n\n### Fetch options\n\nIf you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)\n\n```ts\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n fetchOptions: {\n // `RequestInit` options\n },\n});\n```\n\n#### Configuring proxies\n\nTo modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy\noptions to requests:\n\n **Node** [[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]\n\n```ts\nimport Hyperspell from 'hyperspell';\nimport * as undici from 'undici';\n\nconst proxyAgent = new undici.ProxyAgent('http://localhost:8888');\nconst client = new Hyperspell({\n fetchOptions: {\n dispatcher: proxyAgent,\n },\n});\n```\n\n **Bun** [[docs](https://bun.sh/guides/http/proxy)]\n\n```ts\nimport Hyperspell from 'hyperspell';\n\nconst client = new Hyperspell({\n fetchOptions: {\n proxy: 'http://localhost:8888',\n },\n});\n```\n\n **Deno** [[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]\n\n```ts\nimport Hyperspell from 'npm:hyperspell';\n\nconst httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });\nconst client = new Hyperspell({\n fetchOptions: {\n client: httpClient,\n },\n});\n```\n\n## Frequently Asked Questions\n\n## Semantic versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n3. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/hyperspell/node-sdk/issues) with questions, bugs, or suggestions.\n\n## Requirements\n\nTypeScript >= 4.9 is supported.\n\nThe following runtimes are supported:\n\n- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)\n- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.\n- Deno v1.28.0 or higher.\n- Bun 1.0 or later.\n- Cloudflare Workers.\n- Vercel Edge Runtime.\n- Jest 28 or greater with the `\"node\"` environment (`\"jsdom\"` is not supported at this time).\n- Nitro v2.6 or greater.\n\nNote that React Native is not supported at this time.\n\nIf you are interested in other runtime environments, please open or upvote an issue on GitHub.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n", + "# Hyperspell TypeScript API Library\n\n[![NPM version](https://img.shields.io/npm/v/@hyperspell/hyperspell.svg?label=npm%20(stable))](https://npmjs.org/package/@hyperspell/hyperspell) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@hyperspell/hyperspell)\n\nThis library provides convenient access to the Hyperspell REST API from server-side TypeScript or JavaScript.\n\n\n\nThe REST API documentation can be found on [docs.hyperspell.com](https://docs.hyperspell.com/). The full API of this library can be found in [api.md](api.md).\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Hyperspell MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=hyperspell-mcp&config=eyJuYW1lIjoiaHlwZXJzcGVsbC1tY3AiLCJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9oeXBlcnNwZWxsLnN0bG1jcC5jb20iLCJoZWFkZXJzIjp7IngtaHlwZXJzcGVsbC1hcGkta2V5IjoiTXkgQVBJIEtleSIsIlgtQXMtVXNlciI6Ik15IFVzZXIgSUQifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22hyperspell-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fhyperspell.stlmcp.com%22%2C%22headers%22%3A%7B%22x-hyperspell-api-key%22%3A%22My%20API%20Key%22%2C%22X-As-User%22%3A%22My%20User%20ID%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Installation\n\n```sh\nnpm install @hyperspell/hyperspell\n```\n\n\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n\n```js\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst memoryStatus = await client.memories.add({ text: '...' });\n\nconsole.log(memoryStatus.resource_id);\n```\n\n\n\n### Request & Response types\n\nThis library includes TypeScript definitions for all request params and response fields. You may import and use them like so:\n\n\n```ts\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted\n});\n\nconst params: Hyperspell.MemoryAddParams = { text: '...' };\nconst memoryStatus: Hyperspell.MemoryStatus = await client.memories.add(params);\n```\n\nDocumentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.\n\n## File uploads\n\nRequest parameters that correspond to file uploads can be passed in many different forms:\n- `File` (or an object with the same structure)\n- a `fetch` `Response` (or an object with the same structure)\n- an `fs.ReadStream`\n- the return value of our `toFile` helper\n\n```ts\nimport fs from 'fs';\nimport Hyperspell, { toFile } from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell();\n\n// If you have access to Node `fs` we recommend using `fs.createReadStream()`:\nawait client.memories.upload({ file: fs.createReadStream('/path/to/file') });\n\n// Or if you have the web `File` API you can pass a `File` instance:\nawait client.memories.upload({ file: new File(['my bytes'], 'file') });\n\n// You can also pass a `fetch` `Response`:\nawait client.memories.upload({ file: await fetch('https://somesite/file') });\n\n// Finally, if none of the above are convenient, you can use our `toFile` helper:\nawait client.memories.upload({ file: await toFile(Buffer.from('my bytes'), 'file') });\nawait client.memories.upload({ file: await toFile(new Uint8Array([0, 1, 2]), 'file') });\n```\n\n\n\n## Handling errors\n\nWhen the library is unable to connect to the API,\nor if the API returns a non-success status code (i.e., 4xx or 5xx response),\na subclass of `APIError` will be thrown:\n\n\n```ts\nconst memoryStatus = await client.memories.add({ text: '...' }).catch(async (err) => {\n if (err instanceof Hyperspell.APIError) {\n console.log(err.status); // 400\n console.log(err.name); // BadRequestError\n console.log(err.headers); // {server: 'nginx', ...}\n } else {\n throw err;\n }\n});\n```\n\nError codes are as follows:\n\n| Status Code | Error Type |\n| ----------- | -------------------------- |\n| 400 | `BadRequestError` |\n| 401 | `AuthenticationError` |\n| 403 | `PermissionDeniedError` |\n| 404 | `NotFoundError` |\n| 422 | `UnprocessableEntityError` |\n| 429 | `RateLimitError` |\n| >=500 | `InternalServerError` |\n| N/A | `APIConnectionError` |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,\n429 Rate Limit, and >=500 Internal errors will all be retried by default.\n\nYou can use the `maxRetries` option to configure or disable this:\n\n\n```js\n// Configure the default for all requests:\nconst client = new Hyperspell({\n maxRetries: 0, // default is 2\n});\n\n// Or, configure per-request:\nawait client.memories.add({ text: '...' }, {\n maxRetries: 5,\n});\n```\n\n### Timeouts\n\nRequests time out after 1 minute by default. You can configure this with a `timeout` option:\n\n\n```ts\n// Configure the default for all requests:\nconst client = new Hyperspell({\n timeout: 20 * 1000, // 20 seconds (default is 1 minute)\n});\n\n// Override per-request:\nawait client.memories.add({ text: '...' }, {\n timeout: 5 * 1000,\n});\n```\n\nOn timeout, an `APIConnectionTimeoutError` is thrown.\n\nNote that requests which time out will be [retried twice by default](#retries).\n\n## Auto-pagination\n\nList methods in the Hyperspell API are paginated.\nYou can use the `for await … of` syntax to iterate through items across all pages:\n\n```ts\nasync function fetchAllResources(params) {\n const allResources = [];\n // Automatically fetches more pages as needed.\n for await (const resource of client.memories.list()) {\n allResources.push(resource);\n }\n return allResources;\n}\n```\n\nAlternatively, you can request a single page at a time:\n\n```ts\nlet page = await client.memories.list();\nfor (const resource of page.items) {\n console.log(resource);\n}\n\n// Convenience methods are provided for manually paginating:\nwhile (page.hasNextPage()) {\n page = await page.getNextPage();\n // ...\n}\n```\n\n\n\n## Advanced Usage\n\n### Accessing raw Response data (e.g., headers)\n\nThe \"raw\" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.\nThis method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.\n\nYou can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.\nUnlike `.asResponse()` this method consumes the body, returning once it is parsed.\n\n\n```ts\nconst client = new Hyperspell();\n\nconst response = await client.memories.add({ text: '...' }).asResponse();\nconsole.log(response.headers.get('X-My-Header'));\nconsole.log(response.statusText); // access the underlying Response object\n\nconst { data: memoryStatus, response: raw } = await client.memories\n .add({ text: '...' })\n .withResponse();\nconsole.log(raw.headers.get('X-My-Header'));\nconsole.log(memoryStatus.resource_id);\n```\n\n### Logging\n\n> [!IMPORTANT]\n> All log messages are intended for debugging only. The format and content of log messages\n> may change between releases.\n\n#### Log levels\n\nThe log level can be configured in two ways:\n\n1. Via the `HYPERSPELL_LOG` environment variable\n2. Using the `logLevel` client option (overrides the environment variable if set)\n\n```ts\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n logLevel: 'debug', // Show all log messages\n});\n```\n\nAvailable log levels, from most to least verbose:\n\n- `'debug'` - Show debug messages, info, warnings, and errors\n- `'info'` - Show info messages, warnings, and errors\n- `'warn'` - Show warnings and errors (default)\n- `'error'` - Show only errors\n- `'off'` - Disable all logging\n\nAt the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.\nSome authentication-related headers are redacted, but sensitive data in request and response bodies\nmay still be visible.\n\n#### Custom logger\n\nBy default, this library logs to `globalThis.console`. You can also provide a custom logger.\nMost logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.\n\nWhen providing a custom logger, the `logLevel` option still controls which messages are emitted, messages\nbelow the configured level will not be sent to your logger.\n\n```ts\nimport Hyperspell from '@hyperspell/hyperspell';\nimport pino from 'pino';\n\nconst logger = pino();\n\nconst client = new Hyperspell({\n logger: logger.child({ name: 'Hyperspell' }),\n logLevel: 'debug', // Send all messages to pino, allowing it to filter\n});\n```\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API. If you need to access undocumented\nendpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.\nOptions on the client, such as retries, will be respected when making these requests.\n\n```ts\nawait client.post('/some/path', {\n body: { some_prop: 'foo' },\n query: { some_query_arg: 'bar' },\n});\n```\n\n#### Undocumented request params\n\nTo make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented\nparameter. This library doesn't validate at runtime that the request matches the type, so any extra values you\nsend will be sent as-is.\n\n```ts\nclient.memories.add({\n // ...\n // @ts-expect-error baz is not yet public\n baz: 'undocumented option',\n});\n```\n\nFor requests with the `GET` verb, any extra params will be in the query, all other requests will send the\nextra param in the body.\n\nIf you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request\noptions.\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you may access the response object with `// @ts-expect-error` on\nthe response object, or cast the response object to the requisite type. Like the request params, we do not\nvalidate or strip extra properties from the response from the API.\n\n### Customizing the fetch client\n\nBy default, this library expects a global `fetch` function is defined.\n\nIf you want to use a different `fetch` function, you can either polyfill the global:\n\n```ts\nimport fetch from 'my-fetch';\n\nglobalThis.fetch = fetch;\n```\n\nOr pass it to the client:\n\n```ts\nimport Hyperspell from '@hyperspell/hyperspell';\nimport fetch from 'my-fetch';\n\nconst client = new Hyperspell({ fetch });\n```\n\n### Fetch options\n\nIf you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)\n\n```ts\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n fetchOptions: {\n // `RequestInit` options\n },\n});\n```\n\n#### Configuring proxies\n\nTo modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy\noptions to requests:\n\n **Node** [[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]\n\n```ts\nimport Hyperspell from '@hyperspell/hyperspell';\nimport * as undici from 'undici';\n\nconst proxyAgent = new undici.ProxyAgent('http://localhost:8888');\nconst client = new Hyperspell({\n fetchOptions: {\n dispatcher: proxyAgent,\n },\n});\n```\n\n **Bun** [[docs](https://bun.sh/guides/http/proxy)]\n\n```ts\nimport Hyperspell from '@hyperspell/hyperspell';\n\nconst client = new Hyperspell({\n fetchOptions: {\n proxy: 'http://localhost:8888',\n },\n});\n```\n\n **Deno** [[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]\n\n```ts\nimport Hyperspell from 'npm:@hyperspell/hyperspell';\n\nconst httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });\nconst client = new Hyperspell({\n fetchOptions: {\n client: httpClient,\n },\n});\n```\n\n## Frequently Asked Questions\n\n## Semantic versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n3. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/hyperspell/node-sdk/issues) with questions, bugs, or suggestions.\n\n## Requirements\n\nTypeScript >= 4.9 is supported.\n\nThe following runtimes are supported:\n\n- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)\n- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.\n- Deno v1.28.0 or higher.\n- Bun 1.0 or later.\n- Cloudflare Workers.\n- Vercel Edge Runtime.\n- Jest 28 or greater with the `\"node\"` environment (`\"jsdom\"` is not supported at this time).\n- Nitro v2.6 or greater.\n\nNote that React Native is not supported at this time.\n\nIf you are interested in other runtime environments, please open or upvote an issue on GitHub.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n", }, { language: 'cli', diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts index 40d62504..12073c0a 100644 --- a/packages/mcp-server/src/server.ts +++ b/packages/mcp-server/src/server.ts @@ -7,8 +7,8 @@ import { ListToolsRequestSchema, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js'; -import { ClientOptions } from 'hyperspell'; -import Hyperspell from 'hyperspell'; +import { ClientOptions } from '@hyperspell/hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; import { codeTool } from './code-tool'; import docsSearchTool from './docs-search-tool'; import { setLocalSearch } from './docs-search-tool'; @@ -28,7 +28,7 @@ export const newMcpServer = async ({ }) => new McpServer( { - name: 'hyperspell_api', + name: 'hyperspell_hyperspell_api', version: '0.36.0', }, { diff --git a/packages/mcp-server/src/types.ts b/packages/mcp-server/src/types.ts index 4e969ce7..707ced3c 100644 --- a/packages/mcp-server/src/types.ts +++ b/packages/mcp-server/src/types.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; import { Tool } from '@modelcontextprotocol/sdk/types.js'; type TextContentBlock = { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c7d6aa4c..fe802264 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -83,6 +83,9 @@ importers: '@hono/node-server': specifier: ^1.19.10 version: 1.19.11(hono@4.12.5) + '@hyperspell/hyperspell': + specifier: workspace:* + version: link:../.. '@modelcontextprotocol/sdk': specifier: ^1.27.1 version: 1.27.1(zod@3.25.76) @@ -107,9 +110,6 @@ importers: hono: specifier: ^4.12.4 version: 4.12.5 - hyperspell: - specifier: workspace:* - version: link:../.. jq-web: specifier: https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz version: https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 581cb999..8d78a340 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -4,4 +4,4 @@ onlyBuiltDependencies: - '@swc/core' minimumReleaseAge: 1440 minimumReleaseAgeExclude: - - hyperspell + - '@hyperspell/hyperspell' diff --git a/scripts/build b/scripts/build index 21c9b517..19c0a615 100755 --- a/scripts/build +++ b/scripts/build @@ -8,7 +8,7 @@ node scripts/utils/check-version.cjs # Build into dist and will publish the package from there, # so that src/resources/foo.ts becomes /resources/foo.js -# This way importing from `"hyperspell/resources/foo"` works +# This way importing from `"@hyperspell/hyperspell/resources/foo"` works # even with `"moduleResolution": "node"` rm -rf dist; mkdir dist @@ -42,8 +42,8 @@ node scripts/utils/postprocess-files.cjs # make sure that nothing crashes when we require the output CJS or # import the output ESM -(cd dist && node -e 'require("hyperspell")') -(cd dist && node -e 'import("hyperspell")' --input-type=module) +(cd dist && node -e 'require("@hyperspell/hyperspell")') +(cd dist && node -e 'import("@hyperspell/hyperspell")' --input-type=module) if [ -e ./scripts/build-deno ] then diff --git a/tests/api-resources/actions.test.ts b/tests/api-resources/actions.test.ts index 10dec138..63c65d7c 100644 --- a/tests/api-resources/actions.test.ts +++ b/tests/api-resources/actions.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/auth.test.ts b/tests/api-resources/auth.test.ts index a69dbf80..0960b0ee 100644 --- a/tests/api-resources/auth.test.ts +++ b/tests/api-resources/auth.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/connections.test.ts b/tests/api-resources/connections.test.ts index c3fd176e..f945baa1 100644 --- a/tests/api-resources/connections.test.ts +++ b/tests/api-resources/connections.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/evaluate.test.ts b/tests/api-resources/evaluate.test.ts index 41801f48..514d031e 100644 --- a/tests/api-resources/evaluate.test.ts +++ b/tests/api-resources/evaluate.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/folders.test.ts b/tests/api-resources/folders.test.ts index 5a911179..8848eb81 100644 --- a/tests/api-resources/folders.test.ts +++ b/tests/api-resources/folders.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/integrations/google-calendar.test.ts b/tests/api-resources/integrations/google-calendar.test.ts index 289c7fd4..b9aa076e 100644 --- a/tests/api-resources/integrations/google-calendar.test.ts +++ b/tests/api-resources/integrations/google-calendar.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/integrations/integrations.test.ts b/tests/api-resources/integrations/integrations.test.ts index 6cf96361..e96c8086 100644 --- a/tests/api-resources/integrations/integrations.test.ts +++ b/tests/api-resources/integrations/integrations.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/integrations/slack.test.ts b/tests/api-resources/integrations/slack.test.ts index a6f6f4dc..7367e5fc 100644 --- a/tests/api-resources/integrations/slack.test.ts +++ b/tests/api-resources/integrations/slack.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/integrations/web-crawler.test.ts b/tests/api-resources/integrations/web-crawler.test.ts index fbaf54a4..ce1220db 100644 --- a/tests/api-resources/integrations/web-crawler.test.ts +++ b/tests/api-resources/integrations/web-crawler.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/memories.test.ts b/tests/api-resources/memories.test.ts index d13c738f..bbe4b656 100644 --- a/tests/api-resources/memories.test.ts +++ b/tests/api-resources/memories.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell, { toFile } from 'hyperspell'; +import Hyperspell, { toFile } from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/sessions.test.ts b/tests/api-resources/sessions.test.ts index 130629ea..6126dea6 100644 --- a/tests/api-resources/sessions.test.ts +++ b/tests/api-resources/sessions.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/api-resources/vaults.test.ts b/tests/api-resources/vaults.test.ts index bb105ccf..8d407d08 100644 --- a/tests/api-resources/vaults.test.ts +++ b/tests/api-resources/vaults.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import Hyperspell from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'My API Key', diff --git a/tests/base64.test.ts b/tests/base64.test.ts index 0ab7d6ab..b9eddb1f 100644 --- a/tests/base64.test.ts +++ b/tests/base64.test.ts @@ -1,4 +1,4 @@ -import { fromBase64, toBase64 } from 'hyperspell/internal/utils/base64'; +import { fromBase64, toBase64 } from '@hyperspell/hyperspell/internal/utils/base64'; describe.each(['Buffer', 'atob'])('with %s', (mode) => { let originalBuffer: BufferConstructor; diff --git a/tests/buildHeaders.test.ts b/tests/buildHeaders.test.ts index 18945ca3..973d3a40 100644 --- a/tests/buildHeaders.test.ts +++ b/tests/buildHeaders.test.ts @@ -1,5 +1,9 @@ import { inspect } from 'node:util'; -import { buildHeaders, type HeadersLike, type NullableHeaders } from 'hyperspell/internal/headers'; +import { + buildHeaders, + type HeadersLike, + type NullableHeaders, +} from '@hyperspell/hyperspell/internal/headers'; function inspectNullableHeaders(headers: NullableHeaders) { return `NullableHeaders {${[ diff --git a/tests/form.test.ts b/tests/form.test.ts index 7d9caaec..2e9f0eb8 100644 --- a/tests/form.test.ts +++ b/tests/form.test.ts @@ -1,5 +1,5 @@ -import { multipartFormRequestOptions, createForm } from 'hyperspell/internal/uploads'; -import { toFile } from 'hyperspell/core/uploads'; +import { multipartFormRequestOptions, createForm } from '@hyperspell/hyperspell/internal/uploads'; +import { toFile } from '@hyperspell/hyperspell/core/uploads'; describe('form data validation', () => { test('valid values do not error', async () => { diff --git a/tests/index.test.ts b/tests/index.test.ts index 2c9dae1d..0290ffe8 100644 --- a/tests/index.test.ts +++ b/tests/index.test.ts @@ -1,10 +1,10 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import { APIPromise } from 'hyperspell/core/api-promise'; +import { APIPromise } from '@hyperspell/hyperspell/core/api-promise'; import util from 'node:util'; -import Hyperspell from 'hyperspell'; -import { APIUserAbortError } from 'hyperspell'; +import Hyperspell from '@hyperspell/hyperspell'; +import { APIUserAbortError } from '@hyperspell/hyperspell'; const defaultFetch = fetch; describe('instantiate client', () => { diff --git a/tests/path.test.ts b/tests/path.test.ts index a9b1d83c..b6e2e602 100644 --- a/tests/path.test.ts +++ b/tests/path.test.ts @@ -1,4 +1,4 @@ -import { createPathTagFunction, encodeURIPath } from 'hyperspell/internal/utils/path'; +import { createPathTagFunction, encodeURIPath } from '@hyperspell/hyperspell/internal/utils/path'; import { inspect } from 'node:util'; import { runInNewContext } from 'node:vm'; diff --git a/tests/qs/stringify.test.ts b/tests/qs/stringify.test.ts index 4cbce067..47d83763 100644 --- a/tests/qs/stringify.test.ts +++ b/tests/qs/stringify.test.ts @@ -1,7 +1,7 @@ import iconv from 'iconv-lite'; -import { stringify } from 'hyperspell/internal/qs'; -import { encode } from 'hyperspell/internal/qs/utils'; -import { StringifyOptions } from 'hyperspell/internal/qs/types'; +import { stringify } from '@hyperspell/hyperspell/internal/qs'; +import { encode } from '@hyperspell/hyperspell/internal/qs/utils'; +import { StringifyOptions } from '@hyperspell/hyperspell/internal/qs/types'; import { empty_test_cases } from './empty-keys-cases'; import assert from 'assert'; diff --git a/tests/qs/utils.test.ts b/tests/qs/utils.test.ts index de03fa18..08f0e6da 100644 --- a/tests/qs/utils.test.ts +++ b/tests/qs/utils.test.ts @@ -1,4 +1,4 @@ -import { combine, merge, is_buffer, assign_single_source } from 'hyperspell/internal/qs/utils'; +import { combine, merge, is_buffer, assign_single_source } from '@hyperspell/hyperspell/internal/qs/utils'; describe('merge()', function () { // t.deepEqual(merge(null, true), [null, true], 'merges true into null'); diff --git a/tests/stringifyQuery.test.ts b/tests/stringifyQuery.test.ts index 47cf4589..ce88c6f0 100644 --- a/tests/stringifyQuery.test.ts +++ b/tests/stringifyQuery.test.ts @@ -1,6 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -import { stringifyQuery } from 'hyperspell/internal/utils/query'; +import { stringifyQuery } from '@hyperspell/hyperspell/internal/utils/query'; describe(stringifyQuery, () => { for (const [input, expected] of [ diff --git a/tests/uploads.test.ts b/tests/uploads.test.ts index a02ec83f..71815e2e 100644 --- a/tests/uploads.test.ts +++ b/tests/uploads.test.ts @@ -1,6 +1,6 @@ import fs from 'fs'; -import type { ResponseLike } from 'hyperspell/internal/to-file'; -import { toFile } from 'hyperspell/core/uploads'; +import type { ResponseLike } from '@hyperspell/hyperspell/internal/to-file'; +import { toFile } from '@hyperspell/hyperspell/core/uploads'; import { File } from 'node:buffer'; class MyClass { @@ -97,7 +97,7 @@ describe('missing File error message', () => { }); test('is thrown', async () => { - const uploads = await import('hyperspell/core/uploads'); + const uploads = await import('@hyperspell/hyperspell/core/uploads'); await expect( uploads.toFile(mockResponse({ url: 'https://example.com/my/audio.mp3' })), ).rejects.toMatchInlineSnapshot( diff --git a/tsconfig.build.json b/tsconfig.build.json index ed0ce278..6820ad17 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -5,8 +5,8 @@ "compilerOptions": { "rootDir": "./dist/src", "paths": { - "hyperspell/*": ["./dist/src/*"], - "hyperspell": ["./dist/src/index.ts"] + "@hyperspell/hyperspell/*": ["./dist/src/*"], + "@hyperspell/hyperspell": ["./dist/src/index.ts"] }, "noEmit": false, "declaration": true, diff --git a/tsconfig.json b/tsconfig.json index fb9bf45a..4dff196f 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -8,8 +8,8 @@ "moduleResolution": "node", "esModuleInterop": true, "paths": { - "hyperspell/*": ["./src/*"], - "hyperspell": ["./src/index.ts"] + "@hyperspell/hyperspell/*": ["./src/*"], + "@hyperspell/hyperspell": ["./src/index.ts"] }, "noEmit": true, From a040b66238a39e375d174d45eaa15ffcdd9029b0 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 19:27:11 +0000 Subject: [PATCH 3/3] release: 0.36.1 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 9 +++++++++ package.json | 2 +- packages/mcp-server/manifest.json | 2 +- packages/mcp-server/package.json | 2 +- packages/mcp-server/src/server.ts | 2 +- src/version.ts | 2 +- 7 files changed, 15 insertions(+), 6 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 93c546c8..ae5e906b 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.36.0" + ".": "0.36.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 33d1da7b..9affa3cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 0.36.1 (2026-04-22) + +Full Changelog: [v0.36.0...v0.36.1](https://github.com/hyperspell/node-sdk/compare/v0.36.0...v0.36.1) + +### Chores + +* update SDK settings ([597e2c0](https://github.com/hyperspell/node-sdk/commit/597e2c01ec271e6f7054a03b475968ce5e19af31)) +* update SDK settings ([b4e0424](https://github.com/hyperspell/node-sdk/commit/b4e04248e73f2f8f5db328c54b1e6708d5e95799)) + ## 0.36.0 (2026-04-22) Full Changelog: [v0.35.1...v0.36.0](https://github.com/hyperspell/node-sdk/compare/v0.35.1...v0.36.0) diff --git a/package.json b/package.json index 125d1286..0bc03235 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@hyperspell/hyperspell", - "version": "0.36.0", + "version": "0.36.1", "description": "The official TypeScript library for the Hyperspell API", "author": "Hyperspell ", "types": "dist/index.d.ts", diff --git a/packages/mcp-server/manifest.json b/packages/mcp-server/manifest.json index a33572ff..b133cb81 100644 --- a/packages/mcp-server/manifest.json +++ b/packages/mcp-server/manifest.json @@ -1,7 +1,7 @@ { "dxt_version": "0.2", "name": "hyperspell-mcp", - "version": "0.36.0", + "version": "0.36.1", "description": "The official MCP Server for the Hyperspell API", "author": { "name": "Hyperspell", diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json index 8fdd201a..03a80922 100644 --- a/packages/mcp-server/package.json +++ b/packages/mcp-server/package.json @@ -1,6 +1,6 @@ { "name": "hyperspell-mcp", - "version": "0.36.0", + "version": "0.36.1", "description": "The official MCP Server for the Hyperspell API", "author": "Hyperspell ", "types": "dist/index.d.ts", diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts index 12073c0a..93751808 100644 --- a/packages/mcp-server/src/server.ts +++ b/packages/mcp-server/src/server.ts @@ -29,7 +29,7 @@ export const newMcpServer = async ({ new McpServer( { name: 'hyperspell_hyperspell_api', - version: '0.36.0', + version: '0.36.1', }, { instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }), diff --git a/src/version.ts b/src/version.ts index 018dddd7..918ad99e 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.36.0'; // x-release-please-version +export const VERSION = '0.36.1'; // x-release-please-version