@hardlydifficult/social 1.0.0

package/README.md

@@ -0,0 +1,55 @@
+# @hardlydifficult/social
+
+Provider-agnostic social read client with an X implementation in this version.
+
+## Current scope (read-first)
+
+This package is intentionally read-only for now:
+
+- Read timeline content
+- Read liked content
+- Watch for newly liked posts
+
+Write operations (posting, liking, reposting) are intentionally not included yet.
+
+## Install
+
+```bash
+npm install @hardlydifficult/social
+```
+
+## Usage
+
+```typescript
+import { createSocial } from "@hardlydifficult/social";
+
+const social = createSocial(); // defaults to "x"
+
+const timeline = await social.timeline({ maxResults: 10 });
+const liked = await social.likedPosts({ maxResults: 10 });
+
+const watcher = social.watchLikes({
+  pollIntervalMs: 30_000,
+  onLike: ({ post }) => {
+    console.log(`New like: ${post.url}`);
+  },
+});
+
+watcher.start();
+```
+
+## X configuration
+
+Set environment variables, or pass explicit config through `createSocialClient`.
+
+- `X_BEARER_TOKEN` (required)
+- Get a bearer token from the X Developer Portal: https://developer.x.com/en/docs/authentication/oauth-2-0/bearer-tokens
+
+```typescript
+import { createSocialClient } from "@hardlydifficult/social";
+
+const social = createSocialClient({
+  type: "x",
+  bearerToken: process.env.X_BEARER_TOKEN,
+});
+```

package/dist/SocialClient.d.ts

@@ -0,0 +1,19 @@
+import { SocialLikeWatcher, type SocialLikeWatcherOptions } from "./SocialLikeWatcher.js";
+import type { SocialProviderClient } from "./SocialProviderClient.js";
+import type { SocialPost } from "./types.js";
+/**
+ *
+ */
+export declare class SocialClient {
+    private readonly provider;
+    constructor(provider: SocialProviderClient);
+    getPost(postId: string): Promise<SocialPost | null>;
+    timeline(options?: {
+        maxResults?: number;
+    }): Promise<readonly SocialPost[]>;
+    likedPosts(options?: {
+        maxResults?: number;
+    }): Promise<readonly SocialPost[]>;
+    watchLikes(options: SocialLikeWatcherOptions): SocialLikeWatcher;
+}
+//# sourceMappingURL=SocialClient.d.ts.map

package/dist/SocialClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialClient.d.ts","sourceRoot":"","sources":["../src/SocialClient.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,oBAAoB;IAE3D,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAInD,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAI3E,UAAU,CAAC,OAAO,CAAC,EAAE;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAIlC,UAAU,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB;CAGjE"}

package/dist/SocialClient.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialClient = void 0;
+const SocialLikeWatcher_js_1 = require("./SocialLikeWatcher.js");
+/**
+ *
+ */
+class SocialClient {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    getPost(postId) {
+        return this.provider.getPost(postId);
+    }
+    timeline(options) {
+        return this.provider.getTimeline(options);
+    }
+    likedPosts(options) {
+        return this.provider.getLikedPosts(options);
+    }
+    watchLikes(options) {
+        return SocialLikeWatcher_js_1.SocialLikeWatcher.create(this.provider, options);
+    }
+}
+exports.SocialClient = SocialClient;
+//# sourceMappingURL=SocialClient.js.map

package/dist/SocialClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialClient.js","sourceRoot":"","sources":["../src/SocialClient.ts"],"names":[],"mappings":";;;AAAA,iEAGgC;AAIhC;;GAEG;AACH,MAAa,YAAY;IACM;IAA7B,YAA6B,QAA8B;QAA9B,aAAQ,GAAR,QAAQ,CAAsB;IAAG,CAAC;IAE/D,OAAO,CAAC,MAAc;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,QAAQ,CAAC,OAAiC;QACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED,UAAU,CAAC,OAEV;QACC,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,UAAU,CAAC,OAAiC;QAC1C,OAAO,wCAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;CACF;AApBD,oCAoBC"}

package/dist/SocialLikeWatcher.d.ts

