ship-il-sdk 0.1.0__tar.gz

ship_il_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yair Rosenfeld
+
+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.

ship_il_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: ship-il-sdk
+Version: 0.1.0
+Summary: Production-grade Python SDK for SHIP Israel API
+Author: Yair Rosenfeld
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yair-ros/ship-il-sdk
+Project-URL: Repository, https://github.com/yair-ros/ship-il-sdk
+Keywords: ship,sdk,logistics,shipping,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Requires-Dist: tenacity
+Requires-Dist: structlog
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# ship-il-sdk
+
+[![PyPI version](https://img.shields.io/pypi/v/ship-il-sdk.svg)](https://pypi.org/project/ship-il-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ship-il-sdk.svg)](https://pypi.org/project/ship-il-sdk/)
+[![License](https://img.shields.io/pypi/l/ship-il-sdk.svg)](LICENSE)
+[![CI](https://github.com/yair-ros/ship-il-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/yair-ros/ship-il-sdk/actions/workflows/ci.yml)
+
+Independent/community Python SDK for the SHIP Israel API.
+
+This is not an official SHIP SDK. It is an independent/community project.
+
+PyPI: <https://pypi.org/project/ship-il-sdk/>
+
+## Documentation
+
+- [Usage guide](docs/usage.md): how to use this Python SDK.
+- [SDK API reference](docs/api.md): Python classes, methods, return values, and exceptions.
+- [OpenAPI contract](docs/openapi.yaml): raw SHIP HTTP API contract for the endpoints currently wrapped by this SDK.
+- [Contributing guide](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+- [Security policy](SECURITY.md)
+
+The OpenAPI file documents the vendor HTTP endpoints, not the Python SDK itself.
+It is included as a reference for API tooling, contract review, mock servers, or
+future code generation. The SDK does not load it at runtime.
+
+## Installation
+
+From PyPI:
+
+```bash
+python -m pip install ship-il-sdk
+```
+
+From this repository:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install .
+```
+
+If you only want to run from a checkout without installing:
+
+```bash
+PYTHONPATH=src python -m pytest -q
+```
+
+## Development
+
+Install the SDK and dev tooling inside a virtual environment:
+
+```bash
+make install
+```
+
+Available commands:
+
+```bash
+make format
+make lint
+make typecheck
+make test
+make check
+make integration-test
+make package
+make release
+```
+
+`make package` builds the source distribution and wheel into `dist/`.
+`make release` increments the latest `vX.Y.Z` tag by one patch version, updates
+`pyproject.toml`, runs verification, commits the version bump, creates an
+annotated tag, pushes the branch, and pushes the tag.
+`make check` runs lint, typecheck, and tests.
+`make integration-test` runs the real API integration script.
+
+## CI/CD
+
+GitHub Actions workflows live in `.github/workflows/`.
+
+- `ci.yml` runs on pull requests to `main` and manual dispatch. It installs the
+  package with dev tooling, then runs lint, typecheck, and tests across Python
+  3.9 through 3.13, and builds the package once on Python 3.13.
+- `release.yml` runs only on tags matching `v*`. It runs the same checks,
+  builds `dist/`, uploads the distribution files as a workflow artifact,
+  creates a GitHub Release, and publishes to PyPI through Trusted Publishing.
+- PyPI publishing does not use a stored API token. Configure a pending trusted
+  publisher in PyPI with these values:
+  - PyPI project name: `ship-il-sdk`
+  - Owner: `yair-ros`
+  - Repository name: `ship-il-sdk`
+  - Workflow name: `release.yml`
+  - Environment name: `pypi`
+
+To create a GitHub Release and trigger PyPI publishing:
+
+```bash
+make release
+```
+
+If your virtual environment is not activated, pass the interpreter explicitly:
+
+```bash
+make release PYTHON=.venv/bin/python
+```
+
+## Usage
+
+```python
+from ship_il_sdk import (
+    Environment,
+    ShipClient,
+    build_consignee_address,
+    build_pickup_shipment_request_from_point,
+    build_shipment_preparation,
+)
+
+client = ShipClient(
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    customer_id="YOUR_CUSTOMER_ID",
+    environment=Environment.DEV,
+)
+
+points = client.points.get_closest_points(
+    city="Tel Aviv",
+    street="Herzl",
+    house_number="10",
+)
+
+consignee = build_consignee_address(
+    city_name="Tel Aviv",
+    street_name="Herzl",
+    house_number="10",
+    contact_person="Dana Cohen",
+    customer_name="Dana Cohen",
+    phone1="0501234567",
+)
+
+preparation = build_shipment_preparation(
+    consignee_address=consignee,
+    number_of_packages=1,
+    reference1="ORDER-123",
+)
+
+shipment = build_pickup_shipment_request_from_point(
+    preparation=preparation,
+    pickup_point=points.Points[0],
+)
+
+response = client.shipments.insert_pickup_shipment(shipment)
+print(response.Result.TrackingNumber)
+```
+
+## Supported Workflow
+
+The SDK supports a generic flow that does not depend on any specific commerce
+platform:
+
+1. authenticate
+2. find closest pickup points
+3. build a shipment draft
+4. manually or heuristically choose a pickup point
+5. create the shipment
+6. download the label
+
+For conservative automatic recommendation, use `recommend_pickup_point(...)`.
+If it returns `None`, require manual pickup selection.
+
+## Error Handling
+
+```python
+from ship_il_sdk import Environment, ShipClient
+from ship_il_sdk.exceptions import AuthenticationError, ShipAPIError
+
+client = ShipClient(
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    customer_id="YOUR_CUSTOMER_ID",
+    environment=Environment.DEV,
+)
+
+try:
+    client.login()
+except AuthenticationError as exc:
+    print(f"Authentication failed: {exc}")
+
+try:
+    points = client.points.get_closest_points(
+        city="Tel Aviv",
+        street="Herzl",
+        house_number="10",
+    )
+except ShipAPIError as exc:
+    print(f"API error: {exc}")
+```

ship_il_sdk-0.1.0/README.md

@@ -0,0 +1,196 @@
+# ship-il-sdk
+
+[![PyPI version](https://img.shields.io/pypi/v/ship-il-sdk.svg)](https://pypi.org/project/ship-il-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ship-il-sdk.svg)](https://pypi.org/project/ship-il-sdk/)
+[![License](https://img.shields.io/pypi/l/ship-il-sdk.svg)](LICENSE)
+[![CI](https://github.com/yair-ros/ship-il-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/yair-ros/ship-il-sdk/actions/workflows/ci.yml)
+
+Independent/community Python SDK for the SHIP Israel API.
+
+This is not an official SHIP SDK. It is an independent/community project.
+
+PyPI: <https://pypi.org/project/ship-il-sdk/>
+
+## Documentation
+
+- [Usage guide](docs/usage.md): how to use this Python SDK.
+- [SDK API reference](docs/api.md): Python classes, methods, return values, and exceptions.
+- [OpenAPI contract](docs/openapi.yaml): raw SHIP HTTP API contract for the endpoints currently wrapped by this SDK.
+- [Contributing guide](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+- [Security policy](SECURITY.md)
+
+The OpenAPI file documents the vendor HTTP endpoints, not the Python SDK itself.
+It is included as a reference for API tooling, contract review, mock servers, or
+future code generation. The SDK does not load it at runtime.
+
+## Installation
+
+From PyPI:
+
+```bash
+python -m pip install ship-il-sdk
+```
+
+From this repository:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install .
+```
+
+If you only want to run from a checkout without installing:
+
+```bash
+PYTHONPATH=src python -m pytest -q
+```
+
+## Development
+
+Install the SDK and dev tooling inside a virtual environment:
+
+```bash
+make install
+```
+
+Available commands:
+
+```bash
+make format
+make lint
+make typecheck
+make test
+make check
+make integration-test
+make package
+make release
+```
+
+`make package` builds the source distribution and wheel into `dist/`.
+`make release` increments the latest `vX.Y.Z` tag by one patch version, updates
+`pyproject.toml`, runs verification, commits the version bump, creates an
+annotated tag, pushes the branch, and pushes the tag.
+`make check` runs lint, typecheck, and tests.
+`make integration-test` runs the real API integration script.
+
+## CI/CD
+
+GitHub Actions workflows live in `.github/workflows/`.
+
+- `ci.yml` runs on pull requests to `main` and manual dispatch. It installs the
+  package with dev tooling, then runs lint, typecheck, and tests across Python
+  3.9 through 3.13, and builds the package once on Python 3.13.
+- `release.yml` runs only on tags matching `v*`. It runs the same checks,
+  builds `dist/`, uploads the distribution files as a workflow artifact,
+  creates a GitHub Release, and publishes to PyPI through Trusted Publishing.
+- PyPI publishing does not use a stored API token. Configure a pending trusted
+  publisher in PyPI with these values:
+  - PyPI project name: `ship-il-sdk`
+  - Owner: `yair-ros`
+  - Repository name: `ship-il-sdk`
+  - Workflow name: `release.yml`
+  - Environment name: `pypi`
+
+To create a GitHub Release and trigger PyPI publishing:
+
+```bash
+make release
+```
+
+If your virtual environment is not activated, pass the interpreter explicitly:
+
+```bash
+make release PYTHON=.venv/bin/python
+```
+
+## Usage
+
+```python
+from ship_il_sdk import (
+    Environment,
+    ShipClient,
+    build_consignee_address,
+    build_pickup_shipment_request_from_point,
+    build_shipment_preparation,
+)
+
+client = ShipClient(
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    customer_id="YOUR_CUSTOMER_ID",
+    environment=Environment.DEV,
+)
+
+points = client.points.get_closest_points(
+    city="Tel Aviv",
+    street="Herzl",
+    house_number="10",
+)
+
+consignee = build_consignee_address(
+    city_name="Tel Aviv",
+    street_name="Herzl",
+    house_number="10",
+    contact_person="Dana Cohen",
+    customer_name="Dana Cohen",
+    phone1="0501234567",
+)
+
+preparation = build_shipment_preparation(
+    consignee_address=consignee,
+    number_of_packages=1,
+    reference1="ORDER-123",
+)
+
+shipment = build_pickup_shipment_request_from_point(
+    preparation=preparation,
+    pickup_point=points.Points[0],
+)
+
+response = client.shipments.insert_pickup_shipment(shipment)
+print(response.Result.TrackingNumber)
+```
+
+## Supported Workflow
+
+The SDK supports a generic flow that does not depend on any specific commerce
+platform:
+
+1. authenticate
+2. find closest pickup points
+3. build a shipment draft
+4. manually or heuristically choose a pickup point
+5. create the shipment
+6. download the label
+
+For conservative automatic recommendation, use `recommend_pickup_point(...)`.
+If it returns `None`, require manual pickup selection.
+
+## Error Handling
+
+```python
+from ship_il_sdk import Environment, ShipClient
+from ship_il_sdk.exceptions import AuthenticationError, ShipAPIError
+
+client = ShipClient(
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    customer_id="YOUR_CUSTOMER_ID",
+    environment=Environment.DEV,
+)
+
+try:
+    client.login()
+except AuthenticationError as exc:
+    print(f"Authentication failed: {exc}")
+
+try:
+    points = client.points.get_closest_points(
+        city="Tel Aviv",
+        street="Herzl",
+        house_number="10",
+    )
+except ShipAPIError as exc:
+    print(f"API error: {exc}")
+```

ship_il_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ship-il-sdk"
+version = "0.1.0"
+description = "Production-grade Python SDK for SHIP Israel API"
+readme = "README.md"
+authors = [{name = "Yair Rosenfeld"}]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+keywords = ["ship", "sdk", "logistics", "shipping", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "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",
+    "httpx",
+    "pydantic",
+    "tenacity",
+    "structlog",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest",
+    "types-requests",
+    "build",
+]
+
+[project.urls]
+Homepage = "https://github.com/yair-ros/ship-il-sdk"
+Repository = "https://github.com/yair-ros/ship-il-sdk"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ship_il_sdk", "ship_il_sdk.*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

ship_il_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ship_il_sdk-0.1.0/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+
+setup()

ship_il_sdk-0.1.0/src/ship_il_sdk/__init__.py

@@ -0,0 +1,21 @@
+from .async_client import AsyncShipClient
+from .client import ShipClient
+from .config import Environment
+from .shipment_preparation import (
+    build_consignee_address,
+    build_pickup_shipment_request,
+    build_pickup_shipment_request_from_point,
+    build_shipment_preparation,
+    recommend_pickup_point,
+)
+
+__all__ = [
+    "ShipClient",
+    "AsyncShipClient",
+    "Environment",
+    "build_consignee_address",
+    "build_pickup_shipment_request",
+    "build_pickup_shipment_request_from_point",
+    "build_shipment_preparation",
+    "recommend_pickup_point",
+]

ship_il_sdk-0.1.0/src/ship_il_sdk/async_client.py

@@ -0,0 +1,97 @@
+import httpx
+
+from .config import Environment
+from .endpoints.specs import GET_CLOSEST_POINTS
+from .exceptions import ShipAPIError
+from .logging import get_logger
+from .models.points import ClosestPointsResponse
+from .token_manager import TokenManager
+from .transport.parsing import parse_model
+
+
+class AsyncShipClient:
+    def __init__(
+        self,
+        username,
+        password,
+        customer_id,
+        environment=Environment.PROD,
+        timeout=30,
+    ):
+        self.username = username
+        self.password = password
+        self.customer_id = customer_id
+        self.base_url = environment.value
+        self.timeout = timeout
+
+        self.client = httpx.AsyncClient(timeout=timeout)
+        self.token = None
+        self.tokens = TokenManager()
+        self.logger = get_logger().bind(
+            client="async",
+            environment=environment.name,
+            base_url=self.base_url,
+        )
+
+    async def login(self):
+        r = await self.client.post(
+            f"{self.base_url}/Token",
+            data={
+                "username": self.username,
+                "password": self.password,
+                "scope": str(self.customer_id),
+                "grant_type": "password",
+            },
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        if r.status_code != 200:
+            raise ShipAPIError(r.text)
+
+        data = r.json()
+        self.token = data.get("access_token")
+        if not self.token:
+            raise ShipAPIError("Token missing")
+
+        self.tokens.set_token(self.token, ttl=int(data.get("expires_in", 3600)))
+        self.client.headers["Authorization"] = f"Bearer {self.token}"
+        self.logger.info(
+            "token_refreshed", expires_in=int(data.get("expires_in", 3600))
+        )
+
+    async def _ensure_token(self):
+        if self.tokens.is_expired():
+            await self.login()
+
+    async def get_closest_points(
+        self,
+        city,
+        street,
+        house_number,
+        point_types="1,2,4",
+        points=10,
+    ) -> ClosestPointsResponse:
+        await self._ensure_token()
+
+        r = await self.client.get(
+            f"{self.base_url}{GET_CLOSEST_POINTS.path}",
+            params={
+                "city": city,
+                "street": street,
+                "houseNumber": house_number,
+                "pointTypes": point_types,
+                "points": points,
+            },
+        )
+
+        if r.status_code >= 400:
+            raise ShipAPIError(r.text)
+
+        self.logger.info(
+            "api_call",
+            method=GET_CLOSEST_POINTS.method,
+            endpoint=GET_CLOSEST_POINTS.path,
+            status=r.status_code,
+        )
+
+        return parse_model(GET_CLOSEST_POINTS.response_model, r.json())

ship_il_sdk-0.1.0/src/ship_il_sdk/auth.py

@@ -0,0 +1,26 @@
+from .exceptions import AuthenticationError
+
+
+def authenticate(session, base_url, username, password, customer_id):
+    r = session.post(
+        f"{base_url}/Token",
+        data={
+            "username": username,
+            "password": password,
+            "scope": str(customer_id),
+            "grant_type": "password",
+        },
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+
+    if r.status_code != 200:
+        raise AuthenticationError(r.text)
+
+    data = r.json()
+    token = data.get("access_token")
+
+    if not token:
+        raise AuthenticationError("Token missing")
+
+    session.headers["Authorization"] = f"Bearer {token}"
+    return token, int(data.get("expires_in", 3600))