sentryapi

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package sentryapi is the typed REST client for the ɳSentry cloud API.

Purpose: One client for both worlds — the hosted SaaS (api.sentry.nself.org) 

and a self-hosted / local sentry bundle (NSELF_SENTRY_API_URL).

Contract (v1, consumed by `nself sentry *` and the MCP sentry tools): 

Auth:   Authorization: Bearer nsk_<key>   (API keys issued per tenant, W1)
GET    /v1/me                              → {"tenant_id","email","tier","quotas":{dim:{"used","limit"}}}
GET    /v1/monitors                        → {"monitors":[Monitor]}
POST   /v1/monitors                        → 201 {"monitor":Monitor}
DELETE /v1/monitors/{id}                   → 204
POST   /v1/monitors/{id}/pause|resume      → {"monitor":Monitor}
GET    /v1/incidents?status=<s>            → {"incidents":[Incident]}
POST   /v1/incidents/{id}/ack|resolve      → {"incident":Incident}
GET    /v1/status-pages                    → {"status_pages":[StatusPage]}
POST   /v1/status-pages                    → 201 {"status_page":StatusPage}
GET    /v1/alerts/channels                 → {"channels":[AlertChannel]}
POST   /v1/alerts/channels/{id}/test       → {"delivered":bool,"detail":string}
Errors: non-2xx {"error":{"code","message"}}; 401 → ErrUnauthorized,
        402/429 → ErrQuotaExceeded (upgrade hint).

Constraints: no cobra imports here; pure HTTP + JSON so MCP and commands share it. SPORT: CLI-PKG-SENTRYAPI-001

Index

Constants

View Source 
const (
	EnvAPIURL = "NSELF_SENTRY_API_URL"
	EnvAPIKey = "NSELF_SENTRY_API_KEY"
)

EnvAPIURL / EnvAPIKey are the environment overrides for the client config.

View Source 
const DefaultAPIURL = "https://api.sentry.nself.org"

DefaultAPIURL is the hosted ɳSentry SaaS API endpoint.

View Source 
const KeyPrefix = "nsk_"

KeyPrefix is the required prefix for ɳSentry API keys.

Variables

View Source 
var ErrNotLoggedIn = errors.New("not logged in to ɳSentry — run 'nself sentry login'")

ErrNotLoggedIn is returned when no credentials file exists.

View Source 
var ErrQuotaExceeded = errors.New("quota exceeded for your tier — upgrade at https://sentry.nself.org/billing")

ErrQuotaExceeded is returned on HTTP 402/429 quota responses.

View Source 
var ErrUnauthorized = errors.New("unauthorized: invalid or missing API key — run 'nself sentry login'")

ErrUnauthorized is returned on HTTP 401 — the caller should suggest `nself sentry login`.

Functions

func DeleteCredentials 

func DeleteCredentials() error

DeleteCredentials removes the stored credentials (no-op when absent).

func Resolve 

func Resolve(flagURL, flagKey string) (apiURL, apiKey string)

Resolve computes the effective (apiURL, apiKey) using precedence: explicit args (flags) → env vars → credentials file → defaults. A missing key is not an error here — the API returns 401 and the client maps it to ErrUnauthorized with the login hint.

func ValidateKeyFormat 

func ValidateKeyFormat(key string) error

ValidateKeyFormat checks the nsk_ prefix without hitting the network.

func WriteCredentials 

func WriteCredentials(c *Credentials) error

WriteCredentials persists credentials at 0600 (dir 0700).

Types

type Account 

type Account struct {
	TenantID string                `json:"tenant_id"`
	Email    string                `json:"email"`
	Tier     string                `json:"tier"` // free | bundle | nself-plus
	Quotas   map[string]QuotaUsage `json:"quotas"`
}

Account is the response of GET /v1/me — identity, tier, and quota usage.

type AlertChannel 

type AlertChannel struct {
	ID      string `json:"id"`
	Kind    string `json:"kind"` // email | webhook | slack | telegram
	Target  string `json:"target"`
	Enabled bool   `json:"enabled"`
}

AlertChannel is a notification target (email/webhook/slack/telegram).

type Client 

type Client struct {
	BaseURL string
	APIKey  string
	HTTP    *http.Client
}

Client is a typed REST client for the ɳSentry API.

func New 

func New(baseURL, apiKey string) *Client

New returns a Client for baseURL/apiKey with a sane default timeout.

func (*Client) AckIncident 

func (c *Client) AckIncident(ctx context.Context, id string) (*Incident, error)

AckIncident acknowledges an open incident.

