The descriptor three audiences read: a router mounts it, a menu renders it, a share link resolves it.
Generated from libs/oshun/workbench-kit/src/routes.ts by
node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger:
S1.8. Do not edit by hand.
Summary#
src/routes.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/routes |
contract |
S1.8 |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| BREADCRUMB_MODES | enumeration | — |
| BreadcrumbMode | type | — |
| DeepLinkDescriptor | interface | — |
| Discoverability | type | — |
| DISCOVERABILITY | enumeration | — |
| effectivePaths | function | Every host a route answers on: the canonical one plus its aliases. |
| findRedirectCycles | function | — |
| FLAG_TARGETING | enumeration | — |
| FLAG_UNAVAILABLE_BEHAVIOUR | enumeration | — |
| FlagRequirement | interface | — |
| FlagTargeting | type | — |
| FlagUnavailableBehaviour | type | — |
| hostNavigation | function | — |
| HostNavigation | interface | — |
| HTTP_METHODS | enumeration | — |
| HttpMethod | type | — |
| NAV_PLACEMENTS | enumeration | — |
| NAV_TARGETS | enumeration | — |
| navigationAccountsForEveryRoute | function | Every route in the set is either in the tree or in the exclusion list. |
| NavigationExclusion | interface | — |
| NavigationNode | interface | — |
| NavigationPlacement | interface | — |
| NavPlacement | type | — |
| NavTarget | type | — |
| ParsedPath | interface | — |
| parseRouteDescriptor | function | — |
| parseRoutePath | function | — |
| ROUTE_SCOPES | enumeration | — |
| RouteDescriptor | interface | — |
| routeInventory | function | — |
| RouteInventoryRow | interface | — |
| RouteScope | type | — |
| RouteSurface | type | An API route or a UI route, never a thing that is both. |
| RouteValidationOptions | interface | — |
| RouteViolation | interface | — |
| SCOPE_BINDINGS | enumeration | — |
| ScopeBinding | type | — |
| SHARE_SAFETY | enumeration | — |
| ShareSafety | type | — |
| UI_KINDS | enumeration | — |
| UiKind | type | — |
| validateRoutes | function | — |
Shapes#
BREADCRUMB_MODES#
Values: inherit, replace, hidden
BreadcrumbMode#
(typeof BREADCRUMB_MODES)[number];
DeepLinkDescriptor#
| Field | Type | Required | Notes |
|---|---|---|---|
entityParameter |
string |
required | The path parameter naming the entity a link points at. |
subviews |
readonly string[] |
required | — |
filterKeys |
readonly string[] |
required | — |
inspectorKeys |
readonly string[] |
required | — |
anchorKinds |
readonly AnchorKind[] — AnchorKind |
required | Which S1.4 anchor kinds a link into this route may carry. |
expirySeconds |
number | null |
required | Null only when the link is never shared, so there is nothing to expire. |
shareSafety |
ShareSafety | required | — |
Discoverability#
(typeof DISCOVERABILITY)[number];
DISCOVERABILITY#
Values: listed, search-only, hidden
effectivePaths#
Every host a route answers on: the canonical one plus its aliases.
effectivePaths(route: RouteDescriptor): readonly string[]
findRedirectCycles#
findRedirectCycles(byId: ReadonlyMap<string, RouteDescriptor>): readonly string[][]
FLAG_TARGETING#
Values: global, tenant, workspace, user, percentage
FLAG_UNAVAILABLE_BEHAVIOUR#
Values: hide, disable, fail-closed, fail-open
FlagRequirement#
| Field | Type | Required | Notes |
|---|---|---|---|
flagId |
string |
required | — |
defaultEnabled |
boolean |
required | — |
targeting |
FlagTargeting | required | — |
dependsOn |
string | null |
required | — |
expiresAt |
Instant | null — Instant |
required | Exactly one of expiresAt and permanentReason is set. |
permanentReason |
string | null |
required | — |
whenUnavailable |
FlagUnavailableBehaviour | required | What a consumer does when the flag service cannot answer. |
FlagTargeting#
(typeof FLAG_TARGETING)[number];
FlagUnavailableBehaviour#
(typeof FLAG_UNAVAILABLE_BEHAVIOUR)[number];
hostNavigation#
hostNavigation(routes: readonly RouteDescriptor[], host: Host, audience: Audience): HostNavigation
HostNavigation#
| Field | Type | Required | Notes |
|---|---|---|---|
host |
Host | required | — |
audience |
Audience | required | — |
tree |
readonly NavigationNode[] — NavigationNode |
required | — |
excluded |
readonly NavigationExclusion[] — NavigationExclusion |
required | Every route this projection left out, and why. |
HTTP_METHODS#
Values: GET, POST, PUT, PATCH, DELETE
HttpMethod#
(typeof HTTP_METHODS)[number];
NAV_PLACEMENTS#
Values: primary, secondary, utility, contextual
NAV_TARGETS#
Values: in-app, new-tab, embedded
navigationAccountsForEveryRoute#
Every route in the set is either in the tree or in the exclusion list.
navigationAccountsForEveryRoute(routes: readonly RouteDescriptor[], navigation: HostNavigation): { readonly unaccounted: readonly string[]; readonly doubleCounted: readonly string[] }
NavigationExclusion#
| Field | Type | Required | Notes |
|---|---|---|---|
routeId |
string |
required | — |
reason |
| 'no-navigation-placement' | 'different-host' | 'audience-not-permitted' | 'not-discoverable' | 'retired' |
required | — |
NavigationNode#
| Field | Type | Required | Notes |
|---|---|---|---|
routeId |
string |
required | — |
labelKey |
string |
required | — |
iconKey |
string | null |
required | — |
order |
number |
required | — |
placement |
NavPlacement | required | — |
target |
NavTarget | required | — |
children |
readonly NavigationNode[] — NavigationNode |
required | — |
NavigationPlacement#
| Field | Type | Required | Notes |
|---|---|---|---|
placement |
NavPlacement | required | — |
labelKey |
string |
required | i18n KEYS, never literal text. |
iconKey |
string | null |
required | — |
order |
number |
required | — |
parentRouteId |
string | null |
required | — |
breadcrumb |
BreadcrumbMode | required | — |
discoverability |
Discoverability | required | — |
target |
NavTarget | required | — |
NavPlacement#
(typeof NAV_PLACEMENTS)[number];
NavTarget#
(typeof NAV_TARGETS)[number];
ParsedPath#
| Field | Type | Required | Notes |
|---|---|---|---|
path |
string |
required | — |
parameters |
readonly string[] |
required | — |
parseRouteDescriptor#
parseRouteDescriptor(input: unknown): ParseResult<RouteDescriptor>
parseRoutePath#
parseRoutePath(input: unknown): ParseResult<ParsedPath>
ROUTE_SCOPES#
Values: platform, tenant, workspace
RouteDescriptor#
| Field | Type | Required | Notes |
|---|---|---|---|
routeId |
string |
required | — |
surface |
RouteSurface | required | — |
path |
string |
required | — |
parameters |
readonly string[] |
required | — |
owningCapability |
CapabilityId | required | — |
contractVersion |
SemanticVersion | required | — |
lifecycle |
Lifecycle | required | — |
redirectTo |
string | null |
required | Where a retired or deprecated route sends a caller. |
host |
Host | required | — |
hostAliases |
readonly Host[] — Host |
required | — |
audiences |
readonly Audience[] — Audience |
required | — |
roles |
readonly string[] |
required | — |
scope |
RouteScope | required | — |
scopeBinding |
ScopeBinding | null — ScopeBinding |
required | — |
dataClassification |
DataClassification | required | — |
navigation |
NavigationPlacement | null — NavigationPlacement |
required | — |
deepLink |
DeepLinkDescriptor | null — DeepLinkDescriptor |
required | — |
flags |
readonly FlagRequirement[] — FlagRequirement |
required | — |
routeInventory#
routeInventory(routes: readonly RouteDescriptor[]): readonly RouteInventoryRow[]
RouteInventoryRow#
| Field | Type | Required | Notes |
|---|---|---|---|
routeId |
string |
required | — |
effectivePaths |
readonly string[] |
required | — |
surface |
'api' | 'ui' |
required | — |
kind |
string |
required | — |
owningCapability |
string |
required | — |
contractVersion |
string |
required | — |
lifecycle |
Lifecycle | required | — |
host |
Host | required | — |
audiences |
readonly Audience[] — Audience |
required | — |
scope |
RouteScope | required | — |
dataClassification |
DataClassification | required | — |
flags |
readonly string[] |
required | — |
shareSafety |
ShareSafety | null — ShareSafety |
required | — |
RouteScope#
(typeof ROUTE_SCOPES)[number];
RouteSurface#
An API route or a UI route, never a thing that is both.
| { readonly surface: 'api'; readonly method: HttpMethod }
| { readonly surface: 'ui'; readonly uiKind: UiKind }
RouteValidationOptions#
| Field | Type | Required | Notes |
|---|---|---|---|
knownCapabilities |
readonly string[] |
optional | Capability ids the registry knows. Empty means the check does not run. |
capabilityAudiences |
Readonly<Record<string, readonly Audience[]>> — Audience |
optional | Audiences each capability serves, so a route cannot widen one. |
RouteViolation#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
| 'duplicate-route-id' | 'duplicate-effective-path' | 'unknown-capability' | 'unknown-parent' | 'unnavigable-parent' | 'redirect-cycle' | 'redirect-to-missing' | 'redirect-to-retired' | 'audience-exceeds-capability' |
required | — |
subject |
string |
required | — |
detail |
string |
required | — |
SCOPE_BINDINGS#
Values: path-parameter, session
ScopeBinding#
(typeof SCOPE_BINDINGS)[number];
SHARE_SAFETY#
Values: public, tenant-only, never-share
ShareSafety#
(typeof SHARE_SAFETY)[number];
UI_KINDS#
Values: page, panel, dialog, overlay, wizard-step
UiKind#
(typeof UI_KINDS)[number];
validateRoutes#
validateRoutes(routes: readonly RouteDescriptor[], options: RouteValidationOptions = {}): readonly RouteViolation[]
Valid examples#
No committed fixture corpus covers this page's accepted cases; they are unit-level and live in the module's own spec.
Invalid examples#
descriptor/alias-repeats-canonical-host#
the alias list is what a route is ALSO reachable from, and including the canonical host makes a duplicate-path check see two
Must produce: invariant-violated
{
"audiences": ["creator"],
"contractVersion": "1.0.0",
"dataClassification": "internal",
"deepLink": null,
"flags": [],
"host": "studio-web",
"hostAliases": ["studio-web"],
"lifecycle": "general-availability",
"navigation": null,
"owningCapability": "capability:workbench-shell",
"path": "/studio",
"redirectTo": null,
"roles": [],
"routeId": "studio.unnamed",
"scope": "platform",
"scopeBinding": null,
"surface": "ui",
"uiKind": "page"
}
descriptor/api-route-with-navigation#
a menu entry that resolves to a JSON endpoint is a link nobody can follow
Must produce: invariant-violated
{
"audiences": ["creator"],
"contractVersion": "1.0.0",
"dataClassification": "internal",
"deepLink": null,
"flags": [],
"host": "studio-web",
"hostAliases": [],
"lifecycle": "general-availability",
"method": "GET",
"navigation": {
"breadcrumb": "inherit",
"discoverability": "listed",
"iconKey": null,
"labelKey": "nav.studio.workbench",
"order": 10,
"parentRouteId": null,
"placement": "primary",
"target": "in-app"
},
"owningCapability": "capability:workbench-shell",
"path": "/studio",
"redirectTo": null,
"roles": [],
"routeId": "studio.unnamed",
"scope": "platform",
"scopeBinding": null,
"surface": "api"
}
descriptor/deep-link-entity-not-in-path#
a link built from it would resolve to the route's default entity, not the one shared
Must produce: invariant-violated
{
"audiences": ["creator"],
"contractVersion": "1.0.0",
"dataClassification": "internal",
"deepLink": {
"anchorKinds": [],
"entityParameter": "itemId",
"expirySeconds": 3600,
"filterKeys": [],
"inspectorKeys": [],
"shareSafety": "tenant-only",
"subviews": []
},
"flags": [],
"host": "studio-web",
"hostAliases": [],
"lifecycle": "general-availability",
"navigation": null,
"owningCapability": "capability:workbench-shell",
"path": "/studio/items",
"redirectTo": null,
"roles": [],
"routeId": "studio.unnamed",
"scope": "platform",
"scopeBinding": null,
"surface": "ui",
"uiKind": "page"
}
3 of 24 refused case(s) shown. The full corpus is committed at
evidence/v1-workbenches/workbench-kit-route-fixtures.json and is what the gate
runs.
Authorization and scope#
| Symbol | Type | Notes |
| ------------------------------ | ------------- | ----- | --- |
| ROUTE_SCOPES | enumeration | — |
| RouteDescriptor.scope | RouteScope | — |
| RouteDescriptor.scopeBinding | ScopeBinding | null | — |
| RouteInventoryRow.scope | RouteScope | — |
| RouteScope | type | — |
| SCOPE_BINDINGS | enumeration | — |
| ScopeBinding | type | — |
Idempotency and concurrency#
Not applicable: nothing on this page is retried or applied twice: these are declarations, not operations.
Pagination#
Not applicable: nothing on this page returns a collection a caller reads in pages.
State and failure#
| Symbol | Type | Notes |
|---|---|---|
FLAG_UNAVAILABLE_BEHAVIOUR |
enumeration |
— |
FlagRequirement.whenUnavailable |
FlagUnavailableBehaviour |
What a consumer does when the flag service cannot answer. |
FlagUnavailableBehaviour |
type |
— |
Compatibility#
| Symbol | Type | Notes |
|---|---|---|
RouteDescriptor.contractVersion |
SemanticVersion |
— |
RouteInventoryRow.contractVersion |
string |
— |
Deprecation#
| Symbol | Type | Notes |
|---|---|---|
RouteDescriptor.lifecycle |
Lifecycle |
— |
RouteInventoryRow.lifecycle |
Lifecycle |
— |
Evidence#
evidence/v1-workbenches/workbench-kit-export-map.jsonevidence/v1-workbenches/workbench-kit-route-fixtures.jsonlibs/oshun/workbench-kit/src/routes.ts