Skip to content

fix: make Sheets formulas quota-resilient #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
karlwaldman merged 2 commits into from
Aug 11, 2026
Merged

fix: make Sheets formulas quota-resilient #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8add8a4
fix: make Sheets formulas quota-resilient
karlwaldman Aug 11, 2026
72cc87a
fix: degrade cleanly when Apps Script services fail
karlwaldman Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
753 changes: 620 additions & 133 deletions Code.gs
View file
Open in desktop

Large diffs are not rendered by default.

46 changes: 23 additions & 23 deletions DEPLOYMENT_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ test installation, screenshots, and submission require the publisher account.

## Current release gate

- Runtime version: `1.2.2`
- Public runtime version: `1.2.2`
- Repository release candidate: `1.3.0`
- Production Apps Script ID:
`1rlVWvciYu-wzqnY009I3oW-08ZPazYK1snrrMg9NNY7c5WBSkUK8W2Hb`
- Current immutable Apps Script version: `11` (runtime `1.2.2`, cut
Expand All @@ -17,21 +18,19 @@ test installation, screenshots, and submission require the publisher account.
`https://github.com/OilpriceAPI/google-sheets-addin/actions/workflows/apps-script-release.yml`
Note: versions 9-11 were cut locally with `npm run deploy:version`, not by
this workflow, whose only run to date is 2026-07-24.
- Marketplace status: **version 9 draft submitted for review**. Version 9 was
cut 2026-07-28 16:53 EDT and therefore predates BOTH PR #19 (OAuth
verification prep) and PR #22 (custom-function credential fix). **Version 11
is the release candidate — repin App Configuration from 9 to 11 before
publishing.** Nothing has ever been published; there is no live listing.
- Marketplace status: **published** at
`https://workspace.google.com/marketplace/app/oilpriceapi_for_google_sheets/991152473434`.
The public listing points to immutable Apps Script version 11 (`1.2.2`).
Do not select the `1.3.0` candidate until its exact immutable version passes
an installed Marketplace formula smoke.
- Runtime push/version and local deployment checks: complete
- Marketplace review receipt and a real 1280x800 screenshot: complete
- Public homepage, privacy policy, and terms deployment: complete
- Separate OAuth verification dependency: confirm Search Console ownership,
record the end-to-end authorization demo, submit branding and data-access
verification, and preserve the confirmation receipt
- Canonical remaining-work issue:
`https://github.com/OilpriceAPI/google-sheets-addin/issues/20`
- OAuth verification was submitted July 30, 2026 with reviewer video
`https://youtu.be/FakNSmBddhE`.

Do not claim Marketplace availability until Google publishes the listing.
Do not claim that a new runtime is public until App Configuration selects its
smoke-proven immutable version.

## 1. Choose the publisher and Cloud project

Expand Down Expand Up @@ -192,7 +191,7 @@ screenshots until they have been reviewed for secrets and customer data.
After the smoke passes against the exact pushed source:

```bash
npm run deploy:version -- "OilPriceAPI for Google Sheets 1.2.2"
npm run deploy:version -- "OilPriceAPI for Google Sheets 1.3.0 customer-path recovery"
npm run deploy:list
```

