smplkit

package module
v1.2.3 Latest Latest
Warning

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

 Go to latest Published: Apr 3, 2026 License: MIT Imports: 24 Imported by: 0

README

smplkit Go SDK

The official Go SDK for smplkit — simple application infrastructure that just works.

Installation

go get github.com/smplkit/go-sdk

Requirements

  • Go 1.24+

Quick Start

package main

import (
    "fmt"
    "log"

    smplkit "github.com/smplkit/go-sdk"
)

func main() {
    // Option 1: Explicit API key
    client, err := smplkit.NewClient("sk_api_...")

    // Option 2: Environment variable (SMPLKIT_API_KEY)
    // export SMPLKIT_API_KEY=sk_api_...
    client, err = smplkit.NewClient("")

    // Option 3: Configuration file (~/.smplkit)
    // [default]
    // api_key = sk_api_...
    client, err = smplkit.NewClient("")

    if err != nil {
        log.Fatal(err)
    }

    // Get a config by key
    config, err := client.Config().GetByKey("user_service")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(config.Key)

    // List all configs
    configs, err := client.Config().List()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(len(configs))

    // Create a config
    newConfig, err := client.Config().Create(smplkit.CreateConfigParams{
        Name:        "My Service",
        Key:         strPtr("my_service"),
        Description: strPtr("Configuration for my service"),
        Values:      map[string]any{"timeout": 30, "retries": 3},
    })
    if err != nil {
        log.Fatal(err)
    }

    // Delete a config
    err = client.Config().Delete(newConfig.ID)
    if err != nil {
        log.Fatal(err)
    }
}

func strPtr(s string) *string { return &s }

Configuration

The API key is resolved using the following priority:

  1. Explicit argument: Pass apiKey to NewClient().
  2. Environment variable: Set SMPLKIT_API_KEY.
  3. Configuration file: Add api_key under [default] in ~/.smplkit:
# ~/.smplkit

[default]
api_key = sk_api_your_key_here

If none of these are set, NewClient returns a SmplError listing all three methods.

client, err := smplkit.NewClient("sk_api_...",
    smplkit.WithTimeout(30 * time.Second),   // default
    smplkit.WithHTTPClient(customHTTPClient),
)

Error Handling

All SDK errors extend SmplError and support errors.Is() / errors.As():

import "errors"

config, err := client.Config().GetByKey("nonexistent")
if err != nil {
    var notFound *smplkit.SmplNotFoundError
    if errors.As(err, &notFound) {
        fmt.Println("Not found:", notFound.Message)
    } else {
        fmt.Println("Error:", err)
    }
}
Error Cause
SmplNotFoundError HTTP 404 — resource not found
SmplConflictError HTTP 409 — conflict
SmplValidationError HTTP 422 — validation error
SmplTimeoutError Request timed out
SmplConnectionError Network connectivity issue
SmplError Any other SDK error

Feature Flags

The SDK includes a full-featured feature flags client with management API, prescriptive runtime evaluation, and real-time updates.

Management API
ctx := context.Background()
flags := client.Flags()

// Create a flag
flag, err := flags.Create(ctx, smplkit.CreateFlagParams{
    Key:     "checkout-v2",
    Name:    "Checkout V2",
    Type:    smplkit.FlagTypeBoolean,
    Default: false,
})

// Update with environment rules
err = flag.Update(ctx, smplkit.UpdateFlagParams{
    Environments: map[string]interface{}{
        "staging": map[string]interface{}{
            "enabled": true,
            "rules": []interface{}{
                smplkit.NewRule("Enable for enterprise").
                    When("user.plan", "==", "enterprise").
                    Serve(true).
                    Build(),
            },
        },
    },
})

// List, get, delete
allFlags, _ := flags.List(ctx)
fetched, _ := flags.Get(ctx, flag.ID)
err = flags.Delete(ctx, flag.ID)
Runtime Evaluation
// Define typed flag handles
checkout := flags.BoolFlag("checkout-v2", false)
banner   := flags.StringFlag("banner-color", "red")
retries  := flags.NumberFlag("max-retries", 3)

// Register a context provider
flags.SetContextProvider(func(ctx context.Context) []smplkit.Context {
    return []smplkit.Context{
        smplkit.NewContext("user", "user-42", map[string]interface{}{
            "plan": "enterprise",
        }),
    }
})

// Connect to an environment
err := flags.Connect(ctx, "staging")

// Evaluate — uses provider context, caches results
isV2 := checkout.Get(ctx)            // true (rule matched)
color := banner.Get(ctx)             // "blue"

// Explicit context override
basicUser := smplkit.NewContext("user", "u-1", map[string]interface{}{"plan": "free"})
isV2 = checkout.Get(ctx, basicUser)  // false

