seesdk

package module
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 12 Imported by: 0

README

See Go SDK

Official Golang SDK for S.EE URL shortener service. Create, manage, and track short URLs with ease.

Features

  • 🔗 Create short URLs with custom slugs
  • 📝 Create text/paste with syntax highlighting
  • 📂 File upload and sharing (public or private)
  • 📦 Large file uploads up to 5GB (TUS resumable protocol, with instant deduplicated uploads)
  • 🚀 Smart upload that automatically picks the best upload strategy by file size
  • 📜 Link, text, and file history with pagination
  • 🔑 Temporary download URLs for private files
  • 👤 Bio pages with custom links
  • 📱 Dynamic QR codes (PNG/SVG/PDF)
  • 🔒 Password-protected links
  • ⏰ Expiration time support
  • 🏷️ Tag management for organization
  • 🌐 Multiple domain support
  • 📈 View account usage and link visit statistics
  • ✅ API token validation

Installation

go get github.com/sdotee/sdk.go

Quick Start

Initialize the client with your API credentials:

import seesdk "github.com/sdotee/sdk.go"

client := seesdk.NewClient(seesdk.Config{
    BaseURL: "https://api.s.ee",
    APIKey:  "your-api-key-here",
})

Create your first short URL:

resp, err := client.CreateShortURL(seesdk.CreateShortURLRequest{
    TargetURL: "https://www.example.com/very/long/url",
    Domain:    "s.ee",
    Title:     "My Link",
})

fmt.Printf("Short URL: %s\n", resp.Data.ShortURL)

Usage Examples

Domain and Tag Management
// Get available domains
domains, _ := client.GetDomains()
fmt.Println(domains.Data.Domains)

// Get available tags
tags, _ := client.GetTags()
for _, tag := range tags.Data.Tags {
    fmt.Printf("%s (ID: %d)\n", tag.Name, tag.ID)
}
Advanced Short URL Creation

Create a custom branded link with expiration and password protection:

expireAt := time.Now().Add(30 * 24 * time.Hour).Unix()

resp, err := client.CreateShortURL(seesdk.CreateShortURLRequest{
    TargetURL:  "https://www.example.com/campaign",
    Domain:     "s.ee",
    CustomSlug: "summer-sale",
    ExpireAt:   expireAt,
    Password:   "secret123",
    Title:      "Summer Sale Campaign",
    TagIDs:     []int64{1, 2},
})
Statistics
// Get account usage statistics
usage, _ := client.GetUsage()
fmt.Printf("Links created today: %d/%d\n",
    usage.Data.LinkCountDay,
    usage.Data.LinkCountDayLimit)
fmt.Printf("Storage used: %s MB / %s MB\n",
    usage.Data.StorageUsageMB,
    usage.Data.StorageUsageLimitMB)

// Get visit statistics for a short URL
// Period: seesdk.VisitStatPeriodDaily, seesdk.VisitStatPeriodMonthly,
// or seesdk.VisitStatPeriodTotally (empty string defaults to all-time)
stat, _ := client.GetLinkVisitStat("s.ee", "summer-sale", seesdk.VisitStatPeriodTotally)
fmt.Printf("Total visits: %d\n", stat.Data.VisitCount)
Update and Delete
// Update existing short URL
client.UpdateShortURL(seesdk.UpdateShortURLRequest{
    Domain:    "s.ee",
    Slug:      "summer-sale",
    TargetURL: "https://www.example.com/new-campaign",
    Title:     "Updated Campaign",
})

// Delete short URL
client.DeleteShortURL(seesdk.DeleteURLRequest{
    Domain: "s.ee",
    Slug:   "summer-sale",
})
Text Management
// Create a new text/paste
textResp, err := client.CreateText(seesdk.CreateTextRequest{
    Content:    "fmt.Println(\"Hello World\")",
    Domain:     "s.ee",
    Title:      "Go Hello World",
    TextType:   "source_code",
    CustomSlug: "hello-go",
})
fmt.Printf("Text URL: %s\n", textResp.Data.ShortURL)

// Update text
client.UpdateText(seesdk.UpdateTextRequest{
    Domain:  "s.ee",
    Slug:    "hello-go",
    Content: "fmt.Println(\"Hello Updated World\")",
    Title:   "Updated Go Hello World",
})

// Delete text
client.DeleteText(seesdk.DeleteTextRequest{
    Domain: "s.ee",
    Slug:   "hello-go",
})
File Management
// Upload a file
file, _ := os.Open("image.png")
defer file.Close()

uploadResp, err := client.UploadFile(seesdk.UploadFileRequest{
    Filename: "image.png",
    File:     file,
})
fmt.Printf("File URL: %s\n", uploadResp.Data.URL)
fmt.Printf("Delete Key: %s\n", uploadResp.Data.Hash)

// Upload a private file with custom domain and slug
privateResp, err := client.UploadFile(seesdk.UploadFileRequest{
    Filename:   "secret.pdf",
    File:       file,
    IsPrivate:  true,
    Domain:     "s.ee",
    CustomSlug: "my-file",
})

// Get file upload history (paginated, 30 per page)
history, _ := client.GetFileHistory(1)
for _, f := range history.Data {
    fmt.Printf("%s - %s\n", f.Filename, f.URL)
}

// Get available domains for file sharing
fileDomains, _ := client.GetFileDomains()
fmt.Println(fileDomains.Data.Domains)

// Get a temporary download URL for a private file (valid for ~1 hour)
dlResp, _ := client.GetPrivateFileDownloadURL(int64(privateResp.Data.FileID))
fmt.Printf("Download URL: %s (expires at %d)\n", dlResp.Data.URL, dlResp.Data.ExpiresAt)

// Delete file using hash
client.DeleteFile(uploadResp.Data.Hash)
Large File Upload (up to 5GB)

For files larger than the 100MB UploadFile limit, use the TUS-based large file API:

// One-call convenience: creates a session, uploads in 16MB chunks, completes
f, _ := os.Open("video.mp4")
defer f.Close()
info, _ := f.Stat()

resp, err := client.UploadLargeFile(seesdk.CreateLargeFileUploadRequest{
    FileName: "video.mp4",
    FileSize: info.Size(),
    // FileHash: "<sha256>", // optional: enables instant deduplicated upload
    // IsPrivate: 1,         // optional: 0 = public (default), 1 = private
}, f)
fmt.Printf("File URL: %s\n", resp.Data.File.URL)

Or drive the session manually for resumable uploads:

// 1. Create an upload session
createResp, _ := client.CreateLargeFileUpload(seesdk.CreateLargeFileUploadRequest{
    FileName: "video.mp4",
    FileSize: info.Size(),
})
uploadID := createResp.Data.UploadID

// 2. Upload chunks (TUS PATCH); resume with GetLargeFileUploadOffset
offset, _ := client.GetLargeFileUploadOffset(uploadID)
offset, _ = client.UploadLargeFileChunk(uploadID, offset, chunk)

// 3. Check progress at any time
progress, _ := client.GetLargeFileUploadProgress(uploadID)
fmt.Printf("Progress: %.1f%%\n", progress.Data.Progress)

// 4. Complete (or cancel) the session
completeResp, _ := client.CompleteLargeFileUpload(uploadID)
// client.CancelLargeFileUpload(uploadID)
Smart Upload

SmartUploadFile automatically chooses between the regular upload (≤100MB) and the TUS large file upload (up to 5GB) based on the file size:

f, _ := os.Open("any-file.bin")
defer f.Close()

resp, err := client.SmartUploadFile(seesdk.UploadFileRequest{
    Filename: "any-file.bin",
    File:     f,
})
fmt.Printf("File URL: %s\n", resp.Data.URL)

The size is detected via Stat() (e.g. *os.File) or Len() (e.g. *bytes.Reader). When the size cannot be determined, the regular upload is used.

History
// Short link creation history (paginated)
links, _ := client.GetLinkHistory(1)
for _, l := range links.Data {
    fmt.Printf("%s -> %s (%d visits)\n", l.ShortURL, l.TargetURL, l.VisitCount)
}

// Text creation history (paginated)
texts, _ := client.GetTextHistory(1)
for _, tx := range texts.Data {
    fmt.Printf("%s: %s\n", tx.ShortURL, tx.ContentPreview)
}
Bio Pages
// Create a bio page with custom links
bioResp, _ := client.CreateBioPage(seesdk.CreateBioPageRequest{
    Title:       "My Bio",
    Description: "About me",
    MastodonURL: "https://mastodon.social/@me",
    CustomLinks: []seesdk.BioCustomLink{
        {Title: "Blog", URL: "https://blog.example.com"},
    },
})
fmt.Printf("Bio page: %s\n", bioResp.Data.ShortURL)

// Update a bio page
client.UpdateBioPage(seesdk.UpdateBioPageRequest{
    ID:    bioResp.Data.BioPageID,
    Title: "My Updated Bio",
})

// List bio pages (paginated)
bios, _ := client.GetBioPageHistory(1)
fmt.Printf("Total bio pages: %d\n", bios.Data.Total)

// Delete a bio page
client.DeleteBioPage(bioResp.Data.BioPageID)
QR Codes
// Create a dynamic QR code (PNG/SVG/PDF are generated server-side)
qrResp, _ := client.CreateQRCode(seesdk.CreateQRCodeRequest{
    TargetURL: "https://example.com",
    Title:     "My QR Code",
})
fmt.Printf("QR PNG: %s\n", qrResp.Data.PNGURL)

// List QR codes (paginated)
qrcodes, _ := client.GetQRCodeHistory(1)
fmt.Printf("Total QR codes: %d\n", qrcodes.Data.Total)

// Delete a QR code
client.DeleteQRCode(seesdk.DeleteQRCodeRequest{Domain: "s.ee", Slug: qrResp.Data.Slug})
Token Validation
check, _ := client.CheckToken("your-api-key-here")
if check.Data.Valid {
    fmt.Printf("Token valid until %d\n", check.Data.ExpiresAt)
}

API Reference

Client Configuration
Field Type Required Description
BaseURL string Yes API endpoint URL
APIKey string Yes Your authentication token
Timeout time.Duration No Request timeout (default: 30s)
Methods

CreateShortURL(req CreateShortURLRequest) - Create a new short URL

UpdateShortURL(req UpdateShortURLRequest) - Modify an existing short URL

DeleteShortURL(req DeleteURLRequest) - Remove a short URL

CreateText(req CreateTextRequest) - Create a new text entry

UpdateText(req UpdateTextRequest) - Modify an existing text entry

DeleteText(req DeleteTextRequest) - Remove a text entry

UploadFile(req UploadFileRequest) - Upload a file (max 100MB)

SmartUploadFile(req UploadFileRequest) - Upload a file, automatically switching to the TUS large file upload above 100MB

UploadLargeFile(req CreateLargeFileUploadRequest, r io.Reader) - Upload a file up to 5GB (full TUS flow)

CreateLargeFileUpload(req CreateLargeFileUploadRequest) - Create a TUS upload session

UploadLargeFileChunk(uploadID string, offset int64, chunk []byte) - Upload a chunk (TUS PATCH)

GetLargeFileUploadOffset(uploadID string) - Get the current upload offset (TUS HEAD)

GetLargeFileUploadProgress(uploadID string) - Get upload session progress

CompleteLargeFileUpload(uploadID string) - Finalize an upload session

CancelLargeFileUpload(uploadID string) - Cancel an upload session

GetFileHistory(page int) - Get paginated file upload history (30 per page)

GetLinkHistory(page int) - Get paginated short link creation history

GetTextHistory(page int) - Get paginated text creation history

DeleteFile(deleteKey string) - Delete a file using the delete key

