facebook-leads-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. facebook_leads_cli-0.1.0/.env.example +34 -0
  2. facebook_leads_cli-0.1.0/.gitignore +6 -0
  3. facebook_leads_cli-0.1.0/PKG-INFO +171 -0
  4. facebook_leads_cli-0.1.0/README.md +161 -0
  5. facebook_leads_cli-0.1.0/pyproject.toml +21 -0
  6. facebook_leads_cli-0.1.0/src/__init__.py +1 -0
  7. facebook_leads_cli-0.1.0/src/client.py +360 -0
  8. facebook_leads_cli-0.1.0/src/conversions.py +229 -0
  9. facebook_leads_cli-0.1.0/src/fb.py +401 -0
  10. facebook_leads_cli-0.1.0/tests/test_cli.py +80 -0
  11. facebook_leads_cli-0.1.0/tests/test_client.py +125 -0
facebook_leads_cli-0.1.0/.env.example ADDED
@@ -0,0 +1,34 @@
1
+ # Facebook API Configuration
2
+ # Copy this file to .env and fill in your actual values:
3
+ # cp .env.example .env
4
+
5
+ # Required: Facebook App access token
6
+ # Get from: https://developers.facebook.com/tools/explorer/
7
+ FB_ACCESS_TOKEN=your_access_token_here
8
+
9
+ # Required for Lead Gen API: Facebook Page ID
10
+ # Find in your page's About section or Page Settings
11
+ FB_PAGE_ID=your_page_id_here
12
+
13
+ # Recommended for Lead Gen API: Page access token
14
+ # Required for pages_read_engagement permission
15
+ # Generate in Graph API Explorer with your page selected
16
+ FB_PAGE_ACCESS_TOKEN=your_page_access_token_here
17
+
18
+ # Required for Conversions API: Facebook Pixel ID
19
+ # Find in Events Manager: https://business.facebook.com/events_manager
20
+ FB_PIXEL_ID=your_pixel_id_here
21
+
22
+ # Optional: Facebook App ID
23
+ # Find in App Dashboard: https://developers.facebook.com/apps/
24
+ FB_APP_ID=your_app_id_here
25
+
26
+ # Optional: Test event code for debugging Conversions API
27
+ # Generate in Events Manager > Test Events tab
28
+ FB_TEST_EVENT_CODE=your_test_event_code_here
29
+ FB_ACCESS_TOKEN=your_access_token
30
+ FB_PIXEL_ID=your_pixel_id
31
+ FB_PAGE_ID=your_page_id
32
+ FB_PAGE_ACCESS_TOKEN=your_page_access_token
33
+ FB_APP_ID=your_app_id
34
+ FB_TEST_EVENT_CODE=your_test_event_code
facebook_leads_cli-0.1.0/.gitignore ADDED
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .env
5
+ .DS_Store
6
+ uv.lock
facebook_leads_cli-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,171 @@
1
+ Metadata-Version: 2.4
2
+ Name: facebook-leads-cli
3
+ Version: 0.1.0
4
+ Summary: Facebook Lead Ads and Conversions API CLI
5
+ Requires-Python: >=3.10
6
+ Requires-Dist: facebook-business>=24.0.1
7
+ Requires-Dist: python-dotenv>=1.0.0
8
+ Requires-Dist: requests>=2.31.0
9
+ Description-Content-Type: text/markdown
10
+
11
+ # fb-cli
12
+
13
+ A Python CLI tool for Facebook Lead Ads and Conversions API. Fetch leads, manage forms, and send conversion events.
14
+
15
+ ## Installation
16
+
17
+ Requires [UV](https://docs.astral.sh/uv/) (fast Python package manager).
18
+
19
+ ```bash
20
+ # Install UV (if not already installed)
21
+ brew install uv
22
+
23
+ # Clone and sync dependencies
24
+ git clone https://github.com/thaddeus-git/fb-cli.git
25
+ cd fb-cli
26
+ uv sync
27
+ ```
28
+
29
+ ## Quick Start
30
+
31
+ ```bash
32
+ # Run tests
33
+ uv run python -m unittest discover tests/
34
+
35
+ # Run CLI
36
+ uv run python src/fb.py --help
37
+ ```
38
+
39
+ ## Configuration
40
+
41
+ Set environment variables (copy from `.env.example`):
42
+
43
+ ```bash
44
+ export FB_ACCESS_TOKEN="your_access_token"
45
+ export FB_PIXEL_ID="your_pixel_id"
46
+ export FB_PAGE_ID="your_page_id"
47
+ export FB_PAGE_ACCESS_TOKEN="your_page_access_token" # Recommended for lead retrieval
48
+ ```
49
+
50
+ ## Commands
51
+
52
+ ### Authentication & Status
53
+
54
+ | Command | Description |
55
+ |---------|-------------|
56
+ | `fb whoami` | Verify token, show connected account info |
57
+ | `fb status` | System health check (API connectivity) |
58
+
59
+ ### Lead Gen API
60
+
61
+ | Command | Description |
62
+ |---------|-------------|
63
+ | `fb forms list` | List all lead forms on page |
64
+ | `fb forms show <form_id>` | Show form details |
65
+ | `fb leads fetch --days=7` | Fetch leads from all forms |
66
+ | `fb leads list --form=<id>` | List leads from specific form |
67
+
68
+ ### Conversions API
69
+
70
+ | Command | Description |
71
+ |---------|-------------|
72
+ | `fb conversions test` | Send a test event to verify setup |
73
+ | `fb conversions send --file=data.json` | Send conversion events from file |
74
+
75
+ ## Examples
76
+
77
+ ### Verify Authentication
78
+
79
+ ```bash
80
+ fb whoami
81
+ ```
82
+
83
+ Example output:
84
+ ```
85
+ ✓ Authentication successful!
86
+
87
+ Page: My Business Page (ID: 107534675430395)
88
+ Pixel ID: 1758183674728645
89
+ ```
90
+
91
+ ### Check System Health
92
+
93
+ ```bash
94
+ fb status
95
+ ```
96
+
97
+ Example output:
98
+ ```
99
+ Checking Facebook API connectivity...
100
+
101
+ ✓ Authentication: OK
102
+ Page: My Business Page
103
+ ✓ Lead Gen API: OK
104
+ Forms found: 10
105
+ ✓ Conversions API: Configured
106
+ Pixel ID: 1758183674728645
107
+
108
+ ✓ System health check complete
109
+ ```
110
+
111
+ ### Fetch Recent Leads
112
+
113
+ ```bash
114
+ fb leads fetch --days=7
115
+ ```
116
+
117
+ Example output:
118
+ ```
119
+ Fetching leads from the past 7 days (limit: 1000 per form)...
120
+
121
+ ✓ Fetched 42 lead(s)
122
+
123
+ ID Created Form
124
+ -----------------------------------------------------------------
125
+ 9876543210987654 2026-02-25T10:30:00 Contact Form
126
+ 8765432109876543 2026-02-24T15:45:00 Newsletter Signup
127
+ ```
128
+
129
+ ### Export Leads as JSON
130
+
131
+ ```bash
132
+ fb leads fetch --days=7 --json > leads.json
133
+ ```
134
+
135
+ ### Send Test Conversion
136
+
137
+ ```bash
138
+ fb conversions test
139
+ ```
140
+
141
+ Example output:
142
+ ```
143
+ Sending test conversion event...
144
+
145
+ ✓ Test event sent successfully!
146
+ Response: {'events_received': 1, 'event_ids': ['test_12345']}
147
+ ```
148
+
149
+ ## Environment Variables
150
+
151
+ | Variable | Required | Description |
152
+ |----------|----------|-------------|
153
+ | `FB_ACCESS_TOKEN` | Yes | Facebook API access token |
154
+ | `FB_PIXEL_ID` | Yes* | Pixel ID for Conversions API |
155
+ | `FB_PAGE_ID` | Yes* | Page ID for Lead Gen API |
156
+ | `FB_PAGE_ACCESS_TOKEN` | Recommended | Page token for lead retrieval |
157
+ | `FB_APP_ID` | Optional | App ID for additional API calls |
158
+ | `FB_TEST_EVENT_CODE` | Optional | Test event code for debugging |
159
+
160
+ *At least one of `FB_PIXEL_ID` or `FB_PAGE_ID` must be set.
161
+
162
+ ## Getting Your Access Token
163
+
164
+ 1. Go to [Facebook Graph API Explorer](https://developers.facebook.com/tools/explorer/)
165
+ 2. Select your app
166
+ 3. Click "Generate Access Token"
167
+ 4. Copy the token and set it as `FB_ACCESS_TOKEN`
168
+
169
+ ## License
170
+
171
+ MIT
facebook_leads_cli-0.1.0/README.md ADDED
@@ -0,0 +1,161 @@
1
+ # fb-cli
2
+
3
+ A Python CLI tool for Facebook Lead Ads and Conversions API. Fetch leads, manage forms, and send conversion events.
4
+
5
+ ## Installation
6
+
7
+ Requires [UV](https://docs.astral.sh/uv/) (fast Python package manager).
8
+
9
+ ```bash
10
+ # Install UV (if not already installed)
11
+ brew install uv
12
+
13
+ # Clone and sync dependencies
14
+ git clone https://github.com/thaddeus-git/fb-cli.git
15
+ cd fb-cli
16
+ uv sync
17
+ ```
18
+
19
+ ## Quick Start
20
+
21
+ ```bash
22
+ # Run tests
23
+ uv run python -m unittest discover tests/
24
+
25
+ # Run CLI
26
+ uv run python src/fb.py --help
27
+ ```
28
+
29
+ ## Configuration
30
+
31
+ Set environment variables (copy from `.env.example`):
32
+
33
+ ```bash
34
+ export FB_ACCESS_TOKEN="your_access_token"
35
+ export FB_PIXEL_ID="your_pixel_id"
36
+ export FB_PAGE_ID="your_page_id"
37
+ export FB_PAGE_ACCESS_TOKEN="your_page_access_token" # Recommended for lead retrieval
38
+ ```
39
+
40
+ ## Commands
41
+
42
+ ### Authentication & Status
43
+
44
+ | Command | Description |
45
+ |---------|-------------|
46
+ | `fb whoami` | Verify token, show connected account info |
47
+ | `fb status` | System health check (API connectivity) |
48
+
49
+ ### Lead Gen API
50
+
51
+ | Command | Description |
52
+ |---------|-------------|
53
+ | `fb forms list` | List all lead forms on page |
54
+ | `fb forms show <form_id>` | Show form details |
55
+ | `fb leads fetch --days=7` | Fetch leads from all forms |
56
+ | `fb leads list --form=<id>` | List leads from specific form |
57
+
58
+ ### Conversions API
59
+
60
+ | Command | Description |
61
+ |---------|-------------|
62
+ | `fb conversions test` | Send a test event to verify setup |
63
+ | `fb conversions send --file=data.json` | Send conversion events from file |
64
+
65
+ ## Examples
66
+
67
+ ### Verify Authentication
68
+
69
+ ```bash
70
+ fb whoami
71
+ ```
72
+
73
+ Example output:
74
+ ```
75
+ ✓ Authentication successful!
76
+
77
+ Page: My Business Page (ID: 107534675430395)
78
+ Pixel ID: 1758183674728645
79
+ ```
80
+
81
+ ### Check System Health
82
+
83
+ ```bash
84
+ fb status
85
+ ```
86
+
87
+ Example output:
88
+ ```
89
+ Checking Facebook API connectivity...
90
+
91
+ ✓ Authentication: OK
92
+ Page: My Business Page
93
+ ✓ Lead Gen API: OK
94
+ Forms found: 10
95
+ ✓ Conversions API: Configured
96
+ Pixel ID: 1758183674728645
97
+
98
+ ✓ System health check complete
99
+ ```
100
+
101
+ ### Fetch Recent Leads
102
+
103
+ ```bash
104
+ fb leads fetch --days=7
105
+ ```
106
+
107
+ Example output:
108
+ ```
109
+ Fetching leads from the past 7 days (limit: 1000 per form)...
110
+
111
+ ✓ Fetched 42 lead(s)
112
+
113
+ ID Created Form
114
+ -----------------------------------------------------------------
115
+ 9876543210987654 2026-02-25T10:30:00 Contact Form
116
+ 8765432109876543 2026-02-24T15:45:00 Newsletter Signup
117
+ ```
118
+
119
+ ### Export Leads as JSON
120
+
121
+ ```bash
122
+ fb leads fetch --days=7 --json > leads.json
123
+ ```
124
+
125
+ ### Send Test Conversion
126
+
127
+ ```bash
128
+ fb conversions test
129
+ ```
130
+
131
+ Example output:
132
+ ```
133
+ Sending test conversion event...
134
+
135
+ ✓ Test event sent successfully!
136
+ Response: {'events_received': 1, 'event_ids': ['test_12345']}
137
+ ```
138
+
139
+ ## Environment Variables
140
+
141
+ | Variable | Required | Description |
142
+ |----------|----------|-------------|
143
+ | `FB_ACCESS_TOKEN` | Yes | Facebook API access token |
144
+ | `FB_PIXEL_ID` | Yes* | Pixel ID for Conversions API |
145
+ | `FB_PAGE_ID` | Yes* | Page ID for Lead Gen API |
146
+ | `FB_PAGE_ACCESS_TOKEN` | Recommended | Page token for lead retrieval |
147
+ | `FB_APP_ID` | Optional | App ID for additional API calls |
148
+ | `FB_TEST_EVENT_CODE` | Optional | Test event code for debugging |
149
+
150
+ *At least one of `FB_PIXEL_ID` or `FB_PAGE_ID` must be set.
151
+
152
+ ## Getting Your Access Token
153
+
154
+ 1. Go to [Facebook Graph API Explorer](https://developers.facebook.com/tools/explorer/)
155
+ 2. Select your app
156
+ 3. Click "Generate Access Token"
157
+ 4. Copy the token and set it as `FB_ACCESS_TOKEN`
158
+
159
+ ## License
160
+
161
+ MIT
facebook_leads_cli-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,21 @@
1
+ [project]
2
+ name = "facebook-leads-cli"
3
+ version = "0.1.0"
4
+ description = "Facebook Lead Ads and Conversions API CLI"
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ dependencies = [
8
+ "facebook-business>=24.0.1",
9
+ "python-dotenv>=1.0.0",
10
+ "requests>=2.31.0",
11
+ ]
12
+
13
+ [project.scripts]
14
+ fb = "src.fb:main"
15
+
16
+ [build-system]
17
+ requires = ["hatchling"]
18
+ build-backend = "hatchling.build"
19
+
20
+ [tool.hatch.build.targets.wheel]
21
+ packages = ["src"]
facebook_leads_cli-0.1.0/src/__init__.py ADDED
@@ -0,0 +1 @@
1
+ # Facebook CLI src module