refactor(types): replace JsonDict with type-fest JsonObject and JsonValue (#228)

* refactor(types): replace JsonDict with type-fest JsonObject and JsonValue

Remove the custom `JsonDict = Record<string, unknown>` type alias in
favour of type-fest's stricter `JsonObject` and `JsonValue` types.

Key changes to src/types.ts:
- Import and re-export `JsonObject` and `JsonValue` from type-fest
- Update `JSONSchema` interface to use `JsonValue` instead of `unknown`
  for properties like `enum`, `const`, `default`, and `examples`
- Add explicit index signature union type for JSONSchema extensibility

This provides stronger type safety by ensuring values are actually
JSON-serialisable rather than accepting arbitrary `unknown` values.

* refactor(core): update source files to use JsonObject type

Migrate all source files from the removed `JsonDict` type to the
type-fest `JsonObject` type. This commit updates method signatures
and internal type annotations across the codebase.

Files updated:
- src/tool.ts: Update execute method signatures and meta tool returns
- src/toolsets.ts: Update parameter and return types
- src/feedback.ts: Add explicit array types for results/errors,
  use JsonValue for parsed responses
- src/headers.ts: Update normaliseHeaders parameter type

Notable implementation changes:
- meta_search_tools now uses JSON.parse(JSON.stringify(...)) to ensure
  the return value is JSON-serialisable (removes undefined values from
  JSONSchema objects)
- Feedback tool now explicitly types its internal arrays to ensure
  type safety with the stricter JsonObject constraint

* refactor(requestBuilder): add stringifyValue helper for type-safe serialisation

Add a dedicated `stringifyValue()` function to safely convert JsonValue
types to strings for use in URLs, headers, and form data. This replaces
direct `String()` calls which could produce `[object Object]` for
complex values.

The helper function:
- Returns strings as-is
- Converts numbers and booleans via String()
- Returns empty string for null values
- JSON-stringifies arrays and objects

Also updates the dry run response to properly serialise headers and body
to JSON-compatible values using `satisfies JsonObject` for type checking.

* test: update tests for JsonObject type changes

Update test files to work with the stricter JsonObject type:

src/tool.test.ts:
- Add isMetaToolSearchResults type guard function
- Add getSearchResults helper to safely extract search results
- Replace direct type assertions with type-safe helper calls

src/requestBuilder.test.ts:
- Update dry run test expectation: body is now `null` instead of
  `undefined` when no body params exist (null is JSON-serialisable)
- Add explicit type casts for runtime edge case tests that
  intentionally pass invalid types (Date, RegExp, circular refs)

src/headers.test.ts:
- Remove test for undefined values (not valid in JsonObject)
- Keep null value test (null is a valid JSON value)

* docs(examples): update examples to use JsonObject type

Update example files to work with the new JsonObject type:

examples/meta-tools.ts:
- Import JsonObject from @stackone/ai
- Add explicit type annotation for intents array using
  `as const satisfies Array<{ intent: string; params: JsonObject }>`

examples/tanstack-ai-integration.test.ts:
- Simplify test structure and remove redundant assertions

Author: ryoppippi

examples/meta-tools.ts

@@ -8,7 +8,7 @@
 
 import process from 'node:process';
 import { openai } from '@ai-sdk/openai';
-import { StackOneToolSet, Tools } from '@stackone/ai';
+import { type JsonObject, StackOneToolSet, Tools } from '@stackone/ai';
 import { generateText, stepCountIs } from 'ai';
 
 const apiKey = process.env.STACKONE_API_KEY;
@@ -160,7 +160,7 @@ const directMetaToolUsage = async (): Promise<void> => {
 
 		try {
 			// Prepare parameters based on the tool's schema
-			let params: Record<string, unknown> = {};
+			let params = {} satisfies JsonObject;
 			if (firstTool.name === 'bamboohr_list_employees') {
 				params = { limit: 5 };
 			} else if (firstTool.name === 'bamboohr_create_employee') {
@@ -173,7 +173,7 @@ const directMetaToolUsage = async (): Promise<void> => {
 
 			const result = await executeTool.execute({
 				toolName: firstTool.name,
-				params: params,
+				params,
 			});
 
 			console.log('Execution result:', JSON.stringify(result, null, 2));
@@ -209,7 +209,7 @@ const dynamicToolRouter = async (): Promise<void> => {
 	const metaTools = await combinedTools.metaTools();
 
 	// Create a router function that finds and executes tools based on intent
-	const routeAndExecute = async (intent: string, params: Record<string, unknown> = {}) => {
+	const routeAndExecute = async (intent: string, params: JsonObject = {}) => {
 		const filterTool = metaTools.getTool('meta_search_tools');
 		const executeTool = metaTools.getTool('meta_execute_tool');
 		if (!filterTool || !executeTool) throw new Error('Meta tools not found');
@@ -221,18 +221,18 @@ const dynamicToolRouter = async (): Promise<void> => {
 			minScore: 0.5,
 		});
 
-		const tools = searchResult.tools as Array<{ name: string; score: number }>;
-		if (tools.length === 0) {
+		const tools = searchResult.tools;
+		if (!Array.isArray(tools) || tools.length === 0) {
 			return { error: 'No relevant tools found for the given intent' };
 		}
 
-		const selectedTool = tools[0];
+		const selectedTool = tools[0] as { name: string; score: number };
 		console.log(`Routing to: ${selectedTool.name} (score: ${selectedTool.score.toFixed(2)})`);
 
 		// Execute the selected tool
 		return await executeTool.execute({
 			toolName: selectedTool.name,
-			params: params,
+			params,
 		});
 	};
 
@@ -244,7 +244,7 @@ const dynamicToolRouter = async (): Promise<void> => {
 			params: { name: 'Jane Smith', email: 'jane@example.com' },
 		},
 		{ intent: 'Find recruitment candidates', params: { status: 'active' } },
-	];
+	] as const satisfies { intent: string; params: JsonObject }[];
 
 	for (const { intent, params } of intents) {
 		console.log(`\nIntent: "${intent}"`);

examples/tanstack-ai-integration.test.ts

@@ -33,24 +33,19 @@ describe('tanstack-ai-integration example e2e', () => {
 
 		// Get a specific tool
 		const employeeTool = tools.getTool('bamboohr_get_employee');
-		expect(employeeTool).toBeDefined();
+		assert(employeeTool, 'Expected bamboohr_get_employee tool to exist');
 
 		// Create TanStack AI compatible tool wrapper
 		// Use toJsonSchema() to get the parameter schema in JSON Schema format
 		const getEmployeeTool = {
-			name: employeeTool!.name,
-			description: employeeTool!.description,
-			inputSchema: employeeTool!.toJsonSchema(),
-			execute: async (args: Record<string, unknown>) => {
-				return employeeTool!.execute(args);
-			},
+			name: employeeTool.name,
+			description: employeeTool.description,
+			inputSchema: employeeTool.toJsonSchema(),
+			execute: employeeTool.execute.bind(employeeTool),
 		};
 
 		expect(getEmployeeTool.name).toBe('bamboohr_get_employee');
-		expect(getEmployeeTool.description).toContain('employee');
-		expect(getEmployeeTool.inputSchema).toBeDefined();
 		expect(getEmployeeTool.inputSchema.type).toBe('object');
-		expect(typeof getEmployeeTool.execute).toBe('function');
 	});
 
 	it('should execute tool directly', async () => {
@@ -68,9 +63,7 @@ describe('tanstack-ai-integration example e2e', () => {
 			name: employeeTool.name,
 			description: employeeTool.description,
 			inputSchema: employeeTool.toJsonSchema(),
-			execute: async (args: Record<string, unknown>) => {
-				return employeeTool.execute(args);
-			},
+			execute: employeeTool.execute.bind(employeeTool),
 		};
 
 		// Execute the tool directly to verify it works

src/feedback.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { DEFAULT_BASE_URL } from './consts';
 import { BaseTool } from './tool';
-import type { ExecuteConfig, ExecuteOptions, JsonDict, ToolParameters } from './types';
+import type { ExecuteConfig, ExecuteOptions, JsonObject, JsonValue, ToolParameters } from './types';
 import { StackOneError } from './utils/errors';
 
 interface FeedbackToolOptions {
@@ -107,9 +107,9 @@ export function createFeedbackTool(
 
 	tool.execute = async function (
 		this: BaseTool,
-		inputParams?: JsonDict | string,
+		inputParams?: JsonObject | string,
 		executeOptions?: ExecuteOptions,
-	): Promise<JsonDict> {
+	): Promise<JsonObject> {
 		try {
 			const rawParams =
 				typeof inputParams === 'string' ? JSON.parse(inputParams) : inputParams || {};
@@ -137,12 +137,12 @@ export function createFeedbackTool(
 				return {
 					multiple_requests: dryRunResults,
 					total_accounts: parsedParams.account_id.length,
-				} satisfies JsonDict;
+				} satisfies JsonObject;
 			}
 
 			// Send feedback to each account individually
-			const results = [];
-			const errors = [];
+			const results: Array<{ account_id: string; status: number; response: JsonValue }> = [];
+			const errors: Array<{ account_id: string; status?: number; error: string }> = [];
 
 			for (const accountId of parsedParams.account_id) {
 				try {
@@ -159,9 +159,9 @@ export function createFeedbackTool(
 					});
 
 					const text = await response.text();
-					let parsed: unknown;
+					let parsed: JsonValue;
 					try {
-						parsed = text ? JSON.parse(text) : {};
+						parsed = text ? (JSON.parse(text) satisfies JsonValue) : {};
 					} catch {
 						parsed = { raw: text };
 					}
@@ -191,7 +191,7 @@ export function createFeedbackTool(
 			}
 
 			// Return summary of all submissions in Python SDK format
-			const response: JsonDict = {
+			const response = {
 				message: `Feedback sent to ${parsedParams.account_id.length} account(s)`,
 				total_accounts: parsedParams.account_id.length,
 				successful: results.length,
@@ -208,7 +208,7 @@ export function createFeedbackTool(
 						error: e.error,
 					})),
 				],
-			};
+			} satisfies JsonObject;
 
 			// If all submissions failed, throw an error
 			if (errors.length > 0 && results.length === 0) {

src/headers.test.ts

@@ -1,4 +1,3 @@
-import { describe, expect, it } from 'vitest';
 import { normaliseHeaders } from './headers';
 
 describe('normaliseHeaders', () => {
@@ -43,12 +42,6 @@ describe('normaliseHeaders', () => {
 		});
 	});
 
-	it('skips undefined values', () => {
-		expect(normaliseHeaders({ foo: 'bar', baz: undefined })).toEqual({
-			foo: 'bar',
-		});
-	});
-
 	it('skips null values', () => {
 		expect(normaliseHeaders({ foo: 'bar', baz: null })).toEqual({
 			foo: 'bar',
@@ -64,7 +57,6 @@ describe('normaliseHeaders', () => {
 				object: { nested: 'value' },
 				array: [1, 2, 3],
 				nullValue: null,
-				undefinedValue: undefined,
 			}),
 		).toEqual({
 			string: 'text',

src/headers.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod/mini';
-import type { JsonDict } from './types';
+import type { JsonObject } from './types';
 
 /**
  * Known StackOne API header keys that are forwarded as HTTP headers
@@ -18,13 +18,13 @@ export const stackOneHeadersSchema = z.record(z.string(), z.string()).brand<'Sta
 export type StackOneHeaders = z.infer<typeof stackOneHeadersSchema>;
 
 /**
- * Normalises header values from JsonDict to StackOneHeaders (branded type)
+ * Normalises header values from JsonObject to StackOneHeaders (branded type)
  * Converts numbers and booleans to strings, and serialises objects to JSON
  *
- * @param headers - Headers object with unknown value types
+ * @param headers - Headers object with JSON value types
  * @returns Normalised headers with string values only (branded type)
  */
-export function normaliseHeaders(headers: JsonDict | undefined): StackOneHeaders {
+export function normaliseHeaders(headers: JsonObject | undefined): StackOneHeaders {
 	if (!headers) return stackOneHeadersSchema.parse({});
 	const result: Record<string, string> = {};
 	for (const [key, value] of Object.entries(headers)) {

src/index.ts

@@ -21,7 +21,8 @@ export type {
 	AISDKToolResult,
 	ExecuteConfig,
 	ExecuteOptions,
-	JsonDict,
+	JsonObject,
+	JsonValue,
 	ParameterLocation,
 	ToolDefinition,
 } from './types';