bibleit

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 19, 2026 License: MIT Imports: 13 Imported by: 0

README

Bibleit Go client

A Go SDK for Bibleit REST resources, registered OAuth clients, and SSH command construction/decoding. HTTP resources use the pinned https://api.bibleit.app/v1 service. Browser authentication uses https://bibleit.app. There is no command-style HTTP transport.

The module is released independently from the Bibleit CLI. Use the Go version in go.mod. The SDK does not read CLI configuration, open browsers, store credentials, or depend on the CLI.

Installation

go get github.com/bibleit-labs/bibleit-go

REST resources

Import github.com/bibleit-labs/bibleit-go/rest. The client includes all 88 REST operations, generated schemas, response metadata, conditional writes, binary streams, versioned Live event polling and lazy whole-book page iterators. See REST usage and the runnable reading example.

client, err := rest.NewClient(token, nil)
if err != nil { return err }
response, err := client.GetPersonalIdentity(ctx, nil)
if err != nil { return err }
defer response.Body.Close()
var identity rest.PersonalIdentity
if err := response.Decode(&identity); err != nil { return err }
fmt.Println(identity.ID, identity.PersonalAccountID)

Credentials are explicit: finite personal bt_, delegated oa_, or organization svc_ tokens. The server enforces their separate scopes and resource boundaries. ProblemError exposes HTTP status, stable code, request ID and response headers. Operations never retry automatically; redirects are blocked and TLS verification is enabled. The host cannot be overridden through configuration or environment.

SSH protocol helpers

The parent bibleit package contains validated command builders, response parsers and typed domain helpers for SSH. It does not open SSH connections. Applications supply their own SSH executor to NewSSHClient:

client, err := bibleit.NewSSHClient(func(ctx context.Context, cmd bibleit.Command) (bibleit.Response, error) {
    // Execute cmd.String() over your verified SSH connection, then decode stdout.
    return bibleit.DecodeCommandResponse(cmd, stdout)
})

The executor owns SSH authentication, host-key verification and connection lifetime. The CLI uses OpenSSH to bibleit.app:22. Persistent Live subscriptions use the streaming protocol directly, rather than the finite executor. Protocol fixtures document quoting and response framing. No command-to-REST adapter is provided. Bearer credential clients cannot execute commands; NewClient / NewClientWithHTTPClient remain only for browser-issued CLI credential revocation.

Browser login and registered OAuth

NewAuthClient / NewAuthClientWithHTTPClient exchange an approved CLI browser code with ExchangeCode. The application validates callback state, supplies the PKCE verifier and securely stores the result. Revoke that browser-issued CLI credential with NewClient(token).RevokeCredential(ctx) (handling construction errors as usual). The token exchange and logout endpoints remain supported.

For registered delegated OAuth clients use the separate rest.NewOAuthClient: S256 consent URLs, metadata, code exchange, refresh rotation and revocation stay on the website origin. Codes and refresh tokens are single-use. The SDK never retries an ambiguous exchange or refresh attempt.

Development

See CONTRIBUTING.md, SECURITY.md, and the REST contract regeneration instructions.

GOWORK=off go test -race ./...
GOWORK=off go vet ./...

Licensed under MIT.

Generated-code and dependency redistribution notices are retained in THIRD_PARTY_NOTICES, alongside the project MIT license.

Documentation

Overview

Package bibleit provides a client for Bibleit Server protocol v1. It does not read CLI configuration, open browsers, or manage credentials.

Index

Constants

View Source 
const MaxCommandBytes = 8192
View Source 
const MaxRequestBytes = 16384
View Source 
const ServerEndpoint = "https://bibleit.app"

ServerEndpoint is the project-managed browser authentication origin. Applications cannot override it through configuration or environment variables. HTTPS certificate verification is enabled by the default transport.

Variables

View Source 
var ErrIncompleteTerm = errors.New("unterminated protocol term")

ErrIncompleteTerm means an opaque compound field needs another input line. Stream readers may append the next line and retry ParseRecord.

Functions

This section is empty.

Types

type AccountInfo 

type AccountInfo struct {
	Actor, DisplayName, Handle, AvatarURL, Locale, Theme string
	Plan, PlanName, PlanSource                           string
	PlanActivatedAt                                      int64
	Lives, Translations, Tokens, Keys                    int64
	Raw                                                  Response
}

