@kyyinfinite/lumina 1.0.0

package/src/proto/layouts.js

@@ -0,0 +1,89 @@
+/**
+ * @file layouts.js
+ * @module lumina/proto/layouts
+ *
+ * Layout view-model factories. Each layout wraps one or more UX primitives
+ * inside `view_model`, with the proper `GenAI{Kind}LayoutViewModel` typename.
+ *
+ * Replaces the implicit `Array.isArray(data) ? 'primitives' : 'primitive'`
+ * branching in the legacy `AIRich.newLayout` static method — explicit
+ * single/hscroll/action-row variants instead.
+ */
+
+import { LayoutKind, TYPENAME } from './enums.js'
+
+/**
+ * Wrap a single primitive in a "Single" layout view-model.
+ *
+ * @param {object} primitive
+ * @param {object} [extra]   Additional fields merged at top-level.
+ * @returns {object}
+ */
+export function singleLayout(primitive, extra = {}) {
+  return {
+    ...extra,
+    view_model: {
+      primitive,
+      __typename: TYPENAME.layout(LayoutKind.SINGLE),
+    },
+  }
+}
+
+/**
+ * Wrap multiple primitives in an "HScroll" (horizontal scroll) layout.
+ *
+ * @param {object[]} primitives
+ * @param {object} [extra]
+ * @returns {object}
+ */
+export function hscrollLayout(primitives, extra = {}) {
+  return {
+    ...extra,
+    view_model: {
+      primitives,
+      __typename: TYPENAME.layout(LayoutKind.HSCROLL),
+    },
+  }
+}
+
+/**
+ * Wrap multiple primitives in an "ActionRow" layout (used for follow-up
+ * suggestion pills that should appear as a horizontal row of buttons).
+ *
+ * @param {object[]} primitives
+ * @param {object} [extra]
+ * @returns {object}
+ */
+export function actionRowLayout(primitives, extra = {}) {
+  return {
+    ...extra,
+    view_model: {
+      primitives,
+      __typename: TYPENAME.layout(LayoutKind.ACTION_ROW),
+    },
+  }
+}
+
+/**
+ * Auto-pick helper. Picks `singleLayout` for a single primitive and
+ * `hscrollLayout` for arrays — useful for API surfaces that accept both.
+ *
+ * @param {LayoutKind} kind    Forced kind; overrides auto-detection.
+ * @param {object|object[]} data
+ * @param {object} [extra]
+ * @returns {object}
+ */
+export function layoutFor(kind, data, extra = {}) {
+  switch (kind) {
+    case LayoutKind.SINGLE:
+      return singleLayout(Array.isArray(data) ? data[0] : data, extra)
+    case LayoutKind.HSCROLL:
+      return hscrollLayout(Array.isArray(data) ? data : [data], extra)
+    case LayoutKind.ACTION_ROW:
+      return actionRowLayout(Array.isArray(data) ? data : [data], extra)
+    default:
+      throw new TypeError(`Unknown layout kind: ${kind}`)
+  }
+}
+
+export default { singleLayout, hscrollLayout, actionRowLayout, layoutFor }

package/src/proto/primitives.js

