client.go

// Copyright 2017-2026 Allow2 Pty Ltd. All rights reserved.
// Use of this source code is governed by the Allow2 API and SDK Licence.

// Package allow2service provides the Allow2 Parental Freedom Service SDK for Go.
//
// This SDK is for web services with user accounts (SaaS, forums, web apps, etc.).
// It handles OAuth2 pairing, permission checking, all 3 request types,
// voice codes, and feedback via the Allow2 Service API.
//
// Each linked service account maps to exactly one Allow2 child -- there is
// no child selector in Service API integrations.
package allow2service

// Option is a functional option for configuring Allow2Client.
type Option func(*Allow2Client)

// WithHTTPClient sets a custom HTTP client.
func WithHTTPClient(c HTTPClient) Option {
	return func(a *Allow2Client) {
		a.http = c
	}
}

// WithAPIHost sets the Allow2 API base URL.
func WithAPIHost(host string) Option {
	return func(a *Allow2Client) {
		a.apiHost = host
	}
}

// WithServiceHost sets the Allow2 Service base URL.
func WithServiceHost(host string) Option {
	return func(a *Allow2Client) {
		a.serviceHost = host
	}
}

// WithCacheTTL sets the permission check cache TTL in seconds.
func WithCacheTTL(ttl int) Option {
	return func(a *Allow2Client) {
		a.cacheTTL = ttl
	}
}

// Allow2Client is the main entry point for the Allow2 Go SDK (Service API).
//
// It wraps OAuth2 authorization, permission checking, request creation,
// feedback, and offline voice code features into a single coherent API.
type Allow2Client struct {
	clientID     string
	clientSecret string
	tokenStorage TokenStorage
	cache        Cache
	http         HTTPClient
	apiHost      string
	serviceHost  string
	cacheTTL     int

	oauth    *oauth2Manager
	checker  *permissionChecker
	requests *requestManager
	feedback *feedbackManager
}

// New creates a new Allow2Client with the given credentials, storage, cache,
// and optional functional options.
func New(clientID, clientSecret string, tokenStorage TokenStorage, cache Cache, opts ...Option) *Allow2Client {
	c := &Allow2Client{
		clientID:     clientID,
		clientSecret: clientSecret,
		tokenStorage: tokenStorage,
		cache:        cache,
		apiHost:      "https://api.allow2.com",
		serviceHost:  "https://service.allow2.com",
		cacheTTL:     60,
	}

	for _, opt := range opts {
		opt(c)
	}

	if c.http == nil {
		c.http = newDefaultHTTPClient()
	}

	c.oauth = &oauth2Manager{
		clientID:     c.clientID,
		clientSecret: c.clientSecret,
		tokenStorage: c.tokenStorage,
		httpClient:   c.http,
		apiHost:      c.apiHost,
	}

	c.checker = &permissionChecker{
		httpClient:  c.http,
		cache:       c.cache,
		serviceHost: c.serviceHost,
		cacheTTL:    c.cacheTTL,
	}

	c.requests = &requestManager{
		httpClient: c.http,
		apiHost:    c.apiHost,
	}

	c.feedback = &feedbackManager{
		httpClient: c.http,
		apiHost:    c.apiHost,
	}

	return c
}

// ──────────────────────────────────────────────────────────
// OAuth2
// ──────────────────────────────────────────────────────────

// GetAuthorizeURL builds the OAuth2 authorization URL to redirect the user to.
// The user will be asked to link their Allow2 child account to your service.
// Pass an empty string for state if not using CSRF protection (not recommended).
func (c *Allow2Client) GetAuthorizeURL(userID, redirectURI, state string) string {
	return c.oauth.GetAuthorizeURL(userID, redirectURI, state)
}

// ExchangeCode exchanges an authorization code for OAuth2 tokens.
// Call this in your redirect_uri callback handler.
func (c *Allow2Client) ExchangeCode(userID, code, redirectURI string) (*OAuthTokens, error) {
	return c.oauth.ExchangeCode(userID, code, redirectURI)
}

// CheckPairingStatus checks whether a user's Allow2 account pairing is still valid.
func (c *Allow2Client) CheckPairingStatus(userID string) bool {
	return c.oauth.CheckPairingStatus(userID)
}

// Unpair removes a user's stored OAuth2 tokens.
func (c *Allow2Client) Unpair(userID string) error {
	return c.oauth.Unpair(userID)
}

// IsPaired checks whether the user has stored OAuth2 tokens (i.e., has been paired).
func (c *Allow2Client) IsPaired(userID string) bool {
	return c.oauth.HasTokens(userID)
}

// ──────────────────────────────────────────────────────────
// Permission Checking
// ──────────────────────────────────────────────────────────

// ActivityInput represents an activity to check permissions for.
type ActivityInput struct {
	ID  int  `json:"id"`
	Log bool `json:"log"`
}

// Check checks permissions for a user's linked Allow2 child account.
// Pass an empty string for timezone to use server default.
func (c *Allow2Client) Check(userID string, activities []ActivityInput, timezone string) (*CheckResult, error) {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return nil, err
	}

	result, err := c.checker.Check(accessToken, userID, activities, timezone)
	if err != nil {
		if isUnpairedError(err) {
			c.handleUnpaired(userID)
		}
		return nil, err
	}

	return result, nil
}

