release: 0.9.0

.devcontainer/devcontainer.json

@@ -9,9 +9,7 @@
   "postCreateCommand": "yarn install",
   "customizations": {
     "vscode": {
-      "extensions": [
-        "esbenp.prettier-vscode"
-      ]
+      "extensions": ["esbenp.prettier-vscode"]
     }
   }
 }

.gitignore

@@ -7,4 +7,5 @@ dist
 dist-deno
 /*.tgz
 .idea/
+.eslintcache
 

.release-please-manifest.json

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

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 34
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-db7245c74772a8cd47c02886619fed0568fbb58b1fa8aba0dc77524b924a4fb6.yml
-openapi_spec_hash: ca3de8d7b14b78683e39464fe7d4b1e1
-config_hash: 410f8a2f86f605885911277be47c3c78
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-c8152db455001be3f09a3bc60d63711699d2c2a4ea5f7bbc1d71726efda0fd9b.yml
+openapi_spec_hash: 97719df292ca220de5d35d36f9756b95
+config_hash: ae81af9b7eb88a788a80bcf3480e0b6b

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.9.0 (2025-10-28)
+
+Full Changelog: [v0.8.0...v0.9.0](https://github.com/ContextualAI/contextual-client-node/compare/v0.8.0...v0.9.0)
+
+### Features
+
+* **api:** update via SDK Studio ([1763386](https://github.com/ContextualAI/contextual-client-node/commit/1763386e73b63686841d8ffec13cd2bc16889259))
+
+
+### Bug Fixes
+
+* coerce nullable values to undefined ([0e6f279](https://github.com/ContextualAI/contextual-client-node/commit/0e6f279eac597fca69a580ab8af0a12c015ab644))
+
+
+### Performance Improvements
+
+* faster formatting ([20716e5](https://github.com/ContextualAI/contextual-client-node/commit/20716e5908af1f9cc6e3eb60e306ededc8f3d720))
+
+
+### Chores
+
+* do not install brew dependencies in ./scripts/bootstrap by default ([2ecd296](https://github.com/ContextualAI/contextual-client-node/commit/2ecd29636b8f21c6138729ef7338f50084410b0e))
+* **internal:** codegen related update ([d6debdf](https://github.com/ContextualAI/contextual-client-node/commit/d6debdfcc774fb8092bd2cabdc036359872d8643))
+* **internal:** codegen related update ([3bc0d6f](https://github.com/ContextualAI/contextual-client-node/commit/3bc0d6fec90af69104f10af5def4be3deeb69507))
+* **internal:** fix incremental formatting in some cases ([2d2c927](https://github.com/ContextualAI/contextual-client-node/commit/2d2c9279de2f4cbfd1edba630aeb30b7395c3481))
+* **internal:** ignore .eslintcache ([1b5df0d](https://github.com/ContextualAI/contextual-client-node/commit/1b5df0db14ec9b5bd5429e4025480d8ba430eda0))
+* **internal:** improve examples ([c251c21](https://github.com/ContextualAI/contextual-client-node/commit/c251c212ee8bff087c7b98f3f5750bf3036ce0cf))
+* **internal:** remove .eslintcache ([352a8df](https://github.com/ContextualAI/contextual-client-node/commit/352a8dfca95b76937b6eeb4e800226afcd7d3337))
+* **internal:** remove deprecated `compilerOptions.baseUrl` from tsconfig.json ([80dc3e8](https://github.com/ContextualAI/contextual-client-node/commit/80dc3e82bb18210f781ebf38500a2310ce10e0e5))
+* **internal:** use npm pack for build uploads ([a1e64cd](https://github.com/ContextualAI/contextual-client-node/commit/a1e64cdb60b8c92692b52914609745edd85a6c43))
+
 ## 0.8.0 (2025-08-26)
 
 Full Changelog: [v0.7.0...v0.8.0](https://github.com/ContextualAI/contextual-client-node/compare/v0.7.0...v0.8.0)

api.md

@@ -38,7 +38,7 @@ Methods:
 - <code title="get /datastores/{datastore_id}/documents/{document_id}/parse">client.datastores.documents.<a href="./src/resources/datastores/documents.ts">getParseResult</a>(datastoreId, documentId, { ...params }) -> DocumentGetParseResultResponse</code>
 - <code title="post /datastores/{datastore_id}/documents">client.datastores.documents.<a href="./src/resources/datastores/documents.ts">ingest</a>(datastoreId, { ...params }) -> IngestionResponse</code>
 - <code title="get /datastores/{datastore_id}/documents/{document_id}/metadata">client.datastores.documents.<a href="./src/resources/datastores/documents.ts">metadata</a>(datastoreId, documentId) -> DocumentMetadata</code>
-- <code title="post /datastores/{datastore_id}/documents/{document_id}/metadata">client.datastores.documents.<a href="./src/resources/datastores/documents.ts">setMetadata</a>(datastoreId, documentId, { ...params }) -> DocumentMetadata</code>
+- <code title="put /datastores/{datastore_id}/documents/{document_id}/metadata">client.datastores.documents.<a href="./src/resources/datastores/documents.ts">setMetadata</a>(datastoreId, documentId, { ...params }) -> DocumentMetadata</code>
 
 # Agents
 
@@ -80,7 +80,7 @@ Types:
 Methods:
 
 - <code title="post /agents/{agent_id}/query">client.agents.query.<a href="./src/resources/agents/query.ts">create</a>(agentId, { ...params }) -> QueryResponse</code>
-- <code title="post /agents/{agent_id}/feedback">client.agents.query.<a href="./src/resources/agents/query.ts">feedback</a>(agentId, { ...params }) -> unknown</code>
+- <code title="post /agents/{agent_id}/feedback">client.agents.query.<a href="./src/resources/agents/query.ts">feedback</a>(agentId, { ...params }) -> QueryFeedbackResponse</code>
 - <code title="get /agents/{agent_id}/metrics">client.agents.query.<a href="./src/resources/agents/query.ts">metrics</a>(agentId, { ...params }) -> QueryMetricsResponse</code>
 - <code title="get /agents/{agent_id}/query/{message_id}/retrieval/info">client.agents.query.<a href="./src/resources/agents/query.ts">retrievalInfo</a>(agentId, messageId, { ...params }) -> RetrievalInfoResponse</code>
 

package.json

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

release-please-config.json

@@ -60,8 +60,5 @@
     }
   ],
   "release-type": "node",
-  "extra-files": [
-    "src/version.ts",
-    "README.md"
-  ]
+  "extra-files": ["src/version.ts", "README.md"]
 }

scripts/bootstrap

@@ -4,10 +4,18 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ]; then
+if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ] && [ -t 0 ]; then
   brew bundle check >/dev/null 2>&1 || {
-    echo "==> Installing Homebrew dependencies…"
-    brew bundle
+    echo -n "==> Install Homebrew dependencies? (y/N): "
+    read -r response
+    case "$response" in
+      [yY][eE][sS]|[yY])
+        brew bundle
+        ;;
+      *)
+        ;;
+    esac
+    echo
   }
 fi
 

scripts/fast-format

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+echo "Script started with $# arguments"
+echo "Arguments: $*"
+echo "Script location: $(dirname "$0")"
+
+cd "$(dirname "$0")/.."
+echo "Changed to directory: $(pwd)"
+
+if [ $# -eq 0 ]; then
+    echo "Usage: $0 <file-with-paths> [additional-formatter-args...]"
+    echo "The file should contain one file path per line"
+    exit 1
+fi
+
+FILE_LIST="$1"
+
+echo "Looking for file: $FILE_LIST"
+
+if [ ! -f "$FILE_LIST" ]; then
+    echo "Error: File '$FILE_LIST' not found"
+    exit 1
+fi
+
+echo "==> Running eslint --fix"
+ESLINT_FILES="$(grep '\.ts$' "$FILE_LIST" || true)"
+if ! [ -z "$ESLINT_FILES" ]; then
+   echo "$ESLINT_FILES" | ESLINT_USE_FLAT_CONFIG="false" xargs ./node_modules/.bin/eslint --cache --fix
+fi
+
+echo "==> Running prettier --write"
+# format things eslint didn't
+PRETTIER_FILES="$(grep '\.\(js\|json\)$' "$FILE_LIST" || true)"
+if ! [ -z "$PRETTIER_FILES" ]; then
+   echo "$PRETTIER_FILES" | xargs ./node_modules/.bin/prettier \
+      --write --cache --cache-strategy metadata --no-error-on-unmatched-pattern \
+      '!**/dist' '!**/*.ts' '!**/*.mts' '!**/*.cts' '!**/*.js' '!**/*.mjs' '!**/*.cjs'
+fi