@@ -0,0 +1,181 @@
+/**
+ * @file primitives.js
+ * @module lumina/proto/primitives
+ *
+ * Pure factory functions for every GenAI "UX primitive" used by the AI Rich
+ * Response envelope. Each factory returns a plain object ready to be wrapped
+ * by a layout view-model (see {@link module:proto/layouts}).
+ *
+ * All `__typename` strings are sourced from {@link module:proto/enums.TYPENAME}
+ * — never hardcode them here.
+ */
+
+import { TYPENAME, ImagineType, SourceType, PromptType } from './enums.js'
+
+/**
+ * Markdown-text primitive. May carry inline entities extracted by
+ * `extractInlineEntities`.
+ *
+ * @param {string} text
+ * @param {Array<object>} [inlineEntities]
+ */
+export function markdownTextPrimitive(text, inlineEntities) {
+  const primitive = { text, __typename: TYPENAME.MARKDOWN_TEXT }
+  if (inlineEntities?.length) primitive.inline_entities = inlineEntities
+  return primitive
+}
+
+/**
+ * Code primitive.
+ *
+ * @param {string} language
+ * @param {Array<{ content: string, type: string }>} unifiedBlocks
+ */
+export function codePrimitive(language, unifiedBlocks) {
+  return {
+    language,
+    code_blocks: unifiedBlocks,
+    __typename: TYPENAME.CODE,
+  }
+}
+
+/**
+ * Table primitive.
+ *
+ * @param {Array<object>} unifiedRows   Output of `toTableMetadata().unifiedRows`.
+ */
+export function tablePrimitive(unifiedRows) {
+  return {
+    rows: unifiedRows,
+    __typename: TYPENAME.TABLE,
+  }
+}
+
+/**
+ * Search-result (sources) primitive.
+ *
+ * @param {Array<object>} sources   Pre-shaped source objects.
+ */
+export function searchResultPrimitive(sources) {
+  return {
+    sources,
+    __typename: TYPENAME.SEARCH_RESULT,
+  }
+}
+
+/**
+ * Reel primitive (one per reel item).
+ *
+ * @param {object} item   Pre-shaped reel descriptor.
+ */
+export function reelPrimitive(item) {
+  return { ...item, __typename: TYPENAME.REEL }
+}
+
+/**
+ * Imagine primitive — used for both images and videos (animate).
+ *
+ * @param {{ url: string, mime_type: string, file_length?: number, duration?: number }} media
+ * @param {'IMAGE'|'ANIMATE'} kind
+ * @param {string} [status='READY']
+ * @param {string} [thumbnailBase64]   Base64 JPEG thumbnail (video only).
+ */
+export function imaginePrimitive(media, kind, status = 'READY', thumbnailBase64) {
+  const primitive = {
+    media,
+    imagine_type: kind,
+    status: { status },
+    __typename: TYPENAME.IMAGINE,
+  }
+  if (thumbnailBase64) primitive.thumbnail = { raw_media: thumbnailBase64 }
+  return primitive
+}
+
+/**
+ * Product-card primitive.
+ *
+ * @param {object} item   Pre-shaped product descriptor (already media-resolved).
+ */
+export function productCardPrimitive(item) {
+  return { ...item, __typename: TYPENAME.PRODUCT_CARD }
+}
+
+/**
+ * Post primitive.
+ *
+ * @param {object} p     Pre-shaped post descriptor (already media-resolved).
+ * @param {boolean} isCarousel
+ */
+export function postPrimitive(p, isCarousel) {
+  return { ...p, is_carousel: isCarousel, __typename: TYPENAME.POST }
+}
+
+/**
+ * Metadata-text primitive (used for footer / tip).
+ *
+ * @param {string} text
+ */
+export function metadataTextPrimitive(text) {
+  return { text, __typename: TYPENAME.METADATA_TEXT }
+}
+
+/**
+ * Follow-up suggestion pill primitive.
+ *
+ * @param {string} text
+ */
+export function followUpSuggestionPillPrimitive(text) {
+  return {
+    prompt_text: text,
+    prompt_type: PromptType.SUGGESTED_PROMPT,
+    __typename: TYPENAME.FOLLOW_UP_PILL,
+  }
+}
+
+/**
+ * Helper: shape a source entry for `searchResultPrimitive`.
+ *
+ * @param {{ iconUrl?: string, url?: string, text?: string, subtitle?: string }} src
+ */
+export function shapeSourceEntry({ iconUrl = '', url = '', text = '', subtitle = 'AI' } = {}) {
+  return {
+    source_type: SourceType.THIRD_PARTY,
+    source_display_name: text,
+    source_subtitle: subtitle,
+    source_url: url,
+    favicon: { url: iconUrl, mime_type: 'image/jpeg', width: 16, height: 16 },
+  }
+}
+
+/**
+ * Helper: shape a single reel item for `reelPrimitive`.
+ */
+export function shapeReelEntry(item) {
+  return {
+    reels_url: item.videoUrl ?? item.url ?? '',
+    thumbnail_url: item.thumbnail ?? '',
+    creator: item.username ?? item.title ?? '',
+    avatar_url: item.avatar ?? '',
+    reels_title: item.reelsTitle ?? item.title ?? '',
+    likes_count: item.likes ?? item.like ?? 0,
+    shares_count: item.shares ?? item.share ?? 0,
+    view_count: item.views ?? item.view ?? 0,
+    reel_source: item.source ?? 'IG',
+    is_verified: !!(item.isVerified ?? item.verified),
+  }
+}
+
+export default {
+  markdownTextPrimitive,
+  codePrimitive,
+  tablePrimitive,
+  searchResultPrimitive,
+  reelPrimitive,
+  imaginePrimitive,
+  productCardPrimitive,
+  postPrimitive,
+  metadataTextPrimitive,
+  followUpSuggestionPillPrimitive,
+  shapeSourceEntry,
+  shapeReelEntry,
+}

