khoros-aurora-sdk 26.2.0 → 26.3.0

package/build-hash.txt

@@ -1 +1 @@
-dfcfbdc
+5f02757

package/graphql/aiAnswerLogSchema.graphqls

@@ -79,6 +79,15 @@ type AiAnswerLog {
   "Citation coverage ratio (0.0-1.0) - citations used divided by citations provided."
   citationCoverage: Float
 
+  "Number of KB article citations provided to the LLM."
+  sourceKbCount: Int
+
+  "Number of blog article citations provided to the LLM."
+  sourceBlogCount: Int
+
+  "Number of forum reply citations provided to the LLM."
+  sourceForumCount: Int
+
   "Reasons why AI answer was not generated (can be multiple)."
   noAnswerReasons: [String!]
 

package/graphql/clarificationSchema.graphqls

@@ -0,0 +1,234 @@
+# Clarification Questions - Generic Thread Response Collection
+# KCOMM-484
+
+type ThreadResponseCollection {
+    id: ID!
+    messageUid: Int!
+    boardUid: Int!
+    collectionType: String!
+    status: CollectionStatus!
+    questionText: String
+    createdBy: Int!
+    completedAt: String
+    expiresAt: String
+    createdAt: String!
+    updatedAt: String
+    messageTitle: String
+    boardName: String
+    authorName: String
+    items: [ThreadResponseItem!]!
+}
+
+type ThreadResponseItem {
+    id: ID!
+    collectionId: ID!
+    itemText: String!
+    itemType: String!
+    answerOptions: [String!]
+    isRequired: Boolean!
+    displayOrder: Int!
+    source: String!
+    response: ThreadResponse
+}
+
+type ThreadResponse {
+    id: ID!
+    itemId: ID!
+    respondentUid: Int
+    responseText: String
+    selectedOptions: [Int!]
+    skipped: Boolean!
+    moderationStatus: String!
+    rejectReason: String
+    moderatedBy: String
+    respondedAt: String!
+}
+
+type ClarificationGuidanceExample {
+    id: ID!
+    boardUid: Int!
+    exampleText: String!
+    isRequired: Boolean!
+    displayOrder: Int!
+    enabled: Boolean!
+    createdAt: String!
+}
+
+enum CollectionStatus {
+    PENDING
+    ACTIVE
+    COMPLETED
+    SKIPPED
+    ABANDONED
+}
+
+type ClarificationWorkflowResponse {
+    collection: ThreadResponseCollection
+    success: Boolean!
+    errorMessage: String
+}
+
+type ClarificationWorkflowListResponse {
+    collections: [ThreadResponseCollection!]!
+    totalCount: Int!
+}
+
+type ClarificationMetrics {
+    completionRate: Float!
+    skipRate: Float!
+    avgQuestionsAsked: Float!
+    totalWorkflows: Int!
+    emailPromptRate: Float!
+}
+
+type ClarificationGuidanceExampleResponse {
+    example: ClarificationGuidanceExample
+    success: Boolean!
+    errorMessage: String
+}
+
+type BoardClarificationSummary {
+    nodeId: ID!
+    boardUid: Int!
+    boardTitle: String!
+    conversationStyle: String!
+    enabled: Boolean!
+}
+
+type ClarificationSettings {
+    globalEnabled: Boolean!
+    enabled: Boolean!
+    maxQuestions: Int!
+    showInfoBanner: Boolean!
+    infoBannerText: String!
+    reminderEmailDelay: Int!
+    allowSkip: Boolean!
+}
+
+input ClarificationSettingsInput @validationDefaults(prefix: "clarification_settings") {
+    globalEnabled: Boolean @validation(key: "global_enabled")
+    enabled: Boolean @validation(key: "enabled")
+    maxQuestions: Int @validation(key: "max_questions")
+    showInfoBanner: Boolean @validation(key: "show_info_banner")
+    infoBannerText: String @validation(key: "info_banner_text")
+    reminderEmailDelay: Int @validation(key: "reminder_email_delay")
+    allowSkip: Boolean @validation(key: "allow_skip")
+}
+
+type ClarificationSettingsResult {
+    success: Boolean!
+    errorMessage: String
+}
+
+extend type Query {
+    "Get clarification workflow for a specific post"
+    clarificationWorkflow(messageUid: Int!): ClarificationWorkflowResponse
+
+    "List all clarification workflows for review queue"
+    clarificationWorkflows(
+        boardUid: Int
+        status: CollectionStatus
+        createdAfter: String
+        createdBefore: String
+        offset: Int
+        limit: Int
+    ): ClarificationWorkflowListResponse
+
+    "Get CM guidance examples for a board"
+    clarificationGuidanceExamples(nodeId: ID!): [ClarificationGuidanceExample!]
+
+    "Check if clarification is enabled for a board"
+    isClarificationEnabled(boardUid: Int!): Boolean
+
+    "Get clarification metrics for the review queue"
+    clarificationMetrics(boardUid: Int): ClarificationMetrics
+
+    "Get clarification settings for a board (takes GraphQL node ID like 'board:forum-name')"
+    clarificationSettings(nodeId: ID!): ClarificationSettings
+
+    "Get clarification enabled status for all eligible boards (Forum/Idea)"
+    allBoardClarificationSettings: [BoardClarificationSummary!]
+
+    "Get formatted clarification questions text for a message (used by Flow template variable resolution)"
+    clarificationQuestionsText(messageUid: Int!): String
+
+    "Get clarification responses for moderation dashboard"
+    clarificationResponsesForModeration(
+        status: String
+        rejectReason: String
+        boardUid: Int
+        offset: Int
+        limit: Int
+    ): ClarificationModerationListResponse
+}
+
+type ClarificationModerationListResponse {
+    responses: [ClarificationModerationItem!]!
+    totalCount: Int!
+}
+
+type ClarificationModerationItem {
+    response: ThreadResponse!
+    item: ThreadResponseItem!
+    collection: ThreadResponseCollection!
+    messageSubject: String
+    boardTitle: String
+}
+
+extend type Mutation {
+    "Generate clarification questions for a published post"
+    generateClarificationQuestions(messageUid: Int!): ClarificationWorkflowResponse
+
+    "User submits answers to clarification questions"
+    submitClarificationAnswers(
+        collectionId: ID!
+        answers: [ClarificationAnswerInput!]!
+    ): ClarificationWorkflowResponse
+
+    "User edits previously submitted clarification answers"
+    editClarificationAnswers(
+        collectionId: ID!
+        answers: [ClarificationAnswerInput!]!
+    ): ClarificationWorkflowResponse
+
+    "User skips the entire clarification step"
+    skipClarification(collectionId: ID!): ClarificationWorkflowResponse
+
+    "CM saves a guidance example for a board"
+    saveClarificationGuidanceExample(
+        nodeId: ID!
+        exampleId: ID
+        exampleText: String!
+        displayOrder: Int!
+    ): ClarificationGuidanceExampleResponse
+
+    "CM deletes a guidance example"
+    deleteClarificationGuidanceExample(exampleId: ID!): Boolean
+
+    "CM reorders guidance examples"
+    reorderClarificationGuidanceExamples(
+        nodeId: ID!
+        exampleIds: [ID!]!
+    ): [ClarificationGuidanceExample!]
+
+    "Admin resends clarification nudge email to post author"
+    resendClarificationNudge(collectionId: ID!): ClarificationWorkflowResponse
+
+    "Admin resets clarification status back to PENDING"
+    resetClarificationStatus(collectionId: ID!): ClarificationWorkflowResponse
+
+    "Admin moderates a clarification answer (approve/reject with optional reason)"
+    moderateClarificationAnswer(responseId: ID!, status: String!, rejectReason: String): Boolean
+
+    "Admin bulk-approves all PENDING clarification answers for a collection"
+    approveAllClarificationAnswers(collectionId: ID!): Boolean
+
+    "Set clarification settings for a board (takes GraphQL node ID like 'board:forum-name')"
+    setClarificationSettings(nodeId: ID!, settingsInput: ClarificationSettingsInput!): ClarificationSettingsResult
+}
+
+input ClarificationAnswerInput @validationDefaults(prefix: "clarification_answer") {
+    itemId: ID! @validation(key: "item_id")
+    responseText: String @validation(key: "response_text")
+    selectedOptions: [Int!] @ignoreValidation
+}

package/graphql/clmSchema.graphqls

@@ -0,0 +1,126 @@
+# CLM Expert List Schema
+# Provides the expertList query for Community Managers to discover top experts per topic.
+
+"""
+A single entry in the top experts list for a topic.
+AI profiles are always excluded from this list.
+"""
+type ExpertListEntry {
+  "The user ID of the expert."
+  userId: Int!
+  "The login name of the expert."
+  login: String!
+  "The topic this expert is ranked for."
+  topic: String!
+  "The precomputed expertise score."
+  expertiseScore: Float!
+  "Number of messages posted on this topic."
+  messageCount: Int!
+  "Number of accepted solutions on this topic."
+  solutionCount: Int!
+  "Likes received on this topic."
+  kudosReceived: Int!
+  "The expert's rank name. Null if the user has no rank."
+  rankName: String
+  "The expert's rank position (lower value = higher rank). Null if unranked."
+  rankPosition: Int
+  "Whether the expert is a staff member (has a rank_position assigned)."
+  isStaff: Boolean!
+  "Total posts across all topics. Null if no tblia_expert_totals row exists for this user."
+  totalPosts: Int
+  "Total accepted solutions across all topics. Null if no tblia_expert_totals row exists."
+  totalSolutions: Int
+  "Total likes received across all topics. Null if no tblia_expert_totals row exists."
+  totalKudos: Int
+  "Contributions (posts + solutions) in the last 90 days. Null if no tblia_expert_totals row exists."
+  activity90d: Int
+  "Contributions (posts + solutions) in the last 180 days. Null if no tblia_expert_totals row exists."
+  activity180d: Int
+}
+
+extend type Query {
+  """
+  Returns the top experts per topic, filtered and ranked by expertise score.
+  AI profiles (answerEngine.aiUserId and answerEngine.kcUserId) are always excluded.
+  Results are limited by the clm.topExpertsPerTopic setting (default 10, max 100).
+  """
+  expertList(
+    "Optional topic filter. If provided, returns only experts for this topic (case-insensitive)."
+    topic: String
+    "Optional staff filter. true = staff only, false = non-staff only, null = all experts."
+    staffOnly: Boolean
+    "Optional username substring filter (case-insensitive, server-side AES-decrypted match)."
+    username: String
+    "Optional rank name filter (exact match against rank_name in tblia_expert_topics)."
+    rankName: String
+    "Optional role type filter (exact match against community role name in roles table)."
+    roleType: String
+    "Number of rows to skip before returning results. Defaults to 0."
+    offset: Int
+    "Maximum number of rows to return. Defaults to clm.topExpertsPerTopic setting."
+    limit: Int
+  ): [ExpertListEntry!]!
+}
+
+extend type Query {
+  """
+  Returns the distinct topic strings that have at least one expert record.
+  Used to populate the topic combobox on the CLM Experts admin page.
+  AI profiles are excluded from consideration (consistent with expertList).
+  """
+  expertTopics: [String!]!
+}
+
+"""
+A topic name and its expert count, used in Top 5 / Bottom 5 summary cards.
+"""
+type TopicCount {
+  "The topic name."
+  topic: String!
+  "Number of distinct experts assigned to this topic."
+  expertCount: Int!
+}
+
+"""
+Aggregate counts for the Expert Leaderboard summary panel.
+"""
+type ExpertStats {
+  "Total number of distinct expert users."
+  expertCount: Int!
+  "Total number of distinct expert topics."
+  topicsCount: Int!
+  "Average number of experts per topic (expertCount / topicsCount). Null if no topics."
+  avgExpertsPerTopic: Float
+  "Top 5 topics by expert count, descending."
+  topTopics: [TopicCount!]!
+  "Bottom 5 topics by expert count, ascending."
+  bottomTopics: [TopicCount!]!
+  "Epoch milliseconds of the last CLM build. Null if no build has run."
+  lastBuildTimestamp: Long
+  "Grand total posts across all experts, aggregated at CLM build time."
+  totalPosts: Int
+}
+
+extend type Query {
+  """
+  Returns aggregate expert statistics: total distinct experts and total distinct topics.
+  Used by the Experts Leaderboard summary panel.
+  """
+  expertStats: ExpertStats
+}
+
+extend type Query {
+  """
+  Returns distinct rank names from tblia_expert_topics.
+  Unranked experts (rank_name IS NULL) are excluded. AI profiles excluded.
+  """
+  expertRankNames: [String!]!
+}
+
+extend type Query {
+  """
+  Returns distinct community role names from the roles table for experts.
+  Only non-deleted roles held by at least one expert are returned. AI profiles excluded.
+  """
+  expertRoleTypes: [String!]!
+}

package/graphql/communitySearchSchema.graphqls

@@ -1,5 +1,5 @@
 extend type Query {
-  "Fetches a list of the messages matching the search term with subject or body or teaser or tag or attachment."
+  "Fetches a list of the messages matching the search term with subject or body or teaser or tag or attachment or author name."
   messageSearch(
     "The search query term to look for when searching the messages."
     searchTerm: String!
@@ -19,7 +19,7 @@ extend type Query {
     sorts: MessageSearchSorts
   ): MessageSearchResults!
 
-  "Fetches a list of the messages matching the search term with subject or body or teaser or tag or attachment."
+  "Fetches a list of the messages matching the search term with subject or body or teaser or tag or attachment or author name."
   quickMessageSearch(
     "The search query term to look for when searching the messages."
     searchTerm: String!
@@ -177,6 +177,8 @@ interface MessageSearchResult implements Node {
   message: Message!
   "A list of metadata that specifies the parts of the message where a match for the searchTerm was found."
   snippet: [SearchSnippet!]
+  "Indicates whether this result is a promoted/featured search result."
+  isPromoted: Boolean
 }
 """
 Defines a quick message search result. This holds the topic message, and its associated search specific results
@@ -233,6 +235,8 @@ type TopLevelMessageSearchResult implements MessageSearchResult & Node {
   ): MessageSearchConnection
   "A list of metadata that specifies the parts of the message where a match for the searchTerm was found."
   snippet: [SearchSnippet!]
+  "Indicates whether this result is a promoted/featured search result."
+  isPromoted: Boolean
 }
 
 """
@@ -247,6 +251,8 @@ type DescendantMessageSearchResult implements MessageSearchResult & Node {
   message: Message!
   "A list of metadata that specifies the parts of the message where a match for the search term was found."
   snippet: [SearchSnippet!]
+  "Indicates whether this result is a promoted/featured search result."
+  isPromoted: Boolean
 }
 
 """
@@ -341,6 +347,8 @@ enum SearchSnippetKey {
   TEASER
   "Search snippet is for the message tag."
   TAGS
+  "Search snippet is for the message author name."
+  AUTHOR_NAME
   "This search snippet is the user login ID."
   LOGIN
   "This search snippet is for the user first name."