In adeli-sdk, a GET Request That Never Retries

Adeli's TypeScript client writes its retry policy into a static per-route table, where cost and side effects beat HTTP semantics.

9 min read • View on GitHub • More from kingscrosslabs

A wide border checkpoint where an official at a wooden podium inspects queued vehicles against a thick rulebook, stamping one green and turning another back red while a closed gate blocks a third, with a coin meter beside the podium. The scene shows every request being judged against a written cost policy before it is allowed through.
Every request is inspected against a written policy before it moves. The policy is about cost and consequence, not which road the vehicle came in on.
Key Takeaways

The GET That Never Retries

Two routes from src/operations.ts. Same verb. Opposite retry policy.

listPosts: { method: 'GET', path: '/posts', retry: 'never' },
getMe:     { method: 'GET', path: '/me',    retry: 'safe-read' },

Every HTTP client you have used treats GET as the safe verb. It is idempotent, it has no side effects, so you retry it without a second thought. Adeli's SDK does the opposite for listPosts. It refuses.

The reason is a single comment in operations.ts: "Retry policy is deliberately conservative for provider writes and billed reads." listPosts is a billed read. Retrying it after a timeout does not just repeat a harmless query. It can bill you twice. So the SDK marks it never and moves on.

The same table encodes cost in the timeout too. createPost carries a five-minute default timeout because media processing is slow and expensive. createPublication is different: it is classified idempotent-write, which means it retries only when the caller hands it a non-blank idempotency key.

Notice what is missing. There is no generic retry: true, and there is no HTTP verb logic at all. The policy is a business decision written down per route, and the transport just reads it.

Retry as a Decision Tree, Not a Verb

src/core/retry.ts is small and built from pure functions. The vocabulary lives in src/core/types.ts as a four-part union: RetryClass = 'never' | 'safe-read' | 'profile-create' | 'idempotent-write'.

The whole policy is one predicate, canRetry(operation, idempotencyKey). Reads retry freely. Writes with a retry class retry only if the caller supplied a non-blank idempotency key. Everything else never retries.

Run a real route through the policy. Flip the idempotency key while createPublication is selected and watch the verdict change from STOP to retry, which is the exact reason createPublication and createPost are not the same route.

When a request is eligible, backoffMs decides how long to wait. A Retry-After header wins. Otherwise the delay is exponential, 250ms times 2 to the attempt number, capped at 30 seconds, with up to 100ms of jitter. The random source is injectable so tests can pin it.

Two exclusions show the philosophy more clearly than the rule. retryableNetworkError excludes RedirectError on purpose, because a retry could re-send credentials to a new host. And isDailyQuotaExhausted normalizes server codes (lowercase, hyphens and spaces to underscores) and matches several variants, because the API does not always return the same string for the same condition.

The Upload Path That Leaves the Key Behind

Media upload does not go through the normal request path. upload() sends bytes to a one-object presigned URL, and the doc comment states the goal: send the file "without leaking the Adeli API key."

A close-up of two hands: a left hand sealing and offering a plain paper envelope while a right hand, belonging to a courier, reaches to receive it. Between them a small locked drawer holds a single key that is visibly not being handed over, with a courier satchel at the frame edge. The scene shows bytes going to a third party while the credential stays locked on your side.
The bytes go to a third party. The credential stays locked in the drawer on your side of the counter.

The implementation follows through. The request carries no Authorization header at all. The headers argument comes from the caller and holds only the presigned URL's own headers. The API key never travels to a third-party storage host.

// upload() calls fetch with caller-supplied presigned headers only.
// No Authorization header is attached on this path.
await this.config.fetch(url, {
  method: 'PUT',
  body,
  headers,          // presigned URL headers, nothing else
  redirect: 'error',
  signal,
});

The redirect ban matters as much as the missing header. redirect: 'error' plus a response.redirected check means a redirect cannot silently move the body to a host you did not choose. A credential-free upload is still an upload you want to land where you aimed it.

Guardrails That Fire Before the Network

