@docusign/iam-sdk/src/funcs/agreementManagerAgreementsGetAgreementsList.ts

Developer-friendly & type-safe Typescript SDK specifically catered to leverage *@docusign/iam-sdk* API.

/*
 * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
 */

import { IamClientCore } from "../core.js";
import { encodeFormQuery, encodeSimple } from "../lib/encodings.js";
import { matchStatusCode } from "../lib/http.js";
import * as M from "../lib/matchers.js";
import { compactMap } from "../lib/primitives.js";
import { safeParse } from "../lib/schemas.js";
import { RequestOptions } from "../lib/sdks.js";
import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
import { pathToFunc } from "../lib/url.js";
import * as components from "../models/components/index.js";
import {
  ConnectionError,
  InvalidRequestError,
  RequestAbortedError,
  RequestTimeoutError,
  UnexpectedClientError,
} from "../models/errors/httpclienterrors.js";
import { IamClientError } from "../models/errors/iamclienterror.js";
import * as errors from "../models/errors/index.js";
import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
import * as operations from "../models/operations/index.js";
import { APICall, APIPromise } from "../types/async.js";
import { Result } from "../types/fp.js";

/**
 * Retrieve a list of agreements
 *
 * @remarks
 * This operation retrieves a list of all agreements available in the system. It provides a high-level overview of each agreement, including its unique identifier (`id`), title, type, status, and involved parties. The list also includes important metadata, such as the agreement's creation and modification timestamps, and information on the agreement's source system (e.g., eSign, CLM).
 *
 * Each agreement entry includes essential details that allow users to quickly assess the agreements and determine which ones are relevant for their needs. For example, the agreement's status can help users understand whether an agreement is still active, pending, or completed.
 *
 * The response also includes provisions that outline the key legal, financial, and lifecycle conditions, along with custom user-defined fields, providing a comprehensive understanding of each agreement.
 *
 * ### Use Cases:
 * - **Retrieving a list of agreements for integration into external systems**: Export or sync agreement data into other platforms (e.g., CRM, ERP systems) to align business processes across different tools.
 * - **Providing data for RAG (Retrieval-Augmented Generation) applications or Copilots**: The list of agreements can be a valuable data source for AI/LLM-based applications that answer user queries about agreements.
 *
 *   It allows Copilots to understand what agreements exist and offer insights based on their details.
 * - **Filtering agreements by type or status**: Determine which agreements are active, pending, or completed, and gather a summary of key provisions across multiple agreements.
 * - **Auditing or reporting**: Generate a report on agreements based on type, status, or date created, helping with compliance tracking and internal reviews.
 * - **Metadata tracking**: Track when agreements were created, modified, and by whom, ensuring proper governance and version control.
 *
 * ### Key Features:
 * - **Comprehensive Agreement Overview**: Provides high-level visibility into all agreements, with essential details for each one, including status, type, and involved parties.
 * - **Metadata and Provisions**: Returns important metadata and provisions (legal, financial, and custom) for each agreement, helping users understand their obligations and contract terms.
 * - **Source System Information**: Captures details about where the agreement originated (e.g., eSign, CLM), making it easier to integrate and track agreements across different business systems.
 * - **Data for AI Applications**: The operation is designed to support LLM-powered apps, making it ideal for use in RAG-based applications and Copilots that query agreements for decision-making or information purposes.
 *
 * If set, this operation will use {@link Security.accessToken} from the global security.
 */
export function agreementManagerAgreementsGetAgreementsList(
  client: IamClientCore,
  request: operations.GetAgreementsListRequest,
  options?: RequestOptions,
): APIPromise<
  Result<
    components.AgreementsResponse,
    | errors.ErrDetails
    | IamClientError
    | ResponseValidationError
    | ConnectionError
    | RequestAbortedError
    | RequestTimeoutError
    | InvalidRequestError
    | UnexpectedClientError
    | SDKValidationError
  >
> {
  return new APIPromise($do(
    client,
    request,
    options,
  ));
}

async function $do(
  client: IamClientCore,
  request: operations.GetAgreementsListRequest,
  options?: RequestOptions,
): Promise<
  [
    Result<
      components.AgreementsResponse,
      | errors.ErrDetails
      | IamClientError
      | ResponseValidationError
      | ConnectionError
      | RequestAbortedError
      | RequestTimeoutError
      | InvalidRequestError
      | UnexpectedClientError
      | SDKValidationError
    >,
    APICall,
  ]
