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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: sub2api
3
- Version: 0.1.1
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 in-memory dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
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 dashboard's access token is different from an `sk-...` gateway API key. Browser deployments normally store the panel tokens under `auth_token` and `refresh_token` in local storage.
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. Tokens are retained only in memory. If a refresh token is supplied, the client rotates the token pair after an authenticated `401`. Supplying `expires_at` as a Unix timestamp also enables proactive refresh.
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. Choose another `curl_cffi` fingerprint or configure proxies by supplying your own `curl_cffi.requests.Session`:
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 in-memory dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
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 dashboard's access token is different from an `sk-...` gateway API key. Browser deployments normally store the panel tokens under `auth_token` and `refresh_token` in local storage.
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. Tokens are retained only in memory. If a refresh token is supplied, the client rotates the token pair after an authenticated `401`. Supplying `expires_at` as a Unix timestamp also enables proactive refresh.
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. Choose another `curl_cffi` fingerprint or configure proxies by supplying your own `curl_cffi.requests.Session`:
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.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "sub2api"
7
- version = "0.1.1"
7
+ version = "0.3.0"
8
8
  description = "Python client for the user-facing API of Sub2API instances"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -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.1.1"
83
+ __version__ = "0.3.0"