From 15f4b8769b385361a57d0a8fa11926a32fcd2486 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= <boschi1997@gmail.com>
Date: Tue, 3 Mar 2026 14:54:48 +0100
Subject: [PATCH] fix(ts-sdk): send null instead of undefined when
 includeEntities is false (#476)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ts-sdk): send null instead of undefined when includeEntities is false

When `includeEntities: false` was passed, the client serialized `entities`
as `undefined`, which is stripped from JSON. The API then applied its
default (`EntityIncludeOptions()` — enabled), silently ignoring the flag.

Fix: send `null` explicitly when `includeEntities === false` so the API
correctly interprets it as "disable entities".

chunks and source_facts are unaffected since their API defaults are null
(disabled), so omitting them from JSON produces the correct behaviour.

Also adds integration tests covering all three states of includeEntities.

* fix(ts-sdk): use toBeFalsy for null entity check in test
---
 hindsight-clients/typescript/src/index.ts     |  2 +-
 .../typescript/tests/main_operations.test.ts  | 42 +++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/hindsight-clients/typescript/src/index.ts b/hindsight-clients/typescript/src/index.ts
index 37624a4a..dcf52f56 100644
--- a/hindsight-clients/typescript/src/index.ts
+++ b/hindsight-clients/typescript/src/index.ts
@@ -286,7 +286,7 @@ export class HindsightClient {
                 trace: options?.trace,
                 query_timestamp: options?.queryTimestamp,
                 include: {
-                    entities: options?.includeEntities ? { max_tokens: options?.maxEntityTokens ?? 500 } : undefined,
+                    entities: options?.includeEntities === false ? null : options?.includeEntities ? { max_tokens: options?.maxEntityTokens ?? 500 } : undefined,
                     chunks: options?.includeChunks ? { max_tokens: options?.maxChunkTokens ?? 8192 } : undefined,
                     source_facts: options?.includeSourceFacts ? { max_tokens: options?.maxSourceFactsTokens ?? 4096 } : undefined,
                 },
diff --git a/hindsight-clients/typescript/tests/main_operations.test.ts b/hindsight-clients/typescript/tests/main_operations.test.ts
index d88ea51b..61d93a7b 100644
--- a/hindsight-clients/typescript/tests/main_operations.test.ts
+++ b/hindsight-clients/typescript/tests/main_operations.test.ts
@@ -413,6 +413,48 @@ describe('TestDeleteBank', () => {
     });
 });
 
+describe('TestRecallIncludeOptions', () => {
+    let bankId: string;
+
+    beforeAll(async () => {
+        bankId = randomBankId();
+        await client.retainBatch(bankId, [
+            { content: 'Alice works at Google as a software engineer' },
+            { content: 'Bob is a researcher at OpenAI' },
+        ]);
+    });
+
+    test('entities included by default', async () => {
+        const response = await client.recall(bankId, 'Where does Alice work?');
+
+        expect(response).not.toBeNull();
+        expect(response.results!.length).toBeGreaterThan(0);
+        // entities should be present when includeEntities is not specified (default: true)
+        expect(response.entities).toBeDefined();
+    });
+
+    test('entities excluded when includeEntities is false', async () => {
+        const response = await client.recall(bankId, 'Where does Alice work?', {
+            includeEntities: false,
+        });
+
+        expect(response).not.toBeNull();
+        expect(response.results!.length).toBeGreaterThan(0);
+        // entities should be absent when explicitly disabled
+        expect(response.entities).toBeFalsy();
+    });
+
+    test('entities included when includeEntities is true', async () => {
+        const response = await client.recall(bankId, 'Where does Alice work?', {
+            includeEntities: true,
+        });
+
+        expect(response).not.toBeNull();
+        expect(response.results!.length).toBeGreaterThan(0);
+        expect(response.entities).toBeDefined();
+    });
+});
+
 describe('TestMission', () => {
     test('set mission', async () => {
         const bankId = randomBankId();