Expand Down Expand Up @@ -250,21 +249,22 @@ Verify locally before upload:
npm run verify:assets
```

Save the listing as a draft while OAuth verification or screenshot review is
pending.
For a copy update, save a draft and preserve the existing public version until
the replacement is approved and smoke-tested.

## 11. Submit and post-publication smoke

1. Submit OAuth verification if required.
2. Submit the public Marketplace listing for review.
3. Track the Marketplace SDK publication status and review email sent to
`support@oilpriceapi.com`.
4. After approval, install the public listing using a separate clean account.
5. Repeat the customer-critical smoke against the published version.
1. Push the exact reviewed release and create an immutable Apps Script version.
2. Install that version with a non-customer test account before changing the
public Marketplace configuration.
3. Run key save/test, `OILPRICE_PRICE`, `OILPRICE_TABLE`, quota recovery, and
key deletion checks.
4. Select the proven version in Marketplace App Configuration.
5. Repeat the customer-critical smoke through the public listing.
6. Review Apps Script execution logs for new errors, retries, unexpected
authorization failures, and noisy request patterns.
7. Only then update public marketing copy to say the add-on is available from
the Google Workspace Marketplace and add the real listing URL.
7. Record the exact version, account type, formulas, timestamps, and redacted
screenshots in the release issue.

## Updating an approved release

Expand Down
54 changes: 22 additions & 32 deletions MARKETPLACE_LISTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,12 @@
# Google Workspace Marketplace Listing

Status: the Marketplace Store Listing draft was resubmitted July 29, 2026 and
remains in Google review. That draft references Apps Script version 9, which
predates both PR #19 (OAuth verification prep) and PR #22 (custom-function
credential fix).
Status: **publicly available** at
`https://workspace.google.com/marketplace/app/oilpriceapi_for_google_sheets/991152473434`.

**Version 11 (runtime `1.2.2`) is the release candidate** and should replace
version 9 in App Configuration before publishing. App Configuration is
editable during review — only the Store Listing tab locks (verified
2026-07-31; see `OAUTH_VERIFICATION.md`), so this repin does not have to wait
for Google.

OAuth branding and data-access verification have not yet been submitted.
Do not claim Marketplace availability until Google approves and publishes the
listing.
Public Marketplace Apps Script version: `11` (runtime `1.2.2`). Runtime
`1.3.0` remains a release candidate until an immutable Apps Script version is
cut, smoke-tested through an installed Marketplace add-on, and selected in App
Configuration.

## App details

Expand All @@ -35,7 +28,7 @@ Detailed description:
> request the latest available value, its currency and unit, source timestamp,
> freshness state, or an allowlisted API table.
>
> Core formulas include OILPRICE_PRICE, OILPRICE_INFO, OILPRICE_STATUS,
> Core formulas include OILPRICE_PRICE, OILPRICE_TABLE, OILPRICE_INFO, OILPRICE_STATUS,
> OILPRICE_UNIT, OILPRICE_CODES, and OILPRICE_GET. Existing OILPRICE,
> OILPRICE_HISTORY, futures, bunker-price, rig-count, and reference conversion
> formulas remain available.
Expand Down Expand Up @@ -80,41 +73,38 @@ The submitted OAuth/Marketplace configuration also displays Google's mandatory
`userinfo.email` and `userinfo.profile` defaults. The add-on does not use those
identity defaults for product behavior and does not request Drive-wide access.

## Submission receipt
## Current publication receipt

- Google Cloud project: `oilpriceapi-sheets-addon` (`991152473434`)
- Marketplace draft Apps Script version: `9` (stale - repin to `11`)
- Public listing:
`https://workspace.google.com/marketplace/app/oilpriceapi_for_google_sheets/991152473434`
- Public Marketplace Apps Script version: `11`
- Latest immutable Apps Script version: `11`
- Runtime release represented by version 11: `1.2.2`
- Superseded: version 10 (`1.2.1`), cut before the PR #22 credential fix
- Integration: Google Sheets Editor add-on
- Install modes: individual and administrator
- Regions: all regions
- Review state: **In review — resubmitted July 29, 2026**
- Review state: **Published — independently verified August 10, 2026**
- Rejection email received: **July 27, 2026**
- Google Cloud receipt: **“The draft is in review and can't be edited.”**
- Historical Google Cloud receipt: **“The draft is in review and can't be edited.”**
- Verification-page production deployment:
`https://github.com/OilpriceAPI/website-clean/actions/runs/30434284989`
- OAuth submission state: **not submitted**
- Canonical remaining-work issue:
`https://github.com/OilpriceAPI/google-sheets-addin/issues/20`
- OAuth verification was submitted July 30, 2026 with the reviewer-accessible
demonstration `https://youtu.be/FakNSmBddhE`; the later public listing is the
customer-visible approval evidence.

