edgecron-python 1.0.0__tar.gz

edgecron_python-1.0.0/.github/workflows/publish-python-pypi.yml

@@ -0,0 +1,34 @@
+name: Publish Python Package
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    if: github.repository == 'edgecron/edgecron-python'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

edgecron_python-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+venv/
+dist/
+*.egg-info/
+build/

edgecron_python-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EdgeCron Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edgecron_python-1.0.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: edgecron-python
+Version: 1.0.0
+Summary: Official Python SDK for the EdgeCron webhook scheduling and callback delivery platform.
+Project-URL: Homepage, https://github.com/edgecron/edgecron-python
+Project-URL: Repository, https://github.com/edgecron/edgecron-python
+Project-URL: Documentation, https://www.edgecron.com
+Author: EdgeCron Team
+License: MIT
+License-File: LICENSE
+Keywords: callback,delivery,edgecron,scheduling,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests<3,>=2.31.0
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# EdgeCron Python SDK
+
+Official Python SDK for the EdgeCron webhook scheduling and callback delivery platform.
+
+Schedule delayed HTTP requests, deliver webhooks reliably, and automatically retry failed calls — with full execution history so nothing gets lost.
+
+中文文档：[README.zh-CN.md](README.zh-CN.md)
+
+## Install
+
+```bash
+pip install edgecron-python
+```
+
+## Quick Start
+
+```python
+from edgecron import EdgeCron, APIError
+from edgecron.types import CreateScheduleRequest
+
+client = EdgeCron("ak_xxx", "sk_xxx")
+
+try:
+    schedule = client.schedules.create(
+        CreateScheduleRequest(
+            name="my-schedule",
+            cron_expr="*/5 * * * *",
+        )
+    )
+    print(schedule.id)
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## Modules
+
+| Client method              | Description                      |
+|----------------------------|----------------------------------|
+| `client.schedules.*`       | Cron schedule CRUD, pause, resume |
+| `client.tasks.*`           | Task execution instances, cancel  |
+| `client.events.*`          | Event publishing and management   |
+| `client.endpoints.*`       | Webhook endpoint configuration    |
+| `client.deliveries.*`      | Delivery attempt records and retry |
+| `client.retries.*`         | Retry policies and jobs           |
+| `client.subscription.*`    | Quota, usage, and resource limits |
+
+## Configuration
+
+- `base_url` — override API base URL
+- `timeout` — HTTP client timeout in seconds
+- `session` — custom `requests.Session`
+
+## Error Handling
+
+Service-side business errors raise `APIError`.
+
+```python
+from edgecron import APIError
+
+try:
+    client.schedules.get(123)
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## Security Notice
+
+This is a server-side SDK. Never expose `secret` in browsers, mobile apps, or other untrusted clients.

edgecron_python-1.0.0/README.md

@@ -0,0 +1,68 @@
+# EdgeCron Python SDK
+
+Official Python SDK for the EdgeCron webhook scheduling and callback delivery platform.
+
+Schedule delayed HTTP requests, deliver webhooks reliably, and automatically retry failed calls — with full execution history so nothing gets lost.
+
+中文文档：[README.zh-CN.md](README.zh-CN.md)
+
+## Install
+
+```bash
+pip install edgecron-python
+```
+
+## Quick Start
+
+```python
+from edgecron import EdgeCron, APIError
+from edgecron.types import CreateScheduleRequest
+
+client = EdgeCron("ak_xxx", "sk_xxx")
+
+try:
+    schedule = client.schedules.create(
+        CreateScheduleRequest(
+            name="my-schedule",
+            cron_expr="*/5 * * * *",
+        )
+    )
+    print(schedule.id)
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## Modules
+
+| Client method              | Description                      |
+|----------------------------|----------------------------------|
+| `client.schedules.*`       | Cron schedule CRUD, pause, resume |
+| `client.tasks.*`           | Task execution instances, cancel  |
+| `client.events.*`          | Event publishing and management   |
+| `client.endpoints.*`       | Webhook endpoint configuration    |
+| `client.deliveries.*`      | Delivery attempt records and retry |
+| `client.retries.*`         | Retry policies and jobs           |
+| `client.subscription.*`    | Quota, usage, and resource limits |
+
+## Configuration
+
+- `base_url` — override API base URL
+- `timeout` — HTTP client timeout in seconds
+- `session` — custom `requests.Session`
+
+## Error Handling
+
+Service-side business errors raise `APIError`.
+
+```python
+from edgecron import APIError
+
+try:
+    client.schedules.get(123)
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## Security Notice
+
+This is a server-side SDK. Never expose `secret` in browsers, mobile apps, or other untrusted clients.