@@ -0,0 +1,20 @@
+import type { SocialProviderClient } from "./SocialProviderClient.js";
+import type { LikeWatcherOptions } from "./types.js";
+export type SocialLikeWatcherOptions = LikeWatcherOptions;
+/**
+ *
+ */
+export declare class SocialLikeWatcher {
+    private readonly provider;
+    private readonly options;
+    private timer;
+    private polling;
+    private seeded;
+    private readonly knownLikeIds;
+    constructor(provider: SocialProviderClient, options: Required<Pick<LikeWatcherOptions, "pollIntervalMs">> & Pick<LikeWatcherOptions, "onLike" | "onError">);
+    static create(provider: SocialProviderClient, options: LikeWatcherOptions): SocialLikeWatcher;
+    start(): void;
+    stop(): void;
+    poll(): Promise<void>;
+}
+//# sourceMappingURL=SocialLikeWatcher.d.ts.map

package/dist/SocialLikeWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialLikeWatcher.d.ts","sourceRoot":"","sources":["../src/SocialLikeWatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAoB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAE1D;;GAEG;AACH,qBAAa,iBAAiB;IAO1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;gBAG/B,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,QAAQ,CAChC,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAC3C,GACC,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,SAAS,CAAC;IAGlD,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB;IAOpB,KAAK,IAAI,IAAI;IAYb,IAAI,IAAI,IAAI;IAON,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA6C5B"}

