OpenMax
Free Trial

Card verdicts

classifyCardActionError, cardStateFromSubmit and formAnswersBody: failure verdicts, settled records and form-answer bodies for card submissions.

Card verdicts

Three pure functions for card submissions (business-card actions, settling a choice card, and the unified POST /api/v1/messages/{id}/card-interactions): how a failure is judged, how a successful response becomes the settled record, and how form-card answers go into the request body. Use them when you write your own host against OpenMax, so you judge failures and send exactly what the SDK does. Status and an index of every export are on the Overview.

Failure verdicts

Verdicts use the vocabulary of the @openmaxai/chat contract: kind is the kind of the failure branch of ChatCardActionResult. Each app maps kind to its own copy; nothing here produces copy.

Input kind stage New key Business data may have changed
code is network or timeout (status ignored) unavailable transport No Yes
COMM_CARD_IDEMPOTENCY_KEY_REUSED idempotency-key-reused parse Yes No
COMM_CARD_OPERATION_RETIRED / COMM_CARD_SUPERSEDED / COMM_CARD_INTERACTION_WINDOW_EXPIRED operation-retired / superseded / window-expired parse No No
Any other code starting with COMM_ By status (below) parse No No
No COMM_ code, status 0 or 5xx unavailable transport No Yes
WORK_ISSUE_ACCEPTANCE_FORBIDDEN business-forbidden business No Yes
Any other code By status business No Yes
No code (or an empty one) By status unknown No No

By status: 0 and 5xx are unavailable, 400 action-invalid, 403 forbidden, 404 not-found, 409 conflict, 412 precondition, 429 rate-limited, anything else unknown.

Branching goes by error code, not status: 403, 409 and 412 mean different things on the two sides (412 is used both for "message recalled" and for "issue not awaiting confirmation"). The only failure that calls for a new idempotency key is the fingerprint-mismatch code; network errors, timeouts and business rejections all keep the key, because a new key would bypass deduplication on the business side.

401, status 0 and 5xx are just one verdict here, with no distinction between expired credentials and transport failures. To route expired credentials to onUnauthorized, split them off before calling this.

classifyCardActionError

function classifyCardActionError(error: {
  status: number;
  code?: string;
  field?: string;
  detail?: string;
}): OpenMaxCardErrorVerdict;

The status and error code of a failed card submission ⇒ a verdict, by the table above. Exceptions that are not HTTP failures (bugs, aborted requests) have no status to judge by; the caller handles them.

OpenMaxCardErrorVerdict

interface OpenMaxCardErrorVerdict {
  kind: ChatCardActionErrorKind;
  stage: OpenMaxCardErrorStage;
  resetIdempotencyKey: boolean;
  businessMayHaveChanged: boolean;
  formError?: ChatCardFormError;
}

What classifyCardActionError returns. kind and resetIdempotencyKey are the contract verdict { ok: false, kind, resetIdempotencyKey } as they are; when businessMayHaveChanged is true, invalidate the business data linked to the card's operation. When a form card is rejected for its content (COMM_CARD_FORM_*) it also carries formError: which kind, which question (from the error envelope's field path), and, when blocked by the filter, the server's refusal text (from detail); put it into the contract verdict as is.

OpenMaxCardErrorStage

type OpenMaxCardErrorStage =
  | "parse"
  | "business"
  | "transport"
  | "unknown";

Which hop the failure happened on: parse is the server's parsing hop (the business service was never called), business is the business service's verdict, transport is the transport layer and 5xx (a client-side error while the business call went through is the normal failure mode of this chain, so business data may have changed too), and unknown means there was no code to branch on.

cardStateFromSubmit

function cardStateFromSubmit(result: OpenMaxCardSubmitResult | undefined, input: {
  interactionType: "choice";
} | {
  interactionType: "form";
} | {
  interactionType: "action";
  actionId: string;
}, currentMemberId: string | undefined): OpenMaxCardStateRecord | null;

Builds the card's settled record from the submit response; when it can't be built in full it returns null, and the caller reloads the message instead:

  • replayed is not false (a retry, or someone else answered first) or result_at is missing: null.
  • choice: with exactly one selected id and a currentMemberId, action_id is that id and the answerer is the current member.
  • action: with a currentMemberId, action_id is the one in the response, or the clicked one when there is none; the answerer is the current member.
  • form: with both actor_id and answers in the response, action_id is form_submit and the answers go into form_answers; if either is missing it returns null rather than render a partial list.

OpenMaxCardSubmitResult

interface OpenMaxCardSubmitResult {
  interaction_id: string;
  interaction_type: "choice" | "form" | "action";
  change_seq: number;
  card_sender?: {
    kind: string;
    member_id: string;
  };
  replayed: boolean;
  result_at: string;
  status: string;
  action_id?: string;
  actor_id?: string;
  answers?: {
    [key: string]: OpenMaxCardFormAnswerRecord;
  };
  selected_action_ids?: string[] | null;
}

The data of the submit endpoint (POST /api/v1/messages/{id}/card-interactions), same shape as the backend contract; pass the response straight into cardStateFromSubmit.

OpenMaxCardStateRecord

interface OpenMaxCardStateRecord {
  action_id: string;
  actor_id: string;
  form_answers?: {
    [key: string]: OpenMaxCardFormAnswerRecord;
  };
  result_at: string;
  status: string;
}

A card's settled record, same shape as card_state on the message; what cardStateFromSubmit returns.

OpenMaxCardFormAnswerRecord

interface OpenMaxCardFormAnswerRecord {
  selected_option_ids: string[] | null;
  other_text?: string;
  text?: string;
}

One question's settled answer on a form card: the values of answers in the submit response and of form_answers in the settled record.

formAnswersBody

function formAnswersBody(answers: Readonly<Record<string, ChatCardFormAnswer>>): Record<string, {
  selected_option_ids?: string[];
  other_text?: string;
  text?: string;
}>;

Form-card answers ⇒ form.answers in the request body, field names in snake_case, each field only when given: selectedOptionIds becomes selected_option_ids; otherText becomes other_text, including an empty string (ticking "Other" without writing anything is not the same as not ticking it); a text question's text is sent as text, with no selected_option_ids (the server rejects option ids on a text question).