// Change listeners
flags.OnChange(func(evt *smplkit.FlagChangeEvent) {
    fmt.Println("flag changed:", evt.Key)
})

// Cache stats
stats := flags.Stats()
fmt.Printf("hits=%d misses=%d\n", stats.CacheHits, stats.CacheMisses)

// Cleanup
flags.Disconnect(ctx)
Flag Types
Constant Value
FlagTypeBoolean "BOOLEAN"
FlagTypeString "STRING"
FlagTypeNumeric "NUMERIC"
FlagTypeJSON "JSON"

Documentation

License

MIT

Documentation

Overview

Package smplkit provides a Go client for the smplkit platform.

The SDK follows a two-layer architecture: auto-generated types live in internal/generated, while this package provides the hand-crafted public API.

Quick start: 

client, err := smplkit.NewClient("sk_api_...")
cfg, err := client.Config().GetByKey(ctx, "my-service")
if err != nil {
    var notFound *smplkit.SmplNotFoundError
    if errors.As(err, &notFound) {
        // handle not found
    }
    return err
}
fmt.Println(cfg.Name)

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotConnected = &SmplNotConnectedError{SmplError{Message: "SmplClient is not connected. Call client.Connect() first."}}

ErrNotConnected is a convenience sentinel for SmplNotConnectedError checks.

Functions

This section is empty.

Types

type BoolFlagHandle added in v1.2.0 

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

BoolFlagHandle is a typed handle for a boolean flag.

func (*BoolFlagHandle) Get added in v1.2.0 

func (h *BoolFlagHandle) Get(ctx context.Context, contexts ...Context) bool

Get evaluates the flag and returns a typed boolean value. Pass nil for ctx to use context.Background().

func (*BoolFlagHandle) GetWithContext added in v1.2.0 

func (h *BoolFlagHandle) GetWithContext(ctx context.Context, contexts []Context) bool

GetWithContext evaluates the flag with explicit context override.

func (*BoolFlagHandle) OnChange added in v1.2.0 

func (h *BoolFlagHandle) OnChange(cb func(*FlagChangeEvent))

OnChange registers a flag-specific change listener.

type Client 

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

Client is the top-level entry point for the smplkit SDK.

Create one with NewClient and access sub-clients via accessor methods: 

client, err := smplkit.NewClient("sk_api_...", "production")
err = client.Connect(ctx)
cfgs, err := client.Config().List(ctx)

func NewClient 

func NewClient(apiKey string, environment string, opts ...ClientOption) (*Client, error)

NewClient creates a new smplkit API client.

The apiKey is used for Bearer token authentication on every request. Pass an empty string to resolve the API key automatically from the SMPLKIT_API_KEY environment variable or the ~/.smplkit config file.

The environment is required; pass an empty string to resolve from SMPLKIT_ENVIRONMENT.

Use ClientOption functions to customize the base URL, timeout, HTTP client, or service name.

func (*Client) Config 

func (c *Client) Config() *ConfigClient

Config returns the sub-client for config management operations.

func (*Client) Connect added in v1.2.1 

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

Connect connects to the smplkit platform: fetches initial flag and config data, opens the shared WebSocket, and registers the service as a context instance (if provided).

This method is idempotent — calling it multiple times is safe.

func (*Client) Environment added in v1.2.1 

func (c *Client) Environment() string

Environment returns the resolved environment name.

func (*Client) Flags added in v1.2.0 

func (c *Client) Flags() *FlagsClient

Flags returns the sub-client for flags management and runtime operations.

func (*Client) Service added in v1.2.1 

func (c *Client) Service() string

Service returns the resolved service name, or empty string if not set.

type ClientOption 

type ClientOption func(*clientConfig)

ClientOption configures the Client. Pass options to NewClient.

func WithBaseURL 

func WithBaseURL(url string) ClientOption

WithBaseURL overrides the default API base URL.

func WithHTTPClient 

func WithHTTPClient(c *http.Client) ClientOption

WithHTTPClient replaces the default HTTP client entirely. When set, the WithTimeout option is ignored because the caller controls the client.

func WithService added in v1.2.1 

func WithService(name string) ClientOption

WithService sets the service name for automatic context injection. When set, the SDK registers the service as a context instance during Connect() and includes it in flag evaluation context.

func WithTimeout 

func WithTimeout(d time.Duration) ClientOption

WithTimeout sets the HTTP request timeout. The default is 30 seconds.

type Config 

