django-shopify-kit 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.
- django_shopify_kit-0.1.0/PKG-INFO +183 -0
- django_shopify_kit-0.1.0/README.md +160 -0
- django_shopify_kit-0.1.0/django_shopify_kit.egg-info/PKG-INFO +183 -0
- django_shopify_kit-0.1.0/django_shopify_kit.egg-info/SOURCES.txt +25 -0
- django_shopify_kit-0.1.0/django_shopify_kit.egg-info/dependency_links.txt +1 -0
- django_shopify_kit-0.1.0/django_shopify_kit.egg-info/requires.txt +4 -0
- django_shopify_kit-0.1.0/django_shopify_kit.egg-info/top_level.txt +1 -0
- django_shopify_kit-0.1.0/pyproject.toml +45 -0
- django_shopify_kit-0.1.0/setup.cfg +4 -0
- django_shopify_kit-0.1.0/shopify_kit/__init__.py +0 -0
- django_shopify_kit-0.1.0/shopify_kit/apps.py +34 -0
- django_shopify_kit-0.1.0/shopify_kit/checks.py +48 -0
- django_shopify_kit-0.1.0/shopify_kit/event_bus.py +114 -0
- django_shopify_kit-0.1.0/shopify_kit/events.py +43 -0
- django_shopify_kit-0.1.0/shopify_kit/handlers.py +47 -0
- django_shopify_kit-0.1.0/shopify_kit/legacy_tasks.py +63 -0
- django_shopify_kit-0.1.0/shopify_kit/models.py +94 -0
- django_shopify_kit-0.1.0/shopify_kit/referrals.py +44 -0
- django_shopify_kit-0.1.0/shopify_kit/services/__init__.py +0 -0
- django_shopify_kit-0.1.0/shopify_kit/services/crm.py +54 -0
- django_shopify_kit-0.1.0/shopify_kit/tasks.py +48 -0
- django_shopify_kit-0.1.0/tests/test_checks.py +32 -0
- django_shopify_kit-0.1.0/tests/test_crm.py +65 -0
- django_shopify_kit-0.1.0/tests/test_event_bus.py +102 -0
- django_shopify_kit-0.1.0/tests/test_handlers.py +116 -0
- django_shopify_kit-0.1.0/tests/test_models.py +126 -0
- django_shopify_kit-0.1.0/tests/test_referrals.py +69 -0
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: django_shopify_kit
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Event bus, shop lifecycle events and CRM wiring for Django apps built on django_shopify_app
|
|
5
|
+
Author: Santiago Fernandez
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Classifier: Framework :: Django
|
|
8
|
+
Classifier: Framework :: Django :: 5.2
|
|
9
|
+
Classifier: Framework :: Django :: 6.0
|
|
10
|
+
Classifier: Framework :: Django :: 6.1
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
Requires-Dist: Django<7,>=5.2
|
|
20
|
+
Requires-Dist: django_shopify_app[celery]>=2.20.0
|
|
21
|
+
Requires-Dist: django-crm-events
|
|
22
|
+
Requires-Dist: requests>=2.25
|
|
23
|
+
|
|
24
|
+
# django-shopify-kit
|
|
25
|
+
|
|
26
|
+
The layer between [django_shopify_app](https://pypi.org/project/django_shopify_app/) and your Shopify app: an event bus, shop lifecycle events, and handlers that send those events to your CRM.
|
|
27
|
+
|
|
28
|
+
- **`shopify_kit.event_bus`**: emit events from model methods; handlers run after the transaction commits.
|
|
29
|
+
- **`ShopKitMixin`** for your shop model: emits `ShopInstalled`, `ShopUserLoggedIn`, `ShopUninstalled` and `ShopSaved`, and has the CRM methods.
|
|
30
|
+
- **Handlers**, registered at startup, that store the shop's GID and send installs, logins, uninstalls and plan price changes to the CRM through Celery.
|
|
31
|
+
|
|
32
|
+
## Requirements
|
|
33
|
+
|
|
34
|
+
- Python 3.10+ and Django 5.2 through 6.1
|
|
35
|
+
- django_shopify_app 2.20.0+ with its `celery` extra, and `SHOPIFY_SHOP_MODEL` set
|
|
36
|
+
- Celery
|
|
37
|
+
- [django-crm-events](https://pypi.org/project/django-crm-events/), configured with its own settings
|
|
38
|
+
- Optional: django_shopify_pricing, for the plan price handler
|
|
39
|
+
|
|
40
|
+
## Installation
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install django-shopify-kit
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Add the app:
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
INSTALLED_APPS = [
|
|
50
|
+
# ...
|
|
51
|
+
"shopify_app",
|
|
52
|
+
"shopify_kit",
|
|
53
|
+
"shops",
|
|
54
|
+
]
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
List `ShopKitMixin` before `ShopBase` in your shop model, and subclass `ShopUserBase` for the shop's users:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from shopify_app.models import ShopBase, ShopUserBase
|
|
61
|
+
from shopify_kit.models import ShopKitMixin
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class Shop(ShopKitMixin, ShopBase):
|
|
65
|
+
...
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class User(ShopUserBase):
|
|
69
|
+
...
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Then run `makemigrations` and `migrate`. `ShopKitMixin` includes django_shopify_app's `ShopLifecycleMixin`, which adds `status`, `installed_at` and `uninstalled_at`. `manage.py check` reports a shop model without the mixin (`shopify_kit.E001`) or with `ShopBase` listed first (`shopify_kit.E002`).
|
|
73
|
+
|
|
74
|
+
## Events
|
|
75
|
+
|
|
76
|
+
`ShopKitMixin` overrides four methods of the shop model and emits an event from each:
|
|
77
|
+
|
|
78
|
+
| Method | Event | When |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| `installed(request=None)` | `ShopInstalled(shop, request)` | Once per install. django_shopify_app calls `installed()` for every token it acquires; only the call that claims the install emits |
|
|
81
|
+
| `on_user_login(user_data, request=None)` | `ShopUserLoggedIn(shop, user, user_data, request)` | A staff user opened the app. The user is stored first, through `shop.users` |
|
|
82
|
+
| `uninstall()` | `ShopUninstalled(shop)` | After the shop's credentials are cleared |
|
|
83
|
+
| `save()` | `ShopSaved(shop)` | Every save |
|
|
84
|
+
|
|
85
|
+
Register your own handlers from an `AppConfig.ready()`:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from django.apps import AppConfig
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class OrdersConfig(AppConfig):
|
|
92
|
+
name = "orders"
|
|
93
|
+
|
|
94
|
+
def ready(self) -> None:
|
|
95
|
+
from shopify_kit.event_bus import register_handler
|
|
96
|
+
from shopify_kit.events import ShopInstalled
|
|
97
|
+
|
|
98
|
+
from .handlers import import_orders
|
|
99
|
+
|
|
100
|
+
register_handler(ShopInstalled, import_orders)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- Handlers run from `transaction.on_commit`, so a Celery task a handler queues sees the committed data. Outside a transaction they run right away.
|
|
104
|
+
- `register_handler` takes the event class, not its dotted name, and raises once startup is over: request threads read the registry without a lock.
|
|
105
|
+
|
|
106
|
+
### Emitting your own events
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
from dataclasses import dataclass
|
|
110
|
+
|
|
111
|
+
from django.utils.decorators import method_decorator
|
|
112
|
+
from shopify_kit.event_bus import Event, use_event_bus
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@dataclass
|
|
116
|
+
class RewardRedeemed(Event):
|
|
117
|
+
reward: "Reward"
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class Reward(models.Model):
|
|
121
|
+
@method_decorator(use_event_bus)
|
|
122
|
+
def redeem(self, *, events: list[Event]) -> None:
|
|
123
|
+
...
|
|
124
|
+
events.append(RewardRedeemed(reward=self))
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`use_event_bus` passes the method a new `events` list and dispatches what it appends once the method returns. Keep `events` keyword-only and without a default.
|
|
128
|
+
|
|
129
|
+
## What the package does on each event
|
|
130
|
+
|
|
131
|
+
| Event | Handler |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `ShopInstalled` | Stores the shop's GID (`shop.ensure_shopify_gid()`), sends the install to the CRM, and reports it to the partners service |
|
|
134
|
+
| `ShopUserLoggedIn` | Sends the login to the CRM |
|
|
135
|
+
| `ShopUninstalled` | Sends the uninstall to the CRM |
|
|
136
|
+
| django_shopify_pricing's `subscription_price_changed` | Sends the new price to the CRM. Connected only when `shopify_pricing` is installed |
|
|
137
|
+
|
|
138
|
+
The CRM calls and the GID run in Celery tasks (`shopify_kit.tasks`). The CRM methods on the mixin (`crm_on_install()`, `crm_on_login()`, `crm_on_uninstall()`, `crm_on_billing_plan_change()`) read the shop's name, email, phone and country from the GraphQL Admin API. If Shopify refuses the request, they send the shop's domain alone.
|
|
139
|
+
|
|
140
|
+
### Partners service
|
|
141
|
+
|
|
142
|
+
An install is posted to a partners service, with the merchant's IP for referral tracking, when all three settings are set:
|
|
143
|
+
|
|
144
|
+
| Setting | Description |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `SHOPIFY_KIT_PARTNERS_URL` | The endpoint that receives the install |
|
|
147
|
+
| `SHOPIFY_KIT_PARTNERS_API_KEY` | Its API key |
|
|
148
|
+
| `SHOPIFY_KIT_PARTNERS_APP_ID` | The app's ID in the partners service |
|
|
149
|
+
|
|
150
|
+
Without them nothing is sent. The call has a timeout, and an error is logged, never raised.
|
|
151
|
+
|
|
152
|
+
## The uninstall webhook
|
|
153
|
+
|
|
154
|
+
Queue django_shopify_app's task from your webhook callback; it calls `shop.uninstall()`, which emits `ShopUninstalled`:
|
|
155
|
+
|
|
156
|
+
```python
|
|
157
|
+
from shopify_app.tasks import uninstall_shop
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def webhook_entry(shopify_domain, topic, data, attributes=None):
|
|
161
|
+
if topic == "app/uninstalled":
|
|
162
|
+
uninstall_shop.delay(shopify_domain)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Moving an app that has its own copies
|
|
166
|
+
|
|
167
|
+
An app cloned from django-shopify-app-base before this package has the same tasks under `shops.tasks.*`. During the deploy that moves it, tasks queued under those names would be dropped. List the old names for that one release:
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
CELERY_IMPORTS = ["shopify_kit.legacy_tasks"]
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## Development
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
python -m venv .venv
|
|
177
|
+
.venv/bin/pip install -e . pytest pytest-django
|
|
178
|
+
.venv/bin/pytest
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Releasing
|
|
182
|
+
|
|
183
|
+
Bump `version` in `pyproject.toml`, add the entry to `CHANGES.txt` and push to `main`. Once the tests pass, `.github/workflows/release.yml` publishes that version to PyPI and tags a GitHub release. PyPI never accepts the same version twice, so a bad release is fixed with a new version.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# django-shopify-kit
|
|
2
|
+
|
|
3
|
+
The layer between [django_shopify_app](https://pypi.org/project/django_shopify_app/) and your Shopify app: an event bus, shop lifecycle events, and handlers that send those events to your CRM.
|
|
4
|
+
|
|
5
|
+
- **`shopify_kit.event_bus`**: emit events from model methods; handlers run after the transaction commits.
|
|
6
|
+
- **`ShopKitMixin`** for your shop model: emits `ShopInstalled`, `ShopUserLoggedIn`, `ShopUninstalled` and `ShopSaved`, and has the CRM methods.
|
|
7
|
+
- **Handlers**, registered at startup, that store the shop's GID and send installs, logins, uninstalls and plan price changes to the CRM through Celery.
|
|
8
|
+
|
|
9
|
+
## Requirements
|
|
10
|
+
|
|
11
|
+
- Python 3.10+ and Django 5.2 through 6.1
|
|
12
|
+
- django_shopify_app 2.20.0+ with its `celery` extra, and `SHOPIFY_SHOP_MODEL` set
|
|
13
|
+
- Celery
|
|
14
|
+
- [django-crm-events](https://pypi.org/project/django-crm-events/), configured with its own settings
|
|
15
|
+
- Optional: django_shopify_pricing, for the plan price handler
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install django-shopify-kit
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Add the app:
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
INSTALLED_APPS = [
|
|
27
|
+
# ...
|
|
28
|
+
"shopify_app",
|
|
29
|
+
"shopify_kit",
|
|
30
|
+
"shops",
|
|
31
|
+
]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
List `ShopKitMixin` before `ShopBase` in your shop model, and subclass `ShopUserBase` for the shop's users:
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
from shopify_app.models import ShopBase, ShopUserBase
|
|
38
|
+
from shopify_kit.models import ShopKitMixin
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class Shop(ShopKitMixin, ShopBase):
|
|
42
|
+
...
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class User(ShopUserBase):
|
|
46
|
+
...
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Then run `makemigrations` and `migrate`. `ShopKitMixin` includes django_shopify_app's `ShopLifecycleMixin`, which adds `status`, `installed_at` and `uninstalled_at`. `manage.py check` reports a shop model without the mixin (`shopify_kit.E001`) or with `ShopBase` listed first (`shopify_kit.E002`).
|
|
50
|
+
|
|
51
|
+
## Events
|
|
52
|
+
|
|
53
|
+
`ShopKitMixin` overrides four methods of the shop model and emits an event from each:
|
|
54
|
+
|
|
55
|
+
| Method | Event | When |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| `installed(request=None)` | `ShopInstalled(shop, request)` | Once per install. django_shopify_app calls `installed()` for every token it acquires; only the call that claims the install emits |
|
|
58
|
+
| `on_user_login(user_data, request=None)` | `ShopUserLoggedIn(shop, user, user_data, request)` | A staff user opened the app. The user is stored first, through `shop.users` |
|
|
59
|
+
| `uninstall()` | `ShopUninstalled(shop)` | After the shop's credentials are cleared |
|
|
60
|
+
| `save()` | `ShopSaved(shop)` | Every save |
|
|
61
|
+
|
|
62
|
+
Register your own handlers from an `AppConfig.ready()`:
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from django.apps import AppConfig
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class OrdersConfig(AppConfig):
|
|
69
|
+
name = "orders"
|
|
70
|
+
|
|
71
|
+
def ready(self) -> None:
|
|
72
|
+
from shopify_kit.event_bus import register_handler
|
|
73
|
+
from shopify_kit.events import ShopInstalled
|
|
74
|
+
|
|
75
|
+
from .handlers import import_orders
|
|
76
|
+
|
|
77
|
+
register_handler(ShopInstalled, import_orders)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- Handlers run from `transaction.on_commit`, so a Celery task a handler queues sees the committed data. Outside a transaction they run right away.
|
|
81
|
+
- `register_handler` takes the event class, not its dotted name, and raises once startup is over: request threads read the registry without a lock.
|
|
82
|
+
|
|
83
|
+
### Emitting your own events
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
from dataclasses import dataclass
|
|
87
|
+
|
|
88
|
+
from django.utils.decorators import method_decorator
|
|
89
|
+
from shopify_kit.event_bus import Event, use_event_bus
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
@dataclass
|
|
93
|
+
class RewardRedeemed(Event):
|
|
94
|
+
reward: "Reward"
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class Reward(models.Model):
|
|
98
|
+
@method_decorator(use_event_bus)
|
|
99
|
+
def redeem(self, *, events: list[Event]) -> None:
|
|
100
|
+
...
|
|
101
|
+
events.append(RewardRedeemed(reward=self))
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`use_event_bus` passes the method a new `events` list and dispatches what it appends once the method returns. Keep `events` keyword-only and without a default.
|
|
105
|
+
|
|
106
|
+
## What the package does on each event
|
|
107
|
+
|
|
108
|
+
| Event | Handler |
|
|
109
|
+
|---|---|
|
|
110
|
+
| `ShopInstalled` | Stores the shop's GID (`shop.ensure_shopify_gid()`), sends the install to the CRM, and reports it to the partners service |
|
|
111
|
+
| `ShopUserLoggedIn` | Sends the login to the CRM |
|
|
112
|
+
| `ShopUninstalled` | Sends the uninstall to the CRM |
|
|
113
|
+
| django_shopify_pricing's `subscription_price_changed` | Sends the new price to the CRM. Connected only when `shopify_pricing` is installed |
|
|
114
|
+
|
|
115
|
+
The CRM calls and the GID run in Celery tasks (`shopify_kit.tasks`). The CRM methods on the mixin (`crm_on_install()`, `crm_on_login()`, `crm_on_uninstall()`, `crm_on_billing_plan_change()`) read the shop's name, email, phone and country from the GraphQL Admin API. If Shopify refuses the request, they send the shop's domain alone.
|
|
116
|
+
|
|
117
|
+
### Partners service
|
|
118
|
+
|
|
119
|
+
An install is posted to a partners service, with the merchant's IP for referral tracking, when all three settings are set:
|
|
120
|
+
|
|
121
|
+
| Setting | Description |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `SHOPIFY_KIT_PARTNERS_URL` | The endpoint that receives the install |
|
|
124
|
+
| `SHOPIFY_KIT_PARTNERS_API_KEY` | Its API key |
|
|
125
|
+
| `SHOPIFY_KIT_PARTNERS_APP_ID` | The app's ID in the partners service |
|
|
126
|
+
|
|
127
|
+
Without them nothing is sent. The call has a timeout, and an error is logged, never raised.
|
|
128
|
+
|
|
129
|
+
## The uninstall webhook
|
|
130
|
+
|
|
131
|
+
Queue django_shopify_app's task from your webhook callback; it calls `shop.uninstall()`, which emits `ShopUninstalled`:
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
from shopify_app.tasks import uninstall_shop
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def webhook_entry(shopify_domain, topic, data, attributes=None):
|
|
138
|
+
if topic == "app/uninstalled":
|
|
139
|
+
uninstall_shop.delay(shopify_domain)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Moving an app that has its own copies
|
|
143
|
+
|
|
144
|
+
An app cloned from django-shopify-app-base before this package has the same tasks under `shops.tasks.*`. During the deploy that moves it, tasks queued under those names would be dropped. List the old names for that one release:
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
CELERY_IMPORTS = ["shopify_kit.legacy_tasks"]
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## Development
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
python -m venv .venv
|
|
154
|
+
.venv/bin/pip install -e . pytest pytest-django
|
|
155
|
+
.venv/bin/pytest
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Releasing
|
|
159
|
+
|
|
160
|
+
Bump `version` in `pyproject.toml`, add the entry to `CHANGES.txt` and push to `main`. Once the tests pass, `.github/workflows/release.yml` publishes that version to PyPI and tags a GitHub release. PyPI never accepts the same version twice, so a bad release is fixed with a new version.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: django_shopify_kit
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Event bus, shop lifecycle events and CRM wiring for Django apps built on django_shopify_app
|
|
5
|
+
Author: Santiago Fernandez
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Classifier: Framework :: Django
|
|
8
|
+
Classifier: Framework :: Django :: 5.2
|
|
9
|
+
Classifier: Framework :: Django :: 6.0
|
|
10
|
+
Classifier: Framework :: Django :: 6.1
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
Requires-Dist: Django<7,>=5.2
|
|
20
|
+
Requires-Dist: django_shopify_app[celery]>=2.20.0
|
|
21
|
+
Requires-Dist: django-crm-events
|
|
22
|
+
Requires-Dist: requests>=2.25
|
|
23
|
+
|
|
24
|
+
# django-shopify-kit
|
|
25
|
+
|
|
26
|
+
The layer between [django_shopify_app](https://pypi.org/project/django_shopify_app/) and your Shopify app: an event bus, shop lifecycle events, and handlers that send those events to your CRM.
|
|
27
|
+
|
|
28
|
+
- **`shopify_kit.event_bus`**: emit events from model methods; handlers run after the transaction commits.
|
|
29
|
+
- **`ShopKitMixin`** for your shop model: emits `ShopInstalled`, `ShopUserLoggedIn`, `ShopUninstalled` and `ShopSaved`, and has the CRM methods.
|
|
30
|
+
- **Handlers**, registered at startup, that store the shop's GID and send installs, logins, uninstalls and plan price changes to the CRM through Celery.
|
|
31
|
+
|
|
32
|
+
## Requirements
|
|
33
|
+
|
|
34
|
+
- Python 3.10+ and Django 5.2 through 6.1
|
|
35
|
+
- django_shopify_app 2.20.0+ with its `celery` extra, and `SHOPIFY_SHOP_MODEL` set
|
|
36
|
+
- Celery
|
|
37
|
+
- [django-crm-events](https://pypi.org/project/django-crm-events/), configured with its own settings
|
|
38
|
+
- Optional: django_shopify_pricing, for the plan price handler
|
|
39
|
+
|
|
40
|
+
## Installation
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install django-shopify-kit
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Add the app:
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
INSTALLED_APPS = [
|
|
50
|
+
# ...
|
|
51
|
+
"shopify_app",
|
|
52
|
+
"shopify_kit",
|
|
53
|
+
"shops",
|
|
54
|
+
]
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
List `ShopKitMixin` before `ShopBase` in your shop model, and subclass `ShopUserBase` for the shop's users:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from shopify_app.models import ShopBase, ShopUserBase
|
|
61
|
+
from shopify_kit.models import ShopKitMixin
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class Shop(ShopKitMixin, ShopBase):
|
|
65
|
+
...
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class User(ShopUserBase):
|
|
69
|
+
...
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Then run `makemigrations` and `migrate`. `ShopKitMixin` includes django_shopify_app's `ShopLifecycleMixin`, which adds `status`, `installed_at` and `uninstalled_at`. `manage.py check` reports a shop model without the mixin (`shopify_kit.E001`) or with `ShopBase` listed first (`shopify_kit.E002`).
|
|
73
|
+
|
|
74
|
+
## Events
|
|
75
|
+
|
|
76
|
+
`ShopKitMixin` overrides four methods of the shop model and emits an event from each:
|
|
77
|
+
|
|
78
|
+
| Method | Event | When |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| `installed(request=None)` | `ShopInstalled(shop, request)` | Once per install. django_shopify_app calls `installed()` for every token it acquires; only the call that claims the install emits |
|
|
81
|
+
| `on_user_login(user_data, request=None)` | `ShopUserLoggedIn(shop, user, user_data, request)` | A staff user opened the app. The user is stored first, through `shop.users` |
|
|
82
|
+
| `uninstall()` | `ShopUninstalled(shop)` | After the shop's credentials are cleared |
|
|
83
|
+
| `save()` | `ShopSaved(shop)` | Every save |
|
|
84
|
+
|
|
85
|
+
Register your own handlers from an `AppConfig.ready()`:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from django.apps import AppConfig
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class OrdersConfig(AppConfig):
|
|
92
|
+
name = "orders"
|
|
93
|
+
|
|
94
|
+
def ready(self) -> None:
|
|
95
|
+
from shopify_kit.event_bus import register_handler
|
|
96
|
+
from shopify_kit.events import ShopInstalled
|
|
97
|
+
|
|
98
|
+
from .handlers import import_orders
|
|
99
|
+
|
|
100
|
+
register_handler(ShopInstalled, import_orders)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- Handlers run from `transaction.on_commit`, so a Celery task a handler queues sees the committed data. Outside a transaction they run right away.
|
|
104
|
+
- `register_handler` takes the event class, not its dotted name, and raises once startup is over: request threads read the registry without a lock.
|
|
105
|
+
|
|
106
|
+
### Emitting your own events
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
from dataclasses import dataclass
|
|
110
|
+
|
|
111
|
+
from django.utils.decorators import method_decorator
|
|
112
|
+
from shopify_kit.event_bus import Event, use_event_bus
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@dataclass
|
|
116
|
+
class RewardRedeemed(Event):
|
|
117
|
+
reward: "Reward"
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class Reward(models.Model):
|
|
121
|
+
@method_decorator(use_event_bus)
|
|
122
|
+
def redeem(self, *, events: list[Event]) -> None:
|
|
123
|
+
...
|
|
124
|
+
events.append(RewardRedeemed(reward=self))
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`use_event_bus` passes the method a new `events` list and dispatches what it appends once the method returns. Keep `events` keyword-only and without a default.
|
|
128
|
+
|
|
129
|
+
## What the package does on each event
|
|
130
|
+
|
|
131
|
+
| Event | Handler |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `ShopInstalled` | Stores the shop's GID (`shop.ensure_shopify_gid()`), sends the install to the CRM, and reports it to the partners service |
|
|
134
|
+
| `ShopUserLoggedIn` | Sends the login to the CRM |
|
|
135
|
+
| `ShopUninstalled` | Sends the uninstall to the CRM |
|
|
136
|
+
| django_shopify_pricing's `subscription_price_changed` | Sends the new price to the CRM. Connected only when `shopify_pricing` is installed |
|
|
137
|
+
|
|
138
|
+
The CRM calls and the GID run in Celery tasks (`shopify_kit.tasks`). The CRM methods on the mixin (`crm_on_install()`, `crm_on_login()`, `crm_on_uninstall()`, `crm_on_billing_plan_change()`) read the shop's name, email, phone and country from the GraphQL Admin API. If Shopify refuses the request, they send the shop's domain alone.
|
|
139
|
+
|
|
140
|
+
### Partners service
|
|
141
|
+
|
|
142
|
+
An install is posted to a partners service, with the merchant's IP for referral tracking, when all three settings are set:
|
|
143
|
+
|
|
144
|
+
| Setting | Description |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `SHOPIFY_KIT_PARTNERS_URL` | The endpoint that receives the install |
|
|
147
|
+
| `SHOPIFY_KIT_PARTNERS_API_KEY` | Its API key |
|
|
148
|
+
| `SHOPIFY_KIT_PARTNERS_APP_ID` | The app's ID in the partners service |
|
|
149
|
+
|
|
150
|
+
Without them nothing is sent. The call has a timeout, and an error is logged, never raised.
|
|
151
|
+
|
|
152
|
+
## The uninstall webhook
|
|
153
|
+
|
|
154
|
+
Queue django_shopify_app's task from your webhook callback; it calls `shop.uninstall()`, which emits `ShopUninstalled`:
|
|
155
|
+
|
|
156
|
+
```python
|
|
157
|
+
from shopify_app.tasks import uninstall_shop
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def webhook_entry(shopify_domain, topic, data, attributes=None):
|
|
161
|
+
if topic == "app/uninstalled":
|
|
162
|
+
uninstall_shop.delay(shopify_domain)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Moving an app that has its own copies
|
|
166
|
+
|
|
167
|
+
An app cloned from django-shopify-app-base before this package has the same tasks under `shops.tasks.*`. During the deploy that moves it, tasks queued under those names would be dropped. List the old names for that one release:
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
CELERY_IMPORTS = ["shopify_kit.legacy_tasks"]
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## Development
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
python -m venv .venv
|
|
177
|
+
.venv/bin/pip install -e . pytest pytest-django
|
|
178
|
+
.venv/bin/pytest
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Releasing
|
|
182
|
+
|
|
183
|
+
Bump `version` in `pyproject.toml`, add the entry to `CHANGES.txt` and push to `main`. Once the tests pass, `.github/workflows/release.yml` publishes that version to PyPI and tags a GitHub release. PyPI never accepts the same version twice, so a bad release is fixed with a new version.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
django_shopify_kit.egg-info/PKG-INFO
|
|
4
|
+
django_shopify_kit.egg-info/SOURCES.txt
|
|
5
|
+
django_shopify_kit.egg-info/dependency_links.txt
|
|
6
|
+
django_shopify_kit.egg-info/requires.txt
|
|
7
|
+
django_shopify_kit.egg-info/top_level.txt
|
|
8
|
+
shopify_kit/__init__.py
|
|
9
|
+
shopify_kit/apps.py
|
|
10
|
+
shopify_kit/checks.py
|
|
11
|
+
shopify_kit/event_bus.py
|
|
12
|
+
shopify_kit/events.py
|
|
13
|
+
shopify_kit/handlers.py
|
|
14
|
+
shopify_kit/legacy_tasks.py
|
|
15
|
+
shopify_kit/models.py
|
|
16
|
+
shopify_kit/referrals.py
|
|
17
|
+
shopify_kit/tasks.py
|
|
18
|
+
shopify_kit/services/__init__.py
|
|
19
|
+
shopify_kit/services/crm.py
|
|
20
|
+
tests/test_checks.py
|
|
21
|
+
tests/test_crm.py
|
|
22
|
+
tests/test_event_bus.py
|
|
23
|
+
tests/test_handlers.py
|
|
24
|
+
tests/test_models.py
|
|
25
|
+
tests/test_referrals.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
shopify_kit
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
# 77 is the first setuptools that reads `license` as an SPDX string (PEP 639).
|
|
3
|
+
requires = ["setuptools>=77", "wheel"]
|
|
4
|
+
build-backend = "setuptools.build_meta"
|
|
5
|
+
|
|
6
|
+
[project]
|
|
7
|
+
name = "django_shopify_kit"
|
|
8
|
+
version = "0.1.0"
|
|
9
|
+
description = "Event bus, shop lifecycle events and CRM wiring for Django apps built on django_shopify_app"
|
|
10
|
+
readme = "README.md"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Santiago Fernandez" },
|
|
14
|
+
]
|
|
15
|
+
requires-python = ">=3.10"
|
|
16
|
+
# Django range and Python floor follow django_shopify_app, so any app that runs it can
|
|
17
|
+
# add this package. Raise the Django cap once .github/workflows/tests.yml covers it.
|
|
18
|
+
dependencies = [
|
|
19
|
+
"Django>=5.2,<7",
|
|
20
|
+
"django_shopify_app[celery]>=2.20.0",
|
|
21
|
+
"django-crm-events",
|
|
22
|
+
"requests>=2.25",
|
|
23
|
+
]
|
|
24
|
+
classifiers = [
|
|
25
|
+
"Framework :: Django",
|
|
26
|
+
"Framework :: Django :: 5.2",
|
|
27
|
+
"Framework :: Django :: 6.0",
|
|
28
|
+
"Framework :: Django :: 6.1",
|
|
29
|
+
"Programming Language :: Python :: 3",
|
|
30
|
+
"Programming Language :: Python :: 3.10",
|
|
31
|
+
"Programming Language :: Python :: 3.11",
|
|
32
|
+
"Programming Language :: Python :: 3.12",
|
|
33
|
+
"Programming Language :: Python :: 3.13",
|
|
34
|
+
"Programming Language :: Python :: 3.14",
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
[tool.setuptools.packages.find]
|
|
38
|
+
include = ["shopify_kit*"]
|
|
39
|
+
|
|
40
|
+
[tool.pytest.ini_options]
|
|
41
|
+
DJANGO_SETTINGS_MODULE = "tests.settings"
|
|
42
|
+
# The tests package lives at the repo root; the console-script `pytest` does not
|
|
43
|
+
# put the working directory on sys.path (only `python -m pytest` does).
|
|
44
|
+
pythonpath = ["."]
|
|
45
|
+
testpaths = ["tests"]
|
|
File without changes
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
from django.apps import AppConfig, apps
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class ShopifyKitConfig(AppConfig):
|
|
5
|
+
"""Django app for the event bus, the shop events and their CRM handlers."""
|
|
6
|
+
|
|
7
|
+
default_auto_field = "django.db.models.BigAutoField"
|
|
8
|
+
name = "shopify_kit"
|
|
9
|
+
verbose_name = "Shopify kit"
|
|
10
|
+
|
|
11
|
+
def ready(self) -> None:
|
|
12
|
+
"""Register the system checks and the package's shop event handlers."""
|
|
13
|
+
from . import checks # noqa: F401 (registers the checks)
|
|
14
|
+
from .event_bus import register_handler
|
|
15
|
+
from .events import ShopInstalled, ShopUninstalled, ShopUserLoggedIn
|
|
16
|
+
from .handlers import (
|
|
17
|
+
handle_shop_installed,
|
|
18
|
+
handle_shop_uninstalled,
|
|
19
|
+
handle_shop_user_logged_in,
|
|
20
|
+
handle_subscription_price_changed,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
register_handler(ShopInstalled, handle_shop_installed)
|
|
24
|
+
register_handler(ShopUserLoggedIn, handle_shop_user_logged_in)
|
|
25
|
+
register_handler(ShopUninstalled, handle_shop_uninstalled)
|
|
26
|
+
|
|
27
|
+
# django_shopify_pricing is optional: apps on the Billing API don't have it.
|
|
28
|
+
if apps.is_installed("shopify_pricing"):
|
|
29
|
+
from shopify_pricing.signals import subscription_price_changed
|
|
30
|
+
|
|
31
|
+
subscription_price_changed.connect(
|
|
32
|
+
handle_subscription_price_changed,
|
|
33
|
+
dispatch_uid="shopify_kit.handle_subscription_price_changed",
|
|
34
|
+
)
|