SDK Integrations

SDK integrations are reusable app 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 apps 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 app 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 entrypoint/message handler handles the resulting message.

Integrations can now participate in the object ecosystem. An integration may emit external events, expose searchable objects through a named-service namespace, return object actions such as open/download/confirm, and provide block policies so ReAct can read external objects without bespoke tools for every provider.

SDK integration ownership boundary diagram
SDK integration ownership boundary App policy calls reusable SDK integration modules, which handle protocol mechanics for external providers. Your App 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 app 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,
)

Apps should not duplicate account stores or provider wrappers. Keep app-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 app public routes should preserve those headers.

Reference: Telegram SDK Integration README.

App Integration Pattern

An app 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.bundle_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)
    # app 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 app ownership of product-specific policy and UX.