@courthive/provider-config

中文文档
1.1.0发布于 2026/11/13MITTypeScriptCommonJS零依赖构建来源已验证近 30 天下载 1961

Canonical types, KEYS, validators, computeEffectiveConfig, and MUTATION_PERMISSIONS for CourtHive provider configuration.

原始使用文档
文档目录19 节
  1. Install
  2. Two-tier provider config model
  3. Exports
  4. Types
  5. Constants
  6. Functions
  7. Types
  8. ProviderBranding
  9. ProviderPermissions
  10. ProviderParticipantPrivacy and participantPrivacyPolicy
  11. ScoringLaunchConfig and ScoringLaunchApp
  12. RankingPointsPolicy
  13. Effective-config computation
  14. Worked example — permission caps ∩ settings
  15. Worked example — branding merge (settings-over-caps)
  16. Validators
  17. Mutation gating
  18. Build / test
  19. License

@courthive/provider-config

Canonical types, KEYS, validators, computeEffectiveConfig, and MUTATION_PERMISSIONS for CourtHive provider configuration.

Pure TypeScript, no runtime dependencies. Part of the CourtHive ecosystem.

Consumed by:

  • competition-factory-server — server-side validation, executionQueue gating
  • competition-factory-server/admin-client — caps + settings editors
  • courthive-ams console — provider caps/settings management UI
  • TMX — runtime singleton, mutation gating, branding + privacy application

Install

pnpm add @courthive/provider-config

Inside the CourtHive monorepo this package is pnpm-only — local sibling links resolved via pnpm.overrides won't survive an npm install.

Two-tier provider config model

Provider configuration is split into two owner tiers plus a computed effective shape:

  • ProviderConfigCaps — provisioner-owned. The ceiling a provider cannot exceed: white-label branding defaults, permission ceilings, allowed universes (draw types, categories, tier systems), and integrations (SSO, scoring launch).
  • ProviderConfigSettings — provider-admin-owned. Day-to-day tuning within the cap ceiling: may disable booleans that caps allow, may narrow allowedX arrays, and owns operational policies, defaults, branding overrides, and participant privacy entirely.
  • ProviderConfigData — the effective shape TMX consumes, produced by computeEffectiveConfig(caps, settings). TMX has no awareness of the caps/settings split — it only ever sees the merged result.

The permission-cap override model is a cap ∩ settings intersection: a boolean is enabled in the effective config only when both tiers allow it, and an allowedX universe is intersected across both tiers. See "Effective-config computation" below.

Exports

Everything is exported from the package root (./dist/index.js, types at ./dist/index.d.ts).

Types

ExportPurpose
ProviderConfigCapsProvisioner-owned ceiling (branding, permissions, policies, integrations)
ProviderConfigSettingsProvider-admin-owned settings (permissions, policies, defaults, branding, participantPrivacy, participantPrivacyPolicy)
ProviderConfigDataComputed effective shape delivered to TMX
ProviderBrandingWhite-label branding fields
ProviderPermissionsFull permission surface (booleans + allowed arrays)
ProviderCapsPermissionsPick of ProviderPermissions limited to cappable keys
ProviderCapsPoliciesCaps-tier allowed universes (formats, categories, tier systems)
ProviderPolicyDefaultsSettings-tier operational policies + allowed lists
ProviderDefaultsNew-entity defaults (event type, draw type, language, PDF font, ...)
ProviderIntegrationsSSO provider + scoring-launch config
ProviderParticipantPrivacyGranular privacy toggles (currently cityState)
ProviderBranding, AllowedCategory, AllowedTierSystemSub-types shared across tiers
RankingPointsPolicy, RankingPointsPolicyKindRanking-points policy classifier
PrintPoliciesByTypeOpaque per-print-type pdf-factory composition policies
ScoringLaunchConfig, ScoringLaunchAppScoring-app launch target
ScoringLaunchContextPlaceholder values for URL substitution
BooleanPermissionKey, ArrayPermissionKey, CappablePermissionKeyPermission-key unions
ValidationIssue, ValidationIssueCodeValidator result shape

Constants

ExportValue / purpose
BOOLEAN_PERMISSION_KEYSOrdered list of all boolean permission keys
ARRAY_PERMISSION_KEYSallowedDrawTypes, allowedCreationMethods, allowedScoringApproaches
ARRAY_POLICY_KEYSallowedMatchUpFormats, allowedCategories, allowedTierSystems
PERMISSIONS_DEFAULT_FALSESet of permissions that default to false (canModifyCompletedScores, canAccessProviderAdmin)
RANKING_POINTS_POLICY_KINDS['BASIC', 'CUSTOM', 'NATIONAL']
SCORING_LAUNCH_APPS['EPIXODIC', 'EMBEDDED', 'EXTERNAL']
SCORING_LAUNCH_PLACEHOLDERS['tournamentId', 'matchUpId', 'eventId', 'drawId']
DEFAULT_SCORING_LAUNCH{ app: 'EPIXODIC' }
MUTATION_PERMISSIONSMap of factory mutation method → keyof ProviderPermissions

