Scripts & Tooling

Operational scripts for TeeTime located in tools/scripts/teetime/. These scripts handle data seeding, diagnostics, geocoding, MCA integration audits, and E2E testing.

Quick reference

Category	Scripts	Purpose
Auth/Env	`run-with-infisical.sh`, `get-db-urls.sh`	Inject secrets, get DB connection strings
Import/Seed	`import-clubs.mjs`, `seed-associations.mjs`, `backfill-user-identities.mjs`	Seed clubs, courses, players, associations
Geo	`geocode-all.mjs`, `backfill-geo-from-mca.mjs`	Geocode clubs/courses, backfill coordinates
MCA	`audit-mca-collisions.mjs`, `fix-mca-collisions.mjs`	Audit and fix MCA ID collisions
E2E	`test-multi-club-stream-e2e.mjs`, `test-tee-times-e2e.mjs`	SSE streaming, tee-time API smoke tests
Diagnostics	`assess-golfrsa-coverage.mjs`, `assess-teetime-users.mjs`	Coverage reports and user audits

Running scripts

Most scripts are Node ESM and can be run with:

pnpm exec node tools/scripts/teetime/<script>.mjs [flags]

Scripts requiring database access or secrets use the Infisical wrapper:

INFISICAL_ENV=prod tools/scripts/teetime/auth/run-with-infisical.sh \
  node tools/scripts/teetime/<script>.mjs

Geo/MCA scripts that need database tunnels use:

tools/scripts/teetime/geo/run-geo-with-tunnel.sh geocode-all.mjs --dry-run

Auth & Environment Helpers

`auth/run-with-infisical.sh`

Injects Infisical secrets into the environment before running a command.

INFISICAL_ENV=dev tools/scripts/teetime/auth/run-with-infisical.sh \
  node tools/scripts/teetime/import-seed/import-clubs.mjs

`auth/get-db-urls.sh`

Prints database URLs for tunnels or client connections. Useful when setting up local development against remote databases.

`auth/validate-golfrsa-credentials.mjs`

Sanity-check GolfRSA API credentials to verify they're valid before running imports.

Import & Seeding Scripts

`import-seed/backfill-user-identities.mjs`

Links IDP users (Auth0/etc) to TeeTime players by creating UserIdentity mappings.

TEETIME_DATABASE_URL=postgres://... \
node tools/scripts/teetime/import-seed/backfill-user-identities.mjs \
  --file identities.csv \
  --provider auth0 \
  [--create] \
  [--dry-run]

Input formats:

CSV with headers: subject,email,givenName,familyName,preferredName
NDJSON (one JSON per line)

Behavior:

Check if (provider, subject) already exists → skip
Find player by email → link identity
If --create flag set → create player and link
Otherwise → report as unresolved

`import-seed/seed-associations.mjs`

Seeds core golf associations (GolfRSA, DotGolf, England Golf, Golf Ireland) required for benefits validation.

node tools/scripts/teetime/import-seed/seed-associations.mjs --dry-run  # Preview
node tools/scripts/teetime/import-seed/seed-associations.mjs --apply    # Create records
node tools/scripts/teetime/import-seed/seed-associations.mjs --query-mca --apply  # Query MCA for IDs

`import-seed/import-clubs.mjs` / `import-courses.mjs`

Import club and course data from CSV or external sources.

`import-seed/import-mca-players.mjs`

Import player data from MCA databases.

`import-seed/import-idp-users.mjs`

Bulk import users from IDP exports.

`import-seed/create-test-player.mjs`

Create a test player for development/QA.

`import-seed/seed-golfrsa-test-players.mjs`

Seed test players with GolfRSA memberships for testing reciprocity.

`import-seed/seed-golfrsa-secrets.sh` / `deploy-golfrsa-migration.sh`

GolfRSA-specific secret seeding and migration deployment.

Geo & Distance Scripts

`geo/geocode-all.mjs`

Comprehensive geocoding for clubs and courses using Nominatim (OpenStreetMap).

node tools/scripts/teetime/geo/geocode-all.mjs --dry-run  # Preview changes
node tools/scripts/teetime/geo/geocode-all.mjs            # Apply geocoding
node tools/scripts/teetime/geo/geocode-all.mjs --force    # Re-geocode even if coords exist

Features:

Geocodes clubs using address (more accurate than name)
Falls back to parent club for courses
Validates coordinates are within South African region bounds
Includes manual overrides for known clubs with verified coordinates

`geo/backfill-geo-from-mca.mjs`

