yourimageshare

README

yourimageshare-api/go

Official Go SDK for the YourImageShare upload API. Zero third-party dependencies (standard library only), Go 1.18+.

• Get an API key: sign in and open the API tab at yourimageshare.com/my-account.
• Full HTTP reference: yourimageshare.com/about/api or API.md in this repo.
• Same API, same result shapes, in JavaScript/TypeScript, Python, and PHP too.

Install

go get github.com/MediaShareORG/yourimageshare/go

Usage

package main

import (
	"fmt"

	yourimageshare "github.com/MediaShareORG/yourimageshare/go"
)

func main() {
	client, err := yourimageshare.NewClient("YOUR_API_KEY")
	if err != nil {
		panic(err)
	}

	// Upload a file by path
	result, err := client.Upload("photo.jpg", nil)
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Direct) // https://yourimageshare.com/ib/aB3xY9qRz1

	// Upload with auto-delete after 1 hour
	client.Upload("photo.jpg", &yourimageshare.UploadOptions{ExpiresIn: 3600})

	// Upload from any io.Reader (a network stream, an in-memory buffer, ...)
	// client.UploadReader(r, "photo.jpg", nil)

	// List your uploads (paginated, 50 per page)
	listing, err := client.List(1)
	if err != nil {
		panic(err)
	}
	for _, item := range listing.Data {
		fmt.Println(item.ID, item.Direct)
	}

	// Delete an upload
	client.Delete(result.ID)
}

Error handling

Failed requests return a *yourimageshare.APIError (.Status is the HTTP status code, .Message is the server's error text):

result, err := client.Upload("photo.jpg", nil)
if err != nil {
	var apiErr *yourimageshare.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.Status, apiErr.Message)
	}
}

API

yourimageshare.NewClient(apiKey string, opts ...Option) (*Client, error)

WithBaseURL(url string) overrides the API base URL (mainly for testing). WithHTTPClient(*http.Client) overrides the HTTP client, e.g. for a custom timeout or transport. Defaults to a 30s timeout.

client.Upload(filePath string, opts *UploadOptions) (*UploadResult, error)

Streams the file from disk (doesn't buffer the whole thing in memory - uploads can be up to 200MB). opts.ExpiresIn is seconds, 60 to 2,592,000 (30 days); nil or zero means a permanent upload. Returns an UploadResult with ID, Type, Path, Src, Direct, ExpiresAt.

client.UploadReader(r io.Reader, filename string, opts *UploadOptions) (*UploadResult, error)

Same as Upload, but from any io.Reader instead of a file path.

client.List(page int) (*ListResult, error)

Returns a ListResult with Data (a slice of ListedUpload - ID, Type, Title, Path, Src, Direct, ExpiresAt, CreatedAt) and Meta (ListMeta - CurrentPage, LastPage, Total).

client.Delete(id string) error

Returns a *APIError on a 404/401; nil on success.

Rate limits

20 requests/minute and 500/day per key by default (2,000/day per IP as a backstop). Not currently surfaced on the return values from this SDK - read the X-RateLimit-Limit/X-RateLimit-Remaining response headers yourself if you need them, or open an issue to request them on the result types.

License

MIT

Support

yourimageshare.com/contact

Documentation

Overview

Package yourimageshare is the official Go client for the YourImageShare upload API (https://yourimageshare.com/about/api). It mirrors the existing JS (npm), Python (PyPI), and PHP (Packagist) SDKs - same method names, same result shapes, same error type - just idiomatic Go on top (methods return (result, error), not exceptions).

Zero third-party dependencies - only the standard library.

Index

• Constants
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(apiKey string, opts ...Option) (*Client, error)
  • func (c *Client) Delete(id string) error
  • func (c *Client) List(page int) (*ListResult, error)
  • func (c *Client) Upload(filePath string, opts *UploadOptions) (*UploadResult, error)
  • func (c *Client) UploadReader(r io.Reader, filename string, opts *UploadOptions) (*UploadResult, error)
• type ListMeta
• type ListResult
• type ListedUpload
• type Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
• type UploadOptions
• type UploadResult

Constants

const DefaultBaseURL = "https://yourimageshare.com/api"

DefaultBaseURL is used when no WithBaseURL option is given.

Types

type APIError

type APIError struct {
	Status  int
	Message string
}

APIError is returned for any non-2xx response or a `{"type":"error"}` payload - mirrors the JS/Python/PHP SDKs' error type exactly (same Status/Message shape) so error-handling logic reads the same across every official SDK.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client talks to the YourImageShare upload API. Create one with NewClient; a Client is safe for concurrent use by multiple goroutines (it holds no mutable state after construction).

func NewClient

func NewClient(apiKey string, opts ...Option) (*Client, error)

NewClient creates a Client. apiKey is required - get one from the API tab at https://yourimageshare.com/my-account.

func (*Client) Delete

func (c *Client) Delete(id string) error

Delete removes one of your uploads by id. Returns an *APIError on a 404/401.

func (*Client) List

func (c *Client) List(page int) (*ListResult, error)

List returns your uploads, newest first, 50 per page. page < 2 fetches the first page.

func (*Client) Upload

func (c *Client) Upload(filePath string, opts *UploadOptions) (*UploadResult, error)

Upload uploads a local file by path.

func (*Client) UploadReader

func (c *Client) UploadReader(r io.Reader, filename string, opts *UploadOptions) (*UploadResult, error)

UploadReader uploads from any io.Reader (an open file, a network stream, an in-memory buffer) - useful when the data isn't already a file on disk. filename should include a real extension so the server can infer the content type correctly.

type ListMeta

type ListMeta struct {
	CurrentPage int `json:"current_page"`
	LastPage    int `json:"last_page"`
	Total       int `json:"total"`
}

ListMeta carries the pagination info for a List() result.

type ListResult

type ListResult struct {
	Data []ListedUpload `json:"data"`
	Meta ListMeta       `json:"meta"`
}

ListResult is the response shape for List().

type ListedUpload

type ListedUpload struct {
	ID        string  `json:"id"`
	Type      string  `json:"type"`
	Title     *string `json:"title"`
	Path      string  `json:"path"`
	Src       string  `json:"src"`
	Direct    string  `json:"direct"`
	ExpiresAt *string `json:"expires_at"`
	CreatedAt string  `json:"created_at"`
}

ListedUpload is one row of a List() result.

type Option

type Option func(*Client)

Option configures a Client. See WithBaseURL and WithHTTPClient.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the API base URL - mainly for testing against a different environment. Defaults to DefaultBaseURL.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient overrides the *http.Client used for requests, e.g. to set a custom timeout or transport. Defaults to a client with a 30s timeout.

type UploadOptions

type UploadOptions struct {
	// ExpiresIn auto-deletes the upload after this many seconds (60 to
	// 2,592,000 = 30 days). Zero means a permanent upload.
	ExpiresIn int
}

UploadOptions are the optional parameters for Upload/UploadReader.

type UploadResult

type UploadResult struct {
	ID        string  `json:"id"`
	Type      string  `json:"type"`
	Path      string  `json:"path"`
	Src       string  `json:"src"`
	Direct    string  `json:"direct"`
	ExpiresAt *string `json:"expires_at"`
}

UploadResult is the response shape for a successful upload - same fields as the JS/Python/PHP SDKs' UploadResult.