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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackos-connectors
-Version: 0.2.0
+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.0 → 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.0 → stackos_connectors-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stackos-connectors"
-version = "0.2.0"
+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.0 → stackos_connectors-0.2.2}/src/stackos_connectors/auth.py

@@ -143,6 +143,17 @@ def get_auth_contract(
     return contract
 
 
+def scope_satisfies(connector: str, required: str, granted: set[str]) -> bool:
+    """Report documented scope compatibility; the consumer owns enforcement."""
+    if required in granted:
+        return True
+    if connector == "google-search-console":
+        from .connectors.google_search_console.auth import READ_SCOPE, WRITE_SCOPE
+
+        return required == READ_SCOPE and WRITE_SCOPE in granted
+    return False
+
+
 def build_authorization_request(
     connector: str,
     *,

{stackos_connectors-0.2.0 → 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/google_search_console/auth.py

@@ -0,0 +1,19 @@
+"""Search Console's explicit read and sitemap-submission OAuth scopes."""
+
+from dataclasses import replace
+
+from ...auth import OAuthTokenError
+
+READ_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly"
+WRITE_SCOPE = "https://www.googleapis.com/auth/webmasters"
+
+
+def resolve_contract(contract, config):
+    mode = config.get("access_mode", "readonly")
+    if mode not in ("readonly", "sitemap_write"):
+        raise OAuthTokenError(
+            "Search Console access mode must be readonly or sitemap_write",
+            provider_key=contract.provider_key,
+            invalid_fields=("access_mode",),
+        )
+    return replace(contract, scopes=(WRITE_SCOPE if mode == "sitemap_write" else READ_SCOPE,))

{stackos_connectors-0.2.0 → stackos_connectors-0.2.2}/src/stackos_connectors/connectors/google_search_console/catalog.json

@@ -23,7 +23,16 @@
       },
       "config_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "access_mode": {
+            "type": "string",
+            "enum": [
+              "readonly",
+              "sitemap_write"
+            ],
+            "default": "readonly"
+          }
+        },
         "required": []
       },
       "payload_format": "json",
@@ -49,6 +58,24 @@
             "required": true,
             "secret": true,
             "type": "secret"
+          },
+          {
+            "key": "access_mode",
+            "label": "Access",
+            "type": "select",
+            "secret": false,
+            "required": false,
+            "options": [
+              {
+                "value": "readonly",
+                "label": "Read only"
+              },
+              {
+                "value": "sitemap_write",
+                "label": "Read and submit sitemaps"
+              }
+            ],
+            "description": "Defaults to read only. Changing access requires acquiring a token with the selected scope."
           }
         ],
         "description": "The consumer handles Google browser consent, state and callbacks. Exchange the resulting authorization code with request_token. Execution accepts the resolved access_token; credential storage and refresh scheduling remain consumer-owned.",
@@ -80,7 +107,16 @@
       },
       "config_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "access_mode": {
+            "type": "string",
+            "enum": [
+              "readonly",
+              "sitemap_write"
+            ],
+            "default": "readonly"
+          }
+        },
         "required": []
       },
       "payload_format": "json",
@@ -96,6 +132,24 @@
             "required": true,
             "secret": true,
             "type": "secret"
+          },
+          {
+            "key": "access_mode",
+            "label": "Access",
+            "type": "select",
+            "secret": false,
+            "required": false,
+            "options": [
+              {
+                "value": "readonly",
+                "label": "Read only"
+              },
+              {
+                "value": "sitemap_write",
+                "label": "Read and submit sitemaps"
+              }
+            ],
+            "description": "Defaults to read only. Changing access requires acquiring a token with the selected scope."
           }
         ],
         "description": "Obtain a Google access token with the required provider scopes and permissions before execution.",
@@ -126,7 +180,16 @@
       },
       "config_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "access_mode": {
+            "type": "string",
+            "enum": [
+              "readonly",
+              "sitemap_write"
+            ],
+            "default": "readonly"
+          }
+        },
         "required": []
       },
       "payload_format": "json",
@@ -162,6 +225,24 @@
             "required": true,
             "secret": true,
             "type": "secret"
+          },
+          {
+            "key": "access_mode",
+            "label": "Access",
+            "type": "select",
+            "secret": false,
+            "required": false,
+            "options": [
+              {
+                "value": "readonly",
+                "label": "Read only"
+              },
+              {
+                "value": "sitemap_write",
+                "label": "Read and submit sitemaps"
+              }
+            ],
+            "description": "Defaults to read only. Changing access requires acquiring a token with the selected scope."
           }
         ],
         "description": "Exchange the Google refresh token for an access token with an explicit request_token call. Execution accepts the resolved access_token; credential storage and refresh scheduling remain consumer-owned.",
@@ -192,7 +273,16 @@
       },
       "config_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "access_mode": {
+            "type": "string",
+            "enum": [
+              "readonly",
+              "sitemap_write"
+            ],
+            "default": "readonly"
+          }
+        },
         "required": []
       },
       "payload_format": "json",
@@ -208,6 +298,24 @@
             "required": true,
             "secret": true,
             "type": "secret"
+          },
+          {
+            "key": "access_mode",
+            "label": "Access",
+            "type": "select",
+            "secret": false,
+            "required": false,
+            "options": [
+              {
+                "value": "readonly",
+                "label": "Read only"
+              },
+              {
+                "value": "sitemap_write",
+                "label": "Read and submit sitemaps"
+              }
+            ],
+            "description": "Defaults to read only. Changing access requires acquiring a token with the selected scope."
           }
         ],
         "description": "Use request_token with the Google service-account key to acquire an access token. Execution accepts the resolved access_token; provider resource access must be granted separately. Credential storage and refresh scheduling remain consumer-owned.",
@@ -778,5 +886,6 @@
         "consent"
       ]
     ]
-  }
+  },
+  "auth_implementation": "stackos_connectors.connectors.google_search_console.auth:resolve_contract"
 }

{stackos_connectors-0.2.0 → stackos_connectors-0.2.2}/src/stackos_connectors/connectors/google_search_console/docs/auth.md

@@ -9,6 +9,18 @@ The [bundled catalog](../catalog.json) is the installed contract for method fiel
 | `oauth2_refresh_token` | `refresh_token` |
 | `service-account` | `jwt_bearer` |
 
+All four methods expose `access_mode`: omitted or `readonly` requests
+`https://www.googleapis.com/auth/webmasters.readonly`; explicit `sitemap_write`
+requests `https://www.googleapis.com/auth/webmasters`. Keep the saved selection
+when renewing a service-account token. Changing it requires fresh grant evidence;
+OAuth consent must be repeated when a new scope is needed. Selecting a mode does
+not expand a manually supplied token's permissions.
+
+The full `webmasters` scope also permits read operations. Consumers can use
+`stackos_connectors.auth.scope_satisfies` to check that documented relationship
+without changing stored provider scope evidence. Read-only scope never satisfies
+a sitemap submission requirement. Property permissions remain separate.
+
 Service-account token success does not establish Search Console property access. Inventory probes can succeed with no properties. Google Indexing is a separate resolved-token contract; no new Indexing JWT grant is supplied.
 
 `request_token` receives resolved application/key fields and performs only the requested grant. Actions and `probe_credentials` receive resolved execution fields. Discovery, probes and actions never acquire or refresh implicitly. The consumer owns credential/state/PKCE custody, callbacks, refresh timing and concurrency, permissions, persistence and audit. Token results and authorization URLs are sensitive in-process values.

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}"
+    )