scripts/utils/upload-artifact.sh

@@ -12,9 +12,11 @@ if [[ "$SIGNED_URL" == "null" ]]; then
   exit 1
 fi
 
-UPLOAD_RESPONSE=$(tar -cz "${BUILD_PATH:-dist}" | curl -v -X PUT \
+TARBALL=$(cd dist && npm pack --silent)
+
+UPLOAD_RESPONSE=$(curl -v -X PUT \
   -H "Content-Type: application/gzip" \
-  --data-binary @- "$SIGNED_URL" 2>&1)
+  --data-binary "@dist/$TARBALL" "$SIGNED_URL" 2>&1)
 
 if echo "$UPLOAD_RESPONSE" | grep -q "HTTP/[0-9.]* 200"; then
   echo -e "\033[32mUploaded build to Stainless storage.\033[0m"

src/core.ts

@@ -1088,21 +1088,21 @@ export const coerceBoolean = (value: unknown): boolean => {
 };
 
 export const maybeCoerceInteger = (value: unknown): number | undefined => {
-  if (value === undefined) {
+  if (value == null) {
     return undefined;
   }
   return coerceInteger(value);
 };
 
 export const maybeCoerceFloat = (value: unknown): number | undefined => {
-  if (value === undefined) {
+  if (value == null) {
     return undefined;
   }
   return coerceFloat(value);
 };
 
 export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
-  if (value === undefined) {
+  if (value == null) {
     return undefined;
   }
   return coerceBoolean(value);

src/resources/agents/agents.ts

@@ -124,6 +124,11 @@ export interface Agent {
  * Response to configs for different components
  */
 export interface AgentConfigs {
+  /**
+   * Parameters that affect the agent's ACL workflow
+   */
+  acl_config?: AgentConfigs.ACLConfig;
+
   /**
    * Parameters that affect filtering and reranking of retrieved knowledge
    */
@@ -148,9 +153,29 @@ export interface AgentConfigs {
    * Parameters that affect how the agent retrieves from datastore(s)
    */
   retrieval_config?: RetrievalConfig;
+
+  /**
+   * Parameters that affect the agent's translation workflow
+   */
+  translation_config?: AgentConfigs.TranslationConfig;
 }
 
 export namespace AgentConfigs {
+  /**
+   * Parameters that affect the agent's ACL workflow
+   */
+  export interface ACLConfig {
+    /**
+     * Whether to enable ACL.
+     */
+    acl_active?: boolean;
+
+    /**
+     * The YAML file to use for ACL.
+     */
+    acl_yaml?: string;
+  }
+
   /**
    * Parameters that affect the agent's query reformulation
    */
@@ -175,6 +200,21 @@ export namespace AgentConfigs {
      */
     query_expansion_prompt?: string;
   }
+
+  /**
+   * Parameters that affect the agent's translation workflow
+   */
+  export interface TranslationConfig {
+    /**
+     * The confidence threshold for translation.
+     */
+    translate_confidence?: number;
+
+    /**
+     * Whether to enable translation for the agent's responses.
+     */
+    translate_needed?: boolean;
+  }
 }
 
 /**
@@ -217,13 +257,6 @@ export interface AgentMetadata {
    */
   filter_prompt?: string;
 
-  /**
-   * The model ID to use for generation. Tuned models can only be used for the agents
-   * on which they were tuned. If no model is specified, the default model is used.
-   * Set to `default` to switch from a tuned model to the default model.
-   */
-  llm_model_id?: string;
-
   /**
    * Instructions on how the agent should handle multi-turn conversations.
    */
@@ -476,7 +509,7 @@ export namespace AgentMetadataResponse {
     /**
      * The following advanced parameters are experimental and subject to change.
      */
-    agent_configs?: unknown;
+    agent_configs?: { [key: string]: unknown };
 
     /**
      * Total API request counts for the agent.
@@ -565,6 +598,11 @@ export interface AgentCreateParams {
    * do not guarantee that the system will follow these instructions exactly.
    */
   system_prompt?: string;
+
+  /**
+   * The template defining the base configuration for the agent.
+   */
+  template_name?: string;
 }
 
 export interface AgentUpdateParams {
@@ -578,23 +616,26 @@ export interface AgentUpdateParams {
    */
   datastore_ids?: Array<string>;
 
+  /**
+   * Description of the agent
+   */
+  description?: string;
+
   /**
    * The prompt to an LLM which determines whether retrieved chunks are relevant to a
    * given query and filters out irrelevant chunks.
    */
   filter_prompt?: string;
 
   /**
-   * The model ID to use for generation. Tuned models can only be used for the agents
-   * on which they were tuned. If no model is specified, the default model is used.
-   * Set to `default` to switch from a tuned model to the default model.
+   * Instructions on how the agent should handle multi-turn conversations.
    */
-  llm_model_id?: string;
+  multiturn_system_prompt?: string;
 
   /**
-   * Instructions on how the agent should handle multi-turn conversations.
+   * Name of the agent
    */
-  multiturn_system_prompt?: string;
+  name?: string;
 
   /**
    * Instructions on how the agent should respond when there are no relevant