type Config struct {
	// ID is the unique identifier (UUID) of the config.
	ID string
	// Key is the human-readable config key (e.g. "user_service").
	Key string
	// Name is the display name for the config.
	Name string
	// Description is an optional description of the config.
	Description *string
	// Parent is the parent config UUID, or nil for root configs.
	Parent *string
	// Items holds the base configuration values (extracted raw values from typed items).
	Items map[string]interface{}
	// Environments maps environment names to their value overrides.
	// Each environment entry is a map that contains a "values" key
	// with extracted raw values from wrapped overrides.
	Environments map[string]map[string]interface{}
	// CreatedAt is the creation timestamp.
	CreatedAt *time.Time
	// UpdatedAt is the last-modified timestamp.
	UpdatedAt *time.Time
	// contains filtered or unexported fields
}

Config represents a configuration resource from the smplkit platform.

func (*Config) Connect added in v1.1.1 

func (c *Config) Connect(ctx context.Context, environment string) (*ConfigRuntime, error)

Connect creates a live, reactive ConfigRuntime for this config in the given environment. The runtime maintains a WebSocket connection for real-time updates and supports OnChange listeners. Call Close on the returned runtime when done.

For simple prescriptive access, use ConfigClient.GetValue after calling Client.Connect instead.

func (*Config) SetValue added in v1.1.1 

func (c *Config) SetValue(ctx context.Context, key string, value interface{}, environment string) error

SetValue sets a single key within base or environment-specific values. Pass an empty string for environment to set a base value. This merges the key into existing values rather than replacing all values.

Returns SmplNotFoundError if the config no longer exists.

func (*Config) SetValues added in v1.1.1 

func (c *Config) SetValues(ctx context.Context, values map[string]interface{}, environment string) error

SetValues replaces the base or environment-specific values for this config. Pass an empty string for environment to replace base values. Pass an environment name (e.g. "production") to replace that environment's values.

Returns SmplNotFoundError if the config no longer exists.

func (*Config) Update added in v1.1.1 

func (c *Config) Update(ctx context.Context, params UpdateConfigParams) error

Update replaces this config's attributes on the server. Any nil field in params falls back to the config's current value. Updates the config's fields in place on success.

Returns SmplNotFoundError if the config no longer exists.

type ConfigChangeEvent added in v1.1.1 

type ConfigChangeEvent struct {
	// Key is the top-level key that changed.
	Key string
	// OldValue is the value before the change (nil if the key was new).
	OldValue interface{}
	// NewValue is the value after the change (nil if the key was removed).
	NewValue interface{}
	// Source is "websocket" for server-pushed changes or "manual" for Refresh calls.
	Source string
}

ConfigChangeEvent describes a single value change delivered to OnChange listeners.

type ConfigClient 

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

ConfigClient provides CRUD operations for config resources. Obtain one via Client.Config().

func (*ConfigClient) Create 

func (c *ConfigClient) Create(ctx context.Context, params CreateConfigParams) (*Config, error)

Create creates a new config resource.

func (*ConfigClient) Delete 

func (c *ConfigClient) Delete(ctx context.Context, id string) error

Delete removes a config by its UUID. Returns nil on success (HTTP 204).

func (*ConfigClient) Get 

func (c *ConfigClient) Get(ctx context.Context, opts ...GetOption) (*Config, error)

Get retrieves a single config using functional options. Exactly one of WithKey or WithID must be provided. 

cfg, err := client.Config().Get(ctx, smplkit.WithKey("my-service"))
cfg, err := client.Config().Get(ctx, smplkit.WithID("uuid-here"))

func (*ConfigClient) GetByID 

func (c *ConfigClient) GetByID(ctx context.Context, id string) (*Config, error)

GetByID retrieves a config by its UUID.

func (*ConfigClient) GetByKey 

func (c *ConfigClient) GetByKey(ctx context.Context, key string) (*Config, error)

GetByKey retrieves a config by its human-readable key. Uses the list endpoint with a filter[key] query parameter and returns the first match, or SmplNotFoundError if none match.

func (*ConfigClient) GetValue added in v1.2.1 

func (c *ConfigClient) GetValue(configKey string, itemKey ...string) (interface{}, error)

GetValue reads a resolved config value (prescriptive access).

Requires Client.Connect() to have been called.

With one argument (configKey), returns a copy of all resolved values as map[string]interface{}. With two arguments (configKey, itemKey), returns the specific item value. Returns defaultVal (or nil) if the key is missing.

func (*ConfigClient) List 

func (c *ConfigClient) List(ctx context.Context) ([]*Config, error)

List returns all configs for the account.

type ConfigRuntime added in v1.1.1 

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

ConfigRuntime is a live, in-process view of a resolved config for one environment. Obtain one via Config.Connect. Call Close when done.

func (*ConfigRuntime) Close added in v1.1.1 

func (rt *ConfigRuntime) Close()

Close stops the WebSocket goroutine and marks the runtime as disconnected. Idempotent; safe to call multiple times.

func (*ConfigRuntime) ConnectionStatus added in v1.1.1 

func (rt *ConfigRuntime) ConnectionStatus() string

