Texts Platform SDK

Overview

The Texts Platform SDK is an open-source TypeScript SDK that enables developers to build platform integrations for Texts.app - a unified messaging application. It provides a comprehensive set of interfaces and utilities for connecting messaging platforms to the Texts unified inbox.

28 stars | 6 forks | 436 commits | 13 contributors | MIT License | 100% TypeScript

Loading an External Platform

Option 1: Using the Command Palette

1. Hit ⌘J (or Ctrl+J on Windows/Linux) 2. Type "install platform" 3. Click "Load platform directory" (directory should point to the JavaScript files) 4. Relaunch Texts.app

Option 2: Edit config.json directly. Create ~/Library/Application Support/jack/config.json:

open -a "Visual Studio Code" ~/Library/App*Sup*/jack/config.json

Then paste in:

{
  "developer_mode": true,
  "external_platforms": [
    "/Users/kb/Dropbox/Texts/packages/platform-random"
  ]
}

Viewing Logs

Run this in Terminal.app:

/Applications/Texts.app/Contents/MacOS/Texts --log-level=dev

Architecture

A platform integration can be roughly divided into three parts:

1. Network Layer: Responsible for sending network requests and subscribing to real-time events (code goes into network-api.ts or imported from a third party module) 2. Mapping Layer: Converts original platform data structures into structures that Texts understands (mappers.ts) 3. PlatformAPI Interface: Binds the network layer, mapping layer and implements an interface that Texts can call (api.ts) Information and attributes about the platform go into the info.ts file.

Getting Started

1. Get the network layer working first. Write a simple CLI script that connects to the platform, fetches the threads/messages and prints it to the console:

node dist/script.js

2. Once working with node, test if it runs with Electron (will work fine unless there are native dependencies):

electron dist/script.js

3. After getting the network layer working, proceed with creating the integration using the platform boilerplate.

Core Data Structures

The SDK defines four main objects: • Message: A single message belonging to a thread • Thread: A thread that can contain many messages and many participants along with pagination information • User: A user present on the platform • Participant: A User extended with properties like isAdmin or hasExited, belonging to a thread

Building

While developing, run this to automatically transpile TypeScript files to JavaScript on changes:

tsc --watch

Implementation Priority

Prioritized order for implementing PlatformAPI functionality: 1. Authentication (init, getCurrentUser, login, serializeSession) 2. getThreads 3. getMessages 4. sendMessage 5. Additional features...

Key SDK Features

User-Agent

platform-sdk exports a texts object. texts.constants.USER_AGENT provides the User-Agent to use for all network interactions. The browser login window will use this User-Agent constant as well.

Cookie Jar

We recommend using methods exposed by texts.createHttpClient for all network interactions since it handles the cookie jar automatically – new cookies sent by the server will automatically be updated in the jar. This jar should be serialized by serializeSession so that it's persisted.

ReAuthError

When the user logs out from all sessions using a regular web browser, the session will be invalid and throw an error. This error must be handled gracefully and instead ReAuthError should be thrown. This will cause Texts to ask the user to re-authenticate the account.

Electron Intricacies

Native deps must be recompiled for Electron since Electron ships with a patched version of Node.js. electron-rebuild lets you do this. Native deps depending on N-API don't need recompilation. The Electron desktop app runs three processes/threads: • Main process (no platform code is loaded) • Renderer process (PlatformInfo is loaded from info.ts) • Worker thread (PlatformAPI is loaded from api.ts)

Native Dependencies

If your platform integration uses native deps, for correct bundling, also list them under a nativeDeps key in package.json:

{
  "nativeDeps": {
    "erlpack": "^0.1.4"
  },
  "dependencies": {
    "erlpack": "^0.1.4"
  }
}

Contributors

13 contributors: @KishanBagaria (creator), @adiwajshing, @slice, @1Conan, @SilverBirchh, @kabiroberai, @rumblefrog, @rdev, @ridafkih, @TextsBot, @batuhan, @rnons, @evowizz

Links

View the full source code and documentation on GitHub