[Feature] Viewing Stories (#179)

## Summary

This PR closes #87 by adding a `instagram-cli stories` command that
renders the new stories view. The behaviour should closely mimic
Instagram web / mobile. **This feature is experimental, see the first
comment below** _Bumps version to 1.3.0._

<img width="1171" height="886" alt="Screenshot 2025-11-22 at 10 43
55 pm"
src="https://github.com/user-attachments/assets/8e8022bf-4a91-47b9-81c8-feae4927429c"
/>

## Data flow

This happens after running the command:

- Use the `reelsTray` endpoint for recommended stories from Meta, this
builds the initial unread stories list (**this list is usually extremely
large!** For example, on my personal account this is nearly 100 items!
It contains all the unread stories that your account has, fetching
everything at once is suicidal 💀 ). `reelsTray` is quite lightweight
because it only contains "metadata" instead of the actual story content
(as opposed to the documentation 😭), we use this to get a list of users
whom we need to check, this is ALSO ranked (it returns a list of ranked
scores)
- The `useStories` hook will then fetch and populate one story, then
prefetch two more using (not awaited) the `getStoryFromUser` function
that calls the `userStory` endpoint, this returns the actual story
content and we cache it by userID so navigating back is fast
- Lazy loading is implemented by returning a `loadMore(index)` callback
from the hook, this loads the next 3 stories but two of them should be
prefetched already so it load the 3rd story from current index.
Prefetching will help reduce loading time
- The Story View will call `loadMore` whenever the user navigates the
list of stories, we group story items by user to display it like a
Carousel. Meanwhile, we send read status for the story by building a
local set of read story IDs, this operation is not awaited.
- `s` key enters Search Mode, where the user types an username (**NOT
display name**) and we search for the corresponding userId then stories
for that user, which gets prepended to the top of the list
- Videos can be opened in the browser as usual

Unironically, the `reelsTray` endpoint name very well describes what
Instagram does and we shall illustrate it with a little bit of AI slop
here. Another piece of daily motivation to migrate to Instagram CLI and
save yourself 😄:

<img width="512" height="512" alt="unknown"
src="https://github.com/user-attachments/assets/65f426ee-339c-4b09-92e3-d9e60083ca3b"
/>

## Type Definitions

- Story is an object that carries image and/or video and metadata
- `StoryReel` is a "Story" that you see as a circle object that you can
click open, it associates a User with a list of Stories
- `ReelMentions` is `Users[]` that indicate the users being mentioned in
the story, monkey patched!

## Chore

- Moved all logger usage to outside of the component and removed all
logger references from useEffect dep list
- Renamed and combined a few CI, made sure that Typescript CI runs on
pushes to main
- Removed all `console.xxx` statements and turned on warning in the
linter, use `logger` whenever possible!
- Refactored media components -- media pane and Split View, shared them
over feed and the new stories view

Author: supreme-gg-gg

.github/workflows/python-publish.yml .github/workflows/publish-python.yml.github/workflows/python-publish.yml renamed to .github/workflows/publish-python.yml

@@ -6,7 +6,7 @@
 # separate terms of service, privacy policy, and support
 # documentation.
 
-name: Build and Upload Python Package
+name: Build and Publish Python Package
 
 on:
   push:

.github/workflows/typescript-publish.yml .github/workflows/publish-ts.yml.github/workflows/typescript-publish.yml renamed to .github/workflows/publish-ts.yml

@@ -1,6 +1,6 @@
 # This workflow will publish the TypeScript package to NPM when a tag matching ts-v*.*.* is pushed
 
-name: Build and Publish TypeScript Package to NPM
+name: Build and Publish TypeScript Package
 
 on:
   push:

.github/workflows/python-versions.yml

@@ -0,0 +1,62 @@
+name: Python linting and e2e tests
+
+on:
+  push:
+    branches: [main]
+    paths: ["instagram/**", "tests/**"]
+  pull_request:
+    branches: [main]
+    paths: ["instagram/**", "tests/**"]
+
+permissions:
+  contents: read
+
+jobs:
+  ruff:
+    name: Lint and Format Python Client (Ruff)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run Ruff linter
+        uses: astral-sh/ruff-action@v3
+        with:
+          version: "0.12.4"
+          args: check --output-format=github
+          # src: "./instagram"
+
+      - name: Run Ruff formatter
+        uses: astral-sh/ruff-action@v3
+        with:
+          version: "0.12.4"
+          args: format --check --diff
+          # src: "./instagram"
+  test:
+    name: Test Python Client
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"] # Add the Python versions you want to test
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+
+      - name: Run tests
+        run: |
+          pytest tests/test.py

.github/workflows/ruff-py.yml

@@ -2,15 +2,20 @@ name: TypeScript linting and e2e tests
 
 # Only triggers on changes to the TypeScript codebase
 on:
+  push:
+    branches:
+      - main
+    paths:
+      - "instagram-ts/**"
   pull_request:
     branches:
-      - ts-migration/main-
       - main
     paths:
       - "instagram-ts/**"
 
 jobs:
   format:
+    name: Lint and Test TypeScript Client
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code

.github/workflows/test-python.yml

@@ -21,12 +21,12 @@ https://github.com/user-attachments/assets/3dd65afe-b0d7-4554-9b3c-1e37111ae27d
 
 ## What does it do?
 
-- We transform Instagram from a brainrot hell into productivity tool
-- We allow you to focus on meaningful conversations
-- We celebrate the art and simplicity of **terminal UI (TUI)**
+Empower yourself to become a 10x Instagrammer by minimizing distractions, enabling 100% keyboard control, and accessing it from any terminal — whether in your VSCode editor or your Linux server.
 
-> [!TIP]
-> Use Instagram with 100% keyboard control - no mouse clicks or touchscreen taps needed! Perfect for developers and Linux users who love staying on the keyboard 🤣
+- Chat with your friends without falling into endless brainrot
+- Stay updated & connected without being exploited for your attention
+- Focus on meaningful conversations and be productive
+- Celebrate the art and simplicity of **terminal UI (TUI)**
 
 ## Typescript Client
 
@@ -41,7 +41,7 @@ For other installation methods, please refer to the [TypeScript Client Documenta
 ### Key Features
 
 - Full support for Windows, Linux, and macOS, modern React-based UI
-- Developer-friendly shortcuts, viewing feed and chatting, in-terminal image rendering
+- Developer-friendly shortcuts, viewing feed and stories, in-terminal image rendering
 - Leverages realtime MQTT-based protocol used by Instagram app for instant notifications and chat
 - Highly performant and much faster than your GUI browser or touchscreen app
 - Works well in all terminal emulators, **including VSCode Integrated Terminal**
@@ -50,8 +50,6 @@ For other installation methods, please refer to the [TypeScript Client Documenta
 
 > The Python client is the original implementation of `instagram-cli`.
 
-The simplest way to get started is to install the package from PyPI if you have Python installed:
-
 ```bash
 pip install instagram-cli
 ```
@@ -85,6 +83,7 @@ instagram-cli auth whoami                      # display current default user
 # Core features
 instagram-cli chat                             # start chat interface
 instagram-cli feed                             # view posts from people you follow
+instagram-cli stories                          # view stories from people you follow
 instagram-cli notify                           # view notifications (inbox, followers, mentions)
 
 # Modify configuration
@@ -95,7 +94,7 @@ instagram-cli config edit                      # open config file in editor
 
 > [!TIP]
 > You can easily manage multiple accounts with Instagram CLI!
-> Your login for each account will be saved **locally** and you can switch between them or run a certain command with a specific account using the `--username` flag.
+> Your login for each account will be saved **locally** and you can switch between them using the `instagram-cli auth switch <username>` command or run a certain command with a specific account using the `--username` flag.
 
 ## Chat Commands
 
@@ -137,8 +136,12 @@ You can view and modify configuration with `instagram-cli config`. The configura
 
 ## Contributing
 
-We welcome contributors! Please see the comprehensive [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to get started, create issues, and submit pull requests. It is very important that you follow these instructions because we manage two different clients in the same repository.
+We welcome contributors! Please see the comprehensive [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to get started, create issues, and submit pull requests. It is very important that you follow these instructions because we manage two different clients in the same repository. _Instagram CLI is NOT meant to be used for bot-behaviours, we will not accept contributions that add such features._
 
 ### Commitment to Open Source
 
 Maintainers behind `instagram-cli` are committed to contributing to the open source community behind frameworks that empower terminal applications, such as `ink`. This includes direct contributions and our sister projects -- [Ink Picture, Ink-native image component](https://github.com/endernoke/ink-picture) and [Wax, Ink routing framework](https://github.com/endernoke/wax).
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=supreme-gg-gg/instagram-cli&type=date&legend=top-left)](https://www.star-history.com/#supreme-gg-gg/instagram-cli&type=date&legend=top-left)

.github/workflows/prettier-ts.yml .github/workflows/test-ts.yml.github/workflows/prettier-ts.yml renamed to .github/workflows/test-ts.yml

@@ -1,6 +1,6 @@
 # Instagram CLI
 
-Welcome to the TypeScript client of the Instagram CLI project. The Typescript client is a successor to the original Python client, built with a modern React-based UI using [Ink](https://github.com/vadimdemedes/ink), with features like image rendering in terminal, checking feed, and using Instagram's native [MQTT protocol](https://mqtt.org/) for messaging to significantly reduce latency and account flags.
+Welcome to the TypeScript client of the Instagram CLI project. The Typescript client is a successor to the original Python client, built with a modern React-based UI using [Ink](https://github.com/vadimdemedes/ink), with features like image rendering in terminal, checking feed and stories, and using Instagram's native [MQTT protocol](https://mqtt.org/) for messaging to significantly reduce latency and account flags.
 
 Full documentation with demo video is [on our GitHub](https://github.com/supreme-gg-gg/instagram-cli).
 
@@ -10,7 +10,7 @@ Full documentation with demo video is [on our GitHub](https://github.com/supreme
 ## Key Features
 
 - Full support for Windows, Linux, and macOS, with modern React-based UI
-- Developer-friendly shortcuts, viewing feed and chatting, in-terminal image rendering
+- Developer-friendly shortcuts, viewing feed, stories, and chatting, in-terminal image rendering
 - Leverages realtime MQTT-based protocol used by Instagram app for instant notifications and chat
 - Highly performant and much faster than your GUI browser or touchscreen app
 - Works well in all terminal emulators, **including VSCode Integrated Terminal**
@@ -38,6 +38,7 @@ instagram-cli auth logout                      # logout and removes session
 # Core features
 instagram-cli chat                             # start chat interface
 instagram-cli feed                             # view posts from people you follow
+instagram-cli stories                          # view stories from people you follow
 instagram-cli notify                           # view notifications (inbox, followers, mentions)
 
 # Modify configuration

README.md

@@ -0,0 +1,122 @@
+# Stories UI & Data Flow Design
+
+## Overview
+
+This document outlines the architecture for fetching and displaying Instagram Stories. The system is designed to be efficient, robust, and maintainable, using a centralized, hook-based approach for data management and a clear, unidirectional data flow.
+
+Key features include on-demand lazy-loading of story media and automatically marking stories as seen as a user navigates through them.
+
+## UI Architecture
+
+The story viewer consists of a two-panel layout within a full-screen terminal view.
+
+```plaintext
+┌────────────────────────────────────────────────────────────────────────┐
+│ ✨ Stories                                                             │
+├──────────────────────────────────┬─────────────────────────────────────┤
+│                                  │                                     │
+│  ┌───────────────────────────┐   │  ┌───────────────────────────────┐  │
+│  │ ➜ user_one (current)      │   │  │ 🖼️ Story Media Display        │  │
+│  │   user_two (seen)         │   │  └───────────────────────────────┘  │
+│  │   user_three              │   │                                     │
+│  │   ...                     │   │  Story 1 of 3                       │
+│  └───────────────────────────┘   │  👤 user_one (timestamp)            │
+│                                  │  Caption text for the current...    │
+│                                  │                                     │
+├──────────────────────────────────┴─────────────────────────────────────┤
+│ Help: j/k: users, h/l: stories, o: open, s: search, Esc: quit          │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+1. **Left Panel (Users List)**: Displays a vertical list of all users who have active stories.
+   - The currently selected user is highlighted.
+   - Users whose stories have been viewed during the session are dimmed.
+2. **Right Panel (Media Display)**:
+   - Displays the current story's image (or a placeholder for video).
+   - Shows metadata, including the user's name, timestamp, and caption.
+   - Indicates the current position within a user's multi-story reel (e.g., "Story 2 of 5").
+
+## Data Flow and State Management
+
+The entire feature is powered by a hook-based architecture that centralizes state and data-fetching logic, ensuring a single source of truth and a predictable, unidirectional data flow.
+
+```mermaid
+graph TD
+    subgraph "UI Layer (Components)"
+        A[Stories Command] --> B(useStories Hook);
+        B --> C{StoryDisplay};
+    end
+
+    subgraph "Logic & Data Layer"
+        B --> D[client.getReelsTray()];
+        B -- "loadMore(index)" --> E[client.getStoriesForUser(id)];
+        C -- "mark as seen" --> F[client.markStoryAsSeen(stories)];
+    end
+
+    subgraph "Instagram API"
+        D --> G[API];
+        E --> G;
+        F --> G;
+    end
+
+    C -- "User navigates to new reel" --> B;
+
+    style B fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+### 1. Centralized `useStories` Hook
+
+The `useStories` hook (`source/ui/hooks/use-stories.ts`) is the brain of the feature. It is responsible for all state management and interactions with the `InstagramClient`.
+
+- **Responsibilities**:
+  1. Initializes the `InstagramClient`.
+  2. On mount, fetches the initial list of users with stories (`reelsTray`).
+  3. Immediately fetches the stories for the first user to ensure the UI is not empty on load.
+  4. Manages all loading and error states for the entire feature.
+  5. Exposes a `loadMore(index)` function for the UI to call for lazy-loading.
+  6. Returns a single state object for the UI to consume.
+- **Returned State Object**:
+
+  ```typescript
+  interface UseStoriesReturn {
+  	reels: StoryReel[];
+  	isLoading: boolean;
+  	error?: string;
+  	loadMore: (index: number) => void;
+  	client: InstagramClient;
+  }
+  ```
+
+### 2. Component Responsibilities
+
+- **`Stories` (Command)**: The top-level command component. Its only job is to invoke the `useStories` hook and pass the resulting state and functions down to the `StoryView`.
+- **`StoryView` (View)**: A simple container component that provides necessary context (like `TerminalInfoProvider`) and passes props to the main display component.
+- **`StoryDisplay` (Component)**: A "presentational" component that handles all UI rendering and user interaction. It receives data via props and calls functions like `loadMore` and `markStoryAsSeen` in response to user input, but it contains no business logic itself.
+
+## Key Features Implementation
+
+### Lazy-Loading Stories
+
+To minimize initial load time and API usage, story media is lazy-loaded on demand.
+
+1.  **Initial Load**: The `useStories` hook first calls `client.getReelsTray()` to get the list of users. It then immediately calls `loadMore(0)` to pre-fetch stories for the first user in the list.
+2.  **On-Demand Loading**: The `StoryDisplay` component contains a `useEffect` hook that watches the selected user index. When the user navigates to a new user whose stories have not yet been loaded (`reel.stories.length === 0`), it calls the `loadMore(index)` function passed down from the `useStories` hook.
+
+### Marking Stories as Seen
+
+Stories are automatically marked as seen as the user views them.
+
+1. **Trigger**: A `useEffect` in `StoryDisplay` is triggered whenever the `currentReel` (the selected user's story collection) changes.
+2. **API Call**: The effect calls `client.markStoryAsSeen(currentReel.stories)`, which sends a single API request to mark all stories in that reel as viewed.
+3. **Duplicate Prevention**: To prevent sending redundant API calls for the same reel within a single session, the component maintains a local `seenReels` state (`Set<number>`). The API call is only made if the user's ID is not already in this set.
+4. **Visual Feedback**: Usernames in the left-hand list are dimmed once their stories have been marked as seen.
+
+## Navigation and Key Bindings
+
+- **`j` / `Down Arrow`**: Navigate down the list of users.
+- **`k` / `Up Arrow`**: Navigate up the list of users.
+- **`l` / `Right Arrow`**: Navigate to the next story within a user's reel.
+- **`h` / `Left Arrow`**: Navigate to the previous story within a user's reel.
+- **`s`**: Enter search mode to find a specific user's stories.
+- **`o`**: Open the current story's media (image or video) in the default system browser/viewer.
+- **`Esc`**: Exit the story viewer.