ConnectionStatus returns "connecting", "connected", or "disconnected".

func (*ConfigRuntime) Exists added in v1.1.1 

func (rt *ConfigRuntime) Exists(key string) bool

Exists returns true if key is present in the resolved cache.

func (*ConfigRuntime) Get added in v1.1.1 

func (rt *ConfigRuntime) Get(key string, defaultVal ...interface{}) interface{}

Get returns the resolved value for key, or defaultVal (or nil) if absent.

func (*ConfigRuntime) GetAll added in v1.1.1 

func (rt *ConfigRuntime) GetAll() map[string]interface{}

GetAll returns a shallow copy of the entire resolved cache.

func (*ConfigRuntime) GetBool added in v1.1.1 

func (rt *ConfigRuntime) GetBool(key string, defaultVal ...bool) bool

GetBool returns the resolved bool value for key, or defaultVal if absent or wrong type.

func (*ConfigRuntime) GetInt added in v1.1.1 

func (rt *ConfigRuntime) GetInt(key string, defaultVal ...int) int

GetInt returns the resolved int value for key, or defaultVal if absent or wrong type. JSON numbers are float64; this converts float64 to int automatically.

func (*ConfigRuntime) GetString added in v1.1.1 

func (rt *ConfigRuntime) GetString(key string, defaultVal ...string) string

GetString returns the resolved string value for key, or defaultVal if absent or wrong type.

func (*ConfigRuntime) OnChange added in v1.1.1 

func (rt *ConfigRuntime) OnChange(cb func(*ConfigChangeEvent), key ...string)

OnChange registers a listener for value changes. If key is provided, the listener is called only when that specific key changes. Without key, it is called for every changed key.

func (*ConfigRuntime) Refresh added in v1.1.1 

func (rt *ConfigRuntime) Refresh() error

Refresh re-fetches the full config chain, updates the cache synchronously, and fires OnChange listeners for any keys that changed.

func (*ConfigRuntime) Stats added in v1.1.1 

func (rt *ConfigRuntime) Stats() ConfigStats

Stats returns a snapshot of runtime diagnostics.

type ConfigStats added in v1.1.1 

type ConfigStats struct {
	// FetchCount is the total number of times the full config chain was fetched.
	FetchCount int
	// LastFetchAt is the time of the most recent fetch.
	LastFetchAt time.Time
}

ConfigStats holds runtime diagnostics for a ConfigRuntime.

type Context added in v1.2.0 

type Context struct {
	// Type is the context type (e.g. "user", "account").
	Type string
	// Key is the unique identifier for this entity.
	Key string
	// Name is an optional display name.
	Name string
	// Attributes holds arbitrary key-value data for rule evaluation.
	Attributes map[string]interface{}
}

Context represents a typed evaluation context entity.

Each Context identifies an entity (user, account, device, etc.) by type and key, with optional attributes that JSON Logic rules can target. 

ctx := smplkit.NewContext("user", "user-123", map[string]any{
    "plan": "enterprise",
    "firstName": "Alice",
})

func NewContext added in v1.2.0 

func NewContext(contextType, key string, attrs map[string]interface{}, opts ...ContextOption) Context

NewContext creates a new evaluation context. The optional attrs map provides attributes for JSON Logic rule evaluation. Use WithName to set a display name, or WithAttr to add individual attributes. 

// Using a map:
ctx := smplkit.NewContext("user", "user-123", map[string]any{"plan": "enterprise"})

// Using functional options:
ctx := smplkit.NewContext("user", "user-123", nil,
    smplkit.WithName("Alice"),
    smplkit.WithAttr("plan", "enterprise"),
)

type ContextOption added in v1.2.0 

type ContextOption func(*Context)

ContextOption configures a Context. Use WithName and WithAttr.

func WithAttr added in v1.2.0 

func WithAttr(key string, value interface{}) ContextOption

WithAttr adds a single attribute to a Context.

func WithName added in v1.2.0 

func WithName(name string) ContextOption

WithName sets the display name on a Context.

type ContextType added in v1.2.0 

type ContextType struct {
	// ID is the unique identifier (UUID) of the context type.
	ID string
	// Key is the human-readable key.
	Key string
	// Name is the display name.
	Name string
	// Attributes holds the context type's attribute definitions.
	Attributes map[string]interface{}
}

ContextType represents a context type resource from the management API.

type CreateConfigParams 

type CreateConfigParams struct {
	// Name is the display name (required).
	Name string
	// Key is the human-readable key. Auto-generated by the server if nil.
	Key *string
	// Description is an optional description.
	Description *string
	// Parent is the parent config UUID.
	Parent *string
	// Items holds the initial base values (raw values, not wrapped).
	Items map[string]interface{}
	// Environments holds the initial environment-specific overrides.
	Environments map[string]map[string]interface{}
}

