@docusign/iam-sdk/src/funcs/agreementManagerAgreementsPatchAgreementByDocumentId.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 * as z from "zod/v3";
import { IamClientCore } from "../core.js";
import { encodeFormQuery, encodeJSON, 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 {
  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";

/**
 * Update an agreement by locating it via document ID
 *
 * @remarks
 * This operation updates a specific agreement by first locating it using its associated `document_id`.
 * This is useful when the client knows the document storage identifier but not the agreement ID.
 *
 * The operation accepts a `document_id` query parameter to uniquely identify the agreement, then applies the partial updates specified in the request body.
 * The system will search for an agreement containing the specified document ID, and if found, apply the requested modifications.
 * The operation returns a `204 No Content` response on success.
 *
 * This endpoint provides an alternative way to update agreements when the agreement ID is not readily available, making it convenient for systems that primarily work with document references rather than agreement identifiers.
 *
 * ### Use Cases:
 * - **Updating agreements referenced by document storage ID**: When integration points provide document IDs but not agreement IDs, this endpoint allows direct updates without a prior lookup.
 * - **Batch updating via external document references**: Systems that track agreements through external document management systems can update agreements using their document storage identifiers.
 * - **Cross-system synchronization**: Update agreements based on document references from external systems (e.g., content management systems, document repositories) without maintaining agreement ID mappings.
 * - **Document-centric workflows**: In document-first business processes, update agreements using the document reference that users are familiar with.
 *
 * ### Key Features:
 * - **Document ID Based Lookup**: Locate agreements by their associated document storage identifier rather than requiring the agreement ID upfront.
 * - **Automatic Resolution**: The system automatically finds the agreement associated with the provided document ID.
 * - **Partial Updates**: Modify only the fields you need; other agreement data remains unchanged.
 *
 * If set, this operation will use {@link Security.accessToken} from the global security.
 */
export function agreementManagerAgreementsPatchAgreementByDocumentId(
  client: IamClientCore,
  request: operations.PatchAgreementByDocumentIdRequest,
  options?: RequestOptions,
): APIPromise<
  Result<
    void,
    | errors.ErrDetails
    | IamClientError
    | ResponseValidationError
    | ConnectionError
    | RequestAbortedError
    | RequestTimeoutError
    | InvalidRequestError
    | UnexpectedClientError
    | SDKValidationError
  >
> {
  return new APIPromise($do(
    client,
    request,
    options,
  ));
}

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

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

  const query = encodeFormQuery({
    "document_id": payload.document_id,
  });

  const headers = new Headers(compactMap({
    "Content-Type": "application/json",
    Accept: "application/problem+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: "PatchAgreementByDocumentId",
    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: "PATCH",
    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<
    void,
    | errors.ErrDetails
    | IamClientError
    | ResponseValidationError
    | ConnectionError
    | RequestAbortedError
    | RequestTimeoutError
    | InvalidRequestError
    | UnexpectedClientError
    | SDKValidationError
  >(
    M.nil(204, z.void()),
    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 }];
}