# DocFast Go SDK

Official Go client for the [DocFast](https://docfast.dev) HTML/Markdown to PDF API.

## Installation

```bash
go get github.com/docfast/docfast-go
```

## Quick Start

```go
package main

import (
	"os"
	docfast "github.com/docfast/docfast-go"
)

func main() {
	client := docfast.New("df_pro_your_api_key")

	// HTML to PDF
	pdf, err := client.HTML("<h1>Hello World</h1><p>Generated with DocFast</p>", nil)
	if err != nil {
		panic(err)
	}
	os.WriteFile("output.pdf", pdf, 0644)
}
```

## Usage

### HTML to PDF

```go
pdf, err := client.HTML("<h1>Hello</h1>", &docfast.PDFOptions{
	Format:    "A4",
	Landscape: true,
	Margin:    &docfast.Margin{Top: "20mm", Bottom: "20mm"},
})
```

### HTML with custom CSS

```go
pdf, err := client.HTMLWithCSS(
	"<h1>Styled</h1>",
	"h1 { color: navy; font-family: Georgia; }",
	nil,
)
```

### Markdown to PDF

```go
pdf, err := client.Markdown("# Report\n\nGenerated **automatically**.", nil)
```

### URL to PDF

```go
pdf, err := client.URL("https://example.com", &docfast.PDFOptions{
	Format:          "Letter",
	PrintBackground: docfast.Bool(true),
})
```

### Headers and Footers

```go
pdf, err := client.HTML(html, &docfast.PDFOptions{
	DisplayHeaderFooter: true,
	HeaderTemplate:      `<div style="font-size:10px;text-align:center;width:100%">My Document</div>`,
	FooterTemplate:      `<div style="font-size:10px;text-align:center;width:100%">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>`,
	Margin:              &docfast.Margin{Top: "40mm", Bottom: "20mm"},
})
```

### Custom Page Size

```go
pdf, err := client.HTML(html, &docfast.PDFOptions{
	Width:  "8.5in",
	Height: "11in",
	Scale:  0.8,
})
```

### Templates

```go
// List available templates
templates, err := client.Templates()

// Render a template
pdf, err := client.RenderTemplate("invoice", map[string]interface{}{
	"company":  "Acme Corp",
	"items":    []map[string]interface{}{{"name": "Widget", "price": 9.99}},
	"_format":  "A4",
})
```

## PDF Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `Format` | string | `"A4"` | Page size: A4, Letter, Legal, A3, A5, Tabloid |
| `Landscape` | bool | `false` | Landscape orientation |
| `Margin` | *Margin | `nil` | Page margins (CSS units) |
| `PrintBackground` | *bool | `true` | Print background graphics |
| `Filename` | string | `""` | Suggested filename |
| `HeaderTemplate` | string | `""` | HTML header template |
| `FooterTemplate` | string | `""` | HTML footer template |
| `DisplayHeaderFooter` | bool | `false` | Show header/footer |
| `Scale` | float64 | `1` | Rendering scale (0.1–2.0) |
| `PageRanges` | string | `""` | Pages to print (e.g. "1-3,5") |
| `PreferCSSPageSize` | bool | `false` | Prefer CSS @page size |
| `Width` | string | `""` | Custom paper width |
| `Height` | string | `""` | Custom paper height |

## Error Handling

```go
pdf, err := client.HTML("<h1>Test</h1>", nil)
if err != nil {
	var apiErr *docfast.Error
	if errors.As(err, &apiErr) {
		fmt.Printf("API error: %s (status %d)\n", apiErr.Message, apiErr.StatusCode)
	}
}
```

## Configuration

```go
// Custom base URL (e.g. for self-hosted or staging)
client := docfast.New("key", docfast.WithBaseURL("https://staging.docfast.dev"))

// Custom HTTP client
client := docfast.New("key", docfast.WithHTTPClient(&http.Client{
	Timeout: 120 * time.Second,
}))
```

## Links

- [Documentation](https://docfast.dev/docs)
- [API Reference](https://docfast.dev/openapi.json)
- [Get an API Key](https://docfast.dev)