SDK Integrations

SDK integrations are reusable bundle building blocks for external protocols and product surfaces. They live under kdcube_ai_app.apps.chat.sdk.integrations and are meant to be imported by bundles instead of copied into every application.

The boundary is explicit: the SDK owns protocol mechanics, normalized payloads, provider calls, rendering helpers, and reusable storage primitives. The bundle owns product policy: which user may connect an account, which conversation receives a webhook, which delivery channel is used, which UI route exposes an operation, and which workflow handles the resulting message.

SDK integration ownership boundary diagram
SDK integration ownership boundary Bundle policy calls reusable SDK integration modules, which handle protocol mechanics for external providers. Your Bundle auth and role policy user and conversation binding task and workflow routing imports SDK Integrations email: accounts, providers, delivery telegram: webhook, stream, Mini App protocol calls External Systems Gmail and iCloud Telegram Bot API MCP clients and webhooks

Email Integration

Import reusable email mechanics from kdcube_ai_app.apps.chat.sdk.integrations.email. The email package covers account metadata, Gmail OAuth/API access, iCloud IMAP/SMTP, attachment materialization, email delivery formatting, task-scoped Email MCP runs, and Claude Code email processing.

Account and provider access

EmailAccountStore is the reusable account store. Account metadata stays in bundle storage; tokens and app passwords are stored through KDCube user-secret APIs.

Mailbox and attachment processing

Provider dispatch functions normalize Gmail and iCloud messages. Attachment helpers copy selected email files into the current ReAct turn as fi: artifacts.

Delivery formatting

delivery.py builds conservative email HTML, plain-text fallbacks, address lists, filenames, and EmailMessage objects with attachments.

from kdcube_ai_app.apps.chat.sdk.integrations.email import (
    EmailAccountStore,
    build_email_message,
    materialize_email_attachments_for_current_turn,
    process_user_emails,
    split_email_addresses,
)

Bundles should not duplicate account stores or provider wrappers. Keep bundle-specific behavior in UI operations, policy hooks, task definitions, or delivery tools.

Reference: Email SDK Integration README.

Telegram Integration

Import reusable Telegram transport mechanics from kdcube_ai_app.apps.chat.sdk.integrations.telegram. The package covers Bot API calls, update normalization, attachment hydration, ReAct progress streaming, final response rendering, Mini App auth, generic chat submitter helpers, signed downloads, and configurable user/widget subsystems.

Webhook to chat-core

Telegram updates are normalized into common chat inputs and submitted through the same chat-core path used by browser transports, including followup and steer.

Progress and final delivery

TelegramActivityStreamer edits one progress card while a turn runs. Final delivery appends the final answer or sends follow-up messages without discarding progress.

Mini App operations

Reusable widget auth and widget operations support conversation binding, task views, execution views, and signed artifact download links.

from kdcube_ai_app.apps.chat.sdk.integrations.telegram import (
    TelegramActivityStreamer,
    deliver_react_turn_to_telegram,
    hydrate_telegram_attachments,
    raw_attachments_from_telegram,
    telegram_command_kind_and_text,
    telegram_user_session,
)

For Telegram Web App file downloads, backend responses should include Content-Disposition: attachment; filename="..." and Access-Control-Allow-Origin: https://web.telegram.org. The signed-download helpers and bundle public routes should preserve those headers.

Reference: Telegram SDK Integration README.

Bundle Integration Pattern

A bundle typically uses SDK integrations in thin adapter methods. The adapter resolves the current user and storage root, applies product authorization, then calls SDK integration helpers.

from kdcube_ai_app.infra.plugin.agentic_loader import api
from kdcube_ai_app.apps.chat.sdk.integrations import telegram

@api(method="POST", alias="telegram_webhook", route="public", public_auth="bundle")
async def telegram_webhook(self, **update):
    summary = telegram.summarize_telegram_update(update)
    # bundle policy: verify webhook, authorize user, choose conversation
    # SDK mechanics: hydrate attachments, map followup/steer, submit to chat core
    return await my_router.handle(summary)

This split keeps reusable transport code in the SDK while preserving bundle ownership of product-specific policy and UX.