GetPrivateFileDownloadURL(fileID int64) - Get a temporary download URL for a private file

GetUsage() - Get account usage statistics

GetLinkVisitStat(domain, slug, period string) - Get visit statistics for a short URL

GetDomains() - List available domains

GetFileDomains() - List available domains for file sharing

GetTextDomains() - List available domains for text sharing

GetTags() - List available tags

CreateBioPage(req CreateBioPageRequest) - Create a bio page

UpdateBioPage(req UpdateBioPageRequest) - Update a bio page

DeleteBioPage(id int64) - Delete a bio page by ID

GetBioPageHistory(page int) - Get paginated bio page list

CreateQRCode(req CreateQRCodeRequest) - Create a dynamic QR code

DeleteQRCode(req DeleteQRCodeRequest) - Delete a QR code

GetQRCodeHistory(page int) - Get paginated QR code list

CheckToken(token string) - Validate an API token

Request Models

CreateShortURLRequest

Field Type Required Description
TargetURL string Yes Destination URL
Domain string Yes Short domain name
CustomSlug string No Custom URL slug
ExpireAt int64 No Unix timestamp (seconds)
Password string No Access password
TagIDs []int64 No Associated tag IDs
Title string No Link description
ExpirationRedirectURL string No Redirect after expiration

UpdateShortURLRequest

Field Type Required
Domain string Yes
Slug string Yes
TargetURL string Yes
Title string No

DeleteURLRequest

Field Type Required
Domain string Yes
Slug string Yes

CreateTextRequest

Field Type Required Description
Content string Yes Text content
Domain string No Short domain name
CustomSlug string No Custom URL slug
TextType string No plain_text, source_code, or markdown
Title string No Text title
Password string No Access password
ExpireAt int64 No Unix timestamp (seconds)
TagIDs []int64 No Associated tag IDs

UpdateTextRequest

Field Type Required
Domain string Yes
Slug string Yes
Content string Yes
Title string No

DeleteTextRequest

Field Type Required
Domain string Yes
Slug string Yes

UploadFileRequest

Field Type Required Description
Filename string Yes Name of the file
File io.Reader Yes File content reader
Domain string No Domain for the short link
CustomSlug string No Custom slug for the file URL
IsPrivate bool No Set to true for private file upload

CreateLargeFileUploadRequest

Field Type Required Description
FileName string Yes Original filename
FileSize int64 Yes File size in bytes (max 5GB)
FileHash string No SHA256 hash for instant upload deduplication
Domain string No Domain for the short link
Alias string No Custom slug for the short link
IsPrivate int No 0 = public (default), 1 = private
Password string No Access password (3-32 chars)
ExpireAt int64 No Unix timestamp for link expiry
Title string No Title for the file
Description string No Description
MimeType string No MIME type hint

CreateBioPageRequest

Field Type Required Description
Title string Yes Bio page title
Description string No Bio page description
Domain string No Domain for the bio page URL
CustomSlug string No Custom URL slug
MastodonURL string No Mastodon profile URL
RSSURL string No RSS feed URL
CustomLinks []BioCustomLink No Custom links (Title, URL, Description)

CreateQRCodeRequest

Field Type Required Description
TargetURL string Yes Destination URL
Title string Yes QR code title
Domain string No Domain for the short link
CustomSlug string No Custom URL slug

Error Handling

All methods return standard Go errors. Always check for errors:

resp, err := client.CreateShortURL(req)
if err != nil {
    log.Printf("Failed: %v", err)
    return
}

Example

See examples/main.go for complete working examples.

cd examples && go run main.go

Contributing

Issues and Pull Requests are welcome!

License

MIT License

Documentation

Index

Constants

View Source 
const (
	VisitStatPeriodDaily   = "daily"   // today
	VisitStatPeriodMonthly = "monthly" // this month
	VisitStatPeriodTotally = "totally" // all-time (default)
)

Visit statistics period values accepted by GetLinkVisitStat.

View Source 
const (
	LargeFileUploadStatusUploading = 1
	LargeFileUploadStatusCompleted = 2
	LargeFileUploadStatusFailed    = 3
	LargeFileUploadStatusCancelled = 4
)

Large file upload session status values reported by GetLargeFileUploadProgress.

View Source 
const DefaultBaseURL = "https://s.ee/api/v1"
View Source 
const DefaultLargeFileChunkSize = 16 * 1024 * 1024

DefaultLargeFileChunkSize is the chunk size used by UploadLargeFile (16MB).

View Source 
const DefaultTimeout = 30 * time.Second
View Source 
const UsageNoLimit = -1

UsageNoLimit represents unlimited usage.

View Source 
const Version = "1.5.0"

Version is the current version of the SDK.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError added in v1.3.1 

type APIError struct {
	Method     string
	Endpoint   string
	StatusCode int
	Message    string
}

APIError describes a non-successful HTTP response from the API.

func (*APIError) Error added in v1.3.1 

func (e *APIError) Error() string
type BioCustomLink struct {
	Description string `json:"description,omitempty"`
	Title       string `json:"title"`
	URL         string `json:"url"`
}

BioCustomLink represents a custom link on a bio page.

type BioPageData added in v1.3.0 

type BioPageData struct {
	CreatedAt   int64           `json:"created_at"`
	CustomLinks []BioCustomLink `json:"custom_links"`
	Description string          `json:"description"`
	Domain      string          `json:"domain"`
	ID          int64           `json:"id"`
	Link        string          `json:"link"` // The complete short URL of the bio page
	MastodonURL string          `json:"mastodon_url"`
	RSSURL      string          `json:"rss_url"`
	Slug        string          `json:"slug"`
	Title       string          `json:"title"`
}

BioPageData represents a bio page entry in the history.

type CancelLargeFileUploadRequest added in v1.3.0 

type CancelLargeFileUploadRequest struct {
	UploadID string `json:"upload_id"`
}

CancelLargeFileUploadRequest represents a request to cancel a large file upload session.

