@credal/sdk 0.1.16 → 1.0.0

package/README.md

@@ -1,157 +1,308 @@
-<div align="center">  
-  <img src="./credal-dark-logo.svg" width="400" />
-</div>
+# Credal TypeScript Library
 
-# Credal Typescript Library
-
-[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](/?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fcredal-ai%2Fcredal-typescript-sdk)
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2FCredal-ai%2Fcredal-typescript-sdk-v1)
 [![npm shield](https://img.shields.io/npm/v/@credal/sdk)](https://www.npmjs.com/package/@credal/sdk)
 
-The Credal TypeScript library provides convenient access to the Credal API from TypeScript/JavaScript.
-
-# Documentation
+The Credal TypeScript library provides convenient access to the Credal APIs from TypeScript.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Reference](#reference)
+- [Usage](#usage)
+- [Request and Response Types](#request-and-response-types)
+- [Exception Handling](#exception-handling)
+- [Advanced](#advanced)
+  - [Subpackage Exports](#subpackage-exports)
+  - [Additional Headers](#additional-headers)
+  - [Additional Query String Parameters](#additional-query-string-parameters)
+  - [Retries](#retries)
+  - [Timeouts](#timeouts)
+  - [Aborting Requests](#aborting-requests)
+  - [Access Raw Response Data](#access-raw-response-data)
+  - [Logging](#logging)
+  - [Custom Fetch](#custom-fetch)
+  - [Custom Fetcher](#custom-fetcher)
+  - [Runtime Compatibility](#runtime-compatibility)
+- [Contributing](#contributing)
+
+## Installation
 
-Docs for the API endpoints available through the SDK can be found [here](https://docs.credal.ai/getting-started/overview).
+```sh
+npm i -s @credal/sdk
+```
 
 ## Reference
 
-A full reference of the SDK is available [here](./reference.md).
+A full reference for this library is available [here](https://github.com/Credal-ai/credal-typescript-sdk-v1/blob/HEAD/./reference.md).
 
-# Installation
-
-```sh
-npm install @credal/sdk
-```
+## Usage
 
-# Usage
+Instantiate and use the client with the following:
 
 ```typescript
 import { CredalClient } from "@credal/sdk";
 
-const credal = new CredalClient({
-  apiKey: process.env.CREDAL_API_KEY,
-});
-
-await credal.copilots.sendMessage({
-    message: "Is Credal SOC 2 compliant?",
-    userEmail: "ravin@credal.ai"
+const client = new CredalClient({ token: "YOUR_TOKEN" });
+await client.agents.sendMessage({
+    agentId: "cc3fd192-ea62-11f0-99fd-03d6b2458fff",
+    conversation: {
+        type: "new"
+    },
+    message: "What documents do we have about Q4 planning?"
 });
 ```
 
-Docs for the API endpoints available through the SDK can be found [here](https://docs.credal.ai/getting-started/overview). 
-
-## Self Hosted
-
-If you're on a self-hosted Credal instance, then you can customize the base url of the SDK. 
-
-```typescript
-const credal = new CredalClient({
-    apiKey: process.env.CREDAL_API_KEY,
-    environment: "https://<custom-domain>/api",
-  });
-```
-
 ## Request and Response Types
 
-The SDK exports all request and response types as TypeScript interfaces. Simply 
-import them under the `Credal` namespace: 
+The SDK exports all request and response types as TypeScript interfaces. Simply import them with the
+following namespace:
 
-```ts
-import { Credal } from "@credal/sdk"; 
+```typescript
+import { Credal } from "@credal/sdk";
 
-const metadata: Credal.DocumentMetadataPatch = {
-  resourceIdentifier: "..."
+const request: Credal.SendMessageAgentsRequest = {
+    ...
 };
 ```
 
 ## Exception Handling
 
-When the API returns a non-success status code (4xx or 5xx response), 
-a subclass of [CredalError](./src/errors/CredalError.ts) will be thrown:
+When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
+will be thrown.
 
-```ts
+```typescript
 import { CredalError } from "@credal/sdk";
 
 try {
-  await credal.copilots.sendMessage(...);
+    await client.agents.sendMessage(...);
 } catch (err) {
-  if (err instanceof CredalError) {
-    console.log(err.statusCode); 
-    console.log(err.message);
-    console.log(err.body); 
-  }
+    if (err instanceof CredalError) {
+        console.log(err.statusCode);
+        console.log(err.message);
+        console.log(err.body);
+        console.log(err.rawResponse);
+    }
 }
 ```
 
-## Retries
+## Advanced
+
+### Subpackage Exports
+
+This SDK supports direct imports of subpackage clients, which allows JavaScript bundlers to tree-shake and include only the imported subpackage code. This results in much smaller bundle sizes.
+
+```typescript
+import { AgentsClient } from '@credal/sdk/agents';
+
+const client = new AgentsClient({...});
+```
+
+### Additional Headers
 
-The SDK is instrumented with automatic retries with exponential backoff. A request will be
-retried as long as the request is deemed retriable and the number of retry attempts has not grown larger
-than the configured retry limit (default: 2).
+If you would like to send additional headers as part of the request, use the `headers` request option.
 
-A request is deemed retriable when any of the following HTTP status codes is returned:
+```typescript
+import { CredalClient } from "@credal/sdk";
+
+const client = new CredalClient({
+    ...
+    headers: {
+        'X-Custom-Header': 'custom value'
+    }
+});
+
+const response = await client.agents.sendMessage(..., {
+    headers: {
+        'X-Custom-Header': 'custom value'
+    }
+});
+```
+
+### Additional Query String Parameters
+
+If you would like to send additional query string parameters as part of the request, use the `queryParams` request option.
+
+```typescript
+const response = await client.agents.sendMessage(..., {
+    queryParams: {
+        'customQueryParamKey': 'custom query param value'
+    }
+});
+```
+
+### Retries
+
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2).
+
+A request is deemed retryable when any of the following HTTP status codes is returned:
 
 - [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
 - [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
 - [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
-  
-Use the `maxRetries` request option to configure this behavior. 
 
-```ts
-const response = await credal.copilots.sendMessage(..., {
-  maxRetries: 0 // override maxRetries at the request level
+Use the `maxRetries` request option to configure this behavior.
+
+```typescript
+const response = await client.agents.sendMessage(..., {
+    maxRetries: 0 // override maxRetries at the request level
 });
 ```
 
-## Timeouts
+### Timeouts
 
-The SDK defaults to a 60 second timout. Use the `timeoutInSeconds` option to 
-configure this behavior. 
+The SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.
 
-```ts
-const response = await credal.copilots.sendMessage(..., {
-  timeoutInSeconds: 30 // override timeout to 30s
+```typescript
+const response = await client.agents.sendMessage(..., {
+    timeoutInSeconds: 30 // override timeout to 30s
 });
 ```
 
-## Aborting Requests
+### Aborting Requests
 
-The SDK allows users to abort requests at any point by passing 
-in an abort signal. 
+The SDK allows users to abort requests at any point by passing in an abort signal.
 
-```ts
+```typescript
 const controller = new AbortController();
-const response = await credal.copilots.sendMessage(..., {
-  abortSignal: controller.signal,
+const response = await client.agents.sendMessage(..., {
+    abortSignal: controller.signal
 });
 controller.abort(); // aborts the request
 ```
 
-## Runtime compatiblity
+### Access Raw Response Data
 
-The SDK defaults to `node-fetch` but will use the global fetch client if present. The SDK 
-works in the following runtimes: 
+The SDK provides access to raw response data, including headers, through the `.withRawResponse()` method.
+The `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property.
 
-The following runtimes are supported:
+```typescript
+const { data, rawResponse } = await client.agents.sendMessage(...).withRawResponse();
 
-- Node.js 18+ 
-- Vercel 
-- Cloudflare Workers
-- Deno v1.25+
-- Bun 1.0+
-- React Native
+console.log(data);
+console.log(rawResponse.headers['X-My-Header']);
+```
 
-### Customizing Fetch client
+### Logging
 
-The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're 
-running in an unsupported environment, this provides a way for you to break the glass and 
-ensure the SDK works. 
+The SDK supports logging. You can configure the logger by passing in a `logging` object to the client options.
 
+```typescript
+import { CredalClient, logging } from "@credal/sdk";
+
+const client = new CredalClient({
+    ...
+    logging: {
+        level: logging.LogLevel.Debug, // defaults to logging.LogLevel.Info
+        logger: new logging.ConsoleLogger(), // defaults to ConsoleLogger
+        silent: false, // defaults to true, set to false to enable logging
+    }
+});
+```
+The `logging` object can have the following properties:
+- `level`: The log level to use. Defaults to `logging.LogLevel.Info`.
+- `logger`: The logger to use. Defaults to a `logging.ConsoleLogger`.
+- `silent`: Whether to silence the logger. Defaults to `true`.
+
+The `level` property can be one of the following values:
+- `logging.LogLevel.Debug`
+- `logging.LogLevel.Info`
+- `logging.LogLevel.Warn`
+- `logging.LogLevel.Error`
+
+To provide a custom logger, you can pass in an object that implements the `logging.ILogger` interface.
+
+<details>
+<summary>Custom logger examples</summary>
+
+Here's an example using the popular `winston` logging library.
 ```ts
+import winston from 'winston';
+
+const winstonLogger = winston.createLogger({...});
+
+const logger: logging.ILogger = {
+    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
+    info: (msg, ...args) => winstonLogger.info(msg, ...args),
+    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+    error: (msg, ...args) => winstonLogger.error(msg, ...args),
+};
+```
+
+Here's an example using the popular `pino` logging library.
+
+```ts
+import pino from 'pino';
+
+const pinoLogger = pino({...});
+
+const logger: logging.ILogger = {
+  debug: (msg, ...args) => pinoLogger.debug(args, msg),
+  info: (msg, ...args) => pinoLogger.info(args, msg),
+  warn: (msg, ...args) => pinoLogger.warn(args, msg),
+  error: (msg, ...args) => pinoLogger.error(args, msg),
+};
+```
+</details>
+
+
+### Custom Fetch
+
+The SDK provides a low-level `fetch` method for making custom HTTP requests while still
+benefiting from SDK-level configuration like authentication, retries, timeouts, and logging.
+This is useful for calling API endpoints not yet supported in the SDK.
+
+```typescript
+const response = await client.fetch("/v1/custom/endpoint", {
+    method: "GET",
+}, {
+    timeoutInSeconds: 30,
+    maxRetries: 3,
+    headers: {
+        "X-Custom-Header": "custom-value",
+    },
+});
+
+const data = await response.json();
+```
+
+### Custom Fetcher
+
+The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an
+unsupported environment, this provides a way for you to break glass and ensure the SDK works.
+
+```typescript
 import { CredalClient } from "@credal/sdk";
 
-const credal = new CredalClient({
-  apiKey: "...",
-  fetcher: // provide your implementation here
+const client = new CredalClient({
+    ...
+    fetcher: // provide your implementation here
 });
 ```
+
+### Runtime Compatibility
+
+
+The SDK works in the following runtimes:
+
+
+
+- Node.js 18+
+- Vercel
+- Cloudflare Workers
+- Deno v1.25+
+- Bun 1.0+
+- React Native
+
+
+## Contributing
+
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

package/dist/cjs/BaseClient.js

@@ -43,8 +43,8 @@ function normalizeClientOptions(options) {
     const headers = (0, headers_js_1.mergeHeaders)({
         "X-Fern-Language": "JavaScript",
         "X-Fern-SDK-Name": "@credal/sdk",
-        "X-Fern-SDK-Version": "0.1.16",
-        "User-Agent": "@credal/sdk/0.1.16",
+        "X-Fern-SDK-Version": "1.0.0",
+        "User-Agent": "@credal/sdk/1.0.0",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options === null || options === void 0 ? void 0 : options.headers);

package/dist/cjs/Client.d.ts

@@ -1,10 +1,7 @@
-import { CopilotsClient } from "./api/resources/copilots/client/Client.js";
-import { DocumentCatalogClient } from "./api/resources/documentCatalog/client/Client.js";
-import { DocumentCollectionsClient } from "./api/resources/documentCollections/client/Client.js";
-import { SearchClient } from "./api/resources/search/client/Client.js";
-import { UsersClient } from "./api/resources/users/client/Client.js";
+import { AgentsClient } from "./api/resources/agents/client/Client.js";
 import type { BaseClientOptions, BaseRequestOptions } from "./BaseClient.js";
 import { type NormalizedClientOptionsWithAuth } from "./BaseClient.js";
+import * as core from "./core/index.js";
 export declare namespace CredalClient {
     type Options = BaseClientOptions;
     interface RequestOptions extends BaseRequestOptions {
@@ -12,15 +9,18 @@ export declare namespace CredalClient {
 }
 export declare class CredalClient {
     protected readonly _options: NormalizedClientOptionsWithAuth<CredalClient.Options>;
-    protected _copilots: CopilotsClient | undefined;
-    protected _documentCatalog: DocumentCatalogClient | undefined;
-    protected _documentCollections: DocumentCollectionsClient | undefined;
-    protected _search: SearchClient | undefined;
-    protected _users: UsersClient | undefined;
-    constructor(options?: CredalClient.Options);
-    get copilots(): CopilotsClient;
-    get documentCatalog(): DocumentCatalogClient;
-    get documentCollections(): DocumentCollectionsClient;
-    get search(): SearchClient;
-    get users(): UsersClient;
+    protected _agents: AgentsClient | undefined;
+    constructor(options: CredalClient.Options);
+    get agents(): AgentsClient;
+    /**
+     * Make a passthrough request using the SDK's configured auth, retry, logging, etc.
+     * This is useful for making requests to endpoints not yet supported in the SDK.
+     * The input can be a URL string, URL object, or Request object. Relative paths are resolved against the configured base URL.
+     *
+     * @param {Request | string | URL} input - The URL, path, or Request object.
+     * @param {RequestInit} init - Standard fetch RequestInit options.
+     * @param {core.PassthroughRequest.RequestOptions} requestOptions - Per-request overrides (timeout, retries, headers, abort signal).
+     * @returns {Promise<Response>} A standard Response object.
+     */
+    fetch(input: Request | string | URL, init?: RequestInit, requestOptions?: core.PassthroughRequest.RequestOptions): Promise<Response>;
 }

package/dist/cjs/Client.js

@@ -1,36 +1,83 @@
 "use strict";
 // This file was auto-generated by Fern from our API Definition.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CredalClient = void 0;
-const Client_js_1 = require("./api/resources/copilots/client/Client.js");
-const Client_js_2 = require("./api/resources/documentCatalog/client/Client.js");
-const Client_js_3 = require("./api/resources/documentCollections/client/Client.js");
-const Client_js_4 = require("./api/resources/search/client/Client.js");
-const Client_js_5 = require("./api/resources/users/client/Client.js");
+const Client_js_1 = require("./api/resources/agents/client/Client.js");
 const BaseClient_js_1 = require("./BaseClient.js");
+const core = __importStar(require("./core/index.js"));
 class CredalClient {
-    constructor(options = {}) {
+    constructor(options) {
         this._options = (0, BaseClient_js_1.normalizeClientOptionsWithAuth)(options);
     }
-    get copilots() {
-        var _a;
-        return ((_a = this._copilots) !== null && _a !== void 0 ? _a : (this._copilots = new Client_js_1.CopilotsClient(this._options)));
-    }
-    get documentCatalog() {
-        var _a;
-        return ((_a = this._documentCatalog) !== null && _a !== void 0 ? _a : (this._documentCatalog = new Client_js_2.DocumentCatalogClient(this._options)));
-    }
-    get documentCollections() {
-        var _a;
-        return ((_a = this._documentCollections) !== null && _a !== void 0 ? _a : (this._documentCollections = new Client_js_3.DocumentCollectionsClient(this._options)));
-    }
-    get search() {
+    get agents() {
         var _a;
-        return ((_a = this._search) !== null && _a !== void 0 ? _a : (this._search = new Client_js_4.SearchClient(this._options)));
+        return ((_a = this._agents) !== null && _a !== void 0 ? _a : (this._agents = new Client_js_1.AgentsClient(this._options)));
     }
-    get users() {
-        var _a;
-        return ((_a = this._users) !== null && _a !== void 0 ? _a : (this._users = new Client_js_5.UsersClient(this._options)));
+    /**
+     * Make a passthrough request using the SDK's configured auth, retry, logging, etc.
+     * This is useful for making requests to endpoints not yet supported in the SDK.
+     * The input can be a URL string, URL object, or Request object. Relative paths are resolved against the configured base URL.
+     *
+     * @param {Request | string | URL} input - The URL, path, or Request object.
+     * @param {RequestInit} init - Standard fetch RequestInit options.
+     * @param {core.PassthroughRequest.RequestOptions} requestOptions - Per-request overrides (timeout, retries, headers, abort signal).
+     * @returns {Promise<Response>} A standard Response object.
+     */
+    fetch(input, init, requestOptions) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            return core.makePassthroughRequest(input, init, {
+                baseUrl: (_a = this._options.baseUrl) !== null && _a !== void 0 ? _a : this._options.environment,
+                headers: this._options.headers,
+                timeoutInSeconds: this._options.timeoutInSeconds,
+                maxRetries: this._options.maxRetries,
+                fetch: this._options.fetch,
+                logging: this._options.logging,
+                getAuthHeaders: () => __awaiter(this, void 0, void 0, function* () { return (yield this._options.authProvider.getAuthRequest()).headers; }),
+            }, requestOptions);
+        });
     }
 }
 exports.CredalClient = CredalClient;

package/dist/cjs/api/errors/BadRequestError.d.ts

@@ -0,0 +1,5 @@
+import type * as core from "../../core/index.js";
+import * as errors from "../../errors/index.js";
+export declare class BadRequestError extends errors.CredalError {
+    constructor(body?: unknown, rawResponse?: core.RawResponse);
+}

package/dist/cjs/api/errors/BadRequestError.js

@@ -0,0 +1,54 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BadRequestError = void 0;
+const errors = __importStar(require("../../errors/index.js"));
+class BadRequestError extends errors.CredalError {
+    constructor(body, rawResponse) {
+        super({
+            message: "BadRequestError",
+            statusCode: 400,
+            body: body,
+            rawResponse: rawResponse,
+        });
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        this.name = this.constructor.name;
+    }
+}
+exports.BadRequestError = BadRequestError;

package/dist/cjs/api/errors/ForbiddenError.d.ts

@@ -0,0 +1,5 @@
+import type * as core from "../../core/index.js";
+import * as errors from "../../errors/index.js";
+export declare class ForbiddenError extends errors.CredalError {
+    constructor(body?: unknown, rawResponse?: core.RawResponse);
+}