Add rate limit, readme, response helper

Author: lcd1232

README.md

@@ -0,0 +1,125 @@
+# Temp Mail Go Client
+[![Go Reference](https://pkg.go.dev/badge/github.com/temp-mail-io/temp-mail-go.svg)](https://pkg.go.dev/github.com/temp-mail-io/temp-mail-go)
+[![Go](https://github.com/temp-mail-io/temp-mail-go/actions/workflows/test.yml/badge.svg)](https://github.com/temp-mail-io/temp-mail-go/actions)
+
+The **official Go Client** for [Temp Mail](https://temp-mail.io). This library provides developers a straightforward way to create and manage temporary email addresses, retrieve and delete messages, all via the Temp Mail API.
+
+## Table of Contents
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage Examples](#usage-examples)
+    - [Listing Domains](#listing-domains)
+    - [Getting Rate Limits](#getting-rate-limits)
+    - [Creating Temporary Emails](#creating-temporary-emails)
+    - [Fetching and Deleting Messages](#fetching-and-deleting-messages)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
+
+## Features
+- **Create** temporary email addresses with optional domain specifications
+- **Get** current rate limits after API request
+- **Delete** a temporary email along with all its messages
+- **Retrieve** all messages for a specified email
+- **Get** a specific message or download its attachment
+
+## Installation
+To install this Go package, run:
+```bash
+go get github.com/temp-mail-io/temp-mail-go
+```
+
+## Quick Start
+Below is a simple example to get started:
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	tempmail "github.com/temp-mail-io/temp-mail-go"
+)
+
+func main() {
+	// Replace with your real API key
+	client := tempmail.NewClient("YOUR_API_KEY", nil)
+
+	domains, _, err := client.ListDomains(context.Background())
+	if err != nil {
+		log.Fatalf("Error listing domains: %v", err)
+	}
+
+	fmt.Println("Available domains:", domains)
+}
+```
+
+## Usage Examples
+### Listing Domains
+```go
+domains, _, err := client.ListDomains(context.Background())
+if err != nil {
+    // handle error
+}
+for _, d := range domains.Domains {
+    fmt.Printf("Domain: %s, Type: %s\n", d.Name, d.Type)
+}
+```
+
+### Getting Rate Limits
+```go
+rate, _, err := client.RateLimit(context.Background())
+if err != nil {
+    // handle error
+}
+fmt.Printf("limit: %d, used: %d, remaining: %d, reset: %s\n", resp.Limit, resp.Used, resp.Remaining, resp.Reset)
+// Output: limit: 1000, used: 0, remaining: 1000, reset: 2025-02-01 23:59:59 +0000 +00
+```
+
+### Creating Temporary Emails
+```go
+email, _, err := client.CreateEmail(context.Background(), tempmail.CreateEmailOptions{
+	Domain: "example.com",
+})
+if err != nil {
+// handle error
+}
+fmt.Printf("Created temporary email: %s (TTL: %d seconds)\n", email.Email, email.TTL)
+```
+
+### Fetching and Deleting Messages
+```go
+messages, _, err := client.GetEmailMessages(context.Background(), "[email protected]")
+if err != nil {
+    // handle error
+}
+fmt.Printf("Fetched %d messages.\n", len(messages))
+
+// Deleting a specific message
+_, err = client.DeleteMessageV1(context.Background(), messages[0].ID)
+if err != nil {
+    // handle error
+}
+```
+
+## Testing
+We use the Go testing framework with both unit tests and optional integration tests.
+
+Run tests locally:
+```bash
+go test ./... -v
+```
+
+In CI, the tests are automatically executed via [GitHub Actions](https://github.com/temp-mail-io/temp-mail-go/actions).
+
+## Contributing
+We welcome and appreciate contributions! Please see our CONTRIBUTING.md for guidelines on how to open issues, submit pull requests, and follow our coding standards.
+
+## License
+This project is licensed under the MIT License.
+
+## Support
+If you encounter any issues, please open [an issue](https://github.com/temp-mail-io/temp-mail-go/issues) on GitHub. We are happy to help you!

client.go

@@ -19,7 +19,17 @@ type Client struct {
 	apiKey string
 }
 
-const baseURL = "https://api.temp-mail.io"
+const (
+	baseURL = "https://api.temp-mail.io"
+
+	headerAPIKey        = "X-API-Key"
+	headerRateLimit     = "X-Ratelimit-Limit"
+	headerRateRemaining = "X-Ratelimit-Remaining"
+	headerRateUsed      = "X-Ratelimit-Used"
+	headerRateReset     = "X-Ratelimit-Reset"
+
+	userAgent = "temp-mail-go/v1.0.0"
+)
 
 // NewClient creates ready to use Client.
 func NewClient(apiKey string, client *http.Client) *Client {
@@ -38,31 +48,32 @@ func (c *Client) newRequest(ctx context.Context, method, path string, body io.Re
 	if err != nil {
 		return nil, err
 	}
-	req.Header.Set("X-API-Key", c.apiKey)
+	req.Header.Set(headerAPIKey, c.apiKey)
+	req.Header.Set("User-Agent", userAgent)
 	return req, nil
 }
 
 // do sends an HTTP request and decodes the response.
-func (c *Client) do(req *http.Request, v interface{}) error {
-	resp, err := c.doer.Do(req)
+func (c *Client) do(req *http.Request, v interface{}) (*Response, error) {
+	r, err := c.doer.Do(req)
 	if err != nil {
-		return err
+		return nil, err
 	}
-	defer resp.Body.Close()
+	defer r.Body.Close()
 
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+	if r.StatusCode < 200 || r.StatusCode >= 300 {
 		var httpErr HTTPError
-		if err := json.NewDecoder(resp.Body).Decode(&httpErr); err != nil {
-			return err
+		if err := json.NewDecoder(r.Body).Decode(&httpErr); err != nil {
+			return nil, err
 		}
-		return &httpErr
+		return nil, &httpErr
 	}
 
 	if v != nil {
-		if err := json.NewDecoder(resp.Body).Decode(v); err != nil {
-			return err
+		if err := json.NewDecoder(r.Body).Decode(v); err != nil {
+			return nil, err
 		}
 	}
 
-	return nil
+	return newResponse(r), nil
 }

error.go

@@ -3,10 +3,13 @@ package temp_mail_go
 import (
 	"fmt"
 	"io"
+	"net/http"
 )
 
-// HTTPError is the error response that will be returned by the API.
+// HTTPError reports one or more errors caused by an API request.
+// Temp Mail API docs: https://docs.temp-mail.io/docs/getting-started#error-handling
 type HTTPError struct {
+	Response     *http.Response `json:"-"` // HTTP response that caused this error
 	ErrorDetails HTTPErrorError `json:"error"`
 	Meta         HTTPErrorMeta  `json:"meta"`
 }
@@ -26,11 +29,11 @@ type HTTPErrorMeta struct {
 }
 
 func (h *HTTPError) Error() string {
-	return fmt.Sprintf("error: %s, code: %s, detail: %s", h.ErrorDetails.Type, h.ErrorDetails.Code, h.ErrorDetails.Detail)
+	return fmt.Sprintf("status %d, error: %s, code: %s, detail: %s", h.Response.StatusCode, h.ErrorDetails.Type, h.ErrorDetails.Code, h.ErrorDetails.Detail)
 }
 
 func (h *HTTPError) fullError() string {
-	return fmt.Sprintf("error: %s, code: %s, detail: %s, request_id: %s", h.ErrorDetails.Type, h.ErrorDetails.Code, h.ErrorDetails.Detail, h.Meta.RequestID)
+	return fmt.Sprintf("status %d, error: %s, code: %s, detail: %s, request_id: %s", h.Response.StatusCode, h.ErrorDetails.Type, h.ErrorDetails.Code, h.ErrorDetails.Detail, h.Meta.RequestID)
 }
 
 // Format implements fmt.Formatter interface.

example_test.go

@@ -7,10 +7,10 @@ import (
 
 func ExampleClient_RateLimit() {
 	c := NewClient("YOUR_API_KEY", nil)
-	resp, err := c.RateLimit(context.Background())
+	resp, _, err := c.RateLimit(context.Background())
 	if err != nil {
 		panic(err)
 	}
-	fmt.Printf("limit: %d, used: %d, remaining: %d, reset: %d", resp.Limit, resp.Used, resp.Remaining, resp.Reset)
-	// Output: limit: 1000, used: 0, remaining: 1000, reset: 1738367999
+	fmt.Printf("limit: %d, used: %d, remaining: %d, reset: %s\n", resp.Limit, resp.Used, resp.Remaining, resp.Reset)
+	// Output: limit: 1000, used: 0, remaining: 1000, reset: 2025-01-31 23:59:59 +0000 UTC
 }

rate_limit.go

@@ -1,29 +1,50 @@
 package temp_mail_go
 
-import "context"
+import (
+	"context"
+	"time"
+)
 
-type RateLimitResponse struct {
-	// Limit is the maximum number of requests that you can make per period.
-	Limit int64 `json:"limit"`
-	// Used is the number of requests you have made in the current rate limit window.
-	Used int64 `json:"used"`
+// Rate represents the rate limit for the current client.
+type Rate struct {
+	// Limit is the number of requests per hour the client is currently limited to.
+	Limit int
+	// Used is the number of requests the client has made within the current rate limit window.
+	Used int
 	// Remaining is the number of requests remaining in the current rate limit window.
-	Remaining int64 `json:"remaining"`
+	Remaining int
+	// Reset is the time at which the current rate limit will reset.
+	Reset time.Time
+}
+
+type rateLimitResponse struct {
+	// Limit is the number of requests per hour the client is currently limited to.
+	Limit int `json:"limit"`
+	// Used is the number of requests the client has made within the current rate limit window.
+	Used int `json:"used"`
+	// Remaining is the number of requests remaining in the current rate limit window.
+	Remaining int `json:"remaining"`
 	// Reset is the time at which the current rate limit window resets, in UTC epoch seconds.
 	Reset int64 `json:"reset"`
 }
 
 // RateLimit returns the current rate limit for the client.
-func (c *Client) RateLimit(ctx context.Context) (RateLimitResponse, error) {
+func (c *Client) RateLimit(ctx context.Context) (Rate, *Response, error) {
 	req, err := c.newRequest(ctx, "GET", "/v1/rate_limit", nil)
 	if err != nil {
-		return RateLimitResponse{}, err
+		return Rate{}, nil, err
 	}
 
-	var resp RateLimitResponse
-	if err := c.do(req, &resp); err != nil {
-		return RateLimitResponse{}, err
+	var resp rateLimitResponse
+	r, err := c.do(req, &resp)
+	if err != nil {
+		return Rate{}, nil, err
 	}
 
-	return resp, nil
+	return Rate{
+		Limit:     resp.Limit,
+		Used:      resp.Used,
+		Remaining: resp.Remaining,
+		Reset:     time.Unix(resp.Reset, 0),
+	}, r, nil
 }

response.go

@@ -0,0 +1,46 @@
+package temp_mail_go
+
+import (
+	"net/http"
+	"strconv"
+	"time"
+)
+
+// Response is a GitHub API response. This wraps the standard http.Response
+// returned from GitHub and provides convenient access to things like
+// pagination links.
+type Response struct {
+	*http.Response
+
+	// Explicitly specify the Rate type so Rate's String() receiver doesn't
+	// propagate to Response.
+	Rate Rate
+}
+
+// newResponse creates a new Response for the provided http.Response.
+// r must not be nil.
+func newResponse(r *http.Response) *Response {
+	response := &Response{Response: r}
+	response.Rate = parseRate(r)
+	return response
+}
+
+// parseRate parses the rate related headers.
+func parseRate(r *http.Response) Rate {
+	var rate Rate
+	if limit := r.Header.Get(headerRateLimit); limit != "" {
+		rate.Limit, _ = strconv.Atoi(limit)
+	}
+	if remaining := r.Header.Get(headerRateRemaining); remaining != "" {
+		rate.Remaining, _ = strconv.Atoi(remaining)
+	}
+	if used := r.Header.Get(headerRateUsed); used != "" {
+		rate.Used, _ = strconv.Atoi(used)
+	}
+	if reset := r.Header.Get(headerRateReset); reset != "" {
+		if v, _ := strconv.ParseInt(reset, 10, 64); v != 0 {
+			rate.Reset = time.Unix(v, 0)
+		}
+	}
+	return rate
+}