type AuthClient 

type AuthClient struct {
	// contains filtered or unexported fields
}

AuthClient exchanges an approved browser code. It does not run a browser, validate callback state, persist credentials, or retry a consumed code.

func NewAuthClient 

func NewAuthClient() (*AuthClient, error)

NewAuthClient creates an unauthenticated client for browser-code exchange.

func NewAuthClientWithHTTPClient 

func NewAuthClientWithHTTPClient(httpClient *http.Client) (*AuthClient, error)

NewAuthClientWithHTTPClient configures transport/timeouts for code exchange at the same fixed service endpoint. It copies the supplied HTTP client.

func (*AuthClient) ExchangeCode 

func (c *AuthClient) ExchangeCode(ctx context.Context, exchange CodeExchange) (AuthorizationResult, error)

ExchangeCode redeems an approved one-use code with its PKCE verifier. Even a rejected verifier can consume the code on the current server.

type AuthorizationResult 

type AuthorizationResult struct {
	Actor, IdentityName, DisplayName, AuthProvider, TokenID, AccessToken string
	Fields                                                               map[string]json.RawMessage
}

AuthorizationResult contains a secret AccessToken; Fields also contains the original JSON response, including that secret. Callers own secure storage.

type CatalogBook 

type CatalogBook struct {
	ID       int64 // Server source book identifier; not the book's position in Books.
	Name     string
	Chapters []CatalogChapter
	Fields   map[string]string
}

type CatalogChapter 

type CatalogChapter struct {
	Number int64
	// Verses is the highest source verse identifier, not the number of present
	// rows. Editions may omit identifiers; reading an omitted verse fails.
	Verses int64
	Fields map[string]string
}

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(apiToken string) (*Client, error)

NewClient creates a credential client for browser-issued CLI token revocation. It cannot execute commands. Use package rest for HTTP resource operations. The default HTTP timeout is 15 seconds. Operations are never retried automatically.

func NewClientWithHTTPClient 

func NewClientWithHTTPClient(apiToken string, httpClient *http.Client) (*Client, error)

NewClientWithHTTPClient configures browser-credential revocation transport/timeouts. The origin stays fixed; the supplied client is copied and redirects are blocked.

func NewSSHClient added in v0.1.0 

func NewSSHClient(execute func(context.Context, Command) (Response, error)) (*Client, error)

NewSSHClient binds command helpers to an explicit caller-owned SSH executor. Bearer credential clients cannot execute commands; use package rest for HTTP.

func (*Client) ControlLive 

func (c *Client) ControlLive(ctx context.Context, id string, action LiveAction) (LiveActionResult, error)

func (*Client) CreateLive 

func (c *Client) CreateLive(ctx context.Context, name string) (LiveResult, error)

func (*Client) Execute 

func (c *Client) Execute(ctx context.Context, command Command) (Response, error)

func (*Client) GetAccountInfo 

func (c *Client) GetAccountInfo(ctx context.Context) (AccountInfo, error)

func (*Client) GetIdentity 

func (c *Client) GetIdentity(ctx context.Context) (IdentityInfo, error)

func (*Client) GetLive 

func (c *Client) GetLive(ctx context.Context, id string) (LiveResult, error)

func (*Client) GetLiveStack 

func (c *Client) GetLiveStack(ctx context.Context, id string) (LiveStack, error)

func (*Client) GetLiveStats 

func (c *Client) GetLiveStats(ctx context.Context, id string) (LiveStatistics, error)

func (*Client) GetOrganizationApplicationStatus added in v0.0.2 

func (c *Client) GetOrganizationApplicationStatus(ctx context.Context, id string) (OrganizationApplicationResult, error)

func (*Client) GetServerInfo 

func (c *Client) GetServerInfo(ctx context.Context) (ServerInfo, error)

func (*Client) GetTranslationCatalog 

func (c *Client) GetTranslationCatalog(ctx context.Context, slug string) (TranslationCatalog, error)

func (*Client) GetTranslationInfo 

func (c *Client) GetTranslationInfo(ctx context.Context, slug string) (TranslationInfo, error)

func (*Client) Help 

func (c *Client) Help(ctx context.Context, topic string) (HelpResult, error)

