signed.go

package randomorg

import (
	"context"
	"encoding/json"
	"time"
)

// Signed commands
// see https://api.random.org/json-rpc/4/signed

// License describes the terms under which the random values in a
// SignedResult may be used, as selected by the owner of the API key that
// generated them.
type License struct {
	Type    string  `json:"type"`
	Text    string  `json:"text"`
	InfoURL *string `json:"infoUrl"`
}

// LicenseData carries information required by certain license types (e.g.
// Flexible Gambling), specifying the Maximum Payout Value (MPV) for the
// game round or lottery draw whose outcome the random values decide.
type LicenseData struct {
	MaxPayoutValue MaxPayoutValue `json:"maxPayoutValue"`
}

// MaxPayoutValue is an amount in a RANDOM.ORG-supported currency (USD, EUR,
// GBP, CAD, AUD, BTC, ETH), identified by an ISO 4217-style currency code.
type MaxPayoutValue struct {
	Currency string  `json:"currency"`
	Amount   float64 `json:"amount"`
}

// TicketData identifies the ticket chain position consumed by a signed
// generate call. It is present in a SignedResult only when the request
// specified a TicketID.
type TicketData struct {
	TicketID         string  `json:"ticketId"`
	PreviousTicketID *string `json:"previousTicketId"`
	NextTicketID     *string `json:"nextTicketId"`
}

// SignedResult is the response from a Signed API generate method or
// GetResult: the random values plus everything needed to prove they were
// generated by RANDOM.ORG.
type SignedResult[T any] struct {
	Method         string
	HashedAPIKey   string
	Data           []T
	License        License
	LicenseData    json.RawMessage
	UserData       json.RawMessage
	TicketData     *TicketData
	CompletionTime time.Time
	SerialNumber   int

	// Random is the raw, unmodified "random" object exactly as returned by
	// RANDOM.ORG. Pass it together with Signature to VerifySignature —
	// re-encoding the typed fields above is not guaranteed to reproduce the
	// exact bytes RANDOM.ORG signed.
	Random    json.RawMessage
	Signature string

	Cost          float64
	BitsUsed      int
	BitsLeft      int
	RequestsLeft  int
	AdvisoryDelay int
}

// signedResultEnvelope is the JSON-RPC result payload of every Signed API
// generate method, and of getResult.
type signedResultEnvelope struct {
	Random        json.RawMessage `json:"random"`
	Signature     string          `json:"signature"`
	Cost          float64         `json:"cost"`
	BitsUsed      int             `json:"bitsUsed"`
	BitsLeft      int             `json:"bitsLeft"`
	RequestsLeft  int             `json:"requestsLeft"`
	AdvisoryDelay int             `json:"advisoryDelay"`
}

// signedRandomEnvelope is the shape of the "random" object nested in
// signedResultEnvelope. It is method-agnostic: fields that only exist for
// some methods (e.g. min/max, characters) are decoded separately by callers
// that need them, since SignedResult only surfaces the fields common to
// every Signed API method.
type signedRandomEnvelope[T any] struct {
	Method         string          `json:"method"`
	HashedAPIKey   string          `json:"hashedApiKey"`
	Data           []T             `json:"data"`
	License        License         `json:"license"`
	LicenseData    json.RawMessage `json:"licenseData"`
	UserData       json.RawMessage `json:"userData"`
	TicketData     *TicketData     `json:"ticketData"`
	CompletionTime string          `json:"completionTime"`
	SerialNumber   int             `json:"serialNumber"`
}