Backfill coordinates from MCA databases where TeeTime records are missing geo data.

tools/scripts/teetime/geo/run-geo-with-tunnel.sh backfill-geo-from-mca.mjs --apply

`geo/list-geo-coverage.mjs`

Report on clubs/courses with and without coordinates.

`geo/test-distance-accuracy.mjs` / `test-global-distance-accuracy.mjs`

Validate distance calculations between known points.

`geo/run-geo-with-tunnel.sh`

Wrapper that establishes database tunnels before running geo scripts.

MCA Integration Scripts

`mca/audit-mca-collisions.mjs`

Audit MCA v1 ID collisions between ZA and UK databases.

tools/scripts/teetime/geo/run-geo-with-tunnel.sh audit-mca-collisions.mjs

Reports:

Clubs/courses where mcaV1Id exists in both ZA and UK
Name similarity mismatches (TeeTime vs MCA)
Recommendations for fixing collisions

`mca/fix-mca-collisions.mjs`

Apply fixes for MCA ID collisions identified by the audit.

`mca/audit-mca-visibility-flags.mjs`

Audit visibility flags (searchable, deleted, underMaintenance) across MCA data.

`mca/check-club-associations.mjs`

Check club-to-association mappings.

`mca/check-mca-uk-clubs.mjs`

Validate UK club data in MCA.

`mca/map-golfrsa-clubs.mjs`

Map GolfRSA club codes to TeeTime clubs.

`mca/test-mca-tables.mjs`

Test MCA database table access.

`mca/test-mca-proxy-smoke.mjs`

Smoke test for MCA proxy endpoints. Validates McaCallAudit records when database is available.

`mca/test-golfrsa-enrichment.mjs`

Test GolfRSA data enrichment flow.

`mca/sync-specials-from-mca.mjs`

Sync tee-time specials from MCA.

E2E Test Scripts

`e2e/test-multi-club-stream-e2e.mjs`

SSE smoke test for /api/clubs/tee-sheet/stream.

CLUBS=ALPHA,BETA DATE=2025-12-05 \
  node tools/scripts/teetime/e2e/test-multi-club-stream-e2e.mjs

Environment variables:

Variable	Description
`API_BASE`	Base URL (default: `https://teetime-api.dev.digiwedge.com/api`)
`DATE`	ISO date (default: today)
`CLUBS`	Comma-separated club codes (required)
`MEMBER_CLUBS`	Optional comma list for member ordering
`FAVORITE_CLUBS`	Optional comma list for favorite ordering
`USER_LAT` / `USER_LON`	Optional coordinates for distance ordering
`SPECIALS_ONLY`	Filter to specials only
`AUTH_TOKEN`	Optional bearer token
`MAX_EVENTS`	Max events to print (default: 20)
`TIMEOUT_MS`	Abort timeout (default: 20000)

`e2e/test-tee-times-e2e.mjs`

Test course/club visitor + member tee-times and pricing endpoints.

`e2e/test-buddy-invite-e2e.mjs`

Test buddy invite flow end-to-end. See e2e/README-BUDDY-INVITE-TESTING.md for setup.

`e2e/test-club-admin-e2e.mjs`

Admin club CRUD and logo upload smoke test. Read-only by default; set APPLY_* env vars to mutate.

`e2e/test-club-courses-e2e.mjs`

Admin create/update for /api/clubs/{clubId}/courses.

`e2e/test-mca-v1-tsheet-e2e.mjs` / `test-mca-v1-tee-time-availability-e2e.mjs`

MCA v1 tee-sheet and availability endpoint tests.

`e2e/test-streaming-performance.mjs`

Performance benchmarking for streaming endpoints.

`e2e/benchmark-mca-bridge-performance.mjs`

Benchmark MCA bridge performance.

Ordering & Favorites Scripts

`ordering/test-ordering-integration.mjs`

Integration tests for club ordering logic (favorites, distance, member clubs).

`ordering/test-favorites-e2e.mjs`

E2E test for favorites functionality.

`ordering/test-club-ordering.mjs`

Test club ordering algorithms.

Diagnostics Scripts

`diagnostics/assess-teetime-users.mjs`

Audit TeeTime users: identity mappings, orphaned players, duplicate emails.

`diagnostics/assess-golfrsa-coverage.mjs`

Report on GolfRSA coverage: which clubs have GolfRSA IDs, missing mappings.

`diagnostics/assess-mca-player-data.mjs`

Audit MCA player data quality.

`diagnostics/check-golfrsa-data.mjs`

