Zum Inhalt springen

Client libraries: mykit and mybot

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

Two libraries, each in Go and in TypeScript with the same behavior, do the plumbing the other guides describe. They are MIT-licensed, so you can use them in software under any license.

Library For Go TypeScript
mykit Any client of the API github.com/mycroblog/my/pkg/mykit @mycroblog/mykit
mybot Bots, built on mykit github.com/mycroblog/my/pkg/mybot @mycroblog/mybot

The full API is on pkg.go.dev and in the types of the npm packages; the READMEs (mykit, mybot) go deeper than this page. Mastodon client libraries do not work with this server (getting a token).

mykit’s types and requests are generated from the OpenAPI document of the API, so every operation is there with typed parameters and answers; there are no per-endpoint helper functions. The hand-written layer adds the access token and its renewal, Accept-Language, errors, paging, retries, idempotency keys, media upload, PKCE, and the event stream.

Install it. The Go module has its own go.mod, so none of the server’s dependencies reach your go.sum. The TypeScript package is ESM only and runs where fetch and web streams do (Node.js 22 or later, Bun, Deno, browsers).

Terminal window
go get github.com/mycroblog/my/pkg/mykit
npm install @mycroblog/mykit

Post with a token you already have (see getting a token):

api, err := mykit.New(mykit.Config{
Server: "https://example.com", // the origin, without a path
TokenSource: mykit.StaticToken(os.Getenv("MY_TOKEN")),
UserAgent: "mybot/1.0",
})
if err != nil {
return err
}
resp, err := api.CreateStatusWithResponse(ctx, &mykit.CreateStatusParams{}, mykit.CreateStatusRequest{
Text: "Hello, fediverse!",
Visibility: mykit.VisibilityPublic,
})
if err != nil {
return err
}
fmt.Println("posted", resp.JSON201.Id)
import { createClient, staticToken } from "@mycroblog/mykit";
const api = createClient({
server: "https://example.com", // the origin, without a path
tokenSource: staticToken(process.env.MY_TOKEN!),
});
const { data } = await api.POST("/statuses", { body: { text: "Hello, fediverse!", visibility: "public" } });
console.log(data?.id);

mykit never stores tokens: you give it a token source and you save the tokens. For anything that runs longer than an access token lives (an hour), use NewRefreshingTokenSource (Go) or RefreshingTokenSource (TypeScript), which renews the token when it has expired or the server answers 401, and serializes the renewals. The server rotates the refresh token on every use, so the callback you give it (onTokens) must save the new tokens before they are used again. OAuthConfig, NewCodeVerifier and CodeChallenge (newCodeVerifier, codeChallenge and exchange in TypeScript) run the authorization code flow with PKCE.

mykit.All (Go, an iter.Seq2) and all (TypeScript, an AsyncIterable) follow the next_cursor of the paging and fetch a page when your loop needs it.

for status, err := range mykit.All(ctx, func(ctx context.Context, cursor *mykit.Cursor) ([]mykit.Status, *mykit.Cursor, error) {
resp, err := api.GetHomeTimelineWithResponse(ctx, &mykit.GetHomeTimelineParams{Cursor: cursor})
if err != nil {
return nil, nil, err
}
return resp.JSON200.Items, resp.JSON200.NextCursor, nil
}) {
if err != nil {
return err
}
fmt.Println(status.Id)
}

An answer of 400 or more is an error that carries the problem document: a *mykit.Problem in Go (use errors.As) and a ProblemError in TypeScript, with Type, Title, Status, Detail, and the extension members. A request that got no answer is a *mykit.NetworkError (NetworkError), and a failure at the token endpoint an *mykit.OAuthError (OAuthError). Branch on the type and the status, never on the text.

var problem *mykit.Problem
if errors.As(err, &problem) && problem.Type == "/api/v1/problems/blocking" {
// ...
}

A 429 or 503 is retried up to 3 times after the Retry-After it gives, when the request is safe to repeat (GET, HEAD, and every write but the few whose answer carries a secret or that each call must reach the audit log). The server applies a write with an Idempotency-Key once, so mykit adds a key to every write that takes one, sends the same key on every retry, and sends a write that got no answer, or whose key is still in use (a 409 with Retry-After), again with it. A NetworkError carries the key, so you can send the request again with it and it is applied once. Retry in the configuration changes or turns off the retries; see rate limits.

API.Stream (Go) and runStream (TypeScript) read the event stream as typed events, reconnect with a backoff or after Retry-After, treat 60 seconds without even a heartbeat as a failure, and stop on a final 4xx. They do not replay anything: OnOpen (onOpen) tells you when a stream opens again so that you can read the home timeline and the notifications once more. In TypeScript, runStream also reads the local and federated timeline streams. Do not set a Timeout on the http.Client of the Go client; it would end every stream.

mybot builds bots on mykit. You write the handlers of the bot’s events (OnMention, OnCommand, OnFollow, and others) and the library receives the events so that none is lost or answered twice across disconnections and restarts, runs scheduled jobs (Every), and keeps the bot polite by default. It keeps its state, such as the newest refresh token and the notifications it has handled, in a file, so run it with storage that survives a restart.

Terminal window
go get github.com/mycroblog/my/pkg/mybot
npm install @mycroblog/mybot
bot, err := mybot.New(mybot.Config{
Server: "https://example.com",
OAuth: &mykit.OAuthConfig{ClientID: os.Getenv("CLIENT_ID"), ClientSecret: os.Getenv("CLIENT_SECRET")},
RefreshToken: os.Getenv("REFRESH_TOKEN"),
UserAgent: "echobot/1.0",
})
if err != nil {
log.Fatal(err)
}
bot.OnMention(func(c *mybot.Context) error {
_, err := c.Reply(c.Text)
return err
})
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := bot.Run(ctx); err != nil {
log.Fatal(err)
}
import { Bot } from "@mycroblog/mybot";
const bot = new Bot({
server: "https://example.com",
oauth: { clientId: process.env.CLIENT_ID!, clientSecret: process.env.CLIENT_SECRET! },
refreshToken: process.env.REFRESH_TOKEN!,
userAgent: "echobot/1.0",
});
bot.onMention(async (ctx) => {
await ctx.reply(ctx.text);
});
const controller = new AbortController();
process.once("SIGINT", () => controller.abort());
await bot.run({ signal: controller.signal });

A bot acts as a user, so run it on an account of its own and give it the bot flag (the account’s setting, or Config.SetBotFlag in Go with the scope write:accounts). To get its credentials:

  1. Sign in as the bot’s account and open Settings → Apps → Your apps.
  2. Register an app of the type Confidential, with http://127.0.0.1/callback as its redirect URI and at least the scopes read:accounts, read:notifications, read:statuses, and write:statuses.
  3. Copy the client ID and the secret, which is shown once.
  4. Press Issue token on the app. The server shows an access token and a refresh token for your account once, without a redirect. Pass the refresh token to the bot; it gets its own access tokens and saves each rotated refresh token.

A bot without the scopes it needs stops at start with a scope error. Both packages ship a test harness (mybottest for Go, @mycroblog/mybot/testing for TypeScript) for testing handlers without a server, and the READMEs list runnable examples: an echo bot, a scheduled greeting, and a command bot.

Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt

Analyse auf dieser Website