> {
  const parsed = safeParse(
    request,
    (value) => operations.GetAgreementsListRequest$outboundSchema.parse(value),
    "Input validation failed",
  );
  if (!parsed.ok) {
    return [parsed, { status: "invalid" }];
  }
  const payload = parsed.value;
  const body = null;

  const pathParams = {
    accountId: encodeSimple("accountId", payload.accountId, {
      explode: false,
      charEncoding: "percent",
    }),
  };
  const path = pathToFunc("/v1/accounts/{accountId}/agreements")(pathParams);

  const query = encodeFormQuery({
    "$filter": payload.$filter,
    "$search": payload.$search,
    "ctoken": payload.ctoken,
    "direction": payload.direction,
    "document_id": payload.document_id,
    "id": payload.id,
    "include_linked_data": payload.include_linked_data,
    "languages": payload.languages,
    "limit": payload.limit,
    "metadata.created_at": payload["metadata.created_at"],
    "parties.name_in_agreement": payload["parties.name_in_agreement"],
    "provisions.effective_date": payload["provisions.effective_date"],
    "provisions.execution_date": payload["provisions.execution_date"],
    "provisions.expiration_date": payload["provisions.expiration_date"],
    "provisions.term_length": payload["provisions.term_length"],
    "related_agreement_documents.parent_agreement_document_id":
      payload["related_agreement_documents.parent_agreement_document_id"],
    "review_completed_at": payload.review_completed_at,
    "review_status": payload.review_status,
    "sort": payload.sort,
    "source_id": payload.source_id,
    "source_name": payload.source_name,
    "status": payload.status,
    "title": payload.title,
  });

  const headers = new Headers(compactMap({
    Accept: "application/json",
  }));

  const secConfig = await extractSecurity(client._options.accessToken);
  const securityInput = secConfig == null ? {} : { accessToken: secConfig };
  const requestSecurity = resolveGlobalSecurity(securityInput, [0]);

  const context = {
    options: client._options,
    baseURL: options?.serverURL ?? client._baseURL ?? "",
    operationID: "GetAgreementsList",
    oAuth2Scopes: null,

    resolvedSecurity: requestSecurity,

    securitySource: client._options.accessToken,
    retryConfig: options?.retries
      || client._options.retryConfig
      || {
        strategy: "backoff",
        backoff: {
          initialInterval: 500,
          maxInterval: 5000,
          exponent: 1.5,
          maxElapsedTime: 30000,
        },
        retryConnectionErrors: true,
      }
      || { strategy: "none" },
    retryCodes: options?.retryCodes || ["5XX", "429"],
  };

  const requestRes = client._createRequest(context, {
    security: requestSecurity,
    method: "GET",
    baseURL: options?.serverURL,
    path: path,
    headers: headers,
    query: query,
    body: body,
    userAgent: client._options.userAgent,
    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
  }, options);
  if (!requestRes.ok) {
    return [requestRes, { status: "invalid" }];
  }
  const req = requestRes.value;

  const doResult = await client._do(req, {
    context,
    isErrorStatusCode: (statusCode: number) =>
      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
    retryConfig: context.retryConfig,
    retryCodes: context.retryCodes,
  });
  if (!doResult.ok) {
    return [doResult, { status: "request-error", request: req }];
  }
  const response = doResult.value;

  const responseFields = {
    HttpMeta: { Response: response, Request: req },
  };

  const [result] = await M.match<
    components.AgreementsResponse,
    | errors.ErrDetails
    | IamClientError
    | ResponseValidationError
    | ConnectionError
    | RequestAbortedError
    | RequestTimeoutError
    | InvalidRequestError
    | UnexpectedClientError
    | SDKValidationError
  >(
    M.json(200, components.AgreementsResponse$inboundSchema),
    M.jsonErr([400, 403, 404], errors.ErrDetails$inboundSchema, {
      ctype: "application/problem+json",
    }),
    M.jsonErr(500, errors.ErrDetails$inboundSchema, {
      ctype: "application/problem+json",
    }),
    M.fail([401, "4XX"]),
    M.fail("5XX"),
  )(response, req, { extraFields: responseFields });
  if (!result.ok) {
    return [result, { status: "complete", request: req, response }];
  }

  return [result, { status: "complete", request: req, response }];
}