@nimble-way/nimble-js 0.11.0 → 0.13.0

package/src/client.ts

@@ -32,9 +32,14 @@ import {
 import { APIPromise } from './core/api-promise';
 import {
   Agent,
+  AgentGenerateParams,
+  AgentGenerateResponse,
+  AgentGetGenerationResponse,
   AgentGetResponse,
   AgentListParams,
   AgentListResponse,
+  AgentPublishParams,
+  AgentPublishResponse,
   AgentRunAsyncParams,
   AgentRunAsyncResponse,
   AgentRunBatchParams,
@@ -78,6 +83,11 @@ export interface ClientOptions {
    */
   apiKey?: string | null | undefined;
 
+  /**
+   * Defaults to process.env['CLIENT_SOURCE'].
+   */
+  clientSource?: string | null | undefined;
+
   /**
    * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
    *
@@ -152,6 +162,7 @@ export interface ClientOptions {
  */
 export class Nimble {
   apiKey: string | null;
+  clientSource: string | null;
 
   baseURL: string;
   maxRetries: number;
@@ -169,6 +180,7 @@ export class Nimble {
    * API Client for interfacing with the Nimble API.
    *
    * @param {string | null | undefined} [opts.apiKey=process.env['NIMBLE_API_KEY'] ?? null]
+   * @param {string | null | undefined} [opts.clientSource=process.env['CLIENT_SOURCE'] ?? sdk]
    * @param {string} [opts.baseURL=process.env['NIMBLE_BASE_URL'] ?? https://sdk.nimbleway.com] - Override the default base URL for the API.
    * @param {number} [opts.timeout=3 minutes] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
@@ -180,10 +192,12 @@ export class Nimble {
   constructor({
     baseURL = readEnv('NIMBLE_BASE_URL'),
     apiKey = readEnv('NIMBLE_API_KEY') ?? null,
+    clientSource = readEnv('CLIENT_SOURCE') ?? 'sdk',
     ...opts
   }: ClientOptions = {}) {
     const options: ClientOptions = {
       apiKey,
+      clientSource,
       ...opts,
       baseURL: baseURL || `https://sdk.nimbleway.com`,
     };
@@ -203,9 +217,22 @@ export class Nimble {
     this.fetch = options.fetch ?? Shims.getDefaultFetch();
     this.#encoder = Opts.FallbackEncoder;
 
+    const customHeadersEnv = readEnv('NIMBLE_CUSTOM_HEADERS');
+    if (customHeadersEnv) {
+      const parsed: Record<string, string> = {};
+      for (const line of customHeadersEnv.split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon >= 0) {
+          parsed[line.substring(0, colon).trim()] = line.substring(colon + 1).trim();
+        }
+      }
+      options.defaultHeaders = { ...parsed, ...options.defaultHeaders };
+    }
+
     this._options = options;
 
     this.apiKey = apiKey;
+    this.clientSource = clientSource;
   }
 
   /**
@@ -222,6 +249,7 @@ export class Nimble {
       fetch: this.fetch,
       fetchOptions: this.fetchOptions,
       apiKey: this.apiKey,
+      clientSource: this.clientSource,
       ...options,
     });
     return client;
@@ -754,6 +782,7 @@ export class Nimble {
         'X-Stainless-Retry-Count': String(retryCount),
         ...(options.timeout ? { 'X-Stainless-Timeout': String(Math.trunc(options.timeout / 1000)) } : {}),
         ...getPlatformHeaders(),
+        'X-Client-Source': this.clientSource,
       },
       await this.authHeaders(options),
       this._options.defaultHeaders,
@@ -866,11 +895,16 @@ export declare namespace Nimble {
   export {
     Agent as Agent,
     type AgentListResponse as AgentListResponse,
+    type AgentGenerateResponse as AgentGenerateResponse,
     type AgentGetResponse as AgentGetResponse,
+    type AgentGetGenerationResponse as AgentGetGenerationResponse,
+    type AgentPublishResponse as AgentPublishResponse,
     type AgentRunResponse as AgentRunResponse,
     type AgentRunAsyncResponse as AgentRunAsyncResponse,
     type AgentRunBatchResponse as AgentRunBatchResponse,
     type AgentListParams as AgentListParams,
+    type AgentGenerateParams as AgentGenerateParams,
+    type AgentPublishParams as AgentPublishParams,
     type AgentRunParams as AgentRunParams,
     type AgentRunAsyncParams as AgentRunAsyncParams,
     type AgentRunBatchParams as AgentRunBatchParams,

package/src/internal/types.ts

@@ -40,7 +40,6 @@ type OverloadedParameters<T> =
   : T extends (...args: infer A) => unknown ? A
   : never;
 
-/* eslint-disable */
 /**
  * These imports attempt to get types from a parent package's dependencies.
  * Unresolved bare specifiers can trigger [automatic type acquisition][1] in some projects, which
@@ -63,19 +62,18 @@ type OverloadedParameters<T> =
  *
  * [1]: https://www.typescriptlang.org/tsconfig/#typeAcquisition
  */
-/** @ts-ignore For users with \@types/node */
+/** @ts-ignore For users with \@types/node */ /* prettier-ignore */
 type UndiciTypesRequestInit = NotAny<import('../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit>;
-/** @ts-ignore For users with undici */
+/** @ts-ignore For users with undici */ /* prettier-ignore */
 type UndiciRequestInit = NotAny<import('../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici/index.d.ts').RequestInit>;
-/** @ts-ignore For users with \@types/bun */
+/** @ts-ignore For users with \@types/bun */ /* prettier-ignore */
 type BunRequestInit = globalThis.FetchRequestInit;
-/** @ts-ignore For users with node-fetch@2 */
+/** @ts-ignore For users with node-fetch@2 */ /* prettier-ignore */
 type NodeFetch2RequestInit = NotAny<import('../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit>;
-/** @ts-ignore For users with node-fetch@3, doesn't need file extension because types are at ./@types/index.d.ts */
+/** @ts-ignore For users with node-fetch@3, doesn't need file extension because types are at ./@types/index.d.ts */ /* prettier-ignore */
 type NodeFetch3RequestInit =  NotAny<import('../node_modules/node-fetch').RequestInit> | NotAny<import('../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/node-fetch').RequestInit>;
-/** @ts-ignore For users who use Deno */
+/** @ts-ignore For users who use Deno */ /* prettier-ignore */
 type FetchRequestInit = NonNullable<OverloadedParameters<typeof fetch>[1]>;
-/* eslint-enable */
 
 type RequestInits =
   | NotAny<UndiciTypesRequestInit>

package/src/internal/utils/env.ts

@@ -9,10 +9,10 @@
  */
 export const readEnv = (env: string): string | undefined => {
   if (typeof (globalThis as any).process !== 'undefined') {
-    return (globalThis as any).process.env?.[env]?.trim() ?? undefined;
+    return (globalThis as any).process.env?.[env]?.trim() || undefined;
   }
   if (typeof (globalThis as any).Deno !== 'undefined') {
-    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+    return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined;
   }
   return undefined;
 };

package/src/resources/agent.ts

@@ -7,7 +7,12 @@ import { path } from '../internal/utils/path';
 
 export class Agent extends APIResource {
   /**
-   * List Templates
+   * List Agent Templates
+   *
+   * @example
+   * ```ts
+   * const agents = await client.agent.list();
+   * ```
    */
   list(
     query: AgentListParams | null | undefined = {},
@@ -17,14 +22,69 @@ export class Agent extends APIResource {
   }
 
   /**
-   * Get Template
+   * Create Agent Generation
+   *
+   * @example
+   * ```ts
+   * const response = await client.agent.generate({
+   *   prompt: 'prompt',
+   *   url: 'url',
+   * });
+   * ```
+   */
+  generate(body: AgentGenerateParams, options?: RequestOptions): APIPromise<AgentGenerateResponse> {
+    return this._client.post('/v1/agents/generations', { body, ...options });
+  }
+
+  /**
+   * Get Agent Template
+   *
+   * @example
+   * ```ts
+   * const agent = await client.agent.get('template_name');
+   * ```
    */
   get(templateName: string, options?: RequestOptions): APIPromise<AgentGetResponse> {
     return this._client.get(path`/v1/agents/${templateName}`, options);
   }
 
+  /**
+   * Get Agent Generation
+   *
+   * @example
+   * ```ts
+   * const response = await client.agent.getGeneration(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  getGeneration(generationID: string, options?: RequestOptions): APIPromise<AgentGetGenerationResponse> {
+    return this._client.get(path`/v1/agents/generations/${generationID}`, options);
+  }
+
+  /**
+   * Publish Agent Version
+   *
+   * @deprecated
+   */
+  publish(
+    agentName: string,
+    body: AgentPublishParams,
+    options?: RequestOptions,
+  ): APIPromise<AgentPublishResponse> {
+    return this._client.post(path`/v1/agents/${agentName}/publish`, { body, ...options });
+  }
+
   /**
    * Execute WSA Realtime Endpoint
+   *
+   * @example
+   * ```ts
+   * const response = await client.agent.run({
+   *   agent: 'agent',
+   *   params: { foo: 'bar' },
+   * });
+   * ```
    */
   run(body: AgentRunParams, options?: RequestOptions): APIPromise<AgentRunResponse> {
     return this._client.post('/v1/agents/run', { body, ...options });
@@ -32,6 +92,14 @@ export class Agent extends APIResource {
 
   /**
    * Execute WSA Async Endpoint
+   *
+   * @example
+   * ```ts
+   * const response = await client.agent.runAsync({
+   *   agent: 'agent',
+   *   params: { foo: 'bar' },
+   * });
+   * ```
    */
   runAsync(body: AgentRunAsyncParams, options?: RequestOptions): APIPromise<AgentRunAsyncResponse> {
     return this._client.post('/v1/agents/async', { body, ...options });
@@ -39,6 +107,14 @@ export class Agent extends APIResource {
 
   /**
    * Execute WSA Batch Endpoint
+   *
+   * @example
+   * ```ts
+   * const response = await client.agent.runBatch({
+   *   inputs: [{}],
+   *   shared_inputs: { agent: 'agent' },
+   * });
+   * ```
    */
   runBatch(body: AgentRunBatchParams, options?: RequestOptions): APIPromise<AgentRunBatchResponse> {
     return this._client.post('/v1/agents/batch', { body, ...options });
@@ -67,6 +143,70 @@ export namespace AgentListResponse {
   }
 }
 
+export interface AgentGenerateResponse {
+  id: string;
+
+  status: string;
+
+  agent_name?: string | null;
+
+  completed_at?: string | null;
+
+  created_at?: string | null;
+
+  error?: string | null;
+
+  generated_version?: AgentGenerateResponse.GeneratedVersion | null;
+
+  generated_version_id?: string | null;
+
+  source_version_id?: string | null;
+
+  started_at?: string | null;
+
+  summary?: string | null;
+}
+
+export namespace AgentGenerateResponse {
+  export interface GeneratedVersion {
+    id: string;
+
+    agent_name: string;
+
+    created_at: string;
+
+    input_schema: unknown;
+
+    metadata: GeneratedVersion.Metadata;
+
+    output_schema: unknown;
+
+    steps: Array<unknown>;
+
+    version_number: number;
+
+    output_sample_data?: unknown;
+  }
+
+  export namespace GeneratedVersion {
+    export interface Metadata {
+      data_source?: string | null;
+
+      description?: string | null;
+
+      display_name?: string | null;
+
+      domain?: string | null;
+
+      entity_type?: string | null;
+
+      tags?: Array<string>;
+
+      vertical?: string | null;
+    }
+  }
+}
+
 export interface AgentGetResponse {
   display_name: string;
 
@@ -99,14 +239,16 @@ export namespace AgentGetResponse {
   }
 
   export interface InputProperty {
-    default?: string | null;
+    default?: string | boolean | number | null;
 
     description?: string | null;
 
-    examples?: Array<string> | null;
+    examples?: Array<unknown> | null;
 
     is_localization_param?: boolean;
 
+    is_pagination_param?: boolean;
+
     name?: string;
 
     required?: boolean;
@@ -117,6 +259,76 @@ export namespace AgentGetResponse {
   }
 }
 
+export interface AgentGetGenerationResponse {
+  id: string;
+
+  status: string;
+
+  agent_name?: string | null;
+
+  completed_at?: string | null;
+
+  created_at?: string | null;
+
+  error?: string | null;
+
+  generated_version?: AgentGetGenerationResponse.GeneratedVersion | null;
+
+  generated_version_id?: string | null;
+
+  source_version_id?: string | null;
+
+  started_at?: string | null;
+
+  summary?: string | null;
+}
+
+export namespace AgentGetGenerationResponse {
+  export interface GeneratedVersion {
+    id: string;
+
+    agent_name: string;
+
+    created_at: string;
+
+    input_schema: unknown;
+
+    metadata: GeneratedVersion.Metadata;
+
+    output_schema: unknown;
+
+    steps: Array<unknown>;
+
+    version_number: number;
+
+    output_sample_data?: unknown;
+  }
+
+  export namespace GeneratedVersion {
+    export interface Metadata {
+      data_source?: string | null;
+
+      description?: string | null;
+
+      display_name?: string | null;
+
+      domain?: string | null;
+
+      entity_type?: string | null;
+
+      tags?: Array<string>;
+
+      vertical?: string | null;
+    }
+  }
+}
+
+export interface AgentPublishResponse {
+  agent_name: string;
+
+  published_version_id: string;
+}
+
 export interface AgentRunResponse {
   data: AgentRunResponse.Data;
 
@@ -188,6 +400,11 @@ export namespace AgentRunResponse {
      */
     html?: string;
 
+    /**
+     * List of all unique URLs found on the page.
+     */
+    links?: Array<string>;
+
     /**
      * The Markdown version of the HTML content.
      */
@@ -604,6 +821,46 @@ export interface AgentListParams {
   search?: string | null;
 }
 
+export type AgentGenerateParams =
+  | AgentGenerateParams.CreateAgentGenerationRequest
+  | AgentGenerateParams.CreateAgentRefinementRequest;
+
+export declare namespace AgentGenerateParams {
+  export interface CreateAgentGenerationRequest {
+    prompt: string;
+
+    url: string;
+
+    agent_name?: string | null;
+
+    input_schema?: unknown;
+
+    metadata?: CreateAgentGenerationRequest.Metadata | null;
+
+    output_schema?: unknown;
+  }
+
+  export namespace CreateAgentGenerationRequest {
+    export interface Metadata {
+      description?: string | null;
+
+      display_name?: string | null;
+
+      tags?: Array<string>;
+    }
+  }
+
+  export interface CreateAgentRefinementRequest {
+    from_agent: string;
+
+    prompt: string;
+  }
+}
+
+export interface AgentPublishParams {
+  version_id: string;
+}
+
 export interface AgentRunParams {
   agent: string;
 
@@ -612,7 +869,7 @@ export interface AgentRunParams {
   /**
    * Response formats to include. All disabled by default.
    */
-  formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers'>;
+  formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers' | 'links'>;
 
   localization?: boolean;
 }
@@ -630,7 +887,7 @@ export interface AgentRunAsyncParams {
   /**
    * Response formats to include. All disabled by default.
    */
-  formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers'>;
+  formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers' | 'links'>;
 
   localization?: boolean;
 
@@ -666,7 +923,7 @@ export namespace AgentRunBatchParams {
     /**
      * Response formats to include. All disabled by default.
      */
-    formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers'>;
+    formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers' | 'links'>;
 
     localization?: boolean;
 
@@ -679,7 +936,7 @@ export namespace AgentRunBatchParams {
     /**
      * Response formats to include. All disabled by default.
      */
-    formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers'>;
+    formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers' | 'links'>;
 
     localization?: boolean;
 
@@ -690,11 +947,16 @@ export namespace AgentRunBatchParams {
 export declare namespace Agent {
   export {
     type AgentListResponse as AgentListResponse,
+    type AgentGenerateResponse as AgentGenerateResponse,
     type AgentGetResponse as AgentGetResponse,
+    type AgentGetGenerationResponse as AgentGetGenerationResponse,
+    type AgentPublishResponse as AgentPublishResponse,
     type AgentRunResponse as AgentRunResponse,
     type AgentRunAsyncResponse as AgentRunAsyncResponse,
     type AgentRunBatchResponse as AgentRunBatchResponse,
     type AgentListParams as AgentListParams,
+    type AgentGenerateParams as AgentGenerateParams,
+    type AgentPublishParams as AgentPublishParams,
     type AgentRunParams as AgentRunParams,
     type AgentRunAsyncParams as AgentRunAsyncParams,
     type AgentRunBatchParams as AgentRunBatchParams,

package/src/resources/crawl.ts

@@ -9,6 +9,11 @@ import { path } from '../internal/utils/path';
 export class Crawl extends APIResource {
   /**
    * Crawl by Filter
+   *
+   * @example
+   * ```ts
+   * const crawls = await client.crawl.list();
+   * ```
    */
   list(
     query: CrawlListParams | null | undefined = {},
@@ -19,6 +24,11 @@ export class Crawl extends APIResource {
 
   /**
    * Create crawl task
+   *
+   * @example
+   * ```ts
+   * const response = await client.crawl.run({ url: 'url' });
+   * ```
    */
   run(body: CrawlRunParams, options?: RequestOptions): APIPromise<CrawlRunResponse> {
     return this._client.post('/v1/crawl', { body, ...options });
@@ -26,6 +36,13 @@ export class Crawl extends APIResource {
 
   /**
    * Get crawl data
+   *
+   * @example
+   * ```ts
+   * const response = await client.crawl.status(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   * );
+   * ```
    */
   status(id: string, options?: RequestOptions): APIPromise<CrawlStatusResponse> {
     return this._client.get(path`/v1/crawl/${id}`, options);
@@ -33,6 +50,13 @@ export class Crawl extends APIResource {
 
   /**
    * Cancel Crawl
+   *
+   * @example
+   * ```ts
+   * const response = await client.crawl.terminate(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   * );
+   * ```
    */
   terminate(id: string, options?: RequestOptions): APIPromise<CrawlTerminateResponse> {
     return this._client.delete(path`/v1/crawl/${id}`, options);
@@ -708,7 +732,7 @@ export namespace CrawlRunParams {
     /**
      * Browser driver to use
      */
-    driver?: 'vx6' | 'vx8' | 'vx8-pro' | 'vx10' | 'vx10-pro' | 'vx12' | 'vx12-pro';
+    driver?: 'vx6' | 'vx8' | 'vx8-pro' | 'vx10' | 'vx10-pro' | 'vx12' | 'vx12-pro' | 'media-vx6';
 
     /**
      * Expected HTTP status codes for successful requests
@@ -718,7 +742,7 @@ export namespace CrawlRunParams {
     /**
      * List of acceptable response formats in order of preference
      */
-    formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers'>;
+    formats?: Array<'html' | 'markdown' | 'screenshot' | 'headers' | 'links'>;
 
     /**
      * Custom HTTP headers to include in the request
@@ -1273,6 +1297,13 @@ export namespace CrawlRunParams {
       | 'zu-ZA'
       | 'auto';
 
+    /**
+     * Selects which markdown conversion strategy to use. "full_page" converts the
+     * entire HTML page. "main_content" uses Mozilla Readability to extract the main
+     * article content before converting.
+     */
+    markdown_backend?: 'full_page' | 'main_content';
+
     /**
      * HTTP method for the request
      */

package/src/resources/index.ts

@@ -4,11 +4,16 @@ export * from './shared';
 export {
   Agent,
   type AgentListResponse,
+  type AgentGenerateResponse,
   type AgentGetResponse,
+  type AgentGetGenerationResponse,
+  type AgentPublishResponse,
   type AgentRunResponse,
   type AgentRunAsyncResponse,
   type AgentRunBatchResponse,
   type AgentListParams,
+  type AgentGenerateParams,
+  type AgentPublishParams,
   type AgentRunParams,
   type AgentRunAsyncParams,
   type AgentRunBatchParams,