hermers

README

hermers-go

Open-source Go client for Hermers — REST and native gRPC in one module.

The Hermers server is private / proprietary. This package is open source; it does not include or publish server source.

Client	Package	Default endpoint
rest.Hermes	rest	https://hermers.aduki.pro/v1
grpc.Client	grpc	grpc.aduki.pro:443 (TLS)

Requirements

• Go 1.25 (module declares go 1.25.0). With Go 1.21+, the toolchain auto-downloads 1.25 when needed (GOTOOLCHAIN=auto).

Install

go get github.com/aduki-org/hermers-go@v0.1.0

Quickstart (REST)

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aduki-org/hermers-go/rest"
)

func main() {
	hermes, err := rest.New("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
	if err != nil {
		log.Fatal(err)
	}
	me, err := hermes.Ready(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(me.Tenant, me.User)
	contacts, err := hermes.Contacts.List(context.Background(), nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(contacts.Total, "contacts")
}

Quickstart (gRPC)

package main

import (
	"context"
	"fmt"
	"log"

	hermesgrpc "github.com/aduki-org/hermers-go/grpc"
)

func main() {
	client, err := hermesgrpc.Connect(context.Background(), "hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	if _, err := client.Ready(context.Background()); err != nil {
		log.Fatal(err)
	}
	list, err := client.Contacts.List(context.Background(), nil, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(len(list.Items), "items")
}

Or via the root package:

import hermers "github.com/aduki-org/hermers-go"

h, _ := hermers.New("hm_live_…")
g, _ := hermers.Connect(ctx, "hm_live_…")

Authentication

API key only — Authorization: Key hm_live_… (REST) / metadata authorization: Key … (gRPC).

There are no login, password, or JWT refresh helpers. Prefer Ready(ctx) before the first resource call. Callers never pass tenant/user hex — identity comes from whoami cache.

Testing

go test ./...
export HERMERS_API_KEY=hm_live_…   # never commit secrets
go test ./...

Without HERMERS_API_KEY, unit tests still run; live suites no-op. Copy .env.example locally if you use dotenv tooling — never commit .env.

Docs

Developer documentation lives under docs/ — REST in docs/rest/, gRPC in docs/grpc/.

Documentation is published with mdBook (Rust-book UI). Book root is this package (book.toml + book/); chapters are assembled from docs/ and the module README into book/, then built to site/ for GitHub Pages.

Requires mdbook on PATH (e.g. cargo install mdbook) and Node.js ≥18 for the prepare/check scripts.

make docs-prepare   # sync docs/ + module README → book/
make docs-build     # prepare + mdbook build → site/
make docs-serve     # prepare + mdbook serve (http://localhost:3000)
make docs           # build + link/forbidden-string check

Or: ./scripts/docs-build.sh / ./scripts/docs-serve.sh.

License

MIT

Documentation

Overview

Package hermers is the official Hermers Go SDK (REST + gRPC).

The Hermers server is private / proprietary. This module is open source and describes the public client APIs only.

Prefer importing the rest and grpc subpackages:

import "github.com/aduki-org/hermers-go/rest"
import "github.com/aduki-org/hermers-go/grpc"

Index

• Constants
• func Connect(ctx context.Context, apiKey string) (*hermesgrpc.Client, error)
• func ConnectWithOptions(ctx context.Context, apiKey string, opts hermesgrpc.Config) (*hermesgrpc.Client, error)
• func New(apiKey string) (*rest.Hermes, error)
• func NewWithOptions(apiKey string, opts rest.Config) (*rest.Hermes, error)
• type GrpcConfig
• type GrpcIdentity
• type Hermes
• type HermesError
• type HermesGrpc
• type HermesGrpcError
• type Identity
• type RestConfig

Constants

const BaseEndpoint = hermesgrpc.BaseEndpoint

const BaseURL = rest.BaseURL

const Version = "0.1.0"

Version is the SDK semver.

Functions

func Connect

func Connect(ctx context.Context, apiKey string) (*hermesgrpc.Client, error)

Connect constructs a gRPC client with defaults.

func ConnectWithOptions

func ConnectWithOptions(ctx context.Context, apiKey string, opts hermesgrpc.Config) (*hermesgrpc.Client, error)

ConnectWithOptions constructs a gRPC client with options.

func New

func New(apiKey string) (*rest.Hermes, error)

New constructs a REST client with defaults.

func NewWithOptions

func NewWithOptions(apiKey string, opts rest.Config) (*rest.Hermes, error)

NewWithOptions constructs a REST client with options.

Types

type GrpcConfig

type GrpcConfig = hermesgrpc.Config

Re-export gRPC symbols.

type GrpcIdentity

type GrpcIdentity = hermesgrpc.Identity

Re-export gRPC symbols.

type Hermes

type Hermes = rest.Hermes

Re-export common REST symbols for a short import path.

type HermesError

type HermesError = rest.Error

Re-export common REST symbols for a short import path.

type HermesGrpc

type HermesGrpc = hermesgrpc.Client

Re-export gRPC symbols.

type HermesGrpcError

type HermesGrpcError = hermesgrpc.Error

Re-export gRPC symbols.

type Identity

type Identity = rest.Identity

Re-export common REST symbols for a short import path.

type RestConfig

type RestConfig = rest.Config

Re-export common REST symbols for a short import path.