func (*Client) Identity 

func (c *Client) Identity(ctx context.Context) (Response, error)

func (*Client) ListLives 

func (c *Client) ListLives(ctx context.Context) (LiveList, error)

func (*Client) ListOrganizations added in v0.0.2 

func (c *Client) ListOrganizations(ctx context.Context, cursor string) (OrganizationDirectory, error)

func (*Client) ListQuotas 

func (c *Client) ListQuotas(ctx context.Context) (QuotaResult, error)

func (*Client) ListTokens 

func (c *Client) ListTokens(ctx context.Context) (TokenList, error)

ListTokens lists active personal token metadata. The server filters expired, revoked and expired rotation-grace credentials; it does not return a history.

func (*Client) ListTranslations 

func (c *Client) ListTranslations(ctx context.Context) (Response, error)

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) (Response, error)

func (*Client) PopLive 

func (c *Client) PopLive(ctx context.Context, id string, count int) (LiveVerseResult, error)

func (*Client) PushLive 

func (c *Client) PushLive(ctx context.Context, id string, ref Reference) (LiveVerseResult, error)

func (*Client) Read 

func (c *Client) Read(ctx context.Context, ref Reference) (Response, error)

func (*Client) ReadVerses 

func (c *Client) ReadVerses(ctx context.Context, ref Reference) (Reading, error)

func (*Client) RevokeCredential 

func (c *Client) RevokeCredential(ctx context.Context) error

RevokeCredential revokes this client's bearer credential via CLI logout. Only HTTP 204 is a successful acknowledgement; errors never mutate the client.

func (*Client) Search 

func (c *Client) Search(ctx context.Context, translation, query string) (Response, error)

func (*Client) SearchVerses 

func (c *Client) SearchVerses(ctx context.Context, translation, query string) (Reading, error)

func (*Client) SetLive 

func (c *Client) SetLive(ctx context.Context, id string, field LiveField, values ...string) (LiveResult, error)

type CodeExchange 

type CodeExchange struct {
	Code, Verifier, DeviceName string
}

type Command 

type Command struct {
	// contains filtered or unexported fields
}

Command is a validated customer operation. Its zero value is invalid. String exposes the wire representation for transport adapters; it may contain secrets.

func AccountInfoCommand 

func AccountInfoCommand() Command

func AccountQuotasCommand 

func AccountQuotasCommand() Command

func AccountTokensCommand 

func AccountTokensCommand() Command

func AddTranslationCommand 

func AddTranslationCommand(slug string) (Command, error)

func CreateLiveCommand 

func CreateLiveCommand(name string) (Command, error)

func DeleteAllLivesCommand 

func DeleteAllLivesCommand() Command

func HelpCommand 

func HelpCommand(topic string) (Command, error)

HelpCommand asks the server for commands visible to the current principal. An empty topic selects the root. The server decides permission visibility.

func IdentityCommand 

func IdentityCommand() Command

func LiveCommand 

func LiveCommand(id string, action LiveAction) (Command, error)

func LiveListCommand 

func LiveListCommand() Command

func LiveSecretCommand 

func LiveSecretCommand(id string, action SecretAction, value string) (Command, error)

func LiveStackCommand 

func LiveStackCommand(id string, action StackAction) (Command, error)

func OrganizationApplicationStatusCommand added in v0.0.2 

func OrganizationApplicationStatusCommand(id string) (Command, error)

func OrganizationListCommand added in v0.0.2 

func OrganizationListCommand(cursor string) (Command, error)

OrganizationListCommand returns one page; pass the previous Next cursor unchanged.

func PingCommand 

func PingCommand() Command

func PopLiveCommand 

func PopLiveCommand(id string, count int) (Command, error)

func PushLiveCommand 

func PushLiveCommand(id string, ref Reference) (Command, error)

func ReadCommand 

func ReadCommand(ref Reference) (Command, error)

func RemoveTranslationCommand 

func RemoveTranslationCommand(slug string) (Command, error)

func SearchCommand 

func SearchCommand(translation, query string) (Command, error)

func ServerInfoCommand 

func ServerInfoCommand() Command

func SetLiveCommand 

func SetLiveCommand(id string, field LiveField, values ...string) (Command, error)

func TranslationCatalogCommand 

func TranslationCatalogCommand(slug string) (Command, error)

