kctl-accurate 0.2.0__tar.gz

kctl_accurate-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_accurate-0.2.0/CLAUDE.md

@@ -0,0 +1,42 @@
+# CLAUDE.md - kctl-accurate
+
+Kodemeio CLI for the Accurate Online API.
+
+## Quick start
+
+```bash
+uv sync --all-packages
+uv run --project ../.. pytest packages/kctl-accurate/tests/ -v
+```
+
+## Architecture
+
+```
+src/kctl_accurate/
+├── cli.py                 # Typer app + @app.callback for global flags
+├── core/
+│   ├── config.py          # SERVICE_KEY=accurate, ServiceConfig, resolve_connection
+│   ├── client.py          # AccurateClientWrapper translates SDK exceptions
+│   ├── exceptions.py      # SDK→KctlError translator (drives exit codes)
+│   └── callbacks.py       # AppContext(AppContextBase), lazy client
+└── commands/
+    ├── config_cmd.py      # init/list/show/use/add/remove/set/test
+    ├── auth.py            # token-info/refresh/logout
+    └── doctor_cmd.py      # ConfigCheck + TokenCheck + DbListCheck
+```
+
+## Key constraints
+
+- SERVICE_KEY: `"accurate"` — config at `profiles.<name>.accurate.*`
+- Depends on `kctl-lib>=0.4.0` (workspace) and `kodemeio-accurate>=0.4.0,<1.0.0` (PyPI)
+- All SDK exceptions translated at the wrapper boundary in `core/client.py`
+- Secrets always masked in any non-debug output (per `~/.claude/rules/security.md`)
+- Exit-code contract enforced by `KctlError` subclass (see `core/exceptions.py`)
+- One profile = one tenant. Multi-tenant via multiple profiles, not multi-target invocation.
+
+## What's next
+
+- Phase 2: 23 module command groups (`customers list`, `invoices get`, etc.) generated from `core/columns.py:MODULE_REGISTRY`
+- Phase 3: `extract`, `export`, `indo` (e-Faktur + 3 validators + 3 statement extractors)
+
+See `kodemeio-accurate/docs/superpowers/specs/2026-04-30-kctl-accurate-design.md` for the full design.

kctl_accurate-0.2.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: kctl-accurate
+Version: 0.2.0
+Summary: Kodemeio Accurate Online CLI — general-purpose ops on the Accurate API
+Requires-Python: >=3.12
+Requires-Dist: kctl-lib>=0.4.0
+Requires-Dist: kodemeio-accurate<1.0.0,>=0.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_accurate-0.2.0/README.md

