From 30eb754657c4575fda6942c7c733587cf1e116e9 Mon Sep 17 00:00:00 2001
From: Alexey Tsymbal <tsymbal.aleksey@gmail.com>
Date: Thu, 1 Aug 2024 18:16:08 +0300
Subject: [PATCH] more strict definition for next action

---
 packages/actions-spec/index.d.ts | 79 ++++++++++++++++++++++++++++++--
 1 file changed, 75 insertions(+), 4 deletions(-)

diff --git a/packages/actions-spec/index.d.ts b/packages/actions-spec/index.d.ts
index 8ab230f..bc6e76f 100644
--- a/packages/actions-spec/index.d.ts
+++ b/packages/actions-spec/index.d.ts
@@ -42,9 +42,24 @@ export interface ActionRuleObject {
 export interface ActionGetRequest {}
 
 /**
- * Response body payload returned from the Action GET Request
+ * Type of action to determine client side handling
  */
-export interface ActionGetResponse {
+export type ActionType = "action" | "completed";
+
+/**
+ * Response body payload returned from the initial Action GET Request
+ */
+export interface ActionGetResponse extends Omit<Action, "type"> {
+  type?: "action";
+}
+
+/**
+ * A single Solana Action
+ */
+export interface Action<T extends ActionType = "action"> {
+  /** @default `action` */
+  /** type of Action to present to the user */
+  type: T;
   /** image url that represents the source of the action request */
   icon: string;
   /** describes the source of the action request */
@@ -111,8 +126,8 @@ export interface ActionParameter<T extends ActionParameterType, M = MinMax<T>> {
 type MinMax<T extends ActionParameterType> = T extends "date" | "datetime-local"
   ? string
   : T extends "radio" | "select"
-  ? never
-  : number;
+    ? never
+    : number;
 
 type GeneralParameterType =
   | "text"
@@ -172,6 +187,62 @@ export interface ActionPostResponse {
   transaction: string;
   /** describes the nature of the transaction */
   message?: string;
+  links?: {
+    /**
+     * The next action in a successive chain of actions to be obtained after the previous was successful.
+     */
+    next: NextActionLink;
+  };
+}
+
+/**
+ * Represents a link to the next action to be performed.
+ * The next action can be either a POST request to a callback URL or an inline action.
+ *
+ * @see PostNextActionLink
+ * @see InlineNextActionLink
+ */
+export type NextActionLink = PostNextActionLink | InlineNextActionLink;
+
+/**
+ * Represents a POST request link to the next action.
+ *
+ * This is a same origin callback URL used to fetch the next action in the chain.
+ * - This callback URL will receive a POST request with a body of `NextActionPostRequest`.
+ * - It should respond with a `NextAction`.
+ */
+export interface PostNextActionLink {
+  /** Indicates the type of the link. */
+  type: "post";
+  /** Relative or same origin URL to which the POST request should be made. */
+  href: string;
+}
+
+/**
+ * Represents an inline next action embedded within the current context.
+ */
+export interface InlineNextActionLink {
+  /** Indicates the type of the link. */
+  type: "inline";
+  /** The next action to be performed */
+  action: NextAction;
+}
+
+/** The completed action, used to declare the "completed" state within action chaining. */
+export type CompletedAction = Omit<Action<"completed">, "links">;
+
+/** The next action to be performed */
+export type NextAction = Action<"action"> | CompletedAction;
+
+/**
+ * Response body payload sent via POST request to obtain the next action
+ * in a successive chain of actions
+ *
+ * @see {@link NextAction} should be returned as the POST response
+ */
+export interface NextActionPostRequest extends ActionPostRequest {
+  /** signature produced from the previous action (either a transaction id or message signature) */
+  signature: string;
 }
 
 /**