Client Configuration

NewClient constructs the SDK client and attaches all available services. It defaults to the SocialKit API base URL, a 30-second HTTP timeout, one total attempt per request, and the SocialKit-Go-SDK/1.0.0 user-agent. A client is documented as safe for concurrent use by multiple goroutines. 1

Create a client

client := socialkit.NewClient(os.Getenv("SOCIALKIT_ACCESS_KEY"))

Options are applied in the order supplied to NewClient. A production service will normally set an explicit timeout and may add retries only after considering whether its operations are safe to repeat. 1 2

client := socialkit.NewClient(
    os.Getenv("SOCIALKIT_ACCESS_KEY"),
    socialkit.WithTimeout(20*time.Second),
    socialkit.WithRetry(3, 500*time.Millisecond),
    socialkit.WithUserAgent("acme-ingestion/1.2"),
)

Configuration options

Option	Effect	Notes
WithBaseURL(url)	Replaces the API base URL.	Trailing slashes are removed. This is especially useful for tests with an httptest server.
WithHTTPClient(client)	Replaces the underlying *http.Client.	Use this for proxies, mTLS, custom transports, or connection management. A nil client is ignored.
WithTimeout(d)	Sets the underlying HTTP client timeout.	A duration less than or equal to zero is ignored. Default: 30 seconds.
WithRetry(maxAttempts, baseDelay)	Enables and configures retries.	Attempts include the initial call; defaults are one attempt and a 500 ms base delay.
WithKeyInQuery(enabled)	Adds legacy access_key auth to GET query strings or POST JSON bodies.	The header is still sent. Prefer the default header-only mode.
WithUserAgent(ua)	Replaces the User-Agent header.	An empty value is ignored.

The code below demonstrates a custom transport while retaining SDK authentication and decoding behavior.

transport := &http.Transport{
    MaxIdleConns:        100,
    MaxIdleConnsPerHost: 10,
    IdleConnTimeout:     90 * time.Second,
}

httpClient := &http.Client{
    Transport: transport,
    Timeout:   20 * time.Second,
}

client := socialkit.NewClient(
    os.Getenv("SOCIALKIT_ACCESS_KEY"),
    socialkit.WithHTTPClient(httpClient),
    socialkit.WithUserAgent("acme-ingestion/1.2"),
)

Authentication

By default, the SDK places your supplied key in the x-access-key request header. This matches SocialKit’s recommended authentication mechanism and keeps the secret out of the URL and JSON request payload. 1 3

Use header authentication in normal applications. Query strings can be preserved in logs, browser history, referrer headers, monitoring products, and cache keys. Enable query/body compatibility only when an existing integration explicitly needs it.

// Default: x-access-key header only.
client := socialkit.NewClient(key)

// Compatibility mode: adds access_key to GET queries or POST JSON.
client = socialkit.NewClient(key, socialkit.WithKeyInQuery(true))

The SDK automatically redacts credential-like fields and the configured key from response metadata and errors. This is a defence-in-depth measure, not a replacement for sound application secret-handling practices. 4

Context and time budgets

Each operation takes a context.Context. Use a request-scoped deadline in addition to the HTTP timeout; the first cancellation or deadline to fire ends the request. The SDK returns the context error if the context is already cancelled or expires during the retry wait. 4

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

stats, meta, err := client.YouTube.Stats(ctx, &socialkit.FetchRequest{
    URL: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
})
if err != nil {
    return err
}
_ = stats
_ = meta

For worker queues, create a context per unit of work rather than using context.Background() throughout the application. This makes shutdown and stuck-work recovery predictable.

Retries and idempotency

Retries are disabled until you call WithRetry. With retries enabled, the SDK retries transport errors and HTTP 429, 500, 502, 503, and 504 responses. It honours a valid Retry-After value; otherwise it calculates exponential delay from baseDelay and adds up to 25% jitter. 2 4

Request condition	Default SDK behavior	With WithRetry(…)
Network/transport error	Return ErrTransport.	Retry while attempts remain.
429 or retryable 5xx	Return typed API error.	Retry while attempts remain.
400, 401, 403, 404	Return typed API error.	Never retry.
POST endpoint	One attempt.	Retried only because you explicitly opted in.

A retry can repeat a billable operation. Before enabling it for a POST workflow, decide whether the operation is idempotent for your use case, whether you can deduplicate results, and whether a repeated API call is acceptable.

Testing against a mock server

WithBaseURL lets you redirect requests to httptest.Server without modifying production code.

server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    if r.Header.Get("x-access-key") != "test-key" {
        http.Error(w, `{"message":"invalid key"}`, http.StatusForbidden)
        return
    }
    w.Header().Set("Content-Type", "application/json")
    _, _ = w.Write([]byte(`{"success":true,"data":{"overall":"ok"}}`))
}))
defer server.Close()

client := socialkit.NewClient("test-key", socialkit.WithBaseURL(server.URL))
status, _, err := client.Status.Get(context.Background())

The public repository’s test suite follows this pattern and does not require a real access key or network access. 5

References