package/src/proto/relay-nodes.js

@@ -0,0 +1,55 @@
+/**
+ * @file relay-nodes.js
+ * @module lumina/proto/relay-nodes
+ *
+ * Single source of truth for the `additionalNodes` block that Baileys
+ * `relayMessage` expects when sending interactive (native-flow) messages.
+ *
+ * The legacy code duplicated this 12-line block three times (Button.send,
+ * ButtonV2.send, Carousel.send). Lumina centralises it here.
+ */
+
+import { NativeFlow } from './enums.js'
+
+/**
+ * Build the standard biz/interactive/native_flow additional-nodes block.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.outerVersion=NativeFlow.OUTER_VERSION]
+ * @param {string} [opts.flowVersion=NativeFlow.FLOW_VERSION]
+ * @param {string} [opts.flowName=NativeFlow.FLOW_NAME_MIXED]
+ * @param {boolean} [opts.includeBiz=true]  Whether to wrap in the `<biz>` node.
+ * @returns {Array<object>}  Array suitable for `relayMessage`'s `additionalNodes`.
+ */
+export function createInteractiveNodes(opts = {}) {
+  const outerVersion = opts.outerVersion ?? NativeFlow.OUTER_VERSION
+  const flowVersion = opts.flowVersion ?? NativeFlow.FLOW_VERSION
+  const flowName = opts.flowName ?? NativeFlow.FLOW_NAME_MIXED
+  const includeBiz = opts.includeBiz ?? true
+
+  const interactive = {
+    tag: NativeFlow.INTERACTIVE_TAG,
+    attrs: { type: NativeFlow.TYPE, v: outerVersion },
+    content: [{ tag: NativeFlow.TYPE, attrs: { v: flowVersion, name: flowName } }],
+  }
+
+  if (!includeBiz) return [interactive]
+
+  return [
+    {
+      tag: NativeFlow.BIZ_TAG,
+      attrs: {},
+      content: [interactive],
+    },
+  ]
+}
+
+/**
+ * Convenience: returns the same block but with `name: 'native_flow'` only
+ * (no biz wrapper). Useful for non-business accounts.
+ */
+export function createBareInteractiveNodes(opts = {}) {
+  return createInteractiveNodes({ ...opts, includeBiz: false })
+}
+
+export default { createInteractiveNodes, createBareInteractiveNodes }

package/src/proto/rich-response.js