Functions

ExportSignature
computeEffectiveConfig(caps?: ProviderConfigCaps, settings?: ProviderConfigSettings) => ProviderConfigData
mergePermissions(caps?: Partial<ProviderPermissions>, settings?: Partial<ProviderPermissions>) => ProviderPermissions
mergePolicies(caps?: Partial<ProviderPolicyDefaults>, settings?: Partial<ProviderPolicyDefaults>) => ProviderPolicyDefaults
resolveRankingPointsPolicy(settings?: Partial<ProviderPolicyDefaults>) => RankingPointsPolicy
validateCaps(caps: unknown) => ValidationIssue[]
validateSettings(settings: unknown, caps?: ProviderConfigCaps) => ValidationIssue[]
isMutationAllowed(method: string, permissions?: ProviderPermissions) => boolean
resolveScoringLaunchUrl(urlTemplate: string, ctx: ScoringLaunchContext) => string
scoringLaunchPlaceholders(urlTemplate: string) => string[]

Note: computeEffectiveConfig calls into mergeBranding internally, but mergeBranding is not exported from the package root — its field-by-field / token-merge behaviour is documented below as part of computeEffectiveConfig.

import {
  // Types
  type ProviderConfigCaps,
  type ProviderConfigSettings,
  type ProviderConfigData,
  type ProviderPermissions,
  type ProviderBranding,
  type ScoringLaunchConfig,
  type ValidationIssue,
  // KEYS + constants
  BOOLEAN_PERMISSION_KEYS,
  ARRAY_PERMISSION_KEYS,
  PERMISSIONS_DEFAULT_FALSE,
  SCORING_LAUNCH_APPS,
  DEFAULT_SCORING_LAUNCH,
  // Functions
  computeEffectiveConfig,
  mergePermissions,
  mergePolicies,
  resolveRankingPointsPolicy,
  resolveScoringLaunchUrl,
  validateCaps,
  validateSettings,
  // Mutation gate
  MUTATION_PERMISSIONS,
  isMutationAllowed,
} from '@courthive/provider-config';

Types

ProviderBranding

White-label branding, applied by TMX at boot and on provider switch. All fields optional.

FieldTypePurpose
navbarLogoUrlstringURL or data-URI for the navbar logo (replaces "TMX" text)
navbarLogoAltstringAlt text for the navbar logo
navbarLogoHeightnumberMax navbar-logo height in px (default 32)
splashLogoUrlstringURL/data-URI for the splash/login logo (replaces the CourtHive hex)
appNamestringApp name in page title + nav bar (default "TMX")
accentColorstringAccent color override (CSS color value)
themeTokensRecord<string, string>Per-token CSS custom-property overrides applied to document.documentElement. Keys must start with --tmx- or --chc-
stylesheetUrlstringURL to a provider-hosted stylesheet appended to <head> (escape hatch beyond themeTokens)

ProviderPermissions

Full permission surface. Boolean fields plus three allowedX string arrays. Most booleans default to true (permissive); the exceptions listed in PERMISSIONS_DEFAULT_FALSE default to false.

Boolean keys (grouped by area):

  • Participants — canCreateCompetitors, canCreateOfficials, canDeleteParticipants, canImportParticipants, canEditParticipantDetails
  • Events — canCreateEvents, canDeleteEvents, canModifyEventFormat
  • Draws — canCreateDraws, canDeleteDraws, canUseDraftPositioning, canUseManualPositioning
  • Scheduling — canModifySchedule, canUseBulkScheduling
  • Venues — canCreateVenues, canDeleteVenues, canModifyCourtAvailability
  • Scoring — canEnterScores, canModifyCompletedScores (default false)
  • Publishing — canPublish, canUnpublish
  • Settings — canModifyTournamentDetails, canModifyPolicies, canAccessProviderAdmin (default false)
  • Communication — canUseChat (tournament chat; defaults to true, a provider may set it false to disable chat across its tournaments)

Array keys: allowedDrawTypes, allowedCreationMethods, allowedScoringApproaches. An empty array means "unrestricted".

ProviderParticipantPrivacy and participantPrivacyPolicy

Two provider-admin-owned (settings tier only — the provisioner has no say) surfaces for participant privacy:

  • participantPrivacy (ProviderParticipantPrivacy) — granular boolean toggles that relax individual attributes the default privacy policy strips from public payloads. Currently one field, cityState, which lets person.addresses[0].city / .state through (street and postal code stay stripped). Default per field is false (privacy-first).
  • participantPrivacyPolicy (Record<string, any>) — the richer successor: a complete factory POLICY_TYPE_PARTICIPANT attribute-filter (inner shape). Kept opaque here (validated structurally as a plain object) so the factory owns the attribute schema. Attached to the provider's tournamentRecords so the factory strips/allows attributes during participant queries.

