makeleaps-client 0.1.0__py3-none-any.whl

makeleaps_client/__init__.py

@@ -0,0 +1,8 @@
+"""Unofficial, async Python client for the MakeLeaps REST API."""
+from .client import MakeLeapsClient, MakeLeapsError
+from .models import Client, Contact, Document, DocumentArchive, LineItem, Partner
+
+__all__ = [
+    'MakeLeapsClient', 'MakeLeapsError', 'Partner', 'Document',
+    'DocumentArchive', 'Client', 'Contact', 'LineItem',
+]

makeleaps_client/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

makeleaps_client/cli.py

@@ -0,0 +1,171 @@
+"""Command-line interface built on the async library."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+from datetime import date
+import os
+from pathlib import Path
+import re
+import sys
+from typing import Any
+
+import yaml
+
+from .client import MakeLeapsClient, MakeLeapsError
+
+
+def _nonnegative(value: str) -> int:
+    try:
+        number = int(value)
+        if number < 0:
+            raise ValueError
+        return number
+    except ValueError:
+        raise argparse.ArgumentTypeError('limit must be a nonnegative integer') from None
+
+
+def _date(value: str) -> str:
+    try:
+        return date.fromisoformat(value).isoformat()
+    except ValueError:
+        raise argparse.ArgumentTypeError('dates must use YYYY-MM-DD') from None
+
+
+def _filter(value: str) -> tuple[str, str]:
+    key, separator, val = value.partition('=')
+    if not separator or not key:
+        raise argparse.ArgumentTypeError('filters must use key=value')
+    return key, val
+
+
+def _list_options(parser, *, documents=False):
+    parser.add_argument('--limit', type=_nonnegative, help='Maximum number of records (default: all)')
+    if documents:
+        parser.add_argument('--type', dest='document_type', help='API document_type value')
+        parser.add_argument('--date-from', type=_date, help='Inclusive issue date, YYYY-MM-DD')
+        parser.add_argument('--date-to', type=_date, help='Inclusive issue date, YYYY-MM-DD')
+        parser.add_argument('--filter', action='append', type=_filter, default=[], metavar='KEY=VALUE', help='Pass an API query parameter; may be repeated')
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog='makeleaps', description='Read MakeLeaps company data, documents, archives, and PDFs.')
+    parser.add_argument('--language', default='ja', help='Response language (default: ja)')
+    commands = parser.add_subparsers(dest='resource', required=True)
+    partner = commands.add_parser('partner', help='Get the company associated with the API key')
+    partner.add_argument('--language', default=argparse.SUPPRESS)
+    for name in ('documents', 'archives'):
+        group = commands.add_parser(name, help='Read documents' if name == 'documents' else 'Read records saved at the time of sending')
+        group.add_argument('--language', default=argparse.SUPPRESS)
+        actions = group.add_subparsers(dest='operation', required=True)
+        listing = actions.add_parser('list', help='List all matching records')
+        listing.add_argument('--language', default=argparse.SUPPRESS)
+        _list_options(listing, documents=name == 'documents')
+        if name == 'documents':
+            get = actions.add_parser('get', help='Get a document with its client and contact')
+            get.add_argument('mid')
+            get.add_argument('--language', default=argparse.SUPPRESS)
+        pdf = actions.add_parser('pdf', help='Save one PDF, or all matching PDFs with --dir')
+        pdf.add_argument('mid', nargs='?')
+        pdf.add_argument('--language', default=argparse.SUPPRESS)
+        destinations = pdf.add_mutually_exclusive_group(required=True)
+        destinations.add_argument('--output', type=Path, metavar='FILE')
+        destinations.add_argument('--dir', type=Path, metavar='DIRECTORY')
+        _list_options(pdf, documents=name == 'documents')
+    return parser
+
+
+def _safe_component(value: Any) -> str:
+    # Include Windows filename restrictions so exported names remain portable.
+    return re.sub(r'[<>:"/\\|?*\x00-\x1f\x7f]', '_', str(value)).rstrip(' .')
+
+
+def _filename(record) -> str:
+    if not record.mid:
+        raise MakeLeapsError('A PDF record is missing its mid.')
+    values = (record.date or 'unknown', record.document_type or 'unknown',
+              record.document_number or '', record.mid)
+    return '_'.join(_safe_component(value) for value in values) + '.pdf'
+
+
+async def _records(api, args):
+    if args.resource == 'documents':
+        iterator = api.list_documents(document_type=args.document_type,
+                                      date_from=args.date_from, date_to=args.date_to,
+                                      filters=args.filter)
+    else:
+        iterator = api.list_archives()
+    count = 0
+    try:
+        if args.limit == 0:
+            return
+        async for record in iterator:
+            yield record
+            count += 1
+            if args.limit is not None and count >= args.limit:
+                return
+    finally:
+        await iterator.aclose()
+
+
+async def _execute(args, client_id, client_secret):
+    async with MakeLeapsClient(client_id, client_secret, language=args.language) as api:
+        if args.resource == 'partner':
+            return (await api.get_partner()).model_dump()
+        if args.operation == 'get':
+            return (await api.get_document(args.mid)).model_dump()
+        if args.operation == 'list':
+            return [record.model_dump() async for record in _records(api, args)]
+        fetch = api.get_document_pdf if args.resource == 'documents' else api.get_archive_pdf
+        if args.mid:
+            args.output.write_bytes(await fetch(args.mid))
+            return None
+        directory = args.dir
+        directory.mkdir(parents=True, exist_ok=True)
+        existing = {path.name for path in directory.iterdir() if path.is_file()}
+        records = _records(api, args)
+        try:
+            async for record in records:
+                filename = _filename(record)
+                suffix = '_' + _safe_component(record.mid) + '.pdf'
+                if any(name.endswith(suffix) for name in existing):
+                    continue
+                (directory / filename).write_bytes(await fetch(record.mid))
+                existing.add(filename)
+        finally:
+            await records.aclose()
+        return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if getattr(args, 'operation', None) == 'pdf':
+        if args.mid and args.dir:
+            parser.error('use either MID with --output, or --dir without MID')
+        if not args.mid and args.output:
+            parser.error('--output requires MID')
+        if args.mid and (args.limit is not None or (args.resource == 'documents' and any((args.document_type, args.date_from, args.date_to, args.filter)))):
+            parser.error('filters and --limit apply only to --dir')
+    if args.resource == 'documents' and getattr(args, 'date_from', None) and getattr(args, 'date_to', None):
+        if args.date_from > args.date_to:
+            parser.error('--date-from must not be later than --date-to')
+    client_id = os.environ.get('MAKELEAPS_CLIENT_ID')
+    client_secret = os.environ.get('MAKELEAPS_CLIENT_SECRET')
+    if not client_id or not client_secret:
+        print('Set both MAKELEAPS_CLIENT_ID and MAKELEAPS_CLIENT_SECRET.', file=sys.stderr)
+        return 1
+    try:
+        result = asyncio.run(_execute(args, client_id, client_secret))
+        if result is not None:
+            print(yaml.safe_dump(result, allow_unicode=True, sort_keys=False), end='')
+        return 0
+    except MakeLeapsError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    except OSError:
+        print('Unable to read or write the requested output file.', file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print('Interrupted.', file=sys.stderr)
+        return 130

makeleaps_client/client.py

@@ -0,0 +1,350 @@
+"""Async, read-only MakeLeaps client with bounded retries and pagination."""
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from collections.abc import AsyncIterator, Mapping, Sequence
+from datetime import date
+from email.utils import parsedate_to_datetime
+import math
+import time
+from typing import Any, TypeVar
+from urllib.parse import quote, urljoin
+
+import httpx
+from pydantic import ValidationError
+
+from .models import Contact, Client, Document, DocumentArchive, Partner, Resource
+
+_ORIGIN = 'https://api.makeleaps.com'
+_TOKEN_URL = _ORIGIN + '/user/oauth2/token/'
+_PAGE_SIZE = 100
+_PAGE_CONCURRENCY = 8
+_ATTEMPTS = 4
+T = TypeVar('T', bound=Resource)
+Filters = Mapping[str, Any] | Sequence[tuple[str, Any]]
+
+
+class MakeLeapsError(Exception):
+    """A request or response failure, without credentials or raw server content."""
+
+
+def _safe_url(value: str) -> httpx.URL:
+    try:
+        # Only API-relative links can be resolved against the fixed TLS origin.
+        url = httpx.URL(urljoin(_ORIGIN + '/', value))
+        if (url.scheme != 'https' or url.host != 'api.makeleaps.com'
+                or url.port not in (None, 443) or url.userinfo or url.fragment):
+            raise ValueError
+        return url
+    except (ValueError, TypeError, httpx.InvalidURL):
+        raise MakeLeapsError('The API returned an unsupported resource URL.') from None
+
+
+async def _together(*coroutines):
+    tasks = [asyncio.create_task(coro) for coro in coroutines]
+    try:
+        return await asyncio.gather(*tasks)
+    finally:
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+class _Limiter:
+    def __init__(self):
+        self._recent = deque()
+        self._daily = deque()
+        self._lock = asyncio.Lock()
+        self._blocked_until = 0.0
+
+    def defer(self, seconds: float) -> None:
+        self._blocked_until = max(self._blocked_until, time.monotonic() + seconds)
+
+    async def acquire(self) -> None:
+        async with self._lock:
+            while True:
+                now = time.monotonic()
+                while self._recent and self._recent[0] <= now - 60:
+                    self._recent.popleft()
+                while self._daily and self._daily[0] <= now - 86400:
+                    self._daily.popleft()
+                delay = max(0.0, self._blocked_until - now)
+                if len(self._recent) >= 250:
+                    delay = max(delay, self._recent[0] + 60 - now)
+                if len(self._daily) >= 20000:
+                    delay = max(delay, self._daily[0] + 86400 - now)
+                if delay > 0:
+                    await asyncio.sleep(delay)
+                    continue
+                self._recent.append(now)
+                self._daily.append(now)
+                return
+
+
+def _retry_after(response: httpx.Response, attempt: int) -> float:
+    value = response.headers.get('Retry-After', '')
+    try:
+        delay = float(value)
+        if math.isfinite(delay) and delay >= 0:
+            return delay
+    except ValueError:
+        try:
+            return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
+        except (ValueError, TypeError, OverflowError):
+            pass
+    return float(2 ** attempt)
+
+
+class MakeLeapsClient:
+    """Use credentials from arguments only; close with ``async with`` or ``aclose``.
+
+    ``transport`` supports HTTP boundary substitution, e.g. httpx.MockTransport.
+    A client belongs to one event loop. Its token and request limiter are shared
+    by all operations on that client.
+    """
+
+    def __init__(self, client_id: str, client_secret: str, *, language: str = 'ja',
+                 transport: httpx.AsyncBaseTransport | None = None):
+        if not client_id or not client_secret:
+            raise MakeLeapsError('Both client_id and client_secret are required.')
+        self._credentials = httpx.BasicAuth(client_id, client_secret)
+        self._http = httpx.AsyncClient(
+            headers={'Accept-Language': language, 'Accept': 'application/json'},
+            transport=transport, follow_redirects=False, timeout=60.0,
+            trust_env=False,
+        )
+        self._token = None
+        self._expires_at = 0.0
+        self._token_lock = asyncio.Lock()
+        self._partner_url = None
+        self._partner_lock = asyncio.Lock()
+        self._limiter = _Limiter()
+
+    async def __aenter__(self) -> MakeLeapsClient:
+        return self
+
+    async def __aexit__(self, *exc_info) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+        self._token = None
+        self._expires_at = 0.0
+
+    async def _send(self, method: str, url: str | httpx.URL, **kwargs) -> httpx.Response:
+        url = _safe_url(str(url))
+        for attempt in range(_ATTEMPTS):
+            await self._limiter.acquire()
+            try:
+                response = await self._http.request(method, url, **kwargs)
+            except httpx.HTTPError:
+                if attempt + 1 == _ATTEMPTS:
+                    raise MakeLeapsError('Unable to communicate with the MakeLeaps API.') from None
+                await asyncio.sleep(2 ** attempt)
+                continue
+            if response.status_code == 429:
+                if attempt + 1 == _ATTEMPTS:
+                    raise MakeLeapsError('The MakeLeaps API rate limit persisted after retries.')
+                self._limiter.defer(_retry_after(response, attempt))
+                continue
+            if response.status_code >= 500 and attempt + 1 < _ATTEMPTS:
+                await asyncio.sleep(2 ** attempt)
+                continue
+            return response
+        raise MakeLeapsError('Unable to complete the MakeLeaps API request.')
+
+    @staticmethod
+    def _check(response: httpx.Response) -> None:
+        if not 200 <= response.status_code < 300:
+            raise MakeLeapsError(f'MakeLeaps API request failed (HTTP {response.status_code}).')
+
+    @staticmethod
+    def _json(response: httpx.Response) -> dict[str, Any]:
+        try:
+            data = response.json()
+            if not isinstance(data, dict):
+                raise ValueError
+            return data
+        except (ValueError, UnicodeError):
+            raise MakeLeapsError('The MakeLeaps API returned invalid JSON.') from None
+
+    async def _access_token(self, rejected: str | None = None) -> str:
+        async with self._token_lock:
+            if self._token and time.monotonic() < self._expires_at and self._token != rejected:
+                return self._token
+            response = await self._send('POST', _TOKEN_URL, auth=self._credentials,
+                                        data={'grant_type': 'client_credentials'})
+            self._check(response)
+            data = self._json(response)
+            try:
+                token = data['access_token']
+                expires = float(data['expires_in'])
+                if not isinstance(token, str) or not token or not math.isfinite(expires) or expires <= 0:
+                    raise ValueError
+            except (KeyError, TypeError, ValueError):
+                raise MakeLeapsError('The MakeLeaps API returned an invalid access token response.') from None
+            self._token = token
+            self._expires_at = time.monotonic() + expires
+            return token
+
+    async def _request(self, url: str | httpx.URL, *, params=None) -> httpx.Response:
+        url = _safe_url(str(url))
+        token = await self._access_token()
+        response = await self._send('GET', url, params=params,
+                                    headers={'Authorization': f'Bearer {token}'})
+        if response.status_code == 401:
+            token = await self._access_token(rejected=token)
+            response = await self._send('GET', url, params=params,
+                                        headers={'Authorization': f'Bearer {token}'})
+        self._check(response)
+        return response
+
+    async def _data(self, url: str | httpx.URL, *, params=None) -> dict[str, Any]:
+        data = self._json(await self._request(url, params=params))
+        if 'response' not in data:
+            raise MakeLeapsError('The MakeLeaps API response is missing its resource data.')
+        return data
+
+    @staticmethod
+    def _model(model: type[T], data: Any) -> T:
+        try:
+            return model.model_validate(data)
+        except ValidationError:
+            raise MakeLeapsError('The MakeLeaps API returned an invalid resource.') from None
+
+    async def _company(self) -> str:
+        async with self._partner_lock:
+            if self._partner_url is None:
+                data = (await self._data(_ORIGIN + '/api/'))['response']
+                try:
+                    partners = data['partners']
+                    if len(partners) != 1:
+                        raise ValueError
+                    self._partner_url = str(_safe_url(partners[0]['url']))
+                except (KeyError, TypeError, ValueError):
+                    raise MakeLeapsError('The API key must identify exactly one company.') from None
+            return self._partner_url
+
+    async def get_partner(self) -> Partner:
+        """Return the company associated with the API key."""
+        return self._model(Partner, (await self._data(await self._company()))['response'])
+
+    async def _resource(self, kind: str, mid: str) -> dict[str, Any]:
+        if not mid:
+            raise MakeLeapsError('A resource mid is required.')
+        url = (await self._company()) + kind + '/' + quote(str(mid), safe='') + '/'
+        value = (await self._data(url))['response']
+        if not isinstance(value, dict):
+            raise MakeLeapsError('The MakeLeaps API returned an invalid resource.')
+        return value
+
+    async def _pages(self, url: str, params=None) -> AsyncIterator[list[dict[str, Any]]]:
+        query = httpx.QueryParams({'page_size': _PAGE_SIZE, 'page': 1})
+        if params:
+            query = query.merge(params)
+        first = await self._data(url, params=query)
+        values, meta = self._page(first)
+        yield values
+        if not meta.get('next'):
+            return
+        _safe_url(meta['next'])
+        count, page = meta.get('count'), meta.get('page', 1)
+        if isinstance(count, int) and isinstance(page, int) and values:
+            last_page = math.ceil(count / len(values))
+            for start in range(page + 1, last_page + 1, _PAGE_CONCURRENCY):
+                pages = await _together(*(self._data(url, params=query.set('page', number))
+                                         for number in range(start, min(start + _PAGE_CONCURRENCY, last_page + 1))))
+                for data in pages:
+                    batch, _ = self._page(data)
+                    yield batch
+        else:
+            # Older responses without count still have a usable next link.
+            seen = {str(_safe_url(url).copy_merge_params(query))}
+            while meta.get('next'):
+                next_url = str(_safe_url(meta['next']))
+                if next_url in seen:
+                    raise MakeLeapsError('The MakeLeaps API returned a repeated page.')
+                seen.add(next_url)
+                values, meta = self._page(await self._data(next_url))
+                yield values
+
+    @staticmethod
+    def _page(data):
+        values, meta = data['response'], data.get('meta', {})
+        if not isinstance(values, list) or not all(isinstance(v, dict) for v in values) or not isinstance(meta, dict):
+            raise MakeLeapsError('The MakeLeaps API returned an invalid list page.')
+        return values, meta
+
+    async def _related(self) -> tuple[dict[str, Any], dict[str, Any]]:
+        company = await self._company()
+        async def collect(kind):
+            records = {}
+            async for page in self._pages(company + kind + '/'):
+                for item in page:
+                    if isinstance(item.get('url'), str):
+                        records[item['url']] = item
+            return records
+        clients, contacts = await _together(collect('client'), collect('contact'))
+        return clients, contacts
+
+    def _expand(self, value, related) -> Document:
+        value = dict(value)
+        for field, records in zip(('client', 'client_contact'), related):
+            reference = value.get(field)
+            if isinstance(reference, str):
+                if reference not in records:
+                    raise MakeLeapsError('A document references an unavailable client or contact.')
+                value[field] = records[reference]
+        return self._model(Document, value)
+
+    async def get_document(self, mid: str) -> Document:
+        """Return a document with its complete client and contact resources."""
+        value, related = await _together(self._resource('document', mid), self._related())
+        return self._expand(value, related)
+
+    async def list_documents(self, *, document_type: str | None = None,
+                             date_from: date | str | None = None,
+                             date_to: date | str | None = None,
+                             filters: Filters | None = None) -> AsyncIterator[Document]:
+        """Yield all matching documents in API order, fetching pages on demand.
+
+        Date bounds are inclusive. ``filters`` accepts a mapping or pairs, so
+        repeated API parameters such as document_number retain all values.
+        """
+        params = httpx.QueryParams(filters or {})
+        for key, value in (('document_type', document_type), ('date__gte', date_from), ('date__lte', date_to)):
+            if value is not None:
+                params = params.set(key, value.isoformat() if isinstance(value, date) else value)
+        pages = self._pages((await self._company()) + 'document/', params)
+        try:
+            first, related = await _together(anext(pages), self._related())
+            for value in first:
+                yield self._expand(value, related)
+            async for page in pages:
+                for value in page:
+                    yield self._expand(value, related)
+        finally:
+            await pages.aclose()
+
+    async def list_archives(self) -> AsyncIterator[DocumentArchive]:
+        """Yield every Document Archive in API order."""
+        async for page in self._pages((await self._company()) + 'archive/'):
+            for value in page:
+                yield self._model(DocumentArchive, value)
+
+    async def _pdf(self, kind: str, mid: str) -> bytes:
+        value = await self._resource(kind, mid)
+        url = value.get('pdf_content_url')
+        if not isinstance(url, str) or not url:
+            raise MakeLeapsError('No PDF is available for this resource.')
+        return (await self._request(url)).content
+
+    async def get_document_pdf(self, mid: str) -> bytes:
+        """Return current document PDF bytes, without modifying the document."""
+        return await self._pdf('document', mid)
+
+    async def get_archive_pdf(self, mid: str) -> bytes:
+        """Return the PDF bytes saved at the time of sending."""
+        return await self._pdf('archive', mid)

makeleaps_client/models.py

@@ -0,0 +1,231 @@
+"""Permissive models for MakeLeaps API v2023.06.26 read responses."""
+from __future__ import annotations
+
+import datetime as dt
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Resource(BaseModel):
+    """Retain unknown fields and serialize only fields present in the response."""
+
+    model_config = ConfigDict(extra="allow")
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        kwargs.setdefault("mode", "json")
+        kwargs.setdefault("exclude_unset", True)
+        return super().model_dump(**kwargs)
+
+
+class Money(Resource):
+    amount: Decimal | None = None
+    currency: str | None = None
+
+
+class TaxTotal(Resource):
+    tax_type: str | None = None
+    tax_rate: Decimal | None = None
+    currency: str | None = None
+    subtotal: Decimal | Money | None = None
+    tax: Decimal | Money | None = None
+
+
+class Partner(Resource):
+    url: str | None = None
+    name: str | None = None
+    clients: str | None = None
+    contacts: str | None = None
+    documents: str | None = None
+    line_item_catalog: str | None = None
+    tags: str | None = None
+    sending_orders: str | None = None
+    history: str | None = None
+    integrations: dict[str, Any] | None = None
+    account_name: str | None = None
+    tax_registration_number: str | None = None
+
+
+class Client(Resource):
+    url: str | None = None
+    mid: str | None = None
+    display_name: str | None = None
+    organization_type: str | None = None
+    is_organization: bool | None = None
+    date_archived: dt.datetime | None = None
+    client_external_id: str | None = None
+    contacts: list[Any] | None = None
+    default_contact: str | dict[str, Any] | None = None
+    managing_teams: list[Any] | None = None
+    default_presets: list[Any] | None = None
+    integrations: dict[str, Any] | None = None
+    lang_code: str | None = None
+    settings: str | dict[str, Any] | None = None
+    date_cutoff: int | None = None
+    tax_registration_number: str | None = None
+    virtual_bank_accounts: list[Any] | None = None
+
+
+class Contact(Resource):
+    url: str | None = None
+    mid: str | None = None
+    owner: str | dict[str, Any] | None = None
+    owner_type: str | None = None
+    contact_type: str | None = None
+    name: str | None = None
+    family_name: str | None = None
+    given_name: str | None = None
+    display_name: str | None = None
+    title: str | None = None
+    department: str | None = None
+    format: str | None = None
+    phone_number: str | None = None
+    fax_number: str | None = None
+    is_default: bool | str | None = None
+    email: str | dict[str, Any] | None = None
+    addresses: list[Any] | None = None
+    default_address: str | dict[str, Any] | None = None
+    integrations: dict[str, Any] | None = None
+
+
+class LineItem(Resource):
+    kind: str | None = None
+    description: str | None = None
+    unit_cost: Decimal | None = None
+    quantity: Decimal | None = None
+    quantity_unit: str | None = None
+    price: Decimal | None = None
+    is_taxable: bool | None = None
+    is_tax_inclusive: bool | None = None
+    has_jp_withholding_tax: bool | None = None
+    currency: str | None = None
+    tax_rate: Decimal | None = None
+    tax_type: str | None = None
+    extended_data: dict[str, Any] | None = None
+    vendor_cost: Decimal | None = None
+    source_catalog_item: str | None = None
+
+
+class Document(Resource):
+    document_number: str | None = None
+    document_type: str | None = None
+    title: str | None = None
+    project_name: str | None = None
+    bank_details_header: str | None = None
+    bank_details: str | None = None
+    message: str | None = None
+    proviso: str | None = None
+    group_lineitem_by_tax_rate: bool | None = None
+    has_hanko: bool | None = None
+    has_prices: bool | None = None
+    has_totals: bool | None = None
+    has_currency_code: bool | None = None
+    has_lineitem_tax_state: bool | None = None
+    show_lineitem_tax_rate: bool | None = None
+    show_lineitem_tax_state: bool | None = None
+    show_lineitem_tax_type: bool | None = None
+    signature: bool | None = None
+    display_tax_rate: bool | None = None
+    hide_tax_description: bool | None = None
+    has_tax_stamp: bool | None = None
+    currency: str | None = None
+    subtotal: Decimal | None = None
+    tax: Decimal | None = None
+    jp_withholding_tax: Decimal | None = None
+    tax_rate: Decimal | None = None
+    tax_type: str | None = None
+    subtotal_sales_tax: Decimal | None = None
+    subtotal_withholding_tax: Decimal | None = None
+    total: Decimal | None = None
+    mixed_tax_rate_totals: dict[str, TaxTotal] | None = None
+    tax_group_totals: list[TaxTotal] | None = None
+    extended_data: dict[str, Any] | None = None
+    mid: str | None = None
+    document_template: str | dict[str, Any] | None = None
+    display_name: str | None = None
+    note: str | None = None
+    external_id: str | None = None
+    round_tax_down: bool | None = None
+    tax_rounding: str | None = None
+    lineitem_price_rounding: str | None = None
+    tags: list[Any] | None = None
+    url: str | None = None
+    pickup_links: str | dict[str, Any] | None = None
+    pdf_content_url: str | None = None
+    pdf_upload_url: str | None = None
+    client: Client | str | None = None
+    client_contact: Contact | str | None = None
+    modified: dt.datetime | None = None
+    date_paid: dt.datetime | None = None
+    date_sent: dt.datetime | None = None
+    date_cancelled: dt.datetime | None = None
+    date_removed: dt.datetime | None = None
+    date_accepted: dt.datetime | None = None
+    date_confirmed: dt.datetime | None = None
+    date_converted: dt.datetime | None = None
+    payment_date: dt.date | None = None
+    invoicing_period_start_date: dt.date | None = None
+    invoicing_period_end_date: dt.date | None = None
+    is_accepted: bool | None = None
+    is_confirmed: bool | None = None
+    is_converted: bool | None = None
+    approval_status: str | None = None
+    integrations: dict[str, Any] | None = None
+    date: dt.date | None = None
+    date_due: dt.date | None = None
+    date_valid: dt.date | None = None
+    date_shipped: dt.date | None = None
+    sender_name: str | None = None
+    sender_contact_department: str | None = None
+    sender_contact_title: str | None = None
+    sender_contact_name: str | None = None
+    sender_address_format: str | None = None
+    sender_country: str | None = None
+    sender_postal_code: str | None = None
+    sender_region: str | None = None
+    sender_locality: str | None = None
+    sender_street_address: str | None = None
+    sender_extended_address: str | None = None
+    sender_phone_number: str | None = None
+    sender_fax_number: str | None = None
+    partner_tax_registration_number: str | None = None
+    display_partner_tax_registration_number: bool | None = None
+    recipient_name: str | None = None
+    recipient_contact_department: str | None = None
+    recipient_contact_title: str | None = None
+    recipient_contact_name: str | None = None
+    recipient_honorific: str | None = None
+    recipient_address_format: str | None = None
+    recipient_country: str | None = None
+    recipient_postal_code: str | None = None
+    recipient_region: str | None = None
+    recipient_locality: str | None = None
+    recipient_street_address: str | None = None
+    recipient_extended_address: str | None = None
+    recipient_phone_number: str | None = None
+    recipient_fax_number: str | None = None
+    client_tax_registration_number: str | None = None
+    display_client_tax_registration_number: bool | None = None
+    lineitems: list[LineItem] | None = None
+    purchase_order_ids: list[Any] | None = None
+    peppol_details: Any | None = None
+
+
+class DocumentArchive(Resource):
+    mid: str | None = None
+    url: str | None = None
+    pdf_content_url: str | None = None
+    uses_external_pdf: bool | str | None = None
+    document_type: str | None = None
+    document_number: str | None = None
+    sending_methods: list[str] | None = None
+    legal_categories: list[Any] | None = None
+    date_sent: dt.datetime | None = None
+    date: dt.date | None = None
+    sender: str | None = None
+    client: str | None = None
+    currency: str | None = None
+    total: Decimal | None = None
+    external_id: str | None = None
+    delivery_methods: list[str] | None = None

makeleaps_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: makeleaps-client
+Version: 0.1.0
+Summary: Unofficial Python client library and CLI for the MakeLeaps REST API (not affiliated with MakeLeaps, Inc.)
+Project-URL: Repository, https://github.com/minamikik/makeleaps-client
+Author-email: minamik <10973755+minamikik@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# makeleaps-client
+
+Unofficial Python client library and CLI for the MakeLeaps REST API. This project is not affiliated with or endorsed by MakeLeaps, Inc.
+
+The client targets API keys using **MakeLeaps API version `v2023.06.26`**. Response shapes and behavior were checked against that version. MakeLeaps assigns the API version to your API key; the client does not select a version in requests. Other API key versions have not been verified.
+
+Requires Python 3.12 or newer. Distributed under the MIT license.
+
+```sh
+pip install makeleaps-client
+```
+
+The package provides the `makeleaps_client` library and the `makeleaps` command. Both support read operations only: your company, documents of every type, current document PDFs, Document Archives, and PDFs preserved at the time of sending. Choose the PDF source appropriate for your records; an archive may not exist for every sent document.
+
+## Async Python library
+
+Pass credentials explicitly. The library reads neither environment variables nor configuration files. It discovers the one company associated with the API key, so no company argument is needed.
+
+```python
+import asyncio
+from pathlib import Path
+
+from makeleaps_client import MakeLeapsClient, MakeLeapsError
+
+
+async def read_documents(client_id: str, client_secret: str):
+    async with MakeLeapsClient(client_id, client_secret) as api:
+        company = await api.get_partner()
+        print(company.name)
+
+        async for document in api.list_documents(
+            document_type="invoice",
+            date_from="2025-01-01",
+            date_to="2025-12-31",
+            filters={"sent": "true"},
+        ):
+            print(document.mid, document.total, document.client.display_name)
+
+        document = await api.get_document("example-document-mid")
+        print(document.model_dump())
+        Path("current.pdf").write_bytes(
+            await api.get_document_pdf("example-document-mid")
+        )
+
+        async for archive in api.list_archives():
+            print(archive.mid, archive.date_sent)
+        Path("sent.pdf").write_bytes(
+            await api.get_archive_pdf("example-archive-mid")
+        )
+
+
+# Supply credentials from your application's own credential handling.
+# asyncio.run(read_documents(client_id, client_secret))
+```
+
+Use one client within one event loop. The async context manager closes its HTTP connections; alternatively call `await api.aclose()`. Handle request failures with `MakeLeapsError`.
+
+| Operation | Result |
+| --- | --- |
+| `await api.get_partner()` | `Partner` |
+| `api.list_documents(document_type=None, date_from=None, date_to=None, filters=None)` | Async iterator of `Document` |
+| `await api.get_document(mid)` | `Document` |
+| `await api.get_document_pdf(mid)` | PDF `bytes` |
+| `api.list_archives()` | Async iterator of `DocumentArchive` |
+| `await api.get_archive_pdf(mid)` | PDF `bytes` |
+
+Date bounds are inclusive (`date__gte` and `date__lte`). They accept `datetime.date` or ISO date strings. Other filters pass through using the API's parameter names and values. To repeat a parameter, supply pairs, for example `filters=[("document_number", "EXAMPLE-A"), ("document_number", "EXAMPLE-B")]`. MakeLeaps may silently ignore unsupported filters; consult its API documentation.
+
+List operations yield every matching record in API order. Pages contain up to 100 records, and up to eight subsequent pages are fetched together when iteration advances beyond the current batch. Stopping iteration avoids subsequent batches; pages already requested in the current batch may have completed. Use `await iterator.aclose()` when explicitly holding an iterator and ending it early.
+
+Documents include full client and client contact resources. Each document operation loads the client and contact lists once and joins them by URL. Those lists are not cached across operations. An unavailable referenced resource causes `MakeLeapsError` rather than returning a partially expanded document.
+
+Models are permissive pydantic models: all fields are optional, unknown fields are retained, and enum-like values remain strings. Known monetary and numeric fields become `Decimal`, dates become `datetime.date`, and timestamps become `datetime.datetime`. Nested line items and tax totals are also typed. `model_dump()` defaults to JSON-compatible API values, retaining unknown fields and omitting fields absent from the response. Explicit `mode="python"` produces Python values instead.
+
+The default response language is Japanese. Set `MakeLeapsClient(client_id, client_secret, language="en")` to change `Accept-Language` on all requests.
+
+## Command line
+
+The CLI reads `MAKELEAPS_CLIENT_ID` and `MAKELEAPS_CLIENT_SECRET` from its environment and passes them to the library. Set them using your shell's or process runner's credential handling. It does not read configuration files.
+
+```sh
+makeleaps --help
+makeleaps partner
+makeleaps documents list --type invoice --date-from 2025-01-01 --date-to 2025-12-31
+makeleaps documents list --filter sent=true --filter document_number=EXAMPLE-A --limit 10
+makeleaps documents get example-document-mid
+makeleaps documents pdf example-document-mid --output current.pdf
+makeleaps archives list --limit 10
+makeleaps archives pdf example-archive-mid --output sent.pdf
+makeleaps documents list --language en
+```
+
+Company, document, and archive results are written as complete YAML values to stdout. Each list is a single YAML sequence, including when empty. Monetary values remain strings in YAML. PDF commands write the original bytes to files. Failures produce an explanatory message on stderr and a nonzero exit status; completed files from an interrupted or failed bulk export remain on disk.
+
+Bulk PDF downloads create the destination directory if needed:
+
+```sh
+makeleaps documents pdf --dir ./current-pdfs --type invoice --date-from 2025-01-01 --filter sent=true
+makeleaps archives pdf --dir ./sent-pdfs --limit 100
+```
+
+Documents accept the same filters for `list` and bulk `pdf`. Archives support `--limit` and `--language`. Without `--limit`, list and bulk PDF commands process every matching record; `--limit 0` processes none. `--language` is accepted on every command, and defaults to `ja`.
+
+Bulk filenames use `<date>_<document_type>_<document_number>_<mid>.pdf`. Characters that cannot be used in portable filenames are replaced with `_`. A file with the same `mid` suffix already in the destination directory is skipped without fetching that PDF, even if its document number changed. The current document PDF and its archive PDF can differ; use separate directories for each source.
+
+## Authentication and requests
+
+Requests use HTTPS exclusively on `api.makeleaps.com`, with redirects disabled. Access tokens remain in process memory. Expired tokens and a 401 response cause reauthentication; a second 401 fails. Error messages do not include credentials, tokens, or raw response bodies.
+
+All requests on one client share a rolling limiter of 250 requests per 60 seconds and 20,000 per day, based on observed API response headers. Concurrent clients or other applications using the same credentials can consume the same server quota. A 429 response delays subsequent requests according to `Retry-After` (seconds or an HTTP date). Transport errors and server errors use exponential backoff. A request has at most four attempts, and reauthentication after a 401 is attempted once. The HTTP timeout is 60 seconds.
+
+No third-party MakeLeaps client is used. Tests replace the HTTP boundary with synthetic responses and never contact MakeLeaps:
+
+```sh
+uv run --python 3.12 pytest
+uv run --python 3.13 pytest
+uv build
+```

makeleaps_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+makeleaps_client/__init__.py,sha256=tEXCFRVSk9q0pLXyHCrIDjcznAwY0yN9ewZ5aMQs5rI,335
+makeleaps_client/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+makeleaps_client/cli.py,sha256=ZflqR6Qh3405smU-Jrs5fDxepmVpQSZd2Urxh8xkOaE,7402
+makeleaps_client/client.py,sha256=jYARod8QSqqSoqz-I-Xd-ARl4Tzz0a4FIgNWZsmUabE,15153
+makeleaps_client/models.py,sha256=BAKHhNUl32vo2EZ6OON1cGNcvLq4IlwXZ0P7eEQShoI,8309
+makeleaps_client-0.1.0.dist-info/METADATA,sha256=4URX4X1xN6Syo19W7imE14TXhTujn5cYkRUY60QdL8g,8141
+makeleaps_client-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+makeleaps_client-0.1.0.dist-info/entry_points.txt,sha256=-wBUhyc9PZ2hWTBhdpxEM-geTg772dK_rrLCcdgcZJk,56
+makeleaps_client-0.1.0.dist-info/licenses/LICENSE,sha256=C3kcuSn77D1YmBPwywbEXaYrjkyWWcMvubpMt-2bi3Y,1064
+makeleaps_client-0.1.0.dist-info/RECORD,,

makeleaps_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

makeleaps_client-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+makeleaps = makeleaps_client.cli:main

makeleaps_client-0.1.0.dist-info/licenses/LICENSE

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