iCanText App Bridge

How it works

The iCanText App Bridge is a versatile integration engine that turns iCanText into a Decentralized Operating System. It allows third-party web applications to run seamlessly within the communication flow, leveraging the P2P network as a secure, serverless back-end.

Interaction & Collaboration Models

• Owner Only: (Default) The message context is a private state. Only the original author can update it using updateAppContext.
• Collaborative: The app context is open. Any authorized channel member can perform edits. Ideal for shared settings or simple "last-writer-wins" states.
• Event Sourcing: Instead of overwriting a single state, users emit individual signed App Events. All peers store these in a Universal Ledger, allowing apps to reconstruct perfect state even with high concurrency (e.g. Polls, Games).

Integration Modes

• Channel Header: Install utility apps (like Video Tools or Dashboards) directly in the channel's top bar for quick access by all members.
• Interactive Messages: Post dynamic content (like Polls, Tasks, or Games) that renders as an iframe inside the chat. Use the P2P mesh to sync their state in real-time.
• External Popups: Launch full-scale applications in separate tabs while maintaining a secure link to the user's decentralized identity.

Choosing the Right Communication Flow

The SDK offers three distinct ways to exchange data. Choose based on your persistence requirements:

Understanding interactionModel

The interactionModel option in postAppContent defines who has the right to modify the original message instance itself:

• OWNER_ONLY: Only the author can call updateAppContext. Other members can still contribute via emitAppEvent. This is the safest mode for Polls.
• COLLABORATIVE: Any member with write access to the channel can call updateAppContext to overwrite the shared state.

Unified Security Handshake

Whether your app is running as a header icon, a chat widget, or an external window, it must perform a rigorous handshake to establish a secure link with iCanText:

1. Initiation: The app is rendered by iCanText. This happens when:
   • A member clicks a Header Icon.
   • An Interactive Message appears in the chat timeline.
   • A user manually types /app https://your-app.com.
2. Hello: Your application script starts and automatically sends an ICT_HELLO signal via postMessage to the parent window.
3. Verification: iCanText identifies the source window, verifies it against its internal registry, and retrieves its specific context (active workspace, permissions).
4. Init: iCanText returns an ICT_INIT payload containing the instanceId, the user's localPeerId, localPseudonym, and its Display Mode.
5. Ready: The bridge is now READY. All subsequent P2P operations are cryptographically locked to this specific app instance.

ICTBridgeSDK.js

We provide a lightweight, promise-based SDK to handle the complexity of postMessage communication and handshaking.

Include it in your HTML:

<script src="https://icantext.com/ICTBridgeSDK.js"></script>

API Reference

const connection = await sdk.init();
if (connection.status === 'READY') {
    console.log("Connected as:", connection.localPseudonym);
}

const peers = await sdk.getPeers();
// peer: {id, pseudonym, verified, isActiveOnApp, presenceState, isActuallyOnline}
const activePeers = peers.filter(p => p.isActiveOnApp);

sdk.onPeersUpdate((peers) => {
    const onlinePeers = peers.filter(p => p.isActuallyOnline);
    updatePresenceDots(onlinePeers);
}, { cycleMs: 3000 }); // Optional: check every 3s

const targets = ['peer_xyz...'];
const data = { action: 'move', x: 10, y: 20 };
sdk.sendData(targets, data);

sdk.onData((fromPeerId, payload) => {
    console.log(`Message from ${fromPeerId}:`, payload);
});

sdk.onProfileUpdate((newPseudonym) => {
    document.getElementById('display-name').textContent = newPseudonym;
});

const timeStr = await sdk.getServerTime(); 
// Returns string format: YYYYMMDDHHMMSS (e.g. "20260202101030")

// Close the app when the user clicks a "Quit" button
document.getElementById('quit-btn').onclick = () => sdk.closeApp();

// Post Text
const id = await sdk.postMessage({ text: "Hello!" });

// Post Image/File
sdk.postMessage({ 
    file: { 
        name: "image.png", 
        type: "image/png", 
        data: "data:image/png;base64,..." 
    } 
});

await sdk.editMessage("msg_123...", "Updated text content");

// From a configuration popup:
sdk.postAppContent("https://vote.app/", { 
    question: "Pizza or Tacos?", 
    votes: {} 
}, { 
    interactionModel: 'COLLABORATIVE' 
}););

// On app startup inside the chat:
const state = await sdk.getAppContext();
console.log("Question:", state.question);

// When a user interacts (e.g. votes):
state.votes[myId] = "Pizza";
sdk.updateAppContext(state); 
// Result: All channel members see the update instantly.

const mode = sdk.getDisplayMode();

if (mode === 'MESSAGE') {
    renderCompactView(); // Simplified UI for the chat timeline
} else {
    renderFullEditor();  // Full UI for configuration or popups
}

sdk.onContextUpdate((updatedContext) => {
    console.log("New votes received!");
    refreshUI(updatedContext.votes);
});

const mid = sdk.getMessageId();
console.log("This app instance belongs to message:", mid);

// Example: Cast a vote in a poll
sdk.emitAppEvent({ vote: 'Option A' });

sdk.onAppEvent((senderId, data, timestamp) => {
    console.log(`User ${senderId} voted for:`, data.vote);
    recalculateUI();
});

// On startup: Replay history to show the current score
const events = await sdk.getAppEvents();
events.forEach(e => processVote(e.senderId, e.data.vote));

// Switch the app to total fullscreen
sdk.setFullscreen('VIEWPORT');

await sdk.exitFullscreen();

const isAdmin = sdk.getIsAdmin();