The OAuth consent screen is **In production**. The manifest and prepared
submission use the three functional scopes above; the locked Marketplace draft
uses the same scopes. Google's default `userinfo.email` and
The OAuth consent screen is **In production**. The manifest and published
submission use the three functional scopes above. Google's default `userinfo.email` and
`userinfo.profile` scopes remain in place. The public homepage, privacy policy,
and terms were corrected and deployed from website PR 1461. Cache-busted
production checks returned HTTP 200 from the canonical domain and found the
expected disclosure text on all three pages.

Google Auth Platform still reports branding and data access as unverified.
Before submission, an owner/editor of Cloud project `991152473434` must confirm
Search Console ownership for `oilpriceapi.com`, record the required continuous
OAuth demonstration, enter version 11 in App Configuration (already editable -
it does not lock during review), submit branding and data-access
verification, and preserve the
resulting receipt. Track those actions only in issue 20 rather than opening
parallel submission issues.
Do not infer any private Cloud-console field beyond the receipts above. The
public listing and installed-add-on smoke are the release gates for customer
availability; future runtime revisions still require their own immutable
version and installed formula smoke.

## Graphic assets

Expand Down
128 changes: 39 additions & 89 deletions OAUTH_VERIFICATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,77 +4,34 @@ This packet is for the production Google Cloud project
`oilpriceapi-sheets-addon` (`991152473434`) and the original
`OilPriceAPI for Google Sheets™` add-on.

## Status as of July 31, 2026

Release evidence below is from July 29, 2026. The "Current Google state"
section was re-verified against the live Cloud console on July 31, 2026.

Completed release evidence:

- Add-on PR 19 merged as
`799f49f46059340ed332431f5c7ac87f5c91a695`.
- All 49 runtime, recovery, disclosure, deployment-package, asset, portfolio,
and secret-scan checks passed.
- The exact merged runtime was pushed to the production Apps Script project.
- Immutable Apps Script version 10 was created with description
`OilPriceAPI for Google Sheets 1.2.1 OAuth verification`.
- A fresh clone of version 10 matched the four-file reviewed release package
exactly.
- **Superseded by version 11.** PR #22 (custom-function credential fix) merged
2026-07-29 22:01 UTC, after version 10 was cut, and changed `Code.gs` and
`Sidebar.html`. Immutable version 11 was cut the same minute (18:01 EDT) and
carries runtime `1.2.2`; its `Code.gs` reads `ADDON_VERSION = '1.2.2'`
(verified 2026-07-31). Version 11 is the release candidate.
- Website PR 1461 merged as
`c3acb510680992538315781fb0ce3dcec335bf20`.
- Production deployment
`https://github.com/OilpriceAPI/website-clean/actions/runs/30434284989`
completed successfully, including production and money-page smoke checks
and a Cloudflare purge.
- Cache-busted checks returned HTTP 200 without a cross-domain redirect for
the homepage, privacy policy, and terms. The responses contained the
expected scope, Limited Use, and current-formula disclosures.
- DigitalOcean deployment `65aaf4e7-df6a-44aa-a89b-de796963e442` is ACTIVE.
Its first 500 runtime log lines contained no matched errors, warnings,
retries, timeouts, or 5xx responses.

Current Google state:

- The Marketplace **Store Listing** draft is in review. That tab reports
"The draft is in review and can't be edited" and exposes a "Cancel review"
control.
- The Marketplace **App Configuration** tab is _editable_ during that review.
Verified 2026-07-31 by DOM inspection of the Cloud console: every input
reports `disabled: false`, `readOnly: false`, with no `aria-disabled`. The
Version field is a free-text `<input type="text">`, not a dropdown, and
currently holds `9`. "Save Draft" is greyed only for want of unsaved
changes.
**Correction:** earlier revisions of this document asserted the App
Configuration was locked during review. That is wrong, and it nearly drove
an unnecessary cancel-and-recut. The accurate rule is: **Store Listing locks
during review; App Configuration does not.**
- Apps Script **version 11** (runtime `1.2.2`) is the current release
candidate and is not yet selected in App Configuration, which still points
at version 9.
- OAuth publishing status is **In production**.
- OAuth branding is **not verified**.
- OAuth data access is **not verified**.
- OAuth verification has **not been submitted**.
- No public OAuth demonstration URL or Google submission receipt exists yet.

