khoros-aurora-sdk 26.2.2 → 26.3.1

package/build-hash.txt

@@ -1 +1 @@
-b42ea22
+7d3ff26

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."

package/graphql/emailOrchestrationSchema.graphqls

@@ -0,0 +1,293 @@
+extend type Query {
+  "Returns the available template variables for RULES category email templates. These come from a static registry, not from existing templates."
+  rulesTemplateVariables: [EmailTemplateVariable!]!
+
+  "Fetches a list of email orchestration templates."
+  emailTemplates(
+    "Constraints to filter email templates."
+    constraints: EmailTemplateConstraints
+    "The number of results to return."
+    first: Int
+    "The cursor to return the results after."
+    after: String
+    "The last 'n' number of results to return."
+    last: Int
+    "The cursor to return the results before."
+    before: String
+  ): EmailTemplateConnection
+}
+
+"""
+Defines constraints that can be used to filter the email template queries.
+"""
+input EmailTemplateConstraints {
+  "A search string to filter templates by name, description, or subject."
+  search: String
+  "A category to filter templates by."
+  category: EmailTemplateCategory
+  "A specific template ID to filter by. Returns only versions of this template."
+  templateId: String
+  "Sort order for the results. One of: RECENT, NAME, CATEGORY. Defaults to RECENT."
+  sort: EmailTemplateSort
+  "Filter by template type: SYSTEM or CUSTOM."
+  type: EmailTemplateType
+  "Filter by template status: ACTIVE, DRAFT, DEFAULT, or INACTIVE."
+  status: EmailTemplateStatus
+}
+
+"Template type filter."
+enum EmailTemplateType {
+  SYSTEM
+  CUSTOM
+}
+
+"Template status filter."
+enum EmailTemplateStatus {
+  ACTIVE
+  DRAFT
+  DEFAULT
+  INACTIVE
+}
+
+"Sort order for email template results."
+enum EmailTemplateSort {
+  RECENT
+  NAME
+  CATEGORY
+}
+
+"""
+Defines a connection object for email orchestration templates.
+"""
+type EmailTemplateConnection implements Connection {
+  "The total count of results (across all pages)."
+  totalCount: Int!
+  "The page information for the results."
+  pageInfo: PageInfo!
+  "The results (edges)."
+  edges: [EmailTemplateEdge!]!
+  "Status counts across all templates (not just the current page). Counts are grouped by template, not by version."
+  statusCounts: EmailTemplateStatusCounts
+}
+
+"Counts of templates grouped by their overall status."
+type EmailTemplateStatusCounts {
+  "Total number of unique templates."
+  all: Int!
+  "Templates with a non-default ACTIVE version."
+  active: Int!
+  "Templates with only DRAFT (non-default) versions."
+  draft: Int!
+  "Templates with only the default (system) version and no overrides."
+  default: Int!
+  "Templates with no active and no draft versions."
+  inactive: Int!
+}
+
+"""
+Defines an edge for an email orchestration template.
+"""
+type EmailTemplateEdge implements Edge {
+  "The cursor that can be used to get a new page of results starting after this template."
+  cursor: String
+  "The email template."
+  node: EmailTemplate!
+}
+
+"An individual email orchestration template."
+type EmailTemplate implements Node {
+  "The email template ID."
+  id: ID!
+  "The unique template identifier."
+  templateId: String!
+  "The display name of the template."
+  displayName: String!
+  "The description of the template."
+  description: String
+  "The category of the template."
+  category: EmailTemplateCategory!
+  "Whether this is a system template."
+  isSystem: Boolean!
+  "Whether the latest version is the default (system-seeded) version. Default versions are read-only and serve as a fallback."
+  isDefaultVersion: Boolean
+  "The version number of the latest published version."
+  versionNum: Int
+  "The status of the latest version."
+  status: EmailTemplateVersionStatus
+  "The locale of the latest version."
+  locale: String
+  "The subject line of the latest version."
+  subject: String
+  "The HTML content of the latest version."
+  htmlContent: String
+  "The raw content JSON of the latest version, containing body blocks (text/button), preamble/postamble HTML, and send config."
+  contentJson: String
+  "The available template variables that can be inserted into subject and body text. Each variable has a name (e.g. communityTitle) and a type (text or url)."
+  variables: [EmailTemplateVariable!]
+  "The date the template was created."
+  createdDate: String
+  "The date the template was last modified."
+  modifiedDate: String
+  "The date the latest version was published."
+  publishedDate: String
+}
+
+"""
+A template variable that can be inserted into the subject or body text using {variableName} syntax.
+Variables of type 'url' represent links; variables of type 'text' represent text content.
+"""
+type EmailTemplateVariable {
+  "The variable name, used as {name} in template text."
+  name: String!
+  "A human-readable display name for the variable."
+  displayName: String
+  "The variable type: 'text' for text content, 'url' for links."
+  type: String!
+  "A short description of what this variable represents."
+  description: String
+  "An example value for this variable."
+  example: String
+  "Whether this is a global variable shared by all templates."
+  isGlobal: Boolean
+  "The category this variable belongs to (e.g. Global, User Events, Topic Events)."
+  category: String
+  "The subcategory within the category (e.g. Registration, Solution Accepted)."
+  subcategory: String
+}
+
+"""
+An enumeration that defines the different email template categories.
+"""
+enum EmailTemplateCategory {
+  AUTHENTICATION
+  SUBSCRIPTION
+  ENGAGEMENT
+  MODERATION
+  WORKFLOW
+  MEMBERSHIP
+  EVENTS
+  INTEGRATION
+  ADMIN
+  RULES
+}
+
+"""
+An enumeration that defines the status of an email template version.
+"""
+enum EmailTemplateVersionStatus {
+  DRAFT
+  ACTIVE
+}
+
+"""
+Input for creating a new custom email template.
+"""
+input CreateEmailTemplateInput @validationDefaults(prefix: "create_email_template") {
+  "A unique template identifier (e.g. my-welcome-email)."
+  templateId: String!
+  "The display name shown in the admin UI."
+  displayName: String!
+  "An optional description of the template."
+  description: String
+  "The category to file the template under."
+  category: EmailTemplateCategory!
+  "The subject line for the initial version."
+  subject: String!
+  "The body blocks as a JSON string for the initial version."
+  body: String!
+  "Whether to immediately set the new template as active."
+  setActive: Boolean
+}
+
+extend type Mutation {
+  "Updates an email template's subject and body blocks. For system templates, creates a new version."
+  updateEmailTemplate(
+    "The unique template identifier."
+    templateId: String!
+    "The version number to update. If omitted, updates the latest published version."
+    versionNum: Int
+    "The updated subject line."
+    subject: String!
+    "The updated body blocks as a JSON string."
+    body: String!
+  ): UpdateEmailTemplateResult!
+
+  "Sets the active version for an email template. Only one version can be active per template."
+  setActiveEmailTemplateVersion(
+    "The unique template identifier."
+    templateId: String!
+    "The version number to set as active."
+    versionNum: Int!
+  ): UpdateEmailTemplateResult!
+
+  "Creates a new custom email template with an initial version."
+  createEmailTemplate(input: CreateEmailTemplateInput!): UpdateEmailTemplateResult!
+
+  "Creates a new draft version of an existing email template, copying content from a source version."
+  createEmailTemplateVersion(
+    "The unique template identifier."
+    templateId: String!
+    "The version number to copy content from."
+    sourceVersionNum: Int!
+  ): UpdateEmailTemplateResult!
+
+  """
+  Sends a test email for the specified template to the currently
+  authenticated user. Requires CAN_MANAGE_MAIL_TEMPLATES. Rate limited
+  per user via `rate.limit.send_test_email.*` in flood.config.
+  """
+  sendTestEmailToSelf(
+    "The unique template identifier."
+    templateId: String!
+    "The version number to send. If omitted, sends the active version."
+    versionNum: Int
+  ): SendTestEmailResult!
+
+  "Deletes a specific version of an email template. Cannot delete the default (system) version."
+  deleteEmailTemplateVersion(
+    "The unique template identifier."
+    templateId: String!
+    "The version number to delete."
+    versionNum: Int!
+  ): DeleteEmailTemplateVersionResult!
+}
+
+"""
+The result of a deleteEmailTemplateVersion mutation.
+"""
+type DeleteEmailTemplateVersionResult {
+  "Whether the deletion was successful."
+  success: Boolean!
+  "Errors that occurred during deletion."
+  errors: [EmailTemplateError!]
+}
+
+"""
+The result of a sendTestEmailToSelf mutation.
+"""
+type SendTestEmailResult {
+  "Whether the email was sent successfully."
+  success: Boolean!
+  "The email address the test was sent to."
+  recipientEmail: String
+  "Errors that occurred during sending."
+  errors: [EmailTemplateError!]
+}
+
+"""
+The result of an updateEmailTemplate mutation.
+"""
+type UpdateEmailTemplateResult {
+  "The updated email template."
+  result: EmailTemplate
+  "Any errors that occurred during the mutation."
+  errors: [EmailTemplateError!]
+}
+
+"""
+An error that occurred during an email template mutation.
+"""
+type EmailTemplateError {
+  "The error message."
+  message: String!
+}