CreateConfigParams holds the parameters for creating a new config.

type CreateFlagParams added in v1.2.0 

type CreateFlagParams struct {
	// Key is the human-readable flag key (required).
	Key string
	// Name is the display name (required).
	Name string
	// Type is the value type (required).
	Type FlagType
	// Default is the default value (required).
	Default interface{}
	// Description is an optional description.
	Description *string
	// Values is the closed set of possible values. Auto-generated for boolean flags.
	Values []FlagValue
}

CreateFlagParams holds the parameters for creating a new flag.

type Flag added in v1.2.0 

type Flag struct {
	// ID is the unique identifier (UUID) of the flag.
	ID string
	// Key is the human-readable flag key.
	Key string
	// Name is the display name for the flag.
	Name string
	// Type is the value type (BOOLEAN, STRING, NUMERIC, JSON).
	Type string
	// Default is the default value for the flag.
	Default interface{}
	// Values is the closed set of possible values.
	Values []FlagValue
	// Description is an optional description of the flag.
	Description *string
	// Environments maps environment names to their configuration.
	Environments map[string]interface{}
	// CreatedAt is the creation timestamp.
	CreatedAt *time.Time
	// UpdatedAt is the last-modified timestamp.
	UpdatedAt *time.Time
	// contains filtered or unexported fields
}

Flag represents a flag resource from the smplkit platform.

func (*Flag) AddRule added in v1.2.0 

func (f *Flag) AddRule(ctx context.Context, builtRule map[string]interface{}) error

AddRule adds a rule to a specific environment. The built rule must include an "environment" key (use Rule.Environment("env_key") before Build).

func (*Flag) Update added in v1.2.0 

func (f *Flag) Update(ctx context.Context, params UpdateFlagParams) error

Update replaces this flag's attributes on the server. Only non-nil fields in params are changed.

type FlagChangeEvent added in v1.2.0 

type FlagChangeEvent struct {
	// Key is the flag key that changed.
	Key string
	// Source is "websocket" or "manual".
	Source string
}

FlagChangeEvent describes a flag definition change.

type FlagStats added in v1.2.0 

type FlagStats struct {
	// CacheHits is the number of evaluation cache hits.
	CacheHits int
	// CacheMisses is the number of evaluation cache misses.
	CacheMisses int
}

FlagStats holds cache statistics for the flags runtime.

type FlagType added in v1.2.0 

type FlagType string

FlagType represents the value type of a flag. 

const (
	// FlagTypeBoolean represents a boolean flag.
	FlagTypeBoolean FlagType = "BOOLEAN"
	// FlagTypeString represents a string flag.
	FlagTypeString FlagType = "STRING"
	// FlagTypeNumeric represents a numeric flag.
	FlagTypeNumeric FlagType = "NUMERIC"
	// FlagTypeJSON represents a JSON flag.
	FlagTypeJSON FlagType = "JSON"
)

type FlagValue added in v1.2.0 

type FlagValue struct {
	Name  string
	Value interface{}
}

FlagValue represents a named value in a flag's value set.

type FlagsClient added in v1.2.0 

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

FlagsClient provides management and runtime operations for flag resources. Obtain one via Client.Flags().

func (*FlagsClient) BoolFlag added in v1.2.0 

func (c *FlagsClient) BoolFlag(key string, defaultValue bool) *BoolFlagHandle

BoolFlag returns a typed handle for a boolean flag.

func (*FlagsClient) ConnectionStatus added in v1.2.0 

func (c *FlagsClient) ConnectionStatus() string

ConnectionStatus returns the current WebSocket connection status.

func (*FlagsClient) Create added in v1.2.0 

func (c *FlagsClient) Create(ctx context.Context, params CreateFlagParams) (*Flag, error)

Create creates a new flag resource.

func (*FlagsClient) CreateContextType added in v1.2.0 

func (c *FlagsClient) CreateContextType(ctx context.Context, key string, name string) (*ContextType, error)

CreateContextType creates a new context type.

func (*FlagsClient) Delete added in v1.2.0 

func (c *FlagsClient) Delete(ctx context.Context, flagID string) error

Delete removes a flag by its UUID. Returns nil on success.

func (*FlagsClient) DeleteContextType added in v1.2.0 

func (c *FlagsClient) DeleteContextType(ctx context.Context, ctID string) error

DeleteContextType deletes a context type by its UUID.

func (*FlagsClient) Disconnect added in v1.2.0 

func (c *FlagsClient) Disconnect(ctx context.Context)

Disconnect unregisters from WebSocket, flushes contexts, and clears state.

func (*FlagsClient) Evaluate added in v1.2.0 

func (c *FlagsClient) Evaluate(ctx context.Context, key string, environment string, contexts []Context) interface{}