type CancelLargeFileUploadResponse added in v1.3.0 

type CancelLargeFileUploadResponse struct {
	Code    int    `json:"code"`
	Data    any    `json:"data,omitempty"`
	Message string `json:"message"`
}

CancelLargeFileUploadResponse represents the response from cancelling a large file upload.

type CheckTokenRequest added in v1.3.0 

type CheckTokenRequest struct {
	Token string `json:"token"`
}

CheckTokenRequest represents a request to validate an API token.

type CheckTokenResponse added in v1.3.0 

type CheckTokenResponse struct {
	Code int `json:"code"`
	Data struct {
		ExpiresAt int64  `json:"expires_at"` // Token expiration time in Unix timestamp
		Token     string `json:"token"`
		Valid     bool   `json:"valid"`
	} `json:"data"`
	Message string `json:"message"`
}

CheckTokenResponse represents the response from validating an API token.

type Client 

type Client struct {
	BaseURL    string
	APIKey     string
	HTTPClient *http.Client
}

Client represents the SEE SDK client for short URL operations

func NewClient 

func NewClient(config Config) *Client

NewClient creates a new SEE SDK client with the given configuration.

func (*Client) CancelLargeFileUpload added in v1.3.0 

func (c *Client) CancelLargeFileUpload(uploadID string) (*CancelLargeFileUploadResponse, error)

CancelLargeFileUpload cancels an in-progress upload session and removes the temporary data.

func (*Client) CheckToken added in v1.3.0 

func (c *Client) CheckToken(token string) (*CheckTokenResponse, error)

CheckToken checks whether the provided API token is valid and usable. When valid, the response includes the token string and its expiration time.

func (*Client) CompleteLargeFileUpload added in v1.3.0 

func (c *Client) CompleteLargeFileUpload(uploadID string) (*CompleteLargeFileUploadResponse, error)

CompleteLargeFileUpload finalizes an upload session after all chunks have been uploaded. It validates the file, moves it to permanent storage, and returns the file record. This consumes the upload session.

func (*Client) CreateBioPage added in v1.3.0 

func (c *Client) CreateBioPage(req CreateBioPageRequest) (*CreateBioPageResponse, error)

CreateBioPage creates a new bio page with a short URL.

func (*Client) CreateLargeFileUpload added in v1.3.0 

func (c *Client) CreateLargeFileUpload(req CreateLargeFileUploadRequest) (*CreateLargeFileUploadResponse, error)

CreateLargeFileUpload creates a TUS upload session for files up to 5GB. If FileHash is provided and the file already exists on the server, the response has FastUpload set to true and ExistingFile populated, and no data transfer is needed.

func (*Client) CreateQRCode added in v1.3.0 

func (c *Client) CreateQRCode(req CreateQRCodeRequest) (*CreateQRCodeResponse, error)

CreateQRCode creates a dynamic QR code for a given URL. The QR code is generated server-side and available in PNG, SVG, and PDF formats.

func (*Client) CreateShortURL 

func (c *Client) CreateShortURL(req CreateShortURLRequest) (*CreateShortURLResponse, error)

CreateShortURL creates a new short URL with the given parameters.

func (*Client) CreateText 

func (c *Client) CreateText(req CreateTextRequest) (*CreateTextResponse, error)

CreateText creates a new text entry with the given parameters.

func (*Client) DeleteBioPage added in v1.3.0 

func (c *Client) DeleteBioPage(id int64) (*DeleteBioPageResponse, error)

DeleteBioPage permanently deletes a bio page by its numeric ID.

func (*Client) DeleteFile 

func (c *Client) DeleteFile(deleteKey string) (*DeleteFileResponse, error)

DeleteFile deletes an uploaded file using its delete key.

func (*Client) DeleteQRCode added in v1.3.0 

func (c *Client) DeleteQRCode(req DeleteQRCodeRequest) (*DeleteQRCodeResponse, error)

DeleteQRCode permanently deletes a QR code and its associated short link.

func (*Client) DeleteShortURL 

func (c *Client) DeleteShortURL(req DeleteURLRequest) (*DeleteURLResponse, error)

DeleteShortURL deletes an existing short URL.

func (*Client) DeleteText 

func (c *Client) DeleteText(req DeleteTextRequest) (*DeleteTextResponse, error)

DeleteText deletes an existing text entry.

func (*Client) GetBioPageHistory added in v1.3.0 

func (c *Client) GetBioPageHistory(page int) (*GetBioPageHistoryResponse, error)

GetBioPageHistory retrieves a paginated list of bio pages. Page starts at 1. If page is 0 or negative, defaults to page 1.

func (*Client) GetDomains 

func (c *Client) GetDomains() (*DomainsResponse, error)

GetDomains retrieves the list of available domains.

func (*Client) GetFileDomains 

func (c *Client) GetFileDomains() (*DomainsResponse, error)

GetFileDomains retrieves the list of available domains for file sharing.

func (*Client) GetFileHistory added in v1.1.1 

func (c *Client) GetFileHistory(page int) (*GetFileHistoryResponse, error)

GetFileHistory retrieves a paginated list of uploaded files. Returns 30 files per page, sorted by creation time descending. Page starts at 1. If page is 0 or negative, defaults to page 1.

func (*Client) GetLargeFileUploadOffset added in v1.3.0 

func (c *Client) GetLargeFileUploadOffset(uploadID string) (int64, error)

GetLargeFileUploadOffset queries the server for the current upload offset of a session (TUS HEAD request). Use it to resume an interrupted upload.

func (*Client) GetLargeFileUploadProgress added in v1.3.0 

func (c *Client) GetLargeFileUploadProgress(uploadID string) (*GetLargeFileUploadProgressResponse, error)

GetLargeFileUploadProgress returns the current progress of a large file upload session.

func (*Client) GetLinkHistory added in v1.3.0 

func (c *Client) GetLinkHistory(page int) (*GetLinkHistoryResponse, error)