Validate GolfRSA data integrity.

`diagnostics/list-clubs-geo.mjs`

List clubs with their geo coordinates (or lack thereof).

Other Scripts

`policy-audit.mjs`

Audit club/provider assignment policies via admin validate endpoint or direct Prisma queries.

`validate-gcl-call-counts.mjs`

Validate GCL (Golf Club Lookup) call counts for monitoring.

`seed-dynamic-pricing-config.sh`

Seed dynamic pricing configuration.

`import-mca-pricing-to-scl.ts` / `export-mca-v1-pricing.ts` / `map-billing-items-to-scl.ts`

TypeScript scripts for MCA pricing import/export.

Common patterns

Dry-run first

Most scripts support --dry-run to preview changes:

node tools/scripts/teetime/import-seed/seed-associations.mjs --dry-run
# Review output, then:
node tools/scripts/teetime/import-seed/seed-associations.mjs --apply

Environment variables

Database URLs are typically required:

export TEETIME_DATABASE_URL=postgresql://user:pass@host:5432/teetime
export TEE_SHEET_DATABASE_URL=postgresql://user:pass@host:5432/tee_sheet

Or use Infisical:

INFISICAL_ENV=prod tools/scripts/teetime/auth/run-with-infisical.sh <command>

Output format

Most scripts output JSON for easy parsing:

{
  "provider": "auth0",
  "create": true,
  "linked": 42,
  "exists": 10,
  "unresolved": 3
}

Quick reference
Running scripts
Auth & Environment Helpers
Import & Seeding Scripts
Geo & Distance Scripts
MCA Integration Scripts
E2E Test Scripts
Ordering & Favorites Scripts
Diagnostics Scripts
Other Scripts
Common patterns

Quick reference​

Running scripts​

Auth & Environment Helpers​

auth/run-with-infisical.sh​

auth/get-db-urls.sh​

auth/validate-golfrsa-credentials.mjs​

Import & Seeding Scripts​

import-seed/backfill-user-identities.mjs​

import-seed/seed-associations.mjs​

import-seed/import-clubs.mjs / import-courses.mjs​

import-seed/import-mca-players.mjs​

import-seed/import-idp-users.mjs​

import-seed/create-test-player.mjs​

import-seed/seed-golfrsa-test-players.mjs​

import-seed/seed-golfrsa-secrets.sh / deploy-golfrsa-migration.sh​

Geo & Distance Scripts​

geo/geocode-all.mjs​

geo/backfill-geo-from-mca.mjs​

geo/list-geo-coverage.mjs​

geo/test-distance-accuracy.mjs / test-global-distance-accuracy.mjs​

geo/run-geo-with-tunnel.sh​

MCA Integration Scripts​

mca/audit-mca-collisions.mjs​

mca/fix-mca-collisions.mjs​

mca/audit-mca-visibility-flags.mjs​

mca/check-club-associations.mjs​

mca/check-mca-uk-clubs.mjs​

mca/map-golfrsa-clubs.mjs​

mca/test-mca-tables.mjs​

mca/test-mca-proxy-smoke.mjs​

mca/test-golfrsa-enrichment.mjs​

mca/sync-specials-from-mca.mjs​

E2E Test Scripts​

e2e/test-multi-club-stream-e2e.mjs​

e2e/test-tee-times-e2e.mjs​

e2e/test-buddy-invite-e2e.mjs​

e2e/test-club-admin-e2e.mjs​

e2e/test-club-courses-e2e.mjs​

e2e/test-mca-v1-tsheet-e2e.mjs / test-mca-v1-tee-time-availability-e2e.mjs​

e2e/test-streaming-performance.mjs​

e2e/benchmark-mca-bridge-performance.mjs​

Ordering & Favorites Scripts​

ordering/test-ordering-integration.mjs​

ordering/test-favorites-e2e.mjs​

ordering/test-club-ordering.mjs​

Diagnostics Scripts​

diagnostics/assess-teetime-users.mjs​

diagnostics/assess-golfrsa-coverage.mjs​

diagnostics/assess-mca-player-data.mjs​

diagnostics/check-golfrsa-data.mjs​

diagnostics/list-clubs-geo.mjs​

Other Scripts​

policy-audit.mjs​

validate-gcl-call-counts.mjs​

seed-dynamic-pricing-config.sh​

import-mca-pricing-to-scl.ts / export-mca-v1-pricing.ts / map-billing-items-to-scl.ts​

Common patterns​

Dry-run first​

Environment variables​

Output format​