// IsAllowed is a convenience method that checks if all specified activities are currently allowed.
func (c *Allow2Client) IsAllowed(userID string, activityIDs []int) (bool, error) {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return false, err
	}

	result, err := c.checker.IsAllowed(accessToken, userID, activityIDs)
	if err != nil {
		if isUnpairedError(err) {
			c.handleUnpaired(userID)
		}
		return false, err
	}

	return result, nil
}

// ──────────────────────────────────────────────────────────
// Requests (More Time, Day Type Change, Ban Lift)
// ──────────────────────────────────────────────────────────

// RequestMoreTime requests more time for an activity.
func (c *Allow2Client) RequestMoreTime(userID string, activityID, minutes int, message string) (*RequestResult, error) {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return nil, err
	}

	result, err := c.requests.RequestMoreTime(accessToken, userID, activityID, minutes, message)
	if err != nil {
		if isUnpairedError(err) {
			c.handleUnpaired(userID)
		}
		return nil, err
	}

	return result, nil
}

// RequestDayTypeChange requests a day type change (e.g., treat today as a weekend).
func (c *Allow2Client) RequestDayTypeChange(userID string, dayTypeID int, message string) (*RequestResult, error) {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return nil, err
	}

	result, err := c.requests.RequestDayTypeChange(accessToken, userID, dayTypeID, message)
	if err != nil {
		if isUnpairedError(err) {
			c.handleUnpaired(userID)
		}
		return nil, err
	}

	return result, nil
}

// RequestBanLift requests lifting a ban on an activity.
func (c *Allow2Client) RequestBanLift(userID string, activityID int, message string) (*RequestResult, error) {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return nil, err
	}

	result, err := c.requests.RequestBanLift(accessToken, userID, activityID, message)
	if err != nil {
		if isUnpairedError(err) {
			c.handleUnpaired(userID)
		}
		return nil, err
	}

	return result, nil
}

// GetRequestStatus polls the status of a pending request.
// Returns "pending", "approved", or "denied".
func (c *Allow2Client) GetRequestStatus(requestID, statusSecret string) (string, error) {
	return c.requests.GetRequestStatus(requestID, statusSecret)
}

// GetRequestToken obtains a temporary request token from the Allow2 API.
// Used by integrations that manage the request creation flow themselves.
func (c *Allow2Client) GetRequestToken(userID string, nonce string) (map[string]interface{}, error) {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return nil, err
	}
	return c.requests.GetTempToken(accessToken, nonce)
}

// ──────────────────────────────────────────────────────────
// Voice Codes (Offline Approval)
// ──────────────────────────────────────────────────────────

// GenerateVoiceChallenge generates an offline voice code challenge-response pair.
// Pass empty strings for userID and date to use defaults.
func (c *Allow2Client) GenerateVoiceChallenge(secret string, reqType RequestType, activityID, minutes int, userID, date string) (*VoiceCodePair, error) {
	if secret == "" {
		return nil, &Allow2Error{
			Message: "A pairing secret is required for voice code generation. " +
				"This should be stored during the OAuth2 pairing process.",
		}
	}
	return GenerateVoiceChallenge(secret, reqType, activityID, minutes, date)
}

// VerifyVoiceResponse verifies a voice code response entered by the child.
// Pass empty strings for userID and date to use defaults.
func (c *Allow2Client) VerifyVoiceResponse(secret, challenge, response, userID, date string) bool {
	if secret == "" {
		return false
	}
	return VerifyVoiceResponse(secret, challenge, response, date)
}

// ──────────────────────────────────────────────────────────
// Feedback
// ──────────────────────────────────────────────────────────

// SubmitFeedback submits feedback from the user. Returns the discussion ID.
func (c *Allow2Client) SubmitFeedback(userID string, category FeedbackCategory, message string) (string, error) {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return "", err
	}

	result, err := c.feedback.Submit(accessToken, userID, category, message)
	if err != nil {
		if isUnpairedError(err) {
			c.handleUnpaired(userID)
		}
		return "", err
	}

	return result, nil
}

// LoadFeedback loads all feedback discussion threads for the user.
func (c *Allow2Client) LoadFeedback(userID string) ([]interface{}, error) {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return nil, err
	}

	result, err := c.feedback.Load(accessToken, userID)
	if err != nil {
		if isUnpairedError(err) {
			c.handleUnpaired(userID)
		}
		return nil, err
	}

	return result, nil
}

// ReplyToFeedback replies to an existing feedback discussion thread.
func (c *Allow2Client) ReplyToFeedback(userID, discussionID, message string) error {
	accessToken, err := c.getAccessToken(userID)
	if err != nil {
		return err
	}

	err = c.feedback.Reply(accessToken, userID, discussionID, message)
	if err != nil {
		if isUnpairedError(err) {
			c.handleUnpaired(userID)
		}
		return err
	}

	return nil
}

// ──────────────────────────────────────────────────────────
// Internal
// ──────────────────────────────────────────────────────────

// getAccessToken gets a valid access token for the user, auto-refreshing if needed.
func (c *Allow2Client) getAccessToken(userID string) (string, error) {
	return c.oauth.GetAccessToken(userID)
}

// handleUnpaired clears tokens on unpaired error.
func (c *Allow2Client) handleUnpaired(userID string) {
	_ = c.tokenStorage.Delete(userID)
}

// isUnpairedError checks if an error is an UnpairedError.
func isUnpairedError(err error) bool {
	_, ok := err.(*UnpairedError)
	return ok
}