GetLinkHistory retrieves a paginated list of short links created by the account. Page starts at 1. If page is 0 or negative, defaults to page 1.

func (*Client) GetLinkVisitStat added in v1.3.0 

func (c *Client) GetLinkVisitStat(domain, slug, period string) (*GetLinkVisitStatResponse, error)

GetLinkVisitStat retrieves click/visit statistics for a short URL. The period can be VisitStatPeriodDaily, VisitStatPeriodMonthly, or VisitStatPeriodTotally. An empty period defaults to all-time statistics.

func (*Client) GetPrivateFileDownloadURL added in v1.2.0 

func (c *Client) GetPrivateFileDownloadURL(fileID int64) (*GetPrivateFileDownloadURLResponse, error)

GetPrivateFileDownloadURL retrieves a temporary download URL for a private file using its file ID. The URL is valid for a limited time (about 1 hour).

func (*Client) GetQRCodeHistory added in v1.3.0 

func (c *Client) GetQRCodeHistory(page int) (*GetQRCodeHistoryResponse, error)

GetQRCodeHistory retrieves a paginated list of QR codes. Page starts at 1. If page is 0 or negative, defaults to page 1.

func (*Client) GetTags 

func (c *Client) GetTags() (*TagsResponse, error)

GetTags retrieves the list of available tags.

func (*Client) GetTextDomains added in v1.0.1 

func (c *Client) GetTextDomains() (*DomainsResponse, error)

GetTextDomains retrieves the list of available domains for text sharing.

func (*Client) GetTextHistory added in v1.3.0 

func (c *Client) GetTextHistory(page int) (*GetTextHistoryResponse, error)

GetTextHistory retrieves a paginated list of text sharings created by the account. Page starts at 1. If page is 0 or negative, defaults to page 1.

func (*Client) GetUsage added in v1.1.0 

func (c *Client) GetUsage() (*GetUsageResponse, error)

GetUsage retrieves the usage statistics of the account.

func (*Client) SmartUploadFile added in v1.3.0 

func (c *Client) SmartUploadFile(req UploadFileRequest) (*UploadFileResponse, error)

SmartUploadFile uploads a file choosing the best strategy automatically: files up to 100MB go through the regular multipart upload, while larger files (up to 5GB) are transferred with the TUS resumable protocol. The reader should expose its size via Stat() (e.g. *os.File) or Len() (e.g. *bytes.Reader); when the size cannot be determined, the regular upload is used.

func (*Client) UpdateBioPage added in v1.3.0 

func (c *Client) UpdateBioPage(req UpdateBioPageRequest) (*UpdateBioPageResponse, error)

UpdateBioPage updates an existing bio page.

func (*Client) UpdateShortURL 

func (c *Client) UpdateShortURL(req UpdateShortURLRequest) (*UpdateShortURLResponse, error)

UpdateShortURL updates an existing short URL.

func (*Client) UpdateText 

func (c *Client) UpdateText(req UpdateTextRequest) (*UpdateTextResponse, error)

UpdateText updates an existing text entry.

func (*Client) UploadFile 

func (c *Client) UploadFile(req UploadFileRequest) (*UploadFileResponse, error)

UploadFile uploads a file to the server.

func (*Client) UploadLargeFile added in v1.3.0 

func (c *Client) UploadLargeFile(req CreateLargeFileUploadRequest, r io.Reader) (*CompleteLargeFileUploadResponse, error)

UploadLargeFile uploads a file up to 5GB using the TUS resumable protocol. It creates an upload session, transfers the content in chunks of DefaultLargeFileChunkSize, and completes the session. When the server reports an instant (deduplicated) upload, no data is transferred and the existing file record is returned.

func (*Client) UploadLargeFileChunk added in v1.3.0 

func (c *Client) UploadLargeFileChunk(uploadID string, offset int64, chunk []byte) (int64, error)

UploadLargeFileChunk uploads a single chunk at the given offset (TUS PATCH request) and returns the new offset reported by the server.

type CompleteLargeFileUploadData added in v1.3.0 

type CompleteLargeFileUploadData struct {
	File      UploadFileData `json:"file"`
	ShortLink string         `json:"short_link,omitempty"` // Short link created for the file (if domain/alias were provided)
}

CompleteLargeFileUploadData contains the completed upload result.

type CompleteLargeFileUploadRequest added in v1.3.0 

type CompleteLargeFileUploadRequest struct {
	UploadID string `json:"upload_id"`
}

CompleteLargeFileUploadRequest represents a request to complete a large file upload session.

type CompleteLargeFileUploadResponse added in v1.3.0 

type CompleteLargeFileUploadResponse struct {
	Code    int                         `json:"code"`
	Data    CompleteLargeFileUploadData `json:"data"`
	Message string                      `json:"message"`
}

CompleteLargeFileUploadResponse represents the response from completing a large file upload.

type Config 

type Config struct {
	BaseURL string
	APIKey  string
	Timeout time.Duration
}

Config contains configuration options for the Client

type CreateBioPageRequest added in v1.3.0 

type CreateBioPageRequest struct {
	CustomLinks []BioCustomLink `json:"custom_links,omitempty"`
	CustomSlug  string          `json:"custom_slug,omitempty"`
	Description string          `json:"description,omitempty"`
	Domain      string          `json:"domain,omitempty"`
	MastodonURL string          `json:"mastodon_url,omitempty"`
	RSSURL      string          `json:"rss_url,omitempty"`
	Title       string          `json:"title"`
}

CreateBioPageRequest represents a request to create a bio page.

type CreateBioPageResponse added in v1.3.0 

type CreateBioPageResponse struct {
	Code int `json:"code"`
	Data struct {
		BioPageID int64  `json:"bio_page_id"`
		ShortURL  string `json:"short_url"`
	} `json:"data"`
	Message string `json:"message"`
}

CreateBioPageResponse represents the response from creating a bio page.