@@ -0,0 +1,144 @@
+/**
+ * @file rich-response.js
+ * @module lumina/proto/rich-response
+ *
+ * Assembles the `botForwardedMessage.richResponseMessage` envelope used by
+ * the AI Rich Response feature. Pure function — no socket access. The
+ * {@link AIRichBuilder} calls this from its `build()` method.
+ *
+ * Replaces the legacy `AIRich.build()` method (1436–1503) which:
+ *   - Hardcoded `botJid: '0@bot'`
+ *   - Hardcoded `forwardOrigin: 4`
+ *   - Hardcoded `forwardingScore: 1`
+ *   - Hardcoded personal leftover `disclaimerText: '~ Ahmad tumbuh kembang'`
+ * All four are now sourced from {@link module:proto/enums} / parameters.
+ */
+
+import crypto from 'node:crypto'
+
+import { BOT_JID, ForwardOrigin } from './enums.js'
+
+/**
+ * @typedef {object} RichResponseOptions
+ * @property {string} [title]                        Sets `botMetadata.messageDisclaimerText`.
+ * @property {Array<object>} sections                Pre-resolved layout sections.
+ * @property {Array<object>} [submessages=[]]        Pre-resolved submessage objects.
+ * @property {Array<object>} [richResponseSources=[]]
+ * @property {object} [contextInfo={}]
+ * @property {string} [footer]                       Appended as a metadata-text section.
+ * @property {boolean} [forwarded=true]              Attach forward metadata.
+ * @property {boolean|object} [notification=false]   Attach session-transparency metadata.
+ * @property {boolean} [includesUnifiedResponse=true]
+ * @property {boolean} [includesSubmessages=true]
+ * @property {object} [quoted]                       Quoted-message descriptor.
+ * @property {string} [quotedParticipant]
+ * @property {object} [extraPayload]                 Merged at top-level.
+ */
+
+/**
+ * Assemble a `botForwardedMessage` envelope.
+ *
+ * @param {RichResponseOptions} opts
+ * @returns {Promise<object>}  The envelope, ready to pass to `relayMessage`.
+ */
+export async function assembleRichResponse({
+  title,
+  sections,
+  submessages = [],
+  richResponseSources = [],
+  contextInfo = {},
+  footer,
+  forwarded = true,
+  notification = false,
+  includesUnifiedResponse = true,
+  includesSubmessages = true,
+  quoted,
+  quotedParticipant,
+  extraPayload = {},
+} = {}) {
+  const forwardMeta = forwarded
+    ? {
+        forwardingScore: 1,
+        isForwarded: true,
+        forwardedAiBotMessageInfo: { botJid: BOT_JID },
+        forwardOrigin: ForwardOrigin.BOT,
+      }
+    : {}
+
+  const notificationMeta = notification
+    ? {
+        sessionTransparencyMetadata: {
+          // User-supplied disclaimer (no personal leftovers).
+          disclaimerText: typeof notification === 'object' ? notification.disclaimerText ?? '' : '',
+          hcaId: typeof notification === 'object' && notification.hcaId
+            ? notification.hcaId
+            : `hca_${crypto.randomUUID()}`,
+          sessionTransparencyType: notification.sessionTransparencyType ?? 1,
+        },
+      }
+    : {}
+
+  const quotedMeta = quoted
+    ? {
+        stanzaId: quoted?.key?.id ?? quoted?.id,
+        participant: quotedParticipant ?? quoted?.key?.participant ?? quoted?.key?.remoteJid,
+        quotedType: 0,
+        quotedMessage:
+          typeof quoted === 'object' && quoted !== null ? quoted.message ?? quoted : undefined,
+      }
+    : {}
+
+  const finalSections = footer
+    ? [
+        ...sections,
+        // Footer is appended as a metadata-text primitive, wrapped in a
+        // Single layout view-model. Built inline to avoid a circular import
+        // with primitives/layouts — those are pure helpers, but this envelope
+        // assembler must remain dependency-light for testability.
+        {
+          view_model: {
+            primitive: { text: footer, __typename: 'GenAIMetadataTextPrimitive' },
+            __typename: 'GenAISingleLayoutViewModel',
+          },
+        },
+      ]
+    : sections
+
+  return {
+    messageContextInfo: {
+      deviceListMetadata: {},
+      deviceListMetadataVersion: 2,
+      botMetadata: {
+        messageDisclaimerText: title,
+        richResponseSourcesMetadata: { sources: richResponseSources },
+        ...notificationMeta,
+      },
+    },
+    ...extraPayload,
+    botForwardedMessage: {
+      message: {
+        richResponseMessage: {
+          messageType: 1,
+          submessages: includesSubmessages ? submessages : [],
+          unifiedResponse: {
+            data: includesUnifiedResponse
+              ? Buffer.from(
+                  JSON.stringify({
+                    response_id: crypto.randomUUID(),
+                    sections: finalSections,
+                  }),
+                ).toString('base64')
+              : '',
+          },
+          contextInfo: {
+            ...forwardMeta,
+            ...quotedMeta,
+            ...contextInfo,
+          },
+        },
+      },
+    },
+  }
+}
+
+export default assembleRichResponse