Operations

Configure timeouts, retries, concurrency, rate limits, provider charges, diagnostics, and safe server boundaries.

Social SDK performs only the work an application explicitly requests. It does not start polling, queues, timers, telemetry, or background network requests at import time.

Request controls

Every facade call accepts { signal, authorization, retryBudget }. The default retry budget is { maxAttempts: 1, maxElapsedMs: 30000 }: one attempt, and at most 30 seconds for all transport requests made under one operation.

• maxAttempts applies to reads only. The shared HTTP transport accepts at most five attempts for GET and HEAD, and adapters cap it further (the Bluesky adapter uses at most three). It retries network errors, 429, and 5xx responses with backoff and honors Retry-After. Writes are always sent once.
• maxElapsedMs is shared by the sequential requests of one operation in the adapters that read it (X, YouTube, LinkedIn, Bluesky, and the managed backends). Once it runs out, the next request fails with timeout before dispatch. Each HTTP transport also has its own per-request ceiling, 30 seconds by default, which applies on every route.
• YouTube video uploads are the exception: the resumable upload gets at least 15 minutes, or the remaining budget when that is longer.

A timeout or cancellation after dispatch is an unknown outcome until the backend is reconciled. Do not treat elapsed time as proof that no public post exists. See idempotency.

Cost and limits

The package does not bill or proxy usage. Platform and managed-provider plans may charge separately, and each provider or platform can apply quotas or rate limits. A rate-limited call fails with rate_limited. When the adapter maps the provider’s Retry-After value, retryDisposition is after-delay with that delay; otherwise wait before retrying on your own schedule.

Diagnostics

Diagnostics should be explicit, read-only, and redact secrets, tokens, media, message bodies, and account credentials. For each failure, log the SocialError fields code, operation, correlationId, upstreamStatus, upstreamCode, and retryDisposition. SocialError does not carry provider request IDs.

social.capabilities() returns each adapter’s static manifest. It is local and makes no request. Before dispatch, the client checks the operation against that manifest; it does not probe the backend, the account’s scopes, or its eligibility. Account-specific problems surface when the provider rejects the call.

Route webhook payloads

Verify the exact raw bytes before decoding an event. Zernio uses a body HMAC. Post for Me uses a shared secret header, which does not authenticate the body itself. Use the verifier for the configured backend rather than trying both schemes.

acceptWebhook resolves each account ID against application-owned tenant mappings. It delivers the full event only to tenants authorized for every account in that payload. An unknown account, no account IDs, or accounts belonging to unrelated tenants quarantines the event. Resolving the union of known accounts is unsafe because it can expose another account’s data.

Persist inbox acceptance before acknowledging delivery. Duplicate acceptance does not mean that a worker has applied the event. Keep worker completion separate so a restarted worker can recover pending records.

Operation guides: reads and analytics, comments and messaging, and events.

Bound overlapping work

createSocial({ concurrency: 4, maxQueued: 100, ... }) gives each configured backend instance four active operation slots and at most 100 queued operations. Those are the defaults. Reads, uploads, publishing, comments, messages, and lifecycle mutations share that backend’s slots. Another backend can proceed independently.

When the queue is full, the result depends on the call:

• posts.publish does not throw. The affected target gets a not-submitted outcome with reason capacity, and a target whose signal aborts while queued gets cancelled with reason before-submission. Other targets keep their own outcomes.
• Every other facade call throws rate_limited before adapter I/O, or cancelled when its signal aborts while queued.

These limits govern this client instance. Raw adapter and native access bypass them, and separate client instances do not coordinate quotas. Time spent in the queue does not count against retryBudget.maxElapsedMs, which starts at the first transport request. Persist application jobs explicitly if work must survive process restarts.