edgecron_python-1.0.0/README.zh-CN.md

@@ -0,0 +1,68 @@
+# EdgeCron Python SDK
+
+EdgeCron Python SDK 是 EdgeCron Webhook 调度与回调投递平台的官方 Python 客户端。
+
+调度延迟 HTTP 请求，可靠投递 Webhook，自动重试失败调用 — 完整执行历史，确保不遗漏。
+
+English README: [README.md](README.md)
+
+## 安装
+
+```bash
+pip install edgecron-python
+```
+
+## 快速开始
+
+```python
+from edgecron import EdgeCron, APIError
+from edgecron.types import CreateScheduleRequest
+
+client = EdgeCron("ak_xxx", "sk_xxx")
+
+try:
+    schedule = client.schedules.create(
+        CreateScheduleRequest(
+            name="my-schedule",
+            cron_expr="*/5 * * * *",
+        )
+    )
+    print(schedule.id)
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## 模块说明
+
+| 客户端方法                  | 说明                         |
+|----------------------------|-----------------------------|
+| `client.schedules.*`       | Cron 调度器 CRUD、暂停、恢复   |
+| `client.tasks.*`           | 任务执行实例、取消             |
+| `client.events.*`          | 事件发布与管理                |
+| `client.endpoints.*`       | Webhook 端点配置              |
+| `client.deliveries.*`      | 投递记录与手动重试             |
+| `client.retries.*`         | 重试策略与任务                |
+| `client.subscription.*`    | 配额、用量与资源限制           |
+
+## 配置项
+
+- `base_url`：自定义 API 地址
+- `timeout`：超时时间，单位秒
+- `session`：自定义 `requests.Session`
+
+## 错误处理
+
+服务端业务错误会抛出 `APIError`。
+
+```python
+from edgecron import APIError
+
+try:
+    client.schedules.get(123)
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## 安全说明
+
+这是服务端 SDK，不要在浏览器、小程序、移动端或其他不可信客户端暴露 `secret`。

edgecron_python-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "edgecron-python"
+version = "1.0.0"
+description = "Official Python SDK for the EdgeCron webhook scheduling and callback delivery platform."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "EdgeCron Team" }
+]
+keywords = ["edgecron", "webhook", "scheduling", "callback", "delivery"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "requests>=2.31.0,<3"
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8,<9"
+]
+
+[project.urls]
+Homepage = "https://github.com/edgecron/edgecron-python"
+Repository = "https://github.com/edgecron/edgecron-python"
+Documentation = "https://www.edgecron.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/edgecron"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

edgecron_python-1.0.0/samples/cron_schedule.py

@@ -0,0 +1,43 @@
+"""Cron schedule CRUD - create, list, update, pause, resume, and delete a schedule."""
+import os
+from edgecron import EdgeCron
+from edgecron.types import CreateScheduleRequest, UpdateScheduleRequest
+
+key_id = os.environ["EDGECRON_KEY_ID"]
+secret = os.environ["EDGECRON_SECRET"]
+client = EdgeCron(key_id, secret, base_url="http://localhost:8888")
+
+# 1. Create a cron schedule
+schedule = client.schedules.create(CreateScheduleRequest(
+    name="daily-report",
+    cron_expr="0 8 * * *",
+    timezone="Asia/Shanghai",
+    payload='{"report": "daily"}',
+))
+print(f"Schedule created: {schedule.id} ({schedule.name})")
+
+# 2. List all schedules
+schedules = client.schedules.list(page=1, page_size=20)
+print(f"Total schedules: {schedules.total}")
+
+# 3. Get the schedule by ID
+got = client.schedules.get(schedule.id)
+print(f"Got schedule: {got.name} status={got.status}")
+
+# 4. Update the schedule name
+updated = client.schedules.update(schedule.id, UpdateScheduleRequest(
+    name="daily-report-updated",
+))
+print(f"Updated schedule: {updated.name}")
+
+# 5. Pause the schedule
+client.schedules.pause(schedule.id)
+print("Schedule paused")
+
+# 6. Resume the schedule
+client.schedules.resume(schedule.id)
+print("Schedule resumed")
+
+# 7. Delete the schedule
+client.schedules.delete(schedule.id)
+print("Schedule deleted")

edgecron_python-1.0.0/samples/schedule_task.py

