interfaces.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

// HTTPClient is the interface for making HTTP requests.
// Implementations must handle JSON encoding/decoding.
type HTTPClient interface {
	// Post sends a POST request with JSON-encoded body data.
	Post(url string, data map[string]interface{}, headers map[string]string) (*HttpResponse, error)

	// Get sends a GET request.
	Get(url string, headers map[string]string) (*HttpResponse, error)
}

// TokenStorage is the interface for per-user OAuth2 token persistence.
// Implementations store tokens keyed by the application's internal user ID.
// The user ID is an opaque string from the integrating application, not
// an Allow2 user ID.
type TokenStorage interface {
	// Store persists tokens for a user.
	Store(userID string, tokens *OAuthTokens) error

	// Retrieve returns tokens for a user, or nil if none stored.
	Retrieve(userID string) (*OAuthTokens, error)

	// Delete removes tokens for a user (e.g., on unpair).
	Delete(userID string) error

	// Exists checks whether tokens exist for a user.
	Exists(userID string) (bool, error)
}

// Cache is the interface for caching permission check results.
// Simple key-value cache with TTL support. Values are serialized strings.
type Cache interface {
	// Get retrieves a cached value by key. Returns empty string if not found or expired.
	Get(key string) (string, bool)

	// Set stores a value in cache with the given TTL in seconds.
	Set(key string, value string, ttlSeconds int)

	// Delete removes a cached value.
	Delete(key string)
}