// decodeSignedResult unpacks a signedResultEnvelope's raw "random" object
// into a typed SignedResult[T]. It is shared by every GenerateSigned*
// method, GetResult, and DecodeTicketResult.
func decodeSignedResult[T any](env signedResultEnvelope) (SignedResult[T], error) {
	if env.Random == nil {
		return SignedResult[T]{}, ErrJSONFormat
	}

	var randomEnv signedRandomEnvelope[T]
	if err := json.Unmarshal(env.Random, &randomEnv); err != nil {
		return SignedResult[T]{}, err
	}
	if randomEnv.Data == nil {
		return SignedResult[T]{}, ErrJSONFormat
	}

	completionTime, err := parseAPITime(randomEnv.CompletionTime)
	if err != nil {
		return SignedResult[T]{}, err
	}

	return SignedResult[T]{
		Method:         randomEnv.Method,
		HashedAPIKey:   randomEnv.HashedAPIKey,
		Data:           randomEnv.Data,
		License:        randomEnv.License,
		LicenseData:    randomEnv.LicenseData,
		UserData:       randomEnv.UserData,
		TicketData:     randomEnv.TicketData,
		CompletionTime: completionTime,
		SerialNumber:   randomEnv.SerialNumber,
		Random:         env.Random,
		Signature:      env.Signature,
		Cost:           env.Cost,
		BitsUsed:       env.BitsUsed,
		BitsLeft:       env.BitsLeft,
		RequestsLeft:   env.RequestsLeft,
		AdvisoryDelay:  env.AdvisoryDelay,
	}, nil
}

// signedGenerate invokes method, decodes its signed result into a
// SignedResult[T], and merges the response's bitsLeft/requestsLeft into the
// client's usage cache, mirroring generate's behavior for the Basic API.
func signedGenerate[T any](ctx context.Context, r *Random, method string, params any) (SignedResult[T], error) {
	env, err := invokeRequest[signedResultEnvelope](ctx, r, method, params)
	if err != nil {
		return SignedResult[T]{}, err
	}

	result, err := decodeSignedResult[T](env)
	if err != nil {
		return SignedResult[T]{}, err
	}

	bitsLeft, requestsLeft := env.BitsLeft, env.RequestsLeft
	r.mergeUsage(usageFields{BitsLeft: &bitsLeft, RequestsLeft: &requestsLeft})

	return result, nil
}

// SignedCommonOptions holds the optional parameters shared by every
// GenerateSigned* method.
type SignedCommonOptions struct {
	// PregeneratedRandomization selects historical randomness instead of
	// fresh, on-the-fly randomness. nil (the default) uses fresh randomness.
	PregeneratedRandomization *PregeneratedRandomization
	// LicenseData carries data required by some license types (e.g. the
	// Flexible Gambling license's maximum payout value); required for such
	// license types. nil (the default) omits it.
	LicenseData *LicenseData
	// UserData is included, unmodified, in the signed response alongside
	// the random data. Its JSON-encoded form must not exceed 1,000
	// characters. nil (the default) omits it.
	UserData any
	// TicketID, if set, consumes a ticket obtained from CreateTickets:
	// RANDOM.ORG records that the ticket was used to generate these values.
	// Each ticket can only be used once.
	TicketID string
}

// validateSignedCommonOptions validates the fields of SignedCommonOptions
// that can be checked client-side.
func validateSignedCommonOptions(o SignedCommonOptions) error {
	if err := validatePregeneratedRandomization(o.PregeneratedRandomization); err != nil {
		return err
	}
	if o.UserData != nil {
		encoded, err := json.Marshal(o.UserData)
		if err != nil {
			return err
		}
		if len(encoded) > 1_000 {
			return ErrParamRange
		}
	}
	return nil
}

// GenerateSignedIntegersOptions holds optional parameters for
// GenerateSignedIntegers and GenerateSignedIntegersWithBase.
type GenerateSignedIntegersOptions struct {
	// Replacement specifies whether the numbers are picked with
	// replacement. nil (the default) behaves like true.
	Replacement *bool
	SignedCommonOptions
}

type generateSignedIntegersParams struct {
	baseParams
	N                         int                        `json:"n"`
	Min                       int64                      `json:"min"`
	Max                       int64                      `json:"max"`
	Replacement               *bool                      `json:"replacement,omitempty"`
	Base                      int                        `json:"base,omitempty"`
	PregeneratedRandomization *PregeneratedRandomization `json:"pregeneratedRandomization,omitempty"`
	LicenseData               *LicenseData               `json:"licenseData,omitempty"`
	UserData                  any                        `json:"userData,omitempty"`
	TicketID                  string                     `json:"ticketId,omitempty"`
}