@@ -0,0 +1,22 @@
+"""Schedule a delayed task - EdgeCron's primary use case."""
+import os
+from edgecron import EdgeCron, APIError
+from edgecron.types import CreateEndpointRequest, CreateTaskRequest
+
+key_id = os.environ["EDGECRON_KEY_ID"]
+secret = os.environ["EDGECRON_SECRET"]
+client = EdgeCron(key_id, secret, base_url="http://localhost:8888")
+
+# 1. Create a webhook endpoint
+endpoint = client.endpoints.create(CreateEndpointRequest(
+    name="my-webhook",
+    url="https://httpbin.org/post",
+))
+print(f"Endpoint created: {endpoint.id}")
+
+# 2. Schedule a task
+task = client.tasks.create(CreateTaskRequest(
+    endpoint_id=endpoint.id,
+    payload='{"order_id": "ord_9102"}',
+))
+print(f"Task created: {task.id}")

edgecron_python-1.0.0/samples/webhook_recovery.py

@@ -0,0 +1,52 @@
+"""Webhook delivery recovery - retry policy, endpoint with retry, and manual retry."""
+import os
+from edgecron import EdgeCron
+from edgecron.types import (
+    CreateEndpointRequest,
+    CreateRetryPolicyRequest,
+    CreateTaskRequest,
+)
+
+key_id = os.environ["EDGECRON_KEY_ID"]
+secret = os.environ["EDGECRON_SECRET"]
+client = EdgeCron(key_id, secret, base_url="http://localhost:8888")
+
+# 1. Create a retry policy
+policy = client.retries.create_policy(CreateRetryPolicyRequest(
+    name="my-retry-policy",
+    max_attempts=5,
+    backoff_type="exponential",
+    initial_delay_sec=10,
+    max_delay_sec=3600,
+))
+print(f"Retry policy created: {policy.id}")
+
+# 2. Create an endpoint that uses the retry policy
+endpoint = client.endpoints.create(CreateEndpointRequest(
+    name="retry-endpoint",
+    url="https://httpbin.org/post",
+    retry_policy_id=policy.id,
+))
+print(f"Endpoint created: {endpoint.id} (retry_policy_id={endpoint.retry_policy_id})")
+
+# 3. Create a task (will trigger delivery to the endpoint)
+task = client.tasks.create(CreateTaskRequest(
+    endpoint_id=endpoint.id,
+    payload='{"order_id": "ord_1234"}',
+))
+print(f"Task created: {task.id}")
+
+# 4. List deliveries
+deliveries = client.deliveries.list(page=1, page_size=20)
+print(f"Total deliveries: {deliveries.total}")
+if deliveries.list:
+    for d in deliveries.list:
+        print(f"  Delivery {d.id}: task={d.task_id} status={d.status}")
+
+# 5. Find the first failed delivery and retry it
+failed = [d for d in deliveries.list if d.status == "failed"]
+if failed:
+    result = client.deliveries.retry(failed[0].id)
+    print(f"Retry initiated: delivery={result.delivery_id} job={result.retry_job_id} status={result.status}")
+else:
+    print("No failed deliveries found to retry")

edgecron_python-1.0.0/src/edgecron/__init__.py

@@ -0,0 +1,69 @@
+"""EdgeCron Python SDK."""
+
+from .client import EdgeCron
+from .error import APIError, is_api_error
+from .types import (
+    CreateEndpointRequest,
+    CreateRetryPolicyRequest,
+    CreateScheduleRequest,
+    CreateTaskRequest,
+    Delivery,
+    DeliveryList,
+    EndpointList,
+    Event,
+    EventList,
+    PublishEventRequest,
+    PublishEventResult,
+    ResourceLimits,
+    RetryDeliveryResult,
+    RetryJob,
+    RetryJobList,
+    RetryPolicy,
+    RetryPolicyList,
+    Schedule,
+    ScheduleList,
+    SubscriptionQuota,
+    Task,
+    TaskList,
+    UpdateEndpointRequest,
+    UpdateRetryPolicyRequest,
+    UpdateScheduleRequest,
+    UsageRecords,
+    WebhookEndpoint,
+)
+
+__version__ = "1.2.0"
+
+__all__ = [
+    "APIError",
+    "CreateEndpointRequest",
+    "CreateRetryPolicyRequest",
+    "CreateScheduleRequest",
+    "CreateTaskRequest",
+    "Delivery",
+    "DeliveryList",
+    "EdgeCron",
+    "EndpointList",
+    "Event",
+    "EventList",
+    "PublishEventRequest",
+    "PublishEventResult",
+    "ResourceLimits",
+    "RetryDeliveryResult",
+    "RetryJob",
+    "RetryJobList",
+    "RetryPolicy",
+    "RetryPolicyList",
+    "Schedule",
+    "ScheduleList",
+    "SubscriptionQuota",
+    "Task",
+    "TaskList",
+    "UpdateEndpointRequest",
+    "UpdateRetryPolicyRequest",
+    "UpdateScheduleRequest",
+    "UsageRecords",
+    "WebhookEndpoint",
+    "__version__",
+    "is_api_error",
+]

