chore(go): audit root package

Share one request, decode, and error path across the client, public
endpoints, and export download; align types with the Backend contract
and split types_api.go.

Claude-Session: https://claude.ai/code/session_01Agoc9bRVE9KL7mmWtey9Vq

admin_events.go

@@ -2,8 +2,7 @@ package elydora
 
 import "fmt"
 
-// ListAdminEvents retrieves recent administrative events for the organization.
+// ListAdminEvents retrieves recent administrative events; limit 0 uses the server default.
-// An optional limit (1–100) may be provided; pass 0 to use the server default (20).
 func (c *Client) ListAdminEvents(limit int) (*ListAdminEventsResponse, error) {
 	path := "/v1/admin/events"
 	if limit > 0 {

auth.go

@@ -1,51 +1,30 @@
 package elydora
 
-import (
+import "net/http"
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-)
 
-// RegisterOption is a functional option for the Register function.
+// RegisterOption configures a registration request.
 type RegisterOption func(*AuthRegisterRequest)
 
 // WithDisplayName sets the display_name on a registration request.
 func WithDisplayName(name string) RegisterOption {
-	return func(req *AuthRegisterRequest) {
+	return func(req *AuthRegisterRequest) { req.DisplayName = name }
-		req.DisplayName = name
-	}
 }
 
 // WithOrgName sets the org_name on a registration request.
 func WithOrgName(name string) RegisterOption {
-	return func(req *AuthRegisterRequest) {
+	return func(req *AuthRegisterRequest) { req.OrgName = name }
-		req.OrgName = name
-	}
 }
 
 // Register creates a new user and organization.
 //
-// Deprecated: Use Better Auth endpoints directly. See docs.
+// Deprecated: use the Console sign-up flow; password registration is being phased out.
 func Register(baseURL, email, password string, opts ...RegisterOption) (*AuthRegisterResponse, error) {
-	if baseURL == "" {
+	req := &AuthRegisterRequest{Email: email, Password: password}
-		baseURL = defaultBaseURL
-	}
-	baseURL = strings.TrimRight(baseURL, "/")
-
-	req := &AuthRegisterRequest{
-		Email:    email,
-		Password: password,
-	}
 	for _, opt := range opts {
 		opt(req)
 	}
-
 	var result AuthRegisterResponse
-	if err := authPost(baseURL, "/v1/auth/register", req, &result); err != nil {
+	if err := publicRequest(http.MethodPost, normalizeBaseURL(baseURL)+"/v1/auth/register", req, &result); err != nil {
 		return nil, err
 	}
 	return &result, nil
@@ -53,80 +32,16 @@ func Register(baseURL, email, password string, opts ...RegisterOption) (*AuthReg
 
 // Login authenticates a user and returns a session token.
 //
-// Deprecated: Use Better Auth endpoints directly. See docs.
+// Deprecated: use the Console sign-in flow; password login is being phased out.
 func Login(baseURL, email, password string) (*AuthLoginResponse, error) {
-	if baseURL == "" {
+	req := &AuthLoginRequest{Email: email, Password: password}
-		baseURL = defaultBaseURL
-	}
-	baseURL = strings.TrimRight(baseURL, "/")
-
-	req := &AuthLoginRequest{
-		Email:    email,
-		Password: password,
-	}
-
 	var result AuthLoginResponse
-	if err := authPost(baseURL, "/v1/auth/login", req, &result); err != nil {
+	if err := publicRequest(http.MethodPost, normalizeBaseURL(baseURL)+"/v1/auth/login", req, &result); err != nil {
 		return nil, err
 	}
 	return &result, nil
 }
 
-// authPost is a helper for unauthenticated POST requests used by Register and Login.
-func authPost(baseURL, path string, body interface{}, result interface{}) error {
-	u := baseURL + path
-
-	data, err := json.Marshal(body)
-	if err != nil {
-		return fmt.Errorf("elydora: marshal request body: %w", err)
-	}
-
-	client := &http.Client{Timeout: 30 * time.Second}
-	req, err := http.NewRequest(http.MethodPost, u, bytes.NewReader(data))
-	if err != nil {
-		return fmt.Errorf("elydora: create request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("Accept", "application/json")
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return fmt.Errorf("elydora: http request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	respBody, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
-	if err != nil {
-		return fmt.Errorf("elydora: read response body: %w", err)
-	}
-
-	if resp.StatusCode >= 200 && resp.StatusCode < 300 {
-		if result != nil && len(respBody) > 0 {
-			if err := json.Unmarshal(respBody, result); err != nil {
-				return fmt.Errorf("elydora: unmarshal response: %w", err)
-			}
-		}
-		return nil
-	}
-
-	var errResp errorResponse
-	if err := json.Unmarshal(respBody, &errResp); err == nil && errResp.Error.Code != "" {
-		return &ElydoraError{
-			StatusCode: resp.StatusCode,
-			Code:       errResp.Error.Code,
-			Message:    errResp.Error.Message,
-			RequestID:  errResp.Error.RequestID,
-			Details:    errResp.Error.Details,
-		}
-	}
-
-	return &ElydoraError{
-		StatusCode: resp.StatusCode,
-		Code:       ErrorCodeInternalError,
-		Message:    string(respBody),
-	}
-}
-
 // GetMe retrieves the current authenticated user's profile.
 func (c *Client) GetMe() (*GetMeResponse, error) {
 	var result GetMeResponse
@@ -145,8 +60,7 @@ func (c *Client) IssueApiToken(req *IssueApiTokenRequest) (*IssueApiTokenRespons
 	return &result, nil
 }
 
-// RotateApiToken rotates the current API token and leaves the old token
+// RotateApiToken rotates the current API token; the old token stays valid for 24h.
-// valid for a 24h grace window.
 func (c *Client) RotateApiToken() (*RotateApiTokenResponse, error) {
 	var result RotateApiTokenResponse
 	if err := c.doPost("/v1/auth/rotate", map[string]interface{}{}, &result); err != nil {

client.go

@@ -14,6 +14,8 @@ const (
 	defaultBaseURL    = "https://api.elydora.com"
 	defaultTTLMs      = 30000
 	defaultMaxRetries = 3
+	maxResponseBytes  = 10 << 20
+	requestTimeout    = 30 * time.Second
 )
 
 // Config holds the configuration for creating a new Client.
@@ -44,135 +46,180 @@ func NewClient(cfg *Config) (*Client, error) {
 	if cfg == nil {
 		return nil, fmt.Errorf("elydora: config must not be nil")
 	}
-
-	baseURL := cfg.BaseURL
-	if baseURL == "" {
-		baseURL = defaultBaseURL
-	}
-	baseURL = strings.TrimRight(baseURL, "/")
-
 	ttlMs := cfg.TTLMs
 	if ttlMs <= 0 {
 		ttlMs = defaultTTLMs
 	}
-
 	maxRetries := cfg.MaxRetries
 	if maxRetries <= 0 {
 		maxRetries = defaultMaxRetries
 	}
-
 	return &Client{
 		orgID:      cfg.OrgID,
 		agentID:    cfg.AgentID,
 		privateKey: cfg.PrivateKey,
-		baseURL:    baseURL,
+		baseURL:    normalizeBaseURL(cfg.BaseURL),
 		ttlMs:      ttlMs,
 		maxRetries: maxRetries,
 		token:      cfg.Token,
-		httpClient: &http.Client{
+		httpClient: &http.Client{Timeout: requestTimeout},
-			Timeout: 30 * time.Second,
-		},
 	}, nil
 }
 
-// doRequest executes an HTTP request with retries and error handling.
-func (c *Client) doRequest(method, path string, body interface{}, result interface{}) error {
-	u := c.baseURL + path
-
-	var bodyReader io.Reader
-	if body != nil {
-		data, err := json.Marshal(body)
-		if err != nil {
-			return fmt.Errorf("elydora: marshal request body: %w", err)
-		}
-		bodyReader = bytes.NewReader(data)
-	}
-
-	var lastErr error
-	for attempt := 0; attempt <= c.maxRetries; attempt++ {
-		if attempt > 0 {
-			// Reset body reader for retry
-			if body != nil {
-				data, _ := json.Marshal(body)
-				bodyReader = bytes.NewReader(data)
-			}
-			time.Sleep(time.Duration(attempt*attempt) * 100 * time.Millisecond)
-		}
-
-		req, err := http.NewRequest(method, u, bodyReader)
-		if err != nil {
-			return fmt.Errorf("elydora: create request: %w", err)
-		}
-
-		req.Header.Set("Content-Type", "application/json")
-		req.Header.Set("Accept", "application/json")
-		if c.token != "" {
-			req.Header.Set("Authorization", "Bearer "+c.token)
-		}
-
-		resp, err := c.httpClient.Do(req)
-		if err != nil {
-			lastErr = fmt.Errorf("elydora: http request: %w", err)
-			continue
-		}
-
-		respBody, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
-		resp.Body.Close()
-		if err != nil {
-			lastErr = fmt.Errorf("elydora: read response body: %w", err)
-			continue
-		}
-
-		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
-			if result != nil && len(respBody) > 0 {
-				if err := json.Unmarshal(respBody, result); err != nil {
-					return fmt.Errorf("elydora: unmarshal response: %w", err)
-				}
-			}
-			return nil
-		}
-
-		// Parse error response
-		var errResp errorResponse
-		if err := json.Unmarshal(respBody, &errResp); err == nil && errResp.Error.Code != "" {
-			apiErr := &ElydoraError{
-				StatusCode: resp.StatusCode,
-				Code:       errResp.Error.Code,
-				Message:    errResp.Error.Message,
-				RequestID:  errResp.Error.RequestID,
-				Details:    errResp.Error.Details,
-			}
-			// Don't retry 4xx errors (except 429)
-			if resp.StatusCode < 500 && resp.StatusCode != 429 {
-				return apiErr
-			}
-			lastErr = apiErr
-			continue
-		}
-
-		lastErr = &ElydoraError{
-			StatusCode: resp.StatusCode,
-			Code:       ErrorCodeInternalError,
-			Message:    string(respBody),
-		}
-		if resp.StatusCode < 500 && resp.StatusCode != 429 {
-			return lastErr
-		}
-	}
-	return lastErr
-}
-
-// doGet performs a GET request.
-func (c *Client) doGet(path string, result interface{}) error {
-	return c.doRequest(http.MethodGet, path, nil, result)
-}
-
-// doPost performs a POST request.
-func (c *Client) doPost(path string, body interface{}, result interface{}) error {
-	return c.doRequest(http.MethodPost, path, body, result)
-}
-
 // SetToken sets the API token used for authenticated API requests.
 func (c *Client) SetToken(token string) {
 	c.token = token
 }
+
+func normalizeBaseURL(baseURL string) string {
+	if baseURL == "" {
+		baseURL = defaultBaseURL
+	}
+	return strings.TrimRight(baseURL, "/")
+}
+
+func newRequest(method, url string, body []byte, token, accept string) (*http.Request, error) {
+	var reader io.Reader
+	if body != nil {
+		reader = bytes.NewReader(body)
+	}
+	req, err := http.NewRequest(method, url, reader)
+	if err != nil {
+		return nil, fmt.Errorf("elydora: create request: %w", err)
+	}
+	if accept != "" {
+		req.Header.Set("Accept", accept)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	return req, nil
+}
+
+func marshalBody(body interface{}) ([]byte, error) {
+	if body == nil {
+		return nil, nil
+	}
+	data, err := json.Marshal(body)
+	if err != nil {
+		return nil, fmt.Errorf("elydora: marshal request body: %w", err)
+	}
+	return data, nil
+}
+
+func readBody(resp *http.Response, limit int64) ([]byte, error) {
+	defer resp.Body.Close()
+	var reader io.Reader = resp.Body
+	if limit > 0 {
+		reader = io.LimitReader(resp.Body, limit)
+	}
+	body, err := io.ReadAll(reader)
+	if err != nil {
+		return nil, fmt.Errorf("elydora: read response body: %w", err)
+	}
+	return body, nil
+}
+
+func decodeSuccess(body []byte, result interface{}) error {
+	if result == nil {
+		return nil
+	}
+	if err := json.Unmarshal(body, result); err != nil {
+		return fmt.Errorf("elydora: unmarshal response: %w", err)
+	}
+	return nil
+}
+
+func apiError(status int, body []byte) *ElydoraError {
+	var errResp errorResponse
+	if err := json.Unmarshal(body, &errResp); err == nil && errResp.Error.Code != "" {
+		return &ElydoraError{
+			StatusCode: status,
+			Code:       errResp.Error.Code,
+			Message:    errResp.Error.Message,
+			RequestID:  errResp.Error.RequestID,
+			Details:    errResp.Error.Details,
+		}
+	}
+	return &ElydoraError{StatusCode: status, Code: ErrorCodeInternalError, Message: string(body)}
+}
+
+func retryable(status int) bool {
+	return status >= 500 || status == http.StatusTooManyRequests
+}
+
+// doRequest executes an authenticated request, retrying transport and 5xx failures.
+func (c *Client) doRequest(method, path string, body interface{}, result interface{}) error {
+	data, err := marshalBody(body)
+	if err != nil {
+		return err
+	}
+	var lastErr error
+	for attempt := 0; attempt <= c.maxRetries; attempt++ {
+		if attempt > 0 {
+			time.Sleep(time.Duration(attempt*attempt) * 100 * time.Millisecond)
+		}
+		req, err := newRequest(method, c.baseURL+path, data, c.token, "application/json")
+		if err != nil {
+			return err
+		}
+		resp, err := c.httpClient.Do(req)
+		if err != nil {
+			lastErr = fmt.Errorf("elydora: http request: %w", err)
+			continue
+		}
+		respBody, err := readBody(resp, maxResponseBytes)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+			return decodeSuccess(respBody, result)
+		}
+		lastErr = apiError(resp.StatusCode, respBody)
+		if !retryable(resp.StatusCode) {
+			return lastErr
+		}
+	}
+	return lastErr
+}
+
+func (c *Client) doGet(path string, result interface{}) error {
+	return c.doRequest(http.MethodGet, path, nil, result)
+}
+
+func (c *Client) doPost(path string, body interface{}, result interface{}) error {
+	return c.doRequest(http.MethodPost, path, body, result)
+}
+
+// publicRequest sends one unauthenticated request and decodes accepted statuses.
+func publicRequest(method, url string, body interface{}, result interface{}, accepted ...int) error {
+	data, err := marshalBody(body)
+	if err != nil {
+		return err
+	}
+	req, err := newRequest(method, url, data, "", "application/json")
+	if err != nil {
+		return err
+	}
+	resp, err := (&http.Client{Timeout: requestTimeout}).Do(req)
+	if err != nil {
+		return fmt.Errorf("elydora: http request: %w", err)
+	}
+	respBody, err := readBody(resp, maxResponseBytes)
+	if err != nil {
+		return err
+	}
+	for _, status := range accepted {
+		if resp.StatusCode == status {
+			return decodeSuccess(respBody, result)
+		}
+	}
+	if len(accepted) == 0 && resp.StatusCode >= 200 && resp.StatusCode < 300 {
+		return decodeSuccess(respBody, result)
+	}
+	return apiError(resp.StatusCode, respBody)
+}

crypto.go

@@ -11,12 +11,6 @@ import (
 	"strings"
 )
 
-// sha256Base64url computes SHA-256 of the input string and returns base64url-encoded result.
-func sha256Base64url(data string) string {
-	h := sha256.Sum256([]byte(data))
-	return base64urlEncode(h[:])
-}
-
 // sha256BytesBase64url computes SHA-256 of raw bytes and returns base64url-encoded result.
 func sha256BytesBase64url(data []byte) string {
 	h := sha256.Sum256(data)
@@ -32,8 +26,7 @@ func computePayloadHash(payload interface{}) (string, error) {
 	return sha256BytesBase64url([]byte(canonical)), nil
 }
 
-// signEd25519 signs data with an Ed25519 private key seed (base64url-encoded 32 bytes).
+// signEd25519 signs data with a base64url Ed25519 seed and returns a base64url signature.
-// Returns the signature as base64url.
 func signEd25519(privateKeyBase64url string, data []byte) (string, error) {
 	seed, err := base64urlDecode(privateKeyBase64url)
 	if err != nil {
@@ -47,13 +40,7 @@ func signEd25519(privateKeyBase64url string, data []byte) (string, error) {
 	return base64urlEncode(sig), nil
 }
 
-// ---------------------------------------------------------------------------
+// jcsCanonicalise renders a value as RFC 8785 canonical JSON.
-// JCS Canonicalization (RFC 8785)
-// ---------------------------------------------------------------------------
-
-// jcsCanonicalise produces a JCS-canonicalized JSON string from a Go value.
-// Object keys are sorted lexicographically, no whitespace is used, and numbers
-// follow ES2015 serialization rules.
 func jcsCanonicalise(value interface{}) (string, error) {
 	var b strings.Builder
 	if err := jcsWrite(&b, value); err != nil {
@@ -113,10 +100,6 @@ func jcsWrite(b *strings.Builder, value interface{}) error {
 		first := true
 		for _, k := range keys {
 			val := v[k]
-			if val == nil {
-				// JCS includes null values but skips undefined; in Go there is no undefined
-				// so we include null.
-			}
 			if !first {
 				b.WriteByte(',')
 			}
@@ -145,7 +128,7 @@ func jcsWrite(b *strings.Builder, value interface{}) error {
 	return nil
 }
 
-// jcsWriteString writes a JSON string with minimal escaping per the JSON spec.
+// jcsWriteString writes a JSON string with minimal escaping.
 func jcsWriteString(b *strings.Builder, s string) {
 	b.WriteByte('"')
 	for _, r := range s {
@@ -175,7 +158,7 @@ func jcsWriteString(b *strings.Builder, s string) {
 	b.WriteByte('"')
 }
 
-// jcsFormatNumber formats a float64 according to ES2015 Number serialization (JCS/RFC 8785).
+// jcsFormatNumber formats a float64 as ES2015 Number serialization.
 func jcsFormatNumber(f float64) string {
 	if math.IsNaN(f) || math.IsInf(f, 0) {
 		return "null"
@@ -183,18 +166,14 @@ func jcsFormatNumber(f float64) string {
 	if f == 0 {
 		return "0"
 	}
-	// If the number is an integer that fits in int64, format without decimal point
 	if f == math.Trunc(f) && !math.IsInf(f, 0) && math.Abs(f) < 1e20 {
 		return strconv.FormatInt(int64(f), 10)
 	}
-	// Use the shortest representation that round-trips
 	return strconv.FormatFloat(f, 'G', -1, 64)
 }
 
-// signEOR signs an EOR struct. It computes the canonical representation (all fields except signature),
+// signEOR signs the canonical EOR fields except the signature.
-// hashes it, and produces an Ed25519 signature.
 func signEOR(eor *EOR, privateKeyBase64url string) (string, error) {
-	// Build canonical EOR without signature field
 	canonical := map[string]interface{}{
 		"op_version":       eor.OpVersion,
 		"operation_id":     eor.OperationID,

exports.go

@@ -1,9 +1,7 @@
 package elydora
 
 import (
-	"encoding/json"
 	"fmt"
-	"io"
 	"net/http"
 )
 
@@ -36,44 +34,20 @@ func (c *Client) GetExport(exportID string) (*GetExportResponse, error) {
 
 // DownloadExport downloads the raw file data for a completed export.
 func (c *Client) DownloadExport(exportID string) ([]byte, error) {
-	u := c.baseURL + fmt.Sprintf("/v1/exports/%s/download", exportID)
+	req, err := newRequest(http.MethodGet, c.baseURL+fmt.Sprintf("/v1/exports/%s/download", exportID), nil, c.token, "")
-
-	req, err := http.NewRequest(http.MethodGet, u, nil)
 	if err != nil {
-		return nil, fmt.Errorf("elydora: create request: %w", err)
+		return nil, err
 	}
-	if c.token != "" {
-		req.Header.Set("Authorization", "Bearer "+c.token)
-	}
-
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
 		return nil, fmt.Errorf("elydora: http request: %w", err)
 	}
-	defer resp.Body.Close()
+	body, err := readBody(resp, 0)
-
-	body, err := io.ReadAll(resp.Body)
 	if err != nil {
-		return nil, fmt.Errorf("elydora: read response body: %w", err)
+		return nil, err
 	}
-
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		var errResp errorResponse
+		return nil, apiError(resp.StatusCode, body)
-		if jsonErr := json.Unmarshal(body, &errResp); jsonErr == nil && errResp.Error.Code != "" {
-			return nil, &ElydoraError{
-				StatusCode: resp.StatusCode,
-				Code:       errResp.Error.Code,
-				Message:    errResp.Error.Message,
-				RequestID:  errResp.Error.RequestID,
-				Details:    errResp.Error.Details,
 	}
-		}
-		return nil, &ElydoraError{
-			StatusCode: resp.StatusCode,
-			Code:       ErrorCodeInternalError,
-			Message:    string(body),
-		}
-	}
-
 	return body, nil
 }

health.go

@@ -1,116 +1,29 @@
 package elydora
 
-import (
+import "net/http"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-)
 
-// Health checks the health of the Elydora API. This is a public endpoint
+// Health checks the public health endpoint.
-// that does not require authentication.
 func Health(baseURL string) (*HealthResponse, error) {
-	if baseURL == "" {
-		baseURL = defaultBaseURL
-	}
-	baseURL = strings.TrimRight(baseURL, "/")
-
-	client := &http.Client{Timeout: 30 * time.Second}
-	req, err := http.NewRequest(http.MethodGet, baseURL+"/v1/health", nil)
-	if err != nil {
-		return nil, fmt.Errorf("elydora: create request: %w", err)
-	}
-	req.Header.Set("Accept", "application/json")
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("elydora: http request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	respBody, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
-	if err != nil {
-		return nil, fmt.Errorf("elydora: read response body: %w", err)
-	}
-
-	if resp.StatusCode >= 200 && resp.StatusCode < 300 {
 	var result HealthResponse
-		if err := json.Unmarshal(respBody, &result); err != nil {
+	if err := publicRequest(http.MethodGet, normalizeBaseURL(baseURL)+"/v1/health", nil, &result); err != nil {
-			return nil, fmt.Errorf("elydora: unmarshal response: %w", err)
+		return nil, err
 	}
 	return &result, nil
 }
 
-	var errResp errorResponse
+// DeepHealth checks backend dependencies; 503 reports a degraded API.
-	if err := json.Unmarshal(respBody, &errResp); err == nil && errResp.Error.Code != "" {
-		return nil, &ElydoraError{
-			StatusCode: resp.StatusCode,
-			Code:       errResp.Error.Code,
-			Message:    errResp.Error.Message,
-			RequestID:  errResp.Error.RequestID,
-			Details:    errResp.Error.Details,
-		}
-	}
-
-	return nil, &ElydoraError{
-		StatusCode: resp.StatusCode,
-		Code:       ErrorCodeInternalError,
-		Message:    string(respBody),
-	}
-}
-
-// DeepHealth checks the deep health of the Elydora API, including its backend
-// dependencies (D1, R2, KV). This is a public endpoint that does not require
-// authentication.
 func DeepHealth(baseURL string) (*DeepHealthResponse, error) {
-	if baseURL == "" {
-		baseURL = defaultBaseURL
-	}
-	baseURL = strings.TrimRight(baseURL, "/")
-
-	client := &http.Client{Timeout: 30 * time.Second}
-	req, err := http.NewRequest(http.MethodGet, baseURL+"/v1/health/deep", nil)
-	if err != nil {
-		return nil, fmt.Errorf("elydora: create request: %w", err)
-	}
-	req.Header.Set("Accept", "application/json")
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("elydora: http request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	respBody, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
-	if err != nil {
-		return nil, fmt.Errorf("elydora: read response body: %w", err)
-	}
-
-	// Accept both 200 (healthy) and 503 (degraded) as valid deep-health responses.
-	if resp.StatusCode == http.StatusOK || resp.StatusCode == http.StatusServiceUnavailable {
 	var result DeepHealthResponse
-		if err := json.Unmarshal(respBody, &result); err != nil {
+	err := publicRequest(
-			return nil, fmt.Errorf("elydora: unmarshal response: %w", err)
+		http.MethodGet,
+		normalizeBaseURL(baseURL)+"/v1/health/deep",
+		nil,
+		&result,
+		http.StatusOK,
+		http.StatusServiceUnavailable,
+	)
+	if err != nil {
+		return nil, err
 	}
 	return &result, nil
 }
-
-	var errResp errorResponse
-	if err := json.Unmarshal(respBody, &errResp); err == nil && errResp.Error.Code != "" {
-		return nil, &ElydoraError{
-			StatusCode: resp.StatusCode,
-			Code:       errResp.Error.Code,
-			Message:    errResp.Error.Message,
-			RequestID:  errResp.Error.RequestID,
-			Details:    errResp.Error.Details,
-		}
-	}
-
-	return nil, &ElydoraError{
-		StatusCode: resp.StatusCode,
-		Code:       ErrorCodeInternalError,
-		Message:    string(respBody),
-	}
-}

operations.go

@@ -2,13 +2,10 @@ package elydora
 
 import "fmt"
 
-// GenesisChainHash is the initial chain hash for an agent's first operation.
+// GenesisChainHash is the base64url encoding of 32 zero bytes.
-// It is the base64url encoding of 32 zero bytes, matching the backend.
 const GenesisChainHash = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
 
-// CreateOperation builds a signed EOR from the given parameters.
+// CreateOperation builds and signs an EOR locally.
-// It generates a UUIDv7 operation ID, a nonce, computes the payload hash and chain hash,
-// and signs the entire record with the client's private key.
 func (c *Client) CreateOperation(params *CreateOperationParams) (*EOR, error) {
 	if params == nil {
 		return nil, fmt.Errorf("elydora: params must not be nil")

sdk_compat_integration_test.go

@@ -81,8 +81,8 @@ func TestSDKCompatibilityAgainstLatestAPI(t *testing.T) {
 	if err != nil {
 		t.Fatalf("api token auth failed: %v", err)
 	}
-	if meWithAPI.User.OrgID != login.User.OrgID {
+	if orgID(meWithAPI.User.OrgID) != login.User.OrgID {
-		t.Fatalf("api token org mismatch: got %s want %s", meWithAPI.User.OrgID, login.User.OrgID)
+		t.Fatalf("api token org mismatch: got %s want %s", orgID(meWithAPI.User.OrgID), login.User.OrgID)
 	}
 
 	rotateResp, err := client.RotateApiToken()
@@ -98,8 +98,8 @@ func TestSDKCompatibilityAgainstLatestAPI(t *testing.T) {
 	if err != nil {
 		t.Fatalf("rotated token auth failed: %v", err)
 	}
-	if meWithRotated.User.OrgID != login.User.OrgID {
+	if orgID(meWithRotated.User.OrgID) != login.User.OrgID {
-		t.Fatalf("rotated token org mismatch: got %s want %s", meWithRotated.User.OrgID, login.User.OrgID)
+		t.Fatalf("rotated token org mismatch: got %s want %s", orgID(meWithRotated.User.OrgID), login.User.OrgID)
 	}
 
 	_, err = client.RegisterAgent(&elydora.RegisterAgentRequest{
@@ -154,3 +154,10 @@ func TestSDKCompatibilityAgainstLatestAPI(t *testing.T) {
 		t.Fatalf("verify operation invalid: %+v", verify)
 	}
 }
+
+func orgID(value *string) string {
+	if value == nil {
+		return ""
+	}
+	return *value
+}

types.go

@@ -1,9 +1,5 @@
 package elydora
 
-// ---------------------------------------------------------------------------
-// Enums
-// ---------------------------------------------------------------------------
-
 type AgentStatus string
 
 const (
@@ -69,7 +65,9 @@ const (
 	ErrorCodeInvalidSignature ErrorCode = "INVALID_SIGNATURE"
 	ErrorCodeUnknownAgent     ErrorCode = "UNKNOWN_AGENT"
 	ErrorCodeKeyRevoked       ErrorCode = "KEY_REVOKED"
+	ErrorCodeKeyRetired       ErrorCode = "KEY_RETIRED"
 	ErrorCodeAgentFrozen      ErrorCode = "AGENT_FROZEN"
+	ErrorCodeAgentRevoked     ErrorCode = "AGENT_REVOKED"
 	ErrorCodeTTLExpired       ErrorCode = "TTL_EXPIRED"
 	ErrorCodeReplayDetected   ErrorCode = "REPLAY_DETECTED"
 	ErrorCodePrevHashMismatch ErrorCode = "PREV_HASH_MISMATCH"
@@ -82,6 +80,36 @@ const (
 	ErrorCodeValidationError  ErrorCode = "VALIDATION_ERROR"
 )
 
+type AdminAction string
+
+const (
+	AdminActionAgentRegister    AdminAction = "agent.register"
+	AdminActionAgentUpdate      AdminAction = "agent.update"
+	AdminActionAgentFreeze      AdminAction = "agent.freeze"
+	AdminActionAgentUnfreeze    AdminAction = "agent.unfreeze"
+	AdminActionAgentRevoke      AdminAction = "agent.revoke"
+	AdminActionAgentDelete      AdminAction = "agent.delete"
+	AdminActionKeyRevoke        AdminAction = "key.revoke"
+	AdminActionExportCreate     AdminAction = "export.create"
+	AdminActionOrgCreate        AdminAction = "org.create"
+	AdminActionOrgUpdate        AdminAction = "org.update"
+	AdminActionMemberInvite     AdminAction = "member.invite"
+	AdminActionInvitationCancel AdminAction = "invitation.cancel"
+	AdminActionMemberRemove     AdminAction = "member.remove"
+	AdminActionMemberRoleChange AdminAction = "member.role_change"
+	AdminActionAgentAssign      AdminAction = "agent.assign"
+	AdminActionAgentUnassign    AdminAction = "agent.unassign"
+	AdminActionWebhookRegister  AdminAction = "webhook.register"
+	AdminActionWebhookDelete    AdminAction = "webhook.delete"
+)
+
+type WebhookStatus string
+
+const (
+	WebhookStatusActive   WebhookStatus = "active"
+	WebhookStatusDisabled WebhookStatus = "disabled"
+)
+
 type ExportFormat string
 
 const (
@@ -89,10 +117,6 @@ const (
 	ExportFormatPDF  ExportFormat = "pdf"
 )
 
-// ---------------------------------------------------------------------------
-// Entity types
-// ---------------------------------------------------------------------------
-
 type Agent struct {
 	AgentID           string          `json:"agent_id"`
 	OrgID             string          `json:"org_id"`
@@ -155,7 +179,7 @@ type Epoch struct {
 type Organization struct {
 	OrgID       string  `json:"org_id"`
 	Name        string  `json:"name"`
-	Description string  `json:"description"`
+	Description *string `json:"description"`
 	BAOrgID     *string `json:"ba_org_id"`
 	CreatedAt   int64   `json:"created_at"`
 	UpdatedAt   int64   `json:"updated_at"`
@@ -182,11 +206,7 @@ type Export struct {
 	CompletedAt *int64       `json:"completed_at"`
 }
 
-// ---------------------------------------------------------------------------
+// EOR is the Elydora Operation Record.
-// Protocol types
-// ---------------------------------------------------------------------------
-
-// EOR is the Elydora Operation Record — the fundamental unit of auditable activity.
 type EOR struct {
 	OpVersion      string      `json:"op_version"`
 	OperationID    string      `json:"operation_id"`
@@ -205,7 +225,7 @@ type EOR struct {
 	Signature      string      `json:"signature"`
 }
 
-// EAR is the Elydora Acknowledgment Receipt — server-issued receipt confirming acceptance.
+// EAR is the Elydora Acknowledgment Receipt.
 type EAR struct {
 	ReceiptVersion   string `json:"receipt_version"`
 	ReceiptID        string `json:"receipt_id"`
@@ -221,210 +241,6 @@ type EAR struct {
 	ElydoraSignature string `json:"elydora_signature"`
 }
 
-// ---------------------------------------------------------------------------
-// API request/response types
-// ---------------------------------------------------------------------------
-
-type RegisterAgentKeyInput struct {
-	KID       string `json:"kid"`
-	PublicKey string `json:"public_key"`
-	Algorithm string `json:"algorithm"`
-}
-
-type RegisterAgentRequest struct {
-	AgentID           string                  `json:"agent_id"`
-	DisplayName       string                  `json:"display_name,omitempty"`
-	ResponsibleEntity string                  `json:"responsible_entity,omitempty"`
-	IntegrationType   IntegrationType         `json:"integration_type"`
-	Keys              []RegisterAgentKeyInput `json:"keys"`
-}
-
-type RegisterAgentResponse struct {
-	Agent Agent      `json:"agent"`
-	Keys  []AgentKey `json:"keys"`
-}
-
-type GetAgentResponse struct {
-	Agent Agent      `json:"agent"`
-	Keys  []AgentKey `json:"keys"`
-}
-
-type FreezeAgentRequest struct {
-	Reason string `json:"reason"`
-}
-
-type FreezeAgentResponse struct {
-	Agent          Agent       `json:"agent"`
-	PreviousStatus AgentStatus `json:"previous_status"`
-}
-
-type RevokeAgentRequest struct {
-	KID    string `json:"kid"`
-	Reason string `json:"reason"`
-}
-
-type UnfreezeAgentRequest struct {
-	Reason string `json:"reason"`
-}
-
-type UnfreezeAgentResponse struct {
-	Agent          Agent       `json:"agent"`
-	PreviousStatus AgentStatus `json:"previous_status"`
-}
-
-type UpdateAgentRequest struct {
-	IntegrationType IntegrationType `json:"integration_type"`
-}
-
-type UpdateAgentResponse struct {
-	Agent Agent `json:"agent"`
-}
-
-type ListAgentsResponse struct {
-	Agents []Agent `json:"agents"`
-}
-
-type DeleteAgentResponse struct {
-	Deleted bool `json:"deleted"`
-}
-
-type GetMeResponse struct {
-	User User `json:"user"`
-}
-
-type IssueApiTokenRequest struct {
-	TTLSeconds *int `json:"ttl_seconds"`
-}
-
-type IssueApiTokenResponse struct {
-	Token     string `json:"token"`
-	ExpiresAt *int64 `json:"expires_at"`
-	TokenID   string `json:"token_id"`
-}
-
-type RotateApiTokenResponse struct {
-	Token     string `json:"token"`
-	ExpiresAt *int64 `json:"expires_at"`
-	TokenID   string `json:"token_id"`
-}
-
-type HealthResponse struct {
-	Status          string `json:"status"`
-	Version         string `json:"version"`
-	ProtocolVersion string `json:"protocol_version"`
-	Timestamp       int64  `json:"timestamp"`
-}
-
-type SubmitOperationResponse struct {
-	Receipt EAR `json:"receipt"`
-}
-
-type GetOperationResponse struct {
-	Operation Operation `json:"operation"`
-	Receipt   *Receipt  `json:"receipt,omitempty"`
-}
-
-type VerifyOperationChecks struct {
-	Signature bool  `json:"signature"`
-	Chain     bool  `json:"chain"`
-	Receipt   bool  `json:"receipt"`
-	Merkle    *bool `json:"merkle,omitempty"`
-}
-
-type VerifyOperationResponse struct {
-	Valid  bool                  `json:"valid"`
-	Checks VerifyOperationChecks `json:"checks"`
-	Errors []string              `json:"errors,omitempty"`
-}
-
-type AuditQueryRequest struct {
-	OrgID         string `json:"org_id,omitempty"`
-	AgentID       string `json:"agent_id,omitempty"`
-	OperationType string `json:"operation_type,omitempty"`
-	StartTime     *int64 `json:"start_time,omitempty"`
-	EndTime       *int64 `json:"end_time,omitempty"`
-	Cursor        string `json:"cursor,omitempty"`
-	Limit         *int   `json:"limit,omitempty"`
-}
-
-type AuditQueryResponse struct {
-	Operations []Operation `json:"operations"`
-	Cursor     string      `json:"cursor,omitempty"`
-	TotalCount int64       `json:"total_count"`
-}
-
-type GetEpochResponse struct {
-	Epoch  Epoch        `json:"epoch"`
-	Anchor *EpochAnchor `json:"anchor,omitempty"`
-}
-
-type EpochAnchor struct {
-	TSAToken   string `json:"tsa_token,omitempty"`
-	TSAUrl     string `json:"tsa_url,omitempty"`
-	AnchoredAt *int64 `json:"anchored_at,omitempty"`
-}
-
-type ListEpochsResponse struct {
-	Epochs []Epoch `json:"epochs"`
-}
-
-type CreateExportRequest struct {
-	StartTime     int64        `json:"start_time"`
-	EndTime       int64        `json:"end_time"`
-	AgentID       string       `json:"agent_id,omitempty"`
-	OperationType string       `json:"operation_type,omitempty"`
-	Format        ExportFormat `json:"format"`
-}
-
-type CreateExportResponse struct {
-	Export Export `json:"export"`
-}
-
-type GetExportResponse struct {
-	Export      Export `json:"export"`
-	DownloadURL string `json:"download_url,omitempty"`
-}
-
-type ListExportsResponse struct {
-	Exports []Export `json:"exports"`
-}
-
-type JWK struct {
-	KTY string `json:"kty"`
-	CRV string `json:"crv,omitempty"`
-	X   string `json:"x,omitempty"`
-	KID string `json:"kid"`
-	Use string `json:"use"`
-	Alg string `json:"alg"`
-}
-
-type JWKSResponse struct {
-	Keys []JWK `json:"keys"`
-}
-
-type AuthRegisterRequest struct {
-	Email       string `json:"email"`
-	Password    string `json:"password"`
-	DisplayName string `json:"display_name,omitempty"`
-	OrgName     string `json:"org_name,omitempty"`
-}
-
-type AuthRegisterResponse struct {
-	User         User         `json:"user"`
-	Organization Organization `json:"organization"`
-	Token        string       `json:"token"`
-}
-
-type AuthLoginRequest struct {
-	Email    string `json:"email"`
-	Password string `json:"password"`
-}
-
-type AuthLoginResponse struct {
-	User  User   `json:"user"`
-	Token string `json:"token"`
-}
-
 // AdminEvent represents an administrative event log entry.
 type AdminEvent struct {
 	EventID    string  `json:"event_id"`
@@ -453,25 +269,11 @@ type Webhook struct {
 	OrgID       string        `json:"org_id"`
 	EndpointURL string        `json:"endpoint_url"`
 	Events      []string      `json:"events"`
-	Status      string   `json:"status"`
+	Status      WebhookStatus `json:"status"`
 	CreatedAt   int64         `json:"created_at"`
 	UpdatedAt   int64         `json:"updated_at"`
 }
 
-type ListWebhooksResponse struct {
-	Webhooks []Webhook `json:"webhooks"`
-}
-
-type RegisterWebhookRequest struct {
-	EndpointURL string   `json:"endpoint_url"`
-	Events      []string `json:"events"`
-	Secret      string   `json:"secret"`
-}
-
-type RegisterWebhookResponse struct {
-	Webhook Webhook `json:"webhook"`
-}
-
 // Member represents a console user returned from the members list endpoint.
 type Member struct {
 	MemberID    string `json:"member_id"`
@@ -482,40 +284,42 @@ type Member struct {
 	DisplayName string `json:"display_name"`
 }
 
-type ListMembersResponse struct {
+// AuthMeUser is the profile returned by GET /v1/auth/me.
-	Members []Member `json:"members"`
+type AuthMeUser struct {
+	UserID              string   `json:"user_id"`
+	OrgID               *string  `json:"org_id"`
+	Email               string   `json:"email"`
+	DisplayName         string   `json:"display_name"`
+	Role                RbacRole `json:"role"`
+	Status              string   `json:"status"`
+	CreatedAt           int64    `json:"created_at"`
+	UpdatedAt           int64    `json:"updated_at"`
+	OnboardingCompleted bool     `json:"onboarding_completed"`
 }
 
-type ListAdminEventsResponse struct {
+// CurrentOrganization is the active organization of the authenticated user.
-	Events []AdminEvent `json:"events"`
+type CurrentOrganization struct {
+	OrgID   *string  `json:"org_id"`
+	BAOrgID *string  `json:"ba_org_id"`
+	Role    RbacRole `json:"role"`
 }
 
-// DependencyHealth holds the health status of a single backend dependency.
+// DependencyHealth is the health of one backend dependency.
 type DependencyHealth struct {
 	Status        string `json:"status"`
 	LatencyMs     int64  `json:"latency_ms"`
-	Error     *string `json:"error,omitempty"`
+	ContractPhase string `json:"contract_phase,omitempty"`
 }
 
-// DeepHealthDependencies lists the health of all backend dependencies.
+// DeepHealthDependencies lists every backend dependency.
 type DeepHealthDependencies struct {
 	D1          DependencyHealth `json:"d1"`
+	AuthStorage DependencyHealth `json:"auth_storage"`
 	R2          DependencyHealth `json:"r2"`
 	KV          DependencyHealth `json:"kv"`
 }
 
-// DeepHealthResponse is returned by GET /v1/health/deep.
+// CreateOperationParams are the inputs for CreateOperation.
-type DeepHealthResponse struct {
-	Status       string                 `json:"status"`
-	Version      string                 `json:"version"`
-	Timestamp    int64                  `json:"timestamp"`
-	Dependencies DeepHealthDependencies `json:"dependencies"`
-}
-
-// ---------------------------------------------------------------------------
-// CreateOperation params (SDK-specific)
-// ---------------------------------------------------------------------------
-
 type CreateOperationParams struct {
 	OperationType string
 	Subject       map[string]interface{}

types_api.go

@@ -0,0 +1,235 @@
+package elydora
+
+type RegisterAgentKeyInput struct {
+	KID       string `json:"kid"`
+	PublicKey string `json:"public_key"`
+	Algorithm string `json:"algorithm"`
+}
+
+type RegisterAgentRequest struct {
+	AgentID           string                  `json:"agent_id"`
+	DisplayName       string                  `json:"display_name,omitempty"`
+	ResponsibleEntity string                  `json:"responsible_entity,omitempty"`
+	IntegrationType   IntegrationType         `json:"integration_type"`
+	Keys              []RegisterAgentKeyInput `json:"keys"`
+}
+
+type RegisterAgentResponse struct {
+	Agent Agent      `json:"agent"`
+	Keys  []AgentKey `json:"keys"`
+}
+
+type GetAgentResponse struct {
+	Agent Agent      `json:"agent"`
+	Keys  []AgentKey `json:"keys"`
+}
+
+type FreezeAgentRequest struct {
+	Reason string `json:"reason"`
+}
+
+type FreezeAgentResponse struct {
+	Agent          Agent       `json:"agent"`
+	PreviousStatus AgentStatus `json:"previous_status"`
+}
+
+type RevokeAgentRequest struct {
+	KID    string `json:"kid"`
+	Reason string `json:"reason"`
+}
+
+type UnfreezeAgentRequest struct {
+	Reason string `json:"reason"`
+}
+
+type UnfreezeAgentResponse struct {
+	Agent          Agent       `json:"agent"`
+	PreviousStatus AgentStatus `json:"previous_status"`
+}
+
+type UpdateAgentRequest struct {
+	IntegrationType IntegrationType `json:"integration_type"`
+}
+
+type UpdateAgentResponse struct {
+	Agent Agent `json:"agent"`
+}
+
+type ListAgentsResponse struct {
+	Agents []Agent `json:"agents"`
+}
+
+type DeleteAgentResponse struct {
+	Deleted bool `json:"deleted"`
+}
+
+type GetMeResponse struct {
+	User                AuthMeUser          `json:"user"`
+	CurrentOrganization CurrentOrganization `json:"current_organization"`
+}
+
+type IssueApiTokenRequest struct {
+	TTLSeconds *int `json:"ttl_seconds"`
+}
+
+type IssueApiTokenResponse struct {
+	Token     string `json:"token"`
+	ExpiresAt *int64 `json:"expires_at"`
+	TokenID   string `json:"token_id"`
+}
+
+type RotateApiTokenResponse struct {
+	Token     string `json:"token"`
+	ExpiresAt *int64 `json:"expires_at"`
+	TokenID   string `json:"token_id"`
+}
+
+type HealthResponse struct {
+	Status          string            `json:"status"`
+	Version         string            `json:"version"`
+	ProtocolVersion string            `json:"protocol_version"`
+	Capabilities    map[string]string `json:"capabilities"`
+	Timestamp       int64             `json:"timestamp"`
+}
+
+type SubmitOperationResponse struct {
+	Receipt EAR `json:"receipt"`
+}
+
+type GetOperationResponse struct {
+	Operation Operation   `json:"operation"`
+	Receipt   *Receipt    `json:"receipt,omitempty"`
+	Payload   interface{} `json:"payload,omitempty"`
+}
+
+type VerifyOperationChecks struct {
+	Signature bool  `json:"signature"`
+	Chain     bool  `json:"chain"`
+	Receipt   bool  `json:"receipt"`
+	Merkle    *bool `json:"merkle,omitempty"`
+}
+
+type VerifyOperationResponse struct {
+	Valid  bool                  `json:"valid"`
+	Checks VerifyOperationChecks `json:"checks"`
+	Errors []string              `json:"errors,omitempty"`
+}
+
+type AuditQueryRequest struct {
+	OrgID         string `json:"org_id,omitempty"`
+	AgentID       string `json:"agent_id,omitempty"`
+	OperationType string `json:"operation_type,omitempty"`
+	StartTime     *int64 `json:"start_time,omitempty"`
+	EndTime       *int64 `json:"end_time,omitempty"`
+	Cursor        string `json:"cursor,omitempty"`
+	Limit         *int   `json:"limit,omitempty"`
+}
+
+type AuditQueryResponse struct {
+	Operations []Operation `json:"operations"`
+	Cursor     string      `json:"cursor,omitempty"`
+	TotalCount int64       `json:"total_count"`
+}
+
+type GetEpochResponse struct {
+	Epoch  Epoch        `json:"epoch"`
+	Anchor *EpochAnchor `json:"anchor,omitempty"`
+}
+
+type EpochAnchor struct {
+	TSAToken   string `json:"tsa_token,omitempty"`
+	TSAUrl     string `json:"tsa_url,omitempty"`
+	AnchoredAt *int64 `json:"anchored_at,omitempty"`
+}
+
+type ListEpochsResponse struct {
+	Epochs []Epoch `json:"epochs"`
+}
+
+type CreateExportRequest struct {
+	StartTime     int64        `json:"start_time"`
+	EndTime       int64        `json:"end_time"`
+	AgentID       string       `json:"agent_id,omitempty"`
+	OperationType string       `json:"operation_type,omitempty"`
+	Format        ExportFormat `json:"format"`
+}
+
+type CreateExportResponse struct {
+	Export Export `json:"export"`
+}
+
+type GetExportResponse struct {
+	Export      Export `json:"export"`
+	DownloadURL string `json:"download_url,omitempty"`
+}
+
+type ListExportsResponse struct {
+	Exports []Export `json:"exports"`
+}
+
+type JWK struct {
+	KTY string `json:"kty"`
+	CRV string `json:"crv,omitempty"`
+	X   string `json:"x,omitempty"`
+	KID string `json:"kid"`
+	Use string `json:"use"`
+	Alg string `json:"alg"`
+}
+
+type JWKSResponse struct {
+	Keys []JWK `json:"keys"`
+}
+
+type AuthRegisterRequest struct {
+	Email       string `json:"email"`
+	Password    string `json:"password"`
+	DisplayName string `json:"display_name,omitempty"`
+	OrgName     string `json:"org_name,omitempty"`
+}
+
+type AuthRegisterResponse struct {
+	User         User         `json:"user"`
+	Organization Organization `json:"organization"`
+	Token        string       `json:"token"`
+}
+
+type AuthLoginRequest struct {
+	Email    string `json:"email"`
+	Password string `json:"password"`
+}
+
+type AuthLoginResponse struct {
+	User  User   `json:"user"`
+	Token string `json:"token"`
+}
+
+type ListWebhooksResponse struct {
+	Webhooks []Webhook `json:"webhooks"`
+}
+
+type RegisterWebhookRequest struct {
+	EndpointURL string   `json:"endpoint_url"`
+	Events      []string `json:"events"`
+	Secret      string   `json:"secret"`
+}
+
+type RegisterWebhookResponse struct {
+	Webhook Webhook `json:"webhook"`
+}
+
+type ListMembersResponse struct {
+	Members []Member `json:"members"`
+}
+
+type ListAdminEventsResponse struct {
+	Events []AdminEvent `json:"events"`
+}
+
+type DeepHealthResponse struct {
+	Status          string                 `json:"status"`
+	Version         string                 `json:"version"`
+	ProtocolVersion string                 `json:"protocol_version"`
+	Capabilities    map[string]string      `json:"capabilities"`
+	Timestamp       int64                  `json:"timestamp"`
+	Dependencies    DeepHealthDependencies `json:"dependencies"`
+}

utils.go

@@ -8,7 +8,7 @@ import (
 	"time"
 )
 
-// base64urlEncode encodes bytes to base64url without padding (RFC 4648 section 5).
+// base64urlEncode encodes bytes as unpadded base64url.
 func base64urlEncode(data []byte) string {
 	return base64.RawURLEncoding.EncodeToString(data)
 }
@@ -18,7 +18,7 @@ func base64urlDecode(s string) ([]byte, error) {
 	return base64.RawURLEncoding.DecodeString(s)
 }
 
-// generateNonce generates a 16-byte cryptographically random nonce, base64url encoded.
+// generateNonce returns 16 random bytes as base64url.
 func generateNonce() (string, error) {
 	b := make([]byte, 16)
 	if _, err := io.ReadFull(rand.Reader, b); err != nil {
@@ -34,19 +34,15 @@ func generateUUIDv7() (string, error) {
 
 	var uuid [16]byte
 
-	// Timestamp: 48 bits in big-endian
 	binary.BigEndian.PutUint16(uuid[0:2], uint16(ms>>32))
 	binary.BigEndian.PutUint16(uuid[2:4], uint16(ms>>16))
 	binary.BigEndian.PutUint16(uuid[4:6], uint16(ms))
 
-	// Fill the rest with random data
 	if _, err := io.ReadFull(rand.Reader, uuid[6:]); err != nil {
 		return "", err
 	}
 
-	// Set version 7 (bits 48-51)
 	uuid[6] = (uuid[6] & 0x0F) | 0x70
-	// Set variant 10 (bits 64-65)
 	uuid[8] = (uuid[8] & 0x3F) | 0x80
 
 	return formatUUID(uuid), nil