// GenerateSignedIntegers generates n number of digitally signed random
// integers in the range from min to max. Unlike GenerateIntegers, the
// result includes a Signature that can be used to prove the values were
// generated by RANDOM.ORG; see VerifySignature.
func (r *Random) GenerateSignedIntegers(ctx context.Context, n int, min, max int64, opts ...GenerateSignedIntegersOptions) (SignedResult[int64], error) {
	if n < 1 || n > 10_000 {
		return SignedResult[int64]{}, ErrParamRange
	}
	if min < -1_000_000_000 || min > 1_000_000_000 || max < -1_000_000_000 || max > 1_000_000_000 {
		return SignedResult[int64]{}, ErrParamRange
	}

	o := resolveOptions(opts)
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[int64]{}, err
	}

	params := generateSignedIntegersParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		Min:                       min,
		Max:                       max,
		Replacement:               o.Replacement,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[int64](ctx, r, "generateSignedIntegers", params)
}

// GenerateSignedIntegersWithBase is GenerateSignedIntegers with the numbers
// displayed (and signed) in a non-decimal base: 2, 8 or 16. Because the
// server pads and formats the values as strings in these bases, the result
// carries them as strings rather than int64s.
func (r *Random) GenerateSignedIntegersWithBase(ctx context.Context, n int, min, max int64, base int, opts ...GenerateSignedIntegersOptions) (SignedResult[string], error) {
	if n < 1 || n > 10_000 {
		return SignedResult[string]{}, ErrParamRange
	}
	if min < -1_000_000_000 || min > 1_000_000_000 || max < -1_000_000_000 || max > 1_000_000_000 {
		return SignedResult[string]{}, ErrParamRange
	}
	if base != 2 && base != 8 && base != 16 {
		return SignedResult[string]{}, ErrParamRange
	}

	o := resolveOptions(opts)
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[string]{}, err
	}

	params := generateSignedIntegersParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		Min:                       min,
		Max:                       max,
		Replacement:               o.Replacement,
		Base:                      base,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[string](ctx, r, "generateSignedIntegers", params)
}

// GenerateSignedIntegerSequencesOptions holds optional parameters for
// GenerateSignedIntegerSequences and GenerateSignedIntegerSequencesWithBase.
type GenerateSignedIntegerSequencesOptions struct {
	// Replacement specifies, per sequence, whether its numbers are picked
	// with replacement. If non-nil, it must have exactly n elements. nil
	// (the default) behaves as if every sequence used replacement.
	Replacement []bool
	SignedCommonOptions
}

type generateSignedIntegerSequencesParams struct {
	baseParams
	N                         int                        `json:"n"`
	Length                    []int                      `json:"length"`
	Min                       []int64                    `json:"min"`
	Max                       []int64                    `json:"max"`
	Replacement               []bool                     `json:"replacement,omitempty"`
	Base                      []int                      `json:"base,omitempty"`
	PregeneratedRandomization *PregeneratedRandomization `json:"pregeneratedRandomization,omitempty"`
	LicenseData               *LicenseData               `json:"licenseData,omitempty"`
	UserData                  any                        `json:"userData,omitempty"`
	TicketID                  string                     `json:"ticketId,omitempty"`
}

// GenerateSignedIntegerSequences is the Signed API counterpart of
// GenerateIntegerSequences: it generates n digitally signed sequences,
// where sequence i has length[i] elements drawn from [min[i], max[i]].
func (r *Random) GenerateSignedIntegerSequences(ctx context.Context, n int, length []int, min, max []int64, opts ...GenerateSignedIntegerSequencesOptions) (SignedResult[[]int64], error) {
	if err := validateSequenceParams(n, length, min, max); err != nil {
		return SignedResult[[]int64]{}, err
	}

	o := resolveOptions(opts)
	if o.Replacement != nil && len(o.Replacement) != n {
		return SignedResult[[]int64]{}, ErrParamRange
	}
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[[]int64]{}, err
	}

	params := generateSignedIntegerSequencesParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		Length:                    length,
		Min:                       min,
		Max:                       max,
		Replacement:               o.Replacement,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[[]int64](ctx, r, "generateSignedIntegerSequences", params)
}