type CreateLargeFileUploadData added in v1.3.0 

type CreateLargeFileUploadData struct {
	ExistingFile *UploadFileData `json:"existing_file,omitempty"` // Populated when FastUpload is true
	ExpiresAt    int64           `json:"expires_at"`              // Unix timestamp when this upload session expires (24h)
	FastUpload   bool            `json:"fast_upload"`             // True when the file already exists and upload was skipped
	FileSize     int64           `json:"file_size"`
	ID           int64           `json:"id"`
	UploadID     string          `json:"upload_id"`
	UploadURL    string          `json:"upload_url"` // TUS upload endpoint URL
}

CreateLargeFileUploadData contains the created upload session information.

type CreateLargeFileUploadRequest added in v1.3.0 

type CreateLargeFileUploadRequest struct {
	Alias       string `json:"alias,omitempty"` // Custom slug for the short link (alphanumeric only)
	Description string `json:"description,omitempty"`
	Domain      string `json:"domain,omitempty"`
	ExpireAt    int64  `json:"expire_at,omitempty"` // Unix timestamp for link expiry
	FileHash    string `json:"file_hash,omitempty"` // SHA256 hash for instant upload deduplication
	FileName    string `json:"file_name"`
	FileSize    int64  `json:"file_size"`
	IsPrivate   int    `json:"is_private,omitempty"` // 0 = public (default), 1 = private
	MimeType    string `json:"mime_type,omitempty"`
	Password    string `json:"password,omitempty"`
	Title       string `json:"title,omitempty"`
}

CreateLargeFileUploadRequest represents a request to create a large file (TUS) upload session.

type CreateLargeFileUploadResponse added in v1.3.0 

type CreateLargeFileUploadResponse struct {
	Code    int                       `json:"code"`
	Data    CreateLargeFileUploadData `json:"data"`
	Message string                    `json:"message"`
}

CreateLargeFileUploadResponse represents the response from creating a large file upload session.

type CreateQRCodeData added in v1.3.0 

type CreateQRCodeData struct {
	CustomSlug string `json:"custom_slug"`
	PDFURL     string `json:"pdf_url"`
	PNGURL     string `json:"png_url"`
	ShortURL   string `json:"short_url"`
	Slug       string `json:"slug"`
	SVGURL     string `json:"svg_url"`
}

CreateQRCodeData contains the created QR code information.

type CreateQRCodeRequest added in v1.3.0 

type CreateQRCodeRequest struct {
	CustomSlug string `json:"custom_slug,omitempty"`
	Domain     string `json:"domain,omitempty"`
	TargetURL  string `json:"target_url"`
	Title      string `json:"title"`
}

CreateQRCodeRequest represents a request to create a dynamic QR code.

type CreateQRCodeResponse added in v1.3.0 

type CreateQRCodeResponse struct {
	Code    int              `json:"code"`
	Data    CreateQRCodeData `json:"data"`
	Message string           `json:"message"`
}

CreateQRCodeResponse represents the response from creating a QR code.

type CreateShortURLRequest 

type CreateShortURLRequest struct {
	CustomSlug            string  `json:"custom_slug,omitempty"`
	Domain                string  `json:"domain"`
	ExpirationRedirectURL string  `json:"expiration_redirect_url,omitempty"`
	ExpireAt              int64   `json:"expire_at,omitempty"` // Unix timestamp in seconds
	Password              string  `json:"password,omitempty"`
	TagIDs                []int64 `json:"tag_ids,omitempty"`
	TargetURL             string  `json:"target_url"`
	Title                 string  `json:"title,omitempty"`
}

CreateShortURLRequest represents a request to create a short URL.

type CreateShortURLResponse 

type CreateShortURLResponse struct {
	Code int `json:"code"`
	Data struct {
		CustomSlug string `json:"custom_slug"`
		ShortURL   string `json:"short_url"`
		Slug       string `json:"slug"`
	} `json:"data"`
	Message string `json:"message"`
}

CreateShortURLResponse represents the response from creating a short URL.

type CreateTextRequest 

type CreateTextRequest struct {
	Content    string  `json:"content"`
	CustomSlug string  `json:"custom_slug,omitempty"`
	Domain     string  `json:"domain,omitempty"`
	ExpireAt   int64   `json:"expire_at,omitempty"` // Unix timestamp in seconds
	Password   string  `json:"password,omitempty"`
	TagIDs     []int64 `json:"tag_ids,omitempty"`
	TextType   string  `json:"text_type,omitempty"`
	Title      string  `json:"title,omitempty"`
}

type CreateTextResponse 

type CreateTextResponse struct {
	Code int `json:"code"`
	Data struct {
		CustomSlug string `json:"custom_slug"`
		ShortURL   string `json:"short_url"`
		Slug       string `json:"slug"`
	} `json:"data"`
	Message string `json:"message"`
}

CreateTextResponse represents the response from creating a text sharing.

type DeleteBioPageRequest added in v1.3.0 

type DeleteBioPageRequest struct {
	ID int64 `json:"id"`
}

DeleteBioPageRequest represents a request to delete a bio page.

type DeleteBioPageResponse added in v1.3.0 

type DeleteBioPageResponse struct {
	Code    int    `json:"code"`
	Data    any    `json:"data,omitempty"`
	Message string `json:"message"`
}

DeleteBioPageResponse represents the response from deleting a bio page.

type DeleteFileResponse 

type DeleteFileResponse struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Success bool   `json:"success"`
}

DeleteFileResponse represents the response from deleting a file.

type DeleteQRCodeRequest added in v1.3.0 

type DeleteQRCodeRequest struct {
	Domain string `json:"domain"`
	Slug   string `json:"slug"`
}

DeleteQRCodeRequest represents a request to delete a QR code.

type DeleteQRCodeResponse added in v1.3.0 

type DeleteQRCodeResponse struct {
	Code    int    `json:"code"`
	Data    any    `json:"data,omitempty"`
	Message string `json:"message"`
}

