sdk

type Caller struct {
	UserID   int64  // verified user identifier
	Username string // verified account display name
	Role     string // verified account role
	Locale   string // negotiated request language
	// contains filtered or unexported fields
}

type Captcha hostClient

type Catalog hostClient

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

type ConfigWatcher interface {
	// ConfigChanged receives a snapshot after Env.Config publishes the new values.
	// It must honor cancellation; returning an error leaves the host's persisted
	// configuration intact and allows diagnosis without reverting settings silently.
	ConfigChanged(context.Context, Config) error
}

type CreditRequest struct {
	UserID         int64  // target account identifier
	Amount         string // positive decimal balance amount
	IdempotencyKey string // plugin-wide operation replay key
	Reason         string // user-visible balance adjustment explanation
}

type DebitRequest CreditRequest

type Email hostClient

type Env struct {
	PluginID        string   // publisher-qualified plugin identity
	Version         string   // running plugin release version
	PreviousVersion string   // previous running release version
	HostVersion     string   // host release build version
	InstanceID      string   // host process instance identity
	StateDir        string   // disposable local cache directory
	Permissions     []string // administrator-granted capability names
	// Config keeps a stable concurrent-read handle; the SDK publishes complete snapshots whenever the host applies new configuration.
	Config Config
	Host   *Host        // authenticated host capability client
	Logger *slog.Logger // structured plugin stderr logger
}

type HTTPPlugin interface {
	// Handler returns a concurrency-safe handler for requests authorized by the host.
	Handler() http.Handler
}

type HealthChecker interface {
	// Health returns nil while plugin-owned dependencies can serve business calls.
	// Implementations must honor the short host deadline. Repeated failures cause
	// the supervisor to stop and restart this process generation.
	Health(context.Context) error
}

type Host struct {
	Site          Site          // site context queries
	Users         Users         // account identity queries
	Wallet        Wallet        // balance reads and adjustments
	Redeem        Redeem        // single-use redeem code issuance
	Subscriptions Subscriptions // subscription queries and grants
	Usage         Usage         // account usage aggregate queries
	Orders        Orders        // sanitized payment order queries
	Catalog       Catalog       // model and group queries
	Email         Email         // idempotent notification email delivery
	Captcha       Captcha       // site captcha verification
	KV            KV            // plugin-isolated persistent JSON storage
}

type HostError struct {
	Reason   string            // stable host reason code
	Metadata map[string]string // host error detail metadata
	// contains filtered or unexported fields
}

type KV hostClient

type Orders hostClient

type Plugin interface {
	// Init receives validated configuration and a connected host callback client.
	// It must honor cancellation and return only when contributions are ready;
	// a failure prevents this process generation from becoming healthy.
	Init(context.Context, *Env) error
}

type PutOption func(*pluginpb.KVPutRequest)

type Redeem hostClient

type Shutdowner interface {
	// Shutdown stops plugin-owned background work and releases external resources.
	// The host has stopped admitting requests before invoking it. Cancellation
	// signals that the remaining graceful shutdown budget has expired.
	Shutdown(context.Context) error
}

type Site hostClient

type Subscriptions hostClient

type TaskPlugin interface {
	// RunTask executes one scheduled occurrence with its host-selected timestamp.
	// The host prevents overlapping runs of the same task. Implementations must
	// observe context cancellation when the configured task deadline expires.
	RunTask(context.Context, string, time.Time) error
}

type Usage hostClient

type Users hostClient

type Wallet hostClient