sub2api 0.1.1__tar.gz → 0.3.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.
- {sub2api-0.1.1 → sub2api-0.3.0}/PKG-INFO +66 -6
- {sub2api-0.1.1 → sub2api-0.3.0}/README.md +65 -5
- {sub2api-0.1.1 → sub2api-0.3.0}/pyproject.toml +1 -1
- {sub2api-0.1.1 → sub2api-0.3.0}/src/sub2api/__init__.py +23 -1
- {sub2api-0.1.1 → sub2api-0.3.0}/src/sub2api/_client.py +252 -90
- {sub2api-0.1.1 → sub2api-0.3.0}/src/sub2api/_exceptions.py +12 -0
- {sub2api-0.1.1 → sub2api-0.3.0}/src/sub2api/_models.py +32 -2
- {sub2api-0.1.1 → sub2api-0.3.0}/src/sub2api/_resources.py +217 -0
- sub2api-0.3.0/src/sub2api/_token_store.py +21 -0
- sub2api-0.3.0/tests/test_client.py +641 -0
- {sub2api-0.1.1 → sub2api-0.3.0}/tests/test_resources.py +127 -0
- sub2api-0.1.1/.gitignore +0 -11
- sub2api-0.1.1/tests/test_client.py +0 -308
- {sub2api-0.1.1 → sub2api-0.3.0}/LICENSE +0 -0
- {sub2api-0.1.1 → sub2api-0.3.0}/src/sub2api/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: sub2api
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
4
4
|
Summary: Python client for the user-facing API of Sub2API instances
|
|
5
5
|
Author: Eight Labs
|
|
6
6
|
License-Expression: MIT
|
|
@@ -29,9 +29,9 @@ Description-Content-Type: text/markdown
|
|
|
29
29
|
|
|
30
30
|
# sub2api
|
|
31
31
|
|
|
32
|
-
`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's
|
|
32
|
+
`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
|
|
33
33
|
|
|
34
|
-
The library targets operations present on standard Sub2API deployments: account balance, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
|
|
34
|
+
The library targets operations present on standard Sub2API deployments: account balance, optional payment deposits, payment orders, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
|
|
35
35
|
|
|
36
36
|
## Install
|
|
37
37
|
|
|
@@ -43,7 +43,7 @@ Python 3.10 or newer is required.
|
|
|
43
43
|
|
|
44
44
|
## Authenticate with an existing session
|
|
45
45
|
|
|
46
|
-
The
|
|
46
|
+
The client authenticates with a dashboard access token. If your integration owns the session and its renewal, you can also supply its refresh token.
|
|
47
47
|
|
|
48
48
|
```python
|
|
49
49
|
import os
|
|
@@ -60,9 +60,9 @@ print(client.me().email)
|
|
|
60
60
|
print(client.balance().balance)
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
Pass either the instance origin or its full `/api/v1` URL.
|
|
63
|
+
Pass either the instance origin or its full `/api/v1` URL. By default, the client keeps its tokens in memory and attempts renewal after an authenticated `401` if it has a refresh token. Supplying `expires_at` as a Unix timestamp also enables proactive renewal within 30 seconds of expiry.
|
|
64
64
|
|
|
65
|
-
The default browser fingerprint is Chrome.
|
|
65
|
+
The default browser fingerprint is Chrome. You can choose another `curl_cffi` fingerprint or configure proxies with your own `curl_cffi.requests.Session`.
|
|
66
66
|
|
|
67
67
|
```python
|
|
68
68
|
from curl_cffi import requests
|
|
@@ -71,6 +71,33 @@ session = requests.Session(impersonate="safari")
|
|
|
71
71
|
client = Sub2API("https://sub2api.example.com", session=session)
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
+
### Use a browser-managed session
|
|
75
|
+
|
|
76
|
+
If the dashboard owns renewal, pass its access token with `externally_managed=True`. The client surfaces the original `401`. When the dashboard supplies a new token, call `set_access_token()` on the existing client. You can pass `expires_at` with either call to retain the dashboard's expiry timestamp.
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
client = Sub2API(
|
|
80
|
+
"https://sub2api.example.com",
|
|
81
|
+
access_token=dashboard_access_token,
|
|
82
|
+
externally_managed=True,
|
|
83
|
+
)
|
|
84
|
+
client.set_access_token(updated_dashboard_access_token)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Persist and share a library-managed session
|
|
88
|
+
|
|
89
|
+
Pass a `token_store` that implements `TokenStore`. The client uses the stored `SessionTokens` when present and can initialize an empty store from the constructor credentials. Keep one store per user session and instance. Each write must persist `access_token`, `refresh_token`, `expires_at`, and `token_type` together.
|
|
90
|
+
|
|
91
|
+
- `load()` returns the current snapshot, or `None` for an uninitialized store.
|
|
92
|
+
- `save(tokens)` atomically replaces the snapshot after a successful login, including 2FA.
|
|
93
|
+
- `compare_and_set(expected, tokens)` atomically replaces the snapshot only if it matches `expected`. Return `False` when another writer has changed it. An empty `SessionTokens()` snapshot represents a cleared session.
|
|
94
|
+
|
|
95
|
+
When multiple clients share the session, pass the same `refresh_lock` to each client along with the shared store. A `threading.Lock()` works for threads in one process. Workers in separate processes need a lock that coordinates across those processes and supports `with`. Clients reload the stored pair under that lock and save a rotation before releasing it or retrying the original request.
|
|
96
|
+
|
|
97
|
+
If the rotation write raises, the client surfaces the store exception and keeps the new pair in `client.tokens`. Call `client.save_tokens()` to retry the conditional write without another refresh request. A newer login in the store takes precedence over a pending rotation.
|
|
98
|
+
|
|
99
|
+
Rate limits, transport errors, and server errors during renewal leave credentials intact. HTTP errors expose `retry_after` in seconds when the server supplies a valid `Retry-After` header. After a transport failure the client checks the store for a replacement pair, and surfaces `TransportError` if it finds none. `SessionExpiredError`, `SessionRevokedError`, and `SessionBindingError` are subclasses of `AuthenticationError` that carry the server's reason or code.
|
|
100
|
+
|
|
74
101
|
## Log in with email and password
|
|
75
102
|
|
|
76
103
|
```python
|
|
@@ -186,6 +213,39 @@ result = client.redeem("REDEMPTION-CODE")
|
|
|
186
213
|
redemption_history = client.redeem.history()
|
|
187
214
|
```
|
|
188
215
|
|
|
216
|
+
## Deposits and payment
|
|
217
|
+
|
|
218
|
+
Payment is optional and must be enabled and configured by the instance administrator. Inspect the checkout configuration before offering a deposit:
|
|
219
|
+
|
|
220
|
+
```python
|
|
221
|
+
checkout = client.payment.checkout_info()
|
|
222
|
+
|
|
223
|
+
if checkout.methods:
|
|
224
|
+
order = client.deposit(
|
|
225
|
+
10,
|
|
226
|
+
payment_type="stripe",
|
|
227
|
+
return_url="https://app.example.com/payment/result",
|
|
228
|
+
)
|
|
229
|
+
print(order.order_id, order.pay_url, order.qr_code, order.client_secret)
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Available payment methods depend on the instance and can include `alipay`, `wxpay`, `stripe`, and `airwallex`. The returned order contains the provider-specific checkout data: a hosted payment URL, QR code, Stripe client secret, or WeChat OAuth/JSAPI payload. Creating the order does not credit the balance; the configured provider must confirm payment before the instance completes the deposit.
|
|
233
|
+
|
|
234
|
+
Use the payment resource to inspect and manage the order:
|
|
235
|
+
|
|
236
|
+
```python
|
|
237
|
+
pending = client.payment.get(order.order_id)
|
|
238
|
+
verified = client.payment.verify(order.out_trade_no)
|
|
239
|
+
orders = client.payment.list(status="COMPLETED", order_type="balance")
|
|
240
|
+
client.payment.cancel(order.order_id)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
An instance without payment configuration returns its normal typed API error, including `PAYMENT_DISABLED` or `NO_AVAILABLE_INSTANCE`, rather than silently treating a deposit as successful. Public order recovery is also available when a checkout flow has a signed resume token:
|
|
244
|
+
|
|
245
|
+
```python
|
|
246
|
+
public_order = client.payment.resolve_public(order.resume_token)
|
|
247
|
+
```
|
|
248
|
+
|
|
189
249
|
## Fork-specific endpoints
|
|
190
250
|
|
|
191
251
|
`request()` provides the same authentication, envelope handling, timezone parameter, refresh behavior, and error mapping for relative endpoints that are not part of the stable resource API.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# sub2api
|
|
2
2
|
|
|
3
|
-
`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's
|
|
3
|
+
`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
|
|
4
4
|
|
|
5
|
-
The library targets operations present on standard Sub2API deployments: account balance, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
|
|
5
|
+
The library targets operations present on standard Sub2API deployments: account balance, optional payment deposits, payment orders, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
@@ -14,7 +14,7 @@ Python 3.10 or newer is required.
|
|
|
14
14
|
|
|
15
15
|
## Authenticate with an existing session
|
|
16
16
|
|
|
17
|
-
The
|
|
17
|
+
The client authenticates with a dashboard access token. If your integration owns the session and its renewal, you can also supply its refresh token.
|
|
18
18
|
|
|
19
19
|
```python
|
|
20
20
|
import os
|
|
@@ -31,9 +31,9 @@ print(client.me().email)
|
|
|
31
31
|
print(client.balance().balance)
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
Pass either the instance origin or its full `/api/v1` URL.
|
|
34
|
+
Pass either the instance origin or its full `/api/v1` URL. By default, the client keeps its tokens in memory and attempts renewal after an authenticated `401` if it has a refresh token. Supplying `expires_at` as a Unix timestamp also enables proactive renewal within 30 seconds of expiry.
|
|
35
35
|
|
|
36
|
-
The default browser fingerprint is Chrome.
|
|
36
|
+
The default browser fingerprint is Chrome. You can choose another `curl_cffi` fingerprint or configure proxies with your own `curl_cffi.requests.Session`.
|
|
37
37
|
|
|
38
38
|
```python
|
|
39
39
|
from curl_cffi import requests
|
|
@@ -42,6 +42,33 @@ session = requests.Session(impersonate="safari")
|
|
|
42
42
|
client = Sub2API("https://sub2api.example.com", session=session)
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
+
### Use a browser-managed session
|
|
46
|
+
|
|
47
|
+
If the dashboard owns renewal, pass its access token with `externally_managed=True`. The client surfaces the original `401`. When the dashboard supplies a new token, call `set_access_token()` on the existing client. You can pass `expires_at` with either call to retain the dashboard's expiry timestamp.
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
client = Sub2API(
|
|
51
|
+
"https://sub2api.example.com",
|
|
52
|
+
access_token=dashboard_access_token,
|
|
53
|
+
externally_managed=True,
|
|
54
|
+
)
|
|
55
|
+
client.set_access_token(updated_dashboard_access_token)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Persist and share a library-managed session
|
|
59
|
+
|
|
60
|
+
Pass a `token_store` that implements `TokenStore`. The client uses the stored `SessionTokens` when present and can initialize an empty store from the constructor credentials. Keep one store per user session and instance. Each write must persist `access_token`, `refresh_token`, `expires_at`, and `token_type` together.
|
|
61
|
+
|
|
62
|
+
- `load()` returns the current snapshot, or `None` for an uninitialized store.
|
|
63
|
+
- `save(tokens)` atomically replaces the snapshot after a successful login, including 2FA.
|
|
64
|
+
- `compare_and_set(expected, tokens)` atomically replaces the snapshot only if it matches `expected`. Return `False` when another writer has changed it. An empty `SessionTokens()` snapshot represents a cleared session.
|
|
65
|
+
|
|
66
|
+
When multiple clients share the session, pass the same `refresh_lock` to each client along with the shared store. A `threading.Lock()` works for threads in one process. Workers in separate processes need a lock that coordinates across those processes and supports `with`. Clients reload the stored pair under that lock and save a rotation before releasing it or retrying the original request.
|
|
67
|
+
|
|
68
|
+
If the rotation write raises, the client surfaces the store exception and keeps the new pair in `client.tokens`. Call `client.save_tokens()` to retry the conditional write without another refresh request. A newer login in the store takes precedence over a pending rotation.
|
|
69
|
+
|
|
70
|
+
Rate limits, transport errors, and server errors during renewal leave credentials intact. HTTP errors expose `retry_after` in seconds when the server supplies a valid `Retry-After` header. After a transport failure the client checks the store for a replacement pair, and surfaces `TransportError` if it finds none. `SessionExpiredError`, `SessionRevokedError`, and `SessionBindingError` are subclasses of `AuthenticationError` that carry the server's reason or code.
|
|
71
|
+
|
|
45
72
|
## Log in with email and password
|
|
46
73
|
|
|
47
74
|
```python
|
|
@@ -157,6 +184,39 @@ result = client.redeem("REDEMPTION-CODE")
|
|
|
157
184
|
redemption_history = client.redeem.history()
|
|
158
185
|
```
|
|
159
186
|
|
|
187
|
+
## Deposits and payment
|
|
188
|
+
|
|
189
|
+
Payment is optional and must be enabled and configured by the instance administrator. Inspect the checkout configuration before offering a deposit:
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
checkout = client.payment.checkout_info()
|
|
193
|
+
|
|
194
|
+
if checkout.methods:
|
|
195
|
+
order = client.deposit(
|
|
196
|
+
10,
|
|
197
|
+
payment_type="stripe",
|
|
198
|
+
return_url="https://app.example.com/payment/result",
|
|
199
|
+
)
|
|
200
|
+
print(order.order_id, order.pay_url, order.qr_code, order.client_secret)
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Available payment methods depend on the instance and can include `alipay`, `wxpay`, `stripe`, and `airwallex`. The returned order contains the provider-specific checkout data: a hosted payment URL, QR code, Stripe client secret, or WeChat OAuth/JSAPI payload. Creating the order does not credit the balance; the configured provider must confirm payment before the instance completes the deposit.
|
|
204
|
+
|
|
205
|
+
Use the payment resource to inspect and manage the order:
|
|
206
|
+
|
|
207
|
+
```python
|
|
208
|
+
pending = client.payment.get(order.order_id)
|
|
209
|
+
verified = client.payment.verify(order.out_trade_no)
|
|
210
|
+
orders = client.payment.list(status="COMPLETED", order_type="balance")
|
|
211
|
+
client.payment.cancel(order.order_id)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
An instance without payment configuration returns its normal typed API error, including `PAYMENT_DISABLED` or `NO_AVAILABLE_INSTANCE`, rather than silently treating a deposit as successful. Public order recovery is also available when a checkout flow has a signed resume token:
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
public_order = client.payment.resolve_public(order.resume_token)
|
|
218
|
+
```
|
|
219
|
+
|
|
160
220
|
## Fork-specific endpoints
|
|
161
221
|
|
|
162
222
|
`request()` provides the same authentication, envelope handling, timezone parameter, refresh behavior, and error mapping for relative endpoints that are not part of the stable resource API.
|
|
@@ -8,6 +8,9 @@ from ._exceptions import (
|
|
|
8
8
|
PermissionDeniedError,
|
|
9
9
|
ProtocolError,
|
|
10
10
|
RateLimitError,
|
|
11
|
+
SessionBindingError,
|
|
12
|
+
SessionExpiredError,
|
|
13
|
+
SessionRevokedError,
|
|
11
14
|
Sub2APIError,
|
|
12
15
|
TransportError,
|
|
13
16
|
TwoFactorRequired,
|
|
@@ -17,17 +20,25 @@ from ._models import (
|
|
|
17
20
|
Announcement,
|
|
18
21
|
APIKey,
|
|
19
22
|
Balance,
|
|
23
|
+
CheckoutInfo,
|
|
20
24
|
Group,
|
|
21
25
|
KeyGroupMultiplier,
|
|
22
26
|
Page,
|
|
27
|
+
PaymentConfig,
|
|
28
|
+
PaymentMethodLimit,
|
|
29
|
+
PaymentOrder,
|
|
30
|
+
PaymentOrderCreation,
|
|
23
31
|
PlatformQuota,
|
|
32
|
+
PublicPaymentOrder,
|
|
24
33
|
Redemption,
|
|
25
34
|
Resource,
|
|
26
35
|
SessionTokens,
|
|
27
36
|
Subscription,
|
|
37
|
+
SubscriptionPlan,
|
|
28
38
|
UsageRecord,
|
|
29
39
|
User,
|
|
30
40
|
)
|
|
41
|
+
from ._token_store import TokenStore
|
|
31
42
|
|
|
32
43
|
__all__ = [
|
|
33
44
|
"APIError",
|
|
@@ -35,22 +46,33 @@ __all__ = [
|
|
|
35
46
|
"Announcement",
|
|
36
47
|
"AuthenticationError",
|
|
37
48
|
"Balance",
|
|
49
|
+
"CheckoutInfo",
|
|
38
50
|
"ConfigurationError",
|
|
39
51
|
"ConflictError",
|
|
40
52
|
"Group",
|
|
41
53
|
"KeyGroupMultiplier",
|
|
42
54
|
"NotFoundError",
|
|
43
55
|
"Page",
|
|
56
|
+
"PaymentConfig",
|
|
57
|
+
"PaymentMethodLimit",
|
|
58
|
+
"PaymentOrder",
|
|
59
|
+
"PaymentOrderCreation",
|
|
44
60
|
"PermissionDeniedError",
|
|
45
61
|
"PlatformQuota",
|
|
46
62
|
"ProtocolError",
|
|
63
|
+
"PublicPaymentOrder",
|
|
47
64
|
"RateLimitError",
|
|
48
65
|
"Redemption",
|
|
49
66
|
"Resource",
|
|
67
|
+
"SessionBindingError",
|
|
68
|
+
"SessionExpiredError",
|
|
69
|
+
"SessionRevokedError",
|
|
50
70
|
"SessionTokens",
|
|
51
71
|
"Sub2API",
|
|
52
72
|
"Sub2APIError",
|
|
53
73
|
"Subscription",
|
|
74
|
+
"SubscriptionPlan",
|
|
75
|
+
"TokenStore",
|
|
54
76
|
"TransportError",
|
|
55
77
|
"TwoFactorRequired",
|
|
56
78
|
"UsageRecord",
|
|
@@ -58,4 +80,4 @@ __all__ = [
|
|
|
58
80
|
"ValidationError",
|
|
59
81
|
]
|
|
60
82
|
|
|
61
|
-
__version__ = "0.
|
|
83
|
+
__version__ = "0.3.0"
|