@usecortex_ai/node 0.3.0 → 0.3.2

package/README.md

@@ -2,27 +2,140 @@
 
 The official TypeScript SDK for the Cortex AI platform. Build powerful, context-aware AI applications in your Node.js or TypeScript projects.
 
-* **Homepage:** [usecortex.ai](https://www.usecortex.ai/ "null")
-* **Documentation:** [docs.usecortex.ai](https://docs.usecortex.ai/ "null")
+**Cortex** is your plug-and-play memory infrastructure. It powers intelligent, context-aware retrieval for any AI app or agent. Whether you’re building a customer support bot, research copilot, or internal knowledge assistant - Cortex handles all!
 
-## Getting Started
+[Learn more about the SDK from our docs](https://docs.usecortex.ai/)
 
-To use the SDK, you'll need an API key from your Cortex AI dashboard.
+## Core features
 
-### Initialize the Client
+* **Dynamic retrieval and querying** that always retrieve the most relevant context
+* **Built-in long-term memory** that evolves with every user interaction
+* **Personalization hooks** for user preferences, intent, and history
+* **Developer-first SDK** with the most flexible APIs and fine-grained controls
 
-Initialize the client with your API key. It's recommended to use an environment variable for security.
+## Getting started
 
+### Installation
+
+```
+npm i @usecortex_ai/node
+# or
+yarn add @usecortex_ai/node
+# or
+pnpm add @usecortex_ai/node
+```
+
+### Client setup
+
+```ts
+import { CortexAIClient } from "@usecortex_ai/node";
+
+const client = new CortexAIClient({
+  token: process.env.CORTEX_API_KEY,
+});
+```
+
+### Create a Tenant
+
+You can consider a `tenant` as a single database that can have internal isolated collections called `sub-tenants`. [Know more about the concept of tenant here](https://docs.usecortex.ai/essentials/multi-tenant)
+
+```ts
+async function createTenant() {
+  const tenantCreationResponse = await client.user.createTenant({
+    tenant_id: "my-company"
+  });
+  return tenantCreationResponse;
+}
+```
+
+### Index Your Data
+
+When you index your data, you make it ready for retrieval from Cortex using natural language.
+
+```ts
+// Upload text content
+async function uploadText() {
+  const res = await client.upload.uploadText({
+    tenant_id: "my-company",
+    sub_tenant_id: "engineering",
+    body: {
+      content: "Our API rate limits are 1000 requests per minute for premium accounts.",
+      file_id: "api-docs-rate-limits",
+      tenant_metadata: { sub_tenant_id: "engineering" }
+    }
+  });
+  return res;
+}
+
+// Upload a document file
+async function uploadFile() {
+  const uploadResult = await client.upload.uploadDocument({
+    file: fs.readFileSync("company-handbook.pdf"),
+    tenant_id: "my-company",
+    sub_tenant_id: "hr",
+    file_id: "doc_q1_summary"
+  });
+  return uploadResult;
+}
 ```
-import { CortexAI } from "@usecortex/ai";
 
-const client = new CortexAI({
-  // Defaults to process.env.CORTEX_API_KEY
-  apiKey: "YOUR_API_KEY",
+> **For a more detailed explanation** of document upload, including supported file formats, processing pipeline, metadata handling, and advanced configuration options, refer to the [Upload Document endpoint documentation](https://docs.usecortex.ai/api-reference/endpoint/upload-document).
+
+### Search and retrieval
+
+```ts
+// Semantic search with retrieval
+const results = await client.search.retrieve({
+  query: "What are the API rate limits?",
+  tenant_id: "my-company",
+  sub_tenant_id: "engineering",
+  max_chunks: 10
+});
+
+// List all sources
+const allSources = await client.sources.getAll({
+    tenant_id: "my-company",
+    sub_tenant_id: "engineering"
 });
 
+// Get specific sources by ID
+const specificSources = await client.sources.getByIds({
+  tenant_id: "my-company",
+  sub_tenant_id: "engineering",
+  source_ids: ["api-docs-rate-limits", "company-handbook"]
+});
 ```
 
+> **For a more detailed explanation** of search and retrieval, including query parameters, scoring mechanisms, result structure, and advanced search features, refer to the [Search endpoint documentation](https://docs.usecortex.ai/api-reference/endpoint/search).
+
+## SDK Method Structure & Type Safety
+
+Our SDKs follow a predictable pattern that mirrors the API structure while providing full type safety.
+
+> **Method Mapping** : `client.<group>.<functionName>` mirrors `api.usecortex.ai/<group>/<function_name>`
+>
+> For example: `client.upload.uploadText()` corresponds to `POST /upload/upload_text`
+
+The SDKs provide exact type parity with the API specification:
+
+- **Request Parameters** : Every field documented in the API reference (required, optional, types, validation rules) is reflected in the SDK method signatures
+- **Response Objects** : Return types match the exact JSON schema documented for each endpoint
+- **Error Types** : Exception structures mirror the error response formats from the API
+- **Nested Objects** : Complex nested parameters and responses maintain their full structure and typing
+
+> This means you can rely on your IDE’s autocomplete and type checking. If a parameter is optional in the API docs, it’s optional in the SDK. If a response contains a specific field, your IDE will know about it. Our SDKs are built in such a way that your IDE will automatically provide **autocompletion, type-checking, inline documentation with examples, and compile time validation** for each and every method.
+>
+> Just hit **Cmd+Space/Ctrl+Space!**
+
+## Links
+
+- **Homepage:** [usecortex.ai](https://www.usecortex.ai/)
+- **Documentation:** [docs.usecortex.ai](https://docs.usecortex.ai/)
+
+## Our docs
+
+Please refer to our [API reference](https://docs.usecortex.ai/api-reference/introduction) for detailed explanations of every API endpoint, parameter options, and advanced use cases.
+
 ## Support
 
-If you have any questions or need help, please reach out to our support team at [founders@usecortex.ai](mailto:founders@usecortex.ai "null").
+If you have any questions or need help, please reach out to our support team at [founders@usecortex.ai](mailto:founders@usecortex.ai).

package/dist/api/resources/sources/client/Client.d.ts

@@ -29,6 +29,32 @@ export declare namespace Sources {
 export declare class Sources {
     protected readonly _options: Sources.Options;
     constructor(_options?: Sources.Options);
+    /**
+     * Retrieve all sources for a specific tenant.
+     *
+     * Use this endpoint to fetch a complete list of all sources associated with your tenant. This includes documents, files, and other content you've uploaded for processing.
+     *
+     * You can optionally specify a sub-tenant to narrow down the results to sources within that specific sub-tenant scope.
+     *
+     * @param {CortexAI.SourcesGetAllRequest} request
+     * @param {Sources.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CortexAI.BadRequestError}
+     * @throws {@link CortexAI.UnauthorizedError}
+     * @throws {@link CortexAI.ForbiddenError}
+     * @throws {@link CortexAI.NotFoundError}
+     * @throws {@link CortexAI.UnprocessableEntityError}
+     * @throws {@link CortexAI.InternalServerError}
+     * @throws {@link CortexAI.ServiceUnavailableError}
+     *
+     * @example
+     *     await client.sources.getAll({
+     *         tenant_id: "tenant_1234",
+     *         sub_tenant_id: "sub_tenant_4567"
+     *     })
+     */
+    getAll(request: CortexAI.SourcesGetAllRequest, requestOptions?: Sources.RequestOptions): core.HttpResponsePromise<CortexAI.ListSourcesResponse>;
+    private __getAll;
     /**
      * Retrieve specific sources by their IDs.
      *
@@ -48,12 +74,12 @@ export declare class Sources {
      * @throws {@link CortexAI.ServiceUnavailableError}
      *
      * @example
-     *     await client.sources.getAll({
+     *     await client.sources.getByIds({
      *         tenant_id: "tenant_1234",
      *         source_ids: ["CortexDoc1234", "CortexDoc4567"]
      *     })
      */
-    getAll(request: CortexAI.SourceBodyParams, requestOptions?: Sources.RequestOptions): core.HttpResponsePromise<CortexAI.ListSourcesResponse>;
-    private __getAll;
+    getByIds(request: CortexAI.SourceBodyParams, requestOptions?: Sources.RequestOptions): core.HttpResponsePromise<CortexAI.ListSourcesResponse>;
+    private __getByIds;
     protected _getAuthorizationHeader(): Promise<string | undefined>;
 }

package/dist/api/resources/sources/client/Client.js

@@ -36,6 +36,94 @@ class Sources {
     constructor(_options = {}) {
         this._options = _options;
     }
+    /**
+     * Retrieve all sources for a specific tenant.
+     *
+     * Use this endpoint to fetch a complete list of all sources associated with your tenant. This includes documents, files, and other content you've uploaded for processing.
+     *
+     * You can optionally specify a sub-tenant to narrow down the results to sources within that specific sub-tenant scope.
+     *
+     * @param {CortexAI.SourcesGetAllRequest} request
+     * @param {Sources.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CortexAI.BadRequestError}
+     * @throws {@link CortexAI.UnauthorizedError}
+     * @throws {@link CortexAI.ForbiddenError}
+     * @throws {@link CortexAI.NotFoundError}
+     * @throws {@link CortexAI.UnprocessableEntityError}
+     * @throws {@link CortexAI.InternalServerError}
+     * @throws {@link CortexAI.ServiceUnavailableError}
+     *
+     * @example
+     *     await client.sources.getAll({
+     *         tenant_id: "tenant_1234",
+     *         sub_tenant_id: "sub_tenant_4567"
+     *     })
+     */
+    getAll(request, requestOptions) {
+        return core.HttpResponsePromise.fromPromise(this.__getAll(request, requestOptions));
+    }
+    async __getAll(request, requestOptions) {
+        var _a, _b, _c;
+        const { tenant_id: tenantId, sub_tenant_id: subTenantId } = request;
+        const _queryParams = {};
+        _queryParams["tenant_id"] = tenantId;
+        if (subTenantId != null) {
+            _queryParams["sub_tenant_id"] = subTenantId;
+        }
+        let _headers = (0, headers_js_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, (0, headers_js_1.mergeOnlyDefinedHeaders)({ Authorization: await this._getAuthorizationHeader() }), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
+        const _response = await core.fetcher({
+            url: core.url.join((_c = (_b = (await core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : (await core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.CortexAIEnvironment.CortexProd, "list/sources"),
+            method: "GET",
+            headers: _headers,
+            queryParameters: Object.assign(Object.assign({}, _queryParams), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams),
+            timeoutMs: (requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
+            maxRetries: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries,
+            abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
+        });
+        if (_response.ok) {
+            return { data: _response.body, rawResponse: _response.rawResponse };
+        }
+        if (_response.error.reason === "status-code") {
+            switch (_response.error.statusCode) {
+                case 400:
+                    throw new CortexAI.BadRequestError(_response.error.body, _response.rawResponse);
+                case 401:
+                    throw new CortexAI.UnauthorizedError(_response.error.body, _response.rawResponse);
+                case 403:
+                    throw new CortexAI.ForbiddenError(_response.error.body, _response.rawResponse);
+                case 404:
+                    throw new CortexAI.NotFoundError(_response.error.body, _response.rawResponse);
+                case 422:
+                    throw new CortexAI.UnprocessableEntityError(_response.error.body, _response.rawResponse);
+                case 500:
+                    throw new CortexAI.InternalServerError(_response.error.body, _response.rawResponse);
+                case 503:
+                    throw new CortexAI.ServiceUnavailableError(_response.error.body, _response.rawResponse);
+                default:
+                    throw new errors.CortexAIError({
+                        statusCode: _response.error.statusCode,
+                        body: _response.error.body,
+                        rawResponse: _response.rawResponse,
+                    });
+            }
+        }
+        switch (_response.error.reason) {
+            case "non-json":
+                throw new errors.CortexAIError({
+                    statusCode: _response.error.statusCode,
+                    body: _response.error.rawBody,
+                    rawResponse: _response.rawResponse,
+                });
+            case "timeout":
+                throw new errors.CortexAITimeoutError("Timeout exceeded when calling GET /list/sources.");
+            case "unknown":
+                throw new errors.CortexAIError({
+                    message: _response.error.errorMessage,
+                    rawResponse: _response.rawResponse,
+                });
+        }
+    }
     /**
      * Retrieve specific sources by their IDs.
      *
@@ -55,15 +143,15 @@ class Sources {
      * @throws {@link CortexAI.ServiceUnavailableError}
      *
      * @example
-     *     await client.sources.getAll({
+     *     await client.sources.getByIds({
      *         tenant_id: "tenant_1234",
      *         source_ids: ["CortexDoc1234", "CortexDoc4567"]
      *     })
      */
-    getAll(request, requestOptions) {
-        return core.HttpResponsePromise.fromPromise(this.__getAll(request, requestOptions));
+    getByIds(request, requestOptions) {
+        return core.HttpResponsePromise.fromPromise(this.__getByIds(request, requestOptions));
     }
-    async __getAll(request, requestOptions) {
+    async __getByIds(request, requestOptions) {
         var _a, _b, _c;
         let _headers = (0, headers_js_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, (0, headers_js_1.mergeOnlyDefinedHeaders)({ Authorization: await this._getAuthorizationHeader() }), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
         const _response = await core.fetcher({

package/dist/api/resources/sources/client/requests/SourcesGetAllRequest.d.ts

@@ -4,12 +4,13 @@
 /**
  * @example
  *     {
- *         tenant_id: "tenant_id"
+ *         tenant_id: "tenant_1234",
+ *         sub_tenant_id: "sub_tenant_4567"
  *     }
  */
 export interface SourcesGetAllRequest {
     /** Unique identifier for the tenant/organization */
     tenant_id: string;
-    /** Optional sub-tenant identifier for organizing data within a tenant. If not provided, defaults to tenant_id */
+    /** Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used. */
     sub_tenant_id?: string;
 }

package/dist/api/resources/sources/client/requests/index.d.ts

@@ -1 +1,2 @@
+export { type SourcesGetAllRequest } from "./SourcesGetAllRequest.js";
 export { type SourceBodyParams } from "./SourceBodyParams.js";

package/package.json

@@ -1,19 +1,21 @@
 {
     "name": "@usecortex_ai/node",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "description": "The official TypeScript SDK for the Cortex AI platform.",
     "author": "Nishkarsh Shrivastava <nishkarsh@usecortex.ai>",
     "license": "SEE LICENSE IN LICENSE",
-    "private": false,
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/usefindr/cortex-ai-ts.git"
-    },
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "files": [
         "dist"
     ],
+    "keywords": [
+        "cortex",
+        "cortex-ai",
+        "cortex-ai-sdk",
+        "cortex-ai-typescript-sdk",
+        "rag", "gen-ai", "memory", "ai"
+    ],
     "scripts": {
         "build": "tsc",
         "prepublishOnly": "npm run build"

package/dist/api/resources/sources/client/requests/SourcesGetSubTenantIdsRequest.d.ts

@@ -1,12 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-/**
- * @example
- *     {
- *         tenant_id: "tenant_id"
- *     }
- */
-export interface SourcesGetSubTenantIdsRequest {
-    tenant_id: string;
-}

package/dist/api/resources/sources/client/requests/SourcesGetSubTenantIdsRequest.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/resources/upload/client/requests/BodyUpdateMarkdownUploadUpdateMarkdownPatch.d.ts

@@ -1,21 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-import * as CortexAI from "../../../../index.js";
-/**
- * @example
- *     {
- *         source_id: "source_id",
- *         tenant_id: "tenant_id",
- *         request: {
- *             content: "content"
- *         }
- *     }
- */
-export interface BodyUpdateMarkdownUploadUpdateMarkdownPatch {
-    source_id: string;
-    tenant_id: string;
-    sub_tenant_id?: string;
-    request: CortexAI.MarkdownUploadRequest;
-    relations?: CortexAI.Relations;
-}

package/dist/api/resources/upload/client/requests/BodyUpdateMarkdownUploadUpdateMarkdownPatch.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/resources/upload/client/requests/BodyUpdateMarkdownUploadUpdateTextPatch.d.ts

@@ -1,21 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-import * as CortexAI from "../../../../index.js";
-/**
- * @example
- *     {
- *         source_id: "source_id",
- *         tenant_id: "tenant_id",
- *         request: {
- *             content: "content"
- *         }
- *     }
- */
-export interface BodyUpdateMarkdownUploadUpdateTextPatch {
-    source_id: string;
-    tenant_id: string;
-    sub_tenant_id?: string;
-    request: CortexAI.MarkdownUploadRequest;
-    relations?: CortexAI.Relations;
-}

package/dist/api/resources/upload/client/requests/BodyUpdateMarkdownUploadUpdateTextPatch.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/resources/upload/client/requests/BodyUploadMarkdownUploadUploadMarkdownPost.d.ts

@@ -1,19 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-import * as CortexAI from "../../../../index.js";
-/**
- * @example
- *     {
- *         tenant_id: "tenant_id",
- *         request: {
- *             content: "content"
- *         }
- *     }
- */
-export interface BodyUploadMarkdownUploadUploadMarkdownPost {
-    tenant_id: string;
-    sub_tenant_id?: string;
-    request: CortexAI.MarkdownUploadRequest;
-    relations?: CortexAI.Relations;
-}

package/dist/api/resources/upload/client/requests/BodyUploadMarkdownUploadUploadMarkdownPost.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/resources/upload/client/requests/BodyUploadMarkdownUploadUploadTextPost.d.ts

@@ -1,19 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-import * as CortexAI from "../../../../index.js";
-/**
- * @example
- *     {
- *         tenant_id: "tenant_id",
- *         request: {
- *             content: "content"
- *         }
- *     }
- */
-export interface BodyUploadMarkdownUploadUploadTextPost {
-    tenant_id: string;
-    sub_tenant_id?: string;
-    request: CortexAI.MarkdownUploadRequest;
-    relations?: CortexAI.Relations;
-}

package/dist/api/resources/upload/client/requests/BodyUploadMarkdownUploadUploadTextPost.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/resources/userMemory/client/requests/UserMemoryAddUserMemoryRequest.d.ts

@@ -1,16 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-/**
- * @example
- *     {
- *         tenant_id: "tenant_id",
- *         user_memory: "user_memory",
- *         sub_tenant_id: "sub_tenant_id"
- *     }
- */
-export interface UserMemoryAddUserMemoryRequest {
-    tenant_id: string;
-    user_memory: string;
-    sub_tenant_id: string;
-}

package/dist/api/resources/userMemory/client/requests/UserMemoryAddUserMemoryRequest.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/resources/userMemory/client/requests/UserMemoryGenerateUserMemoryRequest.d.ts

@@ -1,18 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-/**
- * @example
- *     {
- *         tenant_id: "tenant_id",
- *         user_query: "user_query",
- *         user_name: "user_name",
- *         sub_tenant_id: "sub_tenant_id"
- *     }
- */
-export interface UserMemoryGenerateUserMemoryRequest {
-    tenant_id: string;
-    user_query: string;
-    user_name: string;
-    sub_tenant_id: string;
-}

package/dist/api/resources/userMemory/client/requests/UserMemoryGenerateUserMemoryRequest.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/resources/userMemory/client/requests/UserMemoryRetrieveUserMemoryRequest.d.ts

@@ -1,17 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-/**
- * @example
- *     {
- *         tenant_id: "tenant_id",
- *         query: "query",
- *         sub_tenant_id: "sub_tenant_id"
- *     }
- */
-export interface UserMemoryRetrieveUserMemoryRequest {
-    tenant_id: string;
-    query: string;
-    sub_tenant_id: string;
-    max_count?: number;
-}

package/dist/api/resources/userMemory/client/requests/UserMemoryRetrieveUserMemoryRequest.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/types/SourceContent.d.ts

@@ -1,11 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-export interface SourceContent {
-    text?: string;
-    html_base64?: string;
-    csv_base64?: string;
-    markdown?: string;
-    files?: Record<string, unknown>[];
-    layout?: Record<string, unknown>[];
-}

package/dist/api/types/SourceContent.js

@@ -1,5 +0,0 @@
-"use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-Object.defineProperty(exports, "__esModule", { value: true });