Evaluate performs Tier 1 explicit evaluation — stateless, no provider or cache.

func (*FlagsClient) FlushContexts added in v1.2.0 

func (c *FlagsClient) FlushContexts(ctx context.Context)

FlushContexts flushes pending context registrations to the server.

func (*FlagsClient) Get added in v1.2.0 

func (c *FlagsClient) Get(ctx context.Context, flagID string) (*Flag, error)

Get retrieves a flag by its UUID.

func (*FlagsClient) JsonFlag added in v1.2.0 

func (c *FlagsClient) JsonFlag(key string, defaultValue map[string]interface{}) *JsonFlagHandle

JsonFlag returns a typed handle for a JSON flag.

func (*FlagsClient) List added in v1.2.0 

func (c *FlagsClient) List(ctx context.Context) ([]*Flag, error)

List returns all flags for the account.

func (*FlagsClient) ListContextTypes added in v1.2.0 

func (c *FlagsClient) ListContextTypes(ctx context.Context) ([]*ContextType, error)

ListContextTypes lists all context types.

func (*FlagsClient) ListContexts added in v1.2.0 

func (c *FlagsClient) ListContexts(ctx context.Context, contextTypeKey string) ([]map[string]interface{}, error)

ListContexts lists context instances filtered by context type key.

func (*FlagsClient) NumberFlag added in v1.2.0 

func (c *FlagsClient) NumberFlag(key string, defaultValue float64) *NumberFlagHandle

NumberFlag returns a typed handle for a numeric flag.

func (*FlagsClient) OnChange added in v1.2.0 

func (c *FlagsClient) OnChange(cb func(*FlagChangeEvent))

OnChange registers a global change listener.

func (*FlagsClient) Refresh added in v1.2.0 

func (c *FlagsClient) Refresh(ctx context.Context) error

Refresh re-fetches all flag definitions and clears cache.

func (*FlagsClient) Register added in v1.2.0 

func (c *FlagsClient) Register(ctx context.Context, contexts ...Context)

Register explicitly registers context(s) for background batch registration.

func (*FlagsClient) SetContextProvider added in v1.2.0 

func (c *FlagsClient) SetContextProvider(fn func(ctx context.Context) []Context)

SetContextProvider registers a function that provides evaluation contexts.

func (*FlagsClient) Stats added in v1.2.0 

func (c *FlagsClient) Stats() FlagStats

Stats returns cache statistics.

func (*FlagsClient) StringFlag added in v1.2.0 

func (c *FlagsClient) StringFlag(key string, defaultValue string) *StringFlagHandle

StringFlag returns a typed handle for a string flag.

func (*FlagsClient) UpdateContextType added in v1.2.0 

func (c *FlagsClient) UpdateContextType(ctx context.Context, ctID string, attributes map[string]interface{}) (*ContextType, error)

UpdateContextType updates a context type's attributes.

type FlagsRuntime added in v1.2.0 

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

FlagsRuntime holds the prescriptive runtime state for the flags namespace. It is created internally; access it via FlagsClient methods like BoolFlag, Connect, etc.

func (*FlagsRuntime) BoolFlag added in v1.2.0 

func (rt *FlagsRuntime) BoolFlag(key string, defaultValue bool) *BoolFlagHandle

BoolFlag returns a typed handle for a boolean flag.

func (*FlagsRuntime) Connect added in v1.2.0 

func (rt *FlagsRuntime) Connect(ctx context.Context, environment string) error

Connect fetches flag definitions and registers on the shared WebSocket.

func (*FlagsRuntime) ConnectionStatus added in v1.2.0 

func (rt *FlagsRuntime) ConnectionStatus() string

ConnectionStatus returns the current WebSocket connection status.

func (*FlagsRuntime) Disconnect added in v1.2.0 

func (rt *FlagsRuntime) Disconnect(ctx context.Context)

Disconnect unregisters from WebSocket, flushes contexts, and clears state.

func (*FlagsRuntime) Evaluate added in v1.2.0 

func (rt *FlagsRuntime) Evaluate(ctx context.Context, key string, environment string, contexts []Context) interface{}

Evaluate performs Tier 1 explicit evaluation — stateless, no provider or cache.

func (*FlagsRuntime) FlushContexts added in v1.2.0 

func (rt *FlagsRuntime) FlushContexts(ctx context.Context)

FlushContexts flushes pending context registrations to the server.

func (*FlagsRuntime) JsonFlag added in v1.2.0 

func (rt *FlagsRuntime) JsonFlag(key string, defaultValue map[string]interface{}) *JsonFlagHandle

JsonFlag returns a typed handle for a JSON flag.

func (*FlagsRuntime) NumberFlag added in v1.2.0 

func (rt *FlagsRuntime) NumberFlag(key string, defaultValue float64) *NumberFlagHandle

