cutmeshort 1.0.1__tar.gz

cutmeshort-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CutMeShort
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cutmeshort-1.0.1/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: cutmeshort
+Version: 1.0.1
+Summary: CutMeShort CMS API
+Author-email: CutMeShort <support@cutmeshort.com>
+Project-URL: Repository, https://github.com/Cut-Me-Short/cms-python
+Keywords: CutMeShort,CMS,Python SDK
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urllib3<3.0.0,>=2.1.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4.7.1
+Dynamic: license-file
+
+# CutMeShort CMS Python SDK
+
+The CutMeShort Python SDK enables you to track lead and sales events in your **Python applications** with ease.
+
+It provides a clean and simple interface for:
+
+* Lead tracking
+* Deferred lead attribution (`mode="deferred"`)
+* Sale / purchase tracking
+
+---
+
+## Installation
+
+### Install from PyPI (recommended)
+
+```bash
+pip install cutmeshort
+```
+
+---
+
+## 📋 Requirements
+
+* Python 3.9+
+
+---
+
+## Setup
+
+Set your Bearer token:
+
+```bash
+export CMS_BEARER_TOKEN="your_jwt_token"
+```
+
+---
+
+## ⚡ Quick Start
+
+```python
+import os
+from cutmeshort import CMSClient
+
+client = CMSClient(token=os.environ["CMS_BEARER_TOKEN"])
+
+response = client.track_lead(
+    click_id="id_123",
+    event_name="signup_started",
+    customer_external_id="user_42",
+)
+
+print(response)
+```
+
+---
+
+## What is Deferred Attribution?
+
+Deferred attribution allows you to track a click **before knowing the customer identity**.
+
+### Flow:
+
+1. **First Call (store association)**
+
+   * Send `click_id` + `mode="deferred"`
+
+2. **Later Calls**
+
+   * Send normal events without `click_id`
+   * Backend automatically resolves mapping
+
+### Example Use Case
+
+User clicks an ad → later signs up → events get linked automatically.
+
+---
+
+## Track a Lead Event (Standard Flow)
+
+```python
+from cutmeshort import CMSClient
+
+client = CMSClient(token="your_jwt_token")
+
+response = client.track_lead(
+    click_id="id_123",
+    event_name="signup_started",
+    customer_external_id="user_42",
+    customer_name="Jane Doe",            # optional
+    customer_email="jane@example.com",   # optional
+)
+
+print(response)
+```
+
+---
+
+## Track a Lead Event (Deferred Flow)
+
+### Step 1: Store association
+
+```python
+response = client.track_lead(
+    click_id="id_123",
+    event_name="lead_captured",
+    customer_external_id="user_42",
+    mode="deferred",
+)
+```
+
+### Step 2: Send follow-up event
+
+```python
+response = client.track_lead(
+    event_name="kyc_completed",
+    customer_external_id="user_42",
+)
+```
+
+---
+
+## Track a Sale Event
+
+```python
+from cutmeshort import CMSClient
+
+client = CMSClient(token="your_jwt_token")
+
+response = client.track_sale(
+    click_id="id_123",
+    event_name="purchase_completed",
+    customer_external_id="user_42",
+    invoice_id="inv_987",
+    amount=4999,          # in cents
+    currency="USD",       # 3-letter code
+    customer_email="jane@example.com",  # optional
+)
+
+print(response)
+```
+
+---
+
+## CMSClient Reference
+
+### Initialization
+
+```python
+from cutmeshort import CMSClient
+
+client = CMSClient(token="your_jwt_token")
+
+# Custom base URL
+client = CMSClient(token="your_jwt_token", host="https://custom.com")
+```
+
+---
+
+## Methods
+
+### `track_lead()`
+
+Track a lead event.
+
+**Required:**
+
+* `event_name: str`
+* `customer_external_id: str`
+
+**Optional:**
+
+* `click_id: str`
+* `customer_name: str`
+* `customer_email: str`
+* `customer_avatar: str`
+* `timestamp: datetime`
+* `mode: str` (`"deferred"` only)
+
+---
+
+### `track_sale()`
+
+Track a sale event.
+
+**Required:**
+
+* `click_id: str`
+* `event_name: str`
+* `customer_external_id: str`
+* `invoice_id: str`
+* `amount: int` (in cents)
+* `currency: str` (3-letter code)
+
+**Optional:**
+
+* `customer_name: str`
+* `customer_email: str`
+* `customer_avatar: str`
+* `timestamp: datetime`
+
+---
+
+## Response Format
+
+All methods return a dictionary:
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "message": "Event tracked successfully",
+  "data": {...}
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "error": "Validation failed",
+  "status_code": 422
+}
+```
+
+---
+
+## Error Handling
+
+Errors are handled internally by the SDK.
+
+```python
+response = client.track_lead(...)
+
+if response.get("success"):
+    print("Success:", response["data"])
+else:
+    print("Error:", response)
+```
+
+---
+
+## 📊 Payload Reference
+
+### Lead Payload
+
+**Required:**
+
+* `event_name`
+* `customer_external_id`
+
+**Conditionally Required:**
+
+* `click_id` (for standard flow or deferred setup)
+
+**Optional:**
+
+* `timestamp`
+* `customer_name`
+* `customer_email`
+* `customer_avatar`
+* `mode` (`"deferred"` only)
+
+---
+
+### Sale Payload
+
+**Required:**
+
+* `click_id`
+* `event_name`
+* `customer_external_id`
+* `invoice_id`
+* `amount`
+* `currency`
+
+**Optional:**
+
+* `timestamp`
+* `customer_name`
+* `customer_email`
+* `customer_avatar`
+
+---
+
+## Example Scripts
+
+- [examples/lead_example.py](examples/lead_example.py) – Lead tracking and deferred attribution
+- [examples/sale_example.py](examples/sale_example.py) – Sale tracking

cutmeshort-1.0.1/README.md

@@ -0,0 +1,291 @@
+# CutMeShort CMS Python SDK
+
+The CutMeShort Python SDK enables you to track lead and sales events in your **Python applications** with ease.
+
+It provides a clean and simple interface for:
+
+* Lead tracking
+* Deferred lead attribution (`mode="deferred"`)
+* Sale / purchase tracking
+
+---
+
+## Installation
+
+### Install from PyPI (recommended)
+
+```bash
+pip install cutmeshort
+```
+
+---
+
+## 📋 Requirements
+
+* Python 3.9+
+
+---
+
+## Setup
+
+Set your Bearer token:
+
+```bash
+export CMS_BEARER_TOKEN="your_jwt_token"
+```
+
+---
+
+## ⚡ Quick Start
+
+```python
+import os
+from cutmeshort import CMSClient
+
+client = CMSClient(token=os.environ["CMS_BEARER_TOKEN"])
+
+response = client.track_lead(
+    click_id="id_123",
+    event_name="signup_started",
+    customer_external_id="user_42",
+)
+
+print(response)
+```
+
+---
+
+## What is Deferred Attribution?
+
+Deferred attribution allows you to track a click **before knowing the customer identity**.
+
+### Flow:
+
+1. **First Call (store association)**
+
+   * Send `click_id` + `mode="deferred"`
+
+2. **Later Calls**
+
+   * Send normal events without `click_id`
+   * Backend automatically resolves mapping
+
+### Example Use Case
+
+User clicks an ad → later signs up → events get linked automatically.
+
+---
+
+## Track a Lead Event (Standard Flow)
+
+```python
+from cutmeshort import CMSClient
+
+client = CMSClient(token="your_jwt_token")
+
+response = client.track_lead(
+    click_id="id_123",
+    event_name="signup_started",
+    customer_external_id="user_42",
+    customer_name="Jane Doe",            # optional
+    customer_email="jane@example.com",   # optional
+)
+
+print(response)
+```
+
+---
+
+## Track a Lead Event (Deferred Flow)
+
+### Step 1: Store association
+
+```python
+response = client.track_lead(
+    click_id="id_123",
+    event_name="lead_captured",
+    customer_external_id="user_42",
+    mode="deferred",
+)
+```
+
+### Step 2: Send follow-up event
+
+```python
+response = client.track_lead(
+    event_name="kyc_completed",
+    customer_external_id="user_42",
+)
+```
+
+---
+
+## Track a Sale Event
+
+```python
+from cutmeshort import CMSClient
+
+client = CMSClient(token="your_jwt_token")
+
+response = client.track_sale(
+    click_id="id_123",
+    event_name="purchase_completed",
+    customer_external_id="user_42",
+    invoice_id="inv_987",
+    amount=4999,          # in cents
+    currency="USD",       # 3-letter code
+    customer_email="jane@example.com",  # optional
+)
+
+print(response)
+```
+
+---
+
+## CMSClient Reference
+
+### Initialization
+
+```python
+from cutmeshort import CMSClient
+
+client = CMSClient(token="your_jwt_token")
+
+# Custom base URL
+client = CMSClient(token="your_jwt_token", host="https://custom.com")
+```
+
+---
+
+## Methods
+
+### `track_lead()`
+
+Track a lead event.
+
+**Required:**
+
+* `event_name: str`
+* `customer_external_id: str`
+
+**Optional:**
+
+* `click_id: str`
+* `customer_name: str`
+* `customer_email: str`
+* `customer_avatar: str`
+* `timestamp: datetime`
+* `mode: str` (`"deferred"` only)
+
+---
+
+### `track_sale()`
+
+Track a sale event.
+
+**Required:**
+
+* `click_id: str`
+* `event_name: str`
+* `customer_external_id: str`
+* `invoice_id: str`
+* `amount: int` (in cents)
+* `currency: str` (3-letter code)
+
+**Optional:**
+
+* `customer_name: str`
+* `customer_email: str`
+* `customer_avatar: str`
+* `timestamp: datetime`
+
+---
+
+## Response Format
+
+All methods return a dictionary:
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "message": "Event tracked successfully",
+  "data": {...}
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "error": "Validation failed",
+  "status_code": 422
+}
+```
+
+---
+
+## Error Handling
+
+Errors are handled internally by the SDK.
+
+```python
+response = client.track_lead(...)
+
+if response.get("success"):
+    print("Success:", response["data"])
+else:
+    print("Error:", response)
+```
+
+---
+
+## 📊 Payload Reference
+
+### Lead Payload
+
+**Required:**
+
+* `event_name`
+* `customer_external_id`
+
+**Conditionally Required:**
+
+* `click_id` (for standard flow or deferred setup)
+
+**Optional:**
+
+* `timestamp`
+* `customer_name`
+* `customer_email`
+* `customer_avatar`
+* `mode` (`"deferred"` only)
+
+---
+
+### Sale Payload
+
+**Required:**
+
+* `click_id`
+* `event_name`
+* `customer_external_id`
+* `invoice_id`
+* `amount`
+* `currency`
+
+**Optional:**
+
+* `timestamp`
+* `customer_name`
+* `customer_email`
+* `customer_avatar`
+
+---
+
+## Example Scripts
+
+- [examples/lead_example.py](examples/lead_example.py) – Lead tracking and deferred attribution
+- [examples/sale_example.py](examples/sale_example.py) – Sale tracking

