feat: add new endpoints for AppActionCall to fetch structured results [EXT-6593]

[lewisjcs]

Summary

Add structured App Action Call support and a convenient polling-abstracting method:

• New REST endpoints: get (structured call), getResponse (raw response), createWithResult (create + poll).
• Plain client API exposure with JSDocs for the new structured/response flows.
• Default client methods added for structured flow and raw response.
• Types updated to model status/result/error per RFC.
• Unit and integration tests for success, timeout, failure, transient error and endpoint paths.

Description

Types

• Extend AppActionCallProps with:
  • status: 'processing' | 'succeeded' | 'failed'
  • result?: unknown
  • error?: { sys: { type: 'Error'; id: string }, message: string, details?: Record<string, unknown>, statusCode?: number }
• Extend AppActionCallSys with appActionCallResponse?: SysLink.
• Add AppActionCallRawResponseProps (raw headers/body envelope).
• Update CreateAppActionCallProps.parameters to { [key: string]: unknown }.

REST adapter (lib/adapters/REST/endpoints/app-action-call.ts)

• get: GET new route (includes app installation id) returning structured AppActionCall:
  /spaces/{spaceId}/environments/{environmentId}/app_installations/{appDefinitionId}/actions/{appActionId}/calls/{callId}
• getResponse: GET raw response for a call:
  /spaces/{spaceId}/environments/{environmentId}/app_installations/{appDefinitionId}/actions/{appActionId}/calls/{callId}/response
• createWithResult: POST create + poll get until terminal status, returning completed AppActionCall.
  • Default retry policy: 15 retries, 2000ms interval; overridable via retries/retryInterval.
  • Transient GET errors (e.g., propagation/404) re-poll; terminal 4xx/5xx in nested response stop polling.

Common types (lib/common-types.ts)

• Add GetAppActionCallParamsWithId (new route includes callId).
• Add/extend CreateWithResponseParams with optional retries and retryInterval.
• Extend MRActions/MRInternal overloads for:
  • AppActionCall.get, AppActionCall.getResponse, AppActionCall.createWithResult.

Plain client (lib/plain/entities/app-action-call.ts, lib/plain/plain-client.ts)

• Add methods (with JSDocs and examples):
  • get(params): Promise<AppActionCallProps>
  • createWithResult(params, payload): Promise<AppActionCallProps>
  • getResponse(params): Promise<AppActionCallRawResponseProps>
• Existing create, getCallDetails, createWithResponse remain available.

Default client

• Entity API (lib/entities/app-action-call.ts)
  • Add methods:
    • get(): Promise<AppActionCallProps>
    • createWithResult(): Promise<AppActionCallProps>
  • Existing createWithResponse() and getCallDetails() remain available.
• Environment API (lib/create-environment-api.ts)
  • Add getAppActionCallResponse(appDefinitionId, appActionId, callId): Promise<AppActionCallRawResponseProps>
    • Calls makeRequest({ entityType: 'AppActionCall', action: 'getResponse', ... }).

Exports (lib/export-types.ts)

• Export new public types:
  • AppActionCallErrorProps
  • AppActionCallRawResponseProps
  • AppActionCallStatus

Tests

• Unit tests covering:
  • Success path (processing → succeeded)
  • Failure path (failed with structured error)
  • Timeout when status remains processing
  • Thrown GET errors leading to timeout
  • Correct paths for new endpoints (get, getResponse) and polling
  • Default client environment method: getAppActionCallResponse calls correct endpoint
• Integration tests for the structured flow (test/integration/app-action-call-structured-integration.test.ts)
  • Includes increased retries/intervals and retry loop for get to handle eventual consistency
  • Configures AppSigningSecret and creates an AppAction to satisfy backend requirements

Motivation and Context

• Jira:
  • Convenient SDK Method for App Action Results — EXT-6593
  • Convenient SDK Method for Raw Response — EXT-6735

This change provides a simple, predictable way for developers and Automations/Workflows to invoke App Actions and work with structured outcomes without manual polling, and to retrieve the raw executor response when needed.

Checklist (check all before merging)

• Both unit and integration tests are passing
• There are no breaking changes (changes are additive; legacy methods remain)
• Changes are reflected in the documentation
  • JSDocs added to public methods in this repo
  • API blueprint and developer docs updated in doc-app (separate PR to be opened)

When adding a new method:

• The new method is exported through the default and plain CMA client
  • Plain client: get, createWithResult, getResponse
  • Default client (entity API): get, createWithResult
  • Default client (environment API): getAppActionCallResponse
• All new public types are exported from ./lib/export-types.ts
  • AppActionCallRawResponseProps, AppActionCallErrorProps, AppActionCallStatus
• Added a unit test for the new method(s)
• Added an integration test for the structured-flow method(s)
• The new method(s) are added to the documentation
  • Developer docs and API blueprint prepared in doc-app; to be merged separately

[chasepoirier]

Code looks good 🚀

We'll continue to look into the integration test failures related to taxonomies as it seems it's affected master right now too. Otherwise, sounds like a good plan to merge this after the improved app actions are live on prod!

[contentful-automation]

🎉 This PR is included in version 11.55.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