func TranslationInfoCommand 

func TranslationInfoCommand(slug string) (Command, error)

func TranslationListCommand 

func TranslationListCommand() Command

func (Command) Streaming 

func (c Command) Streaming() bool

func (Command) String 

func (c Command) String() string

type HTTPError 

type HTTPError struct {
	StatusCode int
	Code       string
	Fields     map[string]any
}

HTTPError represents a failure without a usable protocol error envelope.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type HelpEntry 

type HelpEntry struct {
	Usage, Summary string
	// Auth is "none" when the server omits the auth field.
	Auth   string
	Fields map[string]string
}

type HelpResult 

type HelpResult struct {
	Authenticated bool
	Commands      []HelpEntry
	Raw           Response
}

type IdentityInfo 

type IdentityInfo struct {
	Actor, DisplayName, IdentityName, AuthProvider, KeyFingerprint string
	Authenticated                                                  bool
	Roles, Permissions                                             []string
	Raw                                                            Response
}

type LiveAction 

type LiveAction string
const (
	LiveInfo      LiveAction = "INFO"
	LiveStats     LiveAction = "STATS"
	LiveStart     LiveAction = "START"
	LiveStop      LiveAction = "STOP"
	LivePause     LiveAction = "PAUSE"
	LiveResume    LiveAction = "RESUME"
	LiveClear     LiveAction = "CLEAR"
	LiveDelete    LiveAction = "DELETE"
	LiveSubscribe LiveAction = "SUBSCRIBE"
)

type LiveActionResult 

type LiveActionResult struct {
	State  *LiveState
	Paused *bool
	Event  string
	Raw    Response
}

LiveActionResult reflects the server acknowledgement without fetching state.

type LiveConnection 

type LiveConnection struct {
	Actor, Access                    string
	ConnectedAt, ConnectedForSeconds int64
	Fields                           map[string]string
}

type LiveField 

type LiveField string
const (
	LiveName         LiveField = "NAME"
	LiveReference    LiveField = "REFERENCE"
	LiveTranslations LiveField = "TRANSLATIONS"
)

type LiveList 

type LiveList struct {
	Lives []LiveState
	Raw   Response
}

type LiveResult 

type LiveResult struct {
	Live LiveState
	Raw  Response
}

type LiveStack 

type LiveStack struct {
	ID      string
	Entries []StackEntry
	Raw     Response
}

type LiveState 

type LiveState struct {
	ID, Name, Status                            string
	Paused                                      bool
	Reference, Owner, CreatedBy, OrganizationID *string
	Owned, Protected                            *bool
	CreatedAt                                   *int64
	Translations                                []string
	Fields                                      map[string]string
}

type LiveStatistics 

type LiveStatistics struct {
	ID                                                                                string
	RunningForSeconds, Revision, StackEntries, ActorConnections, AnonymousConnections int64
	Connections                                                                       []LiveConnection
	Raw                                                                               Response
}

type LiveVerse 

type LiveVerse struct {
	Translation, Reference, Text string
	Fields                       map[string]string
}

type LiveVerseResult 

type LiveVerseResult struct {
	Event  string
	Verses []LiveVerse
	Raw    Response
}

type OrganizationApplicationResult added in v0.0.2 

type OrganizationApplicationResult struct {
	Application OrganizationDirectoryEntry
	Raw         Response
}

type OrganizationDirectory added in v0.0.2 

type OrganizationDirectory struct {
	Entries []OrganizationDirectoryEntry
	Next    *string
	Raw     Response
}

type OrganizationDirectoryEntry added in v0.0.2 

type OrganizationDirectoryEntry struct {
	Kind, ID, ApplicationID, Handle, Name, Domain, Role      string
	Verification, Status, State, NextAction, VerificationURL string
	OrganizationID                                           *string
	Fields                                                   map[string]string
}

OrganizationDirectoryEntry represents either a membership or a private application. State and verification strings remain open to future server values.

type Quota 

type Quota struct {
	Permission string
	Limit      QuotaLimit
	Used       int64
	Fields     map[string]string
}

type QuotaLimit 

type QuotaLimit struct {
	Unlimited bool
	Value     int64 // Meaningful only when Unlimited is false.
}

type QuotaResult 

