@mherod/get-cookie 4.4.0 → 4.4.2

package/examples/README.md

@@ -2,24 +2,49 @@
 
 This directory contains example scripts demonstrating various ways to use get-cookie.
 
-## CLI Examples
+## Shell Script Examples
 
-- `cli-examples.sh`: Shows how to use the command-line interface for common tasks
+### Quick Start
+- **`quick-start.sh`**: Essential patterns for immediate use. Perfect for getting started quickly with basic cookie extraction and one-liner curl commands. Includes a reusable shell function for your `.bashrc/.zshrc`.
+
+### Comprehensive Guides
+- **`curl-integration.sh`**: Complete guide for using get-cookie with curl. Covers everything from basic single-cookie requests to complex multi-cookie authentication, POST requests, and cookie validation. Includes colored output and reusable functions.
+
+- **`github-auth.sh`**: Complete GitHub authentication reference. Demonstrates session cookie filtering, endpoint testing, private repository access patterns, and clarifies the difference between web and API authentication.
+
+- **`features-demo.sh`**: All CLI features in one place. Demonstrates profile listing and selection, cookie deduplication, expired cookie filtering, browser-specific extraction, and how to combine features.
+
+### Development Examples
+- **`cli-examples.sh`**: Basic reference for development. Shows how to use the command-line interface for common tasks using `pnpm tsx` for local development.
 
 ## TypeScript/Node.js Examples
 
-- `basic-usage.ts`: Demonstrates basic Node.js module usage
-- `advanced-usage.ts`: Shows advanced usage with browser-specific strategies
+- **`basic-usage.ts`**: Demonstrates basic Node.js module usage
+- **`advanced-usage.ts`**: Shows advanced usage with browser-specific strategies
 
 ## Running the Examples
 
-### CLI Examples
+### Shell Script Examples
 
 ```bash
 # Make the script executable
-chmod +x cli-examples.sh
+chmod +x quick-start.sh
+chmod +x curl-integration.sh
+chmod +x github-auth.sh
+chmod +x features-demo.sh
 
 # Run the examples
+./quick-start.sh          # Quick start guide
+./curl-integration.sh     # Comprehensive curl integration
+./github-auth.sh          # GitHub authentication patterns
+./features-demo.sh        # All CLI features
+```
+
+### Development Examples
+
+```bash
+# For cli-examples.sh (uses pnpm tsx)
+chmod +x cli-examples.sh
 ./cli-examples.sh
 ```
 