DeleteQRCodeResponse represents the response from deleting a QR code.

type DeleteTextRequest 

type DeleteTextRequest struct {
	Domain string `json:"domain"`
	Slug   string `json:"slug"`
}

DeleteTextRequest represents a request to delete a text.

type DeleteTextResponse 

type DeleteTextResponse struct {
	Code    int    `json:"code"`
	Data    any    `json:"data,omitempty"`
	Message string `json:"message"`
}

DeleteTextResponse represents the response from deleting a text.

type DeleteURLRequest 

type DeleteURLRequest struct {
	Domain string `json:"domain"`
	Slug   string `json:"slug"`
}

DeleteURLRequest represents a request to delete a short URL.

type DeleteURLResponse 

type DeleteURLResponse struct {
	Code    int    `json:"code"`
	Data    any    `json:"data,omitempty"`
	Message string `json:"message"`
}

DeleteURLResponse represents the response from deleting a short URL.

type DomainsResponse 

type DomainsResponse struct {
	Code int `json:"code"`
	Data struct {
		Domains []string `json:"domains"`
	} `json:"data"`
	Message string `json:"message"`
}

DomainsResponse represents the response containing available domains.

type GetBioPageHistoryResponse added in v1.3.0 

type GetBioPageHistoryResponse struct {
	Code int `json:"code"`
	Data struct {
		BioPages []BioPageData `json:"bio_pages"`
		Total    int64         `json:"total"`
	} `json:"data"`
	Message string `json:"message"`
}

GetBioPageHistoryResponse represents the response containing bio page history.

type GetFileHistoryResponse added in v1.1.1 

type GetFileHistoryResponse struct {
	Code    int              `json:"code"`
	Data    []UploadFileData `json:"data"`
	Message string           `json:"message"`
	Success bool             `json:"success"`
}

GetFileHistoryResponse represents the response containing file upload history.

type GetLargeFileUploadProgressResponse added in v1.3.0 

type GetLargeFileUploadProgressResponse struct {
	Code    int                         `json:"code"`
	Data    LargeFileUploadProgressData `json:"data"`
	Message string                      `json:"message"`
}

GetLargeFileUploadProgressResponse represents the response containing upload progress.

type GetLinkHistoryResponse added in v1.3.0 

type GetLinkHistoryResponse struct {
	Code    int               `json:"code"`
	Data    []LinkHistoryData `json:"data"`
	Message string            `json:"message"`
	Success bool              `json:"success"`
}

GetLinkHistoryResponse represents the response containing link creation history.

type GetLinkVisitStatResponse added in v1.3.0 

type GetLinkVisitStatResponse struct {
	Code int `json:"code"`
	Data struct {
		VisitCount int64 `json:"visit_count"`
	} `json:"data"`
	Message string `json:"message"`
}

GetLinkVisitStatResponse represents the response containing link visit statistics.

type GetPrivateFileDownloadURLData added in v1.2.0 

type GetPrivateFileDownloadURLData struct {
	FileID    int64  `json:"file_id"`
	URL       string `json:"url"`
	ExpiresAt int64  `json:"expires_at"`
}

GetPrivateFileDownloadURLData contains the private file download URL information.

type GetPrivateFileDownloadURLResponse added in v1.2.0 

type GetPrivateFileDownloadURLResponse struct {
	Code    int                           `json:"code"`
	Data    GetPrivateFileDownloadURLData `json:"data"`
	Message string                        `json:"message"`
	Success bool                          `json:"success"`
}

GetPrivateFileDownloadURLResponse represents the response when getting a private file download URL.

type GetQRCodeHistoryResponse added in v1.3.0 

type GetQRCodeHistoryResponse struct {
	Code int `json:"code"`
	Data struct {
		QRCodes []QRCodeHistoryData `json:"qrcodes"`
		Total   int64               `json:"total"`
	} `json:"data"`
	Message string `json:"message"`
}

GetQRCodeHistoryResponse represents the response containing QR code history.

type GetTextHistoryResponse added in v1.3.0 

type GetTextHistoryResponse struct {
	Code    int               `json:"code"`
	Data    []TextHistoryData `json:"data"`
	Message string            `json:"message"`
	Success bool              `json:"success"`
}

GetTextHistoryResponse represents the response containing text creation history.

type GetUsageResponse added in v1.1.0 

type GetUsageResponse struct {
	Code int `json:"code"`
	Data struct {
		APICountDay           int    `json:"api_count_day"`
		APICountDayLimit      int    `json:"api_count_day_limit"`
		APICountMonth         int    `json:"api_count_month"`
		APICountMonthLimit    int    `json:"api_count_month_limit"`
		LinkCountDay          int    `json:"link_count_day"`
		LinkCountDayLimit     int    `json:"link_count_day_limit"`
		LinkCountMonth        int    `json:"link_count_month"`
		LinkCountMonthLimit   int    `json:"link_count_month_limit"`
		QRCodeCountDay        int    `json:"qrcode_count_day"`
		QRCodeCountDayLimit   int    `json:"qrcode_count_day_limit"`
		QRCodeCountMonth      int    `json:"qrcode_count_month"`
		QRCodeCountMonthLimit int    `json:"qrcode_count_month_limit"`
		TextCountDay          int    `json:"text_count_day"`
		TextCountDayLimit     int    `json:"text_count_day_limit"`
		TextCountMonth        int    `json:"text_count_month"`
		TextCountMonthLimit   int    `json:"text_count_month_limit"`
		UploadCountDay        int    `json:"upload_count_day"`
		UploadCountDayLimit   int    `json:"upload_count_day_limit"`
		UploadCountMonth      int    `json:"upload_count_month"`
		UploadCountMonthLimit int    `json:"upload_count_month_limit"`
		FileCount             int    `json:"file_count"`
		StorageUsageMB        string `json:"storage_usage_mb"`       // in MB, rounded to 2 decimal places
		StorageUsageLimitMB   string `json:"storage_usage_limit_mb"` // in MB, "-1" means unlimited
	} `json:"data"`
	Message string `json:"message"`
}

