squarecloud-api 4.0.0__tar.gz → 4.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 (38) hide show
  1. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/PKG-INFO +1 -1
  2. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/pyproject.toml +1 -1
  3. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/__init__.py +1 -1
  4. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/app.py +109 -0
  5. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/client.py +268 -5
  6. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/http/endpoints.py +153 -0
  7. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/http/http_client.py +228 -4
  8. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/LICENSE +0 -0
  9. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/README.md +0 -0
  10. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/__init__.py +0 -0
  11. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/app.py +0 -0
  12. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/base.py +0 -0
  13. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/base_database.py +0 -0
  14. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/certificate.py +0 -0
  15. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/database.py +0 -0
  16. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/database_info.py +0 -0
  17. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/deploy_data.py +0 -0
  18. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/dns_record.py +0 -0
  19. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/domain_analytics.py +0 -0
  20. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/file_info.py +0 -0
  21. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/language.py +0 -0
  22. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/logs.py +0 -0
  23. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/plan.py +0 -0
  24. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/snapshot.py +0 -0
  25. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/snapshot_info.py +0 -0
  26. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/status.py +0 -0
  27. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/upload.py +0 -0
  28. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/user.py +0 -0
  29. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/data/workspace.py +0 -0
  30. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/errors.py +0 -0
  31. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/file.py +0 -0
  32. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/http/__init__.py +0 -0
  33. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/listeners/__init__.py +0 -0
  34. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/listeners/capture_listener.py +0 -0
  35. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/listeners/request_listener.py +0 -0
  36. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/logger.py +0 -0
  37. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/py.typed +0 -0
  38. {squarecloud_api-4.0.0 → squarecloud_api-4.1.0}/src/squarecloud/utils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: squarecloud-api
3
- Version: 4.0.0
3
+ Version: 4.1.0
4
4
  Summary: SquareCloud API wrapper
5
5
  License: MIT
6
6
  License-File: LICENSE
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "squarecloud-api"
3
- version = "4.0.0"
3
+ version = "4.1.0"
4
4
  description = "SquareCloud API wrapper"
