feat(cli): add shorthand read and timeouts

src/lib/cli-args.ts

@@ -0,0 +1,32 @@
+export type CliInvocation = {
+  argv: string[] | null;
+  showHelp: boolean;
+};
+
+const TWEET_URL_REGEX = /^(?:https?:\/\/)?(?:www\.)?(?:twitter\.com|x\.com)\/[^/]+\/status\/\d+/i;
+const TWEET_ID_REGEX = /^\d{8,}$/;
+
+export function looksLikeTweetInput(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  return TWEET_URL_REGEX.test(trimmed) || TWEET_ID_REGEX.test(trimmed);
+}
+
+export function resolveCliInvocation(rawArgs: string[], knownCommands: Set<string>): CliInvocation {
+  if (rawArgs.length === 0) {
+    return { argv: null, showHelp: true };
+  }
+
+  const hasKnownCommand = rawArgs.some((arg) => knownCommands.has(arg));
+
+  if (!hasKnownCommand) {
+    const tweetArgIndex = rawArgs.findIndex(looksLikeTweetInput);
+    if (tweetArgIndex >= 0) {
+      const rewrittenArgs = [...rawArgs];
+      rewrittenArgs.splice(tweetArgIndex, 0, 'read');
+      return { argv: ['node', 'bird', ...rewrittenArgs], showHelp: false };
+    }
+  }
+
+  return { argv: null, showHelp: false };
+}

src/lib/sweetistics-client.ts

@@ -4,6 +4,7 @@ export interface SweetisticsClientOptions {
   baseUrl: string;
   apiKey: string;
   userAgent?: string;
+  timeoutMs?: number;
 }
 
 export interface SweetisticsTweetResult {
@@ -63,13 +64,15 @@ export class SweetisticsClient {
   private readonly baseUrl: string;
   private readonly apiKey: string;
   private readonly userAgent?: string;
+  private readonly timeoutMs: number;
   // Prevent hanging requests; keep Sweetistics calls snappy for CLI users.
-  private static readonly REQUEST_TIMEOUT_MS = 15_000;
+  private static readonly DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
 
   constructor(options: SweetisticsClientOptions) {
     this.baseUrl = normalizeBaseUrl(options.baseUrl);
     this.apiKey = options.apiKey.trim();
     this.userAgent = options.userAgent;
+    this.timeoutMs = options.timeoutMs ?? SweetisticsClient.DEFAULT_REQUEST_TIMEOUT_MS;
     if (!this.apiKey) {
       throw new Error('Sweetistics API key is required');
     }
@@ -310,7 +313,7 @@ export class SweetisticsClient {
           {
             method: 'GET',
             headers,
-          }
+          },
         );
       } catch (error) {
         return { success: false, error: this.normalizeError(error) };
@@ -466,7 +469,11 @@ export class SweetisticsClient {
     return { success: true, tweets };
   }
 
-  async uploadMedia(input: { data: string; mimeType: string; alt?: string }): Promise<{ success: boolean; mediaId?: string; error?: string }> {
+  async uploadMedia(input: {
+    data: string;
+    mimeType: string;
+    alt?: string;
+  }): Promise<{ success: boolean; mediaId?: string; error?: string }> {
     try {
       const response = await this.fetchWithTimeout(`${this.baseUrl}/api/actions/media/upload`, {
         method: 'POST',
@@ -504,8 +511,8 @@ export class SweetisticsClient {
   private async fetchWithTimeout(url: string, init?: RequestInit): Promise<Response> {
     const controller = new AbortController();
     const timeoutId = setTimeout(
-      () => controller.abort(new Error(`Request timed out after ${SweetisticsClient.REQUEST_TIMEOUT_MS}ms`)),
-      SweetisticsClient.REQUEST_TIMEOUT_MS,
+      () => controller.abort(new Error(`Request timed out after ${this.timeoutMs}ms`)),
+      this.timeoutMs,
     );
 
     try {