ScoringLaunchConfig and ScoringLaunchApp

Provider-declared scoring-app launch target for courthive-public's per-matchUp "Score this match" action. Lives on caps.integrations.scoringLaunch (caps-owned — provisioner controls integrations).

type ScoringLaunchApp = 'EPIXODIC' | 'EMBEDDED' | 'EXTERNAL';

interface ScoringLaunchConfig {
  app: ScoringLaunchApp;
  urlTemplate?: string; // required when app === 'EXTERNAL'
}

Launch modes:

  • EPIXODIC — CourtHive Epixodic deep-link. The default when nothing is declared (DEFAULT_SCORING_LAUNCH = { app: 'EPIXODIC' }).
  • EMBEDDED — courthive-public's own in-page /track scoring shell.
  • EXTERNAL — a provider's own app via urlTemplate, with ${tournamentId}, ${matchUpId}, ${eventId}, ${drawId} placeholders substituted at launch time by resolveScoringLaunchUrl.
import { resolveScoringLaunchUrl } from '@courthive/provider-config';

const url = resolveScoringLaunchUrl('https://score.example.com/m/${matchUpId}?t=${tournamentId}', {
  matchUpId: 'mu-1',
  tournamentId: 't-9',
});
// → 'https://score.example.com/m/mu-1?t=t-9'
// Values are URI-component-encoded; unknown/absent placeholders → ''.

RankingPointsPolicy

Classifies who owns the ranking-points policy the provider uses: kind is one of 'BASIC' | 'CUSTOM' | 'NATIONAL' (required when the field is declared), plus optional name and version. Undeclared providers resolve to { kind: 'BASIC' } via resolveRankingPointsPolicy for back-compat.

Effective-config computation

computeEffectiveConfig(caps, settings) merges the two tiers into the ProviderConfigData TMX consumes. Both arguments default to {}.

Merge rules by field:

FieldRule
brandingsettings overrides caps field-by-field; themeTokens merge key-by-key
permissions (booleans)(caps[X] ?? defaultForX) && (settings[X] ?? defaultForX) — both tiers must allow
permissions (arrays)intersect(caps[X], settings[X]) — empty on either side = unrestricted
policies.allowedMatchUpFormats / allowedCategoriesintersected across caps + settings
policies.scheduling/scoring/seeding/rankingPointsPolicysettings owns
defaultssettings owns
integrationscaps owns
participantPrivacysettings owns; normalized to { cityState: settings.participantPrivacy?.cityState === true }
participantPrivacyPolicysettings owns; passed through verbatim

Array intersection semantics (allowedX and allowed policy lists): if either side is undefined or empty, the other side wins (empty = "no restriction"); if both are non-empty, the result is their intersection. Categories intersect by ageCategoryCode.

Worked example — permission caps ∩ settings

import { computeEffectiveConfig } from '@courthive/provider-config';

const caps = {
  permissions: {
    canDeleteEvents: false, // provisioner forbids delete-events
    canEnterScores: true,
    allowedDrawTypes: ['SINGLE_ELIMINATION', 'ROUND_ROBIN', 'COMPASS'],
  },
};

const settings = {
  permissions: {
    canEnterScores: false, // provider chooses to disable
    canDeleteEvents: true, // provider tries to enable (blocked by cap)
    allowedDrawTypes: ['ROUND_ROBIN', 'FEED_IN'], // narrows within cap
  },
};

const effective = computeEffectiveConfig(caps, settings);

effective.permissions.canDeleteEvents; // false — cap forbids, AND wins
effective.permissions.canEnterScores; // false — settings disabled, AND wins
effective.permissions.allowedDrawTypes; // ['ROUND_ROBIN'] — intersection
effective.permissions.canCreateEvents; // true — unset both sides, permissive default
effective.permissions.canModifyCompletedScores; // false — PERMISSIONS_DEFAULT_FALSE

Worked example — branding merge (settings-over-caps)

branding has no lock tier: caps.branding is a provisioner-seeded default/fallback, and settings.branding (provider-admin-owned) wins field-by-field where it defines a value. themeTokens maps merge key-by-key so a provider can add tokens without dropping provisioner-seeded ones — and on a key collision, the settings token wins.

const caps = {
  branding: {
    appName: 'Provisioner Default',
    navbarLogoUrl: 'https://cdn.example.com/provisioner.png',
    themeTokens: { '--tmx-accent-blue': '#003366', '--tmx-bg-primary': '#ffffff' },
  },
};