NumberFlag returns a typed handle for a numeric flag.

func (*FlagsRuntime) OnChange added in v1.2.0 

func (rt *FlagsRuntime) OnChange(cb func(*FlagChangeEvent))

OnChange registers a global change listener.

func (*FlagsRuntime) Refresh added in v1.2.0 

func (rt *FlagsRuntime) Refresh(ctx context.Context) error

Refresh re-fetches all flag definitions and clears cache.

func (*FlagsRuntime) Register added in v1.2.0 

func (rt *FlagsRuntime) Register(ctx context.Context, contexts ...Context)

Register explicitly registers context(s) for background batch registration.

func (*FlagsRuntime) SetContextProvider added in v1.2.0 

func (rt *FlagsRuntime) SetContextProvider(fn func(ctx context.Context) []Context)

SetContextProvider registers a function that provides evaluation contexts. The provider receives the Go context.Context and returns a slice of Contexts.

func (*FlagsRuntime) Stats added in v1.2.0 

func (rt *FlagsRuntime) Stats() FlagStats

Stats returns cache statistics.

func (*FlagsRuntime) StringFlag added in v1.2.0 

func (rt *FlagsRuntime) StringFlag(key string, defaultValue string) *StringFlagHandle

StringFlag returns a typed handle for a string flag.

type GetOption 

type GetOption func(*getConfig)

GetOption configures a Get request. Use WithKey or WithID to specify the lookup strategy.

func WithID 

func WithID(id string) GetOption

WithID returns a GetOption that looks up a config by its UUID.

func WithKey 

func WithKey(key string) GetOption

WithKey returns a GetOption that looks up a config by its human-readable key.

type JsonFlagHandle added in v1.2.0 

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

JsonFlagHandle is a typed handle for a JSON flag.

func (*JsonFlagHandle) Get added in v1.2.0 

func (h *JsonFlagHandle) Get(ctx context.Context, contexts ...Context) map[string]interface{}

Get evaluates the flag and returns a typed map value.

func (*JsonFlagHandle) GetWithContext added in v1.2.0 

func (h *JsonFlagHandle) GetWithContext(ctx context.Context, contexts []Context) map[string]interface{}

GetWithContext evaluates the flag with explicit context override.

func (*JsonFlagHandle) OnChange added in v1.2.0 

func (h *JsonFlagHandle) OnChange(cb func(*FlagChangeEvent))

OnChange registers a flag-specific change listener.

type NumberFlagHandle added in v1.2.0 

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

NumberFlagHandle is a typed handle for a numeric flag.

func (*NumberFlagHandle) Get added in v1.2.0 

func (h *NumberFlagHandle) Get(ctx context.Context, contexts ...Context) float64

Get evaluates the flag and returns a typed float64 value.

func (*NumberFlagHandle) GetWithContext added in v1.2.0 

func (h *NumberFlagHandle) GetWithContext(ctx context.Context, contexts []Context) float64

GetWithContext evaluates the flag with explicit context override.

func (*NumberFlagHandle) OnChange added in v1.2.0 

func (h *NumberFlagHandle) OnChange(cb func(*FlagChangeEvent))

OnChange registers a flag-specific change listener.

type Rule added in v1.2.0 

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

Rule is a fluent builder for JSON Logic rule dicts. 

rule := smplkit.NewRule("Enable for enterprise users").
    When("user.plan", "==", "enterprise").
    Serve(true).
    Build()

func NewRule added in v1.2.0 

func NewRule(description string) *Rule

NewRule creates a new rule builder with the given description.

func (*Rule) Build added in v1.2.0 

func (r *Rule) Build() map[string]interface{}

Build finalizes and returns the rule as a plain map.

func (*Rule) Environment added in v1.2.0 

func (r *Rule) Environment(envKey string) *Rule

Environment tags this rule with an environment key (required for AddRule).

func (*Rule) Serve added in v1.2.0 

func (r *Rule) Serve(value interface{}) *Rule

Serve sets the value returned when this rule matches.

func (*Rule) When added in v1.2.0 

func (r *Rule) When(variable, op string, value interface{}) *Rule

When adds a condition. Multiple calls are AND'd. Supported operators: ==, !=, >, <, >=, <=, in, contains.

type SmplConflictError 

type SmplConflictError struct {
	SmplError
}

SmplConflictError is raised when an operation conflicts with current state (HTTP 409).

func (*SmplConflictError) Error 

func (e *SmplConflictError) Error() string

Error implements the error interface.

func (*SmplConflictError) Unwrap 

func (e *SmplConflictError) Unwrap() error

Unwrap returns the embedded SmplError for errors.Is/errors.As support.

type SmplConnectionError 

type SmplConnectionError struct {
	SmplError
}

SmplConnectionError is raised when a network request fails.

