@hasna/connectors 1.3.36 → 1.3.38

package/dist/.types/connectors/x/src/api/tweets.d.ts

@@ -0,0 +1,175 @@
+import type { XClient } from './client';
+import type { Tweet, XResponse, TweetSearchOptions, TweetLookupOptions } from '../types';
+/**
+ * Tweets API module for X API v2
+ */
+export declare class TweetsApi {
+    private readonly client;
+    constructor(client: XClient);
+    /**
+     * Get a single tweet by ID
+     */
+    get(id: string, options?: TweetLookupOptions): Promise<XResponse<Tweet>>;
+    /**
+     * Get multiple tweets by IDs (up to 100)
+     */
+    getMany(ids: string[], options?: TweetLookupOptions): Promise<XResponse<Tweet[]>>;
+    /**
+     * Search recent tweets (last 7 days)
+     */
+    searchRecent(options: TweetSearchOptions): Promise<XResponse<Tweet[]>>;
+    /**
+     * Get tweet counts for a search query (recent)
+     */
+    countRecent(query: string, options?: {
+        startTime?: string;
+        endTime?: string;
+        granularity?: 'minute' | 'hour' | 'day';
+    }): Promise<XResponse<{
+        total_tweet_count: number;
+        data: {
+            start: string;
+            end: string;
+            tweet_count: number;
+        }[];
+    }>>;
+    /**
+     * Get a user's timeline (tweets they've posted)
+     */
+    getUserTimeline(userId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+        startTime?: string;
+        endTime?: string;
+        sinceId?: string;
+        untilId?: string;
+        excludeReplies?: boolean;
+        excludeRetweets?: boolean;
+    }): Promise<XResponse<Tweet[]>>;
+    /**
+     * Get a user's mentions timeline
+     */
+    getUserMentions(userId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+        startTime?: string;
+        endTime?: string;
+        sinceId?: string;
+        untilId?: string;
+    }): Promise<XResponse<Tweet[]>>;
+    /**
+     * Get users who liked a tweet
+     */
+    getLikingUsers(tweetId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<{
+        id: string;
+        name: string;
+        username: string;
+    }[]>>;
+    /**
+     * Get users who retweeted a tweet
+     */
+    getRetweetedBy(tweetId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<{
+        id: string;
+        name: string;
+        username: string;
+    }[]>>;
+    /**
+     * Get quote tweets for a tweet
+     */
+    getQuoteTweets(tweetId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<Tweet[]>>;
+    /**
+     * Create a tweet
+     * Requires OAuth 2.0 user context with tweet.write scope
+     */
+    create(options: {
+        text: string;
+        mediaIds?: string[];
+        replyToTweetId?: string;
+        quoteTweetId?: string;
+        pollOptions?: string[];
+        pollDurationMinutes?: number;
+    }): Promise<XResponse<{
+        id: string;
+        text: string;
+    }>>;
+    /**
+     * Delete a tweet
+     * Requires OAuth 2.0 user context with tweet.write scope
+     */
+    delete(tweetId: string): Promise<{
+        data: {
+            deleted: boolean;
+        };
+    }>;
+    /**
+     * Like a tweet
+     * Requires OAuth 2.0 user context with like.write scope
+     */
+    like(userId: string, tweetId: string): Promise<{
+        data: {
+            liked: boolean;
+        };
+    }>;
+    /**
+     * Unlike a tweet
+     * Requires OAuth 2.0 user context with like.write scope
+     */
+    unlike(userId: string, tweetId: string): Promise<{
+        data: {
+            liked: boolean;
+        };
+    }>;
+    /**
+     * Retweet a tweet
+     * Requires OAuth 2.0 user context with tweet.write scope
+     */
+    retweet(userId: string, tweetId: string): Promise<{
+        data: {
+            retweeted: boolean;
+        };
+    }>;
+    /**
+     * Remove retweet
+     * Requires OAuth 2.0 user context with tweet.write scope
+     */
+    unretweet(userId: string, tweetId: string): Promise<{
+        data: {
+            retweeted: boolean;
+        };
+    }>;
+    /**
+     * Get user's bookmarks
+     * Requires OAuth 2.0 user context with bookmark.read scope
+     */
+    getBookmarks(userId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<Tweet[]>>;
+    /**
+     * Bookmark a tweet
+     * Requires OAuth 2.0 user context with bookmark.write scope
+     */
+    bookmark(userId: string, tweetId: string): Promise<{
+        data: {
+            bookmarked: boolean;
+        };
+    }>;
+    /**
+     * Remove bookmark
+     * Requires OAuth 2.0 user context with bookmark.write scope
+     */
+    removeBookmark(userId: string, tweetId: string): Promise<{
+        data: {
+            bookmarked: boolean;
+        };
+    }>;
+}

package/dist/.types/connectors/x/src/api/users.d.ts

@@ -0,0 +1,127 @@
+import type { XClient } from './client';
+import type { User, XResponse, UserLookupOptions, Tweet } from '../types';
+/**
+ * Users API module for X API v2
+ */
+export declare class UsersApi {
+    private readonly client;
+    constructor(client: XClient);
+    /**
+     * Get a user by ID
+     */
+    getById(id: string, options?: UserLookupOptions): Promise<XResponse<User>>;
+    /**
+     * Get a user by username
+     */
+    getByUsername(username: string, options?: UserLookupOptions): Promise<XResponse<User>>;
+    /**
+     * Get multiple users by IDs (up to 100)
+     */
+    getMany(ids: string[], options?: UserLookupOptions): Promise<XResponse<User[]>>;
+    /**
+     * Get multiple users by usernames (up to 100)
+     */
+    getManyByUsernames(usernames: string[], options?: UserLookupOptions): Promise<XResponse<User[]>>;
+    /**
+     * Get a user's followers
+     */
+    getFollowers(userId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<User[]>>;
+    /**
+     * Get users that a user is following
+     */
+    getFollowing(userId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<User[]>>;
+    /**
+     * Get tweets liked by a user
+     * Requires OAuth 2.0 user context
+     */
+    getLikedTweets(userId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<Tweet[]>>;
+    /**
+     * Get lists owned by a user
+     */
+    getOwnedLists(userId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<{
+        id: string;
+        name: string;
+    }[]>>;
+    /**
+     * Get lists a user is a member of
+     */
+    getListMemberships(userId: string, options?: {
+        maxResults?: number;
+        paginationToken?: string;
+    }): Promise<XResponse<{
+        id: string;
+        name: string;
+    }[]>>;
+    /**
+     * Get the authenticated user's info
+     * Requires OAuth 2.0 user context with users.read scope
+     */
+    me(): Promise<XResponse<User>>;
+    /**
+     * Follow a user
+     * Requires OAuth 2.0 user context with follows.write scope
+     */
+    follow(userId: string, targetUserId: string): Promise<{
+        data: {
+            following: boolean;
+            pending_follow: boolean;
+        };
+    }>;
+    /**
+     * Unfollow a user
+     * Requires OAuth 2.0 user context with follows.write scope
+     */
+    unfollow(userId: string, targetUserId: string): Promise<{
+        data: {
+            following: boolean;
+        };
+    }>;
+    /**
+     * Block a user
+     * Requires OAuth 2.0 user context with block.write scope
+     */
+    block(userId: string, targetUserId: string): Promise<{
+        data: {
+            blocking: boolean;
+        };
+    }>;
+    /**
+     * Unblock a user
+     * Requires OAuth 2.0 user context with block.write scope
+     */
+    unblock(userId: string, targetUserId: string): Promise<{
+        data: {
+            blocking: boolean;
+        };
+    }>;
+    /**
+     * Mute a user
+     * Requires OAuth 2.0 user context with mute.write scope
+     */
+    mute(userId: string, targetUserId: string): Promise<{
+        data: {
+            muting: boolean;
+        };
+    }>;
+    /**
+     * Unmute a user
+     * Requires OAuth 2.0 user context with mute.write scope
+     */
+    unmute(userId: string, targetUserId: string): Promise<{
+        data: {
+            muting: boolean;
+        };
+    }>;
+}

package/dist/.types/connectors/x/src/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/.types/connectors/x/src/index.d.ts

@@ -0,0 +1,6 @@
+export { X, Connector } from './api';
+export * from './types';
+export { XClient, TweetsApi, UsersApi, MediaApi, OAuth1Client } from './api';
+export { generatePKCE, buildAuthorizationUrl, exchangeCodeForTokens, refreshAccessToken, revokeToken, startCallbackServer, getAuthenticatedUser, OAUTH2_SCOPES, DEFAULT_SCOPES, type OAuth2Config, type OAuth2Tokens, type PKCEChallenge, type OAuth2Scope, } from './api/oauth';
+export { buildOAuth1Header, getRequestToken, buildOAuth1AuthorizationUrl, getAccessToken as exchangeOAuth1Verifier, oauth1Request, type OAuth1Config, type OAuth1Tokens, type OAuth1RequestToken, } from './api/oauth1';
+export { getCurrentProfile, setCurrentProfile, listProfiles, createProfile, deleteProfile, loadProfile, saveProfile, profileExists, getApiKey, setApiKey, getApiSecret, setApiSecret, getBearerToken, setBearerToken, getClientId, setClientId, getClientSecret, setClientSecret, getAccessToken, setAccessToken, getRefreshToken, setRefreshToken, getTokenExpiresAt, setTokenExpiresAt, getTokenScopes, setTokenScopes, isTokenExpired, getOAuth1AccessToken, setOAuth1AccessToken, getOAuth1AccessTokenSecret, setOAuth1AccessTokenSecret, getUserId, setUserId, getUsername, setUsername, saveOAuth2Tokens, saveOAuth1Tokens, clearUserTokens, hasUserAuth, hasOAuth2Auth, hasOAuth1Auth, clearConfig, getConfigDir, } from './utils/config';

package/dist/.types/connectors/x/src/types/index.d.ts

@@ -0,0 +1,156 @@
+export interface XConfig {
+    apiKey: string;
+    apiSecret: string;
+    bearerToken?: string;
+    baseUrl?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    tokenExpiresAt?: number;
+    oauth1AccessToken?: string;
+    oauth1AccessTokenSecret?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+export type AuthMethod = 'app-only' | 'oauth2-user' | 'oauth1-user';
+export interface AuthStatus {
+    method: AuthMethod;
+    isAuthenticated: boolean;
+    userId?: string;
+    username?: string;
+    scopes?: string[];
+    expiresAt?: number;
+    hasOAuth1?: boolean;
+}
+export type OutputFormat = 'json' | 'pretty';
+export interface XMeta {
+    result_count?: number;
+    next_token?: string;
+    previous_token?: string;
+}
+export interface XResponse<T> {
+    data: T;
+    meta?: XMeta;
+    includes?: XIncludes;
+}
+export interface XIncludes {
+    users?: User[];
+    tweets?: Tweet[];
+    places?: Place[];
+    media?: Media[];
+}
+export interface Tweet {
+    id: string;
+    text: string;
+    author_id?: string;
+    created_at?: string;
+    conversation_id?: string;
+    in_reply_to_user_id?: string;
+    referenced_tweets?: ReferencedTweet[];
+    attachments?: TweetAttachments;
+    public_metrics?: TweetPublicMetrics;
+    source?: string;
+    lang?: string;
+    geo?: TweetGeo;
+}
+export interface ReferencedTweet {
+    type: 'retweeted' | 'quoted' | 'replied_to';
+    id: string;
+}
+export interface TweetAttachments {
+    media_keys?: string[];
+    poll_ids?: string[];
+}
+export interface TweetPublicMetrics {
+    retweet_count: number;
+    reply_count: number;
+    like_count: number;
+    quote_count: number;
+    impression_count?: number;
+    bookmark_count?: number;
+}
+export interface TweetGeo {
+    place_id?: string;
+    coordinates?: {
+        type: string;
+        coordinates: [number, number];
+    };
+}
+export interface TweetSearchOptions {
+    query: string;
+    maxResults?: number;
+    nextToken?: string;
+    startTime?: string;
+    endTime?: string;
+    sinceId?: string;
+    untilId?: string;
+    sortOrder?: 'recency' | 'relevancy';
+}
+export interface TweetLookupOptions {
+    expansions?: string[];
+    tweetFields?: string[];
+    userFields?: string[];
+    mediaFields?: string[];
+}
+export interface User {
+    id: string;
+    name: string;
+    username: string;
+    created_at?: string;
+    description?: string;
+    location?: string;
+    url?: string;
+    profile_image_url?: string;
+    verified?: boolean;
+    protected?: boolean;
+    public_metrics?: UserPublicMetrics;
+    pinned_tweet_id?: string;
+}
+export interface UserPublicMetrics {
+    followers_count: number;
+    following_count: number;
+    tweet_count: number;
+    listed_count: number;
+}
+export interface UserLookupOptions {
+    expansions?: string[];
+    userFields?: string[];
+    tweetFields?: string[];
+}
+export interface Place {
+    id: string;
+    name: string;
+    full_name: string;
+    country: string;
+    country_code: string;
+    place_type: string;
+    geo?: {
+        type: string;
+        bbox: number[];
+    };
+}
+export interface Media {
+    media_key: string;
+    type: 'photo' | 'video' | 'animated_gif';
+    url?: string;
+    preview_image_url?: string;
+    width?: number;
+    height?: number;
+    duration_ms?: number;
+    alt_text?: string;
+    public_metrics?: {
+        view_count?: number;
+    };
+}
+export interface XApiErrorDetail {
+    code: string;
+    message: string;
+    field?: string;
+}
+export declare class XApiError extends Error {
+    readonly statusCode: number;
+    readonly errors?: XApiErrorDetail[];
+    constructor(message: string, statusCode: number, errors?: XApiErrorDetail[]);
+}
+export declare const DEFAULT_TWEET_FIELDS: string[];
+export declare const DEFAULT_USER_FIELDS: string[];
+export declare const DEFAULT_TWEET_EXPANSIONS: string[];

package/dist/.types/connectors/x/src/utils/config.d.ts

@@ -0,0 +1,99 @@
+export interface AppCredentials {
+    apiKey?: string;
+    apiSecret?: string;
+    bearerToken?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+export interface ProfileConfig {
+    accessToken?: string;
+    refreshToken?: string;
+    tokenExpiresAt?: number;
+    tokenScopes?: string[];
+    oauth1AccessToken?: string;
+    oauth1AccessTokenSecret?: string;
+    userId?: string;
+    username?: string;
+}
+export declare function setProfileOverride(profile: string | undefined): void;
+export declare function ensureConfigDir(): void;
+/**
+ * Get the current active profile name
+ */
+export declare function getCurrentProfile(): string;
+/**
+ * Set the current active profile
+ */
+export declare function setCurrentProfile(profile: string): void;
+/**
+ * Check if a profile exists
+ */
+export declare function profileExists(profile: string): boolean;
+/**
+ * List all available profiles
+ */
+export declare function listProfiles(): string[];
+/**
+ * Create a new profile
+ */
+export declare function createProfile(profile: string, config?: ProfileConfig): boolean;
+/**
+ * Delete a profile
+ */
+export declare function deleteProfile(profile: string): boolean;
+/**
+ * Load profile config
+ */
+export declare function loadProfile(profile?: string): ProfileConfig;
+/**
+ * Save profile config
+ */
+export declare function saveProfile(config: ProfileConfig, profile?: string): void;
+export declare function getApiKey(): string | undefined;
+export declare function setApiKey(apiKey: string): void;
+export declare function getApiSecret(): string | undefined;
+export declare function setApiSecret(apiSecret: string): void;
+export declare function getBearerToken(): string | undefined;
+export declare function setBearerToken(bearerToken: string): void;
+export declare function getClientId(): string | undefined;
+export declare function setClientId(clientId: string): void;
+export declare function getClientSecret(): string | undefined;
+export declare function setClientSecret(clientSecret: string): void;
+export declare function getAccessToken(): string | undefined;
+export declare function setAccessToken(accessToken: string): void;
+export declare function getRefreshToken(): string | undefined;
+export declare function setRefreshToken(refreshToken: string): void;
+export declare function getTokenExpiresAt(): number | undefined;
+export declare function setTokenExpiresAt(expiresAt: number): void;
+export declare function getTokenScopes(): string[] | undefined;
+export declare function setTokenScopes(scopes: string[]): void;
+export declare function isTokenExpired(): boolean;
+export declare function getOAuth1AccessToken(): string | undefined;
+export declare function setOAuth1AccessToken(token: string): void;
+export declare function getOAuth1AccessTokenSecret(): string | undefined;
+export declare function setOAuth1AccessTokenSecret(secret: string): void;
+export declare function getUserId(): string | undefined;
+export declare function setUserId(userId: string): void;
+export declare function getUsername(): string | undefined;
+export declare function setUsername(username: string): void;
+export declare function saveOAuth2Tokens(tokens: {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    scopes?: string[];
+    userId?: string;
+    username?: string;
+}): void;
+export declare function saveOAuth1Tokens(tokens: {
+    oauthToken: string;
+    oauthTokenSecret: string;
+    userId?: string;
+    screenName?: string;
+}): void;
+export declare function clearUserTokens(): void;
+export declare function hasUserAuth(): boolean;
+export declare function hasOAuth2Auth(): boolean;
+export declare function hasOAuth1Auth(): boolean;
+export declare function clearConfig(): void;
+export declare function getConfigDir(): string;
+export declare function getActiveProfileName(): string;

package/dist/.types/connectors/x/src/utils/output.d.ts

@@ -0,0 +1,8 @@
+export type OutputFormat = 'json' | 'table' | 'pretty';
+export declare function formatOutput(data: unknown, format?: OutputFormat): string;
+export declare function success(message: string): void;
+export declare function error(message: string): void;
+export declare function warn(message: string): void;
+export declare function info(message: string): void;
+export declare function heading(message: string): void;
+export declare function print(data: unknown, format?: OutputFormat): void;

package/dist/.types/src/social/bluesky.d.ts

@@ -0,0 +1,65 @@
+import type { AccountMeResult, AnalyticsPostInput, AnalyticsPostResult, MediaUploadInput, MentionsListInput, MentionsListResult, PostCreateInput, PostCreateResult, PostDeleteInput, PostDeleteResult, SocialAdapter } from "./types";
+/** Structural type so tests can inject a mock transport. */
+export interface BlueskyTransport {
+    me(): Promise<{
+        did: string;
+        handle: string;
+    }>;
+    createPost(opts: {
+        text: string;
+        replyToUri?: string;
+        embed?: Record<string, unknown>;
+    }): Promise<{
+        uri: string;
+        cid: string;
+    }>;
+    deletePost(uri: string): Promise<void>;
+    uploadBlob(data: Buffer | Uint8Array, mimeType: string): Promise<unknown>;
+    listNotifications(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        notifications: Array<{
+            uri: string;
+            reason: string;
+            indexedAt?: string;
+            author?: {
+                did: string;
+                handle: string;
+            };
+            record?: {
+                text?: string;
+                createdAt?: string;
+            };
+        }>;
+    }>;
+    getPosts(uris: string[]): Promise<{
+        posts: Array<{
+            uri: string;
+            likeCount?: number;
+            repostCount?: number;
+            replyCount?: number;
+            quoteCount?: number;
+        }>;
+    }>;
+}
+export interface BlueskyCredentials {
+    identifier: string;
+    appPassword: string;
+    pds?: string;
+}
+export declare class BlueskyAdapter implements SocialAdapter {
+    private readonly bsky;
+    private handle?;
+    constructor(bsky: BlueskyTransport);
+    static fromCredentials(creds: BlueskyCredentials): BlueskyAdapter;
+    private resolveHandle;
+    accountMe(): Promise<AccountMeResult>;
+    postCreate(input: PostCreateInput): Promise<PostCreateResult>;
+    postDelete(input: PostDeleteInput): Promise<PostDeleteResult>;
+    mediaUpload(input: MediaUploadInput): Promise<{
+        mediaId: string;
+    }>;
+    mentionsList(input?: MentionsListInput): Promise<MentionsListResult>;
+    analyticsPost(input: AnalyticsPostInput): Promise<AnalyticsPostResult>;
+}

package/dist/.types/src/social/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Error thrown when a normalized social operation is not supported by a given
+ * connector / network (e.g. Bluesky does not expose post analytics).
+ */
+export declare class ConnectorOperationNotSupported extends Error {
+    readonly connector: string;
+    readonly operation: string;
+    constructor(connector: string, operation: string);
+}

package/dist/.types/src/social/googlebusinessprofile.d.ts

@@ -0,0 +1,40 @@
+import { type FetchLike } from "./http";
+import type { AccountMeResult, AnalyticsPostInput, AnalyticsPostResult, MediaUploadInput, MediaUploadResult, MentionsListInput, MentionsListResult, PostCreateInput, PostCreateResult, PostDeleteInput, PostDeleteResult, SocialAdapter } from "./types";
+export interface GoogleBusinessProfileCredentials {
+    accessToken: string;
+    accountId?: string;
+    locationId?: string;
+}
+/** Google Business Profile `post.create` extras (accountId + locationId required). */
+export interface GoogleBusinessProfilePostExtras {
+    accountId?: string;
+    locationId?: string;
+    /** Call-to-action, e.g. { actionType: "LEARN_MORE", url: "https://..." }. */
+    cta?: {
+        actionType: string;
+        url?: string;
+    };
+}
+/** Google Business Profile `media.upload` extras. */
+export interface GoogleBusinessProfileMediaExtras {
+    accountId?: string;
+    locationId?: string;
+    /** Public URL of the image to attach (GBP media items are created from a URL). */
+    sourceUrl?: string;
+}
+export declare class GoogleBusinessProfileAdapter implements SocialAdapter {
+    private readonly accessToken;
+    private readonly defaultAccountId?;
+    private readonly defaultLocationId?;
+    private readonly fetchImpl;
+    constructor(creds: GoogleBusinessProfileCredentials, fetchImpl?: FetchLike);
+    static fromCredentials(creds: GoogleBusinessProfileCredentials, fetchImpl?: FetchLike): GoogleBusinessProfileAdapter;
+    private headers;
+    private resolveIds;
+    accountMe(): Promise<AccountMeResult>;
+    postCreate(input: PostCreateInput & GoogleBusinessProfilePostExtras): Promise<PostCreateResult>;
+    postDelete(input: PostDeleteInput): Promise<PostDeleteResult>;
+    mediaUpload(input: MediaUploadInput & GoogleBusinessProfileMediaExtras): Promise<MediaUploadResult>;
+    mentionsList(_input?: MentionsListInput): Promise<MentionsListResult>;
+    analyticsPost(_input: AnalyticsPostInput): Promise<AnalyticsPostResult>;
+}