@@ -34,4 +59,13 @@ ts-node basic-usage.ts
 ts-node advanced-usage.ts
 ```
 
+## Example File Organization
+
+The examples are organized by use case:
+
+1. **Quick Start** → Start here for immediate practical patterns
+2. **curl Integration** → For HTTP/API automation workflows
+3. **GitHub Auth** → For GitHub-specific authentication scenarios
+4. **Features Demo** → For understanding all CLI capabilities
+
 Note: Make sure you have get-cookie installed either globally or as a project dependency before running the examples.

package/examples/curl-integration.sh

@@ -1,13 +1,10 @@
 #!/bin/bash
 
 # ============================================================================
-# get-cookie + curl Integration Examples
-# 
-# This script demonstrates how to extract browser cookies and use them
-# with curl for authenticated API requests. This is useful for:
-# - Testing APIs with real authentication
-# - Automating tasks that require browser sessions
-# - Debugging authentication issues
+# get-cookie + curl Integration Guide
+# ============================================================================
+# Comprehensive guide for using get-cookie with curl for authenticated
+# HTTP requests. This covers all common patterns from basic to advanced.
 # ============================================================================
 
 # Colors for output
@@ -17,73 +14,118 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
-# Use the globally installed get-cookie binary
-GET_COOKIE="get-cookie"
-
-echo -e "${BLUE}🍪 get-cookie + curl Integration Examples${NC}"
+echo -e "${BLUE}🍪 get-cookie + curl Integration Guide${NC}"
 echo "================================================"
+echo ""
 
 # ============================================================================
-# Example 1: GitHub API with session cookie
+# Example 1: Basic Single Cookie with curl
 # ============================================================================
-echo -e "\n${YELLOW}Example 1: GitHub API Authentication${NC}"
-echo "----------------------------------------"
+echo -e "${YELLOW}1️⃣ Basic Single Cookie Extraction${NC}"
+echo "─────────────────────────────────────"
 
-# Extract GitHub session cookie
 echo -e "${GREEN}Extracting GitHub session cookie...${NC}"
-GITHUB_SESSION=$($GET_COOKIE user_session github.com 2>/dev/null | head -1)
-
-if [ -n "$GITHUB_SESSION" ]; then
-    echo "✓ Found GitHub session cookie"
-    
-    # Get current user info from GitHub API
-    echo -e "\n${GREEN}Fetching user info from GitHub API...${NC}"
-    RESPONSE=$(curl -s -H "Cookie: user_session=$GITHUB_SESSION" \
-                     -H "User-Agent: get-cookie-demo" \
-                     https://api.github.com/user)
-    
-    # Check if we got a valid response
-    if echo "$RESPONSE" | grep -q '"login"'; then
-        USERNAME=$(echo "$RESPONSE" | grep -o '"login":"[^"]*' | cut -d'"' -f4)
-        NAME=$(echo "$RESPONSE" | grep -o '"name":"[^"]*' | cut -d'"' -f4)
-        echo -e "${GREEN}✓ Successfully authenticated as: $NAME (@$USERNAME)${NC}"
+USER_SESSION=$(get-cookie user_session github.com --render 2>/dev/null | head -1)
+
+if [ -n "$USER_SESSION" ]; then
+    echo -e "${GREEN}✓ Found GitHub session cookie${NC}"
+    echo "  Value: ${USER_SESSION:0:30}... (truncated for security)"
+
+    # Test with curl
+    echo -e "\n${GREEN}Testing with GitHub API...${NC}"
+    RESPONSE=$(curl -s \
+        -H "Cookie: $USER_SESSION" \
+        -H "User-Agent: get-cookie-demo" \
+        "https://api.github.com/user")
+
+    LOGIN=$(echo "$RESPONSE" | jq -r '.login // empty' 2>/dev/null)
+    if [ -n "$LOGIN" ]; then
+        echo -e "${GREEN}✓ Authenticated as: @$LOGIN${NC}"
     else
-        echo -e "${RED}✗ Authentication failed - cookie might be expired${NC}"
+        echo -e "${YELLOW}⚠ API may not accept browser cookies (use tokens for API)${NC}"
     fi
 else
     echo -e "${RED}✗ No GitHub session cookie found${NC}"
-    echo "  Make sure you're logged into GitHub in Chrome/Firefox"
+    echo "  Make sure you're logged into GitHub in your browser"
 fi
+echo ""
 
 # ============================================================================
-# Example 2: Multiple cookies for complex authentication
+# Example 2: The Perfect Pattern - Using --url flag
 # ============================================================================
-echo -e "\n${YELLOW}Example 2: Multiple Cookie Authentication${NC}"
-echo "----------------------------------------"
+echo -e "${YELLOW}2️⃣ The Perfect Pattern: --url flag${NC}"
+echo "─────────────────────────────────────────────"
 
-# Some sites require multiple cookies for authentication
-# Extract all GitHub cookies and format for curl
-echo -e "${GREEN}Extracting all GitHub cookies...${NC}"
+echo -e "${GREEN}The --url flag automatically gets all cookies for a URL:${NC}"
+echo ""
+echo -e "${BLUE}curl -H \"Cookie: \$(get-cookie --url <URL> --render)\" <URL>${NC}"
+echo ""
+
+# Reusable function for authenticated requests
+authenticated_curl() {
+    local url=$1
+    shift  # Remove first argument, pass the rest to curl
 
-# Get cookies in JSON format
-COOKIES_JSON=$($GET_COOKIE % github.com --output json 2>/dev/null)
+    # Get cookies for this specific URL
+    local cookies=$(get-cookie --url "$url" --render 2>/dev/null)
+
+    if [ -n "$cookies" ]; then
+        curl -H "Cookie: $cookies" "$@" "$url"
+    else
+        echo "No cookies found for $url" >&2
+        curl "$@" "$url"
+    fi
+}
+
+echo -e "${GREEN}Reusable function for authenticated requests:${NC}"
+cat << 'EOF'
+authenticated_curl() {
+    local url=$1
+    shift
+    curl -H "Cookie: $(get-cookie --url "$url" --render 2>/dev/null)" "$@" "$url"
+}
+
+# Usage:
+#   authenticated_curl https://github.com/settings/profile -s | grep username
+#   authenticated_curl https://example.com/file.pdf -o file.pdf
+EOF
+echo ""
+
+# Test the function
+echo -e "${GREEN}Testing authenticated_curl function:${NC}"
+HTTP_CODE=$(authenticated_curl "https://github.com/settings/profile" -s -o /dev/null -w "%{http_code}" 2>/dev/null)
+if [ "$HTTP_CODE" = "200" ]; then
+    echo -e "${GREEN}✓ Successfully accessed protected page (HTTP 200)${NC}"
+elif [ "$HTTP_CODE" = "302" ]; then
+    echo -e "${YELLOW}⚠ Redirected to login (HTTP 302)${NC}"
+else
+    echo -e "${BLUE}ℹ HTTP $HTTP_CODE${NC}"
+fi
+echo ""
+
+# ============================================================================
+# Example 3: Multiple Cookies for Complex Authentication
+# ============================================================================
+echo -e "${YELLOW}3️⃣ Multiple Cookie Authentication${NC}"
+echo "───────────────────────────────────────"
+
+echo -e "${GREEN}Extracting all GitHub cookies...${NC}"
+COOKIES_JSON=$(get-cookie % github.com --output json 2>/dev/null)
 
 if [ -n "$COOKIES_JSON" ]; then
-    # Count cookies
     COOKIE_COUNT=$(echo "$COOKIES_JSON" | jq 'length')
-    echo "✓ Found $COOKIE_COUNT GitHub cookies"
-    
+    echo -e "${GREEN}✓ Found $COOKIE_COUNT GitHub cookies${NC}"
+
     # Build cookie header with multiple cookies
-    COOKIE_HEADER=$(echo "$COOKIES_JSON" | jq -r '.[] | "\(.name)=\(.value)"' | head -5 | paste -sd '; ')
-    
+    COOKIE_HEADER=$(echo "$COOKIES_JSON" | jq -r '.[] | "\(.name)=\(.value)"' | paste -sd '; ')
+
     if [ -n "$COOKIE_HEADER" ]; then
         echo -e "\n${GREEN}Testing with multiple cookies...${NC}"
-        # Make request with multiple cookies
         STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
                       -H "Cookie: $COOKIE_HEADER" \
                       -H "User-Agent: get-cookie-demo" \
-                      https://github.com/settings/profile)
-        
+                      "https://github.com/settings/profile")
+
         if [ "$STATUS" = "200" ]; then
             echo -e "${GREEN}✓ Successfully accessed protected page (HTTP $STATUS)${NC}"
         else
@@ -93,141 +135,78 @@ if [ -n "$COOKIES_JSON" ]; then
 else
     echo -e "${RED}✗ Failed to extract cookies${NC}"
 fi
+echo ""
 
 # ============================================================================
-# Example 3: Download protected content
+# Example 4: Download Protected Content
 # ============================================================================
-echo -e "\n${YELLOW}Example 3: Download Protected Content${NC}"
-echo "----------------------------------------"
-
-# Example: Download a file that requires authentication
-echo -e "${GREEN}Preparing authenticated download...${NC}"
-
-# Get session cookie for a specific domain
-DOMAIN="github.com"
-SESSION=$($GET_COOKIE user_session $DOMAIN 2>/dev/null | head -1)
-
-if [ -n "$SESSION" ]; then
-    echo "✓ Authentication cookie ready"
-    
-    # Example: Download user's avatar (requires authentication for private profiles)
-    echo -e "\n${GREEN}Example curl command for authenticated download:${NC}"
-    echo -e "${BLUE}curl -H \"Cookie: user_session=\$SESSION\" \\
-     -H \"User-Agent: YourApp\" \\
-     -o avatar.jpg \\
-     https://github.com/username.png${NC}"
-else
-    echo -e "${RED}✗ No session cookie available${NC}"
-fi
-
-# ============================================================================
-# Example 4: Function for easy cookie extraction
-# ============================================================================
-echo -e "\n${YELLOW}Example 4: Reusable Shell Function${NC}"
-echo "----------------------------------------"
-
-# Define a reusable function
-get_cookie_for_curl() {
-    local cookie_name=$1
-    local domain=$2
-    local cookie_value=$($GET_COOKIE "$cookie_name" "$domain" 2>/dev/null | head -1)
-    
-    if [ -n "$cookie_value" ]; then
-        echo "$cookie_name=$cookie_value"
-        return 0
-    else
-        echo ""
-        return 1
-    fi
-}
-
-# Demonstrate the function
-echo -e "${GREEN}Using reusable function to build cookie header...${NC}"
-
-# Build a cookie header with multiple specific cookies
-COOKIE_HEADER=""
-for cookie in "user_session" "dotcom_user" "_gh_sess"; do
-    if cookie_value=$(get_cookie_for_curl "$cookie" "github.com"); then
-        if [ -n "$COOKIE_HEADER" ]; then
-            COOKIE_HEADER="$COOKIE_HEADER; $cookie_value"
-        else
-            COOKIE_HEADER="$cookie_value"
-        fi
-        echo "  ✓ Added $cookie"
-    else
-        echo "  ✗ Skipped $cookie (not found)"
-    fi
-done
+echo -e "${YELLOW}4️⃣ Download Protected Content${NC}"
+echo "───────────────────────────────────"
 
-if [ -n "$COOKIE_HEADER" ]; then
-    echo -e "\n${GREEN}Complete Cookie header for curl:${NC}"
-    echo -e "${BLUE}Cookie: $COOKIE_HEADER${NC}"
-fi
+echo -e "${GREEN}Example: Download a file that requires authentication${NC}"
+echo ""
+echo -e "${BLUE}curl -H \"Cookie: \$(get-cookie --url <URL> --render)\" \\"
+echo "     -H \"User-Agent: YourApp\" \\"
+echo "     -o file.pdf \\"
+echo "     https://example.com/protected/file.pdf${NC}"
+echo ""
 
 # ============================================================================
-# Example 5: POST request with cookies
+# Example 5: POST Request with Authentication
 # ============================================================================
-echo -e "\n${YELLOW}Example 5: POST Request with Authentication${NC}"
-echo "----------------------------------------"
+echo -e "${YELLOW}5️⃣ POST Request with Authentication${NC}"
+echo "─────────────────────────────────────────"
 
 echo -e "${GREEN}Example: Creating a GitHub gist with authentication${NC}"
-
-# Get GitHub session
-SESSION=$($GET_COOKIE user_session github.com 2>/dev/null | head -1)
-CSRF=$($GET_COOKIE _gh_sess github.com 2>/dev/null | head -1)
-
-if [ -n "$SESSION" ]; then
-    echo -e "\n${BLUE}Example POST command:${NC}"
-    cat << 'EOF'
+echo ""
+cat << 'EOF'
 curl -X POST \
-  -H "Cookie: user_session=$SESSION; _gh_sess=$CSRF" \
+  -H "Cookie: $(get-cookie --url https://api.github.com/gists --render)" \
   -H "Content-Type: application/json" \
   -H "User-Agent: get-cookie-demo" \
   -d '{
-    "description": "Created via API",
+    "description": "Created via get-cookie + curl",
     "public": false,
     "files": {
-      "test.txt": {
-        "content": "Hello from get-cookie + curl!"
+      "test.md": {
+        "content": "# Hello from get-cookie!"
       }
     }
   }' \
   https://api.github.com/gists
 EOF
-else
-    echo -e "${RED}✗ Authentication cookies not available${NC}"
-fi
+echo ""
 
 # ============================================================================
-# Example 6: Cookie validation
+# Example 6: Cookie Validation Function
 # ============================================================================
-echo -e "\n${YELLOW}Example 6: Cookie Validation${NC}"
-echo "----------------------------------------"
+echo -e "${YELLOW}6️⃣ Cookie Validation${NC}"
+echo "───────────────────────"
 
 validate_cookie() {
     local domain=$1
     local cookie_name=$2
-    
+
     echo -e "${GREEN}Validating $cookie_name for $domain...${NC}"
-    
+
     # Get cookie with metadata
-    COOKIE_JSON=$($GET_COOKIE "$cookie_name" "$domain" --output json 2>/dev/null)
-    
+    COOKIE_JSON=$(get-cookie "$cookie_name" "$domain" --output json 2>/dev/null)
+
     if [ -n "$COOKIE_JSON" ] && [ "$COOKIE_JSON" != "[]" ]; then
         # Parse cookie details
         EXPIRY=$(echo "$COOKIE_JSON" | jq -r '.[0].expiry' 2>/dev/null)
         BROWSER=$(echo "$COOKIE_JSON" | jq -r '.[0].meta.browser' 2>/dev/null)
         DECRYPTED=$(echo "$COOKIE_JSON" | jq -r '.[0].meta.decrypted' 2>/dev/null)
-        
+
         echo "  ✓ Cookie found"
         echo "    Browser: $BROWSER"
         echo "    Decrypted: $DECRYPTED"
-        
+
         # Check if expired
         if [ "$EXPIRY" != "null" ] && [ "$EXPIRY" != "Infinity" ]; then
             EXPIRY_TIMESTAMP=$(date -d "$EXPIRY" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S" "${EXPIRY%%.*}" +%s 2>/dev/null)
             CURRENT_TIMESTAMP=$(date +%s)
-            
+
             if [ -n "$EXPIRY_TIMESTAMP" ]; then
                 if [ "$EXPIRY_TIMESTAMP" -gt "$CURRENT_TIMESTAMP" ]; then
                     DAYS_LEFT=$(( ($EXPIRY_TIMESTAMP - $CURRENT_TIMESTAMP) / 86400 ))
@@ -250,27 +229,83 @@ validate_cookie() {
 
 # Validate some common cookies
 validate_cookie "github.com" "user_session"
+echo ""
 
 # ============================================================================
-# Tips and Best Practices
+# Example 7: Reusable Shell Function for Multiple Cookies
 # ============================================================================
-echo -e "\n${BLUE}📚 Tips and Best Practices${NC}"
-echo "================================================"
-echo "
-1. ${YELLOW}Security:${NC} Never log or save cookie values in scripts
-2. ${YELLOW}Expiration:${NC} Check cookie expiry before using them
-3. ${YELLOW}User-Agent:${NC} Always set a User-Agent header with curl
-4. ${YELLOW}CSRF Tokens:${NC} Some APIs require CSRF tokens in addition to session cookies
-5. ${YELLOW}Rate Limiting:${NC} Respect API rate limits when using automation
+echo -e "${YELLOW}7️⃣ Reusable Function for Multiple Cookies${NC}"
+echo "───────────────────────────────────────────────"
 
-${GREEN}Example one-liner to test authentication:${NC}
-${BLUE}get-cookie user_session github.com | xargs -I {} curl -s -H \"Cookie: user_session={}\" https://api.github.com/user | jq .login${NC}
+cat << 'EOF'
+get_cookie_for_curl() {
+    local cookie_name=$1
+    local domain=$2
+    local cookie_value=$(get-cookie "$cookie_name" "$domain" --render 2>/dev/null | head -1)
 
-${GREEN}Example to save cookies to a file:${NC}
-${BLUE}get-cookie % domain.com --output json > cookies.json${NC}
+    if [ -n "$cookie_value" ]; then
+        echo "$cookie_value"
+        return 0
+    else
+        echo ""
+        return 1
+    fi
+}
+
+# Build a cookie header with multiple specific cookies
+COOKIE_HEADER=""
+for cookie in "user_session" "dotcom_user" "_gh_sess"; do
+    if cookie_value=$(get_cookie_for_curl "$cookie" "github.com"); then
+        if [ -n "$COOKIE_HEADER" ]; then
+            COOKIE_HEADER="$COOKIE_HEADER; $cookie_value"
+        else
+            COOKIE_HEADER="$cookie_value"
+        fi
+    fi
+done
+
+curl -H "Cookie: $COOKIE_HEADER" https://github.com/settings/profile
+EOF
+echo ""
+
+# ============================================================================
+# Example 8: Using with Other Tools
+# ============================================================================
+echo -e "${YELLOW}8️⃣ Using with Other HTTP Tools${NC}"
+echo "─────────────────────────────────────"
 
-${GREEN}Example to use with wget instead of curl:${NC}
-${BLUE}wget --header=\"Cookie: \$(get-cookie session domain.com)\" https://domain.com/protected${NC}
-"
+echo -e "${GREEN}With wget:${NC}"
+echo -e "${BLUE}wget --header=\"Cookie: \$(get-cookie --url <URL> --render)\" <URL>${NC}"
+echo ""
 
-echo -e "${GREEN}✅ Examples completed!${NC}"
+echo -e "${GREEN}With HTTPie:${NC}"
+echo -e "${BLUE}http GET <URL> Cookie:\"\$(get-cookie --url <URL> --render)\"${NC}"
+echo ""
+
+echo -e "${GREEN}With jq for JSON APIs:${NC}"
+echo -e "${BLUE}curl -H \"Cookie: \$(get-cookie --url <URL> --render)\" <URL> | jq .${NC}"
+echo ""
+
+# ============================================================================
+# Tips and Best Practices
+# ============================================================================
+echo -e "${BLUE}📚 Tips and Best Practices${NC}"
+echo "================================================"
+echo ""
+echo "1. ${YELLOW}Security:${NC} Never log or save cookie values in scripts"
+echo "2. ${YELLOW}Expiration:${NC} Check cookie expiry before using them"
+echo "3. ${YELLOW}User-Agent:${NC} Always set a User-Agent header with curl"
+echo "4. ${YELLOW}CSRF Tokens:${NC} Some APIs require CSRF tokens in addition to session cookies"
+echo "5. ${YELLOW}Rate Limiting:${NC} Respect API rate limits when using automation"
+echo ""
+echo -e "${GREEN}Example one-liner to test authentication:${NC}"
+echo -e "${BLUE}get-cookie --url <URL> --render | xargs -I {} curl -s -H \"Cookie: {}\" <URL> | jq .login${NC}"
+echo ""
+echo -e "${GREEN}Example to save cookies to a file:${NC}"
+echo -e "${BLUE}get-cookie % domain.com --output json > cookies.json${NC}"
+echo ""
+echo -e "${GREEN}Example to use with wget instead of curl:${NC}"
+echo -e "${BLUE}wget --header=\"Cookie: \$(get-cookie --url <URL> --render)\" <URL>${NC}"
+echo ""
+
+echo -e "${GREEN}✅ Integration guide complete!${NC}"