congress-trading-shared

Shared TypeScript contracts for the Congress.Trade and Socratic Trade cross-app integration.

Usage telemetry v2

createUsageTelemetryClient.send sends only strict v2 events. Configure a stable producerId and give every logical event an explicit stable eventId; fresh calls have no legacy five-field identity fallback. Only sendLegacyOutbox accepts already-persisted v1 rows: it requires their existing idempotencyKey, rejects a sourceApp that differs from the configured producer, and promotes the key to v2 eventId. The monitor derives persistence identity solely from producerId + eventId.

Use opaque producerKeyRef, providerConnectionRef, and billingAccountRef values for attribution; never send API-key secrets. Successful responses report explicit received/persisted/duplicate/ pruned/rejected counts. UsageTelemetryApiError exposes typed retryability and server backoff.

This package owns the types, Zod schemas, API path constants, and small utilities that both apps can use for:

• App B -> App A securities imports: refs, prices, spx, insider, shortVolume, fundamentals, analyst.
• App A -> App B return-path cache imports: partial refs, prices, and SPX closes.
• Congress.Trade read contracts such as transactions, market refs, bundle responses, analytics rows, and export manifests.

Commands

npm install
npm run typecheck
npm run build
npm run lint:package
npm test
npm audit
npm run pack:dry

Publish Policy

This repo is public and the supported consumption path is a tokenless git dependency — no npm registry, no NODE_AUTH_TOKEN, no .npmrc auth lines.

Consumers pin a package.json dependency directly to an immutable release tag. Use the release being adopted by the coordinated consumer PRs:

"@jaywedgeworth22/congress-trading-shared": "github:jaywedgeworth22/congress-trading-shared#vX.Y.Z"

Do not point production consumers at main, a branch, or an untagged package version. Semver ranges are supported by npm but are not the fleet's current pin policy because they can move a lockfile without coordinated consumer review.

npm installs the repo tarball at that ref and runs this package's prepare script (npm run build), so dist/ is generated on install — it does not need to be committed and is not published anywhere. Lifecycle scripts therefore must be enabled; --ignore-scripts is unsupported for this source-only Git package. Verify a new pin in an isolated scratch project without registry tokens or changes to a consumer lockfile:

scratch="$(mktemp -d)"
mkdir -p "$scratch/home" "$scratch/cache"
env -u NODE_AUTH_TOKEN -u NPM_TOKEN -u GH_PACKAGES_TOKEN -u GITHUB_TOKEN \
  HOME="$scratch/home" npm_config_cache="$scratch/cache" npm install --prefix "$scratch" \
  "git+https://github.com/jaywedgeworth22/congress-trading-shared.git#<ref>"
node -e "require('$scratch/node_modules/@jaywedgeworth22/congress-trading-shared')"

Tag a new release after any change that consumers should pick up:

git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z

(Legacy note: this package briefly published to the private GitHub Packages registry, https://npm.pkg.github.com. That required NODE_AUTH_TOKEN/PAT auth in every consumer and CI job and is retired now that the repo is public — do not reintroduce a publishConfig.registry / scoped-registry .npmrc setup unless the user explicitly asks for a private registry again.)

package.json is marked private as a machine-enforced guard against an accidental registry publish. This does not prevent Git dependency installs or npm pack verification.

dist/ is generated by npm run build and omitted from git.

Contract Notes

• SecurityRef is the full read-side shape.
• SecurityRefInput is the partial import/upsert shape accepted by the peer import endpoints.
• Date-bearing market/import rows validate as real YYYY-MM-DD calendar dates via IsoDateSchema.
• APP_B_ORIGIN / APP_B_ORIGIN_TAG are the no-echo-loop origin tag for Socratic Trade-originated payloads.
• Exported schemas use Zod 4. A consumer may keep Zod 3 at its root because this package owns a direct nested Zod 4 dependency, but schemas from the two majors must not be composed, cast as assignable, or passed to APIs expecting the other major.