Go SDK

Official Go client for Refyne

The official Go SDK for Refyne with full context support.

Installation

go get github.com/jmylchreest/refyne-sdk-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    refyne "github.com/jmylchreest/refyne-sdk-go"
)

func main() {
    client := refyne.NewClient(os.Getenv("REFYNE_API_KEY"))

    result, err := client.Extract(context.Background(), refyne.ExtractRequest{
        URL: "https://example.com/product",
        Schema: map[string]any{
            "name":  "string",
            "price": "number",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Data: %+v\n", result.Data)
}

Configuration Options

Use functional options to customize the client:

client := refyne.NewClient(
    os.Getenv("REFYNE_API_KEY"),
    refyne.WithBaseURL("https://api.refyne.uk"),
    refyne.WithTimeout(60 * time.Second),
    refyne.WithMaxRetries(3),
    refyne.WithCacheEnabled(true),
)

Site Analysis

Analyze a website to discover structure and suggested schemas:

analysis, err := client.Analyze(ctx, refyne.AnalyzeRequest{
    URL:   "https://example.com/products",
    Depth: 1,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Suggested Schema: %+v\n", analysis.SuggestedSchema)
fmt.Printf("Follow Patterns: %+v\n", analysis.FollowPatterns)

// Use the analysis results for a crawl
job, err := client.Crawl(ctx, refyne.CrawlRequest{
    URL:    "https://example.com/products",
    Schema: analysis.SuggestedSchema,
    Options: &refyne.CrawlOptions{
        FollowSelector: strings.Join(analysis.FollowPatterns, ", "),
        MaxPages:       50,
    },
})

Crawling

// Start a crawl job
job, err := client.Crawl(ctx, refyne.CrawlRequest{
    URL: "https://example.com/products",
    Schema: map[string]any{
        "name":  "string",
        "price": "number",
    },
    Options: &refyne.CrawlOptions{
        FollowSelector: "a.product-link",
        MaxPages:       20,
    },
})
if err != nil {
    log.Fatal(err)
}

// Poll for completion
for {
    status, err := client.Jobs.Get(ctx, job.JobID)
    if err != nil {
        log.Fatal(err)
    }
    if status.Status == refyne.JobStatusCompleted {
        break
    }
    if status.Status == refyne.JobStatusFailed {
        log.Fatalf("Job failed: %s", status.ErrorMessage)
    }
    time.Sleep(2 * time.Second)
}

// Get results
results, err := client.Jobs.GetResults(ctx, job.JobID)
if err != nil {
    log.Fatal(err)
}

// Get merged results
merged, err := client.Jobs.GetResultsMerged(ctx, job.JobID)

Context Support

All methods accept a context for cancellation and timeouts:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := client.Extract(ctx, input)

Error Handling

result, err := client.Extract(ctx, input)
if err != nil {
    var apiErr *refyne.RefyneError
    if errors.As(err, &apiErr) {
        fmt.Printf("API error: %s (status %d)\n", apiErr.Message, apiErr.Status)
    }

    var rateLimitErr *refyne.RateLimitError
    if errors.As(err, &rateLimitErr) {
        fmt.Printf("Rate limited. Retry after %d seconds\n", rateLimitErr.RetryAfter)
    }

    var validationErr *refyne.ValidationError
    if errors.As(err, &validationErr) {
        fmt.Printf("Validation errors: %+v\n", validationErr.Errors)
    }

    return err
}

Sub-Services

The client provides sub-services for different operations:

// Jobs
jobs, err := client.Jobs.List(ctx)
job, err := client.Jobs.Get(ctx, "job-id")
results, err := client.Jobs.GetResults(ctx, "job-id")

// Schemas
schemas, err := client.Schemas.List(ctx)
schema, err := client.Schemas.Get(ctx, "schema-id")
schema, err := client.Schemas.Create(ctx, refyne.CreateSchemaRequest{...})

// Sites
sites, err := client.Sites.List(ctx)

// API Keys
keys, err := client.Keys.List(ctx)

// LLM Configuration
providers, err := client.LLM.ListProviders(ctx)
models, err := client.LLM.ListModels(ctx, "openai")

API Reference

For detailed documentation, see pkg.go.dev/github.com/jmylchreest/refyne-sdk-go.