edgecron_python-1.0.0/src/edgecron/client.py

@@ -0,0 +1,57 @@
+"""Public client entrypoint for the EdgeCron SDK."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+import requests
+
+from .deliveries import DeliveriesService
+from .endpoints import EndpointsService
+from .events import EventsService
+from .retries import RetriesService
+from .schedules import SchedulesService
+from .subscription import SubscriptionService
+from .tasks import TasksService
+from .transport import DEFAULT_BASE_URL, SDK_VERSION, Transport
+
+_KEY_ID_RE = re.compile(r"^ak_[0-9a-zA-Z_]+$")
+
+
+class EdgeCron:
+    """EdgeCron API client.
+
+    The client is safe to reuse across requests. Create once and reuse.
+    """
+
+    version = SDK_VERSION
+
+    def __init__(
+        self,
+        key_id: str,
+        secret: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not _KEY_ID_RE.fullmatch(key_id):
+            raise ValueError(f"edgecron: key_id must match ak_<hex>, got: {key_id}")
+        if not secret:
+            raise ValueError("edgecron: secret must not be empty")
+
+        self._transport = Transport(
+            key_id=key_id,
+            secret=secret,
+            base_url=base_url,
+            timeout=timeout,
+            session=session,
+        )
+        self.schedules = SchedulesService(self._transport)
+        self.tasks = TasksService(self._transport)
+        self.events = EventsService(self._transport)
+        self.endpoints = EndpointsService(self._transport)
+        self.deliveries = DeliveriesService(self._transport)
+        self.retries = RetriesService(self._transport)
+        self.subscription = SubscriptionService(self._transport)

edgecron_python-1.0.0/src/edgecron/deliveries.py

@@ -0,0 +1,37 @@
+"""Delivery APIs."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .transport import Transport
+from .types import Delivery, DeliveryList, RetryDeliveryResult
+from .schedules import _page_query
+
+
+class DeliveriesService:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def list(
+        self,
+        page: int = 1,
+        page_size: int = 20,
+        status: str = "",
+        task_id: int = 0,
+        endpoint_id: int = 0,
+    ) -> DeliveryList:
+        q = _page_query(page, page_size)
+        if status:
+            q["status"] = status
+        if task_id > 0:
+            q["task_id"] = task_id
+        if endpoint_id > 0:
+            q["endpoint_id"] = endpoint_id
+        data = self._transport.request_json("GET", "/v1/deliveries", query=q)
+        items = [Delivery(**d) for d in (data.get("list") or [])]
+        return DeliveryList(total=data.get("total", 0), list=items)
+
+    def retry(self, id: int) -> RetryDeliveryResult:
+        data = self._transport.request_json("POST", f"/v1/deliveries/{id}/retry")
+        return RetryDeliveryResult(**data)

edgecron_python-1.0.0/src/edgecron/endpoints.py

@@ -0,0 +1,43 @@
+"""Webhook endpoint APIs."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .transport import Transport
+from .types import CreateEndpointRequest, EndpointList, UpdateEndpointRequest, WebhookEndpoint
+from .schedules import _compact, _page_query, _asdict
+
+
+class EndpointsService:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def create(self, req: CreateEndpointRequest) -> WebhookEndpoint:
+        data = self._transport.request_json("POST", "/v1/endpoints", body=_asdict(req))
+        return WebhookEndpoint(**data)
+
+    def get(self, id: int) -> WebhookEndpoint:
+        data = self._transport.request_json("GET", f"/v1/endpoints/{id}")
+        return WebhookEndpoint(**data)
+
+    def update(self, id: int, req: UpdateEndpointRequest) -> WebhookEndpoint:
+        data = self._transport.request_json("PATCH", f"/v1/endpoints/{id}", body=_compact(_asdict(req)))
+        return WebhookEndpoint(**data)
+
+    def list(self, page: int = 1, page_size: int = 20, status: str = "") -> EndpointList:
+        q = _page_query(page, page_size)
+        if status:
+            q["status"] = status
+        data = self._transport.request_json("GET", "/v1/endpoints", query=q)
+        items = [WebhookEndpoint(**ep) for ep in (data.get("list") or [])]
+        return EndpointList(total=data.get("total", 0), list=items)
+
+    def delete(self, id: int) -> None:
+        self._transport.request_json("DELETE", f"/v1/endpoints/{id}")
+
+    def enable(self, id: int) -> None:
+        self._transport.request_json("POST", f"/v1/endpoints/{id}/enable")
+
+    def disable(self, id: int) -> None:
+        self._transport.request_json("POST", f"/v1/endpoints/{id}/disable")