example_test.go

package randomorg_test

import (
	"context"
	"fmt"
	"net/http"

	"github.com/sgade/randomorg/v3"
)

const (
	apiKey = "YOUR API KEY"
)

func Example() {
	// create a new client
	_, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	// call methods on the return value here
}

// Generate one int64 value from 0 to 10.
func ExampleRandom_GenerateIntegers() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	// generates a random value
	value, _ := random.GenerateIntegers(context.Background(), 1, 0, 10)
	fmt.Printf("Random value: %v\n", value)
}

// Generate 5 unique numbers from 1-6, like drawing raffle tickets without
// putting them back.
func ExampleRandom_GenerateIntegers_withoutReplacement() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	values, err := random.GenerateIntegers(context.Background(), 5, 1, 6, randomorg.GenerateIntegersOptions{
		Replacement: randomorg.Bool(false),
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", values)
}

// Generate two integer sequences: 5 unique numbers from 1-69 and 1 number
// from 1-26, as in a lottery draw with a separate bonus ball.
func ExampleRandom_GenerateIntegerSequences() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	sequences, err := random.GenerateIntegerSequences(
		context.Background(),
		2,
		[]int{5, 1},
		[]int64{1, 1},
		[]int64{69, 26},
		randomorg.GenerateIntegerSequencesOptions{Replacement: []bool{false, false}},
	)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Main numbers: %v, bonus number: %v\n", sequences[0], sequences[1])
}

// Generate 10 decimal fractions in [0,1) with 8 decimal places.
func ExampleRandom_GenerateDecimalFractions() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	values, err := random.GenerateDecimalFractions(context.Background(), 10, 8)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", values)
}

// Generate 4 numbers from a Gaussian distribution with mean 0 and standard
// deviation 1, accurate to 8 significant digits.
func ExampleRandom_GenerateGaussians() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	values, err := random.GenerateGaussians(context.Background(), 4, 0, 1, 8)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", values)
}

// Generate 8 random lowercase strings of length 10.
func ExampleRandom_GenerateStrings() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	values, err := random.GenerateStrings(context.Background(), 8, 10, "abcdefghijklmnopqrstuvwxyz")
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", values)
}

// Generate one random version 4 UUID.
func ExampleRandom_GenerateUUIDs() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	values, err := random.GenerateUUIDs(context.Background(), 1)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", values)
}

// Generate one 1024-bit random blob, base64-encoded.
func ExampleRandom_GenerateBlobs() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	values, err := random.GenerateBlobs(context.Background(), 1, 1024)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", values)
}

// GetUsage reports how much of the API key's quota remains.
func ExampleRandom_GetUsage() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	usage, err := random.GetUsage(context.Background())
	if err != nil {
		panic(err)
	}
	fmt.Printf("Bits left: %d\n", usage.BitsLeft)
}

// Generate three digitally signed dice rolls, then verify the returned
// signature to confirm the values are authentic RANDOM.ORG output.
func ExampleRandom_GenerateSignedIntegers() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}

	result, err := random.GenerateSignedIntegers(context.Background(), 3, 1, 6)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Dice roll: %v\n", result.Data)

	authentic, err := random.VerifySignature(context.Background(), result.Random, result.Signature)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Authentic: %v\n", authentic)
}

// The Signed API counterpart of GenerateIntegerSequences: the response also
// carries a signature proving the values were generated by RANDOM.ORG.
func ExampleRandom_GenerateSignedIntegerSequences() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	result, err := random.GenerateSignedIntegerSequences(
		context.Background(),
		2,
		[]int{5, 1},
		[]int64{1, 1},
		[]int64{69, 26},
		randomorg.GenerateSignedIntegerSequencesOptions{Replacement: []bool{false, false}},
	)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Main numbers: %v, bonus number: %v\n", result.Data[0], result.Data[1])
}

func ExampleRandom_GenerateSignedDecimalFractions() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	result, err := random.GenerateSignedDecimalFractions(context.Background(), 10, 8)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", result.Data)
}

func ExampleRandom_GenerateSignedGaussians() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	result, err := random.GenerateSignedGaussians(context.Background(), 4, 0, 1, 8)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", result.Data)
}

func ExampleRandom_GenerateSignedStrings() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	result, err := random.GenerateSignedStrings(context.Background(), 8, 10, "abcdefghijklmnopqrstuvwxyz")
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", result.Data)
}

func ExampleRandom_GenerateSignedUUIDs() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	result, err := random.GenerateSignedUUIDs(context.Background(), 1)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", result.Data)
}

func ExampleRandom_GenerateSignedBlobs() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	result, err := random.GenerateSignedBlobs(context.Background(), 1, 1024)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", result.Data)
}

// GetResult retrieves a previously generated Signed API result by its
// serial number — useful if, say, a network failure prevented the original
// response from being delivered. GetResult is a package-level generic
// function rather than a method because Go methods can't introduce their
// own type parameters.
func ExampleGetResult() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	result, err := randomorg.GetResult[int64](context.Background(), random, 6116)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Random values: %v\n", result.Data)
}

// Create a ticket, spend it on a digitally signed value, and then retrieve
// the full audit trail for that ticket via GetTicket.
func ExampleRandom_CreateTickets() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}

	tickets, err := random.CreateTickets(context.Background(), 1, true)
	if err != nil {
		panic(err)
	}

	result, err := random.GenerateSignedIntegers(context.Background(), 1, 1, 6, randomorg.GenerateSignedIntegersOptions{
		SignedCommonOptions: randomorg.SignedCommonOptions{TicketID: tickets[0].TicketID},
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Value: %v\n", result.Data)

	ticket, err := random.GetTicket(context.Background(), tickets[0].TicketID)
	if err != nil {
		panic(err)
	}
	if ticket.Result != nil {
		decoded, err := randomorg.DecodeTicketResult[int64](ticket.Result)
		if err != nil {
			panic(err)
		}
		fmt.Printf("Audited value: %v\n", decoded.Data)
	}
}

// RevealTickets exposes the random values behind a ticket that was created
// with showResult set to false, after the ticket has been used.
func ExampleRandom_RevealTickets() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	tickets, err := random.CreateTickets(context.Background(), 1, false)
	if err != nil {
		panic(err)
	}
	revealed, err := random.RevealTickets(context.Background(), tickets[0].TicketID)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Revealed %d ticket(s)\n", revealed)
}

// ListTickets enumerates all of an API key's singleton tickets, i.e. those
// that are neither the head nor the tail of a longer chain.
func ExampleRandom_ListTickets() {
	random, err := randomorg.NewRandom(apiKey, &http.Client{})
	if err != nil {
		panic(err)
	}
	tickets, err := random.ListTickets(context.Background(), randomorg.TicketTypeSingleton)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%d singleton ticket(s)\n", len(tickets))
}