Three small decisions show the same discipline, and all three fire before a socket opens.

One small leak survives in the public surface: getMe()'s doc comment points at apps/web/lib/public-api/me.ts, an internal monorepo path that came along when the SDK was extracted from the larger codebase.

An Error Hierarchy That Admits What It Doesn't Know

The error tree is typed and shallow, and two of its decisions are more interesting than its shape.

AdeliError
├── ConfigurationError
├── NetworkError → RedirectError
├── TimeoutError
├── CancellationError
├── MalformedResponseError
└── AdeliApiError (status, code, details, headers)
    ├── AuthenticationError
    ├── ValidationError
    ├── RateLimitError
    └── PermissionRequiredError

The first decision is that classification follows documented API codes, not status classes. The comment in apiError() says it plainly: "Classify documented API codes, not broad status classes with unrelated semantics." Status 401 with code unauthorized becomes an AuthenticationError, and permission_required becomes a PermissionRequiredError. Lumping every 4xx into one bucket would erase the difference between "your key is wrong" and "this account needs to reconnect."

The second decision is honesty about limits. TimeoutError's doc comment says: "A timeout only cancels this client request; a write may still have completed remotely." For a publishing client that is the single most important sentence in the file. A timed-out post may already be live, and a developer who assumes otherwise will double-post.

isPermissionRequiredDetails is the same kind of honesty in a type guard. It validates shape, restricts reconnect.action to 'restart_oauth', and its comment notes it is "not normalization or proof that a URL is safe to follow." It checks the object. It does not vouch for the link.

Where It Fits

Adeli publishes comparison pages against Ayrshare, Upload-Post, Zernio (formerly Late), and Buffer API, and against calling Meta, TikTok, and YouTube directly. Everything below comes from those vendor-authored pages, not from independent benchmarks. Treat the pricing as a claim, not a measurement.

ModelBilling unitRetry philosophy in the clientNotable tradeoff
@adeli/sdkUnified hosted API plus official TypeScript clientPer profile (customer)Encoded per route in a static table, based on cost and side effectsYou depend on Adeli's supported operations and normalized contract
AyrshareComparable hosted social APIPer profile, per Adeli's comparisonNot described as shipping a per-route cost tableAdeli claims a lower price floor; unverified
Buffer APIOperates on Buffer accounts and channelsPer channel, per Adeli's comparisonNot described as shipping a per-route cost tableDifferent product shape, aimed at Buffer users rather than end-user-connected accounts
Zernio (formerly Late)Comparable API productPer account, per Adeli's comparisonNot described as shipping a per-route cost tablePricing claim is Adeli's own; unverified
Direct provider APIs (Meta Graph, TikTok, YouTube Data)No intermediaryNo per-profile feeYou own the decision entirelyMaximum control, maximum maintenance: OAuth, token refresh, rate limits, every provider quirk

The interesting column is not price. It is shape. Adeli bills per profile, where a profile is a customer workspace, rather than per channel. Its SDK exposes provider-specific statuses and fields instead of hiding them behind a lowest common denominator. The unified surface still has platform-shaped holes: YouTube has no messaging API, so no amount of normalization fills that in.

The thing the table cannot show is the retry table. None of the alternatives in this list are described as shipping a per-route cost policy in their clients. That is the actual differentiator, and it lives in one file.

What Adeli Actually Is

Adeli is a hosted unified social and ads API. One key and one client reach profiles, OAuth connection sessions, publishing, comments, messages, analytics, ads, and webhooks across TikTok, Instagram, Facebook, YouTube, X, Bluesky, and LinkedIn.

The SDK is @adeli/sdk, server-side only, documented for Node.js 22+, Vercel functions, and Cloudflare Workers. Resource calls take explicit { path, query, body } inputs and return { data, status, headers }. Helpers add polling, comment iterators, and webhook verification.

The docs warn that publishing can return accepted or partial results, including 202 and 207, and that callers should inspect results rather than blindly retry writes. That warning and the retry table say the same thing in two places: a write is not a read, and only one of them is free.