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@latestQuick 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"),
)| Option | Default | Description |
|---|---|---|
WithTimeout | 30s | HTTP request timeout |
WithMaxConcurrent | 10 | Rate limiter permits |
WithMaxRetries | 3 | Retry attempts for 5xx/429 |
WithRetryDelay | 200ms / 10s | Base/max backoff |
WithCircuitBreaker | 5 / 60s | Threshold/recovery |
Services Reference (11 Services)
| Service | Methods | Description |
|---|---|---|
client.Products | Create, GetByIvID, Update, Delete, List | Product catalog |
client.SKUs | Create, GetByIvID, Update, Delete, List | SKU / inventory |
client.Branches | Create, GetByIvID, Update, Delete, List | Locations |
client.Customers | Create, GetByID, Update, Delete, List, LookupByEmail, LookupByPhone, Search, GetAddresses, CreateAddress, UpdateAddress, DeleteAddress, GetGroups, CreateGroup, UpdateGroup, DeleteGroup | Customers |
client.Orders | GetByID, List, UpdateStatus | Orders |
client.Offers | Create, GetByID, Update, UpdateStatus, Delete, List, BulkUpsert | Offers |
client.Brands | Create, GetByID, Update, Delete, List | Brands |
client.Categories | Create, GetByID, Update, Delete, List | Categories |
client.Generics | Create, GetByID, Update, Delete, List | Generics |
client.Integrations | List, GetByID, GetConfig, Execute | Integrations |
client.Health | Check, Detailed | Health |
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 depscontext.Context— Every method takesctxfor cancellation/timeout- Functional options —
WithTimeout(),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