stackos-connectors 0.2.1__tar.gz → 0.2.2__tar.gz

{stackos_connectors-0.2.1 → stackos_connectors-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackos-connectors
-Version: 0.2.1
+Version: 0.2.2
 Summary: Named provider connectors with plain data and caller-owned authentication.
 License-Expression: MIT
 License-File: LICENSE
@@ -73,6 +73,9 @@ execution; existing names cannot be replaced.
 `CallOptions.timeout=None` preserves each provider's default. A numeric timeout
 overrides that default. A supplied HTTP client remains caller-owned.
 
+QuickBooks Online provides bounded company/invoice reads with exact invoice JSON
+fragments and explicit OAuth. See the [provider contract](src/stackos_connectors/connectors/quickbooks_online/docs/quickbooks-online.md).
+
 ## Explicit authentication
 
 `get_auth_contract(connector, method=..., config=...)` reads immutable provider
@@ -188,10 +191,10 @@ Python 3.12 or newer is required. Source:
 Published releases can be installed with:
 
 ```bash
-python -m pip install stackos-connectors==0.2.0
+python -m pip install stackos-connectors==0.2.2
 ```
 
-Or add `stackos-connectors==0.2.0` to your Python dependency requirements.
+Or add `stackos-connectors==0.2.2` to your Python dependency requirements.
 
 Install from a local checkout with `pip install /path/to/StackOSConnectors`, or
 build a wheel with `python -m build --wheel` and install that wheel. Runtime use

{stackos_connectors-0.2.1 → stackos_connectors-0.2.2}/README.md

@@ -57,6 +57,9 @@ execution; existing names cannot be replaced.
 `CallOptions.timeout=None` preserves each provider's default. A numeric timeout
 overrides that default. A supplied HTTP client remains caller-owned.
 
+QuickBooks Online provides bounded company/invoice reads with exact invoice JSON
+fragments and explicit OAuth. See the [provider contract](src/stackos_connectors/connectors/quickbooks_online/docs/quickbooks-online.md).
+
 ## Explicit authentication
 
 `get_auth_contract(connector, method=..., config=...)` reads immutable provider
@@ -172,10 +175,10 @@ Python 3.12 or newer is required. Source:
 Published releases can be installed with:
 
 ```bash
-python -m pip install stackos-connectors==0.2.0
+python -m pip install stackos-connectors==0.2.2
 ```
 
-Or add `stackos-connectors==0.2.0` to your Python dependency requirements.
+Or add `stackos-connectors==0.2.2` to your Python dependency requirements.
 
 Install from a local checkout with `pip install /path/to/StackOSConnectors`, or
 build a wheel with `python -m build --wheel` and install that wheel. Runtime use

{stackos_connectors-0.2.1 → stackos_connectors-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stackos-connectors"
-version = "0.2.1"
+version = "0.2.2"
 description = "Named provider connectors with plain data and caller-owned authentication."
 readme = "README.md"
 requires-python = ">=3.12"

{stackos_connectors-0.2.1 → stackos_connectors-0.2.2}/src/stackos_connectors/catalog/index.json

@@ -35,6 +35,7 @@
     "connectors/openrouter/catalog.json",
     "connectors/outreach/catalog.json",
     "connectors/pipedrive/catalog.json",
+    "connectors/quickbooks_online/catalog.json",
     "connectors/reddit/catalog.json",
     "connectors/reve/catalog.json",
     "connectors/salesforce/catalog.json",

stackos_connectors-0.2.2/src/stackos_connectors/connectors/quickbooks_online/__init__.py

@@ -0,0 +1 @@
+"""QuickBooks Online named reads and explicit OAuth declarations."""

stackos_connectors-0.2.2/src/stackos_connectors/connectors/quickbooks_online/actions.py

@@ -0,0 +1,110 @@
+"""The two bounded QuickBooks Online read actions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import AsyncExitStack
+from functools import partial
+
+import httpx
+
+from stackos_connectors import ConnectorRequest, ConnectorResult, ValidationIssue
+from stackos_connectors.redaction import auth_secret_values, redact_secret_values
+
+from .integration import QuickBooksIntegration
+from .response import (
+    CompanyInfo,
+    InvoicePage,
+    calendar_date,
+    invalid_response,
+    parse_company_info,
+    parse_invoice_page,
+)
+
+
+class QuickBooksActionConnector:
+    key = "quickbooks-online"
+
+    def validate(self, request: ConnectorRequest) -> list[ValidationIssue]:
+        if request.operation != "invoices.list":
+            return []
+        try:
+            first = calendar_date(request.input_json["txn_date_from"])
+            last = calendar_date(request.input_json["txn_date_to"])
+            if first > last:
+                raise ValueError("reversed dates")
+        except ValueError:
+            return [
+                ValidationIssue(path="$.txn_date_from", message="Dates must be valid and ordered")
+            ]
+        return []
+
+    def estimate_cost_cents(self, request: ConnectorRequest) -> int:
+        return 0
+
+    async def execute(self, request: ConnectorRequest) -> ConnectorResult:
+        assert request.auth is not None
+        config = request.auth.config
+        secrets = auth_secret_values(request.auth)
+        realm = config["realm_id"]
+        path, params, parser = _read_parameters(request, secrets)
+        async with AsyncExitStack() as stack:
+            http = request.options.http
+            if http is None:
+                http = await stack.enter_async_context(
+                    httpx.AsyncClient(timeout=30.0, follow_redirects=False)
+                )
+            integration = QuickBooksIntegration(
+                payload=b"",
+                http=http,
+                timeout=request.options.timeout,
+                rate_limiter=request.options.rate_limiter,
+            )
+            result = await integration.read(
+                op=request.operation,
+                environment=config["environment"],
+                realm_id=realm,
+                token=request.auth.fields["access_token"],
+                path=path,
+                params=params,
+                parser=parser,
+            )
+        if redact_secret_values(result.data, secrets) != result.data:
+            raise invalid_response()
+        return ConnectorResult(
+            output_json=result.data,
+            metadata_json={"vendor": self.key, "operation": request.operation},
+        )
+
+
+def _read_parameters(
+    request: ConnectorRequest, secrets: tuple[str, ...]
+) -> tuple[str, dict[str, str] | None, Callable[[httpx.Response], CompanyInfo | InvoicePage]]:
+    assert request.auth is not None
+    realm = request.auth.config["realm_id"]
+    if request.operation == "company-info.get":
+        return (
+            f"companyinfo/{realm}",
+            None,
+            partial(parse_company_info, secrets=secrets, realm_id=realm),
+        )
+    data = request.input_json
+    parser = partial(
+        parse_invoice_page,
+        secrets=secrets,
+        start=data["start_position"],
+        limit=data["max_results"],
+        date_from=data["txn_date_from"],
+        date_to=data["txn_date_to"],
+    )
+    query = _invoice_query(
+        data["txn_date_from"], data["txn_date_to"], data["start_position"], data["max_results"]
+    )
+    return "query", {"query": query}, parser
+
+
+def _invoice_query(date_from: str, date_to: str, start: int, limit: int) -> str:
+    return (
+        f"select * from Invoice where TxnDate >= '{date_from}' and TxnDate <= '{date_to}' "
+        f"STARTPOSITION {start} MAXRESULTS {limit}"
+    )

stackos_connectors-0.2.2/src/stackos_connectors/connectors/quickbooks_online/catalog.json

@@ -0,0 +1,309 @@
+{
+  "schema_version": "stackos.connector.v1",
+  "connector": "quickbooks-online",
+  "name": "QuickBooks Online",
+  "description": "Bounded company and invoice reads with explicit caller-owned OAuth.",
+  "auth_type": "oauth",
+  "auth_methods": [
+    {
+      "key": "oauth2_authorization_code",
+      "description": "Caller-supplied resolved OAuth bearer token; grants are always explicit.",
+      "fields_schema": {
+        "type": "object",
+        "properties": {
+          "access_token": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^\\s]+$"
+          }
+        },
+        "required": [
+          "access_token"
+        ],
+        "additionalProperties": false
+      },
+      "config_schema": {
+        "type": "object",
+        "properties": {
+          "environment": {
+            "enum": [
+              "sandbox",
+              "production"
+            ]
+          },
+          "realm_id": {
+            "type": "string",
+            "pattern": "^[0-9]{1,32}$"
+          }
+        },
+        "required": [
+          "environment",
+          "realm_id"
+        ],
+        "additionalProperties": false
+      },
+      "setup": {
+        "auth_type": "oauth",
+        "interactive": true,
+        "description": "Register an Intuit app, verify callback state and realmId, and supply its resolved accounting access token.",
+        "fields": [
+          {
+            "key": "client_id",
+            "label": "Client Id",
+            "type": "secret",
+            "secret": true,
+            "required": true
+          },
+          {
+            "key": "client_secret",
+            "label": "Client Secret",
+            "type": "secret",
+            "secret": true,
+            "required": true
+          }
+        ]
+      },
+      "evidence_source": "oauth_response",
+      "protocol": {
+        "grant_types": [
+          "authorization_code",
+          "refresh_token"
+        ]
+      }
+    },
+    {
+      "key": "oauth2_token",
+      "description": "Caller-supplied resolved OAuth bearer token; grants are always explicit.",
+      "fields_schema": {
+        "type": "object",
+        "properties": {
+          "access_token": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^\\s]+$"
+          }
+        },
+        "required": [
+          "access_token"
+        ],
+        "additionalProperties": false
+      },
+      "config_schema": {
+        "type": "object",
+        "properties": {
+          "environment": {
+            "enum": [
+              "sandbox",
+              "production"
+            ]
+          },
+          "realm_id": {
+            "type": "string",
+            "pattern": "^[0-9]{1,32}$"
+          }
+        },
+        "required": [
+          "environment",
+          "realm_id"
+        ],
+        "additionalProperties": false
+      },
+      "setup": {
+        "auth_type": "oauth",
+        "interactive": false,
+        "description": "Register an Intuit app, verify callback state and realmId, and supply its resolved accounting access token.",
+        "fields": [
+          {
+            "key": "access_token",
+            "label": "Access Token",
+            "type": "secret",
+            "secret": true,
+            "required": true
+          }
+        ]
+      },
+      "evidence_source": "unavailable",
+      "protocol": {
+        "grant_types": [
+          "refresh_token"
+        ]
+      }
+    }
+  ],
+  "auth_protocol": {
+    "flow": "authorization_code",
+    "authorization_endpoint": "https://appcenter.intuit.com/connect/oauth2",
+    "token_endpoint": "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+    "client_auth_style": "basic",
+    "pkce_mode": "unavailable",
+    "scopes": [
+      "com.intuit.quickbooks.accounting"
+    ],
+    "response_account_id_field": null
+  },
+  "actions": [
+    {
+      "key": "quickbooks-online.company-info.get",
+      "operation": "company-info.get",
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "type": "object",
+        "properties": {
+          "realm_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "company_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "company_name": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "realm_id",
+          "company_id"
+        ],
+        "additionalProperties": false
+      },
+      "auth_methods": [
+        "oauth2_authorization_code",
+        "oauth2_token"
+      ],
+      "description": "Read CompanyInfo for the configured realm. Returned realm_id repeats request context, not independent provider attestation.",
+      "guidance": "Caller owns pagination, complete-scan limits and current-state semantics. total_count is supplied metadata only; missing currency remains unknown. See provider docs.",
+      "metadata": {
+        "name": "Read company info",
+        "risk_level": "read"
+      },
+      "config": {}
+    },
+    {
+      "key": "quickbooks-online.invoices.list",
+      "operation": "invoices.list",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "txn_date_from": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+          },
+          "txn_date_to": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+          },
+          "start_position": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 2147483647
+          },
+          "max_results": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100
+          }
+        },
+        "required": [
+          "txn_date_from",
+          "txn_date_to",
+          "start_position",
+          "max_results"
+        ],
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "type": "object",
+        "properties": {
+          "invoices": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "native_id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "raw_json": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "source_revision": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "source_updated_at": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": [
+                "native_id",
+                "raw_json"
+              ],
+              "additionalProperties": false
+            },
+            "maxItems": 100
+          },
+          "start_position": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "max_results": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 100
+          },
+          "count": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 100
+          },
+          "total_count": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "required": [
+          "invoices",
+          "start_position",
+          "max_results",
+          "count"
+        ],
+        "additionalProperties": false
+      },
+      "auth_methods": [
+        "oauth2_authorization_code",
+        "oauth2_token"
+      ],
+      "description": "Read one bounded Invoice page by inclusive TxnDate, retaining exact JSON source fragments without floating-point conversion.",
+      "guidance": "Caller owns pagination, complete-scan limits and current-state semantics. total_count is supplied metadata only; missing currency remains unknown. See provider docs.",
+      "metadata": {
+        "name": "Read invoice page",
+        "risk_level": "read"
+      },
+      "config": {}
+    }
+  ],
+  "implementation": "stackos_connectors.connectors.quickbooks_online.actions:QuickBooksActionConnector",
+  "icon": {
+    "path": "shared/icons/integration.svg",
+    "kind": "icon",
+    "media_type": "image/svg+xml"
+  },
+  "setup": {
+    "homepage_url": "https://developer.intuit.com/",
+    "docs_url": "https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/invoice",
+    "docs": [
+      "connectors/quickbooks_online/docs/quickbooks-online.md",
+      "connectors/quickbooks_online/docs/auth.md"
+    ],
+    "setup_note": "The caller stores tokens and binds environment plus realm_id after verified OAuth callback state. No implicit authorization or refresh."
+  }
+}

stackos_connectors-0.2.2/src/stackos_connectors/connectors/quickbooks_online/docs/auth.md

@@ -0,0 +1,13 @@
+# QuickBooks Online authentication
+
+The [catalog](../catalog.json) owns fixed Intuit OAuth declarations. Use the public `build_authorization_request`, `request_token` and `get_auth_contract` functions. Neither read action authorizes or refreshes implicitly.
+
+- `oauth2_authorization_code`: explicit code and refresh grants. Consent requests `com.intuit.quickbooks.accounting` with caller-generated state and callback URI.
+- `oauth2_token`: resolved bearer-token reads, plus explicit refresh grants when application fields and a refresh token are supplied to `request_token`.
+- Both grant requests use HTTP Basic application authentication at `https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer`. Consent uses `https://appcenter.intuit.com/connect/oauth2`. The shared grant transport issues one token POST without automatic retries. PKCE is not declared for this provider contract.
+
+The caller owns application secrets, state verification, callback handling, binding the returned `realmId` to the intended company, token custody/expiration, refresh concurrency and permissions. Supply only resolved `access_token` in action auth fields, and `{ "environment": "sandbox", "realm_id": "123456789" }` in action auth config. The environment must be `sandbox` or `production`; endpoints cannot be overridden. Code/token grants accept application fields separately from action execution validation.
+
+An omitted token response scope remains unknown; the requested accounting scope is not evidence of an actual grant. An omitted refresh token remains absent in `TokenResult`; the caller decides whether to retain a prior value. Unknown refresh outcomes require caller reconciliation, not automatic replay. `CompanyInfo.Id` is a separate entity identifier and need not equal callback `realmId`.
+
+Primary protocol sources: [sandbox discovery](https://developer.intuit.com/.well-known/openid_sandbox_configuration/), [production discovery](https://developer.intuit.com/.well-known/openid_configuration/), [official Python OAuth client](https://github.com/intuit/oauth-pythonclient/blob/master/intuitlib/client.py), and [accounting scope](https://github.com/intuit/oauth-pythonclient/blob/master/intuitlib/enums.py). Local fixture verification does not establish live app consent or sandbox compatibility.

stackos_connectors-0.2.2/src/stackos_connectors/connectors/quickbooks_online/docs/quickbooks-online.md

@@ -0,0 +1,24 @@
+# QuickBooks Online bounded reads
+
+`get_default_client().execute` exposes exactly two actions:
+
+| Action | Inputs | Output |
+| --- | --- | --- |
+| `quickbooks-online.company-info.get` | Empty object | Configured `realm_id`, provider `company_id`, optional `company_name` |
+| `quickbooks-online.invoices.list` | `txn_date_from`, `txn_date_to`, `start_position`, `max_results` | `invoices`, `start_position`, `max_results`, `count`, optional provider `total_count` |
+
+Use `ConnectorAuth("oauth2_token", {"access_token": token}, config={"environment": "sandbox", "realm_id": realm_id})` and optional `CallOptions(http=caller_http, timeout=seconds, rate_limiter=caller_bucket)`. The caller owns an injected HTTP client; the connector closes only clients it creates. The numeric timeout overrides each HTTP request; a consumer that needs a whole-operation deadline must enforce it separately. Shared transport retries reads at most three times. Redirects are disabled even when a supplied client enables them. Numeric Retry-After is capped at 30 seconds per retry. OAuth renewal uses its separate explicit, non-retrying token transport.
+
+Invoice queries use inclusive valid calendar dates on `TxnDate` and provider-order offset pagination. The query uses `STARTPOSITION` and `MAXRESULTS`, matching the [current official PHP SDK query builder](https://github.com/intuit/QuickBooks-V3-PHP-SDK/blob/master/src/QueryFilter/QueryMessage.php). Explicit ordering is omitted because this increment does not require it and Invoice `Id` sort support was not established by primary evidence. Dates must be ordered, start position is 1-based (maximum 2147483647), and page size is 1–100. There is no arbitrary SQL, URL, write, or minor-version override. Sandbox requests use `sandbox-quickbooks.api.intuit.com`; production requests use `quickbooks.api.intuit.com`.
+
+Every invoice carries `native_id`, exact UTF-8 `raw_json`, optional `source_revision` from supplied `SyncToken` and optional `source_updated_at` from supplied offset-aware `MetaData.LastUpdatedTime`. Object text is sliced from the response, retaining whitespace, escaping, numeric precision and scale. Monetary numbers are validated with decimal decoding and are never decoded as binary floats or reserialized. Supplied totals/balances may be zero or negative. Missing currency and other optional fields remain missing; no currency is inferred. Amounts and balances describe the provider's current response, not historical balances or revenue.
+
+The provider validates the returned envelope and metadata because the public output schema is descriptive. Duplicate JSON keys anywhere, duplicate invoice IDs in a page, invalid identities/amounts/dates, invoices outside the requested dates, inconsistent positions/counts, malformed metadata, records above 16 KiB and response bodies above 2 MiB fail safely. The response-size check occurs after shared HTTP buffering. Credential echoes in raw text or decoded keys/values fail before registry redaction; evidence is never silently scrubbed and returned as exact.
+
+A missing `Invoice` array in an otherwise empty `QueryResponse` means an empty page. Empty pages may omit position/count metadata; returned position then repeats the requested position and count is zero. Nonempty pages require `startPosition` and `maxResults` matching the request and returned count. Supplied `totalCount` is retained only as a nonnegative integer; its semantics are not used for termination.
+
+The consumer owns page traversal, cross-page duplicate detection, aggregate size/count bounds, empty-scan handling, overflow detection, persistence and publication. A short page can terminate a declared traversal, but offset pagination is not a transactionally isolated snapshot. The returned `realm_id` repeats request context, not independent provider attestation. Provider faults return fixed safe error codes and status, never raw response bodies, tokens or transport exception text.
+
+Run local checks with `.venv/bin/python -B -m pytest tests/quickbooks_online tests/auth tests/catalog tests/packaging -p no:cacheprovider` and `.venv/bin/ruff check src/stackos_connectors/connectors/quickbooks_online tests/quickbooks_online`. The standalone installed-wheel driver in `tests/packaging/installed_auth_consumer.py` uses injected transports with live networking prohibited. Live Intuit consent/provider verification is a separate gate.
+
+References: [Invoice API](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/invoice), [limits and throttling](https://static.developer.intuit.com/output_html/qbo/docs/learn/limits-and-throttles.html), [authentication](auth.md).

stackos_connectors-0.2.2/src/stackos_connectors/connectors/quickbooks_online/integration.py

@@ -0,0 +1,75 @@
+"""Fixed QuickBooks read routes using the shared bounded HTTP transport."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+
+import httpx
+
+from stackos_connectors.errors import ConnectorError, IntegrationDownError, RateLimitedError
+from stackos_connectors.shared.base import BaseIntegration, IntegrationCallResult
+
+from .response import CompanyInfo, InvoicePage
+
+HOSTS = {
+    "sandbox": "https://sandbox-quickbooks.api.intuit.com",
+    "production": "https://quickbooks.api.intuit.com",
+}
+
+
+class QuickBooksIntegration(BaseIntegration):
+    kind = vendor = "quickbooks-online"
+
+    @classmethod
+    def _provider_error(cls, response: httpx.Response) -> dict[str, str]:
+        # Never decode/retain arbitrary provider bodies in diagnostics.
+        return {"reason_code": _reason(response.status_code)}
+
+    @staticmethod
+    def _parse_retry_after(response: httpx.Response) -> float | None:
+        value = BaseIntegration._parse_retry_after(response)
+        return (
+            min(value, 30.0) if value is not None and math.isfinite(value) and value >= 0 else None
+        )
+
+    async def read(
+        self,
+        *,
+        op: str,
+        environment: str,
+        realm_id: str,
+        token: str,
+        path: str,
+        parser: Callable[[httpx.Response], CompanyInfo | InvoicePage],
+        params: dict[str, str] | None = None,
+    ) -> IntegrationCallResult:
+        try:
+            return await self.call(
+                op=op,
+                method="GET",
+                url=f"{HOSTS[environment]}/v3/company/{realm_id}/{path}",
+                headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
+                params=params,
+                response_parser=parser,
+            )
+        except (IntegrationDownError, RateLimitedError) as exc:
+            status = exc.data.get("status")
+            status = status if type(status) is int else None
+            raise ConnectorError(
+                "QuickBooks read failed",
+                provider_status_code=status,
+                provider_error={"reason_code": _reason(status)},
+            ) from None
+
+
+def _reason(status: int | None) -> str:
+    if status == 401:
+        return "authentication_failed"
+    if status == 403:
+        return "permission_denied"
+    if status == 429:
+        return "rate_limited"
+    if status is not None and status >= 500:
+        return "provider_unavailable"
+    return "provider_failure" if status is not None else "network_error"