Metadata-Version: 2.5
Name: geojibe
Version: 0.1.1
Summary: Official Python SDK and CLI for the GeoJibe geospatial processing platform and API.
Project-URL: Homepage, https://geojibe.com
Project-URL: Documentation, https://geojibe.com/guides
Author: AcuGIS
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cli,etl,geojibe,geospatial,gis
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: rich>=13
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0.1; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# geojibe

Official Python SDK and CLI for the [GeoJibe](https://geojibe.com) geospatial
processing platform and API.

`geojibe` is an HTTPS client for an existing GeoJibe installation. Processing
stays on the server. It does **not** require Docker, GDAL, DuckDB, QGIS, Go, or
a local GeoJibe server.

Fuller product documentation: [GeoJibe Guides](https://geojibe.com/guides),
including the [command-line client](https://geojibe.com/guides/reference/cli/).

## Install

This package is published as `geojibe`:

```bash
pip install geojibe
```

or

```bash
pipx install geojibe
```

From a source checkout, Python 3.10 or newer:

```bash
cd clients/python
python -m pip install -e .
```

That provides the `geojibe` executable and the `geojibe` Python package.

## Authenticate

Create a Personal Access Token in **GeoJibe → Account → API Tokens**, then:

```bash
geojibe auth login
```

Enter the GeoJibe URL (your installation origin, for example
`https://geojibe.example.com` — not an `/api/v1` path) and the token.
Token input is hidden. On success: `Authenticated successfully.`

## Use

```bash
geojibe jobs list
geojibe sources list
geojibe destinations list
geojibe recipes list
geojibe jobs run <id>
geojibe workspace upload roads.gpkg
geojibe transformations list
```

`--json` writes machine-readable JSON to stdout:

```bash
geojibe jobs list --json
ID=$(geojibe workspace upload roads.gpkg --json | jq -r '.id')
```

## Automation

```bash
export GEOJIBE_URL=https://geojibe.example.com
export GEOJIBE_TOKEN=gjp_...

geojibe jobs list --json
```

Do not hard-code a hosted GeoJibe URL. Shared, Dedicated, and On-Site
installations each have their own origin.

Credential precedence, highest wins:

1. `--url` / `--token`
2. `GEOJIBE_URL` / `GEOJIBE_TOKEN`
3. Saved configuration

## Configuration

`geojibe config set-url` and `geojibe config set-token` write a user-level
file, never the current working directory:

| OS | Path |
| --- | --- |
| Linux | `~/.config/geojibe/config.toml` (`$XDG_CONFIG_HOME` if set) |
| macOS | `~/Library/Application Support/geojibe/config.toml` |
| Windows | `%APPDATA%\geojibe\config.toml` |

That file may contain a Personal Access Token. Permissions are set to `0600`
on Unix. `geojibe config show` prints a masked token only.

Logout removes the local token. It does not revoke the PAT. Revoke tokens in
**Account → API Tokens**.

```bash
geojibe auth status
geojibe auth logout
```

## Commands

```
geojibe --help
geojibe --version

geojibe auth …
geojibe config …
geojibe sources list|get|create|delete
geojibe destinations list|get|create|delete
geojibe jobs list|get|run|enable|disable|delete|create|update|runs|retry
geojibe recipes list|get|create|delete
geojibe workspace upload|info|preview|convert|download
geojibe workspace transform get|set|clear|preview
geojibe transformations list|show
```

Workspace processing is remote. Discover operations with
`geojibe transformations list` and `geojibe transformations show <id>`.

```bash
geojibe workspace transform set <id> --file pipeline.json
```

```json
{
  "layers": ["apiary"],
  "operations": [
    {"type": "buffer", "distance": 10, "units": "source"}
  ]
}
```

`--debug` prints HTTP method, URL, and status to stderr (never the token).
`--insecure` disables TLS verification for development certificates only and is
not saved. TLS verification is on by default.

`geojibe jobs create --file job.json` sends the public API body
(`POST /api/v1/jobs`). Existing Job JSON without `pipeline` is unchanged
and keeps legacy/inferred stage presence.

Optional Canvas stage flags:

```json
{
  "name": "Neighborhoods",
  "source_id": "…",
  "transform_mode": "sql",
  "sql": "SELECT * FROM source WHERE population > 1000",
  "output_format": "GeoJSON",
  "destination_id": "…",
  "destination_target": {"schema": "public", "table": "neighborhoods", "write_mode": "replace"},
  "schedule": {"kind": "daily", "timezone": "UTC", "hour": 2, "minute": 0},
  "pipeline": {
    "transform": false,
    "convert": false,
    "python": false
  }
}
```

| `pipeline` | Meaning |
| --- | --- |
| omitted | Legacy/inferred behavior (stages stay present) |
| `{}` | Legacy/inferred behavior (stages stay present) |
| explicit `false` | That stage is absent |
| explicit `true` | That stage is present |

Create and update preserve explicit `false` flags. `geojibe jobs get`
shows recorded stages when the Job includes `pipeline`.

## Python

```python
from geojibe import GeoJibe, ValidationError

client = GeoJibe(
    url="https://geojibe.example.com",
    token="gjp_...",
)
```

`url` and `token` may also come from `GEOJIBE_URL` and `GEOJIBE_TOKEN` when
omitted. Explicit constructor arguments always win. The token is sent as
`Authorization: Bearer` and is never logged, stored, or included in
exceptions.

```python
client.me()
```

### Upload

```python
ws = client.workspaces.upload("roads.gpkg")
print(ws.id, ws.status, ws.layers)
```

### Preview

```python
rows = ws.preview_data("roads", limit=50)
geojson = ws.preview_map("roads")["geojson"]
```

`preview_data` and `preview_map` return the server JSON, including fields,
counts, truncation, and CRS. `preview_map()["geojson"]` is a GeoJSON
FeatureCollection. Visualization is up to the caller.

### Transform

Discover operations from the server (do not hard-code a catalog):

```python
ops = client.transformations.list()
```

```python
ws.set_transformations(
    layers=["roads"],
    operations=[{"type": "buffer", "distance": 10, "units": "source"}],
)
```

SQL and Python are sibling fields, not operation types:

```python
ws.set_transformations(layers=["roads"], sql="SELECT * FROM source")
ws.set_transformations(python={"script": script, "filename": "script.py"})
ws.clear_transformations()
```

### Transformed preview

Uses the stored pipeline. The SDK does not resend or execute it locally.

```python
ws.preview_transformed_data("roads", limit=50)
ws.preview_transformed_map("roads")
```

### Convert and download

```python
ws.convert(output_format="GeoJSON", layers=["roads"])
output = ws.download("roads.geojson")
```

Download streams to disk. An existing file is not overwritten unless you pass
`overwrite=True`. Convert is currently synchronous (`status=completed`).

Saved Sources, Destinations, Recipes, and Jobs keep their existing methods.
Job create/update accept the same public body, including optional `pipeline`
flags. Helpers inspect recorded stages without inventing missing keys:

```python
from geojibe import (
    GeoJibe,
    PipelineStages,
    job_pipeline,
    job_write_body,
    pipeline_stages,
    stage_included,
)

jobs = client.jobs.list()
client.jobs.run(jobs[0]["id"])

created = client.jobs.create({
    "name": "Neighborhoods",
    "source_id": "...",
    "output_format": "GeoJSON",
    "pipeline": pipeline_stages(transform=True, convert=True, python=False),
})
job_pipeline(created)
stage_included(created, "python")
```

Omitting `pipeline`, or sending `pipeline: {}`, keeps /api/v1 legacy/inferred
behavior. Explicit `false` removes that stage; leftover operations, format, or
Python on the body do not restore it.

### Errors

```python
try:
    ws.preview_transformed_map("other_layer")
except ValidationError as exc:
    print(exc.status_code, exc.code, exc.message, exc.details)
```

`timeout` (default 30s) is the ordinary HTTP timeout. `run_timeout` (default
600s) is used for upload, preview, convert, and download.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | Failure (including a finished Run with status `failed`) |
| 2 | Usage / local config |
| 3 | Authentication (401 / missing credentials) |
| 4 | Authorization (403 / missing PAT scope) |
| 5 | Not found (404) |
| 6 | Validation (400 / 409 / 422) |
| 7 | Network (DNS, connection refused, TLS, timeout) |
| 8 | GeoJibe server error (5xx) |

## Security

- PAT is sent as `Authorization: Bearer`, never as a query parameter
- Full PAT is not printed by `config show`, `auth status`, or default errors
- Source and Destination secrets from the API are not displayed
