From 4b3cc42f55f2d2a80205f0c526e4b901cab5cd29 Mon Sep 17 00:00:00 2001 From: ucjonathan Date: Tue, 30 Jun 2026 11:07:44 -0400 Subject: [PATCH] Set up npm trusted publishing as @ultracart/bigquery-sdk Prepare the package for OIDC trusted publishing to npm and for the repo going public. - package.json: rename to @ultracart/bigquery-sdk; add repository, homepage, bugs, engines.node; add a `files` allowlist (ships src/ + README/LICENSE/CHANGELOG only); add publishConfig (access public, provenance). - Add .github/workflows/publish.yml: OIDC trusted publishing on v* tags via a protected `npm` environment, SHA-pinned actions, tag/version match check, npm test gate, npm publish --provenance --access public. Mirrors the existing @ultracart/bq-skill setup. - Update install/require snippets to the scoped name across README, docs/EXTRACTION.md, examples/README.md, and src/client.js. - README: fix the broken PLAN.md link; mark status as early release. - CHANGELOG: cut [0.1.0]. - test/schema-drift.test.js: split fake paths on both separators so the offline tests pass on Windows too (CI on Linux was already green). Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/publish.yml | 63 +++++++++++++++++++++++++++++++++++ CHANGELOG.md | 5 ++- README.md | 9 ++--- docs/EXTRACTION.md | 2 +- examples/README.md | 2 +- package-lock.json | 4 +-- package.json | 21 +++++++++++- src/client.js | 2 +- test/schema-drift.test.js | 3 +- 9 files changed, 99 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..555860e --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,63 @@ +# Publishes to npm when you push a version tag (e.g., v0.1.0) +# +# Security notes: +# - Uses OIDC Trusted Publishing (no long-lived NPM_TOKEN needed) +# - Only runs on tags matching v*, not on PRs or branch pushes +# - Uses a protected GitHub Environment ("npm") as an approval gate +# - Pins all actions to exact commit SHAs (not mutable tags) +# - npm provenance links every published package back to this exact build + +name: Publish to npm + +on: + push: + tags: + - 'v*' # Only triggers on version tags: v0.1.0, v1.0.0, etc. + +# Restrict permissions to the minimum needed +permissions: + contents: read + id-token: write # Required for npm provenance (proves this package came from this repo) + +jobs: + publish: + runs-on: ubuntu-latest + environment: npm # Protected environment — requires approval before publishing + + steps: + # Check out the tagged commit + - name: Checkout + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + ref: ${{ github.ref }} + + # Set up Node.js with the npm registry. + # Node 24 ships an npm new enough for OIDC trusted publishing (>= 11.5.1). + - name: Setup Node.js + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + with: + node-version: '24' + registry-url: 'https://registry.npmjs.org' + + # Install dependencies (ci is stricter than install — uses lockfile exactly) + - name: Install dependencies + run: npm ci + + # Run the offline unit tests as a release gate + - name: Test + run: npm test + + # Verify the tag version matches package.json version + - name: Verify version match + run: | + TAG_VERSION="${GITHUB_REF#refs/tags/v}" + PKG_VERSION=$(node -p "require('./package.json').version") + if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then + echo "ERROR: Tag version ($TAG_VERSION) does not match package.json version ($PKG_VERSION)" + exit 1 + fi + echo "Version verified: $PKG_VERSION" + + # Publish to npm with provenance (OIDC Trusted Publishing — no token needed) + - name: Publish to npm + run: npm publish --provenance --access public diff --git a/CHANGELOG.md b/CHANGELOG.md index 375c64f..c78f7d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ All notable changes to this project are documented here. The format is based on ## [Unreleased] +## [0.1.0] - 2026-06-30 + ### Added - Initial release: `UltraCartBigQuery` client that streams UltraCart data-warehouse rows and hydrates them into native `ultra_cart_rest_api_v2` SDK model instances. @@ -23,4 +25,5 @@ All notable changes to this project are documented here. The format is based on - Per-entity examples for full backfill and change-data-capture (orders, customers, auto orders, items), plus the extraction guide in `docs/EXTRACTION.md`. -[Unreleased]: https://github.com/UltraCart/rest_api_v2_sdk_javascript_bigquery +[Unreleased]: https://github.com/UltraCart/rest_api_v2_sdk_javascript_bigquery/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/UltraCart/rest_api_v2_sdk_javascript_bigquery/releases/tag/v0.1.0 diff --git a/README.md b/README.md index f111b3b..656dc87 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ SDK model instances** (`Order`, `Customer`, `AutoOrder`, …) — the same objec use against the REST API. Ideal for bulk extracts (order history, customer data, loyalty portals) where hammering the REST API would be slow and wasteful. -> Status: **early spike.** Core auth + transformer + SDK hydration working and unit-tested. -> See [PLAN.md](./PLAN.md) for design, scope, and roadmap. +> Status: **early release (0.1.0).** Core auth + transformer + SDK hydration working and +> unit-tested. See the [CHANGELOG](./CHANGELOG.md) for release notes and +> [CONTRIBUTING](./CONTRIBUTING.md) to get involved. ## Why @@ -23,7 +24,7 @@ between BigQuery and the SDK, which this library handles automatically: ## Install ```bash -npm install rest_api_v2_sdk_javascript_bigquery ultra_cart_rest_api_v2 @google-cloud/bigquery +npm install @ultracart/bigquery-sdk ultra_cart_rest_api_v2 @google-cloud/bigquery ``` ## Authentication @@ -47,7 +48,7 @@ read access to your warehouse project at the assigned taxonomy (PII) level. handles a small incremental sync and a full-history backfill with constant memory. ```js -const { UltraCartBigQuery } = require('rest_api_v2_sdk_javascript_bigquery'); +const { UltraCartBigQuery } = require('@ultracart/bigquery-sdk'); const UltraCartApi = require('ultra_cart_rest_api_v2'); // Project is derived as ultracart-dw-{merchantId} diff --git a/docs/EXTRACTION.md b/docs/EXTRACTION.md index a72c495..a757684 100644 --- a/docs/EXTRACTION.md +++ b/docs/EXTRACTION.md @@ -168,7 +168,7 @@ WHERE merchant_id = @mid AND creation_dts >= @since > comparison ("Invalid datetime string"). Strip it with the exported helper before using a > value as a filter param: > ```js -> const { toBigQueryDatetime } = require('rest_api_v2_sdk_javascript_bigquery'); +> const { toBigQueryDatetime } = require('@ultracart/bigquery-sdk'); > const params = { since: toBigQueryDatetime(watermark) }; // '2026-06-25T21:41:40Z' -> '...40' > ``` diff --git a/examples/README.md b/examples/README.md index 772f465..79bc457 100644 --- a/examples/README.md +++ b/examples/README.md @@ -23,7 +23,7 @@ There are two patterns per entity: ``` 2. Install peer deps alongside this package: ```bash - npm install rest_api_v2_sdk_javascript_bigquery ultra_cart_rest_api_v2 @google-cloud/bigquery + npm install @ultracart/bigquery-sdk ultra_cart_rest_api_v2 @google-cloud/bigquery ``` ## Running diff --git a/package-lock.json b/package-lock.json index 2196347..79fb229 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { - "name": "rest_api_v2_sdk_javascript_bigquery", + "name": "@ultracart/bigquery-sdk", "version": "0.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "rest_api_v2_sdk_javascript_bigquery", + "name": "@ultracart/bigquery-sdk", "version": "0.1.0", "license": "Apache-2.0", "dependencies": { diff --git a/package.json b/package.json index fc53601..2db69c7 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "rest_api_v2_sdk_javascript_bigquery", + "name": "@ultracart/bigquery-sdk", "version": "0.1.0", "description": "UltraCart REST API V2 JavaScript SDK — BigQuery extension. Query the UltraCart data warehouse and receive native SDK model instances.", "main": "src/index.js", @@ -17,6 +17,25 @@ ], "author": "UltraCart", "license": "Apache-2.0", + "repository": { + "type": "git", + "url": "git+https://github.com/UltraCart/rest_api_v2_sdk_javascript_bigquery.git" + }, + "homepage": "https://github.com/UltraCart/rest_api_v2_sdk_javascript_bigquery#readme", + "bugs": { + "url": "https://github.com/UltraCart/rest_api_v2_sdk_javascript_bigquery/issues" + }, + "engines": { + "node": ">=18" + }, + "files": [ + "src", + "CHANGELOG.md" + ], + "publishConfig": { + "access": "public", + "provenance": true + }, "dependencies": { "@google-cloud/bigquery": "^8.3.1" }, diff --git a/src/client.js b/src/client.js index ad39fc8..2e594cd 100644 --- a/src/client.js +++ b/src/client.js @@ -24,7 +24,7 @@ const USD_PER_TIB = 6.25; * thousands of orders) and an incremental sync share the same constant-memory path. * * @example - * const { UltraCartBigQuery } = require('rest_api_v2_sdk_javascript_bigquery'); + * const { UltraCartBigQuery } = require('@ultracart/bigquery-sdk'); * const UltraCartApi = require('ultra_cart_rest_api_v2'); * * const ucbq = new UltraCartBigQuery({ merchantId: 'DEMO' }); diff --git a/test/schema-drift.test.js b/test/schema-drift.test.js index 591e336..66d7ce4 100644 --- a/test/schema-drift.test.js +++ b/test/schema-drift.test.js @@ -38,7 +38,8 @@ const FAKE_FILES = { 'OrderBilling.js': BILLING_SRC, }; const fakeRead = (file) => { - const base = file.split('/').pop(); + // Split on both separators: buildSdkTree uses path.join, which emits "\" on Windows. + const base = file.split(/[\\/]/).pop(); if (!(base in FAKE_FILES)) throw new Error('no such file'); return FAKE_FILES[base]; };