cloudlayer

package module
v0.0.0-...-b25601e Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2026 License: MIT Imports: 17 Imported by: 0

README

cloudlayer.io Go SDK

Go Reference CI

Official Go SDK for the cloudlayer.io document generation API. Convert URLs, HTML, and templates to PDF and images.

Installation

go get github.com/cloudlayerio/cloudlayerio-go

Requires Go 1.21+. Zero external dependencies.

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    cloudlayer "github.com/cloudlayerio/cloudlayerio-go"
)

func main() {
    client, err := cloudlayer.NewClient("your-api-key", cloudlayer.V2)
    if err != nil {
        log.Fatal(err)
    }

    // Generate a PDF from HTML
    result, err := client.HTMLToPDF(context.Background(), &cloudlayer.HTMLToPDFOptions{
        HTMLOptions: cloudlayer.HTMLOptions{
            HTML: cloudlayer.EncodeHTML("<h1>Hello World</h1>"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // v2 returns a Job — wait for completion, then download
    job, err := client.WaitForJob(context.Background(), result.Job.ID)
    if err != nil {
        log.Fatal(err)
    }

    data, err := client.DownloadJobResult(context.Background(), job)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Downloaded %d bytes\n", len(data))
}

API Versions

Feature v1 v2
Response Raw binary JSON Job object
Default mode Synchronous Asynchronous
Storage Optional Enabled by default
Binary access Direct from response Via DownloadJobResult()

v2 never returns binary directly. Always use WaitForJob() + DownloadJobResult().

// v2 (recommended)
client, _ := cloudlayer.NewClient("key", cloudlayer.V2)

// v1 (legacy — returns raw binary)
client, _ := cloudlayer.NewClient("key", cloudlayer.V1)

Document Generation

URL to PDF/Image
result, err := client.URLToPDF(ctx, &cloudlayer.URLToPDFOptions{
    URLOptions: cloudlayer.URLOptions{
        URL: cloudlayer.StringPtr("https://example.com"),
    },
    PDFOptions: cloudlayer.PDFOptions{
        Format: &cloudlayer.FormatA4,
    },
})
HTML to PDF/Image
result, err := client.HTMLToPDF(ctx, &cloudlayer.HTMLToPDFOptions{
    HTMLOptions: cloudlayer.HTMLOptions{
        HTML: cloudlayer.EncodeHTML("<h1>Invoice</h1><p>Amount: $100</p>"),
    },
    PDFOptions: cloudlayer.PDFOptions{
        PrintBackground: cloudlayer.BoolPtr(true),
    },
})
Template to PDF/Image
result, err := client.TemplateToPDF(ctx, &cloudlayer.TemplateToPDFOptions{
    TemplateOptions: cloudlayer.TemplateOptions{
        TemplateID: cloudlayer.StringPtr("professional-invoice"),
        Data: map[string]interface{}{
            "invoiceNumber": "INV-001",
            "total":         450.00,
        },
    },
})

Document Conversion

// DOCX to PDF
file, _ := cloudlayer.FileInputFromPath("document.docx")
result, err := client.DOCXToPDF(ctx, &cloudlayer.DOCXToPDFOptions{File: file})

// Merge PDFs
result, err := client.MergePDFs(ctx, &cloudlayer.MergePDFsOptions{
    URLOptions: cloudlayer.URLOptions{
        Batch: &cloudlayer.Batch{
            URLs: []string{"https://example.com/1.pdf", "https://example.com/2.pdf"},
        },
    },
})

Data Management

// List recent jobs
jobs, err := client.ListJobs(ctx)

// Get job details
job, err := client.GetJob(ctx, "job-id")

// List assets
assets, err := client.ListAssets(ctx)

// Account info
account, err := client.GetAccount(ctx)

// Storage configuration
configs, err := client.ListStorage(ctx)

Working with v2 Jobs

// 1. Start conversion
result, err := client.HTMLToPDF(ctx, &cloudlayer.HTMLToPDFOptions{
    HTMLOptions: cloudlayer.HTMLOptions{HTML: cloudlayer.EncodeHTML(html)},
})

// 2. Wait for completion (polls every 5s, max 5min)
job, err := client.WaitForJob(ctx, result.Job.ID)

// 3. Download the result
data, err := client.DownloadJobResult(ctx, job)
os.WriteFile("output.pdf", data, 0644)

Custom polling options:

job, err := client.WaitForJob(ctx, jobID,
    cloudlayer.WithPollInterval(3*time.Second),
    cloudlayer.WithMaxWait(10*time.Minute),
)

Error Handling

All errors are concrete types supporting errors.As:

result, err := client.HTMLToPDF(ctx, opts)
if err != nil {
    var authErr *cloudlayer.AuthError
    if errors.As(err, &authErr) {
        log.Fatal("Invalid API key")
    }

    var rateLimitErr *cloudlayer.RateLimitError
    if errors.As(err, &rateLimitErr) {
        log.Printf("Rate limited, retry after %ds", *rateLimitErr.RetryAfter)
    }

    var validationErr *cloudlayer.ValidationError
    if errors.As(err, &validationErr) {
        log.Printf("Invalid input: %s", validationErr.Message)
    }

    log.Fatal(err)
}
Error Type When
*AuthError 401 or 403 response
*RateLimitError 429 response
*APIError Other API errors (400, 404, 500, etc.)
*ValidationError Client-side input validation failure
*ConfigError Invalid client configuration
*NetworkError Connection failures, DNS errors
*TimeoutError SDK internal timeout (e.g., WaitForJob max wait)

Client Configuration

client, err := cloudlayer.NewClient("key", cloudlayer.V2,
    cloudlayer.WithTimeout(60*time.Second),
    cloudlayer.WithMaxRetries(3),
    cloudlayer.WithBaseURL("https://custom-endpoint.example.com"),
    cloudlayer.WithHeaders(map[string]string{"X-Custom": "value"}),
)

Other SDKs

License

MIT - see LICENSE

Documentation

Overview

Package cloudlayer provides a Go client for the CloudLayer.io document generation API. It supports URL/HTML/template to PDF/image conversion, document format conversion, job management, and storage configuration.

Basic usage: 

client, err := cloudlayer.NewClient("your-api-key", cloudlayer.V2)
if err != nil {
    log.Fatal(err)
}

result, err := client.HTMLToPDF(ctx, &cloudlayer.HTMLToPDFOptions{
    HTMLOptions: cloudlayer.HTMLOptions{
        HTML: cloudlayer.EncodeHTML("<h1>Hello World</h1>"),
    },
})

API Versions

CloudLayer.io supports two API versions with different response behaviors:

  • V1: Synchronous by default. Conversion endpoints return raw binary data.
  • V2: Asynchronous by default. Conversion endpoints return a Job object. Use Client.WaitForJob to poll until completion, then Client.DownloadJobResult to fetch the binary.

The API version must be specified when creating the client — there is no default.

Error Handling

All errors returned by the SDK are concrete types that support errors.As: 

var authErr *cloudlayer.AuthError
if errors.As(err, &authErr) {
    // Handle authentication failure (401 or 403)
}

var rateLimitErr *cloudlayer.RateLimitError
if errors.As(err, &rateLimitErr) {
    // Handle rate limiting (429), check rateLimitErr.RetryAfter
}

Index

Constants

View Source 
const Version = "0.1.0"

Version is the current version of the cloudlayer-go SDK.

Variables

This section is empty.

Functions

func EncodeHTML 

func EncodeHTML(html string) string

EncodeHTML base64-encodes an HTML string for use with [HTMLOptions.HTML] and [TemplateOptions.Template].

Types

type APIError 

type APIError struct {
	StatusCode    int             `json:"statusCode"`
	StatusText    string          `json:"statusText"`
	Message       string          `json:"message"`
	Body          json.RawMessage `json:"body,omitempty"`
	RequestPath   string          `json:"requestPath"`
	RequestMethod string          `json:"requestMethod"`
}

APIError represents an error response from the CloudLayer.io API.

func (*APIError) Error 

func (e *APIError) Error() string

type APIVersion 

type APIVersion string

APIVersion represents the CloudLayer.io API version. The API version must be explicitly specified when creating a client. 

const (
	// V1 is API version 1. Conversion endpoints return raw binary by default.
	V1 APIVersion = "v1"
	// V2 is API version 2. Conversion endpoints return Job objects by default.
	V2 APIVersion = "v2"
)

type AccountInfo 

type AccountInfo struct {
	Email            string                 `json:"-"`
	CallsLimit       int                    `json:"-"`
	Calls            int                    `json:"-"`
	StorageUsed      int                    `json:"-"`
	StorageLimit     int                    `json:"-"`
	Subscription     string                 `json:"-"`
	BytesTotal       int                    `json:"-"`
	BytesLimit       int                    `json:"-"`
	ComputeTimeTotal int                    `json:"-"`
	ComputeTimeLimit int                    `json:"-"`
	SubType          string                 `json:"-"`
	UID              string                 `json:"-"`
	Credit           *float64               `json:"-"`
	SubActive        bool                   `json:"-"`
	Extra            map[string]interface{} `json:"-"`
}

AccountInfo contains account usage and subscription information.

func (AccountInfo) MarshalJSON 

func (a AccountInfo) MarshalJSON() ([]byte, error)

MarshalJSON implements custom marshaling for AccountInfo.

func (*AccountInfo) UnmarshalJSON 

func (a *AccountInfo) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshaling for AccountInfo. Known fields are extracted into typed struct fields; remaining fields are collected into the Extra map.

type Asset 

type Asset struct {
	UID           string          `json:"uid"`
	ID            *string         `json:"id,omitempty"`
	FileID        string          `json:"fileId"`
	PreviewFileID *string         `json:"previewFileId,omitempty"`
	Type          *string         `json:"type,omitempty"`
	Ext           *string         `json:"ext,omitempty"`
	PreviewExt    *string         `json:"previewExt,omitempty"`
	URL           *string         `json:"url,omitempty"`
	PreviewURL    *string         `json:"previewUrl,omitempty"`
	Size          *int            `json:"size,omitempty"`
	Timestamp     json.RawMessage `json:"timestamp,omitempty"`
	ProjectID     *string         `json:"projectId,omitempty"`
	JobID         *string         `json:"jobId,omitempty"`
	Name          *string         `json:"name,omitempty"`
}

Asset represents a generated file asset.

func (*Asset) TimestampUnix 

func (a *Asset) TimestampUnix() int64

TimestampUnix returns the asset timestamp as Unix milliseconds. It handles both numeric timestamps and Firestore timestamp objects.

type AuthError 

type AuthError struct {
	APIError
}

AuthError is returned when the API rejects authentication (HTTP 401 or 403).

func (*AuthError) Error 

func (e *AuthError) Error() string

type Authentication 

type Authentication struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

Authentication represents HTTP basic authentication credentials.

type BaseOptions 

type BaseOptions struct {
	Name      *string        `json:"name,omitempty"`
	Timeout   *int           `json:"timeout,omitempty"`
	Delay     *int           `json:"delay,omitempty"`
	Filename  *string        `json:"filename,omitempty"`
	Inline    *bool          `json:"inline,omitempty"`
	Async     *bool          `json:"async,omitempty"`
	Storage   *StorageOption `json:"storage,omitempty"`
	Webhook   *string        `json:"webhook,omitempty"`
	APIVer    *string        `json:"apiVer,omitempty"`
	ProjectID *string        `json:"projectId,omitempty"`
}

BaseOptions are common options shared by all conversion endpoints.

type Batch 

type Batch struct {
	URLs []string `json:"urls"`
}

Batch represents a batch of URLs for batch conversion.

type Client 

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

Client is the CloudLayer.io API client. Create one with NewClient.

func NewClient 

func NewClient(apiKey string, apiVersion APIVersion, opts ...ClientOption) (*Client, error)

NewClient creates a new CloudLayer.io API client.

The apiKey and apiVersion parameters are required. Use V1 or V2 for the API version. Functional options can be used to customize the client. 

client, err := cloudlayer.NewClient("your-api-key", cloudlayer.V2)

func (*Client) AddStorage 

func (c *Client) AddStorage(ctx context.Context, params *StorageParams) (*StorageCreateResponse, error)

AddStorage creates a new storage configuration.

If the user's plan does not support custom storage, the server returns HTTP 200 with {allowed: false, reason: "...", statusCode: N}. In this case, AddStorage returns an APIError with the reason and status code from the response.

func (*Client) DOCXToHTML 

func (c *Client) DOCXToHTML(ctx context.Context, opts *DOCXToHTMLOptions) (*ConversionResult, error)

DOCXToHTML converts a DOCX document to HTML via multipart upload.

func (*Client) DOCXToPDF 

func (c *Client) DOCXToPDF(ctx context.Context, opts *DOCXToPDFOptions) (*ConversionResult, error)

DOCXToPDF converts a DOCX document to PDF via multipart upload.

func (*Client) DeleteStorage 

func (c *Client) DeleteStorage(ctx context.Context, storageID string) error

DeleteStorage deletes a storage configuration by ID.

func (*Client) DownloadJobResult 

func (c *Client) DownloadJobResult(ctx context.Context, job *Job) ([]byte, error)

DownloadJobResult fetches the binary file from a completed job's asset URL.

This is essential for v2 workflows where conversion endpoints return Job objects instead of raw binary. Use Client.WaitForJob first to ensure the job is complete, then call this to download the result.

The asset URL is a presigned S3 URL with a TTL — if it has expired, this method returns an error suggesting the URL may have expired.

func (*Client) GetAccount 

func (c *Client) GetAccount(ctx context.Context) (*AccountInfo, error)

GetAccount retrieves account information including usage statistics.

func (*Client) GetAsset 

func (c *Client) GetAsset(ctx context.Context, assetID string) (*Asset, error)

GetAsset retrieves a single asset by ID.

func (*Client) GetJob 

func (c *Client) GetJob(ctx context.Context, jobID string) (*Job, error)

GetJob retrieves a single job by ID.

func (*Client) GetStatus 

func (c *Client) GetStatus(ctx context.Context) (*StatusResponse, error)

GetStatus checks the API health status.

Note: the legacy API returns {"status": "ok "} with a trailing space.

func (*Client) GetStorage 

func (c *Client) GetStorage(ctx context.Context, storageID string) (*StorageDetail, error)

GetStorage retrieves a single storage configuration by ID.

func (*Client) GetTemplate 

func (c *Client) GetTemplate(ctx context.Context, templateID string) (*PublicTemplate, error)

GetTemplate retrieves a single public template by ID.

This endpoint always uses /v2/ regardless of the client's API version.

func (*Client) HTMLToImage 

func (c *Client) HTMLToImage(ctx context.Context, opts *HTMLToImageOptions) (*ConversionResult, error)

HTMLToImage converts HTML content to an image.

func (*Client) HTMLToPDF 

func (c *Client) HTMLToPDF(ctx context.Context, opts *HTMLToPDFOptions) (*ConversionResult, error)

HTMLToPDF converts HTML content to PDF.

The HTML field must be base64-encoded. Use EncodeHTML to encode raw HTML.

func (*Client) ListAssets 

func (c *Client) ListAssets(ctx context.Context) ([]Asset, error)

ListAssets returns up to 10 most recent assets (newest first).

Note: the server limits results to 10 records. This method should not be polled frequently as each call reads documents from Firestore.

func (*Client) ListJobs 

func (c *Client) ListJobs(ctx context.Context) ([]Job, error)

ListJobs returns up to 10 most recent jobs (newest first).

Note: the server limits results to 10 records. This method should not be polled frequently as each call reads documents from Firestore.

func (*Client) ListStorage 

func (c *Client) ListStorage(ctx context.Context) ([]StorageListItem, error)

ListStorage returns all storage configurations for the account.

func (*Client) ListTemplates 

func (c *Client) ListTemplates(ctx context.Context, opts *ListTemplatesOptions) ([]PublicTemplate, error)

ListTemplates returns public templates from the CloudLayer.io gallery.

This endpoint always uses /v2/ regardless of the client's API version, and does not require API key authentication.

func (*Client) MergePDFs 

func (c *Client) MergePDFs(ctx context.Context, opts *MergePDFsOptions) (*ConversionResult, error)

MergePDFs merges multiple PDFs into one. Uses URL-based input (not file uploads).

func (*Client) PDFToDOCX 

func (c *Client) PDFToDOCX(ctx context.Context, opts *PDFToDOCXOptions) (*ConversionResult, error)

PDFToDOCX converts a PDF to DOCX via multipart upload.

func (*Client) TemplateToImage 

func (c *Client) TemplateToImage(ctx context.Context, opts *TemplateToImageOptions) (*ConversionResult, error)

TemplateToImage generates an image from a template.

func (*Client) TemplateToPDF 

func (c *Client) TemplateToPDF(ctx context.Context, opts *TemplateToPDFOptions) (*ConversionResult, error)

TemplateToPDF generates a PDF from a template.

Either TemplateID or Template (base64-encoded) must be provided, but not both.

func (*Client) URLToImage 

func (c *Client) URLToImage(ctx context.Context, opts *URLToImageOptions) (*ConversionResult, error)

URLToImage converts a URL to an image.

func (*Client) URLToPDF 

func (c *Client) URLToPDF(ctx context.Context, opts *URLToPDFOptions) (*ConversionResult, error)

URLToPDF converts a URL to PDF.

v2 returns a Job object (use Client.WaitForJob + Client.DownloadJobResult). v1 returns raw binary data in [ConversionResult.Data].

func (*Client) WaitForJob 

func (c *Client) WaitForJob(ctx context.Context, jobID string, opts ...WaitOption) (*Job, error)

WaitForJob polls Client.GetJob until the job reaches a terminal status ("success" or "error").

On success: returns the completed Job. On error status: returns an error containing the job ID and error message. On context cancellation: returns the context error. On max wait exceeded: returns a TimeoutError.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures a Client. Use With* functions to create options.

func WithBaseURL 

func WithBaseURL(url string) ClientOption

WithBaseURL sets the API base URL. Defaults to "https://api.cloudlayer.io".

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) ClientOption

WithHTTPClient sets a custom http.Client for requests.

func WithHeaders 

func WithHeaders(h map[string]string) ClientOption

WithHeaders sets additional headers to include on every request.

func WithMaxRetries 

func WithMaxRetries(n int) ClientOption

WithMaxRetries sets the maximum number of retries for retryable requests. Clamped to [0, 5]. Defaults to 2.

func WithTimeout 

func WithTimeout(d time.Duration) ClientOption

WithTimeout sets the HTTP client timeout. Defaults to 30 seconds.

func WithUserAgent 

func WithUserAgent(ua string) ClientOption

WithUserAgent sets the User-Agent header. Defaults to "cloudlayerio-go/{version}".

type ConfigError 

type ConfigError struct {
	Message string
}

ConfigError is returned when client configuration is invalid.

func (*ConfigError) Error 

func (e *ConfigError) Error() string

type ConversionResult 

type ConversionResult struct {
	// Job is populated for v2 responses and v1 async responses.
	Job *Job
	// Data is populated for v1 synchronous responses (raw binary).
	Data []byte
	// Headers contains CloudLayer-specific response headers.
	Headers *ResponseHeaders
	// Status is the HTTP status code.
	Status int
	// Filename is from the Content-Disposition header (v1 only).
	Filename string
}

ConversionResult wraps the response from a conversion endpoint. 

type Cookie struct {
	Name     string  `json:"name"`
	Value    string  `json:"value"`
	URL      *string `json:"url,omitempty"`
	Domain   *string `json:"domain,omitempty"`
	Path     *string `json:"path,omitempty"`
	Expires  *int    `json:"expires,omitempty"`
	HTTPOnly *bool   `json:"httpOnly,omitempty"`
	Secure   *bool   `json:"secure,omitempty"`
	SameSite *string `json:"sameSite,omitempty"`
}

Cookie represents a browser cookie to set before page navigation.

type DOCXToHTMLOptions 

type DOCXToHTMLOptions struct {
	File *FileInput `json:"-"`
	BaseOptions
}

DOCXToHTMLOptions are options for Client.DOCXToHTML.

type DOCXToPDFOptions 

type DOCXToPDFOptions struct {
	File *FileInput `json:"-"`
	BaseOptions
}

DOCXToPDFOptions are options for Client.DOCXToPDF.

type FileInput 

type FileInput struct {
	// Reader provides the file content. Required.
	Reader io.Reader
	// Filename is used as the multipart filename. Required.
	Filename string
	// ContentType is the MIME type. Defaults to "application/octet-stream" if empty.
	ContentType string
}

FileInput represents a file to upload via multipart form. Use FileInputFromPath for convenience, or create directly with an io.Reader.

func FileInputFromPath 

func FileInputFromPath(path string) (*FileInput, error)

FileInputFromPath opens a file at the given path and returns a FileInput. The caller is responsible for closing the underlying file when done (the returned FileInput.Reader is an *os.File).

type GeneratePreviewOption 

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

GeneratePreviewOption represents a value that can be either a boolean or a PreviewOptions object. Use NewGeneratePreviewBool or NewGeneratePreviewOptions to create values.

func NewGeneratePreviewBool 

func NewGeneratePreviewBool(b bool) *GeneratePreviewOption

NewGeneratePreviewBool creates a GeneratePreviewOption from a boolean.

func NewGeneratePreviewOptions 

func NewGeneratePreviewOptions(opts *PreviewOptions) *GeneratePreviewOption

NewGeneratePreviewOptions creates a GeneratePreviewOption from preview options.

func (GeneratePreviewOption) MarshalJSON 

func (g GeneratePreviewOption) MarshalJSON() ([]byte, error)

MarshalJSON serializes as either true/false or a JSON object.

func (*GeneratePreviewOption) UnmarshalJSON 

func (g *GeneratePreviewOption) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes from either a boolean or a JSON object.

type HTMLOptions 

type HTMLOptions struct {
	// HTML is the base64-encoded HTML content. Required.
	// Use [EncodeHTML] to encode raw HTML strings.
	HTML string `json:"html"`
}

HTMLOptions configures HTML-based conversion input.

type HTMLToImageOptions 

type HTMLToImageOptions struct {
	HTMLOptions
	ImageOptions
	PuppeteerOptions
	BaseOptions
}

HTMLToImageOptions are options for Client.HTMLToImage.

type HTMLToPDFOptions 

type HTMLToPDFOptions struct {
	HTMLOptions
	PDFOptions
	PuppeteerOptions
	BaseOptions
}

HTMLToPDFOptions are options for Client.HTMLToPDF.

type HeaderFooterTemplate 

type HeaderFooterTemplate struct {
	Method         *string           `json:"method,omitempty"`
	Selector       *string           `json:"selector,omitempty"`
	Margin         *Margin           `json:"margin,omitempty"`
	Style          map[string]string `json:"style,omitempty"`
	ImageStyle     map[string]string `json:"imageStyle,omitempty"`
	Template       *string           `json:"template,omitempty"`
	TemplateString *string           `json:"templateString,omitempty"`
}

HeaderFooterTemplate configures a PDF header or footer.

type ImageOptions 

type ImageOptions struct {
	ImageType       *ImageType             `json:"imageType,omitempty"`
	Quality         *int                   `json:"quality,omitempty"`
	Trim            *bool                  `json:"trim,omitempty"`
	Transparent     *bool                  `json:"transparent,omitempty"`
	GeneratePreview *GeneratePreviewOption `json:"generatePreview,omitempty"`
}

ImageOptions configures image-specific output settings.

type ImageType 

type ImageType string

ImageType represents an output image format. 

const (
	ImagePNG  ImageType = "png"
	ImageJPEG ImageType = "jpeg"
	ImageJPG  ImageType = "jpg"
	ImageWebP ImageType = "webp"
	ImageSVG  ImageType = "svg"
)

Image format constants.

type Job 

type Job struct {
	ID              string          `json:"id"`
	UID             string          `json:"uid"`
	Name            *string         `json:"name,omitempty"`
	Type            *JobType        `json:"type,omitempty"`
	Status          JobStatus       `json:"status"`
	Timestamp       json.RawMessage `json:"timestamp,omitempty"`
	WorkerName      *string         `json:"workerName,omitempty"`
	ProcessTime     *int            `json:"processTime,omitempty"`
	APIKeyUsed      *string         `json:"apiKeyUsed,omitempty"`
	ProcessTimeCost *float64        `json:"processTimeCost,omitempty"`
	APICreditCost   *float64        `json:"apiCreditCost,omitempty"`
	BandwidthCost   *float64        `json:"bandwidthCost,omitempty"`
	TotalCost       *float64        `json:"totalCost,omitempty"`
	Size            *int            `json:"size,omitempty"`
	Params          json.RawMessage `json:"params,omitempty"`
	AssetURL        *string         `json:"assetUrl,omitempty"`
	PreviewURL      *string         `json:"previewUrl,omitempty"`
	Self            *string         `json:"self,omitempty"`
	AssetID         *string         `json:"assetId,omitempty"`
	ProjectID       *string         `json:"projectId,omitempty"`
	Error           *string         `json:"error,omitempty"`
}

Job represents a CloudLayer.io conversion job.

func (*Job) TimestampUnix 

func (j *Job) TimestampUnix() int64

TimestampUnix returns the job timestamp as Unix milliseconds. It handles both numeric timestamps and Firestore timestamp objects ({_seconds, _nanoseconds}).

type JobStatus 

type JobStatus string

JobStatus represents the status of a conversion job. 

const (
	JobPending JobStatus = "pending"
	JobSuccess JobStatus = "success"
	JobError   JobStatus = "error"
)

Job status constants.

type JobType 

type JobType string

JobType represents the type of a conversion job. 

const (
	JobHTMLPDF       JobType = "html-pdf"
	JobHTMLImage     JobType = "html-image"
	JobURLPDF        JobType = "url-pdf"
	JobURLImage      JobType = "url-image"
	JobTemplatePDF   JobType = "template-pdf"
	JobTemplateImage JobType = "template-image"
	JobDOCXPDF       JobType = "docx-pdf"
	JobDOCXHTML      JobType = "docx-html"
	JobImagePDF      JobType = "image-pdf"
	JobPDFImage      JobType = "pdf-image"
	JobPDFDOCX       JobType = "pdf-docx"
	JobPDFMerge      JobType = "merge-pdf"
)

Job type constants.

type LayoutDimension 

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

LayoutDimension represents a value that can be either a string (CSS units like "10in", "25cm") or an integer (pixels). Use NewLayoutDimensionString or NewLayoutDimensionInt to create values.

func NewLayoutDimensionInt 

func NewLayoutDimensionInt(n int) *LayoutDimension

NewLayoutDimensionInt creates a LayoutDimension from a pixel value.

func NewLayoutDimensionString 

func NewLayoutDimensionString(s string) *LayoutDimension

NewLayoutDimensionString creates a LayoutDimension from a CSS unit string (e.g., "10in", "25cm", "100px").

func (LayoutDimension) MarshalJSON 

func (d LayoutDimension) MarshalJSON() ([]byte, error)

MarshalJSON serializes the LayoutDimension as either a JSON string or number.

func (*LayoutDimension) UnmarshalJSON 

func (d *LayoutDimension) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes a JSON string or number into a LayoutDimension.

type ListTemplatesOptions 

type ListTemplatesOptions struct {
	Type     *string `json:"type,omitempty"`
	Category *string `json:"category,omitempty"`
	Tags     *string `json:"tags,omitempty"`
	Expand   *bool   `json:"expand,omitempty"`
}

ListTemplatesOptions are optional query parameters for Client.ListTemplates.

type Margin 

type Margin struct {
	Top    *LayoutDimension `json:"top,omitempty"`
	Right  *LayoutDimension `json:"right,omitempty"`
	Bottom *LayoutDimension `json:"bottom,omitempty"`
	Left   *LayoutDimension `json:"left,omitempty"`
}

Margin represents page margins with CSS units or pixel values.

type MergePDFsOptions 

type MergePDFsOptions struct {
	URLOptions
	BaseOptions
}

MergePDFsOptions are options for Client.MergePDFs. Merge uses URL-based input, not file uploads.

type NetworkError 

type NetworkError struct {
	Message       string
	Err           error
	RequestPath   string
	RequestMethod string
}

NetworkError is returned when a request fails due to a network-level problem (DNS resolution, connection refused, TLS errors, etc.).

func (*NetworkError) Error 

func (e *NetworkError) Error() string

func (*NetworkError) Unwrap 

func (e *NetworkError) Unwrap() error

Unwrap returns the underlying error for use with errors.Is and errors.As.

type NullableString 

type NullableString struct {
	Value  string
	IsNull bool
}

NullableString represents a three-state string value:

  • nil pointer: field is omitted from JSON (not set)
  • non-nil with IsNull=true: field serializes as JSON null
  • non-nil with IsNull=false: field serializes as the string value

This is needed for fields like emulateMediaType where null has distinct meaning from omission.

func EmulateNone 

func EmulateNone() *NullableString

EmulateNone creates a NullableString that serializes as JSON null, which disables media emulation.

func EmulatePrint 

func EmulatePrint() *NullableString

EmulatePrint creates a NullableString with value "print".

func EmulateScreen 

func EmulateScreen() *NullableString

EmulateScreen creates a NullableString with value "screen".

func (NullableString) MarshalJSON 

func (n NullableString) MarshalJSON() ([]byte, error)

MarshalJSON serializes the NullableString. Returns null for IsNull=true, or the quoted string value otherwise.

func (*NullableString) UnmarshalJSON 

func (n *NullableString) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes from a JSON string or null.

type PDFFormat 

type PDFFormat string

PDFFormat represents a PDF page size format. 

const (
	FormatLetter  PDFFormat = "letter"
	FormatLegal   PDFFormat = "legal"
	FormatTabloid PDFFormat = "tabloid"
	FormatLedger  PDFFormat = "ledger"
	FormatA0      PDFFormat = "a0"
	FormatA1      PDFFormat = "a1"
	FormatA2      PDFFormat = "a2"
	FormatA3      PDFFormat = "a3"
	FormatA4      PDFFormat = "a4"
	FormatA5      PDFFormat = "a5"
	FormatA6      PDFFormat = "a6"
)

PDF page size format constants.

type PDFOptions 

type PDFOptions struct {
	PrintBackground *bool                  `json:"printBackground,omitempty"`
	Format          *PDFFormat             `json:"format,omitempty"`
	Margin          *Margin                `json:"margin,omitempty"`
	HeaderTemplate  *HeaderFooterTemplate  `json:"headerTemplate,omitempty"`
	FooterTemplate  *HeaderFooterTemplate  `json:"footerTemplate,omitempty"`
	GeneratePreview *GeneratePreviewOption `json:"generatePreview,omitempty"`
}

PDFOptions configures PDF-specific output settings.

type PDFToDOCXOptions 

type PDFToDOCXOptions struct {
	File *FileInput `json:"-"`
	BaseOptions
}

PDFToDOCXOptions are options for Client.PDFToDOCX.

type PreviewOptions 

type PreviewOptions struct {
	Width               *int       `json:"width,omitempty"`
	Height              *int       `json:"height,omitempty"`
	Type                *ImageType `json:"type,omitempty"`
	Quality             int        `json:"quality"`
	MaintainAspectRatio *bool      `json:"maintainAspectRatio,omitempty"`
}

PreviewOptions configures preview image generation for a conversion.

type PublicTemplate 

type PublicTemplate struct {
	ID       string          `json:"id"`
	Name     *string         `json:"name,omitempty"`
	Type     *string         `json:"type,omitempty"`
	Category *string         `json:"category,omitempty"`
	Tags     *string         `json:"tags,omitempty"`
	Raw      json.RawMessage `json:"-"`
}

PublicTemplate represents a public template from the CloudLayer.io gallery.

func (*PublicTemplate) UnmarshalJSON 

func (t *PublicTemplate) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshaling for PublicTemplate. Known fields are extracted; the full raw JSON is preserved in Raw.

type PuppeteerOptions 

type PuppeteerOptions struct {
	WaitUntil              *WaitUntil              `json:"waitUntil,omitempty"`
	WaitForFrame           *bool                   `json:"waitForFrame,omitempty"`
	WaitForFrameAttachment *bool                   `json:"waitForFrameAttachment,omitempty"`
	WaitForFrameNavigation *WaitUntil              `json:"waitForFrameNavigation,omitempty"`
	WaitForFrameImages     *bool                   `json:"waitForFrameImages,omitempty"`
	WaitForFrameSelector   *WaitForSelectorOptions `json:"waitForFrameSelector,omitempty"`
	WaitForSelector        *WaitForSelectorOptions `json:"waitForSelector,omitempty"`
	PreferCSSPageSize      *bool                   `json:"preferCSSPageSize,omitempty"`
	Scale                  *float64                `json:"scale,omitempty"`
	Height                 *LayoutDimension        `json:"height,omitempty"`
	Width                  *LayoutDimension        `json:"width,omitempty"`
	Landscape              *bool                   `json:"landscape,omitempty"`
	PageRanges             *string                 `json:"pageRanges,omitempty"`
	AutoScroll             *bool                   `json:"autoScroll,omitempty"`
	ViewPort               *Viewport               `json:"viewPort,omitempty"`
	TimeZone               *string                 `json:"timeZone,omitempty"`
	EmulateMediaType       *NullableString         `json:"emulateMediaType,omitempty"`
}

PuppeteerOptions configures browser rendering behavior.

type RateLimitError 

type RateLimitError struct {
	APIError
	// RetryAfter is the number of seconds to wait before retrying, if provided
	// by the server. Nil if the header was not present.
	RetryAfter *int
}

RateLimitError is returned when the API rate limit is exceeded (HTTP 429).

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

type ResponseHeaders 

type ResponseHeaders struct {
	WorkerJobID     *string  `json:"cl-worker-job-id,omitempty"`
	ClusterID       *string  `json:"cl-cluster-id,omitempty"`
	Worker          *string  `json:"cl-worker,omitempty"`
	Bandwidth       *int     `json:"cl-bandwidth,omitempty"`
	ProcessTime     *int     `json:"cl-process-time,omitempty"`
	CallsRemaining  *int     `json:"cl-calls-remaining,omitempty"`
	ChargedTime     *int     `json:"cl-charged-time,omitempty"`
	BandwidthCost   *float64 `json:"cl-bandwidth-cost,omitempty"`
	ProcessTimeCost *float64 `json:"cl-process-time-cost,omitempty"`
	APICreditCost   *float64 `json:"cl-api-credit-cost,omitempty"`
}

ResponseHeaders contains parsed cl-* response headers from the CloudLayer.io API.

type StatusResponse 

type StatusResponse struct {
	Status string `json:"status"`
}

StatusResponse is returned by Client.GetStatus.

type StorageCreateResponse 

type StorageCreateResponse struct {
	Title string `json:"title"`
	ID    string `json:"id"`
}

StorageCreateResponse is returned by Client.AddStorage on success.

type StorageDetail 

type StorageDetail struct {
	Data  string `json:"data"`
	ID    string `json:"id"`
	Title string `json:"title"`
	UID   string `json:"uid"`
}

StorageDetail is returned by Client.GetStorage.

type StorageListItem 

type StorageListItem struct {
	ID    string `json:"id"`
	Title string `json:"title"`
}

StorageListItem is returned by Client.ListStorage. It contains only the ID and title — use Client.GetStorage for full details.

type StorageNotAllowedResponse 

type StorageNotAllowedResponse struct {
	Allowed    bool   `json:"allowed"`
	Reason     string `json:"reason"`
	StatusCode int    `json:"statusCode"`
}

StorageNotAllowedResponse is returned when the user's plan does not support custom storage. Note: this comes as HTTP 200, not an error status.

type StorageOption 

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

StorageOption represents a value that can be either a boolean or a storage configuration with an ID. Use NewStorageBool or NewStorageID to create values.

func NewStorageBool 

func NewStorageBool(b bool) *StorageOption

NewStorageBool creates a StorageOption from a boolean. Use true to enable default storage, false to disable.

func NewStorageID 

func NewStorageID(id string) *StorageOption

NewStorageID creates a StorageOption that targets a specific storage configuration by ID.

func (StorageOption) MarshalJSON 

func (s StorageOption) MarshalJSON() ([]byte, error)

MarshalJSON serializes as either true/false or {"id":"..."}.

func (*StorageOption) UnmarshalJSON 

func (s *StorageOption) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes from either a boolean or {"id":"..."}.

type StorageParams 

type StorageParams struct {
	Title           string  `json:"title"`
	Region          string  `json:"region"`
	AccessKeyID     string  `json:"accessKeyId"`
	SecretAccessKey string  `json:"secretAccessKey"`
	Bucket          string  `json:"bucket"`
	Endpoint        *string `json:"endpoint,omitempty"`
}

StorageParams are the parameters for Client.AddStorage.

type StorageRequestOptions 

type StorageRequestOptions struct {
	ID string `json:"id"`
}

StorageRequestOptions identifies a specific storage configuration by ID.

type TemplateOptions 

type TemplateOptions struct {
	TemplateID *string                `json:"templateId,omitempty"`
	Template   *string                `json:"template,omitempty"`
	Data       map[string]interface{} `json:"data,omitempty"`
}

TemplateOptions configures template-based conversion input. Note: the "name" field is provided by BaseOptions which is always embedded alongside TemplateOptions in composite types.

type TemplateToImageOptions 

type TemplateToImageOptions struct {
	TemplateOptions
	ImageOptions
	PuppeteerOptions
	BaseOptions
}

TemplateToImageOptions are options for Client.TemplateToImage.

type TemplateToPDFOptions 

type TemplateToPDFOptions struct {
	TemplateOptions
	PDFOptions
	PuppeteerOptions
	BaseOptions
}

TemplateToPDFOptions are options for Client.TemplateToPDF.

type TimeoutError 

type TimeoutError struct {
	// Timeout is the timeout in milliseconds.
	Timeout       int
	RequestPath   string
	RequestMethod string
}

TimeoutError is returned when a request times out due to the SDK's own timeout logic (not context cancellation — use errors.Is(err, context.Canceled) or errors.Is(err, context.DeadlineExceeded) for context errors).

func (*TimeoutError) Error 

func (e *TimeoutError) Error() string

type URLOptions 

type URLOptions struct {
	URL            *string         `json:"url,omitempty"`
	Authentication *Authentication `json:"authentication,omitempty"`
	Batch          *Batch          `json:"batch,omitempty"`
	Cookies        []Cookie        `json:"cookies,omitempty"`
}

URLOptions configures URL-based conversion input.

type URLToImageOptions 

type URLToImageOptions struct {
	URLOptions
	ImageOptions
	PuppeteerOptions
	BaseOptions
}

URLToImageOptions are options for Client.URLToImage.

type URLToPDFOptions 

type URLToPDFOptions struct {
	URLOptions
	PDFOptions
	PuppeteerOptions
	BaseOptions
}

URLToPDFOptions are options for Client.URLToPDF.

type ValidationError 

type ValidationError struct {
	Field   string
	Message string
}

ValidationError is returned when client-side input validation fails.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type Viewport 

type Viewport struct {
	Width             int     `json:"width"`
	Height            int     `json:"height"`
	DeviceScaleFactor float64 `json:"deviceScaleFactor,omitempty"`
	IsMobile          bool    `json:"isMobile,omitempty"`
	HasTouch          bool    `json:"hasTouch,omitempty"`
	IsLandscape       bool    `json:"isLandscape,omitempty"`
}

Viewport represents a browser viewport configuration. Note: the JSON field name is "viewPort" (capital P) to match the legacy API.

type WaitForSelectorOptions 

type WaitForSelectorOptions struct {
	Selector string                     `json:"selector"`
	Options  *WaitForSelectorSubOptions `json:"options,omitempty"`
}

WaitForSelectorOptions configures waiting for a DOM selector.

type WaitForSelectorSubOptions 

type WaitForSelectorSubOptions struct {
	Visible *bool `json:"visible,omitempty"`
	Hidden  *bool `json:"hidden,omitempty"`
	Timeout *int  `json:"timeout,omitempty"`
}

WaitForSelectorSubOptions are additional options for WaitForSelector.

type WaitOption 

type WaitOption func(*waitConfig)

WaitOption configures Client.WaitForJob behavior.

func WithMaxWait 

func WithMaxWait(d time.Duration) WaitOption

WithMaxWait sets the maximum time to wait for a job to complete. Default is 5 minutes.

func WithPollInterval 

func WithPollInterval(d time.Duration) WaitOption

WithPollInterval sets the polling interval for WaitForJob. Default is 5 seconds. Minimum is 2 seconds — values below 2s return a ValidationError.

type WaitUntil 

type WaitUntil string

WaitUntil represents a page load event to wait for. 

const (
	WaitLoad             WaitUntil = "load"
	WaitDOMContentLoaded WaitUntil = "domcontentloaded"
	WaitNetworkIdle0     WaitUntil = "networkidle0"
	WaitNetworkIdle2     WaitUntil = "networkidle2"
)

Page load event constants.

Source Files

View all Source files

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.