release: 0.8.0

.github/workflows/ci.yml

@@ -7,6 +7,10 @@ on:
       - 'integrated/**'
       - 'stl-preview-head/**'
       - 'stl-preview-base/**'
+  pull_request:
+    branches-ignore:
+      - 'stl-preview-head/**'
+      - 'stl-preview-base/**'
 
 jobs:
   lint:

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.7.0"
+  ".": "0.8.0"
 }

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.8.0 (2025-06-17)
+
+Full Changelog: [v0.7.0...v0.8.0](https://github.com/ContextualAI/contextual-client-node/compare/v0.7.0...v0.8.0)
+
+### Features
+
+* **client:** add support for endpoint-specific base URLs ([4375198](https://github.com/ContextualAI/contextual-client-node/commit/4375198ddd324eadac0053fbf0e9284f0686f6a5))
+
+
+### Bug Fixes
+
+* publish script — handle NPM errors correctly ([9855ea4](https://github.com/ContextualAI/contextual-client-node/commit/9855ea41c55355a17d1a6282bc8d158b72da2f63))
+
+
+### Chores
+
+* **ci:** enable for pull requests ([23d5fa7](https://github.com/ContextualAI/contextual-client-node/commit/23d5fa79636f991e3d4ff7a454ee973bb1fc2691))
+* **docs:** grammar improvements ([92210b2](https://github.com/ContextualAI/contextual-client-node/commit/92210b2f9cbfd930dfb7fcc8c6464a8d0c89bda7))
+* **docs:** use top-level-await in example snippets ([39783f4](https://github.com/ContextualAI/contextual-client-node/commit/39783f455c8d9d669d42a0671b239b51a196f743))
+* improve publish-npm script --latest tag logic ([bf8c320](https://github.com/ContextualAI/contextual-client-node/commit/bf8c320845e3781558b5c89c2d0dfda127138d13))
+* **internal:** make base APIResource abstract ([122895d](https://github.com/ContextualAI/contextual-client-node/commit/122895d96bcc6de97dc918dca7b62d8ababb0af5))
+
 ## 0.7.0 (2025-05-13)
 
 Full Changelog: [v0.6.0...v0.7.0](https://github.com/ContextualAI/contextual-client-node/compare/v0.6.0...v0.7.0)

README.md

@@ -24,13 +24,9 @@ const client = new ContextualAI({
   apiKey: process.env['CONTEXTUAL_API_KEY'], // This is the default and can be omitted
 });
 
-async function main() {
-  const createAgentOutput = await client.agents.create({ name: 'Example' });
+const createAgentOutput = await client.agents.create({ name: 'Example' });
 
-  console.log(createAgentOutput.id);
-}
-
-main();
+console.log(createAgentOutput.id);
 ```
 
 ### Request & Response types
@@ -45,12 +41,8 @@ const client = new ContextualAI({
   apiKey: process.env['CONTEXTUAL_API_KEY'], // This is the default and can be omitted
 });
 
-async function main() {
-  const params: ContextualAI.AgentCreateParams = { name: 'Example' };
-  const createAgentOutput: ContextualAI.CreateAgentOutput = await client.agents.create(params);
-}
-
-main();
+const params: ContextualAI.AgentCreateParams = { name: 'Example' };
+const createAgentOutput: ContextualAI.CreateAgentOutput = await client.agents.create(params);
 ```
 
 Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
@@ -103,19 +95,15 @@ a subclass of `APIError` will be thrown:
 
 <!-- prettier-ignore -->
 ```ts
-async function main() {
-  const createAgentOutput = await client.agents.create({ name: 'Example' }).catch(async (err) => {
-    if (err instanceof ContextualAI.APIError) {
-      console.log(err.status); // 400
-      console.log(err.name); // BadRequestError
-      console.log(err.headers); // {server: 'nginx', ...}
-    } else {
-      throw err;
-    }
-  });
-}
-
-main();
+const createAgentOutput = await client.agents.create({ name: 'Example' }).catch(async (err) => {
+  if (err instanceof ContextualAI.APIError) {
+    console.log(err.status); // 400
+    console.log(err.name); // BadRequestError
+    console.log(err.headers); // {server: 'nginx', ...}
+  } else {
+    throw err;
+  }
+});
 ```
 
 Error codes are as follows:

SECURITY.md

@@ -16,11 +16,11 @@ before making any information public.
 ## Reporting Non-SDK Related Security Issues
 
 If you encounter security issues that are not directly related to SDKs but pertain to the services
-or products provided by Contextual AI please follow the respective company's security reporting guidelines.
+or products provided by Contextual AI, please follow the respective company's security reporting guidelines.
 
 ### Contextual AI Terms and Policies
 
-Please contact [email protected] for any questions or concerns regarding security of our services.
+Please contact [email protected] for any questions or concerns regarding the security of our services.
 
 ---
 

bin/publish-npm

@@ -4,19 +4,55 @@ set -eux
 
 npm config set '//registry.npmjs.org/:_authToken' "$NPM_TOKEN"
 
-# Build the project
 yarn build
-
-# Navigate to the dist directory
 cd dist
 
-# Get the version from package.json
-VERSION="$(node -p "require('./package.json').version")"
+# Get package name and version from package.json
+PACKAGE_NAME="$(jq -r -e '.name' ./package.json)"
+VERSION="$(jq -r -e '.version' ./package.json)"
+
+# Get latest version from npm
+#
+# If the package doesn't exist, npm will return:
+# {
+#   "error": {
+#     "code": "E404",
+#     "summary": "Unpublished on 2025-06-05T09:54:53.528Z",
+#     "detail": "'the_package' is not in this registry..."
+#   }
+# }
+NPM_INFO="$(npm view "$PACKAGE_NAME" version --json 2>/dev/null || true)"
+
+# Check if we got an E404 error
+if echo "$NPM_INFO" | jq -e '.error.code == "E404"' > /dev/null 2>&1; then
+  # Package doesn't exist yet, no last version
+  LAST_VERSION=""
+elif echo "$NPM_INFO" | jq -e '.error' > /dev/null 2>&1; then
+  # Report other errors
+  echo "ERROR: npm returned unexpected data:"
+  echo "$NPM_INFO"
+  exit 1
+else
+  # Success - get the version
+  LAST_VERSION=$(echo "$NPM_INFO" | jq -r '.') # strip quotes
+fi
 
-# Extract the pre-release tag if it exists
+# Check if current version is pre-release (e.g. alpha / beta / rc)
+CURRENT_IS_PRERELEASE=false
 if [[ "$VERSION" =~ -([a-zA-Z]+) ]]; then
-  # Extract the part before any dot in the pre-release identifier
-  TAG="${BASH_REMATCH[1]}"
+  CURRENT_IS_PRERELEASE=true
+  CURRENT_TAG="${BASH_REMATCH[1]}"
+fi
+
+# Check if last version is a stable release
+LAST_IS_STABLE_RELEASE=true
+if [[ -z "$LAST_VERSION" || "$LAST_VERSION" =~ -([a-zA-Z]+) ]]; then
+  LAST_IS_STABLE_RELEASE=false
+fi
+
+# Use a corresponding alpha/beta tag if there already is a stable release and we're publishing a prerelease.
+if $CURRENT_IS_PRERELEASE && $LAST_IS_STABLE_RELEASE; then
+  TAG="$CURRENT_TAG"
 else
   TAG="latest"
 fi

package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextual-client",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The official TypeScript library for the Contextual AI API",
   "author": "Contextual AI <[email protected]>",
   "types": "dist/index.d.ts",

scripts/build

@@ -28,7 +28,7 @@ fi
 node scripts/utils/make-dist-package-json.cjs > dist/package.json
 
 # build to .js/.mjs/.d.ts files
-npm exec tsc-multi
+./node_modules/.bin/tsc-multi
 # copy over handwritten .js/.mjs/.d.ts files
 cp src/_shims/*.{d.ts,js,mjs,md} dist/_shims
 cp src/_shims/auto/*.{d.ts,js,mjs} dist/_shims/auto

src/core.ts

@@ -170,6 +170,7 @@ export class APIPromise<T> extends Promise<T> {
 
 export abstract class APIClient {
   baseURL: string;
+  #baseURLOverridden: boolean;
   maxRetries: number;
   timeout: number;
   httpAgent: Agent | undefined;
@@ -179,18 +180,21 @@ export abstract class APIClient {
 
   constructor({
     baseURL,
+    baseURLOverridden,
     maxRetries = 2,
     timeout = 60000, // 1 minute
     httpAgent,
     fetch: overriddenFetch,
   }: {
     baseURL: string;
+    baseURLOverridden: boolean;
     maxRetries?: number | undefined;
     timeout: number | undefined;
     httpAgent: Agent | undefined;
     fetch: Fetch | undefined;
   }) {
     this.baseURL = baseURL;
+    this.#baseURLOverridden = baseURLOverridden;
     this.maxRetries = validatePositiveInteger('maxRetries', maxRetries);
     this.timeout = validatePositiveInteger('timeout', timeout);
     this.httpAgent = httpAgent;
@@ -300,7 +304,7 @@ export abstract class APIClient {
     { retryCount = 0 }: { retryCount?: number } = {},
   ): { req: RequestInit; url: string; timeout: number } {
     const options = { ...inputOptions };
-    const { method, path, query, headers: headers = {} } = options;
+    const { method, path, query, defaultBaseURL, headers: headers = {} } = options;
 
     const body =
       ArrayBuffer.isView(options.body) || (options.__binaryRequest && typeof options.body === 'string') ?
@@ -310,7 +314,7 @@ export abstract class APIClient {
       : null;
     const contentLength = this.calculateContentLength(body);
 
-    const url = this.buildURL(path!, query);
+    const url = this.buildURL(path!, query, defaultBaseURL);
     if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
     options.timeout = options.timeout ?? this.timeout;
     const httpAgent = options.httpAgent ?? this.httpAgent ?? getDefaultAgent(url);
@@ -503,11 +507,12 @@ export abstract class APIClient {
     return new PagePromise<PageClass, Item>(this, request, Page);
   }
 
-  buildURL<Req>(path: string, query: Req | null | undefined): string {
+  buildURL<Req>(path: string, query: Req | null | undefined, defaultBaseURL?: string | undefined): string {
+    const baseURL = (!this.#baseURLOverridden && defaultBaseURL) || this.baseURL;
     const url =
       isAbsoluteURL(path) ?
         new URL(path)
-      : new URL(this.baseURL + (this.baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
+      : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
     if (!isEmptyObj(defaultQuery)) {
@@ -792,6 +797,7 @@ export type RequestOptions<
   query?: Req | undefined;
   body?: Req | null | undefined;
   headers?: Headers | undefined;
+  defaultBaseURL?: string | undefined;
 
   maxRetries?: number;
   stream?: boolean | undefined;
@@ -813,6 +819,7 @@ const requestOptionsKeys: KeysEnum<RequestOptions> = {
   query: true,
   body: true,
   headers: true,
+  defaultBaseURL: true,
 
   maxRetries: true,
   stream: true,

src/index.ts

@@ -178,6 +178,7 @@ export class ContextualAI extends Core.APIClient {
 
     super({
       baseURL: options.baseURL!,
+      baseURLOverridden: baseURL ? baseURL !== 'https://api.contextual.ai/v1' : false,
       timeout: options.timeout ?? 60000 /* 1 minute */,
       httpAgent: options.httpAgent,
       maxRetries: options.maxRetries,
@@ -197,6 +198,13 @@ export class ContextualAI extends Core.APIClient {
   generate: API.Generate = new API.Generate(this);
   parse: API.Parse = new API.Parse(this);
 
+  /**
+   * Check whether the base URL is set to its default.
+   */
+  #baseURLOverridden(): boolean {
+    return this.baseURL !== 'https://api.contextual.ai/v1';
+  }
+
   protected override defaultQuery(): Core.DefaultQuery | undefined {
     return this._options.defaultQuery;
   }

src/resource.ts

@@ -2,7 +2,7 @@
 
 import type { ContextualAI } from './index';
 
-export class APIResource {
+export abstract class APIResource {
   protected _client: ContextualAI;
 
   constructor(client: ContextualAI) {

src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.7.0'; // x-release-please-version
+export const VERSION = '0.8.0'; // x-release-please-version

tests/index.test.ts

@@ -188,6 +188,28 @@ describe('instantiate client', () => {
       const client = new ContextualAI({ apiKey: 'My API Key' });
       expect(client.baseURL).toEqual('https://api.contextual.ai/v1');
     });
+
+    test('in request options', () => {
+      const client = new ContextualAI({ apiKey: 'My API Key' });
+      expect(client.buildURL('/foo', null, 'http://localhost:5000/option')).toEqual(
+        'http://localhost:5000/option/foo',
+      );
+    });
+
+    test('in request options overridden by client options', () => {
+      const client = new ContextualAI({ apiKey: 'My API Key', baseURL: 'http://localhost:5000/client' });
+      expect(client.buildURL('/foo', null, 'http://localhost:5000/option')).toEqual(
+        'http://localhost:5000/client/foo',
+      );
+    });
+
+    test('in request options overridden by env variable', () => {
+      process.env['CONTEXTUAL_AI_BASE_URL'] = 'http://localhost:5000/env';
+      const client = new ContextualAI({ apiKey: 'My API Key' });
+      expect(client.buildURL('/foo', null, 'http://localhost:5000/option')).toEqual(
+        'http://localhost:5000/env/foo',
+      );
+    });
   });
 
   test('maxRetries option is correctly set', () => {