const settings = {
  branding: {
    appName: 'Acme Tennis', // overrides caps value
    themeTokens: { '--tmx-accent-blue': '#1a5276' }, // overrides one token
  },
};

const { branding } = computeEffectiveConfig(caps, settings);

branding.appName; // 'Acme Tennis'                        (settings wins)
branding.navbarLogoUrl; // 'https://cdn.example.com/provisioner.png' (caps preserved)
branding.themeTokens; // { '--tmx-accent-blue': '#1a5276',   (settings token wins)
//   '--tmx-bg-primary': '#ffffff' }    (caps token preserved)

When neither tier defines any branding, the effective branding is undefined, preserving the "no branding" contract.

Validators

Both validators are pure functions — they throw nothing and return an array of ValidationIssue. The caller decides whether issues are a hard reject (HTTP 400) or informational warnings.

interface ValidationIssue {
  path: string; // dotted path, e.g. "permissions.allowedDrawTypes"
  code: ValidationIssueCode; // 'unknownField' | 'wrongType' | 'exceedsCap'
  message: string;
  disallowedValues?: string[]; // set for exceedsCap
}
  • validateCaps(caps) — structural check on a caps write. Rejects unknown top-level keys (only branding, permissions, policies, integrations allowed), wrong types, unknown branding/permission/ policy/integration keys, and out-of-prefix themeTokens.
  • validateSettings(settings, caps) — structural check plus caps-respect. In addition to the structural checks it flags exceedsCap when a settings write would exceed the provisioner ceiling: enabling a boolean the cap set to false, or including allowedX / allowed-policy values outside the cap's universe.
import { validateSettings } from '@courthive/provider-config';

const issues = validateSettings(
  { permissions: { canDeleteEvents: true } },
  { permissions: { canDeleteEvents: false } }, // caps forbid it
);
// issues → [{ path: 'permissions.canDeleteEvents', code: 'exceedsCap',
//             message: 'canDeleteEvents cannot be enabled — provisioner cap forbids it' }]

The settings validator also structurally validates the interior policy shapes (schedulingPolicy, scoringPolicy, seedingPolicy, rankingPointsPolicy) against the field universes accepted by the factory engine, and validates integrations.scoringLaunch (valid app, known placeholders, urlTemplate required for EXTERNAL).

Mutation gating

MUTATION_PERMISSIONS maps factory mutation method names to the permission key that gates them. isMutationAllowed(method, permissions) returns whether a mutation is permitted:

  • Methods not in the map are allowed by default.
  • Boolean permissions gate directly (undefined → true, permissive).
  • Array permissions are not enforced here — they have richer semantics checked at a different layer (e.g. when the draw type itself is selected).
import { isMutationAllowed } from '@courthive/provider-config';

isMutationAllowed('deleteEvents', { canDeleteEvents: false }); // false
isMutationAllowed('addEvent', {}); // true (permissive)
isMutationAllowed('someUngatedMethod', {}); // true (not in map)

Used by TMX mutationRequest() as a UI defense layer and by the server executionQueue as defense in depth against replayed WebSocket payloads.

Build / test

pnpm build         # rm -rf dist && tsc → dist/
pnpm test          # vitest --run
pnpm check-types   # tsc --noEmit
pnpm lint          # ESLint — non-mutating, fails on any warning
pnpm lint:fix      # ESLint with auto-fix (rewrites source)
pnpm format        # prettier --write "src/**/*.ts"

License

MIT

版本与发布记录

@courthive/provider-config 共发布 26 个版本,首次发布于 2026/05/08;过去 12 个月发布了 26 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.1.0latest2026/11/133 天前
1.0.02026/11/124 天前
0.19.12026/11/0412 天前
0.19.02026/10/2423 天前
0.18.32026/10/1927 天前
0.18.22026/09/082 个月前

关于 @courthive/provider-config 的常见问题

@courthive/provider-config 是什么?

Canonical types, KEYS, validators, computeEffectiveConfig, and MUTATION_PERMISSIONS for CourtHive provider configuration.

如何安装 @courthive/provider-config?

在项目目录运行 npm install @courthive/provider-config,或使用 pnpm add / yarn add / bun add。

@courthive/provider-config 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@courthive/provider-config 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@courthive/provider-config 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@courthive/provider-config 可以商用吗?

@courthive/provider-config 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@courthive/provider-config 的下载量有多少?

根据 npm 官方下载统计,@courthive/provider-config 在 2026/10/11 – 2026/11/09 这 30 天内被下载 1,961 次,日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@courthive/provider-config 还在维护吗?

最新版本 1.1.0 发布于 2026/11/13(3 天前);至今共发布 26 个版本,其中过去 12 个月发布了 26 个;首次发布于 2026/05/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。