kodoma-sdk-ts

Build agent-native messaging interfaces with one TypeScript SDK.

kodoma-sdk-ts gives you a single runtime for:

• unified inbound message streams
• platform-scoped spaces and send APIs
• reactions, threaded replies, and typing indicators (when supported)
• composable content builders (text, attachment, custom)

Install

npm i kodoma-sdk-ts

Quick Start

import { Kodama, definePlatform, text } from "kodoma-sdk-ts";

const terminal = definePlatform("terminal", {
  configDefault: {},
  lifecycle: {
    createClient: async () => ({
      async send(value: string) {
        console.log("[out]", value);
      }
    }),
    destroyClient: async () => {}
  },
  events: {
    messages: async function* () {
      // plug your provider stream here
      yield {
        id: "msg_1",
        sender: { id: "user_1" },
        space: { id: "space_1" },
        content: { type: "text", text: "hello" },
        timestamp: new Date()
      };
    }
  },
  actions: {
    send: async ({ client, content }) => {
      if (content.type === "text") {
        await client.send(content.text);
      }
    }
  }
});

const app = await Kodama({ providers: [terminal.config()] });

for await (const [space, message] of app.messages) {
  await space.responding(async () => {
    await space.send(text(`received ${message.content.type}`));
  });
}

Core Concepts

Kodama(...)

Creates the multi-provider runtime.

const app = await Kodama({
  projectId: process.env.KODAMA_PROJECT_ID,
  projectSecret: process.env.KODAMA_PROJECT_SECRET,
  providers: [providerA.config(), providerB.config()]
});

app.messages

Unified async stream of [space, message] tuples across all configured providers.

for await (const [space, message] of app.messages) {
  // route by message.platform / message.content.type
}

space

A platform-scoped context.

await space.send("plain text");
await space.startTyping();
await space.stopTyping();
await space.responding(async () => {
  await space.send("done");
});

message

Inbound message helper methods.

await message.react("like");
await message.reply("got it");

Content Builders

Text

import { text } from "kodoma-sdk-ts";
await space.send(text("hello"));

Attachment

import { attachment } from "kodoma-sdk-ts";
await space.send(
  attachment(fileBytes, { name: "report.pdf", mimeType: "application/pdf" })
);

Custom

import { custom } from "kodoma-sdk-ts";
await space.send(custom({ type: "card", title: "Order Updated" }));

Creating a Platform Adapter

Use definePlatform(name, def) to register your own provider:

• lifecycle.createClient: initialize SDK/API client
• events.messages: async iterable of provider messages
• actions.send: send content into a platform space
• optional actions.replyToMessage, actions.reactToMessage, actions.startTyping, actions.stopTyping

Scripts (package local)

From packages/kodoma-sdk-ts:

bun run typecheck
bun run build
bun run example

Publishing to npm

1. Login:

npm login

2. Build and dry-check tarball:

bun run build
npm pack

3. Publish:

npm publish --access public

If the package name is already taken, update name in package.json (for example to a scoped package like @your-scope/kodoma-sdk-ts) and publish again.

License

PolyForm Noncommercial 1.0.0. See LICENSE.