@docusign/iam-sdk/src/models/components/affordance.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 { remap as remap$ } from "../../lib/primitives.js";
import { safeParse } from "../../lib/schemas.js";
import { ClosedEnum } from "../../types/enums.js";
import { Result as SafeParseResult } from "../../types/fp.js";
import * as types from "../../types/primitives.js";
import { SDKValidationError } from "../errors/sdkvalidationerror.js";

/**
 * The http method to use when invoking this affordance
 */
export const AffordanceMethod = {
  Post: "POST",
  Get: "GET",
  Patch: "PATCH",
  Put: "PUT",
  Delete: "DELETE",
} as const;
/**
 * The http method to use when invoking this affordance
 */
export type AffordanceMethod = ClosedEnum<typeof AffordanceMethod>;

/**
 * Affordances (aka 'actions') describe the available operations on a resource, including CRUD and RPC-like operations. It details the
 *
 * @remarks
 * expected input payload, http method, query parameters, and the resulting output.
 *
 * Affordances enable clients to dynamically adapt to the API's current state and available actions. Instead of
 * hardcoding all possible endpoints and their associated logic, a client can inspect the affordances within a
 * resource's representation to discover what actions are possible and how to perform them.
 */
export type Affordance = {
  href?: string | null | undefined;
  /**
   * The http method to use when invoking this affordance
   */
  method?: AffordanceMethod | undefined;
  /**
   * Indicates if an action must be performed on a resource. This may include a manadatory step as part of a business process, especially
   *
   * @remarks
   * when failing to execute a subsequent action will leave the resource in a bad or incomplete state.
   * # note: would it be necessary for manadatory/required actionsto be performed prior to an optional action
   * # note: mandatory actions which have previously been executed on a resource should not be be returned in the server response
   * # execept in cases where the resource is in a state that permits this action to be performed again.
   */
  required: boolean;
  /**
   * Provides a stable and consistent order to a collection of resources. Useful when multiple processes are working in parallel to iterate over
   *
   * @remarks
   * a collection of resources with a mandatory/required action.
   */
  sequence?: number | undefined;
  /**
   * Placeholder
   */
  description?: string | undefined;
  /**
   * A natural language dictionary of JSON template variables used in invoke an action
   *
   * @remarks
   */
  templateVariables?: { [k: string]: string } | undefined;
  /**
   * Additional HTTP request headers needed in the request to invoke an action.
   *
   * @remarks
   */
  headers?: { [k: string]: string } | undefined;
  /**
   * Limits and restrictions on
   *
   * @remarks
   */
  constraints?: any | undefined;
  /**
   * Success status codes (2xx range) indicating the request was received,
   *
   * @remarks
   * understood, and accepted.
   * Common codes:
   * - 200: OK - Standard successful response
   * - 201: Created - Resource successfully created
   * - 202: Accepted - Request accepted for processing
   * - 204: No Content - Successful with no response body
   * - 206: Partial Content - Partial resource returned
   */
  successStatusCode?: number | undefined;
};

/** @internal */
export const AffordanceMethod$inboundSchema: z.ZodNativeEnum<
  typeof AffordanceMethod
> = z.nativeEnum(AffordanceMethod);

/** @internal */
export const Affordance$inboundSchema: z.ZodType<
  Affordance,
  z.ZodTypeDef,
  unknown
> = z.object({
  href: z.nullable(types.string()).optional(),
  method: types.optional(AffordanceMethod$inboundSchema),
  required: types.boolean().default(false),
  sequence: types.optional(types.number()),
  description: types.optional(types.string()),
  template_variables: types.optional(z.record(types.string())),
  headers: types.optional(z.record(types.string())),
  constraints: types.optional(z.any()),
  success_status_code: types.optional(types.number()),
}).transform((v) => {
  return remap$(v, {
    "template_variables": "templateVariables",
    "success_status_code": "successStatusCode",
  });
});

export function affordanceFromJSON(
  jsonString: string,
): SafeParseResult<Affordance, SDKValidationError> {
  return safeParse(
    jsonString,
    (x) => Affordance$inboundSchema.parse(JSON.parse(x)),
    `Failed to parse 'Affordance' from JSON`,
  );
}