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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackos-connectors
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -124,11 +127,11 @@ through `CallOptions(provider_context={"mailbox": ...})`. Google Ads/Workspace
 service-account probes only report resolved-token presence and unverified resource
 access; they make no HTTP call or new-grant claim.
 
-Google JWT validation/signing is shared across the five declared service-account
+Google JWT validation/signing is shared across the six declared service-account
 methods. Credentials never come from ambient identity or key-supplied endpoints.
 Provider details live in `connectors/<provider>/docs/auth.md` and the catalog.
-Google Indexing retains its existing resolved-token action/probe contract; this
-release adds no Indexing JWT acquisition method.
+Google Indexing supports explicit `jwt_bearer` acquisition with the fixed Indexing
+scope. Token acquisition does not establish API enablement or site-owner access.
 
 Provider-local pure helpers cover Telegram authorization request/challenge/state
 translation (`connectors.telegram.auth`), Slack v0 HMAC verification
@@ -188,15 +191,23 @@ 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.3
 ```
 
-Or add `stackos-connectors==0.2.0` to your Python dependency requirements.
+Or add `stackos-connectors==0.2.3` 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.3 release notes
+
+- Restore Google Indexing service-account token acquisition through the canonical
+  `get_auth_contract` and `request_token` APIs. The contract fixes the Google token
+  endpoint and Indexing scope, requires a Bearer response, and rejects delegation.
+- Preserve the QuickBooks Online connector from 0.2.2 and the Search Console scope
+  handling from 0.2.1.
+
 ## Publishing
 
 The manual [publish workflow](.github/workflows/publish.yml) uses PyPI Trusted

{stackos_connectors-0.2.1 → stackos_connectors-0.2.3}/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
@@ -108,11 +111,11 @@ through `CallOptions(provider_context={"mailbox": ...})`. Google Ads/Workspace
 service-account probes only report resolved-token presence and unverified resource
 access; they make no HTTP call or new-grant claim.
 
-Google JWT validation/signing is shared across the five declared service-account
+Google JWT validation/signing is shared across the six declared service-account
 methods. Credentials never come from ambient identity or key-supplied endpoints.
 Provider details live in `connectors/<provider>/docs/auth.md` and the catalog.
-Google Indexing retains its existing resolved-token action/probe contract; this
-release adds no Indexing JWT acquisition method.
+Google Indexing supports explicit `jwt_bearer` acquisition with the fixed Indexing
+scope. Token acquisition does not establish API enablement or site-owner access.
 
 Provider-local pure helpers cover Telegram authorization request/challenge/state
 translation (`connectors.telegram.auth`), Slack v0 HMAC verification
@@ -172,15 +175,23 @@ 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.3
 ```
 
-Or add `stackos-connectors==0.2.0` to your Python dependency requirements.
+Or add `stackos-connectors==0.2.3` 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.3 release notes
+
+- Restore Google Indexing service-account token acquisition through the canonical
+  `get_auth_contract` and `request_token` APIs. The contract fixes the Google token
+  endpoint and Indexing scope, requires a Bearer response, and rejects delegation.
+- Preserve the QuickBooks Online connector from 0.2.2 and the Search Console scope
+  handling from 0.2.1.
+
 ## Publishing
 
 The manual [publish workflow](.github/workflows/publish.yml) uses PyPI Trusted

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stackos-connectors"
-version = "0.2.1"
+version = "0.2.3"
 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.3}/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.1 → stackos_connectors-0.2.3}/src/stackos_connectors/connectors/google_indexing/catalog.json

@@ -41,7 +41,20 @@
             "type": "secret"
           }
         ],
-        "description": "Use the Google service-account key to acquire an access token outside this library. Execution accepts the resolved access_token; provider resource access must be granted separately."
+        "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.",
+        "auth_type": "oauth",
+        "interactive": false
+      },
+      "evidence_source": "oauth_response",
+      "protocol": {
+        "grant_types": [
+          "jwt_bearer"
+        ],
+        "flow": "jwt_bearer",
+        "authorization_endpoint": null,
+        "pkce_mode": "unavailable",
+        "authorization_params": [],
+        "required_token_type": "Bearer"
       }
     }
   ],
@@ -221,5 +234,12 @@
     "path": "shared/icons/integration.svg",
     "media_type": "image/svg+xml",
     "kind": "fallback"
+  },
+  "auth_protocol": {
+    "flow": "jwt_bearer",
+    "token_endpoint": "https://oauth2.googleapis.com/token",
+    "scopes": [
+      "https://www.googleapis.com/auth/indexing"
+    ]
   }
 }

stackos_connectors-0.2.3/src/stackos_connectors/connectors/google_indexing/docs/auth.md

@@ -0,0 +1,30 @@
+# Google Indexing authentication
+
+The [bundled catalog](../catalog.json) is the installed contract for method fields,
+scopes, endpoints and supported grants. Read it through `describe`; use
+`get_auth_contract` for immutable protocol facts.
+
+| Saved method | Explicit token grants |
+| --- | --- |
+| `service-account` | `jwt_bearer` |
+
+Call `request_token` with resolved `service_account_json` to sign an RSA JWT and
+exchange it at `https://oauth2.googleapis.com/token`. The signed request uses only
+`https://www.googleapis.com/auth/indexing`. The shared Google key validator rejects
+alternate token endpoints and external credential sources. Delegation is not
+supported. A successful response requires a Bearer token and a positive expiry;
+omitted scope remains omitted provider evidence.
+
+Actions and `probe_credentials` accept the resolved `access_token`. Discovery,
+probes and actions never acquire or refresh credentials implicitly. The consumer
+owns key and token custody, refresh timing, permissions, persistence and audit.
+
+Token acquisition does not verify API enablement or site-owner access. The service
+account needs delegated site-owner access in Search Console. This property role
+is separate from Workspace user impersonation. Existing eligibility, quota and
+notification semantics remain in the [provider notes](google-indexing.md).
+
+Provider references retained from the reviewed catalog:
+
+- [Indexing prerequisites](https://developers.google.com/search/apis/indexing-api/v3/prereqs)
+- [Indexing API usage](https://developers.google.com/search/apis/indexing-api/v3/using-api)

{stackos_connectors-0.2.1 → stackos_connectors-0.2.3}/src/stackos_connectors/connectors/google_search_console/docs/auth.md

@@ -21,7 +21,7 @@ The full `webmasters` scope also permits read operations. Consumers can use
 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.
+Service-account token success does not establish Search Console property access. Inventory probes can succeed with no properties. Google Indexing has a separate [service-account authentication contract](../../google_indexing/docs/auth.md) and scope.
 
 `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.3/src/stackos_connectors/connectors/quickbooks_online/__init__.py

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

stackos_connectors-0.2.3/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.3/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.3/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.