@openpalm/channels-sdk

Public SDK for building OpenPalm channel adapters. Extend BaseChannel and implement handleRequest() to create a new channel — boilerplate for health checks, HMAC signing, guardian forwarding, and structured logging is handled for you.

Bun required. This package ships TypeScript source and relies on Bun's native TS execution. It does not compile to JavaScript and is not compatible with Node.js.

Install

bun add @openpalm/channels-sdk

Quick start

import { BaseChannel, type HandleResult } from "@openpalm/channels-sdk";

export default class MyChannel extends BaseChannel {
  name = "my-channel"; // forwarded payload channel identifier

  async handleRequest(req: Request): Promise<HandleResult | null> {
    const body = await req.json() as Record<string, unknown>;
    const text = typeof body.text === "string" ? body.text.trim() : "";
    const userId = typeof body.userId === "string" ? body.userId.trim() : "";
    if (!userId || !text) return null;
    return { userId, text };
  }
}

Set CHANNEL_PACKAGE=@scope/my-channel in your registry overlay to have the channel image install and run it automatically.

API

BaseChannel (abstract)

| Member | Description | |---|---| | name | Channel identifier used in forwarded guardian payloads | | port | Listen port (default: PORT env or 8080) | | guardianUrl | Guardian target — hardcoded to http://guardian:8080 (the in-network service name) | | secret | HMAC secret — loaded from the file path in CHANNEL_SECRET_FILE | | handleRequest(req) | Implement this — parse request, return { userId, text } or null | | route(req, url) | Optional — override for custom routing before handleRequest | | start() | Start the Bun HTTP server | | createFetch(mockFetch?) | Return fetch handler for unit testing (no server started) | | forward(result) | Sign and POST to guardian (called by base class automatically) | | log(level, event, ctx) | Structured JSON logger | | json(status, body) | Build a JSON Response |

Exports

export { BaseChannel, type HandleResult } from "./channel-base.ts";
export { ERROR_CODES, validatePayload, type ChannelPayload, ... } from "./channel.ts";
export { buildChannelMessage, forwardChannelMessage } from "./channel-sdk.ts";
export { signPayload, verifySignature } from "./crypto.ts";
export { createLogger, type LogLevel } from "./logger.ts";

Guardian error codes

The guardian returns these error strings in its JSON error responses. Channel adapters should handle them:

| Code | HTTP | Cause | |---|---|---| | invalid_json | 400 | Request body is not parseable JSON | | invalid_payload | 400 | Missing/wrong-type fields or out-of-bounds lengths | | payload_too_large | 413 | Body exceeds 100 KB | | invalid_signature | 403 | HMAC mismatch, unknown channel, or missing signature | | replay_detected | 409 | Nonce was already seen within the 5-minute window | | rate_limited | 429 | Per-user (120 req/min) or per-channel (200 req/min) limit exceeded | | content_blocked | 403 | Message blocked by the guardian's content-validation stage (opt-in, fail-closed; only returned when GUARDIAN_CONTENT_VALIDATION is enabled) | | assistant_unavailable | 502 | Guardian could not reach or get a response from the assistant | | not_found | 404 | Unrecognised guardian endpoint |

All error responses include { error: "<code>", requestId: "<uuid>" }.

Testing

import { describe, test, expect } from "bun:test";
import MyChannel from "./my-channel.ts";

const channel = new MyChannel();
const handler = channel.createFetch();

const resp = await handler(new Request("http://localhost/", {
  method: "POST",
  body: JSON.stringify({ userId: "u1", text: "hello" }),
}));
expect(resp.status).toBe(200);

See src/channel-base.test.ts for a full test suite.

Secret configuration

Channel containers read their outbound HMAC secret from CHANNEL_SECRET_FILE, which must point at a mounted secret file. The guardian reads the matching verification secret from CHANNEL_<NAME>_SECRET_FILE, where <NAME> is the uppercase channel ID used by the addon overlay, for example CHANNEL_SLACK_SECRET_FILE.

Do not pass raw HMAC secrets through stack.env, service-level env_file, or direct environment values. Stack overlays should grant a Docker Compose secret to both the channel service and guardian, then set only the *_FILE variables to the in-container secret paths.

Full guide

docs/community-channels.md