@whooshbang/contracts 1.0.0-rc.13

package/schemas/interaction-v1.schema.json

@@ -0,0 +1,483 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://whooshbang.flowxo.com/schemas/interaction-v1.schema.json",
+  "x-contract-version": "1.0.0-rc.13",
+  "title": "InteractionV1ContractDocument",
+  "description": "Provider-neutral confirm, single-select, input, lifecycle, callback-token, and authenticated answer-event contracts.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/InteractionRequest"
+    },
+    {
+      "$ref": "#/$defs/InteractionSummary"
+    },
+    {
+      "$ref": "#/$defs/InteractionEvent"
+    },
+    {
+      "$ref": "#/$defs/ProviderCallbackToken"
+    }
+  ],
+  "$defs": {
+    "OpaqueIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+      "description": "An opaque identifier whose internal encoding is not a public promise."
+    },
+    "Timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\\.[0-9]+)?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$"
+    },
+    "InteractionCorrelationId": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 128,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+      "description": "Caller-owned opaque correlation returned as data, never treated as execution authority."
+    },
+    "InteractionPrompt": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000
+    },
+    "InteractionOption": {
+      "type": "object",
+      "required": ["value", "label"],
+      "properties": {
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+          "description": "Opaque customer data. It is never interpreted as a command."
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConfirmInteractionRequest": {
+      "type": "object",
+      "required": ["type", "prompt", "expires_at"],
+      "properties": {
+        "type": {
+          "const": "confirm"
+        },
+        "prompt": {
+          "$ref": "#/$defs/InteractionPrompt"
+        },
+        "confirm_label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40
+        },
+        "deny_label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "Must be 30 seconds through 24 hours after server acceptance."
+        },
+        "correlation_id": {
+          "$ref": "#/$defs/InteractionCorrelationId"
+        }
+      },
+      "additionalProperties": false
+    },
+    "SelectInteractionRequest": {
+      "type": "object",
+      "required": ["type", "prompt", "options", "expires_at"],
+      "properties": {
+        "type": {
+          "const": "select"
+        },
+        "prompt": {
+          "$ref": "#/$defs/InteractionPrompt"
+        },
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 6,
+          "items": {
+            "$ref": "#/$defs/InteractionOption"
+          },
+          "x-unique-property": "value"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "Must be 30 seconds through 24 hours after server acceptance."
+        },
+        "correlation_id": {
+          "$ref": "#/$defs/InteractionCorrelationId"
+        }
+      },
+      "additionalProperties": false
+    },
+    "InputInteractionRequest": {
+      "type": "object",
+      "required": ["type", "prompt", "expires_at"],
+      "properties": {
+        "type": {
+          "const": "input"
+        },
+        "prompt": {
+          "$ref": "#/$defs/InteractionPrompt"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "Must be 30 seconds through 24 hours after server acceptance."
+        },
+        "correlation_id": {
+          "$ref": "#/$defs/InteractionCorrelationId"
+        }
+      },
+      "additionalProperties": false
+    },
+    "InteractionRequest": {
+      "description": "A required-type tagged union. C0 supports confirm, single-select, and input only.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/ConfirmInteractionRequest"
+        },
+        {
+          "$ref": "#/$defs/SelectInteractionRequest"
+        },
+        {
+          "$ref": "#/$defs/InputInteractionRequest"
+        }
+      ]
+    },
+    "InteractionState": {
+      "type": "string",
+      "enum": ["open", "answered", "expired", "cancelled", "retired"]
+    },
+    "InteractionSummary": {
+      "type": "object",
+      "description": "The hosted interaction identity and first-terminal-writer state.",
+      "required": ["id", "type", "state", "expires_at"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["confirm", "select", "input"]
+        },
+        "state": {
+          "$ref": "#/$defs/InteractionState"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "correlation_id": {
+          "$ref": "#/$defs/InteractionCorrelationId"
+        },
+        "answered_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "answer_retained": {
+          "type": "boolean",
+          "description": "Whether the typed answer remains available inside its content-retention window. False preserves the answered terminal fact after answer deletion."
+        },
+        "answer": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4000
+            }
+          ]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "state": {
+                "const": "answered"
+              }
+            },
+            "required": ["state"]
+          },
+          "then": {
+            "required": ["answered_at", "answer_retained"],
+            "properties": {
+              "answered_at": {},
+              "answer_retained": {},
+              "answer": {}
+            },
+            "allOf": [
+              {
+                "if": {
+                  "properties": {
+                    "answer_retained": {
+                      "const": true
+                    }
+                  },
+                  "required": ["answer_retained"]
+                },
+                "then": {
+                  "required": ["answer"],
+                  "properties": {
+                    "answer": {}
+                  }
+                },
+                "else": {
+                  "properties": {
+                    "answer": false
+                  }
+                }
+              }
+            ]
+          },
+          "else": {
+            "properties": {
+              "answered_at": false,
+              "answer_retained": false,
+              "answer": false
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "confirm"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "answer": {
+                "type": "boolean"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "select"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "answer": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "input"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "answer": {
+                "$ref": "#/$defs/TrimmedInputAnswer"
+              }
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "ConfirmInteractionResponse": {
+      "type": "object",
+      "required": ["type", "value"],
+      "properties": {
+        "type": {
+          "const": "confirm"
+        },
+        "value": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "SelectInteractionResponse": {
+      "type": "object",
+      "required": ["type", "value"],
+      "properties": {
+        "type": {
+          "const": "select"
+        },
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "TrimmedInputAnswer": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "pattern": "^\\S(?:[\\s\\S]*\\S)?$",
+      "description": "Untrusted input text after leading and trailing whitespace is removed."
+    },
+    "InputInteractionResponse": {
+      "type": "object",
+      "required": ["type", "value"],
+      "properties": {
+        "type": {
+          "const": "input"
+        },
+        "value": {
+          "$ref": "#/$defs/TrimmedInputAnswer"
+        }
+      },
+      "additionalProperties": false
+    },
+    "InteractionResponse": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/ConfirmInteractionResponse"
+        },
+        {
+          "$ref": "#/$defs/SelectInteractionResponse"
+        },
+        {
+          "$ref": "#/$defs/InputInteractionResponse"
+        }
+      ]
+    },
+    "SafeChannelContext": {
+      "type": "object",
+      "required": ["binding_id", "channel", "conversation_kind"],
+      "properties": {
+        "binding_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "channel": {
+          "const": "telegram"
+        },
+        "conversation_kind": {
+          "type": "string",
+          "enum": ["private_chat", "thread", "group"]
+        },
+        "display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        }
+      },
+      "additionalProperties": false
+    },
+    "InteractionEvent": {
+      "type": "object",
+      "description": "An authenticated, immutable human-answer fact. It is data for the consumer and never a command or proof of business success.",
+      "required": [
+        "schema",
+        "id",
+        "cursor",
+        "type",
+        "message_id",
+        "interaction_id",
+        "channel_context",
+        "occurred_at",
+        "expires_at"
+      ],
+      "properties": {
+        "schema": {
+          "const": "whooshbang.interaction-event.v1"
+        },
+        "id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "cursor": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 128,
+          "pattern": "^mcur_[A-Za-z0-9_-]+$",
+          "description": "The opaque position of this event in the authenticated machine stream."
+        },
+        "type": {
+          "const": "interaction.received"
+        },
+        "message_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "interaction_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "correlation_id": {
+          "$ref": "#/$defs/InteractionCorrelationId"
+        },
+        "response": {
+          "$ref": "#/$defs/InteractionResponse"
+        },
+        "answer_retained": {
+          "type": "boolean",
+          "description": "False means the content window closed and response was removed. New retained events publish true; a retained legacy event may omit this member during rolling deployment."
+        },
+        "channel_context": {
+          "$ref": "#/$defs/SafeChannelContext"
+        },
+        "occurred_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "answer_retained": {
+                "const": false
+              }
+            },
+            "required": ["answer_retained"]
+          },
+          "then": {
+            "properties": {
+              "response": false
+            }
+          },
+          "else": {
+            "properties": {
+              "response": {
+                "$ref": "#/$defs/InteractionResponse"
+              }
+            },
+            "required": ["response"]
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "ProviderCallbackToken": {
+      "type": "string",
+      "pattern": "^itok_[A-Za-z0-9_-]{21}[AQgw]$",
+      "description": "An opaque single-purpose reference containing exactly 128 random bits and no trusted identity, answer, command, or business data."
+    }
+  }
+}