Remaining owner-session work:

1. Confirm that a Cloud project owner/editor is a verified Search Console owner
for `oilpriceapi.com`.
2. Record and publish the continuous end-to-end OAuth demonstration below.
3. Update Marketplace App Configuration to Apps Script version **11**. This
does not have to wait for Google - App Configuration is editable while the
Store Listing is in review.
4. Submit OAuth branding and data-access verification with the exact scopes,
justifications, and public video URL.
5. Capture the confirmation text, date, case/reference ID if present, and
redacted screenshots in issue 20:
`https://github.com/OilpriceAPI/google-sheets-addin/issues/20`.
## Status as of August 11, 2026

Customer-visible Google evidence:

- The listing is publicly available at
`https://workspace.google.com/marketplace/app/oilpriceapi_for_google_sheets/991152473434`.
- The public Marketplace configuration points to immutable Apps Script version
**11**, runtime `1.2.2`.
- OAuth verification was submitted on July 30, 2026 for Cloud project
`991152473434`. The reviewer-accessible continuous demonstration is
`https://youtu.be/FakNSmBddhE`.
- A Marketplace draft install previously proved custom-function registration,
spreadsheet-scoped key save, connection/schema validation,
`OILPRICE_PRICE("WTI_USD")`, `OILPRICE_CODES()`, and sidebar batch fetch.
- Public availability was independently rechecked unauthenticated on August
10, 2026; the canonical URL returned the OilPriceAPI listing while a bogus
application ID returned Google error 400.

Historical release evidence remains relevant: PR #22 supplied the
custom-function credential-context fix, immutable version 11 was cut after it,
and the three functional scopes below were used for submission. Earlier draft
versions 9 and 10 are superseded.

Private Cloud-console fields are not inferred from public availability. The
customer release gate is the public listing plus an installed-add-on formula
smoke. Runtime `1.3.0` must therefore remain a release candidate until it is
merged, pushed, cut as a new immutable Apps Script version, installed through
Marketplace, and smoke-tested before App Configuration is updated.

## Branding values

Expand Down Expand Up @@ -142,21 +99,14 @@ and a non-customer test spreadsheet and OilPriceAPI key.
The recording must not expose an API key, Google account identifier, customer
data, browser password manager, clipboard contents, or unrelated tabs.

## Submission order

1. Deploy the public homepage, privacy policy, and terms above.
2. Confirm all three URLs return `200` without authentication or redirects to
another domain.
3. Confirm Search Console ownership for `oilpriceapi.com`.
4. Push and smoke the exact reviewed Apps Script source.
5. Create a new immutable Apps Script version and enter that version in the
Marketplace SDK.
6. Record and upload the demo video with link visibility enabled for the
Google review team.
7. In Google Auth Platform, verify branding first, then submit Data Access
verification with the scope justifications and demo link.
8. Keep the Workspace Marketplace listing in review only after the OAuth
verification request is accepted for review.

Do not claim that the add-on is publicly installable until Google approves and
publishes the Marketplace listing.
## Future release order

1. Validate and merge the exact reviewed source.
2. Push it to the production Apps Script project and create a new immutable
version without changing the public Marketplace configuration.
3. Install and smoke that candidate with a non-customer account.
4. Select the candidate in Marketplace App Configuration only after key,
formula, batching, quota-recovery, and key-deletion checks pass.
5. Repeat the smoke through the public listing and review Apps Script logs.

Do not claim that a new runtime is public before its selected-version smoke.
26 changes: 15 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,10 @@
Deployment-ready Editor add-on for source-aware OilPriceAPI formulas in Google
Sheets™.