5
5
  authors = [
6
6
  {name = "Robert Nogueira",email = "robertlucasnogueira@gmail.com"}
@@ -47,4 +47,4 @@ __all__ = [
47
47
  'utils',
48
48
  ]
49
49
 
50
- __version__ = '4.0.0'
50
+ __version__ = '4.1.0'
@@ -1,5 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
+ from collections.abc import AsyncGenerator
3
4
  from datetime import datetime
4
5
  from functools import wraps
5
6
  from io import BytesIO
@@ -762,3 +763,111 @@ class Application(CaptureListenerManager):
762
763
  :rtype: dict[str, str]
763
764
  """
764
765
  return await self.client.overwrite_app_envs(self.id, envs)
766
+
767
+ async def metrics(self) -> dict[str, Any]:
768
+ """
769
+ Get the last 24h of metrics for the application
770
+ (288 points, sampled every 5 minutes).
771
+ Available only for apps with at least 512 MB of RAM.
772
+
773
+ :return: The raw metrics payload.
774
+ :rtype: dict[str, Any]
775
+ """
776
+ return await self.client.app_metrics(self.id)
777
+
778
+ def realtime(self) -> AsyncGenerator[dict[str, Any] | str, None]:
779
+ """
780
+ Stream realtime status events (SSE) for the application.
781
+
782
+ Usage::
783
+
784
+ async for event in app.realtime():
785
+ print(event)
786
+
787
+ :return: An async generator of decoded events.
788
+ :rtype: AsyncGenerator[dict[str, Any] | str, None]
789
+ """
790
+ return self.client.realtime(self.id)
791
+
792
+ async def link_github_app(
793
+ self, repository_name: str, repository_branch: str
794
+ ) -> dict[str, Any]:
795
+ """
796
+ Link a GitHub repository via the Square Cloud GitHub App.
797
+ Requires a session token (JWT); API keys are not accepted.
798
+
799
+ :param repository_name: Full repository name (e.g. octocat/hello-world).
800
+ :param repository_branch: Repository branch.
801
+ :return: The linked repository information.
802
+ :rtype: dict[str, Any]
803
+ """
804
+ return await self.client.link_github_app(
805
+ self.id, repository_name, repository_branch
806
+ )
807
+
808
+ async def unlink_github_app(self) -> Response:
809
+ """
810
+ Unlink the GitHub App repository from the application.
811
+ Requires a session token (JWT); API keys are not accepted.
812
+
813
+ :return: A Response object.
814
+ :rtype: Response
815
+ """
816
+ return await self.client.unlink_github_app(self.id)
817
+
818
+ async def network_errors(
819
+ self,
820
+ start: str | datetime,
821
+ end: str | datetime,
822
+ include_4xx: bool = False,
823
+ ) -> dict[str, Any]:
824
+ """
825
+ Get the aggregated edge error breakdown (4xx/5xx) for the
826
+ application's domains. Defaults to 5xx only.
827
+
828
+ :param start: ISO 8601 start timestamp (or datetime).
829
+ :param end: ISO 8601 end timestamp (or datetime).
830
+ :param include_4xx: Include 4xx alongside 5xx.
831
+ :return: The raw errors payload.
832
+ :rtype: dict[str, Any]
833
+ """
834
+ return await self.client.network_errors(
835
+ self.id, start, end, include_4xx
836
+ )
837
+
838
+ async def network_logs(
839
+ self, start: str | datetime, end: str | datetime
840
+ ) -> dict[str, Any]:
841
+ """
842
+ Get the per-request edge logs for the application's domains.
843
+ Requires Pro plan or higher.
844
+
845
+ :param start: ISO 8601 start timestamp (or datetime).
846
+ :param end: ISO 8601 end timestamp (or datetime).
847
+ :return: The raw logs payload.
848
+ :rtype: dict[str, Any]
849
+ """
850
+ return await self.client.network_logs(self.id, start, end)
851
+
852
+ async def network_performance(
853
+ self, start: str | datetime, end: str | datetime
854
+ ) -> dict[str, Any]:
855
+ """
856
+ Get edge and origin latency percentiles (p50/p95/p99) for the
857
+ application's domains. Requires Pro plan or higher.
858
+
859
+ :param start: ISO 8601 start timestamp (or datetime).
860
+ :param end: ISO 8601 end timestamp (or datetime).
861
+ :return: The raw performance payload.
862
+ :rtype: dict[str, Any]
863
+ """
864
+ return await self.client.network_performance(self.id, start, end)
865
+
866
+ async def purge_cache(self) -> Response:
867
+ """
868
+ Purge the entire edge cache for the application's domains.
869
+
870
+ :return: A Response object.
871
+ :rtype: Response
872
+ """
873
+ return await self.client.purge_cache(self.id)
@@ -2,6 +2,8 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from collections.abc import AsyncGenerator
6
+ from datetime import datetime
5
7
  from functools import wraps
6
8
  from io import BytesIO
7
9
  from typing import Any, Callable, Literal, ParamSpec, TypeVar, cast
@@ -39,6 +41,10 @@ P = ParamSpec("P")
39
41
  R = TypeVar("R")
40
42
 
41
43
 
44
+ def _to_iso(value: str | datetime) -> str:
45
+ return value.isoformat() if isinstance(value, datetime) else value
46
+
47
+
42
48
  class Client(RequestListenerManager):
43
49
  """A client for interacting with the SquareCloud API."""
44
50
 
@@ -686,12 +692,43 @@ class Client(RequestListenerManager):
686
692
 
687
693
  @_notify_listener(Endpoint.domain_analytics())
688
694
  async def domain_analytics(
689
- self, app_id: str, **_kwargs
695
+ self,
696
+ app_id: str,
697
+ *,
698
+ start: str | datetime | None = None,
699
+ end: str | datetime | None = None,
700
+ country: str | None = None,
701
+ ip: str | None = None,
702
+ path: str | None = None,
703
+ status: str | None = None,
704
+ os: str | None = None,
705
+ browser: str | None = None,
706
+ protocol: str | None = None,
707
+ referer: str | None = None,
708
+ provider: str | None = None,
709
+ content_type: str | None = None,
710
+ bot: str | None = None,
711
+ **_kwargs,
690
712
  ) -> DomainAnalytics:
691
713
  """
692
- The domain_analytics method return a DomainAnalytics object
714
+ The domain_analytics method return a DomainAnalytics object.
715
+ Maximum retention window is 7 days. The optional drill-down filters
716
+ apply to every breakdown at once.
693
717
 
694
718
  :param app_id: Specify the application by id
719
+ :param start: ISO 8601 start timestamp (or datetime)
720
+ :param end: ISO 8601 end timestamp (or datetime)
721
+ :param country: Filter to one client country (2-char code, e.g. BR)
722
+ :param ip: Filter to one client IP (exact match)
723
+ :param path: Filter to request paths starting with this prefix
724
+ :param status: Filter to one edge response status code
725
+ :param os: Filter to one client OS
726
+ :param browser: Filter to one client browser
727
+ :param protocol: Filter to one HTTP protocol
728
+ :param referer: Filter to one referer host ("Direct" = no referer)
729
+ :param provider: Filter to one client network
730
+ :param content_type: Filter to one response content type
731
+ :param bot: Filter to one verified-bot category
695
732
  :param _kwargs: Keyword arguments
696
733
  :return: A DomainAnalytics object
697
734
  :rtype: DomainAnalytics
@@ -703,10 +740,26 @@ class Client(RequestListenerManager):
703
740
  :raises TooManyRequestsError: Raised when the request status
704
741
  code is 429
705
742
  """
743
+ params = {
744
+ 'start': _to_iso(start) if start else None,
745
+ 'end': _to_iso(end) if end else None,
746
+ 'country': country,
747
+ 'ip': ip,
748
+ 'path': path,
749
+ 'status': status,
750
+ 'os': os,
751
+ 'browser': browser,
752
+ 'protocol': protocol,
753
+ 'referer': referer,
754
+ 'provider': provider,
755
+ 'content_type': content_type,
756
+ 'bot': bot,
757
+ }
758
+ params = {key: value for key, value in params.items() if value}
706
759
  response: Response = await self._http.domain_analytics(
707
- app_id=app_id,
760
+ app_id=app_id, params=params
708
761
  )
709
- return DomainAnalytics(**response.response)
762
+ return DomainAnalytics(**response.response)
710
763
 
711
764
  @_notify_listener(Endpoint.all_snapshots())
712
765
  async def all_app_snapshots(
@@ -1146,4 +1199,214 @@ class Client(RequestListenerManager):
1146
1199
  :rtype: str
1147
1200
  """
1148
1201
  response: Response = await self._http.get_workspace_member_code()
1149
- return cast(str, response.response.get("code", ""))
1202
+ return cast(str, response.response.get("code", ""))
1203
+
1204
+ async def service_status(self) -> dict[str, Any]:
1205
+ """Get the aggregate platform status (mirrors the public status page).
1206
+
1207
+ Note: this endpoint does not use the usual {status, response}
1208
+ envelope — the raw payload ({status, message}) is returned.
1209
+
1210
+ :return: The raw status payload.
1211
+ :rtype: dict[str, Any]
1212
+ """
1213
+ response: Response = await self._http.fetch_service_status()
1214
+ return response.data
1215
+
1216
+ async def user_snapshots(
1217
+ self, scope: Literal["applications", "databases"] = "applications"
1218
+ ) -> list[dict[str, Any]]:
1219
+ """List the authenticated user's snapshots.
1220
+ Requires an active paid plan (402 UPGRADE_REQUIRED otherwise).
1221
+
1222
+ :param scope: Snapshot scope (default "applications").
1223
+ :return: The raw list of snapshots.
1224
+ :rtype: list[dict[str, Any]]
1225
+ """
1226
+ response: Response = await self._http.fetch_user_snapshots(scope)
1227
+ return response.response
1228
+
1229
+ async def all_domains(self) -> list[dict[str, Any]]:
1230
+ """List every domain configured across your applications — the
1231
+ default subdomain and any attached custom domain.
1232
+ Rate limited to 20 requests per 60s.
1233
+
1234
+ :return: The raw list of domains.
1235
+ :rtype: list[dict[str, Any]]
1236
+ """
1237
+ response: Response = await self._http.fetch_all_domains()
1238
+ return response.response
1239
+
1240
+ async def load_balancers(self) -> dict[str, Any]:
1241
+ """List your custom-domain load balancers — applications grouped by
1242
+ attached custom domain. Rate limited to 20 requests per 60s.
1243
+
1244
+ :return: The raw load balancers payload.
1245
+ :rtype: dict[str, Any]
1246
+ """
1247
+ response: Response = await self._http.fetch_load_balancers()
1248
+ return response.response
1249
+
1250
+ async def app_metrics(self, app_id: str) -> dict[str, Any]:
1251
+ """Get the last 24h of metrics for an application
1252
+ (288 points, sampled every 5 minutes).
1253
+ Available only for apps with at least 512 MB of RAM.
1254
+
1255
+ :param app_id: Specify the application by id.
1256
+ :return: The raw metrics payload.
1257
+ :rtype: dict[str, Any]
1258
+ """
1259
+ response: Response = await self._http.fetch_app_metrics(app_id)
1260
+ return response.response
1261
+
1262
+ async def database_metrics(self, database_id: str) -> dict[str, Any]:
1263
+ """Get the last 24h of metrics for a database
1264
+ (288 points, sampled every 5 minutes).
1265
+
1266
+ :param database_id: Specify the database by id.
1267
+ :return: The raw metrics payload.
1268
+ :rtype: dict[str, Any]
1269
+ """
1270
+ response: Response = await self._http.fetch_database_metrics(
1271
+ database_id
1272
+ )
1273
+ return response.response
1274
+
1275
+ async def link_github_app(
1276
+ self, app_id: str, repository_name: str, repository_branch: str
1277
+ ) -> dict[str, Any]:
1278
+ """Link a GitHub repository via the Square Cloud GitHub App.
1279
+ Requires a session token (JWT); API keys are not accepted.
1280
+
1281
+ :param app_id: Specify the application by id.
1282
+ :param repository_name: Full repository name (e.g. octocat/hello-world).
1283
+ :param repository_branch: Repository branch (max 256 chars).
1284
+ :return: The linked repository information.
1285
+ :rtype: dict[str, Any]
1286
+ """
1287
+ response: Response = await self._http.link_github_app(
1288
+ app_id, repository_name, repository_branch
1289
+ )
1290
+ return response.response.get("repository", {})
1291
+
1292
+ async def unlink_github_app(self, app_id: str) -> Response:
1293
+ """Unlink the GitHub App repository from an application.
1294
+ Requires a session token (JWT); API keys are not accepted.
1295
+
1296
+ :param app_id: Specify the application by id.
1297
+ :return: Response object returned by the API.
1298
+ :rtype: Response
1299
+ """
1300
+ return await self._http.unlink_github_app(app_id)
1301
+
1302
+ async def network_errors(
1303
+ self,
1304
+ app_id: str,
1305
+ start: str | datetime,
1306
+ end: str | datetime,
1307
+ include_4xx: bool = False,
1308
+ ) -> dict[str, Any]:
1309
+ """Get the aggregated edge error breakdown (4xx/5xx) for an
1310
+ application's domains. Defaults to 5xx only.
1311
+
1312
+ :param app_id: Specify the application by id.
1313
+ :param start: ISO 8601 start timestamp (or datetime).
1314
+ :param end: ISO 8601 end timestamp (or datetime).
1315
+ :param include_4xx: Include 4xx alongside 5xx.
1316
+ :return: The raw errors payload.
1317
+ :rtype: dict[str, Any]
1318
+ """
1319
+ response: Response = await self._http.network_errors(
1320
+ app_id, _to_iso(start), _to_iso(end), include_4xx
1321
+ )
1322
+ return response.response
1323
+
1324
+ async def network_logs(
1325
+ self, app_id: str, start: str | datetime, end: str | datetime
1326
+ ) -> dict[str, Any]:
1327
+ """Get the per-request edge logs for an application's domains.
1328
+ Requires Pro plan or higher.
1329
+
1330
+ :param app_id: Specify the application by id.
1331
+ :param start: ISO 8601 start timestamp (or datetime).
1332
+ :param end: ISO 8601 end timestamp (or datetime).
1333
+ :return: The raw logs payload.
1334
+ :rtype: dict[str, Any]
1335
+ """
1336
+ response: Response = await self._http.network_logs(
1337
+ app_id, _to_iso(start), _to_iso(end)
1338
+ )
1339
+ return response.response
1340
+
1341
+ async def network_performance(
1342
+ self, app_id: str, start: str | datetime, end: str | datetime
1343
+ ) -> dict[str, Any]:
1344
+ """Get edge and origin latency percentiles (p50/p95/p99) for an
1345
+ application's domains. Requires Pro plan or higher.
1346
+
1347
+ :param app_id: Specify the application by id.
1348
+ :param start: ISO 8601 start timestamp (or datetime).
1349
+ :param end: ISO 8601 end timestamp (or datetime).
1350
+ :return: The raw performance payload.
1351
+ :rtype: dict[str, Any]
1352
+ """
1353
+ response: Response = await self._http.network_performance(
1354
+ app_id, _to_iso(start), _to_iso(end)
1355
+ )
1356
+ return response.response
1357
+
1358
+ async def purge_cache(self, app_id: str) -> Response:
1359
+ """Purge the entire edge cache for an application's domains.
1360
+
1361
+ :param app_id: Specify the application by id.
1362
+ :return: Response object returned by the API.
1363
+ :rtype: Response
1364
+ """
1365
+ return await self._http.purge_cache(app_id)
1366
+
1367
+ async def all_database_snapshots(
1368
+ self, database_id: str
1369
+ ) -> list[SnapshotInfo]:
1370
+ """Retrieve all snapshots of a database.
1371
+
1372
+ :param database_id: Specify the database by id.
1373
+ :return: A list of SnapshotInfo objects.
1374
+ :rtype: list[SnapshotInfo]
1375
+ """
1376
+ response: Response = await self._http.get_all_database_snapshots(
1377
+ database_id
1378
+ )
1379
+ return [
1380
+ SnapshotInfo(**snapshot_data)
1381
+ for snapshot_data in response.response
1382
+ ]
1383
+
1384
+ async def database_snapshot(self, database_id: str) -> Snapshot:
1385
+ """Create a snapshot of a database.
1386
+
1387
+ :param database_id: Specify the database by id.
1388
+ :return: A Snapshot object.
1389
+ :rtype: Snapshot
1390
+ """
1391
+ response: Response = await self._http.create_database_snapshot(
1392
+ database_id
1393
+ )
1394
+ return Snapshot(**response.response)
1395
+
1396
+ def realtime(
1397
+ self, app_id: str
1398
+ ) -> AsyncGenerator[dict[str, Any] | str, None]:
1399
+ """Stream realtime status events (SSE) for an application.
1400
+ Max 5 concurrent connections per user; connections live for up to
1401
+ 10 minutes.
1402
+
1403
+ Usage::
1404
+
1405
+ async for event in client.realtime(app_id):
1406
+ print(event)
1407
+
1408
+ :param app_id: Specify the application by id.
1409
+ :return: An async generator of decoded events.
1410
+ :rtype: AsyncGenerator[dict[str, Any] | str, None]
1411
+ """
1412
+ return self._http.realtime(app_id)
@@ -6,6 +6,12 @@ class Endpoint:
6
6
 
7
7
  ENDPOINTS_V2 = {
8
8
  'USER': {'METHOD': 'GET', 'PATH': '/users/me'},
9
+ 'USER_SNAPSHOTS': {'METHOD': 'GET', 'PATH': '/users/snapshots'},
10
+ 'SERVICE_STATUS': {'METHOD': 'GET', 'PATH': '/service/status'},
11
+ 'ALL_DOMAINS': {'METHOD': 'GET', 'PATH': '/apps/domains'},
12
+ 'LOAD_BALANCERS': {'METHOD': 'GET', 'PATH': '/apps/load-balancers'},
13
+ 'APP_METRICS': {'METHOD': 'GET', 'PATH': '/apps/{app_id}/metrics'},
14
+ 'REALTIME': {'METHOD': 'GET', 'PATH': '/apps/{app_id}/realtime'},
9
15
  'APP_DATA': {'METHOD': 'GET', 'PATH': '/apps/{app_id}'},
10
16
  'APP_STATUS': {'METHOD': 'GET', 'PATH': '/apps/{app_id}/status'},
11
17
  'ALL_APPS_STATUS': {'METHOD': 'GET', 'PATH': '/apps/status'},
@@ -55,6 +61,14 @@ class Endpoint:
55
61
  'METHOD': 'POST',
56
62
  'PATH': '/apps/{app_id}/deploy/webhook',
57
63
  },
64
+ 'GITHUB_APP_LINK': {
65
+ 'METHOD': 'POST',
66
+ 'PATH': '/apps/{app_id}/deploy/github-app',
67
+ },
68
+ 'GITHUB_APP_UNLINK': {
69
+ 'METHOD': 'DELETE',
70
+ 'PATH': '/apps/{app_id}/deploy/github-app',
71
+ },
58
72
  'CUSTOM_DOMAIN': {
59
73
  'METHOD': 'POST',
60
74
  'PATH': '/apps/{app_id}/network/custom',
@@ -64,6 +78,22 @@ class Endpoint:
64
78
  'PATH': '/apps/{app_id}/network/analytics',
65
79
  },
66
80
  'DNSRECORDS': {'METHOD': 'GET', 'PATH': '/apps/{app_id}/network/dns'},
81
+ 'NETWORK_ERRORS': {
82
+ 'METHOD': 'GET',
83
+ 'PATH': '/apps/{app_id}/network/errors',
84
+ },
85
+ 'NETWORK_LOGS': {
86
+ 'METHOD': 'GET',
87
+ 'PATH': '/apps/{app_id}/network/logs',
88
+ },
89
+ 'NETWORK_PERFORMANCE': {
90
+ 'METHOD': 'GET',
91
+ 'PATH': '/apps/{app_id}/network/performance',
92
+ },
93
+ 'PURGE_CACHE': {
94
+ 'METHOD': 'POST',
95
+ 'PATH': '/apps/{app_id}/network/purge_cache',
96
+ },
67
97
  'ENVS_GET': {'METHOD': 'GET', 'PATH': '/apps/{app_id}/envs'},
68
98
  'ENVS_PUT': {'METHOD': 'PUT', 'PATH': '/apps/{app_id}/envs'},
69
99
  'ENVS_POST': {'METHOD': 'POST', 'PATH': '/apps/{app_id}/envs'},
@@ -75,6 +105,9 @@ class Endpoint:
75
105
  'EDIT_DATABASE': {'METHOD': 'PATCH', 'PATH': '/databases/{database_id}'},
76
106
  'DELETE_DATABASE': {'METHOD': 'DELETE', 'PATH': '/databases/{database_id}'},
77
107
  'ALL_DATABASES_STATUS': {'METHOD': 'GET', 'PATH': '/databases/status'},
108
+ 'DATABASE_METRICS': {'METHOD': 'GET', 'PATH': '/databases/{database_id}/metrics'},
109
+ 'ALL_DATABASE_SNAPSHOTS': {'METHOD': 'GET', 'PATH': '/databases/{database_id}/snapshots'},
110
+ 'DATABASE_SNAPSHOT': {'METHOD': 'POST', 'PATH': '/databases/{database_id}/snapshots'},
78
111
  'DATABASE_STATUS': {'METHOD': 'GET', 'PATH': '/databases/{database_id}/status'},
79
112
  'GET_DATABASE_CERTIFICATE': {'METHOD': 'GET', 'PATH': '/databases/{database_id}/credentials/certificate'},
80
113
  'RESET_DATABASE_CREDENTIALS': {'METHOD': 'POST', 'PATH': '/databases/{database_id}/credentials/reset'},
@@ -544,6 +577,126 @@ class Endpoint:
544
577
 
545
578
  return cls('GET_WORKSPACE')
546
579
 
580
+ @classmethod
581
+ def user_snapshots(cls) -> Endpoint:
582
+ """
583
+ Returns an Endpoint object that represents the
584
+ /users/snapshots endpoint.
585
+ """
586
+ return cls('USER_SNAPSHOTS')
587
+
588
+ @classmethod
589
+ def service_status(cls) -> Endpoint:
590
+ """
591
+ Returns an Endpoint object that represents the
592
+ /service/status endpoint.
593
+ """
594
+ return cls('SERVICE_STATUS')
595
+
596
+ @classmethod
597
+ def all_domains(cls) -> Endpoint:
598
+ """
599
+ Returns an Endpoint object that represents the
600
+ /apps/domains endpoint.
601
+ """
602
+ return cls('ALL_DOMAINS')
603
+
604
+ @classmethod
605
+ def load_balancers(cls) -> Endpoint:
606
+ """
607
+ Returns an Endpoint object that represents the
608
+ /apps/load-balancers endpoint.
609
+ """
610
+ return cls('LOAD_BALANCERS')
611
+
612
+ @classmethod
613
+ def app_metrics(cls) -> Endpoint:
614
+ """
615
+ Returns an Endpoint object that represents the
616
+ /apps/{app_id}/metrics endpoint.
617
+ """
618
+ return cls('APP_METRICS')
619
+
620
+ @classmethod
621
+ def realtime(cls) -> Endpoint:
622
+ """
623
+ Returns an Endpoint object that represents the
624
+ /apps/{app_id}/realtime endpoint.
625
+ """
626
+ return cls('REALTIME')
627
+
628
+ @classmethod
629
+ def github_app_link(cls) -> Endpoint:
630
+ """
631
+ Returns an Endpoint object that represents the
632
+ /apps/{app_id}/deploy/github-app POST endpoint.
633
+ """
634
+ return cls('GITHUB_APP_LINK')
635
+
636
+ @classmethod
637
+ def github_app_unlink(cls) -> Endpoint:
638
+ """
639
+ Returns an Endpoint object that represents the
640
+ /apps/{app_id}/deploy/github-app DELETE endpoint.
641
+ """
642
+ return cls('GITHUB_APP_UNLINK')
643
+
644
+ @classmethod
645
+ def network_errors(cls) -> Endpoint:
646
+ """
647
+ Returns an Endpoint object that represents the
648
+ /apps/{app_id}/network/errors endpoint.
649
+ """
650
+ return cls('NETWORK_ERRORS')
651
+
652
+ @classmethod
653
+ def network_logs(cls) -> Endpoint:
654
+ """
655
+ Returns an Endpoint object that represents the
656
+ /apps/{app_id}/network/logs endpoint.
657
+ """
658
+ return cls('NETWORK_LOGS')
659
+
660
+ @classmethod
661
+ def network_performance(cls) -> Endpoint:
662
+ """
663
+ Returns an Endpoint object that represents the
664
+ /apps/{app_id}/network/performance endpoint.
665
+ """
666
+ return cls('NETWORK_PERFORMANCE')
667
+
668
+ @classmethod
669
+ def purge_cache(cls) -> Endpoint:
670
+ """
671
+ Returns an Endpoint object that represents the
672
+ /apps/{app_id}/network/purge_cache endpoint.
673
+ """
674
+ return cls('PURGE_CACHE')
675
+
676
+ @classmethod
677
+ def database_metrics(cls) -> Endpoint:
678
+ """
679
+ Returns an Endpoint object that represents the
680
+ /databases/{database_id}/metrics endpoint.
681
+ """
682
+ return cls('DATABASE_METRICS')
683
+
684
+ @classmethod
685
+ def all_database_snapshots(cls) -> Endpoint:
686
+ """
687
+ Returns an Endpoint object that represents the
688
+ /databases/{database_id}/snapshots GET endpoint.
689
+ """
690
+ return cls('ALL_DATABASE_SNAPSHOTS')
691
+
692
+ @classmethod
693
+ def database_snapshot(cls) -> Endpoint:
694
+ """
695
+ Returns an Endpoint object that represents the
696
+ /databases/{database_id}/snapshots POST endpoint.
697
+ """
698
+ return cls('DATABASE_SNAPSHOT')
699
+
547
700
  # pylint: disable=too-few-public-methods
548
701
  class Router:
549
702
  """Represents a route"""
@@ -1,6 +1,8 @@
1
1
  from __future__ import annotations
2
2
 
3
+ import json
3
4
  import logging
5
+ from collections.abc import AsyncGenerator
4
6
  from typing import Any, Literal
5
7
 
6
8
  import aiohttp
@@ -104,6 +106,8 @@ def _get_error(code: str) -> type[RequestError] | None:
104
106
  class HTTPClient:
105
107
  """A client that handles requests and responses"""
106
108
 
109
+ USER_AGENT = 'squarecloud-sdk-py/4.1.0'
110
+
107
111
  def __init__(self, api_key: str) -> None:
108
112
  """
109
113
  The __init__ function is called when the class is instantiated.
@@ -163,7 +167,7 @@ class HTTPClient:
163
167
  """
164
168
  headers = {
165
169
  'Authorization': self.api_key,
166
- 'User-Agent': 'squarecloud-sdk-py/4.0.0',
170
+ 'User-Agent': self.USER_AGENT,
167
171
  }
168
172
  extra_error_kwargs: dict[str, Any] = {}
169
173
 
@@ -662,12 +666,17 @@ class HTTPClient:
662
666
  )