if (isAdmin) {
    renderAdminControls(); // Enable configuration or moderation tools
} else {
    renderUserView();      // Restrict UI to standard participation
}

SDK Source Code (Open Source)

The ICTBridgeSDK is a zero-dependency JavaScript class. It is designed to be robust against standalone execution and handles the multiplexing of messages between iCanText and your application logic.

/* SDK code loading... */

Usage Example: Shared Sticky Notes

Below is a minimal example of a collaborative app where users send notes to each other.

const sdk = new ICTBridgeSDK('my_collab_app');

async function startApp() {
    const connection = await sdk.init();
    
    if (connection.status === 'READY') {
        console.log(`Connected as: ${connection.localPseudonym}`);

        // Listen for incoming notes
        sdk.onData((from, payload) => {
            alert(`Note from ${from}: ${payload.text}`);
        });

        // Send a note to all known peers
        const peers = await sdk.getPeers();
        const peerIds = peers.map(p => p.id);
        sdk.sendData(peerIds, { text: 'Hello decentralized world!' });
    }
}

startApp();

Complete Usage Example

This example shows a simple "Status Update" app. When launched through iCanText, it fetches your contacts and allows you to broadcast your current activity to them.

// 1. Initialize the SDK with a unique Application ID
		const sdk = new ICTBridgeSDK('p2p_status_tracker');

		async function setup() {
		    // 2. Start the handshake with the parent iCanText window
		    const connection = await sdk.init();

		    if (connection.status === 'STANDALONE') {
			showUIError('Please launch this app from within iCanText using /app');
			return;
		    }

		    // 3. Handle incoming data from other peers
		    sdk.onData((senderId, payload) => {
			console.log(`Peer ${senderId} is now: ${payload.status}`);
			updateStatusBoard(senderId, payload.status);
		    });

		    // 4. Discovery: Fetch the list of peers in the current Workspace
		    const peers = await sdk.getPeers();
		    renderContactList(peers);
		}

		// 5. Sending Data: Encrypted P2P transmission
		function broadcastMyStatus(newStatus) {
		    sdk.getPeers().then(peers => {
			const targetIds = peers.map(p => p.id);
			
			// This JSON object will be E2EE encrypted and routed via Sealed Forward
			const packet = { 
			    type: 'STATUS_UPDATE', 
			    status: newStatus,
			    timestamp: Date.now() 
			};

			sdk.sendData(targetIds, packet);
		    });
		}

		setup();

async function sayHello() {
    // 1. Create the message
    const msgId = await sdk.postMessage({ 
        text: "I am computing the results..." 
    });
    
    // 2. Simulate work and update the same message
    setTimeout(async () => {
        await sdk.editMessage(msgId, "Computation complete: 42 ✅");
    }, 3000);
}

// The author creates the poll message
sdk.postAppContent("https://poll.app/", 
    { question: "Which consensus is best?" }, 
    { interactionModel: 'OWNER_ONLY' } // Protect the question
);

const voteTally = {};

async function start() {
    await sdk.init();

    // Replay all votes from the Ledger (even if the author is offline)
    const history = await sdk.getAppEvents();
    history.forEach(evt => countVote(evt.senderId, evt.data.choice));

    // Listen for incoming votes from peers
    sdk.onAppEvent((senderId, data) => {
        countVote(senderId, data.choice);
        updateCharts();
    });
}

function castVote(myChoice) {
    // Anyone can emit an event, even if they don't own the parent message
    sdk.emitAppEvent({ choice: myChoice });
}

// list.php
<?php
$allowed_origins = [
    "https://icantext.com",
    "null" // Required for sandboxed iframes
];

if (isset($_SERVER['HTTP_ORIGIN'])) {
    $origin = $_SERVER['HTTP_ORIGIN'];
    if (in_array($origin, $allowed_origins)) {
        header("Access-Control-Allow-Origin: " . $origin);
        header("Access-Control-Allow-Credentials: true");
    }
}
// ... your logic here

const connection = await sdk.init();

if (connection.status === 'STANDALONE') {
    // Show the "How to install" guide or app description
    renderLandingPage(); 
} else {
    // Start the collaborative real-time logic
    initializeP2PLogic();
}

Best Practices

• Handle Disconnections: Always check window.opener before sending data; if the user closes iCanText, the bridge will break.
• Payload Size: While the P2P layer handles fragmentation, keep payloads under 1MB for optimal performance across the mesh.
• Origin Security: The SDK automatically ensures messages are only exchanged with the domain that launched the app.
• Validation: Always validate the structure of the payload received in onData as it comes from a remote peer's application instance.
• Frame Permissions: Your server must allow your app to be embedded in an iframe. Ensure your Content-Security-Policy does not have a restrictive frame-ancestors directive, and avoid the X-Frame-Options: DENY header.
• Choosing the right Model: Use updateAppContext for small, non-conflicting metadata (like the name of a room). Use Event Sourcing (emitAppEvent) for collaborative tools where multiple users act simultaneously to avoid data loss.
• Universal Ledger Lifecycle: When an app-event is emitted, it is stored by all peers in a dedicated memory space called the Ledger. This ledger is not limited by the standard 50-message chat history. However, to prevent memory leaks, iCanText automatically wipes the entire ledger of an app as soon as its parent message is deleted or expires.
• Decentralized Presence: When using onPeersUpdate, presence is reached via consensus. If a user closes their tab without signaling, they will transition to SUSPECT then OFFLINE within 3 cycles. This prevents "ghost" users in the UI while keeping network traffic minimal.
• Visual Comfort: Avoid forcing VIEWPORT fullscreen immediately upon app launch. Let the user trigger the expansion via a dedicated button to avoid breaking their reading flow.