> Google Workspace Marketplace publication is pending. The public listing was
> submitted on July 26, 2026, rejected on July 27 pending trademark attribution
> and OAuth verification remediation, and resubmitted on July 29 after the
> listing, homepage, scopes, and Apps Script version were reconciled. Google
> Cloud currently reports that the draft is in review. Do not claim Marketplace
> availability until Google approves and publishes the listing.
The add-on is [publicly available in Google Workspace Marketplace](https://workspace.google.com/marketplace/app/oilpriceapi_for_google_sheets/991152473434).
The public listing currently points to immutable Apps Script version 11
(`1.2.2`). Runtime `1.3.0` is a release candidate until its installed-add-on
smoke and Marketplace version update are recorded.

Dataset access, history, freshness, and limits depend on the API key, source,
and account entitlement. Review the
Expand Down Expand Up @@ -43,11 +41,12 @@ The original `OILPRICE(code)` formula remains supported for existing sheets.

| Function | Behavior | Cache |
| --- | --- | --- |
| `OILPRICE(code)` | Backward-compatible numeric latest price | 5 minutes |
| `OILPRICE(code)` | Backward-compatible numeric latest price | Tier-aware shared cache |
| `OILPRICE_TABLE(range)` | Up to 25 latest prices in one spilled request | Tier-aware shared cache |
| `OILPRICE_HISTORY(code, days)` | Source timestamp and price rows | 1 hour |
| `OILPRICE_CONVERT(code)` | Reference USD/MMBtu conversion for documented mappings | Latest-price cache |
| `BUNKER_PRICE(port, fuel)` | Numeric Data Connector bunker price | None |
| `BUNKER_PORT_PRICES(port)` | Bunker-price table with units and timestamp | None |
| `BUNKER_PRICE(port, fuel)` | Numeric Data Connector bunker price | 5 minutes |
| `BUNKER_PORT_PRICES(port)` | Bunker-price table with units and timestamp | 5 minutes |
| `FUTURES_PRICE(contract)` | Numeric first-contract price | 5 minutes |
| `FUTURES_CURVE(contract)` | Month, price, and change rows | 5 minutes |
| `RIG_COUNT(type)` | Oil, gas, total, or source-dated table | 1 hour |
Expand All @@ -67,7 +66,11 @@ The original `OILPRICE(code)` formula remains supported for existing sheets.
the Excel preview.
- Credential-shaped query keys are rejected before any network request.
- Missing, invalid, locked, rate-limited, timed-out, malformed, and empty
responses fail with worksheet-readable recovery text.
responses fail with worksheet-readable recovery text. Terminal failures are
negatively cached and a connection check bypasses the cache so a paid upgrade
recovers immediately.
- Latest values use a document cache and a lock-protected miss path. Free,
paid, and enterprise cache lifetimes follow the API's canonical tier header.
- Latest-request diagnostics contain endpoint path, status, duration,
timestamp, and optional request ID—never the API key or query string.
- The manifest requests only current-sheet, external-request, and container-UI
Expand Down Expand Up @@ -119,7 +122,7 @@ npm run clasp:login
read -r "OPA_SCRIPT_ID?Apps Script ID: "
npm run clasp:configure -- "$OPA_SCRIPT_ID"
npm run deploy:push
npm run deploy:version -- "OilPriceAPI for Google Sheets 1.2.2 formula credential context fix"
npm run deploy:version -- "OilPriceAPI for Google Sheets 1.3.0 customer-path recovery"
```

Editor add-on publication uses the Apps Script **script ID and version
Expand All @@ -132,6 +135,7 @@ generated assets are in [MARKETPLACE_LISTING.md](MARKETPLACE_LISTING.md).
## Canonical links

- [Product facts](https://api.oilpriceapi.com/product-facts.json)
- [Workspace Marketplace listing](https://workspace.google.com/marketplace/app/oilpriceapi_for_google_sheets/991152473434)
- [API documentation](https://docs.oilpriceapi.com)
- [Pricing and dataset access](https://www.oilpriceapi.com/pricing)
- [Data usage](https://www.oilpriceapi.com/legal/data-usage)
Expand Down
Loading