API reference

This page is a quick reference for the stable, bot-facing part of Osmose. Generated protobuf packages remain available under proto/ for advanced use.

Client

Create a client with the two required settings:

client, err := osmose.New(osmose.Config{
	Token:    os.Getenv("OSMIUM_TOKEN"),
	ClientID: 123456,
})

New validates the configuration and applies defaults. Client exposes these services:

Lifecycle

Run handles the normal lifecycle. Network failures reconnect with bounded backoff. Known rejected-authorization failures and protocol mismatches are permanent errors; other authorization RPC failures remain retryable. Reconnects happen inside a single Run; after it finishes, the client cannot be run again.

Events

All typed event handlers have this shape:

func(context.Context, *Event) error

Registration returns a function that removes that handler.

Message create and interaction events provide a Reply(ctx, content) helper. Interaction events also provide Respond, Acknowledge, and Defer. Every event provides Client(). ConnectionEvent contains Attempt, State, RetryIn, and Err.

Handler errors and panics are logged. Configure Config.OnHandlerError to observe them programmatically; it runs on the event worker after the handler and must not block.

Event dispatch is bounded. When the queue is full, the update is dropped so the socket reader remains responsive. Client.DroppedEvents() returns the cumulative count and Config.OnEventOverflow receives that count after each drop. The overflow callback runs on the socket reader and must not block.

Collectors

MessageCollectorOptions supports Chat, AuthorID, Filter, Time, Idle, Max, and Buffer. The collector uses the existing bounded event workers and never creates a goroutine per incoming message.

InteractionCollectorOptions supports UserID, MessageID, Data, Filter, Time, Idle, Max, and Buffer. ReactionCollectorOptions supports Chat, MessageID, Filter, Time, Idle, Max, and Buffer.

Public models

The types package contains small models shared by events and services:

Use constructors for chat references:

types.SelfChat()
types.UserChat(userID)
types.GroupChat(groupID)
types.ChannelChat(communityID, channelID)

Service responses retain the original generated value in Raw where a response has a wrapper model. This keeps common code typed while preserving access to advanced protocol fields when needed.

Errors

Use errors.Is and errors.As instead of matching error strings.

if errors.Is(err, osmose.ErrPermanent) {
	// Fix credentials or the protocol/client version before retrying.
}

var rpcErr *osmose.RPCError
if errors.As(err, &rpcErr) {
	log.Printf("RPC %d: %s", rpcErr.Code, rpcErr.Message)
}

RPCError preserves the server code, message, and optional trace ID.

Raw API

When a high-level service does not cover an endpoint, call it with a generated protobuf request:

import protoCommunities "github.com/ofabiodev/osmose/proto/communities"

result, err := client.Raw().Call(ctx, &protoCommunities.GetCommunities{})
if err != nil {
	return err
}

communities := result.GetCommunities()

The raw API is intentionally separate from the common service API. Request wrapping is generated and runtime dispatch does not use reflection.

Configuration

Config requires Token and ClientID. Optional fields include:

Zero values use sensible defaults.