Linkit
SDK Reference

Go SDK

High-performance Go SDK for the Linkit API — context.Context, functional options, net/http, zero dependencies.

Go SDK

Zero Dependencies

Pure net/http + encoding/json + context.Context. Go 1.22+. No third-party imports.


Installation

go get github.com/linkit-sa/linkit-go-sdk@latest

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    linkit "github.com/linkit-sa/linkit-go-sdk"
)

func main() {
    client, err := linkit.QuickSetup("https://linkit.works/api/v1", "your-jwt-token")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // List products
    products, err := client.Products.List(ctx, &linkit.ProductListRequest{
        Page: 1, Limit: 20,
    })
    if err != nil {
        log.Fatal(err)
    }
    for _, p := range products.Data {
        fmt.Printf("%s: %s\n", p.IvID, p.NameEn)
    }
}

Configuration

client, err := linkit.New("https://linkit.works/api/v1",
    linkit.WithJWTToken("your-jwt-token"),
    linkit.WithTimeout(45 * time.Second),
    linkit.WithMaxRetries(5),
    linkit.WithMaxConcurrent(20),
    linkit.WithRetryDelay(100*time.Millisecond, 30*time.Second),
    linkit.WithCircuitBreaker(10, 30*time.Second),
    linkit.WithUserAgent("my-app/1.0"),
    linkit.WithHeader("X-Custom", "value"),
)
OptionDefaultDescription
WithTimeout30sHTTP request timeout
WithMaxConcurrent10Rate limiter permits
WithMaxRetries3Retry attempts for 5xx/429
WithRetryDelay200ms / 10sBase/max backoff
WithCircuitBreaker5 / 60sThreshold/recovery

Services Reference (11 Services)

ServiceMethodsDescription
client.ProductsCreate, GetByIvID, Update, Delete, ListProduct catalog
client.SKUsCreate, GetByIvID, Update, Delete, ListSKU / inventory
client.BranchesCreate, GetByIvID, Update, Delete, ListLocations
client.CustomersCreate, GetByID, Update, Delete, List, LookupByEmail, LookupByPhone, Search, GetAddresses, CreateAddress, UpdateAddress, DeleteAddress, GetGroups, CreateGroup, UpdateGroup, DeleteGroupCustomers
client.OrdersGetByID, List, UpdateStatusOrders
client.OffersCreate, GetByID, Update, UpdateStatus, Delete, List, BulkUpsertOffers
client.BrandsCreate, GetByID, Update, Delete, ListBrands
client.CategoriesCreate, GetByID, Update, Delete, ListCategories
client.GenericsCreate, GetByID, Update, Delete, ListGenerics
client.IntegrationsList, GetByID, GetConfig, ExecuteIntegrations
client.HealthCheck, DetailedHealth

Products

ctx := context.Background()

// Create
product, err := client.Products.Create(ctx, &linkit.ProductRequest{
    IvID: "P-001", NameEn: "Aspirin 500mg", NameAr: "أسبرين",
})

// List with filters
enabled := true
products, err := client.Products.List(ctx, &linkit.ProductListRequest{
    Page: 1, Limit: 20, Search: "aspirin", Enabled: &enabled,
})

// Update
updated, err := client.Products.Update(ctx, "P-001", &linkit.ProductRequest{
    IvID: "P-001", NameEn: "Aspirin 500mg Updated",
})

// Delete
err = client.Products.Delete(ctx, "P-001")

Customers

// Create
customer, err := client.Customers.Create(ctx, &linkit.CustomerRequest{
    FirstName: "Ahmad", LastName: "Ali",
    Email: "ahmad@company.sa", Phone: "+966512345678",
    Status: "active", Type: "individual",
})

// Lookup (returns nil, nil if not found)
found, err := client.Customers.LookupByEmail(ctx, "ahmad@company.sa")

// Addresses
addr, err := client.Customers.CreateAddress(ctx, customer.ID, &linkit.AddressRequest{
    Label: "Home", Line1: "123 King Rd", City: "Riyadh", Country: "SA",
})

// Groups
group, err := client.Customers.CreateGroup(ctx, &linkit.CustomerGroupRequest{
    Name: "VIP Customers",
})

Offers

// Create
offer, err := client.Offers.Create(ctx, &linkit.OfferRequest{
    Name: "Weekend 15%", OfferType: "direct_discount",
    Status: "active", TargetScope: "product",
    TargetIvID: "P-001", DiscountType: "percentage", DiscountValue: 15.0,
})

// Bulk upsert
bulk, err := client.Offers.BulkUpsert(ctx, []linkit.OfferRequest{
    {Name: "BOGO", OfferType: "bogo", BuyQty: 1, GetQty: 1},
    {Name: "Bundle", OfferType: "bundle_deal"},
})
fmt.Printf("Processed: %d\n", bulk.Data.Processed)

Error Handling

product, err := client.Products.GetByIvID(ctx, "INVALID")
if err != nil {
    if linkit.IsNotFound(err) {
        fmt.Println("Product not found")
    } else if linkit.IsRateLimited(err) {
        fmt.Println("Rate limited")
    } else if linkit.IsCircuitOpen(err) {
        fmt.Println("Circuit breaker open")
    } else {
        fmt.Printf("Error: %v\n", err)
    }
}

Architecture

  • net/http — Standard library HTTP client, no third-party deps
  • context.Context — Every method takes ctx for cancellation/timeout
  • Functional optionsWithTimeout(), WithMaxRetries(), etc.
  • Mutex circuit breaker — Thread-safe via sync.Mutex
  • Channel rate limiter — Buffered channel semaphore
  • Exponential backoff — With random jitter for thundering herd prevention