@@ -0,0 +1,79 @@
+# kctl-accurate
+
+General-purpose CLI for the Accurate Online API. Part of the Kodemeio kctl-* family.
+
+> **v0.1.0a1 (alpha)** — Phase 1 walking skeleton: config + auth + doctor only.
+> Module commands (customers, invoices, etc.) ship in 0.1.0 (Phase 2).
+> Extract / Indo commands ship in 0.2.0 (Phase 3).
+
+## Install
+
+```bash
+uv tool install kctl-accurate
+# or, from the kodemeio-platform monorepo:
+uv sync --all-packages
+```
+
+## Quickstart
+
+```bash
+# Interactive: prompts for token, secret, db_id; verifies; saves.
+kctl-accurate config init
+
+# Verify creds against the live API
+kctl-accurate config test
+
+# Show current token info
+kctl-accurate auth token-info
+
+# Diagnose
+kctl-accurate doctor
+```
+
+## Profiles
+
+Multi-tenant via the kctl-* shared config at `~/.config/kodemeio/config.yaml`:
+
+```yaml
+profiles:
+  tpp:
+    accurate:
+      api_token: aut.xxxxx
+      signature_secret: ${KCTL_ACCURATE_TPP_SECRET}   # env-var indirection works
+      db_id: 12345
+      host: https://public.accurate.id
+      db_alias: PT TPP Indonesia
+```
+
+Use a profile per command: `kctl-accurate -p tpp auth token-info`.
+
+## Global flags
+
+| flag | purpose |
+|---|---|
+| `-p, --profile NAME` | Override active profile |
+| `--api-token TOKEN` | Override profile's api_token |
+| `--signature-secret S` | Override profile's signature_secret |
+| `--db-id N` | Override profile's db_id |
+| `--host URL` | Override profile's host |
+| `--json` | JSON output |
+| `-q, --quiet` | Suppress progress/info |
+| `-V, --version` | Print version + exit |
+
+## Exit codes
+
+| code | meaning |
+|---|---|
+| 0 | success |
+| 1 | command-level failure |
+| 2 | config error (missing creds, bad profile) |
+| 3 | network/API error (5xx, host unreachable) |
+| 4 | auth error (401/403, signature/token) |
+| 5 | rate-limit exhaustion (429 after retries) |
+
+> Note: kctl-lib 0.4.0's `handle_cli_error` currently exits 1 for all KctlError subclasses. The differentiated exit codes above are the *intent* carried by the subclass — they will activate when kctl-lib adds per-subclass exit-code routing or when per-command `_run()` overrides are added.
+
+## Related
+
+- [`kodemeio-accurate`](https://pypi.org/project/kodemeio-accurate/) — the Python SDK powering this CLI
+- `accurate-sync` — the migration writer (Accurate → Odoo); separate tool, separate scope

kctl_accurate-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-accurate"
+version = "0.2.0"
+description = "Kodemeio Accurate Online CLI — general-purpose ops on the Accurate API"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.4.0",
+    "kodemeio-accurate>=0.4.0,<1.0.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-accurate = "kctl_accurate.cli:_run"
+
+[project.entry-points."kctl_accurate.plugins"]
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_accurate"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["kctl_lib", "kctl_lib.*", "accurate_sdk", "accurate_sdk.*"]
+follow_imports = "silent"

kctl_accurate-0.2.0/skills/accurate-admin/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: accurate-admin
+description: >
+  Accurate Online accounting administration via kctl-accurate CLI (10+ groups, ~30 commands + 23 module groups).
+  MUST use for ANY kctl-accurate operation.
+  Triggers on: "accurate", "accounting", "auth", "config", "customers", "dashboard", "db", "doctor",
+  "efaktur", "export", "extract", "glaccounts", "invoices", "items", "kctl-accurate", "migrate",
+  "module", "nsfp", "pph", "profile", "statements", "tax", "validate", "vendors".
+  Auto-generated: 2026-05-03
+---
+
+# accurate-admin -- kctl-accurate CLI Reference
+
+> Auto-generated from `kctl-accurate` command registry. Do not edit manually.
+> To regenerate: `kctl-accurate skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-accurate`
+**Command groups:** 10 core + 23 module groups
+**Total commands:** ~30 core + ~69 module (list/get/count per module)
+**Install:** `cd packages/kctl-accurate && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON |
+| `--quiet`, `-q` | Suppress info messages |
+| `--profile`, `-p` | Config profile name |
+| `--api-token` | Override Accurate API token |
+| `--signature-secret` | Override HMAC-SHA256 secret |
+| `--db-id` | Override Accurate company db_id |
+| `--host` | Override Accurate host |
+| `--version`, `-V` | Show version |
+
+## Command Reference
+
+### `kctl-accurate auth`
+
+Accurate auth operations: token-info, refresh, logout.
+
+| Command | Description |
+|---------|-------------|
+| `auth token-info` | Show current API token info: user, database, host. |
+| `auth refresh` | Refresh the current API session token. |
+| `auth logout` | Invalidate the current API session. |
+
+### `kctl-accurate config`
+
+Manage CLI configuration and profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config init` | Initialize CLI configuration. |
+| `config show` | Show configuration (keys masked). |
+| `config add` | Add a new profile. |
+| `config use` | Switch default profile. |
+| `config remove` | Remove a profile. |
+| `config set` | Set a config value. |
+| `config test` | Test API connection. |
+
+### `kctl-accurate dashboard`
+
+Show a dashboard overview: user info, DB info, and module record counts
+(customers, vendors, items, sales-invoices, purchase-invoices).
+
+### `kctl-accurate db`
+
+Accurate database/company operations.
+
+| Command | Description |
+|---------|-------------|
+| `db list-companies` | List all Accurate companies accessible with this token. |
+| `db open <db_id>` | Open a database session and print session info. |
+| `db info` | Show current profile's database info (user, DB ID, alias, host). |
+
+### `kctl-accurate extract`
+
+Bulk-extract Accurate Online data to JSON files on disk.
+
+| Command | Description |
+|---------|-------------|
+| `extract run --out-dir <path> [--modules] [--no-detail] [--resume]` | Extract data (master + transaction modules) to JSON files. |
+| `extract resume --out-dir <path>` | Resume a previous extraction run, skipping already-fetched files. |
+
+### `kctl-accurate export`
+
+Convert Accurate Online JSON extracts to Odoo-importable CSV files.
+
+| Command | Description |
+|---------|-------------|
+| `export csv --json-dir <path> --out-dir <path> [--modules]` | Convert JSON extracts to Odoo-importable CSV files. |
+
+### `kctl-accurate tax`
+
+e-Faktur (DJP) commands -- list and export faktur pajak data.
+
+| Command | Description |
+|---------|-------------|
+| `tax efaktur-list [--since] [--period] [--out]` | List faktur pajak records for a date range or calendar period. |
+| `tax efaktur-export-csv --out <path> [--period] [--since]` | Export faktur pajak records to a file (.csv, .jsonl, .json). |
+
+### `kctl-accurate validate`
+
+Pre/post-migration data quality checks.
+
+| Command | Description |
+|---------|-------------|
+| `validate nsfp` | Check for duplicate NSFP numbers across open AR/AP invoices. |
+| `validate pph --accurate-totals <file> --odoo-totals <file>` | Check PPh withholding consistency (post-migration). |
+| `validate ar-ap --accurate-balances <file> --odoo-balances <file>` | Check AR/AP open-balance parity (post-migration). |
+
+### `kctl-accurate statements`
+
+Financial statement extraction (opening BS, YTD BS, YTD P&L).
+
+| Command | Description |
+|---------|-------------|
+| `statements opening-bs --as-of <date> [--out]` | Extract opening Balance Sheet at a specific historical date. |
+| `statements ytd-bs [--out]` | Extract year-to-date Balance Sheet (current account balances). |
+| `statements ytd-pl [--out]` | Extract year-to-date Profit & Loss (current account balances). |
+
+### `kctl-accurate doctor`
+
+Run diagnostic checks: config, token validity, DB access.
+
+### Module Groups (23 auto-generated)
+
+Each module group provides `list`, `get`, and `count` subcommands driven by the `MODULE_REGISTRY`.
+
+**Master data:** customers, vendors, items, glaccounts, warehouses, currencies, employees, units, taxes, payment-terms
+
+**Sales:** sales-orders, sales-invoices, sales-receipts, delivery-orders
+
+**Purchase:** purchase-orders, purchase-invoices, purchase-payments, receive-items
+
+**Finance:** journal-vouchers, expenses, bank-transfers, other-deposits, other-payments
+
+**Examples:**
+```bash
+kctl-accurate customers list -p idtpp
+kctl-accurate sales-invoices get 12345 -p idtpp
+kctl-accurate items count -p idtpp
+```
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+Service key: `accurate`
+
+```bash
+kctl-accurate config init       # Interactive setup
+kctl-accurate config show       # Show current config
+kctl-accurate config test       # Verify API connection
+kctl-accurate doctor run        # Full diagnostics
+```
+
+**Examples:**
+```bash
+# Extract all modules to JSON
+kctl-accurate extract run --out-dir ./dump -p idtpp
+
+# Convert extracted JSON to Odoo CSV
+kctl-accurate export csv --json-dir ./dump --out-dir ./csv -p idtpp
+
+# List e-Faktur records for April 2026
+kctl-accurate tax efaktur-list --period 2026-04 -p idtpp
+
+# Pre-migration NSFP duplicate check
+kctl-accurate validate nsfp -p idtpp
+```

kctl_accurate-0.2.0/src/kctl_accurate/__init__.py

@@ -0,0 +1,3 @@
+"""Kodemeio Accurate Online CLI."""
+
+__version__ = "0.2.0"

kctl_accurate-0.2.0/src/kctl_accurate/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m kctl_accurate."""
+
+from kctl_accurate.cli import _run
+
+_run()

kctl_accurate-0.2.0/src/kctl_accurate/cli.py

@@ -0,0 +1,102 @@
+"""Main CLI entry point for kctl-accurate."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_accurate import __version__
+from kctl_accurate.commands.auth import app as auth_app
+from kctl_accurate.commands.config_cmd import app as config_app
+from kctl_accurate.commands.dashboard import app as dashboard_app
+from kctl_accurate.commands.db import app as db_app
+from kctl_accurate.commands.discover import app as discover_app
+from kctl_accurate.commands.doctor_cmd import app as doctor_app
+from kctl_accurate.commands.export import app as export_app
+from kctl_accurate.commands.extract import app as extract_app
+from kctl_accurate.commands.modules import build_module_app
+from kctl_accurate.commands.reports import app as reports_app
+from kctl_accurate.commands.statements import app as statements_app
+from kctl_accurate.commands.tax import app as tax_app
+from kctl_accurate.commands.validate import app as validate_app
+from kctl_accurate.core.callbacks import AppContext
+from kctl_accurate.core.columns import MODULE_REGISTRY
+from kctl_lib.self_update import notify_if_outdated
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-accurate {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-accurate",
+    help="Kodemeio Accurate Online CLI — general-purpose ops on the Accurate API.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+app.add_typer(auth_app, name="auth")
+app.add_typer(config_app, name="config")
+app.add_typer(discover_app, name="discover")
+app.add_typer(doctor_app, name="doctor")
+app.add_typer(db_app, name="db")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(extract_app, name="extract")
+app.add_typer(export_app, name="export")
+app.add_typer(tax_app, name="tax")
+app.add_typer(validate_app, name="validate")
+app.add_typer(reports_app, name="reports")
+app.add_typer(statements_app, name="statements")
+
+# ── Module groups ─────────────────────────────────────────────────────────────
+for _cli_name, _spec in MODULE_REGISTRY.items():
+    app.add_typer(build_module_app(_spec), name=_cli_name)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    api_token: Annotated[str | None, typer.Option("--api-token", help="Override Accurate API token")] = None,
+    signature_secret: Annotated[
+        str | None,
+        typer.Option("--signature-secret", help="Override HMAC-SHA256 secret"),
+    ] = None,
+    db_id: Annotated[int | None, typer.Option("--db-id", help="Override Accurate company db_id")] = None,
+    host: Annotated[str | None, typer.Option("--host", help="Override Accurate host")] = None,
+    version: Annotated[
+        bool,
+        typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version"),
+    ] = False,
+) -> None:
+    """Kodemeio Accurate Online CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        api_token_override=api_token,
+        signature_secret_override=signature_secret,
+        db_id_override=db_id,
+        host_override=host,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-accurate", __version__)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_accurate-0.2.0/src/kctl_accurate/commands/__init__.py

@@ -0,0 +1 @@
+"""kctl-accurate command groups."""

kctl_accurate-0.2.0/src/kctl_accurate/commands/auth.py

@@ -0,0 +1,58 @@
+"""kctl-accurate auth — Accurate Online auth ops."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from kctl_accurate.core.callbacks import AppContext
+
+app = typer.Typer(help="Accurate auth operations: token-info, refresh, logout.")
+
+
+@app.command("token-info")
+def token_info(ctx: typer.Context) -> None:
+    """Show current API token info: user, database, host."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    info = actx.client.token_info()
+
+    if actx.json_mode:
+        print(json.dumps(info, indent=2, ensure_ascii=False))
+        return
+
+    d = info.get("d", {})
+    user = d.get("user") or {}
+    db = d.get("database") or {}
+
+    out.header("Accurate Token Info")
+    out.kv("User", user.get("name", "[dim]—[/dim]"))
+    out.kv("Email", user.get("email", "[dim]—[/dim]"))
+    out.kv("DB ID", str(db.get("id", "[dim]—[/dim]")))
+    out.kv("DB Alias", db.get("alias", "[dim]—[/dim]"))
+    out.kv("Host", db.get("host", "[dim]—[/dim]"))
+
+
+@app.command()
+def refresh(ctx: typer.Context) -> None:
+    """Refresh the current API session token."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    result = actx.client.refresh_token()
+    if actx.json_mode:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return
+    out.success("Token refreshed")
+
+
+@app.command()
+def logout(ctx: typer.Context) -> None:
+    """Invalidate the current API session."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    result = actx.client.logout()
+    if actx.json_mode:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return
+    out.success("Logged out")