[Feat] Update Typescript SDK & Documentation (#877)

This pull request updates the TypeScript SDK to version 0.6.1, introducing new features such as tool usage for LLMs and image generation configurations, and improving documentation generation. It also includes several important fixes, such as correctly serializing and URI-encoding array query parameters across multiple API clients, which enhances correctness and security. The Zod schemas have been significantly updated to reflect the new features and improve validation.

Author: kamil-hassan201

clients/typescript/__tests__/gentable.test.ts

@@ -58,9 +58,8 @@ describe("APIClient Gentable", () => {
 
             // Store all embedding models
             const allEmbeddingModels = models.data.filter((model) => model.capabilities.includes("embed"));
-            embeddingModels = allEmbeddingModels.length > 0
-                ? allEmbeddingModels.map((model) => model.id)
-                : ["ellm/sentence-transformers/all-MiniLM-L6-v2"];
+            embeddingModels =
+                allEmbeddingModels.length > 0 ? allEmbeddingModels.map((model) => model.id) : ["ellm/sentence-transformers/all-MiniLM-L6-v2"];
 
             // Set the first one as default
             embeddingModel = embeddingModels[0]!;
@@ -466,7 +465,7 @@ describe("APIClient Gentable", () => {
         }
     });
 
-    it("add row to action table with reindex", async () => {
+    it("add row to action table - no stream", async () => {
         for await (const { id: table_id } of _getTable("action")) {
             const response = await client.table.addRow({
                 table_type: "action",
@@ -487,59 +486,7 @@ describe("APIClient Gentable", () => {
         }
     });
 
-    it("add row to action table without reindex", async () => {
-        for await (const { id: table_id } of _getTable("action")) {
-            const response = await client.table.addRow({
-                table_type: "action",
-                data: [
-                    {
-                        question: "What is penguin?"
-                    },
-                    {
-                        question: "What is help?"
-                    }
-                ],
-                table_id: table_id,
-                concurrent: true
-            });
-
-            const parsedData = MultiRowCompletionResponseSchema.parse(response);
-            expect(parsedData).toEqual(response);
-        }
-    });
-
-    it("add row to action table - stream with reindex", async () => {
-        for await (const { id: table_id } of _getTable("action")) {
-            const response = await client.table.addRowStream({
-                table_type: "action",
-                data: [
-                    {
-                        question: "What is penguin?"
-                    },
-                    {
-                        question: "What is help?"
-                    }
-                ],
-                table_id: table_id,
-                concurrent: true
-            });
-
-            expect(response).toBeInstanceOf(ReadableStream);
-            const reader = response.getReader();
-            let chunk_count: number = 0;
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done) {
-                    break;
-                }
-                // console.log(value) ;
-                chunk_count += 1;
-            }
-            expect(chunk_count).toBeGreaterThan(2);
-        }
-    });
-
-    it("add row to action table - stream without reindex", async () => {
+    it("add row to action table - stream", async () => {
         for await (const { id: table_id } of _getTable("action")) {
             const response = await client.table.addRowStream({
                 table_type: "action",
@@ -1053,7 +1000,6 @@ describe("APIClient Gentable", () => {
                 column_ids: table.cols.length && table.cols[3]?.id ? [table.cols[3].id] : undefined
             });
 
-
             const parsedData = GetConversationThreadResponseSchema.parse(response);
             expect(parsedData).toEqual(response);
         }
@@ -1147,7 +1093,7 @@ describe("APIClient Gentable", () => {
                     }
                 }
             });
-            
+
             const parsedData = TableMetaResponseSchema.parse(response);
             expect(response).toEqual(parsedData);
         }
@@ -1438,7 +1384,6 @@ describe("APIClient Gentable", () => {
                 table_id: table_id
             });
 
-
             expect(responseAddRow.rows.length).toBe(responseListRows.items.length);
 
             const exportTableDataResponse = await client.table.exportTableData({

clients/typescript/__tests__/prices.test.ts

@@ -73,6 +73,12 @@ describe("APIClient Prices", () => {
                     included: { unit_cost: 0, up_to: 0.75 },
                     tiers: [],
                     unit: "GiB"
+                },
+                image_tokens: {
+                    name: "Image tokens",
+                    included: { unit_cost: 0, up_to: 0.75 },
+                    tiers: [],
+                    unit: "Million Tokens"
                 }
             }
         });
@@ -138,6 +144,12 @@ describe("APIClient Prices", () => {
                         included: { unit_cost: 0, up_to: 0.75 },
                         tiers: [],
                         unit: "GiB"
+                    },
+                    image_tokens: {
+                        name: "Image tokens",
+                        included: { unit_cost: 0, up_to: 0.75 },
+                        tiers: [],
+                        unit: "Million Tokens"
                     }
                 }
             });
@@ -164,7 +176,6 @@ describe("APIClient Prices", () => {
             if (response.id !== undefined) {
                 await client.prices.deletePricePlan(response.id);
             }
-
         });
 
         it("list price plans - without limit and offset", async () => {
@@ -283,6 +294,12 @@ describe("APIClient Prices", () => {
                         included: { unit_cost: 0, up_to: 0.75 },
                         tiers: [],
                         unit: "GiB"
+                    },
+                    image_tokens: {
+                        name: "Image tokens",
+                        included: { unit_cost: 0, up_to: 0.75 },
+                        tiers: [],
+                        unit: "Million Tokens"
                     }
                 }
             });

clients/typescript/__tests__/tasks.test.ts

@@ -1,7 +1,8 @@
-import JamAI, { PROGRESS_STATES } from "@/index";
+import JamAI from "@/index";
 import { afterAll, beforeAll, describe, expect, it, jest } from "@jest/globals";
 import dotenv from "dotenv";
 import { cleanupTestEnvironment, setupTestEnvironment, TestContext } from "./testUtils";
+import { PROGRESS_STATES } from "@/resources/tasks/types";
 
 dotenv.config({
     path: "__tests__/.env"
@@ -19,8 +20,6 @@ describe("APIClient Tasks", () => {
     beforeAll(async () => {
         testContext = await setupTestEnvironment();
         client = testContext.client;
-
-      
     });
 
     afterAll(async function () {
@@ -90,8 +89,6 @@ describe("APIClient Tasks", () => {
         expect(response).toBeNull();
     });
 
-
-
     it("poll progress with different initial wait times", async () => {
         const testKey = "test-initial-wait-key";
 

clients/typescript/__tests__/testUtils.ts

@@ -23,10 +23,7 @@ export interface TestContext {
  * Also cleans up existing tables for gentable tests
  * Optionally creates model configs and deployments
  */
-export async function setupTestEnvironment(options?: {
-    cleanupTables?: boolean;
-    createModels?: boolean;
-}): Promise<TestContext> {
+export async function setupTestEnvironment(options?: { cleanupTables?: boolean; createModels?: boolean }): Promise<TestContext> {
     // Default cleanupTables to true if not provided
     const { cleanupTables = true, createModels = false } = options ?? {};
     const myuuid = uuidv4();
@@ -50,9 +47,8 @@ export async function setupTestEnvironment(options?: {
 
         // Check for existing user with id="0"
         const users = await setupClient.users.listUsers();
-        const existingUser = users.items.find(u => u.id === "0");
-        userId = "0"
-        
+        const existingUser = users.items.find((u) => u.id === "0");
+        userId = "0";
 
         if (existingUser) {
             shouldDeleteUser = false;
@@ -70,7 +66,7 @@ export async function setupTestEnvironment(options?: {
 
         // Check for existing organization with id="0"
         const orgs = await setupClient.organizations.listOrganizations();
-        const existingOrg = orgs.items.find(o => o.id === "0");
+        const existingOrg = orgs.items.find((o) => o.id === "0");
 
         if (existingOrg) {
             organizationId = existingOrg.id;
@@ -151,10 +147,10 @@ export async function setupTestEnvironment(options?: {
     let modelConfigs: TestContext["modelConfigs"] | undefined;
     if (createModels) {
         const completionModelId = `openai/gpt-4o-mini-test-${uuidv4().substring(0, 8)}`;
-        const completionRoutingId = 'gpt-4o-mini'
-        const embeddingDimention = 1536
+        const completionRoutingId = "gpt-4o-mini";
+        const embeddingDimention = 1536;
         const embeddingModelId = `openai/text-embedding-test-${uuidv4().substring(0, 8)}`;
-        const embeddingRoutingId = "text-embedding-3-small"
+        const embeddingRoutingId = "text-embedding-3-small";
 
         // Create completion model config (similar to GPT_4O_MINI_CONFIG)
         await client.models.createModelConfig({
@@ -224,15 +220,7 @@ export async function setupTestEnvironment(options?: {
  * Only deletes resources that were manually created (based on shouldDelete flags)
  */
 export async function cleanupTestEnvironment(context: TestContext): Promise<void> {
-    const {
-        projectId,
-        organizationId,
-        userId,
-        shouldDeleteProject,
-        shouldDeleteOrganization,
-        shouldDeleteUser,
-        modelConfigs
-    } = context;
+    const { projectId, organizationId, userId, shouldDeleteProject, shouldDeleteOrganization, shouldDeleteUser, modelConfigs } = context;
 
     // Create cleanup client
     const cleanupClient = new JamAI({

clients/typescript/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jamaibase",
-    "version": "0.5.0",
+    "version": "0.6.1",
     "description": "JamAIBase Client SDK (JS/TS). JamAI Base: Let Your Database Orchestrate LLMs and RAG",
     "main": "dist/index.cjs",
     "module": "dist/index.mjs",
@@ -13,7 +13,7 @@
         "build": "/bin/bash build",
         "openapi-to-zod": "openapi-zod-client openapi.json -o zodschema/zodmodels.ts",
         "doc-ts-moduler": "typedoc  --includeVersion --tsconfig tsconfig.build.json --includes ./dist/*.d.ts --includes ./dist/**/*.d.ts --includes ./dist/resources/**/*.d.ts --out docs-autogen-ts",
-        "doc-ts": "typedoc --readme ./README.md --includeVersion --tsconfig tsconfig.build.json --entryPointStrategy expand --entryPoints ./dist/index.d.ts --entryPoints ./dist/resources --out docs-autogen-ts --categorizeByGroup --sort alphabetical && cp JamAI_Base_Cover.png docs-autogen-ts/"
+        "doc-ts": "typedoc --readme ./README.md --includeVersion --tsconfig tsconfig.build.json --entryPointStrategy expand --entryPoints ./dist/index.d.ts --entryPoints ./dist/resources --exclude '**/shared/**' --out docs-autogen-ts --categorizeByGroup --sort alphabetical && cp JamAI_Base_Cover.png docs-autogen-ts/"
     },
     "repository": {
         "type": "git",

clients/typescript/src/helpers/utils.ts

@@ -46,3 +46,26 @@ export function createPaginationSchema<T>(itemSchema: z.ZodType<T>) {
         })
     );
 }
+
+/**
+ * Serializes query parameters for axios requests, properly handling arrays and skipping null/undefined values.
+ * This prevents null/undefined values from being sent as literal strings (e.g., "columns=null").
+ *
+ * @param params - The query parameters object to serialize
+ * @returns URL-encoded query string
+ *
+ * @example
+ * serializeParams({ foo: 'bar', list: [1, 2], skip: null })
+ * // Returns: "foo=bar&list=1&list=2"
+ */
+export function serializeParams(params: Record<string, any>): string {
+    return Object.entries(params)
+        .flatMap(([key, value]) =>
+            Array.isArray(value)
+                ? value.map((val) => `${encodeURIComponent(key)}=${encodeURIComponent(val)}`)
+                : value !== undefined && value !== null
+                ? `${encodeURIComponent(key)}=${encodeURIComponent(value)}`
+                : []
+        )
+        .join("&");
+}

clients/typescript/src/index.ts

@@ -61,12 +61,12 @@ class JamAI extends Base {
         this.file = new Files(sharedConfig);
     }
 
-    public override setApiKey(token: string){
-        super.setApiKey(token)
+    public override setApiKey(token: string) {
+        super.setApiKey(token);
     }
 
-    public override setProjId(projectId: string){
-        super.setProjId(projectId)
+    public override setProjId(projectId: string) {
+        super.setProjId(projectId);
     }
 
     /**
@@ -94,27 +94,23 @@ class JamAI extends Base {
      * @property {Number} [socketActiveTTL=null] - Sets the time to live for active sockets, even if in use. If not set, sockets are released only when free. Default is null.
      */
     public override setHttpsagentConfig(payload: Agent.HttpsOptions) {
-        super.setHttpsagentConfig(payload)
+        super.setHttpsagentConfig(payload);
     }
 
     public override setAuthHeader(header: string) {
-        super.setAuthHeader(header)
+        super.setAuthHeader(header);
     }
 
     public override async health(): Promise<AxiosResponse> {
-        return await super.health()
+        return await super.health();
     }
 }
 
-// Re-export useful constants and types
-export { PROGRESS_STATES } from "@/resources/tasks/types";
-export type { ProgressState, ProgressResponse, PollProgressParams } from "@/resources/tasks/types";
-
 // // Re-export types from internal modules for easier access
 // export * from "@/resources/base";
 // export * from "@/resources/files";
 // export * from "@/resources/gen_tables/tables";
 // export * from "@/resources/llm/chat";
 // export * from "@/resources/templates";
 
-export default JamAI; 
+export default JamAI;

clients/typescript/src/resources/base.ts

@@ -36,7 +36,7 @@ export abstract class Base {
     protected maxRetries: number;
     protected httpClient: AxiosInstance;
     protected timeout: number | undefined;
-    private sdkVersion = "0.3";
+    private sdkVersion = "0.6.1";
 
     /**
      * Creates an instance of APIClient.