Set up npm trusted publishing as @ultracart/bigquery-sdk

.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

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

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}

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'
 > ```
 

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

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"
   },

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' });

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];
 };