mavenagi 1.2.39 → 1.2.41

package/README.md

@@ -12,17 +12,22 @@ The Mavenagi TypeScript library provides convenient access to the Mavenagi APIs
 - [Usage](#usage)
 - [Aborting Requests](#aborting-requests)
 - [Runtime Compatibility](#runtime-compatibility)
+- [Environments](#environments)
 - [Request and Response Types](#request-and-response-types)
 - [Exception Handling](#exception-handling)
 - [Streaming Response](#streaming-response)
 - [Binary Response](#binary-response)
 - [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)
 
@@ -41,7 +46,7 @@ A full reference for this library is available [here](https://github.com/mavenag
 Instantiate and use the client with the following:
 
 ```typescript
-import { MavenAGIClient, MavenAGI } from "mavenagi";
+import { MavenAGI, MavenAGIClient } from "mavenagi";
 
 const client = new MavenAGIClient({ appId: "YOUR_APP_ID", appSecret: "YOUR_APP_SECRET", organizationId: "YOUR_ORGANIZATION_ID", agentId: "YOUR_AGENT_ID" });
 await client.actions.search({});
@@ -85,6 +90,18 @@ const client = new MavenAGIClient({
 });
 ```
 
+## Environments
+
+This SDK allows you to configure different environments for API requests.
+
+```typescript
+import { MavenAGIClient, MavenAGIEnvironment } from "mavenagi";
+
+const client = new MavenAGIClient({
+    environment: MavenAGIEnvironment.Production,
+});
+```
+
 ## Request and Response Types
 
 The SDK exports all request and response types as TypeScript interfaces. Simply import them with the
@@ -541,11 +558,30 @@ const text = new TextDecoder().decode(bytes);
 
 ## 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 { ActionsClient } from 'mavenagi/actions';
+
+const client = new ActionsClient({...});
+```
+
 ### Additional Headers
 
 If you would like to send additional headers as part of the request, use the `headers` request option.
 
 ```typescript
+import { MavenAGIClient } from "mavenagi";
+
+const client = new MavenAGIClient({
+    ...
+    headers: {
+        'X-Custom-Header': 'custom value'
+    }
+});
+
 const response = await client.actions.search(..., {
     headers: {
         'X-Custom-Header': 'custom value'
@@ -571,11 +607,19 @@ The SDK is instrumented with automatic retries with exponential backoff. A reque
 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:
+Which status codes are retried depends on the `retryStatusCodes` generator configuration:
+
+**`legacy`** (current default): retries on
+- [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#server_error_responses) (All server errors, including 500)
 
+**`recommended`**: retries on
 - [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)
+- [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (Bad Gateway)
+- [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (Service Unavailable)
+- [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (Gateway Timeout)
 
 Use the `maxRetries` request option to configure this behavior.
 
@@ -619,21 +663,90 @@ console.log(data);
 console.log(rawResponse.headers['X-My-Header']);
 ```
 
-### Runtime Compatibility
+### Logging
 
+The SDK supports logging. You can configure the logger by passing in a `logging` object to the client options.
 
-The SDK works in the following runtimes:
+```typescript
+import { MavenAGIClient, logging } from "mavenagi";
 
+const client = new MavenAGIClient({
+    ...
+    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`
 
-- Node.js 18+
-- Vercel
-- Cloudflare Workers
-- Deno v1.25+
-- Bun 1.0+
-- React Native
+To provide a custom logger, you can pass in an object that implements the `logging.ILogger` interface.
 
-### Customizing Fetch Client
+<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.
@@ -647,6 +760,21 @@ const client = new MavenAGIClient({
 });
 ```
 
+### 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.
@@ -655,4 +783,4 @@ otherwise they would be overwritten upon the next generated release. Feel free t
 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!
+On the other hand, contributions to the README are always very welcome!

package/api/resources/actions/client/Client.d.ts

@@ -1,38 +1,40 @@
 import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient";
+import { type NormalizedClientOptionsWithAuth } from "../../../../BaseClient";
 import * as core from "../../../../core";
 import * as MavenAGI from "../../../index";
-export declare namespace Actions {
-    interface Options extends BaseClientOptions {
-    }
+export declare namespace ActionsClient {
+    type Options = BaseClientOptions;
     interface RequestOptions extends BaseRequestOptions {
     }
 }
-export declare class Actions {
-    protected readonly _options: Actions.Options;
-    constructor(_options: Actions.Options);
+export declare class ActionsClient {
+    protected readonly _options: NormalizedClientOptionsWithAuth<ActionsClient.Options>;
+    constructor(options: ActionsClient.Options);
     /**
      * @param {MavenAGI.ActionsSearchRequest} request
-     * @param {Actions.RequestOptions} requestOptions - Request-specific configuration.
+     * @param {ActionsClient.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link MavenAGI.NotFoundError}
      * @throws {@link MavenAGI.BadRequestError}
      * @throws {@link MavenAGI.PayloadTooLargeError}
+     * @throws {@link MavenAGI.TooManyRequestsError}
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
      *     await client.actions.search({})
      */
-    search(request: MavenAGI.ActionsSearchRequest, requestOptions?: Actions.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionsResponse>;
+    search(request: MavenAGI.ActionsSearchRequest, requestOptions?: ActionsClient.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionsResponse>;
     private __search;
     /**
      * Update an action or create it if it doesn't exist
      *
      * @param {MavenAGI.ActionRequest} request
-     * @param {Actions.RequestOptions} requestOptions - Request-specific configuration.
+     * @param {ActionsClient.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link MavenAGI.NotFoundError}
      * @throws {@link MavenAGI.BadRequestError}
      * @throws {@link MavenAGI.PayloadTooLargeError}
+     * @throws {@link MavenAGI.TooManyRequestsError}
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
@@ -58,24 +60,25 @@ export declare class Actions {
      *         language: "en"
      *     })
      */
-    createOrUpdate(request: MavenAGI.ActionRequest, requestOptions?: Actions.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionResponse>;
+    createOrUpdate(request: MavenAGI.ActionRequest, requestOptions?: ActionsClient.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionResponse>;
     private __createOrUpdate;
     /**
      * Get an action by its supplied ID
      *
      * @param {string} actionReferenceId - The reference ID of the action to get. All other entity ID fields are inferred from the request.
      * @param {MavenAGI.ActionGetRequest} request
-     * @param {Actions.RequestOptions} requestOptions - Request-specific configuration.
+     * @param {ActionsClient.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link MavenAGI.NotFoundError}
      * @throws {@link MavenAGI.BadRequestError}
      * @throws {@link MavenAGI.PayloadTooLargeError}
+     * @throws {@link MavenAGI.TooManyRequestsError}
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
      *     await client.actions.get("get-balance")
      */
-    get(actionReferenceId: string, request?: MavenAGI.ActionGetRequest, requestOptions?: Actions.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionResponse>;
+    get(actionReferenceId: string, request?: MavenAGI.ActionGetRequest, requestOptions?: ActionsClient.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionResponse>;
     private __get;
     /**
      * Update mutable action fields
@@ -85,11 +88,12 @@ export declare class Actions {
      *
      * @param {string} actionReferenceId - The reference ID of the action to patch.
      * @param {MavenAGI.ActionPatchRequest} request
-     * @param {Actions.RequestOptions} requestOptions - Request-specific configuration.
+     * @param {ActionsClient.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link MavenAGI.NotFoundError}
      * @throws {@link MavenAGI.BadRequestError}
      * @throws {@link MavenAGI.PayloadTooLargeError}
+     * @throws {@link MavenAGI.TooManyRequestsError}
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
@@ -105,23 +109,23 @@ export declare class Actions {
      *         }
      *     })
      */
-    patch(actionReferenceId: string, request?: MavenAGI.ActionPatchRequest, requestOptions?: Actions.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionResponse>;
+    patch(actionReferenceId: string, request?: MavenAGI.ActionPatchRequest, requestOptions?: ActionsClient.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionResponse>;
     private __patch;
     /**
      * Delete an action
      *
      * @param {string} actionReferenceId - The reference ID of the action to unregister. All other entity ID fields are inferred from the request.
-     * @param {Actions.RequestOptions} requestOptions - Request-specific configuration.
+     * @param {ActionsClient.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link MavenAGI.NotFoundError}
      * @throws {@link MavenAGI.BadRequestError}
      * @throws {@link MavenAGI.PayloadTooLargeError}
+     * @throws {@link MavenAGI.TooManyRequestsError}
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
      *     await client.actions.delete("get-balance")
      */
-    delete(actionReferenceId: string, requestOptions?: Actions.RequestOptions): core.HttpResponsePromise<void>;
+    delete(actionReferenceId: string, requestOptions?: ActionsClient.RequestOptions): core.HttpResponsePromise<void>;
     private __delete;
-    protected _getAuthorizationHeader(): Promise<string | undefined>;
 }