Metadata-Version: 2.4
Name: wiliot-hologram-api
Version: 0.1.0
Summary: Python client and CLI for the Hologram REST API (devices, SIMs, messaging, usage, billing).
Project-URL: Homepage, https://github.com/hologram-io/rest-api-docs
Project-URL: Documentation, https://dashboard.hologram.io/api/1
Author-email: Fernando Carrero <fernando.carrero@wiliot.com>
License: MIT License
        
        Copyright (c) 2026 Fernando Carrero
        
        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.
License-File: LICENSE
Keywords: cellular,cli,databricks,hologram,iot,rest-api,sim
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: requests>=2.25
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=1.0; extra == 'pandas'
Description-Content-Type: text/markdown

# hologram-api

A Python client **and** CLI over the most-used [Hologram REST API](https://github.com/hologram-io/rest-api-docs)
endpoints. Import it in scripts and Databricks notebooks, or use the `hologram`
command line.

- **Package (import name):** `hologram_api`
- **Distribution (pip name):** `wiliot-hologram-api`
- **CLI:** `hologram`

## Install

```bash
pip install wiliot-hologram-api
```

In a **Databricks** notebook:

```python
%pip install wiliot-hologram-api
dbutils.library.restartPython()
```

## Use it as a library

```python
from hologram_api import HologramClient, build_report_rows

# Pass credentials directly...
c = HologramClient(apikey="xxxxxxxx", orgid="12345")

# ...or read HOLOGRAM_API_KEY / HOLOGRAM_ORG_ID from the environment / a .env
c = HologramClient.from_env()

devices = c.request("GET", "/devices", {"orgid": c.orgid})   # single page
all_sims = list(c.paginate("/links/cellular", {"orgid": c.orgid, "limit": 1000}))

rows = build_report_rows(c)                 # full active-SIM inventory (list of dicts)
```

`build_report_rows(client, orgid=None, active_only=True, deep=False, max_usage_pages=40, limit=None)`
returns rows in the order of `SIM_REPORT_COLUMNS` — wrap them in a DataFrame,
write CSV, or `display()` in Databricks.

### Public API
`HologramClient`, `HologramError`, `HologramClient.from_env`, `load_dotenv`,
`split_csv`, `build_report_rows`, `resolve_plan_names`, `SIM_REPORT_COLUMNS`,
`BASE_URL`.

## Use it as a CLI

Credentials resolve in priority order: `--apikey`/`--orgid` flags →
`HOLOGRAM_API_KEY`/`HOLOGRAM_ORG_ID` env vars → the nearest `.env` (searched from
the current directory upward).

```bash
hologram <command> [options]
hologram --help                 # every command
hologram list_devices --help    # help for one command
```

Common flags (place them **after** the command):
`--apikey`, `--orgid`, `--table`, `--fields id,name,...`

### Commands by category

| Category | Commands |
|---|---|
| **Devices** | `list_devices` `count_devices` `get_device` `device_names` `device_locations` `update_device` `device_state` |
| **SIM configuration** | `list_sims` `sim_report` `get_sim` `sim_state` `sim_history` `sim_changeplan` `sim_overage` `sim_threshold` `sim_smslimit` `activate_sim` |
| **Bulk actions** | `bulk_device_state` `bulk_device_changeplan` `bulk_sim_changeplan` `bulk_sim_overage` `bulk_sim_threshold` `bulk_sim_smslimit` `bulk_activate` |
| **Tags** | `list_tags` `create_tag` `tag_link` `tag_unlink` `delete_tag` |
| **Data usage** | `usage_data` `usage_daily` `usage_monthly` `usage_billing` `usage_sms` |
| **Cloud messaging** | `send_sms` `send_message` `send_rdm` `list_messages` |
| **Billing / account** | `whoami` `list_orgs` `get_org` `balance` `add_balance` `balance_history` `list_plans` `get_plan` |

### Examples

```bash
hologram list_devices --table
hologram list_devices --tagname Fleet --all --table
hologram get_device 123456
hologram device_state 123456 pause
hologram send_sms --deviceids 123,456 --body "reboot"
hologram send_message --deviceids 123 --port 4010 --data "ping"
hologram sim_changeplan 999 --planid 73 --zone 1
hologram bulk_device_state --deviceids 1,2,3 live
hologram usage_data --linkid 999 --limit 10
hologram balance
hologram sim_report                 # active SIMs -> sim_report.csv (fast, ~40s)
hologram sim_report --deep -o all.csv   # authoritative last-session (slow)
hologram sim_report --all-states        # include paused/inactive SIMs
```

### `sim_report` — full SIM inventory to CSV
Joins `/links/cellular`, `/devices`, `/usage/data(/billing)`, and `/plans` into one CSV
with columns: name, SIM status, last closed session (UTC), Data usage (MB), Enabled
profile ICCID, Profile name, Last known IMEI, SIM ID, Data plan, Activation date (UTC).
- Default: active (LIVE) SIMs only; `--all-states` for everything.
- **Fast mode (default):** bulk usage scan (~40s for ~900 SIMs). A blank last-session
  means the SIM never connected *or* has been idle beyond the scan window.
- **`--deep`:** adds a per-SIM fallback so a blank definitively means "never connected"
  (slow — one API call per idle SIM; minutes for large fleets).
- Output CSVs are git-ignored (they contain account data).

### `sim_report_databricks.py` — Databricks notebook version
Same report, rendered as an interactive `display()` DataFrame. It `%pip install wiliot-hologram-api`
and calls `build_report_rows`, so there's no duplicated logic. Import the `.py`
into Databricks (it's notebook source with cell markers). Credentials come from a secret
scope + widget:
```
databricks secrets create-scope hologram
databricks secrets put-secret hologram api_key    # your Hologram API key
```
Set the `org_id` widget; toggle `active_only` / `deep` / `max_usage_pages` via widgets.
Builds a pandas DataFrame → Spark DataFrame → `display()`, with an optional Delta-table
write at the bottom. Runs locally too (prints a preview) for testing.

## Publishing to PyPI

The project builds with [hatchling](https://hatch.pypa.io/) using a `src/` layout.

```bash
python -m pip install --upgrade build twine
python -m build                 # -> dist/hologram_api-<version>-py3-none-any.whl + .tar.gz
python -m twine upload dist/*    # needs a PyPI account + API token
```

Bump `version` in both `pyproject.toml` and `src/hologram_api/__init__.py` for each
release (PyPI rejects re-uploads of an existing version). Test against
[TestPyPI](https://test.pypi.org) first with
`twine upload --repository testpypi dist/*` if you like.

## Notes

- **Auth:** HTTP Basic — username `apikey`, password = your API key. Handled automatically.
- **Account ID** = `orgid`; required for activation, billing, and bulk claims. Set once via `HOLOGRAM_ORG_ID`.
- Rate limits (HTTP 429) are retried automatically with backoff.
- List commands support `--limit`; several support `--all` for full pagination.
- Output is pretty JSON by default; add `--table` (with optional `--fields`) for a compact view.
