fancy-google-docs 0.4.0__tar.gz → 0.6.0__tar.gz

{fancy_google_docs-0.4.0 → fancy_google_docs-0.6.0}/CHANGELOG.md

@@ -8,6 +8,52 @@ The four packages share one version, because they are generated from one
 `provider/` definition and a version that meant something different in each
 would be a version nobody could reason about.
 
+## [0.6.0] — 2026-11-08
+
+### Added
+
+- **One Google consent grant, shared by every Google connector** (`oauth.grant:
+  "google"`), for an org-level Google connection: one OAuth client, one consent
+  and one refresh token per person, with each feature's scopes asked for when it
+  is first used. Declared in the manifest, the `-ui` package's OAuth constant,
+  the README and the registry index:
+  - `authorizeParams`: `access_type=offline` and `include_granted_scopes=true`.
+    A refresh token comes back only on the FIRST code exchange, so keep the stored
+    one when an exchange returns none.
+  - `revoke`: POST `https://oauth2.googleapis.com/revoke` with `token`, and
+    `scope: "grant"`. **Revoking removes the person's WHOLE Google grant, every
+    Google connector**, so a per-feature disconnect stops using that feature's
+    scopes locally and only a full Google disconnect revokes.
+  - `identity`: identify the account by the id_token's `sub` (request `openid`;
+    issuer `https://accounts.google.com` or `accounts.google.com`; audience is
+    the `clientId`), never by email, which Google says is neither unique nor
+    permanent.
+  `restrictedScopes` is empty: none of this connector's scopes is restricted.
+
+  Nothing a request sends has changed; this is what a host needs to run the
+  connection.
+
+## [0.5.0] — 2026-11-08
+
+### Added
+
+- **Laravel integration, in this package** (`src/Laravel/`), auto-discovered
+  through composer's `extra.laravel`. Laravel is SUGGESTED, never required:
+  outside a Laravel app none of it loads.
+  - a service provider that merges `config/google-docs.php` under
+    `connectors.google-docs` (credentials from the environment, or per call for a
+    multi-account app);
+  - the `GoogleDocs` facade: `GoogleDocs::call('<operation>', [...])` runs any action;
+  - `GoogleDocs::fake()`, answered from the connector's faker, with
+    `assertSent` / `assertNotSent` / `assertNothingSent` / `assertSentCount`;
+  - its own Pest test of all of it against a booted Laravel app.
+
+### Changed
+
+- **Tests: Pest `^5`**, and `laravel/framework` `^13` as a DEV-ONLY test
+  dependency (the framework this package integrates with; nothing ships in
+  `require`).
+
 ## [0.4.0] — 2026-10-01
 
 ### Added