func (*Client) CreateMonitor 

func (c *Client) CreateMonitor(ctx context.Context, req CreateMonitorRequest) (*Monitor, error)

CreateMonitor creates a monitor and returns the created record.

func (*Client) CreateStatusPage 

func (c *Client) CreateStatusPage(ctx context.Context, req CreateStatusPageRequest) (*StatusPage, error)

CreateStatusPage creates a status page.

func (*Client) DeleteMonitor 

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

DeleteMonitor removes a monitor by id.

func (*Client) ListAlertChannels 

func (c *Client) ListAlertChannels(ctx context.Context) ([]AlertChannel, error)

ListAlertChannels returns the tenant's alert channels.

func (*Client) ListIncidents 

func (c *Client) ListIncidents(ctx context.Context, status string) ([]Incident, error)

ListIncidents returns incidents, optionally filtered by status (open | acknowledged | resolved; empty = all).

func (*Client) ListMonitors 

func (c *Client) ListMonitors(ctx context.Context) ([]Monitor, error)

ListMonitors returns all monitors for the tenant.

func (*Client) ListStatusPages 

func (c *Client) ListStatusPages(ctx context.Context) ([]StatusPage, error)

ListStatusPages returns the tenant's status pages.

func (*Client) PauseMonitor 

func (c *Client) PauseMonitor(ctx context.Context, id string, pause bool) (*Monitor, error)

PauseMonitor pauses (paused=true) or resumes (paused=false) a monitor.

func (*Client) ResolveIncident 

func (c *Client) ResolveIncident(ctx context.Context, id string) (*Incident, error)

ResolveIncident resolves an incident.

func (*Client) TestAlertChannel 

func (c *Client) TestAlertChannel(ctx context.Context, id string) (*TestChannelResult, error)

TestAlertChannel sends a test notification through a channel.

func (*Client) WhoAmI 

func (c *Client) WhoAmI(ctx context.Context) (*Account, error)

WhoAmI returns the authenticated account (tier + quota usage).

type CreateMonitorRequest 

type CreateMonitorRequest struct {
	Name            string `json:"name"`
	URL             string `json:"url"`
	Kind            string `json:"kind"`
	IntervalSeconds int    `json:"interval_seconds"`
}

CreateMonitorRequest is the body of POST /v1/monitors.

type CreateStatusPageRequest 

type CreateStatusPageRequest struct {
	Name string `json:"name"`
	Slug string `json:"slug"`
}

CreateStatusPageRequest is the body of POST /v1/status-pages.

type Credentials 

type Credentials struct {
	APIURL string `json:"api_url"`
	APIKey string `json:"api_key"`
}

Credentials is the on-disk shape of ~/.nself/sentry.json.

func ReadCredentials 

func ReadCredentials() (*Credentials, error)

ReadCredentials loads the stored credentials, or ErrNotLoggedIn.

type Incident 

type Incident struct {
	ID             string `json:"id"`
	MonitorID      string `json:"monitor_id"`
	Title          string `json:"title"`
	Status         string `json:"status"` // open | acknowledged | resolved
	Severity       string `json:"severity"`
	StartedAt      string `json:"started_at"`
	AcknowledgedAt string `json:"acknowledged_at,omitempty"`
	ResolvedAt     string `json:"resolved_at,omitempty"`
}

Incident is a monitoring incident (open → acknowledged → resolved).

type Monitor 

type Monitor struct {
	ID              string `json:"id"`
	Name            string `json:"name"`
	URL             string `json:"url"`
	Kind            string `json:"kind"` // http | tcp | ping
	IntervalSeconds int    `json:"interval_seconds"`
	Status          string `json:"status"` // up | down | paused | pending
	Paused          bool   `json:"paused"`
	CreatedAt       string `json:"created_at"`
}

Monitor is an uptime monitor owned by the authenticated tenant.

type QuotaUsage 

type QuotaUsage struct {
	Used  int64 `json:"used"`
	Limit int64 `json:"limit"`
}

QuotaUsage is used/limit for a single quota dimension.

type StatusPage 

type StatusPage struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Slug      string `json:"slug"`
	URL       string `json:"url"`
	Public    bool   `json:"public"`
	CreatedAt string `json:"created_at"`
}

StatusPage is a public status page owned by the tenant.

type TestChannelResult 

type TestChannelResult struct {
	Delivered bool   `json:"delivered"`
	Detail    string `json:"detail"`
}

TestChannelResult is the response of POST /v1/alerts/channels/{id}/test.

Source Files

View all Source files

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.