type QuotaResult struct {
	Quotas []Quota
	Raw    Response
}

type Reading 

type Reading struct {
	Translation string
	// Header coordinates describe the requested range; per-verse source metadata
	// is available in Verses when supplied by the server.
	Book, Chapter, Verse *int64
	Verses               []VerseText
	Raw                  Response
}

type Record 

type Record struct {
	Type   string
	Fields map[string]string
	Order  []string
}

Record preserves unknown v1 fields and their wire order.

func ParseRecord 

func ParseRecord(line string) (Record, error)

ParseRecord decodes response quoting and escaping, rejecting truncated strings.

type Reference 

type Reference struct {
	Translation string
	Book        string
	Chapter     int
	Verse       int
}

Reference identifies a book, chapter, or verse. Zero chapter/verse means omitted.

type RequestSizeError 

type RequestSizeError struct {
	Part  string
	Bytes int
	Limit int
}

RequestSizeError reports a request rejected locally before any network call.

func (*RequestSizeError) Error 

func (e *RequestSizeError) Error() string

type Response 

type Response struct {
	Lines   []string
	Records []Record
}

Response retains original lines for CLI raw output. END is excluded. Protocol v1 fields remain strings; future typed models can build on Records.

func DecodeCommandResponse 

func DecodeCommandResponse(command Command, reader io.Reader) (Response, error)

DecodeCommandResponse uses the command's framing contract for a finite reply. Account translation replies contain count but are single records without END.

func DecodeResponse 

func DecodeResponse(reader io.Reader) (Response, error)

DecodeResponse decodes one finite HTTP or SSH-exec reply, requiring END for multi-record replies. It is not a decoder for a persistent SSH subscription.

type SecretAction 

type SecretAction string
const (
	SecretAuthenticate SecretAction = ""
	SecretCreate       SecretAction = "CREATE"
	SecretRotate       SecretAction = "ROTATE"
	SecretDelete       SecretAction = "DELETE"
)

type ServerError 

type ServerError struct {
	Code   string
	Fields map[string]string
}

ServerError preserves the server code and metadata, including unknown codes.

func (*ServerError) Error 

func (e *ServerError) Error() string

func (*ServerError) RetryAfter 

func (e *ServerError) RetryAfter() time.Duration

type ServerInfo 

type ServerInfo struct {
	ProtocolVersion int64
	Version         string
	Capabilities    []string
	Raw             Response
}

Typed results retain Raw for unknown fields and original wire records.

type StackAction 

type StackAction string
const (
	StackInfo  StackAction = "INFO"
	StackClear StackAction = "CLEAR"
)

type StackEntry 

type StackEntry struct {
	Position int64
	LiveVerse
}

type TokenList 

type TokenList struct {
	Actor  string
	Tokens []TokenMetadata
	Raw    Response
}

type TokenMetadata 

type TokenMetadata struct {
	ID, Source      string
	IssuedAt        int64
	IssuedBy, Label *string
	// Empty scopes inherit the actor's permissions. Nil means the field was absent;
	// it must not be interpreted as unrestricted authority.
	Scopes                []string
	LastUsedAt, ExpiresAt *int64
	Retiring              *bool
	Fields                map[string]string
}

TokenMetadata describes a currently active personal credential, never its value. Timestamp fields are Unix seconds. Optional fields remain nil when absent.

type TranslationCatalog 

type TranslationCatalog struct {
	Translation string
	Books       []CatalogBook
	Raw         Response
}

type TranslationInfo 

type TranslationInfo struct {
	ShortName, FullName                             string
	Edition, Updated                                string
	RightsStatus, RightsLabel, RightsURL, SourceURL string
	Attribution, TrademarkNotice                    string
	Raw                                             Response
}

type VerseText 

type VerseText struct {
	// Text retains the historical wire text, including any reference prefix.
	Text string
	// Structured source metadata is optional on older SSH servers.
	Content                          *string
	Translation, BookName, Reference string
	BookID, Chapter, Verse           *int64
	Fields                           map[string]string
}

Source Files

View all Source files

Directories

Path Synopsis
examples
read command
Read a verse using a finite personal token supplied by the application.
 Read a verse using a finite personal token supplied by the application.
Package rest provides Bibleit's versioned REST API.
 Package rest provides Bibleit's versioned REST API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.