package/dist/SocialLikeWatcher.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialLikeWatcher = void 0;
+/**
+ *
+ */
+class SocialLikeWatcher {
+    provider;
+    options;
+    timer = null;
+    polling = false;
+    seeded = false;
+    knownLikeIds = new Set();
+    constructor(provider, options) {
+        this.provider = provider;
+        this.options = options;
+    }
+    static create(provider, options) {
+        return new SocialLikeWatcher(provider, {
+            ...options,
+            pollIntervalMs: options.pollIntervalMs ?? 60_000,
+        });
+    }
+    start() {
+        if (this.timer !== null) {
+            return;
+        }
+        void this.poll();
+        this.timer = setInterval(() => void this.poll(), this.options.pollIntervalMs);
+    }
+    stop() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    async poll() {
+        if (this.polling) {
+            return;
+        }
+        this.polling = true;
+        try {
+            const liked = await this.provider.getLikedPosts();
+            const now = new Date().toISOString();
+            if (!this.seeded) {
+                for (const post of liked) {
+                    this.knownLikeIds.add(post.id);
+                }
+                this.seeded = true;
+                return;
+            }
+            const notifications = [];
+            for (const post of liked) {
+                if (!this.knownLikeIds.has(post.id)) {
+                    this.knownLikeIds.add(post.id);
+                    notifications.push({ post, seenAt: now });
+                }
+            }
+            for (const notification of notifications.reverse()) {
+                this.options.onLike(notification);
+            }
+        }
+        catch (error) {
+            const normalizedError = error instanceof Error ? error : new Error(String(error));
+            if (this.options.onError) {
+                this.options.onError(normalizedError);
+            }
+            else {
+                console.error("SocialLikeWatcher: poll failed:", normalizedError.message);
+            }
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+}
+exports.SocialLikeWatcher = SocialLikeWatcher;
+//# sourceMappingURL=SocialLikeWatcher.js.map

package/dist/SocialLikeWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialLikeWatcher.js","sourceRoot":"","sources":["../src/SocialLikeWatcher.ts"],"names":[],"mappings":"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"}

package/dist/SocialProviderClient.d.ts

@@ -0,0 +1,11 @@
+import type { SocialPost } from "./types.js";
+export interface SocialProviderClient {
+    getPost(postId: string): Promise<SocialPost | null>;
+    getTimeline(options?: {
+        maxResults?: number;
+    }): Promise<readonly SocialPost[]>;
+    getLikedPosts(options?: {
+        maxResults?: number;
+    }): Promise<readonly SocialPost[]>;
+}
+//# sourceMappingURL=SocialProviderClient.d.ts.map

package/dist/SocialProviderClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialProviderClient.d.ts","sourceRoot":"","sources":["../src/SocialProviderClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACpD,WAAW,CAAC,OAAO,CAAC,EAAE;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACnC,aAAa,CAAC,OAAO,CAAC,EAAE;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;CACpC"}

package/dist/SocialProviderClient.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=SocialProviderClient.js.map

package/dist/SocialProviderClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialProviderClient.js","sourceRoot":"","sources":["../src/SocialProviderClient.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type { Provider, XConfig, SocialConfig, SocialPost, SocialAuthor, SocialPostMetrics, LikeWatcherOptions, LikeNotification, } from "./types.js";
+export type { SocialProviderClient } from "./SocialProviderClient.js";
+export { SocialClient } from "./SocialClient.js";
+export { SocialLikeWatcher, type SocialLikeWatcherOptions, } from "./SocialLikeWatcher.js";
+export { XSocialClient } from "./x";
+export { MastodonSocialClient } from "./mastodon/MastodonSocialClient.js";
+import { SocialClient } from "./SocialClient.js";
+import type { SocialConfig } from "./types.js";
+/**
+ * Create a social client from explicit provider configuration.
+ */
+export declare function createSocialClient(config: SocialConfig): SocialClient;
+/**
+ * Create a social client using default provider configuration.
+ */
+export declare function createSocial(): SocialClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,QAAQ,EACR,OAAO,EACP,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAErE;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAE3C"}

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MastodonSocialClient = exports.XSocialClient = exports.SocialLikeWatcher = exports.SocialClient = void 0;
+exports.createSocialClient = createSocialClient;
+exports.createSocial = createSocial;
+var SocialClient_js_1 = require("./SocialClient.js");
+Object.defineProperty(exports, "SocialClient", { enumerable: true, get: function () { return SocialClient_js_1.SocialClient; } });
+var SocialLikeWatcher_js_1 = require("./SocialLikeWatcher.js");
+Object.defineProperty(exports, "SocialLikeWatcher", { enumerable: true, get: function () { return SocialLikeWatcher_js_1.SocialLikeWatcher; } });
+var x_1 = require("./x");
+Object.defineProperty(exports, "XSocialClient", { enumerable: true, get: function () { return x_1.XSocialClient; } });
+var MastodonSocialClient_js_1 = require("./mastodon/MastodonSocialClient.js");
+Object.defineProperty(exports, "MastodonSocialClient", { enumerable: true, get: function () { return MastodonSocialClient_js_1.MastodonSocialClient; } });
+const SocialClient_js_2 = require("./SocialClient.js");
+const x_2 = require("./x");
+/**
+ * Create a social client from explicit provider configuration.
+ */
+function createSocialClient(config) {
+    return new SocialClient_js_2.SocialClient(new x_2.XSocialClient(config));
+}
+/**
+ * Create a social client using default provider configuration.
+ */
+function createSocial() {
+    return createSocialClient({ type: "x" });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AA6BA,gDAEC;AAKD,oCAEC;AAzBD,qDAAiD;AAAxC,+GAAA,YAAY,OAAA;AACrB,+DAGgC;AAF9B,yHAAA,iBAAiB,OAAA;AAInB,yBAAoC;AAA3B,kGAAA,aAAa,OAAA;AACtB,8EAA0E;AAAjE,+HAAA,oBAAoB,OAAA;AAE7B,uDAAiD;AAEjD,2BAAoC;AAEpC;;GAEG;AACH,SAAgB,kBAAkB,CAAC,MAAoB;IACrD,OAAO,IAAI,8BAAY,CAAC,IAAI,iBAAa,CAAC,MAAM,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,OAAO,kBAAkB,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;AAC3C,CAAC"}

package/dist/mastodon/MastodonSocialClient.d.ts

@@ -0,0 +1,16 @@
+import type { SocialProviderClient } from "../SocialProviderClient.js";
+import type { SocialPost } from "../types.js";
+/**
+ *
+ */
+export declare class MastodonSocialClient implements SocialProviderClient {
+    private readonly message;
+    getPost(_postId: string): Promise<SocialPost | null>;
+    getTimeline(_options?: {
+        maxResults?: number;
+    }): Promise<readonly SocialPost[]>;
+    getLikedPosts(_options?: {
+        maxResults?: number;
+    }): Promise<readonly SocialPost[]>;
+}
+//# sourceMappingURL=MastodonSocialClient.d.ts.map

package/dist/mastodon/MastodonSocialClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MastodonSocialClient.d.ts","sourceRoot":"","sources":["../../src/mastodon/MastodonSocialClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;GAEG;AACH,qBAAa,oBAAqB,YAAW,oBAAoB;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CACiF;IAEzG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAIpD,WAAW,CAAC,QAAQ,CAAC,EAAE;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAIlC,aAAa,CAAC,QAAQ,CAAC,EAAE;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;CAGnC"}

package/dist/mastodon/MastodonSocialClient.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MastodonSocialClient = void 0;
+/**
+ *
+ */
+class MastodonSocialClient {
+    message = 'MastodonSocialClient is not yet supported in @hardlydifficult/social. Use provider type "x" for now.';
+    getPost(_postId) {
+        throw new Error(this.message);
+    }
+    getTimeline(_options) {
+        throw new Error(this.message);
+    }
+    getLikedPosts(_options) {
+        throw new Error(this.message);
+    }
+}
+exports.MastodonSocialClient = MastodonSocialClient;
+//# sourceMappingURL=MastodonSocialClient.js.map

package/dist/mastodon/MastodonSocialClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MastodonSocialClient.js","sourceRoot":"","sources":["../../src/mastodon/MastodonSocialClient.ts"],"names":[],"mappings":";;;AAGA;;GAEG;AACH,MAAa,oBAAoB;IACd,OAAO,GACtB,sGAAsG,CAAC;IAEzG,OAAO,CAAC,OAAe;QACrB,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,WAAW,CAAC,QAEX;QACC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,aAAa,CAAC,QAEb;QACC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;CACF;AAnBD,oDAmBC"}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+export type Provider = "x";
+export interface XConfig {
+    readonly type: "x";
+    readonly bearerToken?: string;
+    readonly maxResults?: number;
+}
+export type SocialConfig = XConfig;
+export interface SocialAuthor {
+    readonly id: string;
+    readonly username: string;
+    readonly displayName: string;
+}
+export interface SocialPostMetrics {
+    readonly likes: number;
+    readonly replies: number;
+    readonly reposts: number;
+}
+export interface SocialPost {
+    readonly id: string;
+    readonly text: string;
+    readonly createdAt: string;
+    readonly url: string;
+    readonly author: SocialAuthor;
+    readonly metrics: SocialPostMetrics;
+}
+export interface LikeNotification {
+    readonly post: SocialPost;
+    readonly seenAt: string;
+}
+export interface LikeWatcherOptions {
+    readonly pollIntervalMs?: number;
+    readonly onLike: (notification: LikeNotification) => void;
+    readonly onError?: (error: Error) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC;AAE3B,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC3C"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/x/XSocialClient.d.ts

@@ -0,0 +1,24 @@
+import type { SocialProviderClient } from "../SocialProviderClient.js";
+import type { SocialPost, XConfig } from "../types.js";
+/**
+ *
+ */
+export declare class XSocialClient implements SocialProviderClient {
+    private readonly bearerToken;
+    private readonly maxResults;
+    constructor(config: XConfig);
+    getPost(postId: string): Promise<SocialPost | null>;
+    getTimeline(options?: {
+        maxResults?: number;
+    }): Promise<readonly SocialPost[]>;
+    getLikedPosts(options?: {
+        maxResults?: number;
+    }): Promise<readonly SocialPost[]>;
+    private buildQuery;
+    private request;
+    private readSingleTweet;
+    private readTweetList;
+    private isTweet;
+    private normalizeTweet;
+}
+//# sourceMappingURL=XSocialClient.d.ts.map

package/dist/x/XSocialClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XSocialClient.d.ts","sourceRoot":"","sources":["../../src/x/XSocialClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AA2BvD;;GAEG;AACH,qBAAa,aAAc,YAAW,oBAAoB;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,OAAO;IASrB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAYnD,WAAW,CAAC,OAAO,CAAC,EAAE;QAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAU5B,aAAa,CAAC,OAAO,CAAC,EAAE;QAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAUlC,OAAO,CAAC,UAAU;YAWJ,OAAO;IAgBrB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,cAAc;CAoBvB"}

package/dist/x/XSocialClient.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XSocialClient = void 0;
+/**
+ *
+ */
+class XSocialClient {
+    bearerToken;
+    maxResults;
+    constructor(config) {
+        this.bearerToken = config.bearerToken ?? process.env.X_BEARER_TOKEN ?? "";
+        this.maxResults = config.maxResults ?? 25;
+        if (this.bearerToken.length === 0) {
+            throw new Error("X bearer token is required. Set X_BEARER_TOKEN.");
+        }
+    }
+    async getPost(postId) {
+        const response = await this.request(`/tweets/${postId}${this.buildQuery()}`);
+        const tweet = this.readSingleTweet(response.data);
+        if (!tweet) {
+            return null;
+        }
+        return this.normalizeTweet(tweet, response.includes?.users ?? []);
+    }
+    async getTimeline(options) {
+        const response = await this.request(`/users/me/timelines/reverse_chronological${this.buildQuery(options?.maxResults)}`);
+        return this.readTweetList(response.data).map((tweet) => this.normalizeTweet(tweet, response.includes?.users ?? []));
+    }
+    async getLikedPosts(options) {
+        const response = await this.request(`/users/me/liked_tweets${this.buildQuery(options?.maxResults)}`);
+        return this.readTweetList(response.data).map((tweet) => this.normalizeTweet(tweet, response.includes?.users ?? []));
+    }
+    buildQuery(maxResults) {
+        const params = new URLSearchParams({
+            expansions: "author_id",
+            "tweet.fields": "created_at,public_metrics",
+            "user.fields": "name,username",
+            max_results: String(maxResults ?? this.maxResults),
+        });
+        return `?${params.toString()}`;
+    }
+    async request(path) {
+        const response = await fetch(`https://api.x.com/2${path}`, {
+            headers: {
+                Authorization: `Bearer ${this.bearerToken}`,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok) {
+            const status = String(response.status);
+            throw new Error(`X API request failed: ${status} ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    readSingleTweet(data) {
+        if (!this.isTweet(data)) {
+            return null;
+        }
+        return data;
+    }
+    readTweetList(data) {
+        if (!Array.isArray(data)) {
+            return [];
+        }
+        return data.filter((item) => this.isTweet(item));
+    }
+    isTweet(value) {
+        if (typeof value !== "object" || value === null) {
+            return false;
+        }
+        const candidate = value;
+        return (typeof candidate.id === "string" && typeof candidate.text === "string");
+    }
+    normalizeTweet(tweet, users) {
+        const author = users.find((user) => user.id === tweet.author_id);
+        return {
+            id: tweet.id,
+            text: tweet.text,
+            createdAt: tweet.created_at ?? new Date(0).toISOString(),
+            url: `https://x.com/${author?.username ?? "i"}/status/${tweet.id}`,
+            author: {
+                id: author?.id ?? tweet.author_id ?? "unknown",
+                username: author?.username ?? "unknown",
+                displayName: author?.name ?? author?.username ?? "Unknown",
+            },
+            metrics: {
+                likes: tweet.public_metrics?.like_count ?? 0,
+                replies: tweet.public_metrics?.reply_count ?? 0,
+                reposts: tweet.public_metrics?.retweet_count ?? 0,
+            },
+        };
+    }
+}
+exports.XSocialClient = XSocialClient;
+//# sourceMappingURL=XSocialClient.js.map

package/dist/x/XSocialClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XSocialClient.js","sourceRoot":"","sources":["../../src/x/XSocialClient.ts"],"names":[],"mappings":"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"}

package/dist/x/index.d.ts

@@ -0,0 +1,2 @@
+export { XSocialClient } from "./XSocialClient.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/x/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/x/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/x/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XSocialClient = void 0;
+var XSocialClient_js_1 = require("./XSocialClient.js");
+Object.defineProperty(exports, "XSocialClient", { enumerable: true, get: function () { return XSocialClient_js_1.XSocialClient; } });
+//# sourceMappingURL=index.js.map

package/dist/x/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/x/index.ts"],"names":[],"mappings":";;;AAAA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@hardlydifficult/social",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "25.2.3",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  }
+}