// GenerateSignedIntegerSequencesWithBase is GenerateSignedIntegerSequences
// with each sequence displayed (and signed) in a non-decimal base: base
// must have exactly n elements, each 2, 8 or 16.
func (r *Random) GenerateSignedIntegerSequencesWithBase(ctx context.Context, n int, length []int, min, max []int64, base []int, opts ...GenerateSignedIntegerSequencesOptions) (SignedResult[[]string], error) {
	if err := validateSequenceParams(n, length, min, max); err != nil {
		return SignedResult[[]string]{}, err
	}
	if len(base) != n {
		return SignedResult[[]string]{}, ErrParamRange
	}
	for _, b := range base {
		if b != 2 && b != 8 && b != 16 {
			return SignedResult[[]string]{}, ErrParamRange
		}
	}

	o := resolveOptions(opts)
	if o.Replacement != nil && len(o.Replacement) != n {
		return SignedResult[[]string]{}, ErrParamRange
	}
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[[]string]{}, err
	}

	params := generateSignedIntegerSequencesParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		Length:                    length,
		Min:                       min,
		Max:                       max,
		Replacement:               o.Replacement,
		Base:                      base,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[[]string](ctx, r, "generateSignedIntegerSequences", params)
}

// GenerateSignedDecimalFractionsOptions holds optional parameters for GenerateSignedDecimalFractions.
type GenerateSignedDecimalFractionsOptions struct {
	// Replacement specifies whether the numbers are picked with
	// replacement. nil (the default) behaves like true.
	Replacement *bool
	SignedCommonOptions
}

type generateSignedDecimalFractionsParams struct {
	baseParams
	N                         int                        `json:"n"`
	DecimalPlaces             int                        `json:"decimalPlaces"`
	Replacement               *bool                      `json:"replacement,omitempty"`
	PregeneratedRandomization *PregeneratedRandomization `json:"pregeneratedRandomization,omitempty"`
	LicenseData               *LicenseData               `json:"licenseData,omitempty"`
	UserData                  any                        `json:"userData,omitempty"`
	TicketID                  string                     `json:"ticketId,omitempty"`
}

// GenerateSignedDecimalFractions generates n digitally signed decimal
// fractions with decimalPlaces number of decimal places.
func (r *Random) GenerateSignedDecimalFractions(ctx context.Context, n, decimalPlaces int, opts ...GenerateSignedDecimalFractionsOptions) (SignedResult[float64], error) {
	if n < 1 || n > 10_000 {
		return SignedResult[float64]{}, ErrParamRange
	}
	if decimalPlaces < 1 || decimalPlaces > 14 {
		return SignedResult[float64]{}, ErrParamRange
	}

	o := resolveOptions(opts)
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[float64]{}, err
	}

	params := generateSignedDecimalFractionsParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		DecimalPlaces:             decimalPlaces,
		Replacement:               o.Replacement,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[float64](ctx, r, "generateSignedDecimalFractions", params)
}

// GenerateSignedGaussiansOptions holds optional parameters for GenerateSignedGaussians.
type GenerateSignedGaussiansOptions struct {
	SignedCommonOptions
}

type generateSignedGaussiansParams struct {
	baseParams
	N                         int                        `json:"n"`
	Mean                      float64                    `json:"mean"`
	StandardDeviation         float64                    `json:"standardDeviation"`
	SignificantDigits         int                        `json:"significantDigits"`
	PregeneratedRandomization *PregeneratedRandomization `json:"pregeneratedRandomization,omitempty"`
	LicenseData               *LicenseData               `json:"licenseData,omitempty"`
	UserData                  any                        `json:"userData,omitempty"`
	TicketID                  string                     `json:"ticketId,omitempty"`
}

