stackos-connectors 0.2.3__tar.gz → 0.2.4__tar.gz

{stackos_connectors-0.2.3 → stackos_connectors-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackos-connectors
-Version: 0.2.3
+Version: 0.2.4
 Summary: Named provider connectors with plain data and caller-owned authentication.
 License-Expression: MIT
 License-File: LICENSE
@@ -191,15 +191,24 @@ Python 3.12 or newer is required. Source:
 Published releases can be installed with:
 
 ```bash
-python -m pip install stackos-connectors==0.2.3
+python -m pip install stackos-connectors==0.2.4
 ```
 
-Or add `stackos-connectors==0.2.3` to your Python dependency requirements.
+Or add `stackos-connectors==0.2.4` 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
 needs only the installed package and its declared dependencies.
 
+### 0.2.4 release notes
+
+- Complete QuickBooks setup metadata with method labels and explicit required
+  environment and company realm fields.
+- Add a credential probe through the existing validated CompanyInfo read. It
+  returns bounded company identity and leaves OAuth grant evidence unknown.
+- Preserve the two QuickBooks read actions and Google Indexing authentication
+  support from 0.2.3.
+
 ### 0.2.3 release notes
 
 - Restore Google Indexing service-account token acquisition through the canonical

{stackos_connectors-0.2.3 → stackos_connectors-0.2.4}/README.md

@@ -175,15 +175,24 @@ Python 3.12 or newer is required. Source:
 Published releases can be installed with:
 
 ```bash
-python -m pip install stackos-connectors==0.2.3
+python -m pip install stackos-connectors==0.2.4
 ```
 
-Or add `stackos-connectors==0.2.3` to your Python dependency requirements.
+Or add `stackos-connectors==0.2.4` 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
 needs only the installed package and its declared dependencies.
 
+### 0.2.4 release notes
+
+- Complete QuickBooks setup metadata with method labels and explicit required
+  environment and company realm fields.
+- Add a credential probe through the existing validated CompanyInfo read. It
+  returns bounded company identity and leaves OAuth grant evidence unknown.
+- Preserve the two QuickBooks read actions and Google Indexing authentication
+  support from 0.2.3.
+
 ### 0.2.3 release notes
 
 - Restore Google Indexing service-account token acquisition through the canonical

{stackos_connectors-0.2.3 → stackos_connectors-0.2.4}/pyproject.toml

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

{stackos_connectors-0.2.3 → stackos_connectors-0.2.4}/src/stackos_connectors/connectors/quickbooks_online/catalog.json

@@ -4,6 +4,7 @@
   "name": "QuickBooks Online",
   "description": "Bounded company and invoice reads with explicit caller-owned OAuth.",
   "auth_type": "oauth",
+  "probe_implementation": "stackos_connectors.connectors.quickbooks_online.probe:probe",
   "auth_methods": [
     {
       "key": "oauth2_authorization_code",
@@ -26,6 +27,7 @@
         "type": "object",
         "properties": {
           "environment": {
+            "type": "string",
             "enum": [
               "sandbox",
               "production"
@@ -43,6 +45,7 @@
         "additionalProperties": false
       },
       "setup": {
+        "label": "Connect with QuickBooks",
         "auth_type": "oauth",
         "interactive": true,
         "description": "Register an Intuit app, verify callback state and realmId, and supply its resolved accounting access token.",
@@ -60,6 +63,26 @@
             "type": "secret",
             "secret": true,
             "required": true
+          },
+          {
+            "key": "environment",
+            "label": "Environment",
+            "type": "select",
+            "secret": false,
+            "required": true,
+            "options": [
+              {"value": "sandbox", "label": "Sandbox"},
+              {"value": "production", "label": "Production"}
+            ],
+            "description": "Choose the intended QuickBooks environment explicitly; there is no default."
+          },
+          {
+            "key": "realm_id",
+            "label": "Company realm ID",
+            "type": "text",
+            "secret": false,
+            "required": true,
+            "description": "Numeric company realm ID, 1–32 digits. Bind it to the intended company and verify callback realmId before token exchange."
           }
         ]
       },
@@ -92,6 +115,7 @@
         "type": "object",
         "properties": {
           "environment": {
+            "type": "string",
             "enum": [
               "sandbox",
               "production"
@@ -109,6 +133,7 @@
         "additionalProperties": false
       },
       "setup": {
+        "label": "OAuth2 access token",
         "auth_type": "oauth",
         "interactive": false,
         "description": "Register an Intuit app, verify callback state and realmId, and supply its resolved accounting access token.",
@@ -119,6 +144,26 @@
             "type": "secret",
             "secret": true,
             "required": true
+          },
+          {
+            "key": "environment",
+            "label": "Environment",
+            "type": "select",
+            "secret": false,
+            "required": true,
+            "options": [
+              {"value": "sandbox", "label": "Sandbox"},
+              {"value": "production", "label": "Production"}
+            ],
+            "description": "Choose the intended QuickBooks environment explicitly; there is no default."
+          },
+          {
+            "key": "realm_id",
+            "label": "Company realm ID",
+            "type": "text",
+            "secret": false,
+            "required": true,
+            "description": "Numeric company realm ID, 1–32 digits. Supply the company realm bound to this access token."
           }
         ]
       },

{stackos_connectors-0.2.3 → stackos_connectors-0.2.4}/src/stackos_connectors/connectors/quickbooks_online/docs/auth.md

@@ -10,4 +10,16 @@ The caller owns application secrets, state verification, callback handling, bind
 
 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`.
 
+Both method setup forms require an explicit environment and numeric company realm
+ID of 1–32 digits. Neither field has a default. The caller validates the intended
+realm against the OAuth callback before exchanging a code.
+
+`probe_credentials` reuses `quickbooks-online.company-info.get` with the resolved
+token and configured realm. It returns optional company display name and metadata
+containing provider-returned `company_id`, caller-configured `configured_realm_id`
+and `environment`. `provider_account_id` remains null because the returned entity
+ID is not realm attestation. No grants or scopes are inferred from a successful
+CompanyInfo read. Malformed responses and credential echoes fail through the same
+validator as the action; provider failures expose only safe status/reason facts.
+
 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.3 → stackos_connectors-0.2.4}/src/stackos_connectors/connectors/quickbooks_online/docs/quickbooks-online.md

@@ -19,6 +19,11 @@ A missing `Invoice` array in an otherwise empty `QueryResponse` means an empty p
 
 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.
 
+The explicit credential probe calls the existing CompanyInfo action and shares
+its validation, transport, retry bounds and redaction. It reports only safe company
+identity, keeps configured realm context distinct from `CompanyInfo.Id`, and does
+not establish OAuth scope grants. See [authentication](auth.md) for its result.
+
 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.4/src/stackos_connectors/connectors/quickbooks_online/probe.py

@@ -0,0 +1,62 @@
+"""Company identity probe using the existing validated QuickBooks read action."""
+
+from typing import Any
+
+from stackos_connectors import CallOptions, ConnectorAuth, get_default_client
+from stackos_connectors.errors import ConnectorError, IntegrationDownError, RateLimitedError
+from stackos_connectors.probe import AuthMethodProbeContext
+
+_SAFE_ERROR_REASONS = frozenset(
+    {
+        "invalid_response",
+        "authentication_failed",
+        "permission_denied",
+        "rate_limited",
+        "provider_unavailable",
+        "provider_failure",
+        "network_error",
+    }
+)
+
+
+async def probe(
+    *, auth: ConnectorAuth, options: CallOptions, context: AuthMethodProbeContext
+) -> dict[str, Any]:
+    try:
+        result = await get_default_client().execute(
+            "quickbooks-online", "quickbooks-online.company-info.get", {}, auth, options
+        )
+    except ConnectorError as exc:
+        data: dict[str, Any] = {"stage": "test", "reason_code": "probe_error"}
+        reason = (
+            exc.provider_error.get("reason_code") if isinstance(exc.provider_error, dict) else None
+        )
+        if isinstance(reason, str) and reason in _SAFE_ERROR_REASONS:
+            data["reason_code"] = reason
+        status = exc.provider_status_code
+        if type(status) is int and 100 <= status <= 599:
+            data["status"] = status
+        error_type = RateLimitedError if status == 429 else IntegrationDownError
+        raise error_type("QuickBooks CompanyInfo probe failed.", data=data) from None
+
+    company = result.output_json
+    return {
+        "ok": True,
+        "vendor": "quickbooks-online",
+        "status": "ok",
+        "summary": "QuickBooks CompanyInfo read succeeded for the configured realm.",
+        "metadata": {
+            "evidence": {
+                "account": {
+                    # CompanyInfo.Id is an entity id, not the account's realm id.
+                    "provider_account_id": None,
+                    "display_name": company.get("company_name"),
+                    "metadata": {
+                        "company_id": company["company_id"],
+                        "configured_realm_id": company["realm_id"],
+                        "environment": auth.config["environment"],
+                    },
+                }
+            }
+        },
+    }

{stackos_connectors-0.2.3 → stackos_connectors-0.2.4}/tests/auth/test_probes.py

@@ -385,5 +385,5 @@ def test_probe_bindings_are_fixed_and_metadata_discovery_does_not_probe(monkeypa
         for key, metadata in get_default_client().registry.connector_metadata.items()
         if metadata.get("probe_implementation")
     }
-    assert len(bound) == 37
+    assert len(bound) == 38
     assert all(project_probe_config(key, {}) == {} for key in bound)

{stackos_connectors-0.2.3 → stackos_connectors-0.2.4}/tests/packaging/installed_auth_consumer.py

@@ -58,6 +58,12 @@ ACCESS = "driver-access-canary"
 
 async def quickbooks_reads(client):
     """Exercise the installed QBO action factory through the public API."""
+    description = client.describe("quickbooks-online")
+    assert len(description["actions"]) == 2
+    for method in description["auth_methods"]:
+        assert method["setup"]["label"]
+        setup_fields = {field["key"]: field for field in method["setup"]["fields"]}
+        assert setup_fields["environment"]["required"] and setup_fields["realm_id"]["required"]
     raw = '{ "Id":"7", "TxnDate":"2026-01-31", "TotalAmt":9007199254740993.0100, "Balance":-0.001 }'
     calls = []
 
@@ -110,8 +116,21 @@ async def quickbooks_reads(client):
         )
         assert page.output_json["invoices"] == [{"native_id": "7", "raw_json": raw}]
         assert page.output_json["count"] == 1
+        probe = await probe_credentials("quickbooks-online", auth=auth, options=options)
+        assert probe["ok"]
+        assert probe["metadata"]["evidence"] == {
+            "account": {
+                "provider_account_id": None,
+                "display_name": "Synthetic",
+                "metadata": {
+                    "company_id": "1",
+                    "configured_realm_id": "123456789",
+                    "environment": "sandbox",
+                },
+            }
+        }
         assert not http.is_closed
-    assert len(calls) == 2
+    assert len(calls) == 3
 
 
 async def main():
@@ -202,7 +221,6 @@ async def main():
         assert result.access_token == ACCESS and result.scopes_present
         assert ACCESS not in repr(result) and SECRET not in repr(auth)
     assert len(grant_calls) == 17  # Meta explicitly performs its second exchange.
-    await quickbooks_reads(client)
 
     async with httpx.AsyncClient(
         transport=httpx.MockTransport(
@@ -302,6 +320,7 @@ async def main():
 
     auth_api.request_token = implicit_grant
     oauth_protocol.request_token = implicit_grant
+    await quickbooks_reads(client)
     client.describe("google-workspace")
     config = project_probe_config(
         "wordpress", {"site_url": "https://fixture.test", "account_ref": "private"}
@@ -396,6 +415,7 @@ async def main():
                     "slack_v0",
                     "hubspot_v3",
                     "quickbooks_exact_reads",
+                    "quickbooks_company_probe",
                 ],
                 "network": "blocked; injected edges only",
                 "origins": origins,

stackos_connectors-0.2.4/tests/quickbooks_online/test_probe.py

@@ -0,0 +1,207 @@
+import json
+import socket
+
+import httpx
+import pytest
+
+from stackos_connectors import CallOptions, ConnectorAuth, get_default_client, probe_credentials
+from stackos_connectors.errors import ConnectorError, IntegrationDownError, ValidationError
+from stackos_connectors.probe import AuthProbeEvidence, project_probe_config
+
+PROVIDER = "quickbooks-online"
+TOKEN = "qbo-probe-access-canary"
+CONFIG = {"environment": "sandbox", "realm_id": "123456789"}
+
+
+@pytest.fixture(autouse=True)
+def no_implicit_grant_or_network(monkeypatch):
+    def forbidden(*args, **kwargs):
+        raise AssertionError("probe must use the supplied token and injected HTTP transport")
+
+    monkeypatch.setattr(socket.socket, "connect", forbidden)
+    monkeypatch.setattr(socket, "getaddrinfo", forbidden)
+    monkeypatch.setattr("stackos_connectors.auth.request_token", forbidden)
+    monkeypatch.setattr("stackos_connectors.shared.oauth.request_token", forbidden)
+
+
+@pytest.mark.parametrize("method", ["oauth2_authorization_code", "oauth2_token"])
+def test_setup_declares_required_explicit_company_context(method):
+    description = get_default_client().describe(PROVIDER)
+    declaration = next(item for item in description["auth_methods"] if item["key"] == method)
+    setup = declaration["setup"]
+    assert setup["label"]
+    fields = {field["key"]: field for field in setup["fields"]}
+    environment, realm = fields["environment"], fields["realm_id"]
+    assert environment["type"] == "select" and environment["required"]
+    assert not environment["secret"]
+    assert {option["value"] for option in environment["options"]} == {"sandbox", "production"}
+    assert realm["type"] == "text" and realm["required"] and not realm["secret"]
+    assert "numeric" in realm["description"].lower()
+    schema = declaration["config_schema"]
+    assert schema["required"] == ["environment", "realm_id"]
+    assert schema["properties"]["realm_id"]["pattern"] == "^[0-9]{1,32}$"
+    assert "default" not in schema["properties"]["environment"]
+    assert "default" not in environment and not setup.get("config")
+    assert project_probe_config(PROVIDER, {**CONFIG, "account_ref": "private-host-ref"}) == CONFIG
+
+
+@pytest.mark.parametrize("method", ["oauth2_authorization_code", "oauth2_token"])
+@pytest.mark.parametrize(
+    "environment,host",
+    [("sandbox", "sandbox-quickbooks.api.intuit.com"), ("production", "quickbooks.api.intuit.com")],
+)
+async def test_probe_uses_company_read_and_preserves_distinct_identity(method, environment, host):
+    calls = []
+
+    class Limiter:
+        count = 0
+
+        async def acquire(self, n=1):
+            self.count += 1
+
+    limiter = Limiter()
+
+    def handle(request):
+        calls.append(request)
+        assert request.method == "GET"
+        assert str(request.url) == f"https://{host}/v3/company/123456789/companyinfo/123456789"
+        assert request.headers["authorization"] == f"Bearer {TOKEN}"
+        assert request.extensions["timeout"]["read"] == 0.5
+        return httpx.Response(
+            200,
+            json={"CompanyInfo": {"Id": "1", "CompanyName": "Example", "Email": "private"}},
+        )
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handle)) as http:
+        result = await probe_credentials(
+            PROVIDER,
+            auth=ConnectorAuth(
+                method, {"access_token": TOKEN}, {**CONFIG, "environment": environment}
+            ),
+            options=CallOptions(http=http, timeout=0.5, rate_limiter=limiter),
+        )
+        assert not http.is_closed
+    assert result["ok"] and result["vendor"] == PROVIDER and result["status"] == "ok"
+    evidence = result["metadata"]["evidence"]
+    assert evidence == {
+        "account": {
+            "provider_account_id": None,
+            "display_name": "Example",
+            "metadata": {
+                "company_id": "1",
+                "configured_realm_id": "123456789",
+                "environment": environment,
+            },
+        }
+    }
+    assert AuthProbeEvidence.model_validate(evidence).grants is None
+    assert TOKEN not in json.dumps(result) and "private" not in json.dumps(result)
+    assert len(calls) == 1 and limiter.count == 1
+
+
+async def test_probe_optional_company_name_does_not_gain_scope_evidence():
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(
+            lambda r: httpx.Response(200, json={"CompanyInfo": {"Id": "1"}})
+        )
+    ) as http:
+        result = await probe_credentials(
+            PROVIDER,
+            auth=ConnectorAuth("oauth2_token", {"access_token": TOKEN}, CONFIG),
+            options=CallOptions(http=http),
+        )
+    evidence = result["metadata"]["evidence"]
+    assert evidence["account"]["display_name"] is None
+    assert "grants" not in evidence and "scope" not in json.dumps(result)
+
+
+@pytest.mark.parametrize(
+    "config",
+    [
+        {},
+        {"realm_id": "123"},
+        {"environment": "sandbox"},
+        {**CONFIG, "environment": "unknown"},
+        {**CONFIG, "realm_id": "../123"},
+        {**CONFIG, "realm_id": 123},
+    ],
+)
+async def test_probe_rejects_missing_or_invalid_context_before_io(config):
+    with pytest.raises(ValidationError, match="inputs are invalid"):
+        await probe_credentials(
+            PROVIDER, auth=ConnectorAuth("oauth2_token", {"access_token": TOKEN}, config)
+        )
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        b"not json",
+        b"{}",
+        b'{"CompanyInfo":{"Id":1}}',
+        b'{"CompanyInfo":{"Id":"1","Id":"2"}}',
+        b'{"CompanyInfo":{"Id":"1","CompanyName":""}}',
+        json.dumps({"CompanyInfo": {"Id": "1", "CompanyName": TOKEN}}).encode(),
+        json.dumps({"CompanyInfo": {"Id": "1", "private": TOKEN}}).encode(),
+    ],
+)
+async def test_probe_reuses_malformed_and_credential_echo_rejection(body):
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(lambda r: httpx.Response(200, content=body))
+    ) as http:
+        with pytest.raises(IntegrationDownError) as caught:
+            await probe_credentials(
+                PROVIDER,
+                auth=ConnectorAuth("oauth2_token", {"access_token": TOKEN}, CONFIG),
+                options=CallOptions(http=http),
+            )
+    assert caught.value.data == {"stage": "test", "reason_code": "invalid_response"}
+    assert TOKEN not in str(caught.value.__dict__)
+    assert caught.value.__cause__ is None
+
+
+@pytest.mark.parametrize(
+    "status,reason",
+    [
+        (401, "authentication_failed"),
+        (403, "permission_denied"),
+        (429, "rate_limited"),
+        (503, "provider_unavailable"),
+    ],
+)
+async def test_probe_preserves_safe_provider_error_without_body(status, reason):
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(
+            lambda r: httpx.Response(
+                status,
+                json={"Fault": {"Error": [{"Message": f"private-body {TOKEN}"}]}},
+                headers={"Retry-After": "0.001"},
+            )
+        )
+    ) as http:
+        with pytest.raises(IntegrationDownError) as caught:
+            await probe_credentials(
+                PROVIDER,
+                auth=ConnectorAuth("oauth2_token", {"access_token": TOKEN}, CONFIG),
+                options=CallOptions(http=http),
+            )
+    assert caught.value.data == {"stage": "test", "status": status, "reason_code": reason}
+    assert TOKEN not in str(caught.value.__dict__) and "private-body" not in str(
+        caught.value.__dict__
+    )
+
+
+async def test_probe_never_returns_unreviewed_exception_details(monkeypatch):
+    async def fail(*args, **kwargs):
+        raise ConnectorError(
+            f"unsafe-detail {TOKEN}",
+            provider_error={"reason_code": "unsafe-reason", "body": f"unsafe-body {TOKEN}"},
+        )
+
+    monkeypatch.setattr(get_default_client(), "execute", fail)
+    with pytest.raises(IntegrationDownError) as caught:
+        await probe_credentials(
+            PROVIDER, auth=ConnectorAuth("oauth2_token", {"access_token": TOKEN}, CONFIG)
+        )
+    assert caught.value.data == {"stage": "test", "reason_code": "probe_error"}
+    assert "unsafe" not in str(caught.value.__dict__) and TOKEN not in str(caught.value.__dict__)