cutmeshort-1.0.1/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "cutmeshort"
+version = "1.0.1"
+description = "CutMeShort CMS API"
+authors = [
+  {name = "CutMeShort",email = "support@cutmeshort.com"},
+]
+readme = "README.md"
+keywords = ["CutMeShort", "CMS", "Python SDK"]
+requires-python = ">=3.9"
+
+dependencies = [
+  "urllib3>=2.1.0,<3.0.0",
+  "python-dateutil>=2.8.2",
+  "pydantic>=2",
+  "typing-extensions>=4.7.1",
+]
+
+[project.urls]
+Repository = "https://github.com/Cut-Me-Short/cms-python"
+
+[tool.poetry]
+requires-poetry = ">=2.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">= 7.2.1"
+pytest-cov = ">= 2.8.1"
+tox = ">= 3.9.0"
+flake8 = ">= 4.0.0"
+types-python-dateutil = ">= 2.8.19.14"
+mypy = ">= 1.5"
+
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["cutmeshort*"]
+
+[tool.pylint.'MESSAGES CONTROL']
+extension-pkg-whitelist = "pydantic"
+
+[tool.mypy]
+files = [
+  "cutmeshort",
+  "src/test",
+]
+# TODO: enable "strict" once all these individual checks are passing
+# strict = true
+
+# List from: https://mypy.readthedocs.io/en/stable/existing_code.html#introduce-stricter-options
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+## Getting these passing should be easy
+strict_equality = true
+extra_checks = true
+
+## Strongly recommend enabling this one as soon as you can
+check_untyped_defs = true
+
+## These shouldn't be too much additional work, but may be tricky to
+## get passing if you use a lot of untyped libraries
+disallow_subclassing_any = true
+disallow_untyped_decorators = true
+disallow_any_generics = true
+
+### These next few are various gradations of forcing use of type annotations
+#disallow_untyped_calls = true
+#disallow_incomplete_defs = true
+#disallow_untyped_defs = true
+#
+### This one isn't too hard to get passing, but return on investment is lower
+#no_implicit_reexport = true
+#
+### This one can be tricky to get passing if you use a lot of untyped libraries
+#warn_return_any = true
+
+[[tool.mypy.overrides]]
+module = [
+  "cutmeshort.configuration",
+]
+warn_unused_ignores = true
+strict_equality = true
+extra_checks = true
+check_untyped_defs = true
+disallow_subclassing_any = true
+disallow_untyped_decorators = true
+disallow_any_generics = true
+disallow_untyped_calls = true
+disallow_incomplete_defs = true
+disallow_untyped_defs = true
+no_implicit_reexport = true
+warn_return_any = true

cutmeshort-1.0.1/setup.cfg

@@ -0,0 +1,7 @@
+[flake8]
+max-line-length = 99
+
+[egg_info]
+tag_build = 
+tag_date = 0
+