{fancy_google_docs-0.4.0 → fancy_google_docs-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fancy-google-docs
-Version: 0.4.0
+Version: 0.6.0
 Summary: Google Docs for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK.
 Project-URL: Homepage, https://github.com/Fancy-Friends/google-docs
 Project-URL: Issues, https://github.com/Fancy-Friends/google-docs/issues
@@ -77,6 +77,13 @@ Google Docs uses OAuth2 (authorization_code). The package DECLARES the exchange;
 - **Scopes** — `https://www.googleapis.com/auth/documents`
 - **Access token lifetime** — 3600 seconds (1 hours). A host that never refreshes works all afternoon and is broken by morning.
 
+**One consent grant, shared** (`grant: "google"`). Every connector declaring the same grant can run on ONE OAuth client, with one consent and one refresh token per person.
+
+- **Authorize with** `access_type=offline`, `include_granted_scopes=true`. Ask for a feature's scopes when it is first used; the new token covers every scope granted before. A refresh token comes back only on the FIRST exchange, so keep the stored one when an exchange returns none.
+- **Revoke** — POST https://oauth2.googleapis.com/revoke with `token`. **It removes the WHOLE grant**: every connector sharing it, not only this one. A per-feature disconnect stops using that feature's scopes locally; only a full disconnect revokes.
+- **Identify the account by `sub`**: request `openid`, then verify the token response's id_token (issuer `https://accounts.google.com` or `accounts.google.com`, keys at https://www.googleapis.com/oauth2/v3/certs, audience = `clientId`). Never key a connection by email.
+- **No restricted scopes** in this connector.
+
 The refresh tokens do **not** rotate: the same one is reusable, so a refresh may safely be retried and may run concurrently. Stated rather than assumed, because the opposite — a provider that spends the token and revokes the grant on a replay — looks identical until it happens.
 
 ### The estate

{fancy_google_docs-0.4.0 → fancy_google_docs-0.6.0}/README.md

@@ -55,6 +55,13 @@ Google Docs uses OAuth2 (authorization_code). The package DECLARES the exchange;
 - **Scopes** — `https://www.googleapis.com/auth/documents`
 - **Access token lifetime** — 3600 seconds (1 hours). A host that never refreshes works all afternoon and is broken by morning.
 
+**One consent grant, shared** (`grant: "google"`). Every connector declaring the same grant can run on ONE OAuth client, with one consent and one refresh token per person.
+
+- **Authorize with** `access_type=offline`, `include_granted_scopes=true`. Ask for a feature's scopes when it is first used; the new token covers every scope granted before. A refresh token comes back only on the FIRST exchange, so keep the stored one when an exchange returns none.
+- **Revoke** — POST https://oauth2.googleapis.com/revoke with `token`. **It removes the WHOLE grant**: every connector sharing it, not only this one. A per-feature disconnect stops using that feature's scopes locally; only a full disconnect revokes.
+- **Identify the account by `sub`**: request `openid`, then verify the token response's id_token (issuer `https://accounts.google.com` or `accounts.google.com`, keys at https://www.googleapis.com/oauth2/v3/certs, audience = `clientId`). Never key a connection by email.
+- **No restricted scopes** in this connector.
+
 The refresh tokens do **not** rotate: the same one is reusable, so a refresh may safely be retried and may run concurrently. Stated rather than assumed, because the opposite — a provider that spends the token and revokes the grant on a replay — looks identical until it happens.
 
 ### The estate

{fancy_google_docs-0.4.0 → fancy_google_docs-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fancy-google-docs"
-version = "0.4.0"
+version = "0.6.0"
 description = "Google Docs for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK."
 readme = "README.md"
 # 3.11 matches fancy-flow-py's floor: 3.10 reaches end of life on 2026-10-31,

{fancy_google_docs-0.4.0 → fancy_google_docs-0.6.0}/src/fancy_google_docs/__init__.py

@@ -22,7 +22,7 @@ from .actions.text_insert import text_insert
 from .faker import respond
 from .service import BASE_URLS, CONNECTOR_API_VERSION, REQUIRES, SANDBOX, SERVICE, TITLE, descriptor
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"
 
 __all__ = [
     "BASE_URLS",

{fancy_google_docs-0.4.0 → fancy_google_docs-0.6.0}/src/fancy_google_docs/_runtime.py

@@ -319,6 +319,11 @@ def verify_hmac(
     secret_encoding: str = "utf8",  # noqa: S107 — how the secret is SPELLED, not one
     secret_prefix: str | None = None,
     id: str | None = None,
+    timestamp_unit: str = "s",
+    signs_request_line: bool = False,
+    uri: str | None = None,
+    method: str | None = None,
+    url: str | None = None,
 ) -> Verification:
     """Verify one inbound delivery.
 
@@ -366,21 +371,33 @@ def verify_hmac(
                 False, "the delivery carried no timestamp, and this scheme signs one"
             )
         try:
-            sent = int(float(timestamp))
+            sent = float(timestamp)
         except (TypeError, ValueError):
             return Verification(False, f'the delivery timestamp "{timestamp}" is not a number')
+        # Converted, never compared raw: HubSpot sends MILLISECONDS, and a
+        # millisecond value against a window in seconds refuses every delivery.
+        if timestamp_unit == "ms":
+            sent = sent / 1000
 
         current = int(time.time()) if now is None else now
         if abs(current - sent) > tolerance:
             return Verification(
                 False,
                 f"the delivery is outside the {tolerance}s replay window "
-                f"({abs(current - sent)}s old)",
+                f"({int(abs(current - sent))}s old)",
             )
 
     # A payload that signs the delivery's ID (Svix) takes it as a third argument;
     # the two-argument payloads every earlier scheme wrote are called as before.
-    signed = payload(raw, timestamp) if id is None else payload(raw, timestamp, id)
+    # HubSpot v3 signs the REQUEST LINE: refused by name without it, and the
+    # uri normalised here, once, by the scheme's rule.
+    if signs_request_line:
+        if not method or not url:
+            return Verification(False, "the delivery carried no request method or url")
+        line = {"method": method, "uri": normalise_signed_uri(url, uri) if uri else url}
+        signed = payload(raw, timestamp, id, line)
+    else:
+        signed = payload(raw, timestamp) if id is None else payload(raw, timestamp, id)
     computed = hmac.new(key, signed.encode(), digest)
     expected = computed.hexdigest() if encoding == "hex" else _b64(computed.digest())
 
@@ -392,6 +409,34 @@ def verify_hmac(
     return Verification(True)
 
 
+_HUBSPOT_V3_DECODE = {
+    "%3A": ":", "%2F": "/", "%3F": "?", "%40": "@", "%21": "!", "%24": "$",
+    "%27": "'", "%28": "(", "%29": ")", "%2A": "*", "%2C": ",", "%3B": ";",
+}
+
+
+def normalise_signed_uri(url: str, rule: str) -> str:
+    """The URI a provider signs, from the URL the request arrived on.
+
+    ``hubspot-v3``: only the QUERY portion is percent-decoded, and only for
+    twelve escapes (case-insensitive); never its leading ``?``; any
+    ``#fragment`` dropped. ``%26`` and ``%3D`` stay as sent. The twin of the
+    core's ``normaliseSignedUri``.
+    """
+    import re
+
+    if rule != "hubspot-v3":
+        raise ValueError(f"unknown signed-uri rule {rule!r}")
+    without_fragment = url.split("#", 1)[0]
+    base, sep, query = without_fragment.partition("?")
+    if not sep:
+        return without_fragment
+    decoded = re.sub(
+        r"%[0-9A-Fa-f]{2}", lambda m: _HUBSPOT_V3_DECODE.get(m.group(0).upper(), m.group(0)), query
+    )
+    return f"{base}?{decoded}"
+
+
 def _secret_key_bytes(
     secret: str,
     secret_encoding: str = "utf8",  # noqa: S107 — how the secret is SPELLED, not one