func (*SmplConnectionError) Error 

func (e *SmplConnectionError) Error() string

Error implements the error interface.

func (*SmplConnectionError) Unwrap 

func (e *SmplConnectionError) Unwrap() error

Unwrap returns the embedded SmplError for errors.Is/errors.As support.

type SmplError 

type SmplError struct {
	Message      string
	StatusCode   int
	ResponseBody string
}

SmplError is the base error type for all smplkit SDK errors. All specific error types embed SmplError, so errors.As(err, &SmplError{}) will match any SDK error.

func (*SmplError) Error 

func (e *SmplError) Error() string

Error implements the error interface.

type SmplNotConnectedError added in v1.2.1 

type SmplNotConnectedError struct {
	SmplError
}

SmplNotConnectedError is raised when a method requiring Connect() is called before the client is connected.

func (*SmplNotConnectedError) Error added in v1.2.1 

func (e *SmplNotConnectedError) Error() string

Error implements the error interface.

func (*SmplNotConnectedError) Unwrap added in v1.2.1 

func (e *SmplNotConnectedError) Unwrap() error

Unwrap returns the embedded SmplError for errors.Is/errors.As support.

type SmplNotFoundError 

type SmplNotFoundError struct {
	SmplError
}

SmplNotFoundError is raised when a requested resource does not exist (HTTP 404).

func (*SmplNotFoundError) Error 

func (e *SmplNotFoundError) Error() string

Error implements the error interface.

func (*SmplNotFoundError) Unwrap 

func (e *SmplNotFoundError) Unwrap() error

Unwrap returns the embedded SmplError for errors.Is/errors.As support.

type SmplTimeoutError 

type SmplTimeoutError struct {
	SmplError
}

SmplTimeoutError is raised when an operation exceeds its timeout.

func (*SmplTimeoutError) Error 

func (e *SmplTimeoutError) Error() string

Error implements the error interface.

func (*SmplTimeoutError) Unwrap 

func (e *SmplTimeoutError) Unwrap() error

Unwrap returns the embedded SmplError for errors.Is/errors.As support.

type SmplValidationError 

type SmplValidationError struct {
	SmplError
}

SmplValidationError is raised when the server rejects a request due to validation errors (HTTP 422).

func (*SmplValidationError) Error 

func (e *SmplValidationError) Error() string

Error implements the error interface.

func (*SmplValidationError) Unwrap 

func (e *SmplValidationError) Unwrap() error

Unwrap returns the embedded SmplError for errors.Is/errors.As support.

type StringFlagHandle added in v1.2.0 

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

StringFlagHandle is a typed handle for a string flag.

func (*StringFlagHandle) Get added in v1.2.0 

func (h *StringFlagHandle) Get(ctx context.Context, contexts ...Context) string

Get evaluates the flag and returns a typed string value.

func (*StringFlagHandle) GetWithContext added in v1.2.0 

func (h *StringFlagHandle) GetWithContext(ctx context.Context, contexts []Context) string

GetWithContext evaluates the flag with explicit context override.

func (*StringFlagHandle) OnChange added in v1.2.0 

func (h *StringFlagHandle) OnChange(cb func(*FlagChangeEvent))

OnChange registers a flag-specific change listener.

type UpdateConfigParams added in v1.1.1 

type UpdateConfigParams struct {
	// Name overrides the config's display name.
	Name *string
	// Description overrides the config's description.
	Description *string
	// Items replaces the config's base values entirely (raw values, not wrapped).
	Items map[string]interface{}
	// Environments replaces the config's environments map entirely.
	Environments map[string]map[string]interface{}
}

UpdateConfigParams holds the optional fields for updating a config. Any nil field falls back to the config's current value.

type UpdateFlagParams added in v1.2.0 

type UpdateFlagParams struct {
	// Name overrides the flag's display name.
	Name *string
	// Description overrides the flag's description.
	Description *string
	// Default overrides the flag's default value.
	Default interface{}
	// Values overrides the flag's value set.
	Values []FlagValue
	// Environments replaces the flag's environments map.
	Environments map[string]interface{}
}

UpdateFlagParams holds the optional fields for updating a flag.

Source Files

View all Source files

Directories

Path Synopsis
internal
generated/app
Package app contains auto-generated types from the app OpenAPI spec.
 Package app contains auto-generated types from the app OpenAPI spec.
generated/config
Package config contains auto-generated types from the config OpenAPI spec.
 Package config contains auto-generated types from the config OpenAPI spec.
generated/flags
Package flags provides primitives to interact with the openapi HTTP API.
 Package flags provides primitives to interact with the openapi HTTP API.
generated/logging
Package logging provides primitives to interact with the openapi HTTP API.
 Package logging provides primitives to interact with the openapi HTTP 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.