663
667
  return response
664
668
 
665
- async def domain_analytics(self, app_id: str) -> Response:
669
+ async def domain_analytics(
670
+ self, app_id: str, params: dict[str, str] | None = None
671
+ ) -> Response:
666
672
  """
667
673
  The domain_analytics method returns a list of all domains analytics
668
674
  for the specified app.
669
675
 
670
676
  :param app_id: The application id
677
+ :param params: Optional query params (start/end window and
678
+ drill-down filters such as country, ip, path, status, os,
679
+ browser, protocol, referer, provider, content_type, bot)
671
680
  :return: A Response object
672
681
  :rtype: Response
673
682
 
@@ -679,7 +688,7 @@ class HTTPClient:
679
688
  code is 429
680
689
  """
681
690
  route: Router = Router(Endpoint.domain_analytics(), app_id=app_id)
682
- response: Response = await self.request(route)
691
+ response: Response = await self.request(route, params=params or {})
683
692
  return response
684
693
 
685
694
  async def get_all_app_snapshots(self, app_id: str) -> Response:
@@ -1119,4 +1128,219 @@ class HTTPClient:
1119
1128
  """
1120
1129
  route: Router = Router(Endpoint.workspaces_members_code())
1121
1130
  response: Response = await self.request(route)
1122
- return response
1131
+ return response
1132
+
1133
+ async def fetch_user_snapshots(self, scope: str) -> Response:
1134
+ """
1135
+ Fetch the authenticated user's snapshots.
1136
+
1137
+ :param scope: Snapshot scope ("applications" or "databases").
1138
+ :return: A Response object.
1139
+ """
1140
+ route: Router = Router(Endpoint.user_snapshots())
1141
+ return await self.request(route, params={'scope': scope})
1142
+
1143
+ async def fetch_service_status(self) -> Response:
1144
+ """
1145
+ Fetch the aggregate platform status.
1146
+
1147
+ Note: this endpoint does not wrap its payload in the usual
1148
+ {status, response} envelope — it returns {status, message} directly.
1149
+
1150
+ :return: A Response object (payload in Response.data).
1151
+ """
1152
+ route: Router = Router(Endpoint.service_status())
1153
+ return await self.request(route)
1154
+
1155
+ async def fetch_all_domains(self) -> Response:
1156
+ """
1157
+ Fetch every domain configured across the user's applications.
1158
+
1159
+ :return: A Response object.
1160
+ """
1161
+ route: Router = Router(Endpoint.all_domains())
1162
+ return await self.request(route)
1163
+
1164
+ async def fetch_load_balancers(self) -> Response:
1165
+ """
1166
+ Fetch the user's custom-domain load balancers.
1167
+
1168
+ :return: A Response object.
1169
+ """
1170
+ route: Router = Router(Endpoint.load_balancers())
1171
+ return await self.request(route)
1172
+
1173
+ async def fetch_app_metrics(self, app_id: str) -> Response:
1174
+ """
1175
+ Fetch the last 24h of metrics for an application.
1176
+
1177
+ :param app_id: The application id.
1178
+ :return: A Response object.
1179
+ """
1180
+ route: Router = Router(Endpoint.app_metrics(), app_id=app_id)
1181
+ return await self.request(route)
1182
+
1183
+ async def fetch_database_metrics(self, database_id: str) -> Response:
1184
+ """
1185
+ Fetch the last 24h of metrics for a database.
1186
+
1187
+ :param database_id: The database id.
1188
+ :return: A Response object.
1189
+ """
1190
+ route: Router = Router(
1191
+ Endpoint.database_metrics(), database_id=database_id
1192
+ )
1193
+ return await self.request(route)
1194
+
1195
+ async def link_github_app(
1196
+ self, app_id: str, repository_name: str, repository_branch: str
1197
+ ) -> Response:
1198
+ """
1199
+ Link a GitHub repository via the Square Cloud GitHub App.
1200
+ Requires a session token (JWT); API keys are not accepted.
1201
+
1202
+ :param app_id: The application id.
1203
+ :param repository_name: Full repository name (e.g. octocat/hello-world).
1204
+ :param repository_branch: Repository branch.
1205
+ :return: A Response object.
1206
+ """
1207
+ route: Router = Router(Endpoint.github_app_link(), app_id=app_id)
1208
+ body = {
1209
+ 'repositoryName': repository_name,
1210
+ 'repositoryBranch': repository_branch,
1211
+ }
1212
+ return await self.request(route, json=body)
1213
+
1214
+ async def unlink_github_app(self, app_id: str) -> Response:
1215
+ """
1216
+ Unlink the GitHub App repository from an application.
1217
+ Requires a session token (JWT); API keys are not accepted.
1218
+
1219
+ :param app_id: The application id.
1220
+ :return: A Response object.
1221
+ """
1222
+ route: Router = Router(Endpoint.github_app_unlink(), app_id=app_id)
1223
+ return await self.request(route)
1224
+
1225
+ async def network_errors(
1226
+ self, app_id: str, start: str, end: str, include_4xx: bool = False
1227
+ ) -> Response:
1228
+ """
1229
+ Fetch the aggregated edge error breakdown for an application.
1230
+
1231
+ :param app_id: The application id.
1232
+ :param start: ISO 8601 start timestamp.
1233
+ :param end: ISO 8601 end timestamp.
1234
+ :param include_4xx: Include 4xx alongside 5xx (default 5xx only).
1235
+ :return: A Response object.
1236
+ """
1237
+ route: Router = Router(Endpoint.network_errors(), app_id=app_id)
1238
+ params = {'start': start, 'end': end}
1239
+ if include_4xx:
1240
+ params['include_4xx'] = 'true'
1241
+ return await self.request(route, params=params)
1242
+
1243
+ async def network_logs(self, app_id: str, start: str, end: str) -> Response:
1244
+ """
1245
+ Fetch the per-request edge logs for an application.
1246
+
1247
+ :param app_id: The application id.
1248
+ :param start: ISO 8601 start timestamp.
1249
+ :param end: ISO 8601 end timestamp.
1250
+ :return: A Response object.
1251
+ """
1252
+ route: Router = Router(Endpoint.network_logs(), app_id=app_id)
1253
+ return await self.request(route, params={'start': start, 'end': end})
1254
+
1255
+ async def network_performance(
1256
+ self, app_id: str, start: str, end: str
1257
+ ) -> Response:
1258
+ """
1259
+ Fetch edge and origin latency percentiles for an application.
1260
+
1261
+ :param app_id: The application id.
1262
+ :param start: ISO 8601 start timestamp.
1263
+ :param end: ISO 8601 end timestamp.
1264
+ :return: A Response object.
1265
+ """
1266
+ route: Router = Router(Endpoint.network_performance(), app_id=app_id)
1267
+ return await self.request(route, params={'start': start, 'end': end})
1268
+
1269
+ async def purge_cache(self, app_id: str) -> Response:
1270
+ """
1271
+ Purge the entire edge cache for an application's domains.
1272
+
1273
+ :param app_id: The application id.
1274
+ :return: A Response object.
1275
+ """
1276
+ route: Router = Router(Endpoint.purge_cache(), app_id=app_id)
1277
+ return await self.request(route)
1278
+
1279
+ async def get_all_database_snapshots(self, database_id: str) -> Response:
1280
+ """
1281
+ Fetch all snapshots of a database.
1282
+
1283
+ :param database_id: The database id.
1284
+ :return: A Response object.
1285
+ """
1286
+ route: Router = Router(
1287
+ Endpoint.all_database_snapshots(), database_id=database_id
1288
+ )
1289
+ return await self.request(route)
1290
+
1291
+ async def create_database_snapshot(self, database_id: str) -> Response:
1292
+ """
1293
+ Create a snapshot of a database.
1294
+
1295
+ :param database_id: The database id.
1296
+ :return: A Response object.
1297
+ """
1298
+ route: Router = Router(
1299
+ Endpoint.database_snapshot(), database_id=database_id
1300
+ )
1301
+ return await self.request(route)
1302
+
1303
+ async def realtime(
1304
+ self, app_id: str
1305
+ ) -> AsyncGenerator[dict[str, Any] | str, None]:
1306
+ """
1307
+ Stream realtime status events (SSE) for an application.
1308
+ Max 5 concurrent connections per user; connections live for
1309
+ up to 10 minutes.
1310
+
1311
+ :param app_id: The application id.
1312
+ :return: An async generator yielding decoded events (dict when the
1313
+ payload is JSON, raw str otherwise).
1314
+ """
1315
+ route: Router = Router(Endpoint.realtime(), app_id=app_id)
1316
+ headers = {
1317
+ 'Authorization': self.api_key,
1318
+ 'User-Agent': self.USER_AGENT,
1319
+ 'Accept': 'text/event-stream',
1320
+ }
1321
+ # total=None so the long-lived (up to 10 min) stream isn't cut by
1322
+ # aiohttp's default 5-min total timeout; sock_read still detects a
1323
+ # dead connection.
1324
+ timeout = aiohttp.ClientTimeout(total=None, sock_read=90)
1325
+ async with self.__session(headers=headers, timeout=timeout) as session:
1326
+ async with session.get(route.url) as resp:
1327
+ if resp.status != 200:
1328
+ error: type[RequestError] = {
1329
+ 401: AuthenticationFailure,
1330
+ 404: NotFoundError,
1331
+ 429: TooManyRequests,
1332
+ }.get(resp.status, RequestError)
1333
+ raise error(
1334
+ route=route.endpoint.name,
1335
+ status_code=resp.status,
1336
+ code='REALTIME_CONNECTION_FAILED',
1337
+ )
1338
+ async for raw in resp.content:
1339
+ line = raw.decode('utf-8', errors='replace').strip()
1340
+ if not line.startswith('data:'):
1341
+ continue
1342
+ payload = line[len('data:'):].strip()
1343
+ try:
1344
+ yield json.loads(payload)
1345
+ except ValueError:
1346
+ yield payload
File without changes