@opencoredev/social-sdk 0.3.0 → 0.4.0

package/dist/platforms/x-stream.js

@@ -0,0 +1,350 @@
+import { SocialError } from "../core/errors.js";
+import { definedFields } from "../core/fields.js";
+import { remainingBudget } from "../transport/budget.js";
+import { abortable, retryDelay } from "../transport/http.js";
+import { parseJson } from "../transport/json.js";
+import { isJsonObject, isString } from "../transport/validation.js";
+// Filtered stream contract, checked 2026-09-24 against X API v2 OpenAPI 2.168:
+// https://docs.x.com/x-api/posts/filtered-stream/introduction
+// https://docs.x.com/x-api/stream/stream-filtered-posts
+// https://docs.x.com/x-api/stream/get-stream-rules
+// https://docs.x.com/x-api/stream/update-stream-rules
+// https://docs.x.com/x-api/fundamentals/handling-disconnections
+// https://docs.x.com/x-api/fundamentals/recovery-and-redundancy
+/** X sends a `\r\n` keep-alive at least every 20 seconds and recommends a 20-second read timeout. */
+export const xStreamDefaultStallTimeoutMs = 20_000;
+/** Upper bound for one newline-delimited stream message held in memory. */
+const maxMessageLength = 1024 * 1024;
+const ruleIdPattern = /^[0-9]{1,19}$/;
+function jsonObjectValue(value) {
+    return value !== undefined && isJsonObject(value) ? value : undefined;
+}
+function objectArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.flatMap((entry) => {
+        const row = jsonObjectValue(entry);
+        return row === undefined ? [] : [row];
+    });
+}
+function stringValue(value) {
+    return value !== undefined && isString(value) ? value : undefined;
+}
+function invalidResponse(operation, message) {
+    return new SocialError({
+        code: "upstream_failure",
+        operation,
+        message,
+        retryDisposition: { kind: "never" },
+    });
+}
+/** Parse one rule object from X, rejecting malformed identifiers. */
+export function parseStreamRule(value, operation) {
+    const row = jsonObjectValue(value);
+    const id = stringValue(row?.["id"]);
+    const ruleValue = stringValue(row?.["value"]);
+    const tag = stringValue(row?.["tag"]);
+    if (id === undefined || !ruleIdPattern.test(id) || ruleValue === undefined)
+        throw invalidResponse(operation, "X returned a filtered-stream rule without an id or value.");
+    return { id, value: ruleValue, ...definedFields({ tag }) };
+}
+/** Parse the rule-mutation response while keeping per-rule errors. */
+export function parseRulesUpdate(value, dryRun) {
+    const operation = "x.streamRules.update";
+    const body = jsonObjectValue(value);
+    if (body === undefined)
+        throw invalidResponse(operation, "X returned a non-object rule update.");
+    const data = body["data"];
+    const meta = jsonObjectValue(body["meta"]);
+    const summary = jsonObjectValue(meta?.["summary"]);
+    if (data !== undefined && !Array.isArray(data))
+        throw invalidResponse(operation, "X returned a rule update whose data is not an array.");
+    return {
+        dryRun,
+        rules: (data ?? []).map((entry) => parseStreamRule(entry, operation)),
+        ...definedFields({ summary }),
+        errors: objectArray(body["errors"]) ?? [],
+    };
+}
+/** Validate one rule for local bounds. X enforces the tier-specific limit. */
+export function validateRuleInput(rule) {
+    if (!rule.value.trim() || rule.value.length > 2048)
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "x.streamRules.add",
+            message: "X filtered-stream rule values must contain 1-2048 characters.",
+        });
+    if (rule.tag !== undefined && !rule.tag.trim())
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "x.streamRules.add",
+            message: "X filtered-stream rule tags must not be empty when provided.",
+        });
+}
+export function validateRuleIds(ids, operation, max) {
+    if (ids.length === 0 || ids.length > max || ids.some((id) => !ruleIdPattern.test(id)))
+        throw new SocialError({
+            code: "invalid_input",
+            operation,
+            message: `Provide 1-${max} numeric X filtered-stream rule IDs.`,
+        });
+}
+/** Classify one newline-delimited message. */
+export function parseStreamMessage(line) {
+    let parsed;
+    try {
+        parsed = parseJson(line);
+    }
+    catch {
+        throw invalidResponse("streams.read", "X filtered stream sent an invalid JSON message.");
+    }
+    const message = jsonObjectValue(parsed);
+    if (message === undefined)
+        throw invalidResponse("streams.read", "X filtered stream sent a non-object message.");
+    const post = jsonObjectValue(message["data"]);
+    const errors = objectArray(message["errors"]);
+    if (post !== undefined) {
+        const includes = jsonObjectValue(message["includes"]);
+        const rules = objectArray(message["matching_rules"]) ?? [];
+        return {
+            kind: "post",
+            post,
+            matchingRules: rules.flatMap((rule) => {
+                const id = stringValue(rule["id"]);
+                const tag = stringValue(rule["tag"]);
+                return id === undefined ? [] : [{ id, ...definedFields({ tag }) }];
+            }),
+            ...definedFields({
+                includes,
+                errors: errors !== undefined && errors.length > 0 ? errors : undefined,
+            }),
+        };
+    }
+    if (errors !== undefined && errors.length > 0)
+        return { kind: "error", errors };
+    return { kind: "other", message };
+}
+function isoTime(value, name) {
+    if (value !== undefined && !Number.isFinite(Date.parse(value)))
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "streams.read",
+            message: `${name} must be an ISO 8601 timestamp.`,
+        });
+}
+/** Validate caller options and build the connection URL. Performs no I/O. */
+export function streamUrl(options) {
+    const backfill = options.backfillMinutes;
+    if (backfill !== undefined && (!Number.isSafeInteger(backfill) || backfill < 0 || backfill > 5))
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "streams.read",
+            message: "backfillMinutes must be an integer from 1 through 5, or 0 for no backfill.",
+        });
+    const stall = options.stallTimeoutMs;
+    if (stall !== undefined && (!Number.isSafeInteger(stall) || stall < 1000 || stall > 600_000))
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "streams.read",
+            message: "stallTimeoutMs must be an integer from 1000 through 600000.",
+        });
+    isoTime(options.startTime, "startTime");
+    isoTime(options.endTime, "endTime");
+    if (options.startTime !== undefined &&
+        options.endTime !== undefined &&
+        Date.parse(options.startTime) >= Date.parse(options.endTime))
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "streams.read",
+            message: "startTime must be earlier than endTime.",
+        });
+    const url = new URL("https://api.x.com/2/tweets/search/stream");
+    const unique = (values) => values.filter((value, index) => values.indexOf(value) === index).join(",");
+    if (options.tweetFields?.length)
+        url.searchParams.set("tweet.fields", unique(options.tweetFields));
+    if (options.expansions?.length)
+        url.searchParams.set("expansions", unique(options.expansions));
+    if (options.userFields?.length)
+        url.searchParams.set("user.fields", unique(options.userFields));
+    if (options.mediaFields?.length)
+        url.searchParams.set("media.fields", unique(options.mediaFields));
+    if (backfill !== undefined && backfill > 0)
+        url.searchParams.set("backfill_minutes", String(backfill));
+    if (options.startTime !== undefined)
+        url.searchParams.set("start_time", options.startTime);
+    if (options.endTime !== undefined)
+        url.searchParams.set("end_time", options.endTime);
+    return url;
+}
+function statusError(response, context) {
+    const status = response.status;
+    const now = Date.now();
+    let delay = retryDelay(response.headers.get("retry-after"), now);
+    const reset = Number(response.headers.get("x-rate-limit-reset") ?? Number.NaN);
+    if (delay === undefined && Number.isFinite(reset) && reset >= 0)
+        delay = Math.max(0, reset * 1000 - now);
+    const common = {
+        operation: "streams.read",
+        backend: context.backendInstance,
+        correlationId: context.correlationId,
+        upstreamStatus: status,
+    };
+    if (status === 401)
+        return new SocialError({
+            ...common,
+            code: "reconnect_required",
+            message: "X rejected the app-only bearer token for the filtered stream.",
+            retryDisposition: { kind: "after-reconnect" },
+        });
+    if (status === 403)
+        return new SocialError({
+            ...common,
+            code: "missing_permission",
+            message: "X denied the filtered stream. It needs an app-only bearer token and pay-per-use or Enterprise access; backfill and recovery need Enterprise.",
+            retryDisposition: { kind: "never" },
+        });
+    if (status === 402)
+        return new SocialError({
+            ...common,
+            code: "billing_required",
+            message: "X requires API credits or a plan change for the filtered stream.",
+            retryDisposition: { kind: "never" },
+        });
+    if (status === 429)
+        return new SocialError({
+            ...common,
+            code: "rate_limited",
+            message: "X rate-limited the filtered stream connection or the connection limit is reached. Close other connections and back off before reconnecting.",
+            retryDisposition: delay === undefined ? { kind: "never" } : { kind: "after-delay", delayMs: delay },
+        });
+    return new SocialError({
+        ...common,
+        code: "upstream_failure",
+        message: `X filtered stream connection failed with HTTP ${status}.`,
+        retryDisposition: { kind: "never" },
+    });
+}
+/**
+ * Open one filtered-stream connection and yield its messages. The connection is made when
+ * iteration starts and closes when the caller stops iterating, the context signal aborts, the
+ * stall timeout elapses, or X ends the response. This function never reconnects.
+ */
+export async function* readFilteredStream(config, options, context) {
+    const url = streamUrl(options);
+    const stallTimeoutMs = options.stallTimeoutMs ?? xStreamDefaultStallTimeoutMs;
+    const outer = context.signal;
+    const common = {
+        operation: "streams.read",
+        backend: context.backendInstance,
+        correlationId: context.correlationId,
+    };
+    if (outer?.aborted)
+        throw new SocialError({
+            ...common,
+            code: "cancelled",
+            message: "The filtered stream was cancelled before connecting.",
+        });
+    const connectBudget = remainingBudget(context);
+    const controller = new AbortController();
+    const connectTimeout = new Error("connect timeout");
+    const stalled = new Error("stalled");
+    const onAbort = () => controller.abort(outer?.reason);
+    outer?.addEventListener("abort", onAbort, { once: true });
+    let timer = setTimeout(() => controller.abort(connectTimeout), connectBudget);
+    let reader;
+    const interrupted = (phase) => {
+        const reason = controller.signal.reason;
+        if (outer?.aborted)
+            return new SocialError({
+                ...common,
+                code: "cancelled",
+                message: "The filtered stream was cancelled by the caller.",
+            });
+        if (reason === connectTimeout || reason === stalled)
+            return new SocialError({
+                ...common,
+                code: "timeout",
+                message: reason === stalled
+                    ? `X filtered stream sent no data or keep-alive within ${stallTimeoutMs} ms. Reconnect explicitly.`
+                    : "X filtered stream did not connect within the operation budget.",
+                retryDisposition: { kind: "never" },
+            });
+        return new SocialError({
+            ...common,
+            code: "upstream_failure",
+            message: phase === "connect"
+                ? "The filtered stream connection failed before X responded."
+                : "The filtered stream connection dropped. Reconnect explicitly.",
+            retryDisposition: { kind: "never" },
+        });
+    };
+    try {
+        let response;
+        try {
+            const pending = (config.fetch ?? globalThis.fetch)(url, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${config.bearerToken}` },
+                signal: controller.signal,
+                redirect: "error",
+            });
+            void pending.then((late) => {
+                if (controller.signal.aborted)
+                    void late.body?.cancel().catch(() => undefined);
+            }, () => undefined);
+            response = await abortable(pending, controller.signal);
+        }
+        catch {
+            throw interrupted("connect");
+        }
+        clearTimeout(timer);
+        if (!response.ok) {
+            void response.body?.cancel().catch(() => undefined);
+            throw statusError(response, context);
+        }
+        if (!response.body)
+            throw invalidResponse("streams.read", "X returned an empty stream body.");
+        reader = response.body.getReader();
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        let buffer = "";
+        for (;;) {
+            timer = setTimeout(() => controller.abort(stalled), stallTimeoutMs);
+            let chunk;
+            try {
+                chunk = await abortable(reader.read(), controller.signal);
+            }
+            catch {
+                throw interrupted("read");
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            try {
+                buffer += chunk.done ? decoder.decode() : decoder.decode(chunk.value, { stream: true });
+            }
+            catch {
+                throw invalidResponse("streams.read", "X filtered stream sent invalid UTF-8.");
+            }
+            const lines = buffer.split("\n");
+            buffer = chunk.done ? "" : (lines.pop() ?? "");
+            if (buffer.length > maxMessageLength)
+                throw invalidResponse("streams.read", "X filtered stream message exceeds 1 MiB.");
+            for (const line of lines) {
+                if (line.length > maxMessageLength)
+                    throw invalidResponse("streams.read", "X filtered stream message exceeds 1 MiB.");
+                const text = line.trim();
+                // Blank lines are X keep-alive heartbeats.
+                if (text)
+                    yield parseStreamMessage(text);
+            }
+            if (chunk.done)
+                return;
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        outer?.removeEventListener("abort", onAbort);
+        if (!controller.signal.aborted)
+            controller.abort(new Error("stream closed"));
+        void reader?.cancel().catch(() => undefined);
+    }
+}

package/dist/platforms/x.d.ts

@@ -1,16 +1,23 @@
 import type { AdapterOperationContext, ConnectedAccountRef, JsonObject, Page, PlatformPostRef, SearchPostsInput } from "../core/types.js";
+import { type XStreamEvent, type XStreamOptions, type XStreamRule, type XStreamRuleInput, type XStreamRulesUpdate } from "./x-stream.js";
 export interface XAuthorization {
     readonly userId: string;
     readonly accessToken?: string;
     readonly handle?: string;
 }
 export { xLike, xUnlike, type XEngagementOptions, type XEngagementResult } from "./x-engagement.js";
+export { xStreamDefaultStallTimeoutMs, type XMatchingRule, type XStreamEvent, type XStreamOptions, type XStreamRule, type XStreamRuleInput, type XStreamRulesUpdate, } from "./x-stream.js";
 export interface XOptions {
     readonly auth: XAuthorization;
     /** App-only bearer token for full-archive search and filtered stream. */
     readonly appBearerToken?: string;
     readonly fetch?: typeof globalThis.fetch;
     readonly clock?: () => Date;
+    /**
+     * OAuth 2.0 client secret (or legacy OAuth 1.0 consumer secret) that X uses to sign
+     * webhook deliveries and CRC responses.
+     */
+    readonly webhookSecret?: string;
 }
 export type XTweetField = "attachments" | "author_id" | "conversation_id" | "created_at" | "entities" | "geo" | "id" | "lang" | "public_metrics" | "referenced_tweets" | "text";
 export type XTweetExpansion = "attachments.media_keys" | "attachments.poll_ids" | "author_id" | "entities.mentions.username" | "geo.place_id" | "in_reply_to_user_id" | "referenced_tweets.id";
@@ -26,6 +33,16 @@ export interface XSearchInput extends SearchPostsInput {
 export interface XUploadedMedia {
     readonly mediaId: string;
 }
+/** A confirmed X post edit. X assigns every edited version a new post ID. */
+export interface XUpdatedPost {
+    /** Reference to the new version created by the edit. */
+    readonly post: PlatformPostRef;
+    /** The post ID that was passed as `previous_post_id`. */
+    readonly previousPostId: string;
+    readonly text: string;
+    /** Oldest-first edit chain, when X returns it. The first entry is the original post ID. */
+    readonly editHistoryPostIds?: readonly string[];
+}
 export interface XNative {
     readonly searchRecentPosts: (input: {
         readonly account: ConnectedAccountRef;
@@ -54,6 +71,18 @@ export interface XNative {
         readonly postId: string;
         readonly context: AdapterOperationContext;
     }) => Promise<void>;
+    /**
+     * Edits the text of a recent post with `POST /2/tweets` and `edit_options.previous_post_id`.
+     * X decides eligibility (X Premium, own post, edit window, edit count) and returns a new post ID.
+     * Sources, accessed 2026-09-24: https://docs.x.com/x-api/posts/create-post,
+     * https://docs.x.com/x-api/fundamentals/edit-posts, https://docs.x.com/changelog (2025-10-03).
+     */
+    readonly updatePost: (input: {
+        readonly account: ConnectedAccountRef;
+        readonly postId: string;
+        readonly text: string;
+        readonly context: AdapterOperationContext;
+    }) => Promise<XUpdatedPost>;
     /** Uploads one MP4 Blob (up to 512 MiB) and waits for processing. Returns an attachable media ID. */
     readonly uploadVideo: (input: {
         readonly account: ConnectedAccountRef;
@@ -310,5 +339,48 @@ export interface XNative {
         readonly postId: string;
         readonly context: AdapterOperationContext;
     }) => Promise<void>;
+    /** Lists the app's filtered-stream rules. Requires `appBearerToken`. */
+    readonly listStreamRules: (input: {
+        readonly account: ConnectedAccountRef;
+        readonly ids?: readonly string[];
+        readonly cursor?: string;
+        readonly limit?: number;
+        readonly context: AdapterOperationContext;
+    }) => Promise<Page<XStreamRule>>;
+    /** Adds filtered-stream rules in one request. Set `dryRun` to validate without saving. */
+    readonly addStreamRules: (input: {
+        readonly account: ConnectedAccountRef;
+        readonly rules: readonly XStreamRuleInput[];
+        readonly dryRun?: boolean;
+        readonly context: AdapterOperationContext;
+    }) => Promise<XStreamRulesUpdate>;
+    /** Deletes filtered-stream rules by ID in one request. Set `dryRun` to validate without saving. */
+    readonly deleteStreamRules: (input: {
+        readonly account: ConnectedAccountRef;
+        readonly ids: readonly string[];
+        readonly dryRun?: boolean;
+        readonly context: AdapterOperationContext;
+    }) => Promise<XStreamRulesUpdate>;
+    /**
+     * Opens one filtered-stream connection when iteration starts. It yields until the caller
+     * stops, `context.signal` aborts, the stall timeout elapses, or X closes the response. It
+     * never reconnects on its own. Requires `appBearerToken`.
+     */
+    readonly stream: (input: XStreamOptions & {
+        readonly account: ConnectedAccountRef;
+        readonly context: AdapterOperationContext;
+    }) => AsyncGenerator<XStreamEvent, void, undefined>;
+    /**
+     * Hides or unhides a reply in a conversation the authenticated user started.
+     * Calls `PUT /2/tweets/:id/hidden` and returns the hidden state X reports.
+     */
+    readonly hideReply: (input: {
+        readonly account: ConnectedAccountRef;
+        readonly replyId: string;
+        readonly hidden: boolean;
+        readonly context: AdapterOperationContext;
+    }) => Promise<{
+        readonly hidden: boolean;
+    }>;
 }
 export declare function x(options: XOptions): import("../core/adapter.js").SocialAdapter<XNative>;