// GenerateSignedGaussians generates n digitally signed true random numbers
// from a Gaussian distribution.
func (r *Random) GenerateSignedGaussians(ctx context.Context, n int, mean, standardDeviation float64, significantDigits int, opts ...GenerateSignedGaussiansOptions) (SignedResult[float64], error) {
	if n < 1 || n > 10_000 {
		return SignedResult[float64]{}, ErrParamRange
	}
	if mean < -1_000_000 || mean > 1_000_000 {
		return SignedResult[float64]{}, ErrParamRange
	}
	if standardDeviation < -1_000_000 || standardDeviation > 1_000_000 {
		return SignedResult[float64]{}, ErrParamRange
	}
	if significantDigits < 2 || significantDigits > 14 {
		return SignedResult[float64]{}, ErrParamRange
	}

	o := resolveOptions(opts)
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[float64]{}, err
	}

	params := generateSignedGaussiansParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		Mean:                      mean,
		StandardDeviation:         standardDeviation,
		SignificantDigits:         significantDigits,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[float64](ctx, r, "generateSignedGaussians", params)
}

// GenerateSignedStringsOptions holds optional parameters for GenerateSignedStrings.
type GenerateSignedStringsOptions struct {
	// Replacement specifies whether the strings are picked with
	// replacement. nil (the default) behaves like true.
	Replacement *bool
	SignedCommonOptions
}

type generateSignedStringsParams struct {
	baseParams
	N                         int                        `json:"n"`
	Length                    int                        `json:"length"`
	Characters                string                     `json:"characters"`
	Replacement               *bool                      `json:"replacement,omitempty"`
	PregeneratedRandomization *PregeneratedRandomization `json:"pregeneratedRandomization,omitempty"`
	LicenseData               *LicenseData               `json:"licenseData,omitempty"`
	UserData                  any                        `json:"userData,omitempty"`
	TicketID                  string                     `json:"ticketId,omitempty"`
}

// GenerateSignedStrings generates n digitally signed random strings with
// the given length composed from the characters.
func (r *Random) GenerateSignedStrings(ctx context.Context, n, length int, characters string, opts ...GenerateSignedStringsOptions) (SignedResult[string], error) {
	if n < 1 || n > 10_000 {
		return SignedResult[string]{}, ErrParamRange
	}
	if length < 1 || length > 32 {
		return SignedResult[string]{}, ErrParamRange
	}
	if len(characters) < 1 || len(characters) > 128 {
		return SignedResult[string]{}, ErrParamRange
	}

	o := resolveOptions(opts)
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[string]{}, err
	}

	params := generateSignedStringsParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		Length:                    length,
		Characters:                characters,
		Replacement:               o.Replacement,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[string](ctx, r, "generateSignedStrings", params)
}

// GenerateSignedUUIDsOptions holds optional parameters for GenerateSignedUUIDs.
type GenerateSignedUUIDsOptions struct {
	SignedCommonOptions
}

type generateSignedUUIDsParams struct {
	baseParams
	N                         int                        `json:"n"`
	PregeneratedRandomization *PregeneratedRandomization `json:"pregeneratedRandomization,omitempty"`
	LicenseData               *LicenseData               `json:"licenseData,omitempty"`
	UserData                  any                        `json:"userData,omitempty"`
	TicketID                  string                     `json:"ticketId,omitempty"`
}

// GenerateSignedUUIDs generates n digitally signed random version 4 UUIDs
// (see section 4.4 of RFC 4122).
func (r *Random) GenerateSignedUUIDs(ctx context.Context, n int, opts ...GenerateSignedUUIDsOptions) (SignedResult[string], error) {
	if n < 1 || n > 1_000 {
		return SignedResult[string]{}, ErrParamRange
	}

	o := resolveOptions(opts)
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[string]{}, err
	}

	params := generateSignedUUIDsParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[string](ctx, r, "generateSignedUUIDs", params)
}

// GenerateSignedBlobsOptions holds optional parameters for GenerateSignedBlobs.
type GenerateSignedBlobsOptions struct {
	// Format specifies the encoding used for the returned blobs:
	// BlobFormatBase64 (the default) or BlobFormatHex.
	Format string
	SignedCommonOptions
}

