creat01deployengine 1.0.0__tar.gz → 1.0.1__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 (52) hide show
  1. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/.gitignore +8 -0
  2. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/AI_USAGE.md +12 -7
  3. creat01deployengine-1.0.1/PKG-INFO +164 -0
  4. creat01deployengine-1.0.1/README.md +148 -0
  5. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/pyproject.toml +1 -1
  6. creat01deployengine-1.0.1/src/creat01deployengine/logging/__init__.py +5 -0
  7. creat01deployengine-1.0.1/src/creat01deployengine/models/__init__.py +27 -0
  8. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/models/common.py +1 -1
  9. creat01deployengine-1.0.1/src/creat01deployengine/models/infrastructure.py +86 -0
  10. creat01deployengine-1.0.1/src/creat01deployengine/models/project_ssl.py +61 -0
  11. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/models/projects.py +7 -4
  12. creat01deployengine-1.0.1/src/creat01deployengine/models/users.py +38 -0
  13. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/__init__.py +6 -4
  14. creat01deployengine-1.0.1/src/creat01deployengine/resources/authentication.py +64 -0
  15. creat01deployengine-1.0.1/src/creat01deployengine/resources/certificates.py +32 -0
  16. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/load_balancers.py +10 -2
  17. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/machines.py +14 -0
  18. creat01deployengine-1.0.1/src/creat01deployengine/resources/managed_registry.py +81 -0
  19. creat01deployengine-1.0.1/src/creat01deployengine/resources/projects.py +75 -0
  20. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/tracking.py +7 -12
  21. creat01deployengine-1.0.1/src/creat01deployengine/resources/users.py +48 -0
  22. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/workflows.py +1 -1
  23. creat01deployengine-1.0.1/src/creat01deployengine/tracking/__init__.py +5 -0
  24. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/tracking/client.py +23 -15
  25. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/version.py +1 -1
  26. creat01deployengine-1.0.1/tests/test_client.py +178 -0
  27. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/tests/test_live_api.py +0 -1
  28. creat01deployengine-1.0.1/tests/test_models.py +24 -0
  29. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/tests/test_resource_contracts.py +155 -32
  30. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/uv.lock +1 -1
  31. creat01deployengine-1.0.0/PKG-INFO +0 -81
  32. creat01deployengine-1.0.0/README.md +0 -65
  33. creat01deployengine-1.0.0/src/creat01deployengine/logging/__init__.py +0 -5
  34. creat01deployengine-1.0.0/src/creat01deployengine/models/__init__.py +0 -14
  35. creat01deployengine-1.0.0/src/creat01deployengine/models/infrastructure.py +0 -27
  36. creat01deployengine-1.0.0/src/creat01deployengine/resources/authentication.py +0 -38
  37. creat01deployengine-1.0.0/src/creat01deployengine/resources/certificates.py +0 -19
  38. creat01deployengine-1.0.0/src/creat01deployengine/resources/projects.py +0 -37
  39. creat01deployengine-1.0.0/src/creat01deployengine/resources/security_groups.py +0 -28
  40. creat01deployengine-1.0.0/src/creat01deployengine/tracking/__init__.py +0 -5
  41. creat01deployengine-1.0.0/tests/test_client.py +0 -94
  42. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/LICENSE +0 -0
  43. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/__init__.py +0 -0
  44. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/client.py +0 -0
  45. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/errors.py +0 -0
  46. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/logging/reporter.py +0 -0
  47. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/py.typed +0 -0
  48. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/alerts.py +0 -0
  49. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/base.py +0 -0
  50. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/domains.py +0 -0
  51. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/feedback.py +0 -0
  52. {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/payments.py +0 -0
@@ -49,6 +49,7 @@ coverage.xml
49
49
  *.py,cover
50
50
  .hypothesis/
51
51
  .pytest_cache/
52
+ .deepeval/
52
53
  cover/
53
54
 
54
55
  # Translations
@@ -205,10 +206,17 @@ pip_packages/
205
206
  *.mp4
206
207
  *.mp3
207
208
  *.pem
209
+ deploy/managed-registry/certs/token-signing.key
208
210
  local_settings.py
209
211
  certs/
210
212
  reference/
213
+ # Public reference articles are part of the shipped documentation.
214
+ !portal/src/content/docs/reference/
215
+ !portal/src/content/docs/reference/*.md
216
+ !portal/src/content/docs-en/reference/
217
+ !portal/src/content/docs-en/reference/*.md
211
218
  *.bak
212
219
  *.dat
213
220
  *.dir
214
221
  .dev/
222
+ .artifacts/
@@ -4,8 +4,8 @@ Use this decision order when generating code with `creat01deployengine`.
4
4
 
5
5
  1. For management operations, read `DEPLOYENGINE_API_KEY` from the server
6
6
  environment and create `DeployEngine` or `AsyncDeployEngine`.
7
- 2. For browser/application telemetry, use only `Tracker` with a project
8
- `write_key`. Never substitute a management API key.
7
+ 2. Use the tracking resource or `Tracker` only in trusted server code, with
8
+ the user API Key and project name. Never place the key in browser code.
9
9
  3. Prefer named resource methods over raw `client.request`.
10
10
  4. For writes, provide an idempotency key when the method accepts one. Never
11
11
  retry a payment, deployment, DNS, or infrastructure write blindly.
@@ -29,15 +29,16 @@ DNS records -> domains.records/create_record/update_re
29
29
  sync load balancer -> load_balancers.sync
30
30
  bind project to load balancer -> load_balancers.bind_project
31
31
  add load-balancer listener -> load_balancers.add_listener
32
- apply host firewall -> security_groups.apply
33
- add firewall rule -> security_groups.add_rule
34
32
  send alert -> alerts.send
35
33
  create payment -> payments.create_order
36
34
  refund payment -> payments.refund
37
- send end-user login code -> authentication.send_code
38
- login with code/password -> authentication.login_with_code/password_login
35
+ send end-user registration code -> authentication.send_registration_code
36
+ register/login with password -> authentication.register/password_login
37
+ recover/change/refresh end-user auth -> authentication.forgot_password/reset_password/change_password/refresh_token
39
38
  create customer feedback link -> feedback.create_ticket_link
40
- tracking analytics/identity -> Tracker.track/identify
39
+ list/create platform users -> users.list/create
40
+ change role/delete platform user -> users.change_role/delete
41
+ tracking analytics/identity -> client.tracking.collect/identify or Tracker.track/identify
41
42
  send application log -> LogReporter.debug/info/warning/error
42
43
  ```
43
44
 
@@ -62,7 +63,11 @@ async def deploy(project_id: int, body: dict) -> None:
62
63
  raise
63
64
  ```
64
65
 
66
+ Tracking ingestion uses the existing `business` or `full_access` API Key scope.
65
67
  Scopes: `read`, `deploy`, `machines`, `databases`, `certificates`,
66
68
  `monitoring`, `infrastructure`, and `business`. A 403 means the key needs the
67
69
  scope documented on the resource; do not work around it with a broader key in
68
70
  client code.
71
+
72
+ User management is administrator-only. Its write methods require an
73
+ administrator Bearer JWT; do not attempt them with a management API key.
@@ -0,0 +1,164 @@
1
+ Metadata-Version: 2.5
2
+ Name: creat01deployengine
3
+ Version: 1.0.1
4
+ Summary: Official Python SDK for Creat01 DeployEngine
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Classifier: Development Status :: 4 - Beta
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Typing :: Typed
10
+ Requires-Python: >=3.9
11
+ Requires-Dist: httpx<1,>=0.27
12
+ Provides-Extra: test
13
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
14
+ Requires-Dist: pytest>=8; extra == 'test'
15
+ Description-Content-Type: text/markdown
16
+
17
+ # creat01deployengine Python SDK
18
+
19
+ Release **1.0.1** follows the repository's sequential version policy. It changes the tracking and project authentication contracts from public 1.0.0; read the [migration guide](https://jihulab.com/creat01-group1/deployengine/-/blob/main/client/MIGRATION.md) before upgrading. Version increments do not imply backward compatibility.
20
+
21
+ 机器 Nginx 站点列表与正文返回 `readOnly`、`projectBindings`,公开类型为 `NginxConfigInfo`、`NginxConfigContent` 和 `NginxProjectBinding`。项目相关站点在通用机器配置 API 中仅可读取,编辑、重命名/创建覆盖、启停及批量删除均返回 409/ConflictError,需转到项目接口操作。Python/TypeScript SDK 均没有专用 Nginx 资源域,沿用通用 request 调用,不新增业务方法;两端同步公开类型和 OpenAPI 契约。 原文件与同名启用入口联合判定;即使原文件独立,只要启用入口的软链、硬链或标记副本关联项目,readOnly 也为 true,通用写请求返回 409。
22
+
23
+ Official synchronous and asynchronous clients for the DeployEngine API.
24
+
25
+ ```bash
26
+ python -m pip install creat01deployengine
27
+ ```
28
+
29
+ Use `DeployEngine` in synchronous code, `AsyncDeployEngine` in asyncio code,
30
+ and `Tracker`/`LogReporter` for application-side event ingestion. Never ship a
31
+ management API key in browser, desktop, or mobile code.
32
+
33
+ ## Managed private Registry
34
+
35
+ ```python
36
+ client.managed_registry.set_namespace("alice-space") # Globally unique; existing images and references are migrated.
37
+ repositories = client.managed_registry.repositories()
38
+ references = client.managed_registry.references("alice-space/team/api")
39
+ subscriptions = client.managed_registry.image_auto_updates()
40
+ client.managed_registry.delete_repository("alice-space/team/obsolete") # Deletes every tag and manifest when unreferenced.
41
+ ```
42
+
43
+
44
+ 托管 Registry 支持项目镜像自动更新订阅。
45
+
46
+ 镜像部署前可调用 `client.managed_registry.connect_image_registry()` 建立 pull-only 镜像连接。
47
+
48
+ ```python
49
+ connection = client.managed_registry.connect_image_registry()
50
+ client.projects.save_image_auto_update(42, connection["id"], "alice-space/team/api", tag="latest")
51
+ # Pause/resume without losing the saved tag or update policy.
52
+ saved = client.projects.image_auto_update(42)
53
+ client.projects.save_image_auto_update(
54
+ 42, saved["registry_id"], saved["repository"], tag=saved["tag"],
55
+ enabled=False, update_mode=saved["update_mode"],
56
+ ignore_platform_builds=saved["ignore_platform_builds"],
57
+ ) # Use enabled=True with the same saved fields to resume.
58
+ # Permanently remove the subscription configuration.
59
+ client.projects.delete_image_auto_update(42)
60
+
61
+ ```
62
+
63
+ Docker login accepts either the DeployEngine account username/password or a separate Registry credential. Create, list, rotate, and revoke separate credentials with `client.managed_registry`; the secret is returned only on creation or rotation, never expires automatically, and remains valid until revoked or rotated. Both user credential types are restricted to the caller's namespace. The SDK returns the one-time secret to the caller and does not store it. The platform generates separate short-lived internal credentials for unattended builds and deployments. Portal JWTs and management API keys are not Docker credentials.
64
+
65
+ ```python
66
+ import os
67
+ from creat01deployengine import DeployEngine
68
+ from creat01deployengine.errors import PermissionDeniedError
69
+
70
+ try:
71
+ with DeployEngine(
72
+ api_key=os.environ["DEPLOYENGINE_API_KEY"],
73
+ base_url="https://deployengine.creat01.com",
74
+ ) as client:
75
+ projects = client.projects.list(page=1, pageSize=20)
76
+ machine = client.machines.get(12)
77
+ except PermissionDeniedError as exc:
78
+ print(f"missing API scope; request={exc.request_id}")
79
+ ```
80
+
81
+ ```python
82
+ from creat01deployengine import AsyncDeployEngine
83
+
84
+ async with AsyncDeployEngine(api_key=key) as client:
85
+ projects = await client.projects.list()
86
+ ```
87
+
88
+ ## Resource map
89
+
90
+ | Attribute | Purpose | Typical scope |
91
+ |---|---|---|
92
+ | `projects` | CRUD, precheck, deployments, releases, deploy/restart streams | `read`, `deploy` |
93
+ | `machines` | CRUD, recommendations, Agent state, port checks | `machines` |
94
+ | `workflows` | Task progress, detail, termination | `read`, `deploy` |
95
+ | `certificates` | CRUD, upload, manual/automatic Let's Encrypt renewal, deployment | `certificates` |
96
+ | `domains` | Domain CRUD and DNS records | `read` |
97
+ | `load_balancers` | Gateway config, sync, bindings, listeners | `infrastructure` |
98
+ | `alerts` | Alert contacts and notification sending | `monitoring` |
99
+ | `payments` | Payment orders and refunds | `business` |
100
+ | `authentication` | Project account/password registration, login, recovery and sessions; SMS/email code requests take an owner-scoped `credential_id` per call | public `projectId` / end-user bearer token |
101
+ | `feedback` | Customer feedback ticket links | `business` |
102
+ | `tracking` | Project event ingestion | `business` API Key scope |
103
+ | `users` | Admin-only user list/create/role/deletion | administrator role; JWT for writes |
104
+
105
+ ```python
106
+ with DeployEngine(access_token=admin_jwt) as admin:
107
+ page = admin.users.list(page=1, page_size=20, role="user", keyword="ops")
108
+ created = admin.users.create({"username": "operator", "password": "secret123"})
109
+ admin.users.change_role(created["id"], "admin")
110
+ admin.users.delete(created["id"])
111
+ ```
112
+
113
+ User-management writes require an administrator Bearer JWT; the list also
114
+ accepts an administrator API key. Authenticated non-admin users receive
115
+ `PermissionDeniedError`. Business-capability management is likewise admin-only,
116
+ while login, callback, and one-time feedback endpoints keep
117
+ their project credential, signature, or token authentication. Project tracking
118
+ uses the API Key and project name supplied to the tracking resource.
119
+
120
+ ```python
121
+ with DeployEngine(api_key=key) as client:
122
+ for event in client.projects.deploy_stream(7, {"branch": "main"}):
123
+ print(event)
124
+ ```
125
+
126
+ Resources return the unwrapped `data` field. Writes are not retried unless an
127
+ idempotency key is present. `DeployEngineError` exposes `status_code`, `code`,
128
+ `request_id`, `details`, and `retryable`. See `AI_USAGE.md` for task recipes.
129
+
130
+ Machine metrics start automatically after machine creation and Agent
131
+ connection, at a system-owned one-minute interval. This SDK does not currently
132
+ expose the `/api/monitor/machines` HTTP resource; `alerts` manages alert
133
+ contacts only. Existing direct HTTP integrations should move threshold/contact
134
+ updates to `PUT /api/monitor/machines/{machine_id}/alert-config`; legacy monitor
135
+ add, remove, and interval endpoints remain compatibility-only.
136
+
137
+ Maintainers can run the opt-in live smoke test with
138
+ `DEPLOYENGINE_E2E_API_KEY=... pytest tests/test_live_api.py`. It performs only
139
+ authenticated list operations and does not deploy or mutate resources.
140
+
141
+ 证书续期:`client.certificates.renew(cert_id)` 会触发已有部署机器的证书更新及 Nginx 重载;任一机器失败时返回错误,需检查对应部署记录。
142
+
143
+ ## Load balancer sync
144
+
145
+ `client.load_balancers.sync(id)` synchronizes bound project gateway configuration. HTTP 200 is not proof of application: check `sync_status`, `last_sync_error`, `config_revision`, and `applied_revision` in the returned data. Independent listener records (even disabled ones) are metadata only and make sync fail before remote operations. Configure domains and certificates on the project instead; remove independent listener metadata before retrying. Removing metadata does not remove project sites. New or changed configurations remain `pending` until sync succeeds for the current revision; old `ready` records should be resynced. Methods, paths and response envelopes remain compatible; this corrects false success reporting.
146
+
147
+ 机器证书部署查询:Python `client.certificates.machine_deployments(machine_id)`,TypeScript `client.api.certificates.machineDeployments(machineId)` 调用 `GET /api/certificates/machines/{machine_id}/deployments`,返回 `{ list: [...] }`。仅返回当前用户所拥有机器的部署元数据与证书名称/域名,不包含 PEM 或私钥内容;不可见或不存在的机器返回 HTTP 404。该能力为兼容性新增。
148
+
149
+
150
+ ### 项目 SSL 证书
151
+
152
+ 项目域名发布默认要求 HTTPS,必须先确认每个域名的证书绑定并部署到入口机器;无证书时不会静默降级。需要 HTTP 时显式保存 `mode: "http"`。旧客户端请求字段保持兼容,但未准备证书的域名发布现在返回就绪错误;运行中的服务不会因升级自动改配置。证书申请继续使用独立证书工作流。
153
+
154
+ Python:`client.api.projects.ssl(id, check_remote=True)`、`save_ssl(id, {"mode": "https", "bindings": {"app.example.com": certificate_id}})`、`deploy_ssl(id, "app.example.com")`、`preview_ssl(id)`、`apply_ssl(id, preview["revision"])`。TypeScript 对应 `ssl(id, true)`、`saveSsl`、`deploySsl`、`previewSsl`、`applySsl`。查询可传 `host` 准备待新增域名。类型为 `ProjectSslPolicy`、`ProjectSslStatus`、`ProjectSslPreview`。保存绑定只修改期望配置,应用前必须审阅预览的站点替换内容;409 表示未就绪、操作冲突或需要重新预览。返回元数据不含证书/私钥正文。应用只核对入口本机 TLS;公网 DNS、CDN、防火墙需单独验证。
155
+
156
+ 工作流 `GET /api/workflow-tasks/{task_id}/progress` 的 `logPreview` 为最多 12,000 字符的日志尾部;完整保留日志使用 `/detail` 的 `logContent`。接口路径、字段与认证保持兼容。 零停机清理恢复及按次诊断语义见 [SDK 说明](../../docs/sdk.md)。
157
+
158
+ ### 系统自动识别与容器盘点
159
+
160
+ 机器创建/修改连接信息自动保存系统版本和架构;读取 `platform` 与 `platformProbeAt`,无需手动填写系统。Python 使用 `client.machines.container_inventory(machine_id=7)`,TypeScript 使用 `client.api.machines.containerInventory(7)`;省略机器 ID 查询本人全部机器。`machines[]` 包含采集时间、ready/unavailable、errorCode 与容器列表,局部失败必须单独处理。容器的 `readOnly` 与 `projectBindings` 指示项目生命周期归属;项目容器只读,通用写操作(包括强制删除)返回 409,须通过项目流程管理。大规模盘点最长 90 秒,请将客户端 timeout 配置为 120 秒。容器操作使用机器 ID 与完整容器 ID;409 表示操作未完成,先刷新确认再重试。详见[SDK 说明](../../docs/sdk.md)。
161
+
162
+ ### 部署失败诊断与日志兼容性
163
+
164
+ 部署失败事件的 `content` 可包含容器状态与启动日志;失败或清理后可用通用 request 查询原项目日志接口。现有方法、字段和认证保持兼容;详见[SDK 说明](../../docs/sdk.md)。
@@ -0,0 +1,148 @@
1
+ # creat01deployengine Python SDK
2
+
3
+ Release **1.0.1** follows the repository's sequential version policy. It changes the tracking and project authentication contracts from public 1.0.0; read the [migration guide](https://jihulab.com/creat01-group1/deployengine/-/blob/main/client/MIGRATION.md) before upgrading. Version increments do not imply backward compatibility.
4
+
5
+ 机器 Nginx 站点列表与正文返回 `readOnly`、`projectBindings`,公开类型为 `NginxConfigInfo`、`NginxConfigContent` 和 `NginxProjectBinding`。项目相关站点在通用机器配置 API 中仅可读取,编辑、重命名/创建覆盖、启停及批量删除均返回 409/ConflictError,需转到项目接口操作。Python/TypeScript SDK 均没有专用 Nginx 资源域,沿用通用 request 调用,不新增业务方法;两端同步公开类型和 OpenAPI 契约。 原文件与同名启用入口联合判定;即使原文件独立,只要启用入口的软链、硬链或标记副本关联项目,readOnly 也为 true,通用写请求返回 409。
6
+
7
+ Official synchronous and asynchronous clients for the DeployEngine API.
8
+
9
+ ```bash
10
+ python -m pip install creat01deployengine
11
+ ```
12
+
13
+ Use `DeployEngine` in synchronous code, `AsyncDeployEngine` in asyncio code,
14
+ and `Tracker`/`LogReporter` for application-side event ingestion. Never ship a
15
+ management API key in browser, desktop, or mobile code.
16
+
17
+ ## Managed private Registry
18
+
19
+ ```python
20
+ client.managed_registry.set_namespace("alice-space") # Globally unique; existing images and references are migrated.
21
+ repositories = client.managed_registry.repositories()
22
+ references = client.managed_registry.references("alice-space/team/api")
23
+ subscriptions = client.managed_registry.image_auto_updates()
24
+ client.managed_registry.delete_repository("alice-space/team/obsolete") # Deletes every tag and manifest when unreferenced.
25
+ ```
26
+
27
+
28
+ 托管 Registry 支持项目镜像自动更新订阅。
29
+
30
+ 镜像部署前可调用 `client.managed_registry.connect_image_registry()` 建立 pull-only 镜像连接。
31
+
32
+ ```python
33
+ connection = client.managed_registry.connect_image_registry()
34
+ client.projects.save_image_auto_update(42, connection["id"], "alice-space/team/api", tag="latest")
35
+ # Pause/resume without losing the saved tag or update policy.
36
+ saved = client.projects.image_auto_update(42)
37
+ client.projects.save_image_auto_update(
38
+ 42, saved["registry_id"], saved["repository"], tag=saved["tag"],
39
+ enabled=False, update_mode=saved["update_mode"],
40
+ ignore_platform_builds=saved["ignore_platform_builds"],
41
+ ) # Use enabled=True with the same saved fields to resume.
42
+ # Permanently remove the subscription configuration.
43
+ client.projects.delete_image_auto_update(42)
44
+
45
+ ```
46
+
47
+ Docker login accepts either the DeployEngine account username/password or a separate Registry credential. Create, list, rotate, and revoke separate credentials with `client.managed_registry`; the secret is returned only on creation or rotation, never expires automatically, and remains valid until revoked or rotated. Both user credential types are restricted to the caller's namespace. The SDK returns the one-time secret to the caller and does not store it. The platform generates separate short-lived internal credentials for unattended builds and deployments. Portal JWTs and management API keys are not Docker credentials.
48
+
49
+ ```python
50
+ import os
51
+ from creat01deployengine import DeployEngine
52
+ from creat01deployengine.errors import PermissionDeniedError
53
+
54
+ try:
55
+ with DeployEngine(
56
+ api_key=os.environ["DEPLOYENGINE_API_KEY"],
57
+ base_url="https://deployengine.creat01.com",
58
+ ) as client:
59
+ projects = client.projects.list(page=1, pageSize=20)
60
+ machine = client.machines.get(12)
61
+ except PermissionDeniedError as exc:
62
+ print(f"missing API scope; request={exc.request_id}")
63
+ ```
64
+
65
+ ```python
66
+ from creat01deployengine import AsyncDeployEngine
67
+
68
+ async with AsyncDeployEngine(api_key=key) as client:
69
+ projects = await client.projects.list()
70
+ ```
71
+
72
+ ## Resource map
73
+
74
+ | Attribute | Purpose | Typical scope |
75
+ |---|---|---|
76
+ | `projects` | CRUD, precheck, deployments, releases, deploy/restart streams | `read`, `deploy` |
77
+ | `machines` | CRUD, recommendations, Agent state, port checks | `machines` |
78
+ | `workflows` | Task progress, detail, termination | `read`, `deploy` |
79
+ | `certificates` | CRUD, upload, manual/automatic Let's Encrypt renewal, deployment | `certificates` |
80
+ | `domains` | Domain CRUD and DNS records | `read` |
81
+ | `load_balancers` | Gateway config, sync, bindings, listeners | `infrastructure` |
82
+ | `alerts` | Alert contacts and notification sending | `monitoring` |
83
+ | `payments` | Payment orders and refunds | `business` |
84
+ | `authentication` | Project account/password registration, login, recovery and sessions; SMS/email code requests take an owner-scoped `credential_id` per call | public `projectId` / end-user bearer token |
85
+ | `feedback` | Customer feedback ticket links | `business` |
86
+ | `tracking` | Project event ingestion | `business` API Key scope |
87
+ | `users` | Admin-only user list/create/role/deletion | administrator role; JWT for writes |
88
+
89
+ ```python
90
+ with DeployEngine(access_token=admin_jwt) as admin:
91
+ page = admin.users.list(page=1, page_size=20, role="user", keyword="ops")
92
+ created = admin.users.create({"username": "operator", "password": "secret123"})
93
+ admin.users.change_role(created["id"], "admin")
94
+ admin.users.delete(created["id"])
95
+ ```
96
+
97
+ User-management writes require an administrator Bearer JWT; the list also
98
+ accepts an administrator API key. Authenticated non-admin users receive
99
+ `PermissionDeniedError`. Business-capability management is likewise admin-only,
100
+ while login, callback, and one-time feedback endpoints keep
101
+ their project credential, signature, or token authentication. Project tracking
102
+ uses the API Key and project name supplied to the tracking resource.
103
+
104
+ ```python
105
+ with DeployEngine(api_key=key) as client:
106
+ for event in client.projects.deploy_stream(7, {"branch": "main"}):
107
+ print(event)
108
+ ```
109
+
110
+ Resources return the unwrapped `data` field. Writes are not retried unless an
111
+ idempotency key is present. `DeployEngineError` exposes `status_code`, `code`,
112
+ `request_id`, `details`, and `retryable`. See `AI_USAGE.md` for task recipes.
113
+
114
+ Machine metrics start automatically after machine creation and Agent
115
+ connection, at a system-owned one-minute interval. This SDK does not currently
116
+ expose the `/api/monitor/machines` HTTP resource; `alerts` manages alert
117
+ contacts only. Existing direct HTTP integrations should move threshold/contact
118
+ updates to `PUT /api/monitor/machines/{machine_id}/alert-config`; legacy monitor
119
+ add, remove, and interval endpoints remain compatibility-only.
120
+
121
+ Maintainers can run the opt-in live smoke test with
122
+ `DEPLOYENGINE_E2E_API_KEY=... pytest tests/test_live_api.py`. It performs only
123
+ authenticated list operations and does not deploy or mutate resources.
124
+
125
+ 证书续期:`client.certificates.renew(cert_id)` 会触发已有部署机器的证书更新及 Nginx 重载;任一机器失败时返回错误,需检查对应部署记录。
126
+
127
+ ## Load balancer sync
128
+
129
+ `client.load_balancers.sync(id)` synchronizes bound project gateway configuration. HTTP 200 is not proof of application: check `sync_status`, `last_sync_error`, `config_revision`, and `applied_revision` in the returned data. Independent listener records (even disabled ones) are metadata only and make sync fail before remote operations. Configure domains and certificates on the project instead; remove independent listener metadata before retrying. Removing metadata does not remove project sites. New or changed configurations remain `pending` until sync succeeds for the current revision; old `ready` records should be resynced. Methods, paths and response envelopes remain compatible; this corrects false success reporting.
130
+
131
+ 机器证书部署查询:Python `client.certificates.machine_deployments(machine_id)`,TypeScript `client.api.certificates.machineDeployments(machineId)` 调用 `GET /api/certificates/machines/{machine_id}/deployments`,返回 `{ list: [...] }`。仅返回当前用户所拥有机器的部署元数据与证书名称/域名,不包含 PEM 或私钥内容;不可见或不存在的机器返回 HTTP 404。该能力为兼容性新增。
132
+
133
+
134
+ ### 项目 SSL 证书
135
+
136
+ 项目域名发布默认要求 HTTPS,必须先确认每个域名的证书绑定并部署到入口机器;无证书时不会静默降级。需要 HTTP 时显式保存 `mode: "http"`。旧客户端请求字段保持兼容,但未准备证书的域名发布现在返回就绪错误;运行中的服务不会因升级自动改配置。证书申请继续使用独立证书工作流。
137
+
138
+ Python:`client.api.projects.ssl(id, check_remote=True)`、`save_ssl(id, {"mode": "https", "bindings": {"app.example.com": certificate_id}})`、`deploy_ssl(id, "app.example.com")`、`preview_ssl(id)`、`apply_ssl(id, preview["revision"])`。TypeScript 对应 `ssl(id, true)`、`saveSsl`、`deploySsl`、`previewSsl`、`applySsl`。查询可传 `host` 准备待新增域名。类型为 `ProjectSslPolicy`、`ProjectSslStatus`、`ProjectSslPreview`。保存绑定只修改期望配置,应用前必须审阅预览的站点替换内容;409 表示未就绪、操作冲突或需要重新预览。返回元数据不含证书/私钥正文。应用只核对入口本机 TLS;公网 DNS、CDN、防火墙需单独验证。
139
+
140
+ 工作流 `GET /api/workflow-tasks/{task_id}/progress` 的 `logPreview` 为最多 12,000 字符的日志尾部;完整保留日志使用 `/detail` 的 `logContent`。接口路径、字段与认证保持兼容。 零停机清理恢复及按次诊断语义见 [SDK 说明](../../docs/sdk.md)。
141
+
142
+ ### 系统自动识别与容器盘点
143
+
144
+ 机器创建/修改连接信息自动保存系统版本和架构;读取 `platform` 与 `platformProbeAt`,无需手动填写系统。Python 使用 `client.machines.container_inventory(machine_id=7)`,TypeScript 使用 `client.api.machines.containerInventory(7)`;省略机器 ID 查询本人全部机器。`machines[]` 包含采集时间、ready/unavailable、errorCode 与容器列表,局部失败必须单独处理。容器的 `readOnly` 与 `projectBindings` 指示项目生命周期归属;项目容器只读,通用写操作(包括强制删除)返回 409,须通过项目流程管理。大规模盘点最长 90 秒,请将客户端 timeout 配置为 120 秒。容器操作使用机器 ID 与完整容器 ID;409 表示操作未完成,先刷新确认再重试。详见[SDK 说明](../../docs/sdk.md)。
145
+
146
+ ### 部署失败诊断与日志兼容性
147
+
148
+ 部署失败事件的 `content` 可包含容器状态与启动日志;失败或清理后可用通用 request 查询原项目日志接口。现有方法、字段和认证保持兼容;详见[SDK 说明](../../docs/sdk.md)。
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "creat01deployengine"
7
- version = "1.0.0"
7
+ version = "1.0.1"
8
8
  description = "Official Python SDK for Creat01 DeployEngine"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
@@ -0,0 +1,5 @@
1
+ """Public structured logging integration for project tracking."""
2
+
3
+ from .reporter import LogReporter
4
+
5
+ __all__ = ["LogReporter"]
@@ -0,0 +1,27 @@
1
+ """Public type models importable from ``creat01deployengine.models``."""
2
+
3
+ from .project_ssl import ProjectSslPolicy, ProjectSslStatus, ProjectSslPreview
4
+ from .common import Page
5
+ from .infrastructure import NginxConfigInfo, NginxConfigContent, NginxProjectBinding, LoadBalancer, MachineCertificateDeployment, ContainerInventory, InventoryContainer, InventoryMachine, ProjectContainerBinding
6
+ from .projects import CreateProjectRequest, Project
7
+ from .users import CreateUserRequest, ManagedUser, UserPage, UserRole
8
+
9
+ __all__ = [
10
+ "NginxConfigInfo", "NginxConfigContent", "NginxProjectBinding",
11
+ "CreateProjectRequest",
12
+ "LoadBalancer",
13
+ "ContainerInventory",
14
+ "ProjectContainerBinding",
15
+ "InventoryContainer",
16
+ "InventoryMachine",
17
+ "MachineCertificateDeployment",
18
+ "Page",
19
+ "Project",
20
+ "ProjectSslPolicy",
21
+ "ProjectSslStatus",
22
+ "ProjectSslPreview",
23
+ "CreateUserRequest",
24
+ "ManagedUser",
25
+ "UserPage",
26
+ "UserRole",
27
+ ]
@@ -6,7 +6,7 @@ from typing import Generic, TypeVar
6
6
  T = TypeVar("T")
7
7
 
8
8
 
9
- @dataclass(frozen=True, slots=True)
9
+ @dataclass(frozen=True)
10
10
  class Page(Generic[T]):
11
11
  """A page of ``items`` with one-based page metadata and a total count."""
12
12
 
@@ -0,0 +1,86 @@
1
+ """Typed mappings for infrastructure resources."""
2
+
3
+ from typing import Optional, TypedDict
4
+
5
+
6
+ class LoadBalancer(TypedDict, total=False):
7
+ """DeployEngine-managed load balancer summary."""
8
+ id: int
9
+ name: str
10
+ enabled: bool
11
+ gatewayMachineId: int
12
+ sync_status: str
13
+ config_revision: int
14
+ applied_revision: int
15
+ last_sync_error: Optional[str]
16
+
17
+
18
+ class MachineCertificateDeployment(TypedDict, total=False):
19
+ """Public certificate deployment metadata; excludes certificate and key contents."""
20
+ id: int
21
+ certificate_id: int
22
+ machine_id: int
23
+ cert_path: str
24
+ key_path: Optional[str]
25
+ deployed: int
26
+ certificate_name: Optional[str]
27
+ certificate_domain_name: Optional[str]
28
+ created_at: Optional[str]
29
+ updated_at: Optional[str]
30
+
31
+
32
+ class ProjectContainerBinding(TypedDict):
33
+ """Project that owns the lifecycle of a container on this machine."""
34
+ projectId: int
35
+ projectName: str
36
+
37
+
38
+ class InventoryContainer(TypedDict):
39
+ """A current Docker container, identified by full ID within its machine."""
40
+ readOnly: bool
41
+ projectBindings: list[ProjectContainerBinding]
42
+ id: str
43
+ name: str
44
+ image: str
45
+ state: str
46
+ status: str
47
+ ports: str
48
+ createdAt: str
49
+
50
+
51
+ class InventoryMachine(TypedDict):
52
+ """Collection status; unavailable is never an empty successful inventory."""
53
+ machineId: int
54
+ machineName: str
55
+ status: str
56
+ errorCode: Optional[str]
57
+ checkedAt: str
58
+ containers: list[InventoryContainer]
59
+
60
+
61
+ class ContainerInventory(TypedDict):
62
+ """Per-machine results of a live collection across owned machines."""
63
+ machines: list[InventoryMachine]
64
+
65
+
66
+ class NginxProjectBinding(TypedDict):
67
+ """Owner of a project configuration on this machine."""
68
+ projectId: int
69
+ projectName: str
70
+
71
+
72
+ class NginxConfigInfo(TypedDict):
73
+ """Machine Nginx site metadata; only readOnly=False permits mutations."""
74
+ filePath: str
75
+ name: str
76
+ enabled: int
77
+ readOnly: bool
78
+ projectBindings: list[NginxProjectBinding]
79
+
80
+
81
+ class NginxConfigContent(TypedDict):
82
+ """Configuration content and its current server-side ownership policy."""
83
+ filePath: str
84
+ content: str
85
+ readOnly: bool
86
+ projectBindings: list[NginxProjectBinding]
@@ -0,0 +1,61 @@
1
+ """Project certificate contracts; certificate and private-key PEM never appear here."""
2
+ from typing import Literal, Optional, TypedDict
3
+
4
+
5
+ class ProjectSslPolicy(TypedDict):
6
+ """Explicit access protocol and confirmed per-host certificate IDs."""
7
+ mode: Literal['https', 'http']
8
+ bindings: dict[str, int]
9
+
10
+
11
+ class ProjectSslCandidate(TypedDict):
12
+ """Public certificate metadata and actual PEM usability."""
13
+ id: int
14
+ name: str
15
+ usable: bool
16
+ reason: Optional[str]
17
+ expireAt: Optional[str]
18
+
19
+
20
+ class ProjectSslDeployment(TypedDict):
21
+ """Ingress file paths and recorded deployment state."""
22
+ id: int
23
+ cert_path: str
24
+ key_path: Optional[str]
25
+ deployed: int
26
+
27
+
28
+ class ProjectSslDomain(TypedDict):
29
+ """Separate certificate-library, machine and site facts for a host."""
30
+ host: str
31
+ certificateId: Optional[int]
32
+ recommendedId: Optional[int]
33
+ candidates: list[ProjectSslCandidate]
34
+ deployment: Optional[ProjectSslDeployment]
35
+ ready: bool
36
+ error: Optional[str]
37
+ siteUsesCertificate: Optional[bool]
38
+ siteError: Optional[str]
39
+
40
+
41
+ class ProjectSslStatus(ProjectSslPolicy):
42
+ """Owned project TLS readiness without certificate or key contents."""
43
+ machineId: Optional[int]
44
+ running: bool
45
+ domains: list[ProjectSslDomain]
46
+ checkedAt: Optional[str]
47
+
48
+
49
+ class ProjectSslSiteChange(TypedDict):
50
+ """Current and generated site text requiring explicit review."""
51
+ host: str
52
+ name: str
53
+ before: str
54
+ after: str
55
+
56
+
57
+ class ProjectSslPreview(TypedDict):
58
+ """Reviewed site changes and their optimistic concurrency revision."""
59
+ revision: str
60
+ machineId: int
61
+ changes: list[ProjectSslSiteChange]
@@ -1,6 +1,6 @@
1
1
  """Typed mappings for common project responses and create requests."""
2
2
 
3
- from typing import NotRequired, TypedDict
3
+ from typing import TypedDict
4
4
 
5
5
 
6
6
  class Project(TypedDict, total=False):
@@ -11,7 +11,10 @@ class Project(TypedDict, total=False):
11
11
  createdAt: str
12
12
 
13
13
 
14
- class CreateProjectRequest(TypedDict):
15
- """Minimum supported request for creating a project."""
14
+ class _CreateProjectRequired(TypedDict):
16
15
  name: str
17
- machineId: NotRequired[int]
16
+
17
+
18
+ class CreateProjectRequest(_CreateProjectRequired, total=False):
19
+ """Minimum supported request for creating a project."""
20
+ machineId: int
@@ -0,0 +1,38 @@
1
+ """Typed request and response mappings for administrator user management."""
2
+
3
+ from typing import Literal, Optional, TypedDict
4
+
5
+ UserRole = Literal["admin", "user"]
6
+
7
+
8
+ class ManagedUser(TypedDict, total=False):
9
+ """Non-sensitive user fields returned by administrator APIs."""
10
+
11
+ id: int
12
+ username: str
13
+ email: Optional[str]
14
+ role: UserRole
15
+ created_at: Optional[str]
16
+ updated_at: Optional[str]
17
+ last_login_at: Optional[str]
18
+
19
+
20
+ class _CreateUserRequired(TypedDict):
21
+ username: str
22
+ password: str
23
+
24
+
25
+ class CreateUserRequest(_CreateUserRequired, total=False):
26
+ """Body accepted when an administrator creates a platform user."""
27
+
28
+ email: Optional[str]
29
+ role: UserRole
30
+
31
+
32
+ class UserPage(TypedDict):
33
+ """Paginated administrator user-list response."""
34
+
35
+ items: list[ManagedUser]
36
+ total: int
37
+ page: int
38
+ pageSize: int