GetUsageResponse represents the response containing usage statistics.

type LargeFileUploadProgressData added in v1.3.0 

type LargeFileUploadProgressData struct {
	CreatedAt    int64   `json:"created_at"`
	FileName     string  `json:"file_name"`
	FileSize     int64   `json:"file_size"`
	Progress     float64 `json:"progress"` // Progress percentage (0-100)
	Status       int     `json:"status"`   // See LargeFileUploadStatus* constants
	UpdatedAt    int64   `json:"updated_at"`
	UploadID     string  `json:"upload_id"`
	UploadedSize int64   `json:"uploaded_size"`
}

LargeFileUploadProgressData contains the progress of a large file upload session.

type LinkHistoryData added in v1.3.0 

type LinkHistoryData struct {
	CreatedAt  int64  `json:"created_at"`
	Domain     string `json:"domain"`
	ObjectType int    `json:"object_type"` // 0 = link, 1 = file, 2 = text, 3 = qrcode
	ShortURL   string `json:"short_url"`
	Slug       string `json:"slug"`
	TargetURL  string `json:"target_url"`
	Title      string `json:"title"`
	VisitCount int64  `json:"visit_count"`
}

LinkHistoryData represents a short link entry in the creation history.

type QRCodeHistoryData added in v1.3.0 

type QRCodeHistoryData struct {
	CreatedAt int64  `json:"created_at"`
	Domain    string `json:"domain"`
	PDFURL    string `json:"pdf_url"`
	PNGURL    string `json:"png_url"`
	ScanCount int64  `json:"scan_count"`
	ShortURL  string `json:"short_url"`
	Slug      string `json:"slug"`
	SVGURL    string `json:"svg_url"`
	Title     string `json:"title"`
}

QRCodeHistoryData represents a QR code entry in the history.

type Tag 

type Tag struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

Tag represents a tag entity.

type TagsResponse 

type TagsResponse struct {
	Code int `json:"code"`
	Data struct {
		Tags []Tag `json:"tags"`
	} `json:"data"`
	Message string `json:"message"`
}

TagsResponse represents the response containing available tags.

type TextHistoryData added in v1.3.0 

type TextHistoryData struct {
	ContentPreview string `json:"content_preview"` // Preview of the content (truncated)
	CreatedAt      int64  `json:"created_at"`
	Domain         string `json:"domain"`
	ID             int64  `json:"id"`
	IsExpired      bool   `json:"is_expired"`
	ShortURL       string `json:"short_url"`
	Slug           string `json:"slug"`
	TextType       string `json:"text_type"` // "plain_text", "source_code", or "markdown"
	Title          string `json:"title"`
}

TextHistoryData represents a text sharing entry in the creation history.

type UpdateBioPageRequest added in v1.3.0 

type UpdateBioPageRequest struct {
	CustomLinks []BioCustomLink `json:"custom_links,omitempty"`
	Description string          `json:"description,omitempty"`
	ID          int64           `json:"id"`
	MastodonURL string          `json:"mastodon_url,omitempty"`
	RSSURL      string          `json:"rss_url,omitempty"`
	Title       string          `json:"title"`
}

UpdateBioPageRequest represents a request to update a bio page. Omit CustomLinks to leave the existing custom links unchanged.

type UpdateBioPageResponse added in v1.3.0 

type UpdateBioPageResponse struct {
	Code    int    `json:"code"`
	Data    any    `json:"data,omitempty"`
	Message string `json:"message"`
}

UpdateBioPageResponse represents the response from updating a bio page.

type UpdateShortURLRequest 

type UpdateShortURLRequest struct {
	Domain    string `json:"domain"`
	Slug      string `json:"slug"`
	TargetURL string `json:"target_url"`
	Title     string `json:"title"`
}

UpdateShortURLRequest represents a request to update a short URL.

type UpdateShortURLResponse 

type UpdateShortURLResponse struct {
	Code    int    `json:"code"`
	Data    any    `json:"data"`
	Message string `json:"message"`
}

UpdateShortURLResponse represents the response from updating a short URL.

type UpdateTextRequest 

type UpdateTextRequest struct {
	Domain  string `json:"domain"`
	Slug    string `json:"slug"`
	Content string `json:"content"`
	Title   string `json:"title,omitempty"`
}

type UpdateTextResponse 

type UpdateTextResponse struct {
	Code    int    `json:"code"`
	Data    any    `json:"data,omitempty"`
	Message string `json:"message"`
}

UpdateTextResponse represents the response from updating a text.

type UploadFileData added in v1.1.1 

type UploadFileData struct {
	CreatedAt    int    `json:"created_at,omitempty"`
	Delete       string `json:"delete"`
	FileID       int    `json:"file_id"`
	Filename     string `json:"filename"`
	Hash         string `json:"hash"`
	Height       int    `json:"height"`
	MimeType     string `json:"mime_type,omitempty"`
	Page         string `json:"page"`
	Path         string `json:"path"`
	Size         int    `json:"size"`
	Storename    string `json:"storename"`
	ThumbURL     string `json:"thumb_url,omitempty"`
	UploadStatus int    `json:"upload_status"`
	URL          string `json:"url"`
	Width        int    `json:"width"`
}

UploadFileData represents the metadata of an uploaded file.

type UploadFileRequest added in v1.1.1 

type UploadFileRequest struct {
	Filename   string
	File       io.Reader
	Domain     string
	CustomSlug string
	IsPrivate  bool
}

UploadFileRequest represents a request to upload a file.

type UploadFileResponse 

type UploadFileResponse struct {
	Code    int            `json:"code"`
	Data    UploadFileData `json:"data"`
	Message string         `json:"message"`
}

UploadFileResponse represents the response from uploading a file.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.