type generateSignedBlobsParams struct {
	baseParams
	N                         int                        `json:"n"`
	Size                      int                        `json:"size"`
	Format                    string                     `json:"format,omitempty"`
	PregeneratedRandomization *PregeneratedRandomization `json:"pregeneratedRandomization,omitempty"`
	LicenseData               *LicenseData               `json:"licenseData,omitempty"`
	UserData                  any                        `json:"userData,omitempty"`
	TicketID                  string                     `json:"ticketId,omitempty"`
}

// GenerateSignedBlobs generates n digitally signed random blobs of size (in
// bits, must be divisible by 8). As with GenerateBlobs, n*size must not
// exceed 1,048,576 bits.
func (r *Random) GenerateSignedBlobs(ctx context.Context, n, size int, opts ...GenerateSignedBlobsOptions) (SignedResult[string], error) {
	if n < 1 || n > 100 {
		return SignedResult[string]{}, ErrParamRange
	}
	if size < 1 || size > 1_048_576 || size%8 != 0 {
		return SignedResult[string]{}, ErrParamRange
	}
	if n*size > 1_048_576 {
		return SignedResult[string]{}, ErrParamRange
	}

	o := resolveOptions(opts)
	if o.Format != "" && o.Format != BlobFormatBase64 && o.Format != BlobFormatHex {
		return SignedResult[string]{}, ErrParamRange
	}
	if err := validateSignedCommonOptions(o.SignedCommonOptions); err != nil {
		return SignedResult[string]{}, err
	}

	params := generateSignedBlobsParams{
		baseParams:                baseParams{APIKey: r.apiKey},
		N:                         n,
		Size:                      size,
		Format:                    o.Format,
		PregeneratedRandomization: o.PregeneratedRandomization,
		LicenseData:               o.LicenseData,
		UserData:                  o.UserData,
		TicketID:                  o.TicketID,
	}

	return signedGenerate[string](ctx, r, "generateSignedBlobs", params)
}

type getResultParams struct {
	baseParams
	SerialNumber int `json:"serialNumber"`
}

// GetResult retrieves a previously generated Signed API result by its
// SerialNumber (as returned in SignedResult.SerialNumber). RANDOM.ORG
// stores signed results for a minimum of 24 hours so they can be retrieved
// again if, for example, the original response was lost to a network
// failure. It is a package-level function rather than a method because Go
// does not allow methods to introduce their own type parameters; T must
// match the data type originally generated (e.g. int64 for
// generateSignedIntegers, string for generateSignedUUIDs/Strings/Blobs,
// []int64 for generateSignedIntegerSequences, float64 for
// generateSignedDecimalFractions/Gaussians).
func GetResult[T any](ctx context.Context, r *Random, serialNumber int) (SignedResult[T], error) {
	params := getResultParams{
		baseParams:   baseParams{APIKey: r.apiKey},
		SerialNumber: serialNumber,
	}

	env, err := invokeRequest[signedResultEnvelope](ctx, r, "getResult", params)
	if err != nil {
		return SignedResult[T]{}, err
	}

	return decodeSignedResult[T](env)
}

type verifySignatureParams struct {
	Random    json.RawMessage `json:"random"`
	Signature string          `json:"signature"`
}

type verifySignatureResult struct {
	Authenticity bool `json:"authenticity"`
}

// VerifySignature verifies that random and signature — typically
// SignedResult.Random and SignedResult.Signature from a prior Signed API
// call — were produced by RANDOM.ORG and have not been tampered with. It
// reports the server's authenticity verdict; a false result with a nil
// error means the signature did not match, not that the call failed.
func (r *Random) VerifySignature(ctx context.Context, random json.RawMessage, signature string) (bool, error) {
	params := verifySignatureParams{
		Random:    random,
		Signature: signature,
	}

	result, err := invokeRequest[verifySignatureResult](ctx, r, "verifySignature", params)
	if err != nil {
		return false, err
	}

	return result.Authenticity, nil
}