tredi-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,798 @@
+/**
+ * Logging hooks. The SDK never writes to the console itself; it calls the
+ * injected logger so the host app controls transport and level. The SDK's own
+ * log calls (in `http.ts`) only ever include a redacted URL — never raw
+ * request params or the access token — via {@link redactUrl}.
+ *
+ * {@link redactParams} is exported as a standalone utility for host apps that
+ * build a custom logger and want to log request params (not just the URL)
+ * safely; the SDK itself doesn't need it since it never logs params.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LogContext {
+    [key: string]: unknown;
+}
+interface Logger {
+    /**
+     * Receives a structured log event. Implementations must be non-throwing and
+     * fast; the SDK calls this synchronously on the request path.
+     */
+    log(level: LogLevel, message: string, context?: LogContext): void;
+}
+/** Discards all logs. Default when no logger is configured. */
+declare const noopLogger: Logger;
+/**
+ * Returns a copy of `params` with sensitive values masked. Non-sensitive
+ * values are preserved so logs stay useful for debugging.
+ */
+declare function redactParams(params: Record<string, unknown> | undefined): Record<string, unknown>;
+/**
+ * Masks sensitive query-string values in a URL. Falsy/relative inputs are
+ * returned with a best-effort regex redaction so we never throw on the log
+ * path.
+ */
+declare function redactUrl(url: string): string;
+
+/**
+ * The single HTTP engine used by both the client and the OAuth helpers.
+ *
+ * Responsibilities: build the request, enforce a timeout, send via the injected
+ * `fetch`, parse the response, map failures to typed errors, retry idempotent
+ * failures with exponential backoff + jitter, and emit redacted logs.
+ *
+ * Retry safety: non-idempotent (POST) requests are only retried when the server
+ * never processed them (HTTP 429) or no response was received (network error).
+ * A POST timeout or 5xx is *not* retried — it may have already taken effect
+ * (e.g. a published post), and re-sending could duplicate it.
+ */
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+type HttpMethod = 'GET' | 'POST' | 'DELETE';
+interface RetryConfig {
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffFactor: number;
+}
+
+/**
+ * Shared contract between the client and its resource modules. Resources depend
+ * only on this narrow interface (not the concrete `ThreadsClient`), which keeps
+ * the dependency graph acyclic and makes resources trivial to unit test.
+ */
+
+interface ResourceRequest {
+    method: HttpMethod;
+    /** Path appended after the version segment, e.g. `/me/threads`. */
+    path: string;
+    params?: Record<string, unknown>;
+    /** Optional per-call cancellation. */
+    signal?: AbortSignal;
+}
+interface ThreadsRequester {
+    /** Default node id for user-scoped endpoints (the configured user, or `me`). */
+    readonly userNode: string;
+    request<T>(req: ResourceRequest): Promise<T>;
+}
+
+/**
+ * Public API types. Field names mirror the Threads API exactly (snake_case);
+ * all object fields are optional because the API only returns the fields you
+ * request via `fields=`. Enum unions list only documented values.
+ */
+/** `media_type` accepted when creating a publish container. */
+type MediaContainerType = 'TEXT' | 'IMAGE' | 'VIDEO' | 'CAROUSEL';
+/** `media_type` returned when reading a media object (differs from input). */
+type MediaType = 'TEXT_POST' | 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM' | 'AUDIO' | 'REPOST_FACADE';
+/** Who is allowed to reply to a post. */
+type ReplyControl = 'everyone' | 'accounts_you_follow' | 'mentioned_only' | 'parent_post_author_only' | 'followers_only';
+/** Lifecycle status of a publish container. */
+type ContainerStatus = 'EXPIRED' | 'ERROR' | 'FINISHED' | 'IN_PROGRESS' | 'PUBLISHED';
+/** Generic cursor-paginated list response. */
+interface Paginated<T> {
+    data: T[];
+    paging?: {
+        cursors?: {
+            before?: string;
+            after?: string;
+        };
+        next?: string;
+        previous?: string;
+    };
+}
+/** A Threads user profile. */
+interface ThreadsProfile {
+    id?: string;
+    username?: string;
+    name?: string;
+    threads_profile_picture_url?: string;
+    threads_biography?: string;
+    is_verified?: boolean;
+}
+/** A Threads media object (post). */
+interface ThreadsMedia {
+    id?: string;
+    media_product_type?: string;
+    media_type?: MediaType;
+    media_url?: string;
+    permalink?: string;
+    owner?: {
+        id: string;
+    };
+    username?: string;
+    text?: string;
+    /** ISO 8601 timestamp. */
+    timestamp?: string;
+    shortcode?: string;
+    thumbnail_url?: string;
+    children?: {
+        data: ThreadsMedia[];
+    };
+    is_quote_post?: boolean;
+    quoted_post?: ThreadsMedia;
+    reposted_post?: ThreadsMedia;
+    alt_text?: string;
+    link_attachment_url?: string;
+    gif_url?: string;
+    topic_tag?: string;
+    is_verified?: boolean;
+    profile_picture_url?: string;
+}
+/** A reply object. Shares most fields with media plus reply-specific ones. */
+interface ThreadsReply {
+    id?: string;
+    text?: string;
+    timestamp?: string;
+    media_product_type?: string;
+    media_type?: MediaType;
+    media_url?: string;
+    shortcode?: string;
+    thumbnail_url?: string;
+    children?: {
+        data: ThreadsReply[];
+    };
+    has_replies?: boolean;
+    root_post?: {
+        id: string;
+    };
+    replied_to?: {
+        id: string;
+    };
+    is_reply?: boolean;
+    username?: string;
+    permalink?: string;
+    /** Whether the reply is currently hidden. */
+    hide_status?: 'NOT_HUSHED' | 'UNHUSHED' | 'HIDDEN' | 'COVERED' | 'BLOCKED' | 'RESTRICTED';
+    reply_audience?: string;
+}
+/** One metric value in an insights response. */
+interface InsightMetric {
+    name: string;
+    period?: string;
+    title?: string;
+    description?: string;
+    /** Present for "total value" metrics. */
+    total_value?: {
+        value: number;
+    };
+    /** Present for "time series" metrics. */
+    values?: {
+        value: number;
+        end_time?: string;
+    }[];
+    id?: string;
+}
+interface InsightsResponse {
+    data: InsightMetric[];
+    paging?: {
+        previous?: string;
+        next?: string;
+    };
+}
+/** A single quota bucket from the publishing-limit endpoint. */
+interface QuotaBucket {
+    quota_usage?: number;
+    config?: {
+        quota_total?: number;
+        quota_duration?: number;
+    };
+}
+/** Response of `GET /{user}/threads_publishing_limit`. */
+interface PublishingLimit {
+    quota_usage?: number;
+    config?: {
+        quota_total?: number;
+        quota_duration?: number;
+    };
+    reply_quota_usage?: number;
+    reply_config?: {
+        quota_total?: number;
+        quota_duration?: number;
+    };
+    delete_quota_usage?: number;
+    delete_config?: {
+        quota_total?: number;
+        quota_duration?: number;
+    };
+    location_search_quota_usage?: number;
+    location_search_config?: {
+        quota_total?: number;
+        quota_duration?: number;
+    };
+}
+/** Result of creating or publishing a container. */
+interface ContainerRef {
+    id: string;
+}
+/** `{ "success": true }` responses from moderation endpoints. */
+interface SuccessResponse {
+    success: boolean;
+}
+
+/** Insights — `GET /{media-id}/insights` and `GET /{user-id}/threads_insights`. */
+
+/** Documented media-level metrics. */
+type MediaMetric = 'views' | 'likes' | 'replies' | 'reposts' | 'quotes' | 'shares';
+/** Documented user-level metrics. */
+type UserMetric = 'views' | 'likes' | 'replies' | 'reposts' | 'quotes' | 'clicks' | 'followers_count' | 'follower_demographics';
+/** Breakdown dimension for `follower_demographics`. */
+type DemographicBreakdown = 'country' | 'city' | 'age' | 'gender';
+interface MediaInsightsOptions {
+    metrics?: MediaMetric[];
+    signal?: AbortSignal;
+}
+interface UserInsightsOptions {
+    userId?: string;
+    metrics?: UserMetric[];
+    since?: number | Date;
+    until?: number | Date;
+    /** Required by the API when requesting `follower_demographics`. */
+    breakdown?: DemographicBreakdown;
+    signal?: AbortSignal;
+}
+declare class InsightsResource {
+    private readonly client;
+    constructor(client: ThreadsRequester);
+    /**
+     * Returns engagement metrics for a single post.
+     * Requires the `threads_manage_insights` permission.
+     */
+    media(mediaId: string, options?: MediaInsightsOptions): Promise<InsightsResponse>;
+    /**
+     * Returns account-level metrics for a user.
+     * Requires the `threads_manage_insights` permission.
+     */
+    user(options?: UserInsightsOptions): Promise<InsightsResponse>;
+}
+
+/** Mentions — `GET /{user-id}/mentions`. */
+
+interface ListMentionsOptions {
+    userId?: string;
+    fields?: string[];
+    since?: number | Date;
+    until?: number | Date;
+    limit?: number;
+    before?: string;
+    after?: string;
+    signal?: AbortSignal;
+}
+declare class MentionsResource {
+    private readonly client;
+    constructor(client: ThreadsRequester);
+    /**
+     * Lists posts that mention the user. Requires the mentions permission in
+     * addition to `threads_basic`.
+     */
+    list(options?: ListMentionsOptions): Promise<Paginated<ThreadsMedia>>;
+}
+
+/** Retrieve & discover posts — `GET /{user-id}/threads` and `GET /{media-id}`. */
+
+interface ListPostsOptions {
+    /** User id to list; defaults to the configured user (or `me`). */
+    userId?: string;
+    fields?: string[];
+    /** Unix timestamp or `Date` lower bound. */
+    since?: number | Date;
+    /** Unix timestamp or `Date` upper bound. */
+    until?: number | Date;
+    limit?: number;
+    /** Pagination cursors (from a previous response's `paging`). */
+    before?: string;
+    after?: string;
+    signal?: AbortSignal;
+}
+interface GetPostOptions {
+    fields?: string[];
+    signal?: AbortSignal;
+}
+declare class PostsResource {
+    private readonly client;
+    constructor(client: ThreadsRequester);
+    /**
+     * Lists a user's posts, most recent first. Cursor-paginated.
+     * Requires the `threads_basic` permission.
+     */
+    list(options?: ListPostsOptions): Promise<Paginated<ThreadsMedia>>;
+    /**
+     * Reads a single media object (post or reply) by id.
+     * Requires the `threads_basic` permission.
+     */
+    get(mediaId: string, options?: GetPostOptions): Promise<ThreadsMedia>;
+}
+
+/** Profile endpoint — `GET /me` / `GET /{user-id}`. */
+
+interface GetProfileOptions {
+    /** User id to read; defaults to the configured user (or `me`). */
+    userId?: string;
+    /** Profile fields to return; defaults to all documented fields. */
+    fields?: string[];
+    signal?: AbortSignal;
+}
+declare class ProfileResource {
+    private readonly client;
+    constructor(client: ThreadsRequester);
+    /**
+     * Returns profile information for a Threads user.
+     * Requires the `threads_basic` permission.
+     */
+    get(options?: GetProfileOptions): Promise<ThreadsProfile>;
+}
+
+/**
+ * Publishing — the two-step container flow plus convenience wrappers.
+ *
+ * Flow: `createContainer()` → (optionally wait for processing) →
+ * `publishContainer()`. The `publishText` / `publishImage` / `publishVideo` /
+ * `publishCarousel` helpers run the whole flow for you.
+ */
+
+interface CreateContainerInput {
+    mediaType: MediaContainerType;
+    text?: string;
+    /** Required when `mediaType` is `IMAGE`. */
+    imageUrl?: string;
+    /** Required when `mediaType` is `VIDEO`. */
+    videoUrl?: string;
+    /** Mark this container as a carousel child (not published on its own). */
+    isCarouselItem?: boolean;
+    /** Child container ids — required when `mediaType` is `CAROUSEL`. */
+    children?: string[];
+    /** Make this post a reply to the given media id. */
+    replyToId?: string;
+    replyControl?: ReplyControl;
+    /** Accessibility description (max 1,000 chars). */
+    altText?: string;
+    linkAttachment?: string;
+    locationId?: string;
+    quotePostId?: string;
+    topicTag?: string;
+    /** Attach a poll (TEXT posts only). 2–4 options. */
+    pollAttachment?: PollAttachment;
+    /** Publishing user; defaults to the configured user (or `me`). */
+    userId?: string;
+    signal?: AbortSignal;
+}
+interface PollAttachment {
+    optionA: string;
+    optionB: string;
+    optionC?: string;
+    optionD?: string;
+}
+interface ContainerStatusResult {
+    id: string;
+    status: ContainerStatus;
+    error_message?: string;
+}
+interface WaitOptions {
+    /** Poll until the container is ready before publishing. */
+    waitForReady?: boolean;
+    pollIntervalMs?: number;
+    maxWaitMs?: number;
+}
+type PublishImageInput = {
+    imageUrl: string;
+} & Omit<CreateContainerInput, 'mediaType'>;
+type PublishVideoInput = {
+    videoUrl: string;
+} & Omit<CreateContainerInput, 'mediaType'>;
+interface PublishCarouselInput {
+    items: {
+        imageUrl?: string;
+        videoUrl?: string;
+        altText?: string;
+    }[];
+    text?: string;
+    replyControl?: ReplyControl;
+    userId?: string;
+    signal?: AbortSignal;
+    wait?: WaitOptions;
+}
+declare class PublishingResource {
+    private readonly client;
+    constructor(client: ThreadsRequester);
+    /** Step 1: create a media container. Returns its creation id. */
+    createContainer(input: CreateContainerInput): Promise<ContainerRef>;
+    /** Step 2: publish a previously created container. Returns the post id. */
+    publishContainer(creationId: string, options?: {
+        userId?: string;
+        signal?: AbortSignal;
+    }): Promise<ContainerRef>;
+    /** Reads a container's processing status. */
+    getContainerStatus(containerId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ContainerStatusResult>;
+    /**
+     * Creates a container, optionally waits for media processing, then publishes.
+     * `waitForReady` defaults to `true` for `VIDEO`/`CAROUSEL` (which need
+     * server-side processing) and `false` otherwise.
+     */
+    createAndPublish(input: CreateContainerInput, wait?: WaitOptions): Promise<ContainerRef>;
+    /** Convenience: publish a text-only post. */
+    publishText(text: string, options?: Omit<CreateContainerInput, 'mediaType' | 'text'>): Promise<ContainerRef>;
+    /** Convenience: publish a text post with a poll (2–4 options). */
+    publishPoll(text: string, poll: PollAttachment, options?: Omit<CreateContainerInput, 'mediaType' | 'text' | 'pollAttachment'>): Promise<ContainerRef>;
+    /** Delete a published post. Requires the `threads_delete` scope. */
+    deletePost(postId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /** Convenience: publish a single image post. */
+    publishImage(input: PublishImageInput): Promise<ContainerRef>;
+    /** Convenience: publish a single video post (waits for processing). */
+    publishVideo(input: PublishVideoInput): Promise<ContainerRef>;
+    /**
+     * Convenience: publish a carousel. Each item becomes a child container, then
+     * a parent `CAROUSEL` container is created and published.
+     */
+    publishCarousel(input: PublishCarouselInput): Promise<ContainerRef>;
+    /** Reads remaining publish/reply/delete quotas for the user. */
+    getPublishingLimit(options?: {
+        userId?: string;
+        signal?: AbortSignal;
+    }): Promise<PublishingLimit>;
+    /** Polls a container until it is ready to publish, or throws on failure. */
+    private waitForContainer;
+}
+
+/**
+ * Replies & moderation.
+ *
+ * Reading: `GET /{media}/replies` (top-level) and `GET /{media}/conversation`
+ * (flattened thread). Moderation: hide/unhide, plus the reply-approval queue.
+ * Publishing a reply reuses the publishing flow with `reply_to_id` set.
+ */
+
+interface ListRepliesOptions {
+    fields?: string[];
+    /** Reverse chronological order. */
+    reverse?: boolean;
+    signal?: AbortSignal;
+}
+interface ListPendingRepliesOptions {
+    fields?: string[];
+    reverse?: boolean;
+    /** Filter by approval state. */
+    approvalStatus?: 'pending' | 'ignored';
+    signal?: AbortSignal;
+}
+declare class RepliesResource {
+    private readonly client;
+    private readonly publishing;
+    constructor(client: ThreadsRequester, publishing: PublishingResource);
+    /**
+     * Lists the top-level replies to a post.
+     * Requires `threads_read_replies` (or `threads_manage_replies`).
+     */
+    list(mediaId: string, options?: ListRepliesOptions): Promise<Paginated<ThreadsReply>>;
+    /**
+     * Lists the full conversation (all nested replies) under a post.
+     * Requires `threads_read_replies` (or `threads_manage_replies`).
+     */
+    conversation(mediaId: string, options?: ListRepliesOptions): Promise<Paginated<ThreadsReply>>;
+    /**
+     * Publishes a reply to an existing post. Requires `threads_content_publish`
+     * (and `threads_manage_replies` for replies you don't own).
+     */
+    publish(replyToId: string, text: string, options?: {
+        userId?: string;
+        signal?: AbortSignal;
+    }): Promise<ContainerRef>;
+    /** Hides a reply. Requires `threads_manage_replies`. */
+    hide(replyId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SuccessResponse>;
+    /** Unhides a previously hidden reply. Requires `threads_manage_replies`. */
+    unhide(replyId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SuccessResponse>;
+    /**
+     * Lists replies awaiting approval (when reply approvals are enabled).
+     * Requires `threads_manage_replies`.
+     */
+    listPending(mediaId: string, options?: ListPendingRepliesOptions): Promise<Paginated<ThreadsReply>>;
+    /**
+     * Approves or rejects a pending reply. Requires `threads_manage_replies`.
+     */
+    managePending(replyId: string, approve: boolean, options?: {
+        signal?: AbortSignal;
+    }): Promise<SuccessResponse>;
+    private setHidden;
+}
+
+/** Keyword search — `GET /keyword_search`. */
+
+interface KeywordSearchOptions {
+    /** `TOP` (default) ranks by relevance; `RECENT` is reverse-chronological. */
+    searchType?: 'TOP' | 'RECENT';
+    /** `KEYWORD` (default) or `TAG`. */
+    searchMode?: 'KEYWORD' | 'TAG';
+    /** Restrict to a media type. */
+    mediaType?: Extract<MediaContainerType, 'TEXT' | 'IMAGE' | 'VIDEO'>;
+    since?: number | Date;
+    until?: number | Date;
+    /** Default 25, max 100. */
+    limit?: number;
+    /** Exact username to filter results by author. */
+    authorUsername?: string;
+    fields?: string[];
+    signal?: AbortSignal;
+}
+declare class SearchResource {
+    private readonly client;
+    constructor(client: ThreadsRequester);
+    /**
+     * Searches public Threads posts by keyword or tag. The `owner` field is never
+     * returned for search results. Requires the `threads_keyword_search`
+     * permission (plus `threads_basic`).
+     */
+    keyword(query: string, options?: KeywordSearchOptions): Promise<Paginated<ThreadsMedia>>;
+}
+
+/**
+ * `ThreadsClient` — the typed entry point. Holds resolved configuration and
+ * exposes resource namespaces. One client instance is bound to one access
+ * token; create a new instance (or use {@link ThreadsClient.withToken}) per
+ * user/token.
+ */
+
+interface ThreadsClientConfig {
+    /** A Threads user access token (short- or long-lived). */
+    accessToken: string;
+    /**
+     * Default node id for user-scoped endpoints. Defaults to `me`, which resolves
+     * to the token's owner.
+     */
+    userId?: string;
+    /** Graph host override. Defaults to `https://graph.threads.net`. */
+    baseUrl?: string;
+    /** API version. Defaults to `v1.0`. */
+    version?: string;
+    /** Per-request timeout in ms. Defaults to 30000. */
+    timeoutMs?: number;
+    /**
+     * Retry policy for idempotent requests. Pass `false` to disable retries, or a
+     * partial object to override individual fields.
+     */
+    retry?: Partial<RetryConfig> | false;
+    /** Logging hook. Tokens/secrets are always redacted before logging. */
+    logger?: Logger;
+    /** Custom fetch (for tests or non-standard runtimes). Defaults to global. */
+    fetch?: FetchLike;
+}
+declare class ThreadsClient implements ThreadsRequester {
+    readonly profile: ProfileResource;
+    readonly posts: PostsResource;
+    readonly publishing: PublishingResource;
+    readonly replies: RepliesResource;
+    readonly insights: InsightsResource;
+    readonly mentions: MentionsResource;
+    readonly search: SearchResource;
+    private readonly config;
+    constructor(config: ThreadsClientConfig);
+    /** Default node id for user-scoped endpoints. */
+    get userNode(): string;
+    /**
+     * Low-level escape hatch: issue a request to any Threads endpoint with full
+     * typing of the response. Prefer the resource methods; use this for endpoints
+     * the SDK doesn't model yet.
+     */
+    request<T>(req: ResourceRequest): Promise<T>;
+    /** Returns a new client that shares this config but uses a different token. */
+    withToken(accessToken: string): ThreadsClient;
+}
+
+/**
+ * Static configuration for the Threads API.
+ *
+ * Values here mirror the official documentation
+ * (https://developers.facebook.com/docs/threads). Hosts and the API version
+ * are the only "magic strings" in the SDK and live in one place so they are
+ * easy to audit against the docs.
+ */
+/** Graph host for all data/publishing calls. */
+declare const DEFAULT_BASE_URL = "https://graph.threads.net";
+/** Host that serves the OAuth authorization window (user-facing redirect). */
+declare const AUTHORIZATION_BASE_URL = "https://threads.net";
+/** Current Threads Graph API version. */
+declare const DEFAULT_API_VERSION = "v1.0";
+/**
+ * OAuth permission scopes supported by the Threads API, as documented.
+ * `threads_basic` is required for every call.
+ */
+declare const THREADS_SCOPES: readonly ["threads_basic", "threads_content_publish", "threads_read_replies", "threads_manage_replies", "threads_manage_insights", "threads_keyword_search", "threads_delete", "threads_location_tagging"];
+/**
+ * A documented Threads scope, or any other scope string the API may accept.
+ * The string fallback keeps autocomplete for known scopes without hardcoding
+ * scope names that aren't verified against the docs.
+ */
+type ThreadsScope = (typeof THREADS_SCOPES)[number] | (string & {});
+
+/**
+ * OAuth 2.0 helpers for the Threads authorization-code flow.
+ *
+ * These are standalone functions (not methods on the client) so a host app that
+ * only handles the auth handshake can import them without pulling in the rest
+ * of the SDK. Token-exchange calls must run server-side: they require the app
+ * secret, which must never reach a browser.
+ */
+
+/** Options shared by the server-side token-exchange calls. */
+interface ExchangeBaseOptions {
+    /** Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    /** Graph host override (defaults to `https://graph.threads.net`). */
+    baseUrl?: string;
+    /** Per-request timeout in ms. */
+    timeoutMs?: number;
+    /** Optional logging hook (token values are always redacted). */
+    logger?: Logger;
+}
+interface AuthorizationUrlOptions {
+    clientId: string;
+    redirectUri: string;
+    /** Requested scopes. `threads_basic` is required by the API. */
+    scopes: ThreadsScope[];
+    /** Opaque CSRF token echoed back to your redirect URI. Strongly recommended. */
+    state?: string;
+    /** Authorization host override (defaults to `https://threads.net`). */
+    baseUrl?: string;
+}
+interface ShortLivedTokenResponse {
+    access_token: string;
+    user_id: string;
+}
+interface LongLivedTokenResponse {
+    access_token: string;
+    token_type: string;
+    /** Seconds until expiry (~60 days). */
+    expires_in: number;
+}
+/**
+ * Builds the URL to redirect a user to in order to grant your app access.
+ *
+ * @example
+ * ```ts
+ * const url = getAuthorizationUrl({
+ *   clientId: process.env.THREADS_APP_ID!,
+ *   redirectUri: 'https://app.example.com/auth/callback',
+ *   scopes: ['threads_basic', 'threads_content_publish'],
+ *   state: csrfToken,
+ * })
+ * ```
+ */
+declare function getAuthorizationUrl(options: AuthorizationUrlOptions): string;
+/**
+ * Exchanges an authorization `code` for a short-lived access token. Server-side
+ * only (requires the app secret).
+ */
+declare function exchangeCodeForToken(options: ExchangeBaseOptions & {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri: string;
+}): Promise<ShortLivedTokenResponse>;
+/**
+ * Exchanges a short-lived token for a long-lived (~60 day) token. Server-side
+ * only (requires the app secret).
+ */
+declare function exchangeForLongLivedToken(options: ExchangeBaseOptions & {
+    clientSecret: string;
+    shortLivedToken: string;
+}): Promise<LongLivedTokenResponse>;
+/**
+ * Refreshes a long-lived token, extending it ~60 days. The token must be at
+ * least 24 hours old and unexpired. No app secret required.
+ */
+declare function refreshLongLivedToken(options: ExchangeBaseOptions & {
+    longLivedToken: string;
+}): Promise<LongLivedTokenResponse>;
+
+/**
+ * Typed error hierarchy. Every failure the SDK surfaces is an instance of
+ * {@link ThreadsError}, so callers can `catch` broadly or narrow with
+ * `instanceof` to a specific subtype.
+ *
+ * ```text
+ * ThreadsError
+ * ├─ ThreadsValidationError   client-side input was invalid (no request sent)
+ * ├─ ThreadsTimeoutError      request exceeded the configured timeout
+ * ├─ ThreadsNetworkError      fetch failed before a response was received
+ * └─ ThreadsAPIError          the API returned a non-2xx response
+ *    ├─ ThreadsAuthError      invalid/expired token or auth failure (401 / code 190)
+ *    └─ ThreadsRateLimitError throttled (HTTP 429 or a known throttle code)
+ * ```
+ */
+interface ApiErrorDetails {
+    message: string;
+    /** HTTP status code of the response. */
+    status?: number;
+    /** Graph API `error.code`. */
+    code?: number;
+    /** Graph API `error.error_subcode`. */
+    subcode?: number;
+    /** Graph API `error.type`. */
+    type?: string;
+    /** Graph API `error.fbtrace_id` — quote this when contacting Meta support. */
+    fbtraceId?: string;
+}
+/** Base class for every error thrown by the SDK. */
+declare class ThreadsError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when caller input fails validation before any request is made. */
+declare class ThreadsValidationError extends ThreadsError {
+}
+/** Thrown when a request exceeds the configured timeout. */
+declare class ThreadsTimeoutError extends ThreadsError {
+}
+/** Thrown when the request fails at the network layer (no HTTP response). */
+declare class ThreadsNetworkError extends ThreadsError {
+}
+/** Thrown for any non-2xx API response. */
+declare class ThreadsAPIError extends ThreadsError {
+    readonly status?: number;
+    readonly code?: number;
+    readonly subcode?: number;
+    readonly type?: string;
+    readonly fbtraceId?: string;
+    constructor(details: ApiErrorDetails, options?: {
+        cause?: unknown;
+    });
+}
+/** Invalid or expired access token / authorization failure. */
+declare class ThreadsAuthError extends ThreadsAPIError {
+}
+/** Request was throttled. {@link retryAfterMs} is set when the API tells us. */
+declare class ThreadsRateLimitError extends ThreadsAPIError {
+    readonly retryAfterMs?: number;
+    constructor(details: ApiErrorDetails & {
+        retryAfterMs?: number;
+    }, options?: {
+        cause?: unknown;
+    });
+}
+/** A `Headers`-like object (only `get` is needed). */
+interface HeadersLike {
+    get(name: string): string | null;
+}
+/**
+ * Parses a `Retry-After` header (seconds or HTTP-date) into milliseconds.
+ * Returns `undefined` when absent or unparseable.
+ */
+declare function parseRetryAfterMs(value: string | null): number | undefined;
+/**
+ * Maps a non-2xx HTTP response into the most specific error subtype.
+ *
+ * @param status - HTTP status code.
+ * @param body - Parsed JSON body (may be undefined for empty/non-JSON bodies).
+ * @param headers - Response headers, used to read `Retry-After`.
+ */
+declare function toApiError(status: number, body: unknown, headers?: HeadersLike): ThreadsAPIError;
+
+export { AUTHORIZATION_BASE_URL, type ApiErrorDetails, type AuthorizationUrlOptions, type ContainerRef, type ContainerStatus, type ContainerStatusResult, type CreateContainerInput, DEFAULT_API_VERSION, DEFAULT_BASE_URL, type DemographicBreakdown, type FetchLike, type GetPostOptions, type GetProfileOptions, type HttpMethod, type InsightMetric, type InsightsResponse, type KeywordSearchOptions, type ListMentionsOptions, type ListPendingRepliesOptions, type ListPostsOptions, type ListRepliesOptions, type LogContext, type LogLevel, type Logger, type LongLivedTokenResponse, type MediaContainerType, type MediaInsightsOptions, type MediaMetric, type MediaType, type Paginated, type PublishCarouselInput, type PublishImageInput, type PublishVideoInput, type PublishingLimit, type QuotaBucket, type ReplyControl, type ResourceRequest, type RetryConfig, type ShortLivedTokenResponse, type SuccessResponse, THREADS_SCOPES, ThreadsAPIError, ThreadsAuthError, ThreadsClient, type ThreadsClientConfig, ThreadsError, type ThreadsMedia, ThreadsNetworkError, type ThreadsProfile, ThreadsRateLimitError, type ThreadsReply, type ThreadsRequester, type ThreadsScope, ThreadsTimeoutError, ThreadsValidationError, type UserInsightsOptions, type UserMetric, type WaitOptions, exchangeCodeForToken, exchangeForLongLivedToken, getAuthorizationUrl, noopLogger, parseRetryAfterMs, redactParams, redactUrl, refreshLongLivedToken, toApiError };